1// This file is part of SmallBASIC
2//
3// SmallBASIC plugin manager
4//
5// This program is distributed under the terms of the GPL v2.0 or later
6// Download the GNU Public License (GPL) from www.gnu.org
7//
8// Copyright(C) 2000 Nicholas Christopoulos
9
10/**
11 * @ingroup mod
12 * @page moddoc Modules
13 *
14 * The modules are common shared-libraries which can call back the SB's code.
15 *
16 * The module-manager loads the modules at the startup and unloads them
17 * before SB's exit. Which module will be loaded is specified by the
18 * user in SB's command-line parameters (option -m). The path of the modules
19 * is predefined to /usr/lib/sbasic/modules and/or /usr/local/lib/sbasic/modules
20 *
21 * <b>Standard interface</b>
22 *
23 * All modules must provides at least the three following functions:
24 * sblib_init(), sblib_close, sblib_type().
25 *
26 * the sblib_init() called on startup, the sblib_close() called on SB's exit,
27 * and the sblib_type() called after sblib_init() to inform the module-manager
28 * about the type of the module (slib_tp).
29 *
30 * <b>Library-modules</b>
31 *
32 * The SB before compiles the .bas program, the module-manager
33 * asks every module about the number of the functions and procedures
34 * which are supported. (sblib_proc_count, sblib_func_count)
35 *
36 * It continues by asking the name of each function and procedure and
37 * updates the compiler. (sblib_proc_getname, sblib_func_getname)
38 *
39 * On the execution time, if the program wants to execute a library's
40 * procedure or function, the module-manager builds the parameter table
41 * and calls the sblib_proc_exec or the sblib_func_exec.
42 *
43 * See modules/example1.c
44 * <b>Notes:</b>
45 *
46 * Procedure & functions names are limited to 32 characters (33 with \0)
47 */
48
49/**
50 * @defgroup mod Module Manager
51 */
52/**
53 * @defgroup modstd Module interface - Standard
54 */
55/**
56 * @defgroup modlib Module interface - Library
57 */
58
59#if !defined(_sb_extlib_h)
60#define _sb_extlib_h
61
62#include "common/sys.h"
63#include "common/var.h"
64#include "common/device.h"
65#include "include/module.h"
66
67#if defined(__cplusplus)
68extern "C" {
69#endif
70
71/**
72 * @ingroup mod
73 *
74 * Initialize module-manager
75 *
76 * default path /usr/lib/sbasic/modules/:/usr/local/lib/sbasic/modules/
77 */
78void slib_init();
79
80/**
81 * @ingroup mod
82 *
83 * close module manager
84 */
85void slib_close(void);
86
87/**
88 * @ingroup mod
89 *
90 * set the alias and returns a library's ID
91 *
92 * @param name is the name of the library (without the file-extention)
93 * @param alias updates the internal name with the given alias
94 * @return the id or -1 for error
95 */
96int slib_get_module_id(const char *name, const char *alias);
97
98/**
99 * @ingroup mod
100 *
101 * imports the modules routine and optionally updates the compiler
102 * with the module (mid) keywords.
103 */
104void slib_import(int lib_id, int comp);
105
106/**
107 * @ingroup mod
108 *
109 * returns the ID of the keyword. used at run-time to assign BCs ID with slib_mgr's one
110 */
111int slib_get_kid(int lib_id, const char *name);
112
113/**
114 * @ingroup mod
115 *
116 * execute a library's procedure
117 *
118 * @param lib is the lib-id
119 * @param index is the index of the procedure
120 * @return non-zero on success
121 */
122int slib_procexec(int lib, int index);
123
124/**
125 * @ingroup mod
126 *
127 * execute a library's function
128 *
129 * @param lib is the lib-id
130 * @param index is the index of the function
131 * @param ret is the variable to store the result
132 * @return non-zero on success
133 */
134int slib_funcexec(int lib, int index, var_t *ret);
135
136/**
137 * @ingroup mod
138 *
139 * returns the function from the first available module
140 *
141 * @param name the function name
142 * @return non-zero on success
143 */
144void *slib_get_func(const char *name);
145
146#if defined(__cplusplus)
147}
148#endif
149#endif
150