Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


module.h
Go to the documentation of this file.
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 
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 
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 initialization 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 /*!
179  * \brief Get the name of a module.
180  * \param mod A pointer to the module.
181  * \return the name of the module
182  * \retval NULL if mod or mod->info is NULL
183  */
184 const char *ast_module_name(const struct ast_module *mod);
185 
186 /* User count routines keep track of which channels are using a given module
187  resource. They can help make removing modules safer, particularly if
188  they're in use at the time they have been requested to be removed */
189 
190 struct ast_module_user;
191 struct ast_module_user_list;
192 
193 /*! \page ModMngmnt The Asterisk Module management interface
194  *
195  * All modules must implement the module API (load, unload...)
196  */
197 
202 };
203 
205  AST_MODPRI_REALTIME_DEPEND = 10, /*!< Dependency for a realtime driver */
206  AST_MODPRI_REALTIME_DEPEND2 = 20, /*!< Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl) */
207  AST_MODPRI_REALTIME_DRIVER = 30, /*!< A realtime driver, which provides configuration services for other modules */
208  AST_MODPRI_TIMING = 40, /*!< Dependency for a channel (MOH needs timing interfaces to be fully loaded) */
209  AST_MODPRI_CHANNEL_DEPEND = 50, /*!< Channel driver dependency (may depend upon realtime, e.g. MOH) */
210  AST_MODPRI_CHANNEL_DRIVER = 60, /*!< Channel drivers (provide devicestate) */
211  AST_MODPRI_APP_DEPEND = 70, /*!< Dependency for an application */
212  AST_MODPRI_DEVSTATE_PROVIDER = 80, /*!< Applications and other modules that _provide_ devicestate (e.g. meetme) */
213  AST_MODPRI_DEVSTATE_PLUGIN = 90, /*!< Plugin for a module that provides devstate (e.g. res_calendar_*) */
214  AST_MODPRI_CDR_DRIVER = 100, /*!< CDR or CEL backend */
215  AST_MODPRI_DEFAULT = 128, /*!< Modules not otherwise defined (such as most apps) will load here */
216  AST_MODPRI_DEVSTATE_CONSUMER = 150, /*!< Certain modules, which consume devstate, need to load after all others (e.g. app_queue) */
217 };
218 
220 
221  /*!
222  * The 'self' pointer for a module; it will be set by the loader before
223  * it calls the module's load_module() entrypoint, and used by various
224  * other macros that need to identify the module.
225  */
226 
227  struct ast_module *self;
228  enum ast_module_load_result (*load)(void); /*!< register stuff etc. Optional. */
229  int (*reload)(void); /*!< config etc. Optional. */
230  int (*unload)(void); /*!< unload. called with the module locked */
231  int (*backup_globals)(void); /*!< for embedded modules, backup global data */
232  void (*restore_globals)(void); /*!< for embedded modules, restore global data */
233  const char *name; /*!< name of the module for loader reference and CLI commands */
234  const char *description; /*!< user friendly description of the module. */
235 
236  /*!
237  * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
238  * the Asterisk license as stated in the ASTERISK_GPL_KEY. Your module will not
239  * load if it does not return the EXACT key string.
240  */
241 
242  const char *key;
243  unsigned int flags;
244 
245  /*! The value of AST_BUILDOPT_SUM when this module was compiled */
246  const char buildopt_sum[33];
247 
248  /*! This value represents the order in which a module's load() function is initialized.
249  * The lower this value, the higher the priority. The value is only checked if the
250  * AST_MODFLAG_LOAD_ORDER flag is set. If the AST_MODFLAG_LOAD_ORDER flag is not set,
251  * this value will never be read and the module will be given the lowest possible priority
252  * on load. */
253  unsigned char load_pri;
254 
255  /*! Modules which should be loaded first, in comma-separated string format.
256  * These are only required for loading, when the optional_api header file
257  * detects that the compiler does not support the optional API featureset. */
258  const char *nonoptreq;
259 };
260 
261 void ast_module_register(const struct ast_module_info *);
262 void ast_module_unregister(const struct ast_module_info *);
263 
264 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
265 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
267 
268 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
269 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
270 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
271 
272 struct ast_module *ast_module_ref(struct ast_module *);
273 void ast_module_unref(struct ast_module *);
274 
275 #if defined(__cplusplus) || defined(c_plusplus)
276 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func, load_pri) \
277  static struct ast_module_info __mod_info = { \
278  NULL, \
279  load_func, \
280  reload_func, \
281  unload_func, \
282  NULL, \
283  NULL, \
284  AST_MODULE, \
285  desc, \
286  keystr, \
287  flags_to_set, \
288  AST_BUILDOPT_SUM, \
289  load_pri, \
290  }; \
291  static void __attribute__((constructor)) __reg_module(void) \
292  { \
293  ast_module_register(&__mod_info); \
294  } \
295  static void __attribute__((destructor)) __unreg_module(void) \
296  { \
297  ast_module_unregister(&__mod_info); \
298  } \
299  static const __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
300 
301 #define AST_MODULE_INFO_STANDARD(keystr, desc) \
302  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
303  load_module, \
304  unload_module, \
305  NULL, \
306  AST_MODPRI_DEFAULT \
307  )
308 #else /* plain C */
309 
310 /* forward declare this pointer in modules, so that macro/function
311  calls that need it can get it, since it will actually be declared
312  and populated at the end of the module's source file... */
313 static const __attribute__((unused)) struct ast_module_info *ast_module_info;
314 
315 #if !defined(EMBEDDED_MODULE)
316 #define __MODULE_INFO_SECTION
317 #define __MODULE_INFO_GLOBALS
318 #else
319 /*
320  * For embedded modules we need additional information to backup and
321  * restore the global variables in the module itself, so we can unload
322  * reload the module.
323  * EMBEDDED_MODULE is defined as the module name, so the calls to make_var()
324  * below will actually define different symbols for each module.
325  */
326 #define __MODULE_INFO_SECTION __attribute__((section(".embed_module")))
327 #define __MODULE_INFO_GLOBALS .backup_globals = __backup_globals, .restore_globals = __restore_globals,
328 
329 #define make_var_sub(mod, type) __ ## mod ## _ ## type
330 #define make_var(mod, type) make_var_sub(mod, type)
331 
332 extern void make_var(EMBEDDED_MODULE, bss_start);
333 extern void make_var(EMBEDDED_MODULE, bss_end);
334 extern void make_var(EMBEDDED_MODULE, data_start);
335 extern void make_var(EMBEDDED_MODULE, data_end);
336 
337 static void * __attribute__((section(".embed_module"))) __global_backup;
338 
339 static int __backup_globals(void)
340 {
341  size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
342 
343  if (__global_backup)
344  return 0;
345 
346  if (!data_size)
347  return 0;
348 
349  if (!(__global_backup = ast_malloc(data_size)))
350  return -1;
351 
352  memcpy(__global_backup, & make_var(EMBEDDED_MODULE, data_start), data_size);
353 
354  return 0;
355 }
356 
357 static void __restore_globals(void)
358 {
359  size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
360  size_t bss_size = & make_var(EMBEDDED_MODULE, bss_end) - & make_var(EMBEDDED_MODULE, bss_start);
361 
362  if (bss_size)
363  memset(& make_var(EMBEDDED_MODULE, bss_start), 0, bss_size);
364 
365  if (!data_size || !__global_backup)
366  return;
367 
368  memcpy(& make_var(EMBEDDED_MODULE, data_start), __global_backup, data_size);
369 }
370 #undef make_var
371 #undef make_var_sub
372 #endif /* EMBEDDED_MODULE */
373 
374 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...) \
375  static struct ast_module_info \
376  __MODULE_INFO_SECTION \
377  __mod_info = { \
378  __MODULE_INFO_GLOBALS \
379  .name = AST_MODULE, \
380  .flags = flags_to_set, \
381  .description = desc, \
382  .key = keystr, \
383  .buildopt_sum = AST_BUILDOPT_SUM, \
384  fields \
385  }; \
386  static void __attribute__((constructor)) __reg_module(void) \
387  { \
388  ast_module_register(&__mod_info); \
389  } \
390  static void __attribute__((destructor)) __unreg_module(void) \
391  { \
392  ast_module_unregister(&__mod_info); \
393  } \
394  static const struct ast_module_info *ast_module_info = &__mod_info
395 
396 #define AST_MODULE_INFO_STANDARD(keystr, desc) \
397  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
398  .load = load_module, \
399  .unload = unload_module, \
400  .load_pri = AST_MODPRI_DEFAULT, \
401  )
402 #endif /* plain C */
403 
404 /*!
405  * \brief Register an application.
406  *
407  * \param app Short name of the application
408  * \param execute a function callback to execute the application. It should return
409  * non-zero if the channel needs to be hung up.
410  * \param synopsis a short description (one line synopsis) of the application
411  * \param description long description with all of the details about the use of
412  * the application
413  *
414  * This registers an application with Asterisk's internal application list.
415  * \note The individual applications themselves are responsible for registering and unregistering
416  * and unregistering their own CLI commands.
417  *
418  * \retval 0 success
419  * \retval -1 failure.
420  */
421 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self)
422 
423 /*!
424  * \brief Register an application using XML documentation.
425  *
426  * \param app Short name of the application
427  * \param execute a function callback to execute the application. It should return
428  * non-zero if the channel needs to be hung up.
429  *
430  * This registers an application with Asterisk's internal application list.
431  * \note The individual applications themselves are responsible for registering and unregistering
432  * and unregistering their own CLI commands.
433  *
434  * \retval 0 success
435  * \retval -1 failure.
436  */
437 #define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL)
438 
439 
440 /*!
441  * \brief Register an application.
442  *
443  * \param app Short name of the application
444  * \param execute a function callback to execute the application. It should return
445  * non-zero if the channel needs to be hung up.
446  * \param synopsis a short description (one line synopsis) of the application
447  * \param description long description with all of the details about the use of
448  * the application
449  * \param mod module this application belongs to
450  *
451  * This registers an application with Asterisk's internal application list.
452  * \note The individual applications themselves are responsible for registering and unregistering
453  * and unregistering their own CLI commands.
454  *
455  * \retval 0 success
456  * \retval -1 failure.
457  */
458 int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *),
459  const char *synopsis, const char *description, void *mod);
460 
461 /*!
462  * \brief Unregister an application
463  *
464  * \param app name of the application (does not have to be the same string as the one that was registered)
465  *
466  * This unregisters an application from Asterisk's internal application list.
467  *
468  * \retval 0 success
469  * \retval -1 failure
470  */
471 int ast_unregister_application(const char *app);
472 
473 
474 #if defined(__cplusplus) || defined(c_plusplus)
475 }
476 #endif
477 
478 #endif /* _ASTERISK_MODULE_H */
const char * description
Definition: module.h:234
ast_module_load_result
Definition: module.h:60
Main Channel structure associated with a channel.
Definition: channel.h:742
void ast_module_unref(struct ast_module *)
Definition: loader.c:1312
enum ast_module_load_result ast_load_resource(const char *resource_name)
Load a module.
Definition: loader.c:947
void __ast_module_user_hangup_all(struct ast_module *)
Definition: loader.c:254
const char * nonoptreq
Definition: module.h:258
unsigned char load_pri
Definition: module.h:253
void __ast_module_user_remove(struct ast_module *, struct ast_module_user *)
Definition: loader.c:231
enum ast_module_load_result(* load)(void)
Definition: module.h:228
void ast_module_shutdown(void)
Run the unload() callback for all loaded modules.
Definition: loader.c:513
unsigned int flags
Definition: module.h:243
void ast_update_use_count(void)
Notify when usecount has been changed.
Definition: loader.c:1222
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx.c:7705
Definition: ael.tab.c:203
int ast_module_check(const char *name)
Check if module with the name given is loaded.
Definition: loader.c:1255
Utility functions.
void ast_module_unregister(const struct ast_module_info *)
Definition: loader.c:185
const char * name
Definition: module.h:233
static const char app[]
Definition: app_adsiprog.c:49
int(* reload)(void)
Definition: module.h:229
char * ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload)
Match modules names for the Asterisk cli.
Definition: loader.c:626
ast_module_unload_mode
Definition: module.h:53
int(* unload)(void)
Definition: module.h:230
struct ast_module_user * __ast_module_user_add(struct ast_module *, struct ast_channel *)
Definition: loader.c:209
int ast_loader_unregister(int(*updater)(void))
Remove a procedure to be run when modules are updated.
Definition: loader.c:1283
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode)
Unload a module.
Definition: loader.c:551
static char * synopsis
Definition: func_enum.c:156
static const char name[]
int ast_loader_register(int(*updater)(void))
Add a procedure to be run when modules have been updated.
Definition: loader.c:1268
const char * ast_module_name(const struct ast_module *mod)
Get the name of a module.
Definition: loader.c:104
const char * key
Definition: module.h:242
int(* backup_globals)(void)
Definition: module.h:231
int ast_update_module_list(int(*modentry)(const char *module, const char *description, int usecnt, const char *like), const char *like)
Ask for a list of modules, descriptions, and use counts.
Definition: loader.c:1234
void(* restore_globals)(void)
Definition: module.h:232
int ast_register_application2(const char *app, int(*execute)(struct ast_channel *, const char *), const char *synopsis, const char *description, void *mod)
Register an application.
Definition: pbx.c:6344
ast_module_load_priority
Definition: module.h:204
void ast_module_register(const struct ast_module_info *)
Definition: loader.c:147
#define ast_malloc(a)
Definition: astmm.h:91
static int usecnt
Definition: chan_unistim.c:236
const char buildopt_sum[33]
Definition: module.h:246
ast_module_flags
Definition: module.h:198
struct ast_module * ast_module_ref(struct ast_module *)
Definition: loader.c:1300