Mon May 14 04:42:59 2007

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 - 2006, 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_FAILURE = -1, /*!< Module could not be loaded properly */
00065 };
00066 
00067 /*! 
00068  * \brief Load a module.
00069  * \param resource_name The name of the module to load.
00070  *
00071  * This function is run by the PBX to load the modules.  It performs
00072  * all loading and initilization tasks.   Basically, to load a module, just
00073  * give it the name of the module and it will do the rest.
00074  *
00075  * \return See possible enum values for ast_module_load_result.
00076  */
00077 enum ast_module_load_result ast_load_resource(const char *resource_name);
00078 
00079 /*! 
00080  * \brief Unload a module.
00081  * \param resource_name The name of the module to unload.
00082  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE flags.
00083  *
00084  * This function unloads a module.  It will only unload modules that are not in
00085  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
00086  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
00087  * module regardless of consequences (NOT RECOMMENDED).
00088  *
00089  * \return Zero on success, -1 on error.
00090  */
00091 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
00092 
00093 /*! 
00094  * \brief Notify when usecount has been changed.
00095  *
00096  * This function calulates use counts and notifies anyone trying to keep track
00097  * of them.  It should be called whenever your module's usecount changes.
00098  *
00099  * \note The LOCAL_USER macros take care of calling this function for you.
00100  */
00101 void ast_update_use_count(void);
00102 
00103 /*! 
00104  * \brief Ask for a list of modules, descriptions, and use counts.
00105  * \param modentry A callback to an updater function.
00106  * \param like
00107  *
00108  * For each of the modules loaded, modentry will be executed with the resource,
00109  * description, and usecount values of each particular module.
00110  * 
00111  * \return the number of modules loaded
00112  */
00113 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
00114             const char *like);
00115 
00116 /*!
00117  * \brief Check if module with the name given is loaded
00118  * \param name Module name, like "chan_sip.so"
00119  * \return 0 if false, 1 if true 
00120  */
00121 int ast_module_check(char *name);
00122 
00123 /*! 
00124  * \brief Add a procedure to be run when modules have been updated.
00125  * \param updater The function to run when modules have been updated.
00126  *
00127  * This function adds the given function to a linked list of functions to be
00128  * run when the modules are updated. 
00129  *
00130  * \return Zero on success and -1 on failure.
00131  */
00132 int ast_loader_register(int (*updater)(void));
00133 
00134 /*! 
00135  * \brief Remove a procedure to be run when modules are updated.
00136  * \param updater The updater function to unregister.
00137  *
00138  * This removes the given function from the updater list.
00139  * 
00140  * \return Zero on success, -1 on failure.
00141  */
00142 int ast_loader_unregister(int (*updater)(void));
00143 
00144 /*! 
00145  * \brief Match modules names for the Asterisk cli.
00146  * \param line Unused by this function, but this should be the line we are
00147  *        matching.
00148  * \param word The partial name to match. 
00149  * \param pos The position the word we are completing is in.
00150  * \param state The possible match to return.
00151  * \param rpos The position we should be matching.  This should be the same as
00152  *        pos.
00153  * \param needsreload This should be 1 if we need to reload this module and 0
00154  *        otherwise.  This function will only return modules that are reloadble
00155  *        if this is 1.
00156  *
00157  * \return A possible completion of the partial match, or NULL if no matches
00158  * were found.
00159  */
00160 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
00161 
00162 /* Opaque type for module handles generated by the loader */
00163 
00164 struct ast_module;
00165 
00166 /* User count routines keep track of which channels are using a given module
00167    resource.  They can help make removing modules safer, particularly if
00168    they're in use at the time they have been requested to be removed */
00169 
00170 struct ast_module_user;
00171 struct ast_module_user_list;
00172 
00173 /*! \page ModMngmnt The Asterisk Module management interface
00174  *
00175  * All modules must implement the module API (load, unload...)
00176  * whose functions are exported through fields of a "struct module_symbol";
00177  */
00178 
00179 enum ast_module_flags {
00180    AST_MODFLAG_DEFAULT = 0,
00181    AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
00182 };
00183 
00184 struct ast_module_info {
00185 
00186    /* The 'self' pointer for a module; it will be set by the loader before
00187       it calls the module's load_module() entrypoint, and used by various
00188       other macros that need to identify the module.
00189    */
00190 
00191    struct ast_module *self;
00192    enum ast_module_load_result (*load)(void);   /* register stuff etc. Optional. */
00193    int (*reload)(void);       /* config etc. Optional. */
00194    int (*unload)(void);       /* unload. called with the module locked */
00195    const char *name;       /* name of the module for loader reference and CLI commands */
00196    const char *description;      /* user friendly description of the module. */
00197 
00198    /*! 
00199     * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
00200     * the Asterisk license as stated in the ASTERISK_GPL_KEY.  Your module will not
00201     * load if it does not return the EXACT key string.
00202     */
00203 
00204    const char *key;
00205    unsigned int flags;
00206 };
00207 
00208 void ast_module_register(const struct ast_module_info *);
00209 void ast_module_unregister(const struct ast_module_info *);
00210 
00211 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
00212 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
00213 void __ast_module_user_hangup_all(struct ast_module *);
00214 
00215 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
00216 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
00217 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
00218 
00219 struct ast_module *ast_module_ref(struct ast_module *);
00220 void ast_module_unref(struct ast_module *);
00221 
00222 #if defined(__cplusplus) || defined(c_plusplus)
00223 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func)  \
00224    static struct ast_module_info __mod_info = { \
00225       NULL,             \
00226       load_func,           \
00227       unload_func,            \
00228       reload_func,            \
00229       AST_MODULE,          \
00230       desc,             \
00231       keystr,              \
00232       flags_to_set            \
00233    };                \
00234    static void  __attribute__ ((constructor)) __reg_module(void) \
00235    { \
00236       ast_module_register(&__mod_info); \
00237    } \
00238    static void  __attribute__ ((destructor)) __unreg_module(void) \
00239    { \
00240       ast_module_unregister(&__mod_info); \
00241    } \
00242    const static __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
00243 
00244 #define AST_MODULE_INFO_STANDARD(keystr, desc)     \
00245    AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc, \
00246          load_module,         \
00247          unload_module,    \
00248          NULL        \
00249              )
00250 #else
00251 /* forward declare this pointer in modules, so that macro/function
00252    calls that need it can get it, since it will actually be declared
00253    and populated at the end of the module's source file... */
00254 const static __attribute__((unused)) struct ast_module_info *ast_module_info;
00255 
00256 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...) \
00257    static struct ast_module_info __mod_info = {    \
00258       .name = AST_MODULE,           \
00259       .flags = flags_to_set,           \
00260       .description = desc,          \
00261       .key = keystr,             \
00262       fields                  \
00263    };                   \
00264    static void  __attribute__ ((constructor)) __reg_module(void) \
00265    { \
00266       ast_module_register(&__mod_info); \
00267    } \
00268    static void  __attribute__ ((destructor)) __unreg_module(void) \
00269    { \
00270       ast_module_unregister(&__mod_info); \
00271    } \
00272    const static struct ast_module_info *ast_module_info = &__mod_info
00273 
00274 #define AST_MODULE_INFO_STANDARD(keystr, desc)     \
00275    AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc, \
00276          .load = load_module,       \
00277          .unload = unload_module,      \
00278              )
00279 #endif
00280 
00281 #if defined(__cplusplus) || defined(c_plusplus)
00282 }
00283 #endif
00284 
00285 #endif /* _ASTERISK_MODULE_H */

Generated on Mon May 14 04:42:59 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1