Asterisk - The Open Source Telephony Project  21.4.1
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 /*! \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 
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 
69  /*! Module is loaded and configured. */
71  /*!
72  * \brief Module has failed to load, may be in an inconsistent state.
73  *
74  * This value is used when a module fails to start but does not risk
75  * system-wide stability. Declined modules will prevent any other
76  * dependent module from starting.
77  */
79  /*! \internal
80  * \brief Module was skipped for some reason.
81  *
82  * \note For loader.c use only. Should never be returned by modules.
83  */
84  AST_MODULE_LOAD_SKIP = 2,
85  /*! \internal
86  * \brief Module is not loaded yet, but is added to priority list.
87  *
88  * \note For loader.c use only. Should never be returned by modules.
89  */
90  AST_MODULE_LOAD_PRIORITY = 3,
91  /*!
92  * \brief Module could not be loaded properly.
93  *
94  * This return should only be returned by modules for unrecoverable
95  * failures that cause the whole system to become unstable. In almost
96  * all cases \ref AST_MODULE_LOAD_DECLINE should be used instead.
97  *
98  * \warning Returning this code from any module will cause startup to abort.
99  * If startup is already completed this code has the same effect as
100  * \ref AST_MODULE_LOAD_DECLINE.
101  */
103 };
104 
105 /*!
106  * \since 12
107  * \brief Possible return types for \ref ast_module_reload
108  */
110  AST_MODULE_RELOAD_SUCCESS = 0, /*!< The module was reloaded succesfully */
111  AST_MODULE_RELOAD_QUEUED, /*!< The module reload request was queued */
112  AST_MODULE_RELOAD_NOT_FOUND, /*!< The requested module was not found */
113  AST_MODULE_RELOAD_ERROR, /*!< An error occurred while reloading the module */
114  AST_MODULE_RELOAD_IN_PROGRESS, /*!< A module reload request is already in progress */
115  AST_MODULE_RELOAD_UNINITIALIZED, /*!< The module has not been initialized */
116  AST_MODULE_RELOAD_NOT_IMPLEMENTED, /*!< This module doesn't support reloading */
117 };
118 
119 enum ast_module_support_level {
120  AST_MODULE_SUPPORT_UNKNOWN,
121  AST_MODULE_SUPPORT_CORE,
122  AST_MODULE_SUPPORT_EXTENDED,
123  AST_MODULE_SUPPORT_DEPRECATED,
124 };
125 
126 /*! Used to specify which modules should be returned by ast_module_helper. */
128  /*! Modules that are loaded by dlopen. */
130  /*! Running modules that include a reload callback. */
132  /*! Modules that can be loaded or started. */
134  /*! Modules that can be unloaded. */
136  /*! Running modules */
138 };
139 
140 /*!
141  * \brief Load a module.
142  * \param resource_name The name of the module to load.
143  *
144  * This function is run by the PBX to load the modules. It performs
145  * all loading and initialization tasks. Basically, to load a module, just
146  * give it the name of the module and it will do the rest.
147  *
148  * \return See possible enum values for ast_module_load_result.
149  */
150 enum ast_module_load_result ast_load_resource(const char *resource_name);
151 
152 /*!
153  * \brief Unload and load a module again.
154  * \param resource_name The name of the module to unload.
155  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE flags.
156  * \param recursive Attempt to recursively unload any dependents of this module
157  * if that will allow the module to unload, and load them back again afterwards.
158  *
159  *
160  * \retval 0 on success.
161  * \retval 1 on error unloading modules.
162  * \retval -1 on error loading modules back.
163  */
164 int ast_refresh_resource(const char *resource_name, enum ast_module_unload_mode force, int recursive);
165 
166 /*!
167  * \brief Unload a module.
168  * \param resource_name The name of the module to unload.
169  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE 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  * \retval 0 on success.
177  * \retval -1 on error.
178  */
179 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
180 
181 /*!
182  * \brief Reload asterisk modules.
183  * \param name the name of the module to reload
184  *
185  * This function reloads the specified module, or if no modules are specified,
186  * it will reload all loaded modules.
187  *
188  * \note Modules are reloaded using their reload() functions, not unloading
189  * them and loading them again.
190  *
191  * \retval The \ref ast_module_reload_result status of the module load request
192  */
193 enum ast_module_reload_result ast_module_reload(const char *name);
194 
195 /*!
196  * \brief Notify when usecount has been changed.
197  *
198  * This function calculates use counts and notifies anyone trying to keep track
199  * of them. It should be called whenever your module's usecount changes.
200  *
201  * \note The ast_module_user_* functions take care of calling this function for you.
202  */
203 void ast_update_use_count(void);
204 
205 /*!
206  * \brief Ask for a list of modules, descriptions, use counts and status.
207  * \param modentry A callback to an updater function.
208  * \param like
209  *
210  * For each of the modules loaded, modentry will be executed with the resource,
211  * description, and usecount values of each particular module.
212  *
213  * \return the number of modules loaded
214  */
215 int ast_update_module_list(int (*modentry)(const char *module, const char *description,
216  int usecnt, const char *status, const char *like,
217  enum ast_module_support_level support_level),
218  const char *like);
219 
220 /*!
221  * \brief Ask for a list of modules, descriptions, use counts and status.
222  * \param modentry A callback to an updater function
223  * \param like
224  * \param data Data passed into the callback for manipulation
225  *
226  * For each of the modules loaded, modentry will be executed with the resource,
227  * description, and usecount values of each particular module.
228  *
229  * \return the number of modules loaded
230  * \since 13.5.0
231  */
232 int ast_update_module_list_data(int (*modentry)(const char *module, const char *description,
233  int usecnt, const char *status, const char *like,
234  enum ast_module_support_level support_level,
235  void *data),
236  const char *like, void *data);
237 
238 /*!
239  * \brief Ask for a list of modules, descriptions, use counts and status.
240  * \param modentry A callback to an updater function
241  * \param like
242  * \param data Data passed into the callback for manipulation
243  * \param condition The condition to meet
244  *
245  * For each of the modules loaded, modentry will be executed with the resource,
246  * description, and usecount values of each particular module.
247  *
248  * \return the number of conditions met
249  * \since 13.5.0
250  */
251 int ast_update_module_list_condition(int (*modentry)(const char *module, const char *description,
252  int usecnt, const char *status, const char *like,
253  enum ast_module_support_level support_level,
254  void *data, const char *condition),
255  const char *like, void *data, const char *condition);
256 
257 /*!
258  * \brief Check if module with the name given is loaded
259  * \param name Module name, like "chan_pjsip.so"
260  * \retval 1 if true
261  * \retval 0 if false
262  */
263 int ast_module_check(const char *name);
264 
265 /*!
266  * \brief Add a procedure to be run when modules have been updated.
267  * \param updater The function to run when modules have been updated.
268  *
269  * This function adds the given function to a linked list of functions to be
270  * run when the modules are updated.
271  *
272  * \retval 0 on success
273  * \retval -1 on failure.
274  */
275 int ast_loader_register(int (*updater)(void));
276 
277 /*!
278  * \brief Remove a procedure to be run when modules are updated.
279  * \param updater The updater function to unregister.
280  *
281  * This removes the given function from the updater list.
282  *
283  * \retval 0 on success
284  * \retval -1 on failure.
285  */
286 int ast_loader_unregister(int (*updater)(void));
287 
288 /*!
289  * \brief Match modules names for the Asterisk cli.
290  * \param line Unused by this function, but this should be the line we are
291  * matching.
292  * \param word The partial name to match.
293  * \param pos The position the word we are completing is in.
294  * \param state The possible match to return.
295  * \param rpos The position we should be matching. This should be the same as
296  * pos.
297  * \param type The type of action that will be performed by CLI.
298  *
299  * \retval A possible completion of the partial match.
300  * \retval NULL if no matches were found or Asterisk is not yet fully booted.
301  */
302 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, enum ast_module_helper_type type);
303 
304 /* Opaque type for module handles generated by the loader */
305 
306 struct ast_module;
307 
308 /*!
309  * \brief Get the name of a module.
310  * \param mod A pointer to the module.
311  * \return the name of the module
312  * \retval NULL if mod or mod->info is NULL
313  */
314 const char *ast_module_name(const struct ast_module *mod);
315 
316 /* User count routines keep track of which channels are using a given module
317  resource. They can help make removing modules safer, particularly if
318  they're in use at the time they have been requested to be removed */
319 
320 struct ast_module_user;
321 struct ast_module_user_list;
322 
323 /*! \page ModMngmnt The Asterisk Module management interface
324  *
325  * All modules must implement the module API (load, unload...)
326  */
327 
328 enum ast_module_flags {
329  AST_MODFLAG_DEFAULT = 0,
330  AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
331  AST_MODFLAG_LOAD_ORDER = (1 << 1),
332 };
333 
335  AST_MODPRI_REALTIME_DEPEND = 10, /*!< Dependency for a realtime driver */
336  AST_MODPRI_REALTIME_DEPEND2 = 20, /*!< Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl) */
337  AST_MODPRI_REALTIME_DRIVER = 30, /*!< A realtime driver, which provides configuration services for other modules */
338  AST_MODPRI_CORE = 40, /*!< A core module originally meant to start between preload and load. */
339  AST_MODPRI_TIMING = 50, /*!< Dependency for a channel (MOH needs timing interfaces to be fully loaded) */
340  AST_MODPRI_CHANNEL_DEPEND = 60, /*!< Channel driver dependency (may depend upon realtime, e.g. MOH) */
341  AST_MODPRI_CHANNEL_DRIVER = 70, /*!< Channel drivers (provide devicestate) */
342  AST_MODPRI_APP_DEPEND = 80, /*!< Dependency for an application */
343  AST_MODPRI_DEVSTATE_PROVIDER = 90, /*!< Applications and other modules that _provide_ devicestate (e.g. meetme) */
344  AST_MODPRI_DEVSTATE_PLUGIN = 100, /*!< Plugin for a module that provides devstate (e.g. res_calendar_*) */
345  AST_MODPRI_CDR_DRIVER = 110, /*!< CDR or CEL backend */
346  AST_MODPRI_DEFAULT = 128, /*!< Modules not otherwise defined (such as most apps) will load here */
347  AST_MODPRI_DEVSTATE_CONSUMER = 150, /*!< Certain modules, which consume devstate, need to load after all others (e.g. app_queue) */
348 };
349 
351  /*!
352  * The 'self' pointer for a module; it will be set by the loader before
353  * it calls the module's load_module() entrypoint, and used by various
354  * other macros that need to identify the module.
355  */
356  struct ast_module *self;
357  /*! Register stuff etc. Optional. */
359  /*! Config etc. Optional. */
360  int (*reload)(void);
361  /*! Unload. called with the module locked */
362  int (*unload)(void);
363  /*! Name of the module for loader reference and CLI commands */
364  const char *name;
365  /*! User friendly description of the module. */
366  const char *description;
367 
368  /*!
369  * This holds the ASTERISK_GPL_KEY, signifying that you agree to the terms of
370  * the Asterisk license as stated in the ASTERISK_GPL_KEY. Your module will not
371  * load if it does not return the EXACT key string.
372  */
373  const char *key;
374  unsigned int flags;
375 
376  /*! The value of AST_BUILDOPT_SUM when this module was compiled */
377  const char buildopt_sum[33];
378 
379  /*! This value represents the order in which a module's load() function is initialized.
380  * The lower this value, the higher the priority. The value is only checked if the
381  * AST_MODFLAG_LOAD_ORDER flag is set. If the AST_MODFLAG_LOAD_ORDER flag is not set,
382  * this value will never be read and the module will be given the lowest possible priority
383  * on load. */
384  unsigned char load_pri;
385 
386  /*! Modules which must always be started first, in comma-separated string format. */
387  const char *requires;
388 
389  /*!
390  * \brief Comma-separated list of optionally required modules.
391  *
392  * The listed modules are optional, but load order is enforced. For example
393  * app_voicemail optionally requires res_adsi. This means that app_voicemail
394  * will happily load without res_adsi, but if both are being loaded the module
395  * loader will force res_adsi to start first.
396  */
397  const char *optional_modules;
398 
399  /*!
400  * \brief Modules that we provide enhanced functionality for.
401  *
402  * This is similar to a "requires" but specifies that we add functionality to
403  * the other modules. Any module that requires something we "enhances" will
404  * also require us, but only if we are dlopen'ed.
405  *
406  * Example:
407  * - res_fax_spandsp has .enhances = "res_fax".
408  * - res_my_module has .requires = "res_fax" but has no direct knowledge
409  * of res_fax_spandsp.
410  *
411  * This forces the following startup order among the 3 modules:
412  * 1) res_fax starts.
413  * 2) res_fax_spandsp starts, holds a reference to res_fax.
414  * 3) res_mymod starts, holds a reference to res_fax and res_fax_spandsp.
415  *
416  * If res_fax_spandsp were not being loaded res_mymod would load with
417  * res_fax only. If res_fax_spandsp were later loaded res_mymod would
418  * get a reference to it.
419  */
420  const char *enhances;
421 
422  /*! These reserved fields should be NULL, they exist to allow addition to this
423  * structure in a non-breaking way. */
424  void *reserved1;
425  void *reserved2;
426  void *reserved3;
427  void *reserved4;
428 
429  /*! The support level for the given module */
430  enum ast_module_support_level support_level;
431 };
432 
433 void ast_module_register(const struct ast_module_info *);
434 void ast_module_unregister(const struct ast_module_info *);
435 
436 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
437 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
438 void __ast_module_user_hangup_all(struct ast_module *);
439 
440 #define ast_module_user_add(chan) __ast_module_user_add(AST_MODULE_SELF, chan)
441 #define ast_module_user_remove(user) __ast_module_user_remove(AST_MODULE_SELF, user)
442 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(AST_MODULE_SELF)
443 
444 struct ast_module *__ast_module_ref(struct ast_module *mod, const char *file, int line, const char *func);
445 struct ast_module *__ast_module_running_ref(struct ast_module *mod, const char *file, int line, const char *func);
446 void __ast_module_shutdown_ref(struct ast_module *mod, const char *file, int line, const char *func);
447 void __ast_module_unref(struct ast_module *mod, const char *file, int line, const char *func);
448 
449 /*!
450  * \brief Hold a reference to the module
451  * \param mod Module to reference
452  * \return mod
453  *
454  * \note A module reference will prevent the module
455  * from being unloaded.
456  */
457 #define ast_module_ref(mod) __ast_module_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
458 
459 /*!
460  * \brief Hold a reference to the module if it is running.
461  * \param mod Module to reference
462  * \retval mod if running
463  * \retval NULL if not running
464  *
465  * The returned pointer should be released with ast_module_unref.
466  *
467  * \note A module reference will prevent the module from being unloaded.
468  */
469 #define ast_module_running_ref(mod) \
470  __ast_module_running_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
471 
472 /*!
473  * \brief Prevent unload of the module before shutdown
474  * \param mod Module to hold
475  *
476  * \note This should not be balanced by a call to ast_module_unref.
477  */
478 #define ast_module_shutdown_ref(mod) __ast_module_shutdown_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
479 /*!
480  * \brief Release a reference to the module
481  * \param mod Module to release
482  */
483 #define ast_module_unref(mod) __ast_module_unref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
484 
485 #if defined(__cplusplus) || defined(c_plusplus)
486 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func, load_pri, support_level) \
487  static struct ast_module_info __mod_info = { \
488  NULL, \
489  load_func, \
490  reload_func, \
491  unload_func, \
492  AST_MODULE, \
493  desc, \
494  keystr, \
495  flags_to_set, \
496  AST_BUILDOPT_SUM, \
497  load_pri, \
498  NULL, \
499  NULL, \
500  NULL, \
501  NULL, \
502  NULL, \
503  NULL, \
504  NULL, \
505  support_level, \
506  }; \
507  static void __attribute__((constructor)) __reg_module(void) \
508  { \
509  ast_module_register(&__mod_info); \
510  } \
511  static void __attribute__((destructor)) __unreg_module(void) \
512  { \
513  ast_module_unregister(&__mod_info); \
514  } \
515  struct ast_module *AST_MODULE_SELF_SYM(void) \
516  { \
517  return __mod_info.self; \
518  } \
519  static const __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
520 
521 
522 #define AST_MODULE_INFO_STANDARD(keystr, desc) \
523  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
524  load_module, \
525  unload_module, \
526  NULL, \
527  AST_MODPRI_DEFAULT, \
528  AST_MODULE_SUPPORT_CORE \
529  )
530 
531 #define AST_MODULE_INFO_STANDARD_EXTENDED(keystr, desc) \
532  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
533  load_module, \
534  unload_module, \
535  NULL, \
536  AST_MODPRI_DEFAULT, \
537  AST_MODULE_SUPPORT_EXTENDED \
538  )
539 #define AST_MODULE_INFO_STANDARD_DEPRECATED(keystr, desc) \
540  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
541  load_module, \
542  unload_module, \
543  NULL, \
544  AST_MODPRI_DEFAULT, \
545  AST_MODULE_SUPPORT_DEPRECATED \
546  )
547 
548 #else /* plain C */
549 
550 /* forward declare this pointer in modules, so that macro/function
551  calls that need it can get it, since it will actually be declared
552  and populated at the end of the module's source file... */
553 #if !defined(AST_IN_CORE)
554 static const __attribute__((unused)) struct ast_module_info *ast_module_info;
555 #endif
556 
557 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...) \
558  static struct ast_module_info \
559  __mod_info = { \
560  .name = AST_MODULE, \
561  .flags = flags_to_set, \
562  .description = desc, \
563  .key = keystr, \
564  .buildopt_sum = AST_BUILDOPT_SUM, \
565  fields \
566  }; \
567  static void __attribute__((constructor)) __reg_module(void) \
568  { \
569  ast_module_register(&__mod_info); \
570  } \
571  static void __attribute__((destructor)) __unreg_module(void) \
572  { \
573  ast_module_unregister(&__mod_info); \
574  } \
575  struct ast_module *AST_MODULE_SELF_SYM(void) \
576  { \
577  return __mod_info.self; \
578  } \
579  static const struct ast_module_info *ast_module_info = &__mod_info
580 
581 #define AST_MODULE_INFO_STANDARD(keystr, desc) \
582  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
583  .load = load_module, \
584  .unload = unload_module, \
585  .load_pri = AST_MODPRI_DEFAULT, \
586  .support_level = AST_MODULE_SUPPORT_CORE, \
587  )
588 
589 #define AST_MODULE_INFO_STANDARD_EXTENDED(keystr, desc) \
590  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
591  .load = load_module, \
592  .unload = unload_module, \
593  .load_pri = AST_MODPRI_DEFAULT, \
594  .support_level = AST_MODULE_SUPPORT_EXTENDED, \
595  )
596 
597 #define AST_MODULE_INFO_STANDARD_DEPRECATED(keystr, desc) \
598  AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
599  .load = load_module, \
600  .unload = unload_module, \
601  .load_pri = AST_MODPRI_DEFAULT, \
602  .support_level = AST_MODULE_SUPPORT_DEPRECATED, \
603  )
604 
605 #endif /* plain C */
606 
607 /*!
608  * \brief Register an application.
609  *
610  * \param app Short name of the application
611  * \param execute a function callback to execute the application. It should return
612  * non-zero if the channel needs to be hung up.
613  * \param synopsis a short description (one line synopsis) of the application
614  * \param description long description with all of the details about the use of
615  * the application
616  *
617  * This registers an application with Asterisk's internal application list.
618  * \note The individual applications themselves are responsible for registering and unregistering
619  * and unregistering their own CLI commands.
620  *
621  * \retval 0 success
622  * \retval -1 failure.
623  */
624 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, AST_MODULE_SELF)
625 
626 /*!
627  * \brief Register an application using XML documentation.
628  *
629  * \param app Short name of the application
630  * \param execute a function callback to execute the application. It should return
631  * non-zero if the channel needs to be hung up.
632  *
633  * This registers an application with Asterisk's internal application list.
634  * \note The individual applications themselves are responsible for registering and unregistering
635  * and unregistering their own CLI commands.
636  *
637  * \retval 0 success
638  * \retval -1 failure.
639  */
640 #define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL)
641 
642 
643 /*!
644  * \brief Register an application.
645  *
646  * \param app Short name of the application
647  * \param execute a function callback to execute the application. It should return
648  * non-zero if the channel needs to be hung up.
649  * \param synopsis a short description (one line synopsis) of the application
650  * \param description long description with all of the details about the use of
651  * the application
652  * \param mod module this application belongs to
653  *
654  * This registers an application with Asterisk's internal application list.
655  * \note The individual applications themselves are responsible for registering and unregistering
656  * and unregistering their own CLI commands.
657  *
658  * \retval 0 success
659  * \retval -1 failure.
660  */
661 int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *),
662  const char *synopsis, const char *description, void *mod);
663 
664 /*!
665  * \brief Unregister an application
666  *
667  * \param app name of the application (does not have to be the same string as the one that was registered)
668  *
669  * This unregisters an application from Asterisk's internal application list.
670  *
671  * \retval 0 success
672  * \retval -1 failure
673  */
674 int ast_unregister_application(const char *app);
675 
676 const char *ast_module_support_level_to_string(enum ast_module_support_level support_level);
677 
678 /*! Macro to safely ref and unref the self module for the current scope */
679 #define SCOPED_MODULE_USE(module) \
680  RAII_VAR(struct ast_module *, __self__ ## __LINE__, ast_module_ref(module), ast_module_unref)
681 
682 #if defined(__cplusplus) || defined(c_plusplus)
683 }
684 #endif
685 
686 #endif /* _ASTERISK_MODULE_H */
const char * description
Definition: module.h:366
ast_module_load_result
Definition: module.h:68
Main Channel structure associated with a channel.
static SQLHSTMT execute(struct odbc_obj *obj, void *data, int silent)
Common execution function for SQL queries.
Definition: func_odbc.c:471
char * ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, enum ast_module_helper_type type)
Match modules names for the Asterisk cli.
Definition: loader.c:1528
enum ast_module_load_result ast_load_resource(const char *resource_name)
Load a module.
Definition: loader.c:1978
enum ast_module_reload_result ast_module_reload(const char *name)
Reload asterisk modules.
Definition: loader.c:1721
ast_module_reload_result
Possible return types for ast_module_reload.
Definition: module.h:109
unsigned char load_pri
Definition: module.h:384
void * reserved1
Definition: module.h:424
int ast_refresh_resource(const char *resource_name, enum ast_module_unload_mode force, int recursive)
Unload and load a module again.
Definition: loader.c:1407
void ast_update_use_count(void)
Notify when usecount has been changed.
Definition: loader.c:2698
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx_app.c:392
ast_module_helper_type
Definition: module.h:127
const char * enhances
Modules that we provide enhanced functionality for.
Definition: module.h:420
int ast_module_check(const char *name)
Check if module with the name given is loaded.
Definition: loader.c:2823
Utility functions.
const char * requires
Definition: module.h:387
int ast_update_module_list(int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level), const char *like)
Ask for a list of modules, descriptions, use counts and status.
int ast_update_module_list_data(int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data), const char *like, void *data)
Ask for a list of modules, descriptions, use counts and status.
Definition: loader.c:2764
const char * name
Definition: module.h:364
const char * optional_modules
Comma-separated list of optionally required modules.
Definition: module.h:397
int(* unload)(void)
Definition: module.h:362
ast_module_unload_mode
Definition: module.h:61
int(* reload)(void)
Definition: module.h:360
int ast_loader_unregister(int(*updater)(void))
Remove a procedure to be run when modules are updated.
Definition: loader.c:2851
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode)
Unload a module.
Definition: loader.c:1448
int ast_update_module_list_condition(int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data, const char *condition), const char *like, void *data, const char *condition)
Ask for a list of modules, descriptions, use counts and status.
union ast_frame::@224 data
Module could not be loaded properly.
Definition: module.h:102
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
int ast_loader_register(int(*updater)(void))
Add a procedure to be run when modules have been updated.
Definition: loader.c:2836
const char * ast_module_name(const struct ast_module *mod)
Get the name of a module.
Definition: loader.c:615
const char * key
Definition: module.h:373
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_app.c:103
ast_module_load_priority
Definition: module.h:334
enum ast_module_load_result(* load)(void)
Definition: module.h:358
enum ast_module_support_level support_level
Definition: module.h:430
const char buildopt_sum[33]
Definition: module.h:377