Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals

module.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- A telephony toolkit for Linux.
00003  *
00004  * Module definitions
00005  * 
00006  * Copyright (C) 1999, Mark Spencer
00007  *
00008  * Mark Spencer <markster@linux-support.net>
00009  *
00010  * This program is free software, distributed under the terms of
00011  * the GNU General Public License
00012  */
00013 
00014 #ifndef _ASTERISK_MODULE_H
00015 #define _ASTERISK_MODULE_H
00016 
00017 #if defined(__cplusplus) || defined(c_plusplus)
00018 extern "C" {
00019 #endif
00020 
00021 /* Every module must provide these functions */
00022 
00023 //! Initialize the module
00024 /*!
00025  * This function is called at module load time.  Put all code in here
00026  * that needs to set up your module's hardware, software, registrations,
00027  * etc.
00028  */
00029 int load_module(void);
00030 
00031 //! Cleanup all module structures, sockets, etc
00032 /*!
00033  * This is called at exit.  Any registrations and memory allocations need
00034  * to be unregistered and free'd here.  Nothing else will do these for you (until exit).
00035  * Return 0 on success, or other than 0 if there is a problem.
00036  */
00037 int unload_module(void);
00038 
00039 //! Provides a usecount
00040 /*!
00041  * This function will be called by various parts of asterisk.  Basically, all it has
00042  * to do is to return a usecount when called.  You will need to maintain your usecount
00043  * within the module somewhere.
00044  */
00045 int usecount(void);        /*! How many channels provided by this module are in use? */
00046 
00047 //! Description
00048 /*!
00049  * Returns a short description of your module.
00050  */
00051 char *description(void);      /*! Description of this module */
00052 
00053 //! Returns the ASTERISK_GPL_KEY
00054 /*!
00055  * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
00056  * the GPL stated in the ASTERISK_GPL_KEY.  Your module will not load if it does
00057  * not return the EXACT message, i.e.  char *key(void){return ASTERISK_GPL_KEY;}
00058  */
00059 char *key(void);     /*! Return the below mentioned key, unmodified */
00060 
00061 //! Reload stuff
00062 /*!
00063  * This function is where any reload routines take place.  Re-read config files,
00064  * change signalling, whatever is appropriate on a reload.
00065  * Return 0 on success, and other than 0 on problem.
00066  */
00067 int reload(void);    /*! reload configs */
00068 
00069 #define ASTERISK_GPL_KEY \
00070    "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
00071 In order for your module to load, it must return this key via a function \
00072 called \"key\".  Any code which includes this paragraph must be licensed under \
00073 the GNU General Public License version 2 or later (at your option).   Linux \
00074 Support Services, Inc. reserves the right to allow other parties to license \
00075 this paragraph under other terms as well."
00076 
00077 #define AST_MODULE_CONFIG "modules.conf" /*! Module configuration file */
00078 
00079 #define AST_FORCE_SOFT 0
00080 #define AST_FORCE_FIRM 1
00081 #define AST_FORCE_HARD 2
00082 
00083 //! Loads a module
00084 /*! 
00085  * \param resource_name the filename of the module to load
00086  * This function is ran by the PBX to load the modules.  It performs
00087  * all loading, setting up of it's module related data structures, etc.
00088  * Basically, to load a module, you just give it the name of the module and
00089  * it will do the rest.
00090  * It returns 0 on success, -1 on error
00091  */
00092 int ast_load_resource(char *resource_name);
00093 
00094 //! Unloads a module
00095 /*! 
00096  * \param resourcename the name of the module to unload
00097  * \param force the force flag.  Setting this to non-zero will force the module to be unloaded
00098  * This function unloads a particular module.  If the force flag is not set,
00099  * it will not unload a module with a usecount > 0.  However, if it is set,
00100  * it will unload the module regardless of consequences (NOT_RECOMMENDED)
00101  */
00102 int ast_unload_resource(char *resource_name, int force);
00103 
00104 //! Notify when usecount has been changed
00105 /*!
00106  * This function goes through and calulates use counts.  It also notifies anybody
00107  * trying to keep track of them.
00108  */
00109 void ast_update_use_count(void);
00110 
00111 //! Ask for a list of modules, descriptions, and use counts
00112 /*!
00113  * \param modentry a callback to an updater function
00114  * For each of the modules loaded, modentry will be executed with the resource, description,
00115  * and usecount values of each particular module.
00116  */
00117 int ast_update_module_list(int (*modentry)(char *module, char *description, int usecnt));
00118 
00119 //! Ask this procedure to be run with modules have been updated
00120 /*!
00121  * \param updater the function to run when modules have been updated
00122  * This function adds the given function to a linked list of functions to be run
00123  * when the modules are updated. 
00124  * It returns 0 on success and -1 on failure.
00125  */
00126 int ast_loader_register(int (*updater)(void));
00127 
00128 //! No longer run me when modules are updated
00129 /*!
00130  * \param updater function to unregister
00131  * This removes the given function from the updater list.
00132  * It returns 0 on success, -1 on failure.
00133  */
00134 int ast_loader_unregister(int (*updater)(void));
00135 
00136 //! Reload all modules
00137 /*!
00138  * This reloads all modules set to load in asterisk.  It does NOT run the unload
00139  * routine and then loads them again, it runs the given reload routine.
00140  */
00141 void ast_module_reload(const char *name);
00142 
00143 int ast_register_atexit(void (*func)(void));
00144 void ast_unregister_atexit(void (*func)(void));
00145 
00146 /* Local user routines keep track of which channels are using a given module resource.
00147    They can help make removing modules safer, particularly if they're in use at the time
00148    they have been requested to be removed */
00149 
00150 #define STANDARD_LOCAL_USER struct localuser { \
00151                         struct ast_channel *chan; \
00152                         struct localuser *next; \
00153                      }
00154 
00155 #define LOCAL_USER_DECL AST_MUTEX_DEFINE_STATIC(localuser_lock); \
00156                   static struct localuser *localusers = NULL; \
00157                   static int localusecnt = 0;
00158 
00159 #define LOCAL_USER_ADD(u) { \
00160  \
00161    if (!(u=(struct localuser *)malloc(sizeof(struct localuser)))) { \
00162       ast_log(LOG_WARNING, "Out of memory\n"); \
00163       return -1; \
00164    } \
00165    ast_mutex_lock(&localuser_lock); \
00166    u->chan = chan; \
00167    u->next = localusers; \
00168    localusers = u; \
00169    localusecnt++; \
00170    ast_mutex_unlock(&localuser_lock); \
00171    ast_update_use_count(); \
00172 }
00173 
00174 #define LOCAL_USER_REMOVE(u) { \
00175    struct localuser *uc, *ul = NULL; \
00176    ast_mutex_lock(&localuser_lock); \
00177    uc = localusers; \
00178    while (uc) { \
00179       if (uc == u) { \
00180          if (ul) \
00181             ul->next = uc->next; \
00182          else \
00183             localusers = uc->next; \
00184          break; \
00185       } \
00186       ul = uc; \
00187       uc = uc->next; \
00188    }\
00189    free(u); \
00190    localusecnt--; \
00191    ast_mutex_unlock(&localuser_lock); \
00192    ast_update_use_count(); \
00193 }
00194 
00195 #define STANDARD_HANGUP_LOCALUSERS { \
00196    struct localuser *u, *ul; \
00197    ast_mutex_lock(&localuser_lock); \
00198    u = localusers; \
00199    while(u) { \
00200       ast_softhangup(u->chan, AST_SOFTHANGUP_APPUNLOAD); \
00201       ul = u; \
00202       u = u->next; \
00203       free(ul); \
00204    } \
00205    ast_mutex_unlock(&localuser_lock); \
00206    localusecnt=0; \
00207 }
00208 
00209 #define STANDARD_USECOUNT(res) { \
00210    ast_mutex_lock(&localuser_lock); \
00211    res = localusecnt; \
00212    ast_mutex_unlock(&localuser_lock); \
00213 }
00214    
00215    
00216 
00217 #if defined(__cplusplus) || defined(c_plusplus)
00218 }
00219 #endif
00220 #endif

Generated on Thu Nov 29 22:50:23 2007 for Asterisk by  doxygen 1.4.2