Asterisk.org: Developer Documentation (28 Oct 2009)

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 */