include/asterisk/module.h

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