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