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