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