From 277e550a0788f8a4c2297a54a05e5402d9b8704f Mon Sep 17 00:00:00 2001 From: Mark Spencer Date: Thu, 1 Nov 2001 20:00:54 +0000 Subject: Version 0.1.10 from FTP git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@383 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/module.h | 106 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 15 deletions(-) (limited to 'include') diff --git a/include/asterisk/module.h b/include/asterisk/module.h index 59689ba0b..214e38f02 100755 --- a/include/asterisk/module.h +++ b/include/asterisk/module.h @@ -20,14 +20,51 @@ extern "C" { /* Every module must provide these functions */ -int load_module(void); /* Initialize the module */ -int unload_module(void); /* Cleanup all module structures, - sockets, etc */ -int usecount(void); /* How many channels provided by this module are in use? */ -char *description(void); /* Description of this module */ -char *key(void); /* Return the below mentioned key, unmodified */ +//! Initialize the module +/*! + * This function is called at module load time. Put all code in here + * that needs to set up your module's hardware, software, registrations, + * etc. + */ +int load_module(void); -int reload(void); /* reload configs */ +//! Cleanup all module structures, sockets, etc +/*! + * This is called at exit. Any registrations and memory allocations need + * to be unregistered and free'd here. Nothing else will do these for you (until exit). + * Return 0 on success, or other than 0 if there is a problem. + */ +int unload_module(void); + +//! Provides a usecount +/*! + * This function will be called by various parts of asterisk. Basically, all it has + * to do is to return a usecount when called. You will need to maintain your usecount + * within the module somewhere. + */ +int usecount(void); /*! How many channels provided by this module are in use? */ + +//! Description +/*! + * Returns a short description of your module. + */ +char *description(void); /*! Description of this module */ + +//! Returns the ASTERISK_GPL_KEY +/*! + * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of + * the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does + * not return the EXACT message, i.e. char *key(void){return ASTERISK_GPL_KEY;} + */ +char *key(void); /*! Return the below mentioned key, unmodified */ + +//! Reload stuff +/*! + * This function is where any reload routines take place. Re-read config files, + * change signalling, whatever is appropriate on a reload. + * Return 0 on success, and other than 0 on problem. + */ +int reload(void); /*! reload configs */ #define ASTERISK_GPL_KEY \ "This paragraph is Copyright (C) 2000, Linux Support Services, Inc. \ @@ -37,31 +74,70 @@ the GNU General Public License version 2 or later (at your option). Linux \ Support Services, Inc. reserves the right to allow other parties to license \ this paragraph under other terms as well." -#define AST_MODULE_CONFIG "modules.conf" /* Module configuration file */ +#define AST_MODULE_CONFIG "modules.conf" /*! Module configuration file */ #define AST_FORCE_SOFT 0 #define AST_FORCE_FIRM 1 #define AST_FORCE_HARD 2 -/* Load a module */ +//! Loads a module +/*! + * \param resource_name the filename of the module to load + * This function is ran by the PBX to load the modules. It performs + * all loading, setting up of it's module related data structures, etc. + * Basically, to load a module, you just give it the name of the module and + * it will do the rest. + * It returns 0 on success, -1 on error + */ int ast_load_resource(char *resource_name); -/* Unload a module. Force unloading a module is not recommended. */ +//! Unloads a module +/*! + * \param resourcename the name of the module to unload + * \param force the force flag. Setting this to non-zero will force the module to be unloaded + * This function unloads a particular module. If the force flag is not set, + * it will not unload a module with a usecount > 0. However, if it is set, + * it will unload the module regardless of consequences (NOT_RECOMMENDED) + */ int ast_unload_resource(char *resource_name, int force); -/* Notify when usecount has been changed */ +//! Notify when usecount has been changed +/*! + * This function goes through and calulates use counts. It also notifies anybody + * trying to keep track of them. + */ void ast_update_use_count(void); -/* Ask for a list of modules, descriptions, and use counts */ +//! Ask for a list of modules, descriptions, and use counts +/*! + * \param modentry a callback to an updater function + * For each of the modules loaded, modentry will be executed with the resource, description, + * and usecount values of each particular module. + */ int ast_update_module_list(int (*modentry)(char *module, char *description, int usecnt)); -/* Ask this procedure to be run with modules have been updated */ +//! Ask this procedure to be run with modules have been updated +/*! + * \param updater the function to run when modules have been updated + * This function adds the given function to a linked list of functions to be run + * when the modules are updated. + * It returns 0 on success and -1 on failure. + */ int ast_loader_register(int (*updater)(void)); -/* No longer run me when modules are updated */ +//! No longer run me when modules are updated +/*! + * \param updater function to unregister + * This removes the given function from the updater list. + * It returns 0 on success, -1 on failure. + */ int ast_loader_unregister(int (*updater)(void)); -/* Reload all modules */ +//! Reload all modules +/*! + * This reloads all modules set to load in asterisk. It does NOT run the unload + * routine and then loads them again, it runs the given reload routine. + */ void ast_module_reload(void); /* Local user routines keep track of which channels are using a given module resource. -- cgit v1.2.3