Thu Oct 11 06:33:50 2012

Asterisk developer's documentation


module.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2008, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  * Kevin P. Fleming <kpfleming@digium.com>
00008  * Luigi Rizzo <rizzo@icir.org>
00009  *
00010  * See http://www.asterisk.org for more information about
00011  * the Asterisk project. Please do not directly contact
00012  * any of the maintainers of this project for assistance;
00013  * the project provides a web site, mailing lists and IRC
00014  * channels for your use.
00015  *
00016  * This program is free software, distributed under the terms of
00017  * the GNU General Public License Version 2. See the LICENSE file
00018  * at the top of the source tree.
00019  */
00020 
00021 /*! \file
00022  * \brief Asterisk module definitions.
00023  *
00024  * This file contains the definitons for functions Asterisk modules should
00025  * provide and some other module related functions.
00026  */
00027 
00028 #ifndef _ASTERISK_MODULE_H
00029 #define _ASTERISK_MODULE_H
00030 
00031 #include "asterisk/utils.h"
00032 
00033 #if defined(__cplusplus) || defined(c_plusplus)
00034 extern "C" {
00035 #endif
00036 
00037 /*! \brief The text the key() function should return. */
00038 #define ASTERISK_GPL_KEY \
00039 "This paragraph is copyright (c) 2006 by Digium, Inc. \
00040 In order for your module to load, it must return this \
00041 key via a function called \"key\".  Any code which \
00042 includes this paragraph must be licensed under the GNU \
00043 General Public License version 2 or later (at your \
00044 option).  In addition to Digium's general reservations \
00045 of rights, Digium expressly reserves the right to \
00046 allow other parties to license this paragraph under \
00047 different terms. Any use of Digium, Inc. trademarks or \
00048 logos (including \"Asterisk\" or \"Digium\") without \
00049 express written permission of Digium, Inc. is prohibited.\n"
00050 
00051 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
00052 
00053 enum ast_module_unload_mode {
00054    AST_FORCE_SOFT = 0, /*!< Softly unload a module, only if not in use */
00055    AST_FORCE_FIRM = 1, /*!< Firmly unload a module, even if in use */
00056    AST_FORCE_HARD = 2, /*!< as FIRM, plus dlclose() on the module. Not recommended
00057             as it may cause crashes */
00058 };
00059 
00060 enum ast_module_load_result {
00061    AST_MODULE_LOAD_SUCCESS = 0,    /*!< Module loaded and configured */
00062    AST_MODULE_LOAD_DECLINE = 1,    /*!< Module is not configured */
00063    AST_MODULE_LOAD_SKIP = 2,       /*!< Module was skipped for some reason */
00064    AST_MODULE_LOAD_PRIORITY = 3,   /*!< Module is not loaded yet, but is added to prioity heap */
00065    AST_MODULE_LOAD_FAILURE = -1,   /*!< Module could not be loaded properly */
00066 };
00067 
00068 /*! 
00069  * \brief Load a module.
00070  * \param resource_name The name of the module to load.
00071  *
00072  * This function is run by the PBX to load the modules.  It performs
00073  * all loading and initialization tasks.   Basically, to load a module, just
00074  * give it the name of the module and it will do the rest.
00075  *
00076  * \return See possible enum values for ast_module_load_result.
00077  */
00078 enum ast_module_load_result ast_load_resource(const char *resource_name);
00079 
00080 /*! 
00081  * \brief Unload a module.
00082  * \param resource_name The name of the module to unload.
00083  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE flags.
00084  *
00085  * This function unloads a module.  It will only unload modules that are not in
00086  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
00087  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
00088  * module regardless of consequences (NOT RECOMMENDED).
00089  *
00090  * \retval 0 on success.
00091  * \retval -1 on error.
00092  */
00093 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
00094 
00095 /*! 
00096  * \brief Notify when usecount has been changed.
00097  *
00098  * This function calulates use counts and notifies anyone trying to keep track
00099  * of them.  It should be called whenever your module's usecount changes.
00100  *
00101  * \note The ast_module_user_* functions take care of calling this function for you.
00102  */
00103 void ast_update_use_count(void);
00104 
00105 /*! 
00106  * \brief Ask for a list of modules, descriptions, and use counts.
00107  * \param modentry A callback to an updater function.
00108  * \param like
00109  *
00110  * For each of the modules loaded, modentry will be executed with the resource,
00111  * description, and usecount values of each particular module.
00112  * 
00113  * \return the number of modules loaded
00114  */
00115 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
00116             const char *like);
00117 
00118 /*!
00119  * \brief Check if module with the name given is loaded
00120  * \param name Module name, like "chan_sip.so"
00121  * \retval 1 if true 
00122  * \retval 0 if false
00123  */
00124 int ast_module_check(const char *name);
00125 
00126 /*! 
00127  * \brief Add a procedure to be run when modules have been updated.
00128  * \param updater The function to run when modules have been updated.
00129  *
00130  * This function adds the given function to a linked list of functions to be
00131  * run when the modules are updated. 
00132  *
00133  * \retval 0 on success 
00134  * \retval -1 on failure.
00135  */
00136 int ast_loader_register(int (*updater)(void));
00137 
00138 /*! 
00139  * \brief Remove a procedure to be run when modules are updated.
00140  * \param updater The updater function to unregister.
00141  *
00142  * This removes the given function from the updater list.
00143  * 
00144  * \retval 0 on success
00145  * \retval -1 on failure.
00146  */
00147 int ast_loader_unregister(int (*updater)(void));
00148 
00149 /*!
00150  * \brief Run the unload() callback for all loaded modules
00151  *
00152  * This function should be called when Asterisk is shutting down gracefully.
00153  */
00154 void ast_module_shutdown(void);
00155 
00156 /*! 
00157  * \brief Match modules names for the Asterisk cli.
00158  * \param line Unused by this function, but this should be the line we are
00159  *        matching.
00160  * \param word The partial name to match. 
00161  * \param pos The position the word we are completing is in.
00162  * \param state The possible match to return.
00163  * \param rpos The position we should be matching.  This should be the same as
00164  *        pos.
00165  * \param needsreload This should be 1 if we need to reload this module and 0
00166  *        otherwise.  This function will only return modules that are reloadble
00167  *        if this is 1.
00168  *
00169  * \retval A possible completion of the partial match.
00170  * \retval NULL if no matches were found.
00171  */
00172 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
00173 
00174 /* Opaque type for module handles generated by the loader */
00175 
00176 struct ast_module;
00177 
00178 /*!
00179  * \brief Get the name of a module.
00180  * \param mod A pointer to the module.
00181  * \return the name of the module
00182  * \retval NULL if mod or mod->info is NULL
00183  */
00184 const char *ast_module_name(const struct ast_module *mod);
00185 
00186 /* User count routines keep track of which channels are using a given module
00187    resource.  They can help make removing modules safer, particularly if
00188    they're in use at the time they have been requested to be removed */
00189 
00190 struct ast_module_user;
00191 struct ast_module_user_list;
00192 
00193 /*! \page ModMngmnt The Asterisk Module management interface
00194  *
00195  * All modules must implement the module API (load, unload...)
00196  */
00197 
00198 enum ast_module_flags {
00199    AST_MODFLAG_DEFAULT = 0,
00200    AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
00201    AST_MODFLAG_LOAD_ORDER = (1 << 1),
00202 };
00203 
00204 enum ast_module_load_priority {
00205    AST_MODPRI_REALTIME_DEPEND =    10,  /*!< Dependency for a realtime driver */
00206    AST_MODPRI_REALTIME_DEPEND2 =   20,  /*!< Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl) */
00207    AST_MODPRI_REALTIME_DRIVER =    30,  /*!< A realtime driver, which provides configuration services for other modules */
00208    AST_MODPRI_TIMING =             40,  /*!< Dependency for a channel (MOH needs timing interfaces to be fully loaded) */
00209    AST_MODPRI_CHANNEL_DEPEND =     50,  /*!< Channel driver dependency (may depend upon realtime, e.g. MOH) */
00210    AST_MODPRI_CHANNEL_DRIVER =     60,  /*!< Channel drivers (provide devicestate) */
00211    AST_MODPRI_APP_DEPEND =         70,  /*!< Dependency for an application */
00212    AST_MODPRI_DEVSTATE_PROVIDER =  80,  /*!< Applications and other modules that _provide_ devicestate (e.g. meetme) */
00213    AST_MODPRI_DEVSTATE_PLUGIN =    90,  /*!< Plugin for a module that provides devstate (e.g. res_calendar_*) */
00214    AST_MODPRI_CDR_DRIVER =        100,  /*!< CDR or CEL backend */
00215    AST_MODPRI_DEFAULT =           128,  /*!< Modules not otherwise defined (such as most apps) will load here */
00216    AST_MODPRI_DEVSTATE_CONSUMER = 150,  /*!< Certain modules, which consume devstate, need to load after all others (e.g. app_queue) */
00217 };
00218 
00219 struct ast_module_info {
00220 
00221    /*!
00222     * The 'self' pointer for a module; it will be set by the loader before
00223     * it calls the module's load_module() entrypoint, and used by various
00224     * other macros that need to identify the module.
00225     */
00226 
00227    struct ast_module *self;
00228    enum ast_module_load_result (*load)(void);   /*!< register stuff etc. Optional. */
00229    int (*reload)(void);       /*!< config etc. Optional. */
00230    int (*unload)(void);       /*!< unload. called with the module locked */
00231    int (*backup_globals)(void);     /*!< for embedded modules, backup global data */
00232    void (*restore_globals)(void);      /*!< for embedded modules, restore global data */
00233    const char *name;       /*!< name of the module for loader reference and CLI commands */
00234    const char *description;      /*!< user friendly description of the module. */
00235 
00236    /*! 
00237     * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
00238     * the Asterisk license as stated in the ASTERISK_GPL_KEY.  Your module will not
00239     * load if it does not return the EXACT key string.
00240     */
00241 
00242    const char *key;
00243    unsigned int flags;
00244 
00245    /*! The value of AST_BUILDOPT_SUM when this module was compiled */
00246    const char buildopt_sum[33];
00247 
00248    /*! This value represents the order in which a module's load() function is initialized.
00249     *  The lower this value, the higher the priority.  The value is only checked if the
00250     *  AST_MODFLAG_LOAD_ORDER flag is set.  If the AST_MODFLAG_LOAD_ORDER flag is not set,
00251     *  this value will never be read and the module will be given the lowest possible priority
00252     *  on load. */
00253    unsigned char load_pri;
00254 
00255    /*! Modules which should be loaded first, in comma-separated string format.
00256     * These are only required for loading, when the optional_api header file
00257     * detects that the compiler does not support the optional API featureset. */
00258    const char *nonoptreq;
00259 };
00260 
00261 void ast_module_register(const struct ast_module_info *);
00262 void ast_module_unregister(const struct ast_module_info *);
00263 
00264 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
00265 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
00266 void __ast_module_user_hangup_all(struct ast_module *);
00267 
00268 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
00269 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
00270 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
00271 
00272 struct ast_module *ast_module_ref(struct ast_module *);
00273 void ast_module_unref(struct ast_module *);
00274 
00275 #if defined(__cplusplus) || defined(c_plusplus)
00276 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func, load_pri) \
00277    static struct ast_module_info __mod_info = { \
00278       NULL,             \
00279       load_func,           \
00280       reload_func,            \
00281       unload_func,            \
00282       NULL,             \
00283       NULL,             \
00284       AST_MODULE,          \
00285       desc,             \
00286       keystr,              \
00287       flags_to_set,           \
00288       AST_BUILDOPT_SUM,       \
00289       load_pri,           \
00290    };                \
00291    static void  __attribute__((constructor)) __reg_module(void) \
00292    { \
00293       ast_module_register(&__mod_info); \
00294    } \
00295    static void  __attribute__((destructor)) __unreg_module(void) \
00296    { \
00297       ast_module_unregister(&__mod_info); \
00298    } \
00299    static const __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
00300 
00301 #define AST_MODULE_INFO_STANDARD(keystr, desc)     \
00302    AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
00303          load_module,         \
00304          unload_module,    \
00305          NULL,       \
00306          AST_MODPRI_DEFAULT \
00307              )
00308 #else /* plain C */
00309 
00310 /* forward declare this pointer in modules, so that macro/function
00311    calls that need it can get it, since it will actually be declared
00312    and populated at the end of the module's source file... */
00313 static const __attribute__((unused)) struct ast_module_info *ast_module_info;
00314 
00315 #if !defined(EMBEDDED_MODULE)
00316 #define __MODULE_INFO_SECTION
00317 #define __MODULE_INFO_GLOBALS
00318 #else
00319 /*
00320  * For embedded modules we need additional information to backup and
00321  * restore the global variables in the module itself, so we can unload
00322  * reload the module.
00323  * EMBEDDED_MODULE is defined as the module name, so the calls to make_var()
00324  * below will actually define different symbols for each module.
00325  */
00326 #define __MODULE_INFO_SECTION __attribute__((section(".embed_module")))
00327 #define __MODULE_INFO_GLOBALS .backup_globals = __backup_globals, .restore_globals = __restore_globals,
00328 
00329 #define make_var_sub(mod, type) __ ## mod ## _ ## type
00330 #define make_var(mod, type) make_var_sub(mod, type)
00331 
00332 extern void make_var(EMBEDDED_MODULE, bss_start);
00333 extern void make_var(EMBEDDED_MODULE, bss_end);
00334 extern void make_var(EMBEDDED_MODULE, data_start);
00335 extern void make_var(EMBEDDED_MODULE, data_end);
00336 
00337 static void * __attribute__((section(".embed_module"))) __global_backup;
00338 
00339 static int __backup_globals(void)
00340 {
00341    size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
00342 
00343    if (__global_backup)
00344       return 0;
00345 
00346    if (!data_size)
00347       return 0;
00348 
00349    if (!(__global_backup = ast_malloc(data_size)))
00350       return -1;
00351 
00352    memcpy(__global_backup, & make_var(EMBEDDED_MODULE, data_start), data_size);
00353 
00354    return 0;
00355 }
00356 
00357 static void __restore_globals(void)
00358 {
00359    size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
00360    size_t bss_size = & make_var(EMBEDDED_MODULE, bss_end) - & make_var(EMBEDDED_MODULE, bss_start);
00361 
00362    if (bss_size)
00363       memset(& make_var(EMBEDDED_MODULE, bss_start), 0, bss_size);
00364 
00365    if (!data_size || !__global_backup)
00366       return;
00367 
00368    memcpy(& make_var(EMBEDDED_MODULE, data_start), __global_backup, data_size);
00369 }
00370 #undef make_var
00371 #undef make_var_sub
00372 #endif /* EMBEDDED_MODULE */
00373 
00374 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...) \
00375    static struct ast_module_info             \
00376       __MODULE_INFO_SECTION            \
00377       __mod_info = {             \
00378       __MODULE_INFO_GLOBALS            \
00379       .name = AST_MODULE,           \
00380       .flags = flags_to_set,           \
00381       .description = desc,          \
00382       .key = keystr,             \
00383       .buildopt_sum = AST_BUILDOPT_SUM,      \
00384       fields                  \
00385    };                   \
00386    static void  __attribute__((constructor)) __reg_module(void) \
00387    { \
00388       ast_module_register(&__mod_info); \
00389    } \
00390    static void  __attribute__((destructor)) __unreg_module(void) \
00391    { \
00392       ast_module_unregister(&__mod_info); \
00393    } \
00394    static const struct ast_module_info *ast_module_info = &__mod_info
00395 
00396 #define AST_MODULE_INFO_STANDARD(keystr, desc)     \
00397    AST_MODULE_INFO(keystr, AST_MODFLAG_LOAD_ORDER, desc, \
00398          .load = load_module,       \
00399          .unload = unload_module,      \
00400          .load_pri = AST_MODPRI_DEFAULT, \
00401              )
00402 #endif   /* plain C */
00403 
00404 /*! 
00405  * \brief Register an application.
00406  *
00407  * \param app Short name of the application
00408  * \param execute a function callback to execute the application. It should return
00409  *                non-zero if the channel needs to be hung up.
00410  * \param synopsis a short description (one line synopsis) of the application
00411  * \param description long description with all of the details about the use of 
00412  *                    the application
00413  * 
00414  * This registers an application with Asterisk's internal application list. 
00415  * \note The individual applications themselves are responsible for registering and unregistering
00416  *       and unregistering their own CLI commands.
00417  * 
00418  * \retval 0 success 
00419  * \retval -1 failure.
00420  */
00421 #define ast_register_application(app, execute, synopsis, description) ast_register_application2(app, execute, synopsis, description, ast_module_info->self)
00422 
00423 /*! 
00424  * \brief Register an application using XML documentation.
00425  *
00426  * \param app Short name of the application
00427  * \param execute a function callback to execute the application. It should return
00428  *                non-zero if the channel needs to be hung up.
00429  * 
00430  * This registers an application with Asterisk's internal application list. 
00431  * \note The individual applications themselves are responsible for registering and unregistering
00432  *       and unregistering their own CLI commands.
00433  * 
00434  * \retval 0 success 
00435  * \retval -1 failure.
00436  */
00437 #define ast_register_application_xml(app, execute) ast_register_application(app, execute, NULL, NULL)
00438 
00439 
00440 /*!
00441  * \brief Register an application.
00442  *
00443  * \param app Short name of the application
00444  * \param execute a function callback to execute the application. It should return
00445  *                non-zero if the channel needs to be hung up.
00446  * \param synopsis a short description (one line synopsis) of the application
00447  * \param description long description with all of the details about the use of
00448  *                    the application
00449  * \param mod module this application belongs to
00450  *
00451  * This registers an application with Asterisk's internal application list.
00452  * \note The individual applications themselves are responsible for registering and unregistering
00453  *       and unregistering their own CLI commands.
00454  *
00455  * \retval 0 success
00456  * \retval -1 failure.
00457  */
00458 int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *),
00459                  const char *synopsis, const char *description, void *mod);
00460 
00461 /*! 
00462  * \brief Unregister an application
00463  * 
00464  * \param app name of the application (does not have to be the same string as the one that was registered)
00465  * 
00466  * This unregisters an application from Asterisk's internal application list.
00467  * 
00468  * \retval 0 success 
00469  * \retval -1 failure
00470  */
00471 int ast_unregister_application(const char *app);
00472 
00473 
00474 #if defined(__cplusplus) || defined(c_plusplus)
00475 }
00476 #endif
00477 
00478 #endif /* _ASTERISK_MODULE_H */

Generated on Thu Oct 11 06:33:50 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6