d6e1d903998360d2673bd587411f257bd39ef38d
[asterisk/asterisk.git] / include / asterisk / module.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2008, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  * Kevin P. Fleming <kpfleming@digium.com>
8  * Luigi Rizzo <rizzo@icir.org>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20
21 /*! \file
22  * \brief Asterisk module definitions.
23  *
24  * This file contains the definitons for functions Asterisk modules should
25  * provide and some other module related functions.
26  */
27
28 /*! \li \ref module.h uses the configuration file \ref modules.conf
29  * \addtogroup configuration_file
30  */
31
32 /*! \page modules.conf modules.conf
33  * \verbinclude modules.conf.sample
34  */
35
36 #ifndef _ASTERISK_MODULE_H
37 #define _ASTERISK_MODULE_H
38
39 #include "asterisk/utils.h"
40
41 #if defined(__cplusplus) || defined(c_plusplus)
42 extern "C" {
43 #endif
44
45 /*! \brief The text the key() function should return. */
46 #define ASTERISK_GPL_KEY \
47 "This paragraph is copyright (c) 2006 by Digium, Inc. \
48 In order for your module to load, it must return this \
49 key via a function called \"key\".  Any code which \
50 includes this paragraph must be licensed under the GNU \
51 General Public License version 2 or later (at your \
52 option).  In addition to Digium's general reservations \
53 of rights, Digium expressly reserves the right to \
54 allow other parties to license this paragraph under \
55 different terms. Any use of Digium, Inc. trademarks or \
56 logos (including \"Asterisk\" or \"Digium\") without \
57 express written permission of Digium, Inc. is prohibited.\n"
58
59 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
60
61 enum ast_module_unload_mode {
62         AST_FORCE_SOFT = 0, /*!< Softly unload a module, only if not in use */
63         AST_FORCE_FIRM = 1, /*!< Firmly unload a module, even if in use */
64         AST_FORCE_HARD = 2, /*!< as FIRM, plus dlclose() on the module. Not recommended
65                                 as it may cause crashes */
66 };
67
68 enum ast_module_load_result {
69         AST_MODULE_LOAD_SUCCESS = 0,    /*!< Module loaded and configured */
70         AST_MODULE_LOAD_DECLINE = 1,    /*!< Module is not configured */
71         AST_MODULE_LOAD_SKIP = 2,       /*!< Module was skipped for some reason */
72         AST_MODULE_LOAD_PRIORITY = 3,   /*!< Module is not loaded yet, but is added to prioity heap */
73         AST_MODULE_LOAD_FAILURE = -1,   /*!< Module could not be loaded properly */
74 };
75
76 /*!
77  * \since 12
78  * \brief Possible return types for \ref ast_module_reload
79  */
80 enum ast_module_reload_result {
81         AST_MODULE_RELOAD_SUCCESS = 0,      /*!< The module was reloaded succesfully */
82         AST_MODULE_RELOAD_QUEUED,           /*!< The module reload request was queued */
83         AST_MODULE_RELOAD_NOT_FOUND,        /*!< The requested module was not found */
84         AST_MODULE_RELOAD_ERROR,            /*!< An error occurred while reloading the module */
85         AST_MODULE_RELOAD_IN_PROGRESS,      /*!< A module reload request is already in progress */
86         AST_MODULE_RELOAD_UNINITIALIZED,    /*!< The module has not been initialized */
87         AST_MODULE_RELOAD_NOT_IMPLEMENTED,  /*!< This module doesn't support reloading */
88 };
89
90 enum ast_module_support_level {
91         AST_MODULE_SUPPORT_UNKNOWN,
92         AST_MODULE_SUPPORT_CORE,
93         AST_MODULE_SUPPORT_EXTENDED,
94         AST_MODULE_SUPPORT_DEPRECATED,
95 };
96
97 /*! 
98  * \brief Load a module.
99  * \param resource_name The name of the module to load.
100  *
101  * This function is run by the PBX to load the modules.  It performs
102  * all loading and initialization tasks.   Basically, to load a module, just
103  * give it the name of the module and it will do the rest.
104  *
105  * \return See possible enum values for ast_module_load_result.
106  */
107 enum ast_module_load_result ast_load_resource(const char *resource_name);
108
109 /*! 
110  * \brief Unload a module.
111  * \param resource_name The name of the module to unload.
112  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE flags.
113  *
114  * This function unloads a module.  It will only unload modules that are not in
115  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
116  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
117  * module regardless of consequences (NOT RECOMMENDED).
118  *
119  * \retval 0 on success.
120  * \retval -1 on error.
121  */
122 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
123
124 /*!
125  * \brief Reload asterisk modules.
126  * \param name the name of the module to reload
127  *
128  * This function reloads the specified module, or if no modules are specified,
129  * it will reload all loaded modules.
130  *
131  * \note Modules are reloaded using their reload() functions, not unloading
132  * them and loading them again.
133  *
134  * \retval The \ref ast_module_reload_result status of the module load request
135  */
136 enum ast_module_reload_result ast_module_reload(const char *name);
137
138 /*! 
139  * \brief Notify when usecount has been changed.
140  *
141  * This function calulates use counts and notifies anyone trying to keep track
142  * of them.  It should be called whenever your module's usecount changes.
143  *
144  * \note The ast_module_user_* functions take care of calling this function for you.
145  */
146 void ast_update_use_count(void);
147
148 /*!
149  * \brief Ask for a list of modules, descriptions, use counts and status.
150  * \param modentry A callback to an updater function.
151  * \param like
152  *
153  * For each of the modules loaded, modentry will be executed with the resource,
154  * description, and usecount values of each particular module.
155  *
156  * \return the number of modules loaded
157  */
158 int ast_update_module_list(int (*modentry)(const char *module, const char *description,
159                                            int usecnt, const char *status, const char *like,
160                                            enum ast_module_support_level support_level),
161                            const char *like);
162
163 /*!
164  * \brief Check if module with the name given is loaded
165  * \param name Module name, like "chan_sip.so"
166  * \retval 1 if true 
167  * \retval 0 if false
168  */
169 int ast_module_check(const char *name);
170
171 /*! 
172  * \brief Add a procedure to be run when modules have been updated.
173  * \param updater The function to run when modules have been updated.
174  *
175  * This function adds the given function to a linked list of functions to be
176  * run when the modules are updated. 
177  *
178  * \retval 0 on success 
179  * \retval -1 on failure.
180  */
181 int ast_loader_register(int (*updater)(void));
182
183 /*! 
184  * \brief Remove a procedure to be run when modules are updated.
185  * \param updater The updater function to unregister.
186  *
187  * This removes the given function from the updater list.
188  * 
189  * \retval 0 on success
190  * \retval -1 on failure.
191  */
192 int ast_loader_unregister(int (*updater)(void));
193
194 /*!
195  * \brief Run the unload() callback for all loaded modules
196  *
197  * This function should be called when Asterisk is shutting down gracefully.
198  */
199 void ast_module_shutdown(void);
200
201 /*! 
202  * \brief Match modules names for the Asterisk cli.
203  * \param line Unused by this function, but this should be the line we are
204  *        matching.
205  * \param word The partial name to match. 
206  * \param pos The position the word we are completing is in.
207  * \param state The possible match to return.
208  * \param rpos The position we should be matching.  This should be the same as
209  *        pos.
210  * \param needsreload This should be 1 if we need to reload this module and 0
211  *        otherwise.  This function will only return modules that are reloadble
212  *        if this is 1.
213  *
214  * \retval A possible completion of the partial match.
215  * \retval NULL if no matches were found.
216  */
217 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
218
219 /* Opaque type for module handles generated by the loader */
220
221 struct ast_module;
222
223 /*!
224  * \brief Get the name of a module.
225  * \param mod A pointer to the module.
226  * \return the name of the module
227  * \retval NULL if mod or mod->info is NULL
228  */
229 const char *ast_module_name(const struct ast_module *mod);
230
231 /* User count routines keep track of which channels are using a given module
232    resource.  They can help make removing modules safer, particularly if
233    they're in use at the time they have been requested to be removed */
234
235 struct ast_module_user;
236 struct ast_module_user_list;
237
238 /*! \page ModMngmnt The Asterisk Module management interface
239  *
240  * All modules must implement the module API (load, unload...)
241  */
242
243 enum ast_module_flags {
244         AST_MODFLAG_DEFAULT = 0,
245         AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
246         AST_MODFLAG_LOAD_ORDER = (1 << 1),
247 };
248
249 enum ast_module_load_priority {
250         AST_MODPRI_REALTIME_DEPEND =    10,  /*!< Dependency for a realtime driver */
251         AST_MODPRI_REALTIME_DEPEND2 =   20,  /*!< Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl) */
252         AST_MODPRI_REALTIME_DRIVER =    30,  /*!< A realtime driver, which provides configuration services for other modules */
253         AST_MODPRI_TIMING =             40,  /*!< Dependency for a channel (MOH needs timing interfaces to be fully loaded) */
254         AST_MODPRI_CHANNEL_DEPEND =     50,  /*!< Channel driver dependency (may depend upon realtime, e.g. MOH) */
255         AST_MODPRI_CHANNEL_DRIVER =     60,  /*!< Channel drivers (provide devicestate) */
256         AST_MODPRI_APP_DEPEND =         70,  /*!< Dependency for an application */
257         AST_MODPRI_DEVSTATE_PROVIDER =  80,  /*!< Applications and other modules that _provide_ devicestate (e.g. meetme) */
258         AST_MODPRI_DEVSTATE_PLUGIN =    90,  /*!< Plugin for a module that provides devstate (e.g. res_calendar_*) */
259         AST_MODPRI_CDR_DRIVER =        100,  /*!< CDR or CEL backend */
260         AST_MODPRI_DEFAULT =           128,  /*!< Modules not otherwise defined (such as most apps) will load here */
261         AST_MODPRI_DEVSTATE_CONSUMER = 150,  /*!< Certain modules, which consume devstate, need to load after all others (e.g. app_queue) */
262 };
263
264 struct ast_module_info {
265
266         /*!
267          * The 'self' pointer for a module; it will be set by the loader before
268          * it calls the module's load_module() entrypoint, and used by various
269          * other macros that need to identify the module.
270          */
271
272         struct ast_module *self;
273         enum ast_module_load_result (*load)(void);      /*!< register stuff etc. Optional. */
274         int (*reload)(void);                    /*!< config etc. Optional. */
275         int (*unload)(void);                    /*!< unload. called with the module locked */
276         int (*backup_globals)(void);            /*!< for embedded modules, backup global data */
277         void (*restore_globals)(void);          /*!< for embedded modules, restore global data */
278         const char *name;                       /*!< name of the module for loader reference and CLI commands */
279         const char *description;                /*!< user friendly description of the module. */
280
281         /*! 
282          * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
283          * the Asterisk license as stated in the ASTERISK_GPL_KEY.  Your module will not
284          * load if it does not return the EXACT key string.
285          */
286
287         const char *key;
288         unsigned int flags;
289
290         /*! The value of AST_BUILDOPT_SUM when this module was compiled */
291         const char buildopt_sum[33];
292
293         /*! This value represents the order in which a module's load() function is initialized.
294          *  The lower this value, the higher the priority.  The value is only checked if the
295          *  AST_MODFLAG_LOAD_ORDER flag is set.  If the AST_MODFLAG_LOAD_ORDER flag is not set,
296          *  this value will never be read and the module will be given the lowest possible priority
297          *  on load. */
298         unsigned char load_pri;
299
300         /*! Modules which should be loaded first, in comma-separated string format.
301          * These are only required for loading, when the optional_api header file
302          * detects that the compiler does not support the optional API featureset. */
303         const char *nonoptreq;
304         /*! The support level for the given module */
305         enum ast_module_support_level support_level;
306 };
307
308 void ast_module_register(const struct ast_module_info *);
309 void ast_module_unregister(const struct ast_module_info *);
310
311 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
312 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
313 void __ast_module_user_hangup_all(struct ast_module *);
314
315 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
316 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
317 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
318
319 struct ast_module *ast_module_ref(struct ast_module *);
320 void ast_module_unref(struct ast_module *);
321
322 #if defined(__cplusplus) || defined(c_plusplus)
323 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func, load_pri, support_level)       \
324         static struct ast_module_info __mod_info = {    \
325                 NULL,                                                          \
326                 load_func,                                                     \
327                 reload_func,                                                   \
328                 unload_func,                                                   \
329                 NULL,                                                          \
330                 NULL,                                                          \
331                 AST_MODULE,                                                    \
332                 desc,                                                          \
333                 keystr,                                                        \
334                 flags_to_set,                                                  \
335                 AST_BUILDOPT_SUM,                                              \
336                 load_pri,                                                      \
337                 NULL,                                                          \
338                 support_level,                                                 \
339         };                                                                 \
340         static void  __attribute__((constructor)) __reg_module(void)       \
341         {                                                                  \
342                 ast_module_register(&__mod_info);                              \
343         }                                                                  \
344         static void  __attribute__((destructor)) __unreg_module(void)      \
345         {                                                                  \
346                 ast_module_unregister(&__mod_info);                            \
347         }                                                                  \
348         static const __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
349
350 #define AST_MODULE_INFO_STANDARD(keystr, desc)              \
351         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
352                         load_module,                                    \
353                         unload_module,                                  \
354                         NULL,                                           \
355                         AST_MODPRI_DEFAULT,                             \
356                         AST_MODULE_SUPPORT_CORE                         \
357                        )
358
359 #define AST_MODULE_INFO_STANDARD_EXTENDED(keystr, desc)     \
360         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
361                         load_module,                                    \
362                         unload_module,                                  \
363                         NULL,                                           \
364                         AST_MODPRI_DEFAULT,                             \
365                         AST_MODULE_SUPPORT_EXTENDED                     \
366                        )
367 #define AST_MODULE_INFO_STANDARD_DEPRECATED(keystr, desc)   \
368         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
369                         load_module,                                    \
370                         unload_module,                                  \
371                         NULL,                                           \
372                         AST_MODPRI_DEFAULT,                             \
373                         AST_MODULE_SUPPORT_DEPRECATED                   \
374                        )
375
376 #else /* plain C */
377
378 /* forward declare this pointer in modules, so that macro/function
379    calls that need it can get it, since it will actually be declared
380    and populated at the end of the module's source file... */
381 static const __attribute__((unused)) struct ast_module_info *ast_module_info;
382
383 #if !defined(EMBEDDED_MODULE)
384 #define __MODULE_INFO_SECTION
385 #define __MODULE_INFO_GLOBALS
386 #else
387 /*
388  * For embedded modules we need additional information to backup and
389  * restore the global variables in the module itself, so we can unload
390  * reload the module.
391  * EMBEDDED_MODULE is defined as the module name, so the calls to make_var()
392  * below will actually define different symbols for each module.
393  */
394 #define __MODULE_INFO_SECTION   __attribute__((section(".embed_module")))
395 #define __MODULE_INFO_GLOBALS   .backup_globals = __backup_globals, .restore_globals = __restore_globals,
396
397 #define make_var_sub(mod, type) __ ## mod ## _ ## type
398 #define make_var(mod, type) make_var_sub(mod, type)
399
400 extern void make_var(EMBEDDED_MODULE, bss_start);
401 extern void make_var(EMBEDDED_MODULE, bss_end);
402 extern void make_var(EMBEDDED_MODULE, data_start);
403 extern void make_var(EMBEDDED_MODULE, data_end);
404
405 static void * __attribute__((section(".embed_module"))) __global_backup;
406
407 static int __backup_globals(void)
408 {
409         size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
410
411         if (__global_backup)
412                 return 0;
413
414         if (!data_size)
415                 return 0;
416
417         if (!(__global_backup = ast_malloc(data_size)))
418                 return -1;
419
420         memcpy(__global_backup, & make_var(EMBEDDED_MODULE, data_start), data_size);
421
422         return 0;
423 }
424
425 static void __restore_globals(void)
426 {
427         size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
428         size_t bss_size = & make_var(EMBEDDED_MODULE, bss_end) - & make_var(EMBEDDED_MODULE, bss_start);
429
430         if (bss_size)
431                 memset(& make_var(EMBEDDED_MODULE, bss_start), 0, bss_size);
432
433         if (!data_size || !__global_backup)
434                 return;
435
436         memcpy(& make_var(EMBEDDED_MODULE, data_start), __global_backup, data_size);
437 }
438 #undef make_var
439 #undef make_var_sub
440 #endif /* EMBEDDED_MODULE */
441
442 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)  \
443         static struct ast_module_info                           \
444                 __MODULE_INFO_SECTION                           \
445                 __mod_info = {                                  \
446                 __MODULE_INFO_GLOBALS                           \
447                 .name = AST_MODULE,                             \
448                 .flags = flags_to_set,                          \
449                 .description = desc,                            \
450                 .key = keystr,                                  \
451                 .buildopt_sum = AST_BUILDOPT_SUM,               \
452                 fields                                          \
453         };                                                      \
454         static void  __attribute__((constructor)) __reg_module(void) \
455         { \
456                 ast_module_register(&__mod_info); \
457         } \
458         static void  __attribute__((destructor)) __unreg_module(void) \
459         { \
460                 ast_module_unregister(&__mod_info); \
461         } \
462         static const struct ast_module_info *ast_module_info = &__mod_info
463
464 #define AST_MODULE_INFO_STANDARD(keystr, desc)              \
465         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
466                         .load = load_module,                            \
467                         .unload = unload_module,                        \
468                         .load_pri = AST_MODPRI_DEFAULT,                 \
469                         .support_level = AST_MODULE_SUPPORT_CORE,       \
470                        )
471
472 #define AST_MODULE_INFO_STANDARD_EXTENDED(keystr, desc)     \
473         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
474                         .load = load_module,                            \
475                         .unload = unload_module,                        \
476                         .load_pri = AST_MODPRI_DEFAULT,                 \
477                         .support_level = AST_MODULE_SUPPORT_EXTENDED,   \
478                        )
479
480 #define AST_MODULE_INFO_STANDARD_DEPRECATED(keystr, desc)   \
481         AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc,   \
482                         .load = load_module,                            \
483                         .unload = unload_module,                        \
484                         .load_pri = AST_MODPRI_DEFAULT,                 \
485                         .support_level = AST_MODULE_SUPPORT_DEPRECATED, \
486                        )
487
488 #endif  /* plain C */
489
490 /*! 
491  * \brief Register an application.
492  *
493  * \param app Short name of the application
494  * \param execute a function callback to execute the application. It should return
495  *                non-zero if the channel needs to be hung up.
496  * \param synopsis a short description (one line synopsis) of the application
497  * \param description long description with all of the details about the use of 
498  *                    the application
499  * 
500  * This registers an application with Asterisk's internal application list. 
501  * \note The individual applications themselves are responsible for registering and unregistering
502  *       and unregistering their own CLI commands.
503  * 
504  * \retval 0 success 
505  * \retval -1 failure.
506  */
507 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self)
508
509 /*! 
510  * \brief Register an application using XML documentation.
511  *
512  * \param app Short name of the application
513  * \param execute a function callback to execute the application. It should return
514  *                non-zero if the channel needs to be hung up.
515  * 
516  * This registers an application with Asterisk's internal application list. 
517  * \note The individual applications themselves are responsible for registering and unregistering
518  *       and unregistering their own CLI commands.
519  * 
520  * \retval 0 success 
521  * \retval -1 failure.
522  */
523 #define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL)
524
525
526 /*!
527  * \brief Register an application.
528  *
529  * \param app Short name of the application
530  * \param execute a function callback to execute the application. It should return
531  *                non-zero if the channel needs to be hung up.
532  * \param synopsis a short description (one line synopsis) of the application
533  * \param description long description with all of the details about the use of
534  *                    the application
535  * \param mod module this application belongs to
536  *
537  * This registers an application with Asterisk's internal application list.
538  * \note The individual applications themselves are responsible for registering and unregistering
539  *       and unregistering their own CLI commands.
540  *
541  * \retval 0 success
542  * \retval -1 failure.
543  */
544 int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *),
545                                      const char *synopsis, const char *description, void *mod);
546
547 /*! 
548  * \brief Unregister an application
549  * 
550  * \param app name of the application (does not have to be the same string as the one that was registered)
551  * 
552  * This unregisters an application from Asterisk's internal application list.
553  * 
554  * \retval 0 success 
555  * \retval -1 failure
556  */
557 int ast_unregister_application(const char *app);
558
559 const char *ast_module_support_level_to_string(enum ast_module_support_level support_level);
560
561 /*! Macro to safely ref and unref the self module for the current scope */
562 #define SCOPED_MODULE_USE(module) \
563         RAII_VAR(struct ast_module *, __self__ ## __LINE__, ast_module_ref(module), ast_module_unref)
564
565 #if defined(__cplusplus) || defined(c_plusplus)
566 }
567 #endif
568
569 #endif /* _ASTERISK_MODULE_H */