small cleanups to module.h and loader.c to start playing with
[asterisk/asterisk.git] / include / asterisk / module.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Asterisk module definitions.
21  *
22  * This file contains the definitons for functions Asterisk modules should
23  * provide and some other module related functions.
24  */
25
26 #ifndef _ASTERISK_MODULE_H
27 #define _ASTERISK_MODULE_H
28
29 #include "asterisk/linkedlists.h"       /* XXX needed here */
30
31 #include "asterisk/utils.h"
32
33 #if defined(__cplusplus) || defined(c_plusplus)
34 extern "C" {
35 #endif
36
37 #ifdef STATIC_MODULE    /* symbols are static */
38 #define _HAVE_STATIC_MODULE
39 #undef STATIC_MODULE
40 #define STATIC_MODULE   static /* symbols are static */
41 #else   /* !STATIC_MODULE, symbols are global */
42 #define STATIC_MODULE   /* empty - symbols are global */
43
44 /*! \note Every module should provide these functions */
45 /*! 
46  * \brief Initialize the module.
47  * 
48  * This function is called at module load time.  Put all code in here
49  * that needs to set up your module's hardware, software, registrations,
50  * etc.
51  *
52  * \return This function should return 0 on success and non-zero on failure.
53  * If the module is not loaded successfully, Asterisk will call its
54  * unload_module() function.
55  */
56 int load_module(void);
57
58 /*! 
59  * \brief Cleanup all module structures, sockets, etc.
60  *
61  * This is called at exit.  Any registrations and memory allocations need to be
62  * unregistered and free'd here.  Nothing else will do these for you (until
63  * exit).
64  *
65  * \return Zero on success, or non-zero on error.
66  */
67 int unload_module(void);
68
69 /*! 
70  * \brief Provides a usecount.
71  *
72  * This function will be called by various parts of asterisk.  Basically, all
73  * it has to do is to return a usecount when called.  You will need to maintain
74  * your usecount within the module somewhere.  The usecount should be how many
75  * channels provided by this module are in use.
76  *
77  * \return The module's usecount.
78  */
79 int usecount(void);             /* How many channels provided by this module are in use? */
80
81 /*! \brief Provides a description of the module.
82  *
83  * \return a short description of your module
84  */
85 char *description(void);                /* Description of this module */
86
87 /*! 
88  * \brief Returns the ASTERISK_GPL_KEY
89  *
90  * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
91  * the GPL stated in the ASTERISK_GPL_KEY.  Your module will not load if it does
92  * not return the EXACT message:
93  *
94  * \code
95  * char *key(void) {
96  *         return ASTERISK_GPL_KEY;
97  * }
98  * \endcode
99  *
100  * \return ASTERISK_GPL_KEY
101  */
102 char *key(void);                /* Return the below mentioned key, unmodified */
103
104 /*! 
105  * \brief Reload stuff.
106  *
107  * This function is where any reload routines take place.  Re-read config files,
108  * change signalling, whatever is appropriate on a reload.
109  *
110  * \return The return value is not used.
111  */
112 int reload(void);               /* reload configs */
113 #endif  /* !STATIC_MODULE case */
114
115 /*! \brief The text the key() function should return. */
116 #define ASTERISK_GPL_KEY \
117         "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
118 In order for your module to load, it must return this key via a function \
119 called \"key\".  Any code which includes this paragraph must be licensed under \
120 the GNU General Public License version 2 or later (at your option).   Linux \
121 Support Services, Inc. reserves the right to allow other parties to license \
122 this paragraph under other terms as well."
123
124 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
125
126 /*! 
127  * \brief Softly unload a module.
128  *
129  * This flag signals ast_unload_resource() to unload a module only if it is not
130  * in use, according to the module's usecount.
131  */
132 #define AST_FORCE_SOFT 0
133
134 /*! 
135  * \brief Firmly unload a module.
136  *
137  * This flag signals ast_unload_resource() to attempt to unload a module even
138  * if it is in use.  It will attempt to use the module's unload_module
139  * function.
140  */
141 #define AST_FORCE_FIRM 1
142
143 /*! 
144  * \brief Unconditionally unload a module.
145  *
146  * This flag signals ast_unload_resource() to first attempt to unload a module
147  * using the module's unload_module function, then if that fails to unload the
148  * module using dlclose.  The module will be unloaded even if it is still in
149  * use.  Use of this flag is not recommended.
150  */
151 #define AST_FORCE_HARD 2
152
153 /*! 
154  * \brief Load a module.
155  * \param resource_name The filename of the module to load.
156  *
157  * This function is run by the PBX to load the modules.  It performs
158  * all loading and initilization tasks.   Basically, to load a module, just
159  * give it the name of the module and it will do the rest.
160  *
161  * \return Zero on success, -1 on error.
162  */
163 int ast_load_resource(const char *resource_name);
164
165 /*! 
166  * \brief Unloads a module.
167  * \param resource_name The name of the module to unload.
168  * \param force The force flag.  This should be set using one of the AST_FORCE*
169  *        flags.
170  *
171  * This function unloads a module.  It will only unload modules that are not in
172  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
173  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
174  * module regardless of consequences (NOT_RECOMMENDED).
175  *
176  * \return Zero on success, -1 on error.
177  */
178 int ast_unload_resource(const char *resource_name, int force);
179
180 /*! 
181  * \brief Notify when usecount has been changed.
182  *
183  * This function calulates use counts and notifies anyone trying to keep track
184  * of them.  It should be called whenever your module's usecount changes.
185  *
186  * \note The LOCAL_USER macros take care of calling this function for you.
187  */
188 void ast_update_use_count(void);
189
190 /*! 
191  * \brief Ask for a list of modules, descriptions, and use counts.
192  * \param modentry A callback to an updater function.
193  * \param like
194  *
195  * For each of the modules loaded, modentry will be executed with the resource,
196  * description, and usecount values of each particular module.
197  * 
198  * \return the number of modules loaded
199  */
200 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
201                            const char *like);
202
203 /*! 
204  * \brief Add a procedure to be run when modules have been updated.
205  * \param updater The function to run when modules have been updated.
206  *
207  * This function adds the given function to a linked list of functions to be
208  * run when the modules are updated. 
209  *
210  * \return Zero on success and -1 on failure.
211  */
212 int ast_loader_register(int (*updater)(void));
213
214 /*! 
215  * \brief Remove a procedure to be run when modules are updated.
216  * \param updater The updater function to unregister.
217  *
218  * This removes the given function from the updater list.
219  * 
220  * \return Zero on success, -1 on failure.
221  */
222 int ast_loader_unregister(int (*updater)(void));
223
224 /*! 
225  * \brief Reload asterisk modules.
226  * \param name the name of the module to reload
227  *
228  * This function reloads the specified module, or if no modules are specified,
229  * it will reload all loaded modules.
230  *
231  * \note Modules are reloaded using their reload() functions, not unloading
232  * them and loading them again.
233  *
234  * \return Zero if the specified module was not found, 1 if the module was
235  * found but cannot be reloaded, -1 if a reload operation is already in
236  * progress, and 2 if the specfied module was found and reloaded.
237  */
238 int ast_module_reload(const char *name);
239
240 /*! 
241  * \brief Match modules names for the Asterisk cli.
242  * \param line Unused by this function, but this should be the line we are
243  *        matching.
244  * \param word The partial name to match. 
245  * \param pos The position the word we are completing is in.
246  * \param state The possible match to return.
247  * \param rpos The position we should be matching.  This should be the same as
248  *        pos.
249  * \param needsreload This should be 1 if we need to reload this module and 0
250  *        otherwise.  This function will only return modules that are reloadble
251  *        if this is 1.
252  *
253  * \return A possible completion of the partial match, or NULL if no matches
254  * were found.
255  */
256 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
257
258 /*! 
259  * \brief Register a function to be executed before Asterisk exits.
260  * \param func The callback function to use.
261  *
262  * \return Zero on success, -1 on error.
263  */
264 int ast_register_atexit(void (*func)(void));
265
266 /*! 
267  * \brief Unregister a function registered with ast_register_atexit().
268  * \param func The callback function to unregister.
269  */
270 void ast_unregister_atexit(void (*func)(void));
271
272 /*!
273  * \brief Given a function address, find the corresponding module.
274  * This is required as a workaround to the fact that we do not
275  * have a module argument to the load_module() function.
276  * Hopefully the performance implications are small.
277  */
278 struct module *ast_find_module(int (*load_fn)(void));
279
280 /* Local user routines keep track of which channels are using a given module
281    resource.  They can help make removing modules safer, particularly if
282    they're in use at the time they have been requested to be removed */
283
284 struct localuser {
285         struct ast_channel *chan;
286         AST_LIST_ENTRY(localuser) next;
287 };
288
289 /*! \brief structure used for lock and refcount of module users.
290  * \note The mutex protects the usecnt field and whatever needs to be
291  * protected (typically, a list of struct localuser).
292  * As a trick, if usecnt is initialized with -1,
293  * ast_format_register will init the mutex for you.
294  */
295 struct ast_module_lock {
296         ast_mutex_t lock;
297         AST_LIST_HEAD_NOLOCK(localuser_head, localuser) u;
298         int usecnt;     /* number of active clients */
299 };
300
301 struct localuser *ast_localuser_add(struct ast_module_lock *m, struct ast_channel *chan);
302 void ast_localuser_remove(struct ast_module_lock *m, struct localuser *u);
303 void ast_hangup_localusers(struct ast_module_lock *m);
304
305 /*! 
306  * \brief create a localuser mutex and several other variables used for keeping the
307  * use count.
308  *
309  * <b>Sample Usage:</b>
310  * \code
311  * LOCAL_USER_DECL;
312  * \endcode
313  */
314 #define LOCAL_USER_DECL                                 \
315         static struct ast_module_lock me = {            \
316                 .u = AST_LIST_HEAD_NOLOCK_INIT_VALUE,   \
317                 .usecnt = 0,                            \
318                 .lock = AST_MUTEX_INIT_VALUE }
319
320 #define STANDARD_USECOUNT_DECL LOCAL_USER_DECL  /* XXX lock remains unused */
321
322 /*! \brief run 'x' protected by lock, then call ast_update_use_count() */
323 #define __MOD_PROTECT(x) do {                   \
324         ast_mutex_lock(&me.lock);               \
325         x;                                      \
326         ast_mutex_unlock(&me.lock);             \
327         ast_update_use_count();                 \
328         } while (0)
329
330 #define STANDARD_INCREMENT_USECOUNT __MOD_PROTECT(me.usecnt++)
331 #define STANDARD_DECREMENT_USECOUNT __MOD_PROTECT(me.usecnt--)
332
333 /*! 
334  * \brief Add a localuser.
335  * \param u a pointer to a localuser struct
336  *
337  * This macro adds a localuser to the list of users and increments the
338  * usecount.  It expects a variable named \p chan of type \p ast_channel in the
339  * current scope.
340  *
341  * \note This function dynamically allocates memory.  If this operation fails
342  * it will cause your function to return -1 to the caller.
343  */
344 #define LOCAL_USER_ADD(u) do {                  \
345         u = ast_localuser_add(&me, chan);       \
346         if (!u)                                 \
347                 return -1;                      \
348         } while (0)
349
350 /*! 
351  * \brief Remove a localuser.
352  * \param u the user to add, should be of type struct localuser
353  *
354  * This macro removes a localuser from the list of users and decrements the
355  * usecount.
356  */
357 #define LOCAL_USER_REMOVE(u) ast_localuser_remove(&me, u)
358
359 /*! 
360  * \brief Hangup all localusers.
361  *
362  * This macro hangs up on all current localusers and sets the usecount to zero
363  * when finished.
364  */
365 #define STANDARD_HANGUP_LOCALUSERS ast_hangup_localusers(&me)
366
367 /*!
368  * \brief Set the specfied integer to the current usecount.
369  * \param res the integer variable to set.
370  *
371  * This macro sets the specfied integer variable to the local usecount.
372  *
373  * <b>Sample Usage:</b>
374  * \code
375  * int usecount(void)
376  * {
377  *    int res;
378  *    STANDARD_USECOUNT(res);
379  *    return res;
380  * }
381  * \endcode
382  */
383 #define STANDARD_USECOUNT(res) do { res = me.usecnt; } while (0)
384
385 /*! \brief Old usecount macro
386  * \note XXX The following macro is deprecated, and only used by modules
387  * in codecs/ and a few other places which do their own manipulation
388  * of the usecount variable.
389  * Its use is supposed to be gradually phased away as those modules
390  * are updated to use the standard mechanism.
391  */
392 #define OLD_STANDARD_USECOUNT(res) do { res = localusecnt; } while (0)
393
394 /*! \page ModMngmnt The Asterisk Module management interface
395  * \par The following is part of the new module management code.
396  *
397  * All modules must implement the module API (load, unload...)
398  * whose functions are exported through fields of a "struct module_symbol";
399  *
400  * Modules exporting extra symbols (data or functions), should list
401  * them into an array of struct symbol_entry: \r
402  *     struct symbol_entry exported_symbols[]
403  * \r
404  * of symbols, with a NULL name on the last entry
405  *
406  * Functions should be added with MOD_FUNC(name),
407  * data structures with MOD_DATA(_name).
408  * The array in turn is referenced by struct module_symbol.
409  * (Typically, a module will export only a single symbol, which points
410  * to a record containing all the methods. This is the API of the module,
411  * and should be known to the module's clients as well.
412  *
413  * \par Connections to symbols in other modules
414  * Modules that require symbols supplied by other modules should
415  * provide an array
416  *     struct symbol_entry required_symbols[]
417  * of symbols, with a NULL name on the last entry, containing the
418  * name of the desired symbol.
419  * For good measure, we also provide the size in both caller and calle
420  * to figure out if there is a mismatch (not terribly useful because most
421  * objects are a single word, but still... )
422  * The symbol can be added to the array with MOD_WANT(symbol) macro.
423  * required_symbols is also pointed by through struct module_symbol.
424  *
425  * Typically, the whole interface exported by a module should be
426  * in a single structure named after the module, as follows.
427  * Say the module high level name is 'foo', then we should have
428  * - in include/asterisk/foo.h
429  *     struct foo_interface {
430  *              int (*f)(int, char *); -- first function exported 
431  *              const char (*g)(int); -- second function exported 
432  *              char *buf;
433  *              ...             -- other fields
434  *     }
435  * - in the module exporting the interface, e.g. res/res_foo.c
436  *      static int f(int, char *);
437  *      static const char *g(int);
438  *      const char buf[BUFSZ];
439  *     struct foo_interface foo = {
440  *      .f = f,
441  *      .g = g,
442  *      .buf = buf,
443  *     }
444  *
445  * \note NOTE: symbol names are 'global' in this module namespace, so it
446  * will be wiser to name exported symbols with a prefix indicating the module
447  * supplying it, e.g. foo_f, foo_g, foo_buf. Internally to the module,
448  * symbols are still static so they can keep short and meaningful names.
449  * The macros MOD_FIELD and METHOD_BASE() below help setting these entries.
450  *
451  *      MOD_FIELD(f1),          -- field and function name are the same
452  *      METHOD_BASE(foo_, f1),  -- field and function name differ by a prefix
453  *      .f1 = function_name,    -- generic case
454  *     }
455  *
456  * Note that the loader requires that no fields of exported_symbols
457  * are NULL, because that is used as an indication of the end of the array.
458  *
459  * \par Module states
460  * Modules can be in a number of different states, as below:
461  * - \b MS_FAILED    attempt to load failed. This is final.
462  * - \b MS_NEW       just added to the list, symbols unresolved.
463  * - \b MS_RESOLVED  all symbols resolved, but supplier modules not active yet.
464  * - \b MS_CANLOAD   all symbols resolved and suppliers are all active
465  *              (or we are in a cyclic dependency and we are breaking a loop)
466  * - \b MS_ACTIVE    load() returned successfully.
467  *
468  * 
469  * \par Module Types
470  * For backward compatibility, we have 3 types of loadable modules:
471  *
472  * - \b MOD_0 these are the 'old style' modules, which export a number
473  *       of callbacks, and their full interface, as globally visible
474  *       symbols. The module needs to be loaded with RTLD_LAZY and
475  *       RTLD_GLOBAL to make symbols visible to other modules, and
476  *       to avoid load failures due to cross dependencies.
477  *
478  * - \b MOD_1 almost as above, but the generic callbacks are all into a
479  *       a structure, mod_data. Same load requirements as above.
480  *
481  * - \b MOD_2 this is the 'new style' format for modules. The module must
482  *       explictly declare which simbols are exported and which
483  *       symbols from other modules are used, and the code in this
484  *       loader will implement appropriate checks to load the modules
485  *       in the correct order. Also this allows to load modules
486  *       with RTLD_NOW and RTLD_LOCAL so there is no chance of run-time
487  *       bugs due to unresolved symbols or name conflicts.
488  */
489
490 struct symbol_entry {
491         const char *name;
492         void *value;
493         int size;
494         struct module *src;     /* module sourcing it, filled by loader */
495 };
496
497 /*
498  * Constructors for symbol_entry values
499  */
500 #define MOD_FUNC(f)     { .name = #f, .value = f, .size = sizeof(f) }
501 #define MOD_DATA(d)     { .name = #d, .value = &d, .size = sizeof(_name) }
502 #define MOD_WANT(s)     { .name = #s, .value = &s, 0 }   /* required symbols */
503
504 /*
505  * Constructors for fields of foo_interface
506  */
507 #define MOD_FIELD(f)    . ## f = f
508 #define METHOD_BASE(_base, _name)       . ## _name = _base ## _name
509
510 /*
511  * Each 'registerable' entity has a pointer in the
512  * struct ast_registry, which points to an array of objects of
513  * the same type. The ast_*_register() function will be able to
514  * derive the size of these entries.
515  */
516 struct ast_registry {
517         struct ast_cli_entry *clis;
518 };
519
520 struct module_symbols {
521         int (*load_module)(void);
522         int (*unload_module)(void);
523         int (*usecount)(void);   
524         char *(*description)(void);
525         char *(*key)(void);
526         int (*reload)(void);
527
528         enum module_type {
529                 MOD_0,  /* old module style */
530                 MOD_1,  /* old style, but symbols here */
531                 MOD_2,  /* new style, exported symbols */
532         } type;
533         struct ast_registry *reg;
534         struct symbol_entry *exported_symbols;
535         struct symbol_entry *required_symbols;
536 };
537
538 #ifndef _HAVE_STATIC_MODULE
539 #define STD_MOD(t, reload_fn, exp, req)
540 #else
541 #define STD_MOD(t, reload_fn, exp, req)                 \
542 struct module_symbols mod_data = {                      \
543         .load_module = load_module,                     \
544         .unload_module = unload_module,                 \
545         .description = description,                     \
546         .key = key,                                     \
547         .reload = reload_fn,                            \
548         .usecount = usecount,                           \
549         .type = t,                                      \
550         .exported_symbols = exp,                        \
551         .required_symbols = req                         \
552 };
553 #endif /* _HAVE_STATIC_MODULE */
554
555 #if defined(__cplusplus) || defined(c_plusplus)
556 }
557 #endif
558
559 #endif /* _ASTERISK_MODULE_H */