Wed Oct 28 15:47:54 2009

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 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Asterisk module definitions.
00021  *
00022  * This file contains the definitons for functions Asterisk modules should
00023  * provide and some other module related functions.
00024  */
00025 
00026 #ifndef _ASTERISK_MODULE_H
00027 #define _ASTERISK_MODULE_H
00028 
00029 #if defined(__cplusplus) || defined(c_plusplus)
00030 extern "C" {
00031 #endif
00032 
00033 /* Every module should provide these functions */
00034 
00035 /*! 
00036  * \brief Initialize the module.
00037  * 
00038  * This function is called at module load time.  Put all code in here
00039  * that needs to set up your module's hardware, software, registrations,
00040  * etc.
00041  *
00042  * \return This function should return 0 on success and non-zero on failure.
00043  * If the module is not loaded successfully, Asterisk will call its
00044  * unload_module() function.
00045  */
00046 int load_module(void);
00047 
00048 /*! 
00049  * \brief Cleanup all module structures, sockets, etc.
00050  *
00051  * This is called at exit.  Any registrations and memory allocations need to be
00052  * unregistered and free'd here.  Nothing else will do these for you (until
00053  * exit).
00054  *
00055  * \return Zero on success, or non-zero on error.
00056  */
00057 int unload_module(void);
00058 
00059 /*! 
00060  * \brief Provides a usecount.
00061  *
00062  * This function will be called by various parts of asterisk.  Basically, all
00063  * it has to do is to return a usecount when called.  You will need to maintain
00064  * your usecount within the module somewhere.  The usecount should be how many
00065  * channels provided by this module are in use.
00066  *
00067  * \return The module's usecount.
00068  */
00069 int usecount(void);        /* How many channels provided by this module are in use? */
00070 
00071 /*! \brief Provides a description of the module.
00072  *
00073  * \return a short description of your module
00074  */
00075 char *description(void);      /* Description of this module */
00076 
00077 /*! 
00078  * \brief Returns the ASTERISK_GPL_KEY
00079  *
00080  * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
00081  * the GPL stated in the ASTERISK_GPL_KEY.  Your module will not load if it does
00082  * not return the EXACT message:
00083  *
00084  * \code
00085  * char *key(void) {
00086  *         return ASTERISK_GPL_KEY;
00087  * }
00088  * \endcode
00089  *
00090  * \return ASTERISK_GPL_KEY
00091  */
00092 char *key(void);     /* Return the below mentioned key, unmodified */
00093 
00094 /*! 
00095  * \brief Reload stuff.
00096  *
00097  * This function is where any reload routines take place.  Re-read config files,
00098  * change signalling, whatever is appropriate on a reload.
00099  *
00100  * \return The return value is not used.
00101  */
00102 int reload(void);    /* reload configs */
00103 
00104 /*! \brief The text the key() function should return. */
00105 #define ASTERISK_GPL_KEY \
00106    "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
00107 In order for your module to load, it must return this key via a function \
00108 called \"key\".  Any code which includes this paragraph must be licensed under \
00109 the GNU General Public License version 2 or later (at your option).   Linux \
00110 Support Services, Inc. reserves the right to allow other parties to license \
00111 this paragraph under other terms as well."
00112 
00113 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
00114 
00115 /*! 
00116  * \brief Softly unload a module.
00117  *
00118  * This flag signals ast_unload_resource() to unload a module only if it is not
00119  * in use, according to the module's usecount.
00120  */
00121 #define AST_FORCE_SOFT 0
00122 
00123 /*! 
00124  * \brief Firmly unload a module.
00125  *
00126  * This flag signals ast_unload_resource() to attempt to unload a module even
00127  * if it is in use.  It will attempt to use the module's unload_module
00128  * function.
00129  */
00130 #define AST_FORCE_FIRM 1
00131 
00132 /*! 
00133  * \brief Unconditionally unload a module.
00134  *
00135  * This flag signals ast_unload_resource() to first attempt to unload a module
00136  * using the module's unload_module function, then if that fails to unload the
00137  * module using dlclose.  The module will be unloaded even if it is still in
00138  * use.  Use of this flag is not recommended.
00139  */
00140 #define AST_FORCE_HARD 2
00141 
00142 /*! 
00143  * \brief Load a module.
00144  * \param resource_name The filename of the module to load.
00145  *
00146  * This function is run by the PBX to load the modules.  It performs
00147  * all loading and initilization tasks.   Basically, to load a module, just
00148  * give it the name of the module and it will do the rest.
00149  *
00150  * \return Zero on success, -1 on error.
00151  */
00152 int ast_load_resource(const char *resource_name);
00153 
00154 /*! 
00155  * \brief Unloads a module.
00156  * \param resource_name The name of the module to unload.
00157  * \param force The force flag.  This should be set using one of the AST_FORCE*
00158  *        flags.
00159  *
00160  * This function unloads a module.  It will only unload modules that are not in
00161  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
00162  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
00163  * module regardless of consequences (NOT_RECOMMENDED).
00164  *
00165  * \return Zero on success, -1 on error.
00166  */
00167 int ast_unload_resource(const char *resource_name, int force);
00168 
00169 /*! 
00170  * \brief Notify when usecount has been changed.
00171  *
00172  * This function calulates use counts and notifies anyone trying to keep track
00173  * of them.  It should be called whenever your module's usecount changes.
00174  *
00175  * \note The LOCAL_USER macros take care of calling this function for you.
00176  */
00177 void ast_update_use_count(void);
00178 
00179 /*! 
00180  * \brief Ask for a list of modules, descriptions, and use counts.
00181  * \param modentry A callback to an updater function.
00182  * \param like
00183  *
00184  * For each of the modules loaded, modentry will be executed with the resource,
00185  * description, and usecount values of each particular module.
00186  * 
00187  * \return the number of modules loaded
00188  */
00189 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
00190             const char *like);
00191 
00192 /*! 
00193  * \brief Add a procedure to be run when modules have been updated.
00194  * \param updater The function to run when modules have been updated.
00195  *
00196  * This function adds the given function to a linked list of functions to be
00197  * run when the modules are updated. 
00198  *
00199  * \return Zero on success and -1 on failure.
00200  */
00201 int ast_loader_register(int (*updater)(void));
00202 
00203 /*! 
00204  * \brief Remove a procedure to be run when modules are updated.
00205  * \param updater The updater function to unregister.
00206  *
00207  * This removes the given function from the updater list.
00208  * 
00209  * \return Zero on success, -1 on failure.
00210  */
00211 int ast_loader_unregister(int (*updater)(void));
00212 
00213 /*! 
00214  * \brief Reload asterisk modules.
00215  * \param name the name of the module to reload
00216  *
00217  * This function reloads the specified module, or if no modules are specified,
00218  * it will reload all loaded modules.
00219  *
00220  * \note Modules are reloaded using their reload() functions, not unloading
00221  * them and loading them again.
00222  *
00223  * \return Zero if the specified module was not found, 1 if the module was
00224  * found but cannot be reloaded, -1 if a reload operation is already in
00225  * progress, and 2 if the specfied module was found and reloaded.
00226  */
00227 int ast_module_reload(const char *name);
00228 
00229 /*! 
00230  * \brief Match modules names for the Asterisk cli.
00231  * \param line Unused by this function, but this should be the line we are
00232  *        matching.
00233  * \param word The partial name to match. 
00234  * \param pos The position the word we are completing is in.
00235  * \param state The possible match to return.
00236  * \param rpos The position we should be matching.  This should be the same as
00237  *        pos.
00238  * \param needsreload This should be 1 if we need to reload this module and 0
00239  *        otherwise.  This function will only return modules that are reloadble
00240  *        if this is 1.
00241  *
00242  * \return A possible completion of the partial match, or NULL if no matches
00243  * were found.
00244  */
00245 char *ast_module_helper(char *line, char *word, int pos, int state, int rpos, int needsreload);
00246 
00247 /*! 
00248  * \brief Register a function to be executed before Asterisk exits.
00249  * \param func The callback function to use.
00250  *
00251  * \return Zero on success, -1 on error.
00252  */
00253 int ast_register_atexit(void (*func)(void));
00254 
00255 /*! 
00256  * \brief Unregister a function registered with ast_register_atexit().
00257  * \param func The callback function to unregister.
00258  */
00259 void ast_unregister_atexit(void (*func)(void));
00260 
00261 /* Local user routines keep track of which channels are using a given module
00262    resource.  They can help make removing modules safer, particularly if
00263    they're in use at the time they have been requested to be removed */
00264 
00265 /*! 
00266  * \brief Standard localuser struct definition.
00267  *
00268  * This macro defines a localuser struct.  The channel.h file must be included
00269  * to use this macro because it refrences ast_channel.
00270  */
00271 #define STANDARD_LOCAL_USER struct localuser { \
00272                   struct ast_channel *chan; \
00273                   struct localuser *next; \
00274                     }
00275 
00276 /*! 
00277  * \brief The localuser declaration.
00278  *
00279  * This macro should be used in combination with #STANDARD_LOCAL_USER.  It
00280  * creates a localuser mutex and several other variables used for keeping the
00281  * use count.
00282  *
00283  * <b>Sample Usage:</b>
00284  * \code
00285  * STANDARD_LOCAL_USER;
00286  * LOCAL_USER_DECL;
00287  * \endcode
00288  */
00289 #define LOCAL_USER_DECL AST_MUTEX_DEFINE_STATIC(localuser_lock); \
00290                   static struct localuser *localusers = NULL; \
00291                   static int localusecnt = 0;
00292 
00293 #define STANDARD_INCREMENT_USECOUNT \
00294    ast_mutex_lock(&localuser_lock); \
00295    localusecnt++; \
00296    ast_mutex_unlock(&localuser_lock); \
00297    ast_update_use_count();
00298 
00299 #define STANDARD_DECREMENT_USECOUNT \
00300    ast_mutex_lock(&localuser_lock); \
00301    localusecnt--; \
00302    ast_mutex_unlock(&localuser_lock); \
00303    ast_update_use_count();
00304 
00305 /*! 
00306  * \brief Add a localuser.
00307  * \param u a pointer to a localuser struct
00308  *
00309  * This macro adds a localuser to the list of users and increments the
00310  * usecount.  It expects a variable named \p chan of type \p ast_channel in the
00311  * current scope.
00312  *
00313  * \note This function dynamically allocates memory.  If this operation fails
00314  * it will cause your function to return -1 to the caller.
00315  */
00316 #define LOCAL_USER_ADD(u) { \
00317  \
00318    if (!(u=calloc(1,sizeof(*u)))) { \
00319       ast_log(LOG_WARNING, "Out of memory\n"); \
00320       return -1; \
00321    } \
00322    ast_mutex_lock(&localuser_lock); \
00323    u->chan = chan; \
00324    u->next = localusers; \
00325    localusers = u; \
00326    localusecnt++; \
00327    ast_mutex_unlock(&localuser_lock); \
00328    ast_update_use_count(); \
00329 }
00330 
00331 #define LOCAL_USER_ACF_ADD(u) { \
00332  \
00333    if (!(u=calloc(1,sizeof(*u)))) { \
00334       ast_log(LOG_WARNING, "Out of memory\n"); \
00335       return ""; \
00336    } \
00337    ast_mutex_lock(&localuser_lock); \
00338    u->chan = chan; \
00339    u->next = localusers; \
00340    localusers = u; \
00341    localusecnt++; \
00342    ast_mutex_unlock(&localuser_lock); \
00343    ast_update_use_count(); \
00344 }
00345 
00346 /*! 
00347  * \brief Remove a localuser.
00348  * \param u the user to add, should be of type struct localuser
00349  *
00350  * This macro removes a localuser from the list of users and decrements the
00351  * usecount.
00352  */
00353 #define LOCAL_USER_REMOVE(u) { \
00354    struct localuser *uc, *ul = NULL; \
00355    ast_mutex_lock(&localuser_lock); \
00356    uc = localusers; \
00357    while (uc) { \
00358       if (uc == u) { \
00359          if (ul) \
00360             ul->next = uc->next; \
00361          else \
00362             localusers = uc->next; \
00363          break; \
00364       } \
00365       ul = uc; \
00366       uc = uc->next; \
00367    }\
00368    free(u); \
00369    localusecnt--; \
00370    ast_mutex_unlock(&localuser_lock); \
00371    ast_update_use_count(); \
00372 }
00373 
00374 /*! 
00375  * \brief Hangup all localusers.
00376  *
00377  * This macro hangs up on all current localusers and sets the usecount to zero
00378  * when finished.
00379  */
00380 #define STANDARD_HANGUP_LOCALUSERS { \
00381    struct localuser *u, *ul; \
00382    ast_mutex_lock(&localuser_lock); \
00383    u = localusers; \
00384    while(u) { \
00385       ast_softhangup(u->chan, AST_SOFTHANGUP_APPUNLOAD); \
00386       ul = u; \
00387       u = u->next; \
00388       free(ul); \
00389    } \
00390    localusecnt=0; \
00391    ast_mutex_unlock(&localuser_lock); \
00392    ast_update_use_count(); \
00393 }
00394 
00395 /*!
00396  * \brief Set the specfied integer to the current usecount.
00397  * \param res the integer variable to set.
00398  *
00399  * This macro sets the specfied integer variable to the local usecount.
00400  *
00401  * <b>Sample Usage:</b>
00402  * \code
00403  * int usecount(void)
00404  * {
00405  *    int res;
00406  *    STANDARD_USECOUNT(res);
00407  *    return res;
00408  * }
00409  * \endcode
00410  */
00411 #define STANDARD_USECOUNT(res) { \
00412    res = localusecnt; \
00413 }
00414    
00415 #if defined(__cplusplus) || defined(c_plusplus)
00416 }
00417 #endif
00418 
00419 #endif /* _ASTERISK_MODULE_H */

Generated on Wed Oct 28 15:47:54 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6