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

module.h File Reference

This graph shows which files directly or indirectly include this file:

Included by dependency graph

Go to the source code of this file.

Defines

#define ASTERISK_GPL_KEY   "This paragraph is Copyright (C) 2000, Linux Support Services, Inc. \In order for your module to load, it must return this key via a function \called \"key\". Any code which includes this paragraph must be licensed under \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_FORCE_SOFT   0
#define AST_FORCE_FIRM   1
#define AST_FORCE_HARD   2
#define STANDARD_LOCAL_USER
#define LOCAL_USER_DECL
#define LOCAL_USER_ADD(u)
#define LOCAL_USER_REMOVE(u)
#define STANDARD_HANGUP_LOCALUSERS
#define STANDARD_USECOUNT(res)

Functions

int load_module (void)
 Initialize the module.

int unload_module (void)
 Cleanup all module structures, sockets, etc.

int usecount (void)
 Provides a usecount.

char * description (void)
 Description.

char * key (void)
 Returns the ASTERISK_GPL_KEY.

int reload (void)
 Reload stuff.

int ast_load_resource (char *resource_name)
 Loads a module.

int ast_unload_resource (char *resource_name, int force)
 Unloads a module.

void ast_update_use_count (void)
 Notify when usecount has been changed.

int ast_update_module_list (int(*modentry)(char *module, char *description, int usecnt))
 Ask for a list of modules, descriptions, and use counts.

int ast_loader_register (int(*updater)(void))
 Ask this procedure to be run with modules have been updated.

int ast_loader_unregister (int(*updater)(void))
 No longer run me when modules are updated.

void ast_module_reload (void)
 Reload all modules.

int ast_register_atexit (void(*func)(void))
void ast_unregister_atexit (void(*func)(void))

Define Documentation

#define AST_FORCE_FIRM   1
 

Definition at line 80 of file module.h.

Referenced by ast_unload_resource().

#define AST_FORCE_HARD   2
 

Definition at line 81 of file module.h.

#define AST_FORCE_SOFT   0
 

Definition at line 79 of file module.h.

#define AST_MODULE_CONFIG   "modules.conf" /*! Module configuration file */
 

Definition at line 77 of file module.h.

Referenced by ast_load_resource(), and load_modules().

#define ASTERISK_GPL_KEY   "This paragraph is Copyright (C) 2000, Linux Support Services, Inc. \In order for your module to load, it must return this key via a function \called \"key\". Any code which includes this paragraph must be licensed under \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."
 

reload configs

Definition at line 69 of file module.h.

#define LOCAL_USER_ADD (  u   ) 
 

Definition at line 159 of file module.h.

#define LOCAL_USER_DECL
 

Value:

AST_MUTEX_DEFINE_STATIC(localuser_lock); \
                  static struct localuser *localusers = NULL; \
                  static int localusecnt = 0;

Definition at line 155 of file module.h.

#define LOCAL_USER_REMOVE (  u   ) 
 

Definition at line 174 of file module.h.

#define STANDARD_HANGUP_LOCALUSERS
 

Definition at line 195 of file module.h.

#define STANDARD_LOCAL_USER
 

Value:

struct localuser { \
                        struct ast_channel *chan; \
                        struct localuser *next; \
                     }

Definition at line 150 of file module.h.

#define STANDARD_USECOUNT (  res   ) 
 

Value:

{ \
   ast_mutex_lock(&localuser_lock); \
   res = localusecnt; \
   ast_mutex_unlock(&localuser_lock); \
}

Definition at line 209 of file module.h.

Function Documentation

int ast_load_resource (  char *  resource_name  ) 
 

Loads a module.

Parameters:
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

Definition at line 178 of file loader.c.

References ast_config_AST_MODULE_DIR, ast_destroy(), ast_load(), ast_log(), AST_MODULE_CONFIG, ast_mutex_lock, ast_mutex_unlock, ast_true(), ast_unload_resource(), ast_update_use_count(), ast_variable_retrieve(), ast_verbose(), COLOR_BLACK, COLOR_BROWN, dlclose(), dlerror(), dlopen(), dlsym(), free, fully_booted, key(), LOG_WARNING, malloc, module::next, option_console, option_verbose, RTLD_GLOBAL, RTLD_LAZY, RTLD_NOW, term_color(), and VERBOSE_PREFIX_1.

Referenced by load_modules(). 

00179 {
00180    static char fn[256];
00181    int errors=0;
00182    int res;
00183    struct module *m;
00184    int flags=RTLD_NOW;
00185 #ifdef RTLD_GLOBAL
00186    char *val;
00187 #endif
00188    char *key;
00189    int o;
00190    struct ast_config *cfg;
00191    char tmp[80];
00192    /* Keep the module file parsing silent */
00193    o = option_verbose;
00194    if (strncasecmp(resource_name, "res_", 4)) {
00195       option_verbose = 0;
00196       cfg = ast_load(AST_MODULE_CONFIG);
00197       option_verbose = o;
00198       if (cfg) {
00199 #ifdef RTLD_GLOBAL
00200          if ((val = ast_variable_retrieve(cfg, "global", resource_name))
00201                && ast_true(val))
00202             flags |= RTLD_GLOBAL;
00203 #endif
00204          ast_destroy(cfg);
00205       }
00206    } else {
00207       /* Resource modules are always loaded global and lazy */
00208 #ifdef RTLD_GLOBAL
00209       flags = (RTLD_GLOBAL | RTLD_LAZY);
00210 #else
00211       flags = RTLD_LAZY;
00212 #endif
00213    }
00214    
00215    if (ast_mutex_lock(&modlock))
00216       ast_log(LOG_WARNING, "Failed to lock\n");
00217    m = module_list;
00218    while(m) {
00219       if (!strcasecmp(m->resource, resource_name)) {
00220          ast_log(LOG_WARNING, "Module '%s' already exists\n", resource_name);
00221          ast_mutex_unlock(&modlock);
00222          return -1;
00223       }
00224       m = m->next;
00225    }
00226    m = malloc(sizeof(struct module));  
00227    if (!m) {
00228       ast_log(LOG_WARNING, "Out of memory\n");
00229       ast_mutex_unlock(&modlock);
00230       return -1;
00231    }
00232    strncpy(m->resource, resource_name, sizeof(m->resource)-1);
00233    if (resource_name[0] == '/') {
00234       strncpy(fn, resource_name, sizeof(fn)-1);
00235    } else {
00236       snprintf(fn, sizeof(fn), "%s/%s", (char *)ast_config_AST_MODULE_DIR, resource_name);
00237    }
00238    m->lib = dlopen(fn, flags);
00239    if (!m->lib) {
00240       ast_log(LOG_WARNING, "%s\n", dlerror());
00241       free(m);
00242       ast_mutex_unlock(&modlock);
00243       return -1;
00244    }
00245    m->load_module = dlsym(m->lib, "load_module");
00246    if (m->load_module == NULL)
00247       m->load_module = dlsym(m->lib, "_load_module");
00248    if (!m->load_module) {
00249       ast_log(LOG_WARNING, "No load_module in module %s\n", fn);
00250       errors++;
00251    }
00252    m->unload_module = dlsym(m->lib, "unload_module");
00253    if (m->unload_module == NULL)
00254       m->unload_module = dlsym(m->lib, "_unload_module");
00255    if (!m->unload_module) {
00256       ast_log(LOG_WARNING, "No unload_module in module %s\n", fn);
00257       errors++;
00258    }
00259    m->usecount = dlsym(m->lib, "usecount");
00260    if (m->usecount == NULL)
00261       m->usecount = dlsym(m->lib, "_usecount");
00262    if (!m->usecount) {
00263       ast_log(LOG_WARNING, "No usecount in module %s\n", fn);
00264       errors++;
00265    }
00266    m->description = dlsym(m->lib, "description");
00267    if (m->description == NULL)
00268       m->description = dlsym(m->lib, "_description");
00269    if (!m->description) {
00270       ast_log(LOG_WARNING, "No description in module %s\n", fn);
00271       errors++;
00272    }
00273    m->key = dlsym(m->lib, "key");
00274    if (m->key == NULL)
00275       m->key = dlsym(m->lib, "_key");
00276    if (!m->key) {
00277       ast_log(LOG_WARNING, "No key routine in module %s\n", fn);
00278       errors++;
00279    }
00280    m->reload = dlsym(m->lib, "reload");
00281    if (m->reload == NULL)
00282       m->reload = dlsym(m->lib, "_reload");
00283    if (!m->key || !(key = m->key())) {
00284       ast_log(LOG_WARNING, "Key routine returned NULL in module %s\n", fn);
00285       key = NULL;
00286       errors++;
00287    }
00288    if (key && verify_key(key)) {
00289       ast_log(LOG_WARNING, "Unexpected key returned by module %s\n", fn);
00290       errors++;
00291    }
00292    if (errors) {
00293       ast_log(LOG_WARNING, "%d error(s) loading module %s, aborted\n", errors, fn);
00294       dlclose(m->lib);
00295       free(m);
00296       ast_mutex_unlock(&modlock);
00297       return -1;
00298    }
00299    if (!fully_booted) {
00300       if (option_verbose) 
00301          ast_verbose( " => (%s)\n", term_color(tmp, m->description(), COLOR_BROWN, COLOR_BLACK, sizeof(tmp)));
00302       if (option_console && !option_verbose)
00303          ast_verbose( ".");
00304    } else {
00305       if (option_verbose)
00306          ast_verbose(VERBOSE_PREFIX_1 "Loaded %s => (%s)\n", fn, m->description());
00307    }
00308 
00309    // add module 'm' to end of module_list chain
00310    // so reload commands will be issued in same order modules were loaded
00311    m->next = NULL;
00312    if (module_list == NULL) {
00313       // empty list so far, add at front
00314       module_list = m;
00315    }
00316    else {
00317       struct module *i;
00318       // find end of chain, and add there
00319       for (i = module_list; i->next; i = i->next)
00320          ;
00321       i->next = m;
00322    }
00323    
00324    ast_mutex_unlock(&modlock);
00325    if ((res = m->load_module())) {
00326       ast_log(LOG_WARNING, "%s: load_module failed, returning %d\n", m->resource, res);
00327       ast_unload_resource(resource_name, 0);
00328       return -1;
00329    }
00330    ast_update_use_count();
00331    return 0;
00332 }

int ast_loader_register (  int(*  updater)(void)  ) 
 

Ask this procedure to be run with modules have been updated.

Parameters:
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.

Definition at line 471 of file loader.c.

References ast_log(), ast_mutex_lock, ast_mutex_unlock, LOG_WARNING, and malloc. 

00472 {
00473    struct loadupdate *tmp;
00474    /* XXX Should be more flexible here, taking > 1 verboser XXX */
00475    if ((tmp = malloc(sizeof (struct loadupdate)))) {
00476       tmp->updater = v;
00477       if (ast_mutex_lock(&modlock))
00478          ast_log(LOG_WARNING, "Failed to lock\n");
00479       tmp->next = updaters;
00480       updaters = tmp;
00481       ast_mutex_unlock(&modlock);
00482       return 0;
00483    }
00484    return -1;
00485 }

int ast_loader_unregister (  int(*  updater)(void)  ) 
 

No longer run me when modules are updated.

Parameters:
updater function to unregister This removes the given function from the updater list. It returns 0 on success, -1 on failure.

Definition at line 487 of file loader.c.

References ast_log(), ast_mutex_lock, ast_mutex_unlock, and LOG_WARNING. 

00488 {
00489    int res = -1;
00490    struct loadupdate *tmp, *tmpl=NULL;
00491    if (ast_mutex_lock(&modlock))
00492       ast_log(LOG_WARNING, "Failed to lock\n");
00493    tmp = updaters;
00494    while(tmp) {
00495       if (tmp->updater == v)  {
00496          if (tmpl)
00497             tmpl->next = tmp->next;
00498          else
00499             updaters = tmp->next;
00500          break;
00501       }
00502       tmpl = tmp;
00503       tmp = tmp->next;
00504    }
00505    if (tmp)
00506       res = 0;
00507    ast_mutex_unlock(&modlock);
00508    return res;
00509 }

void ast_module_reload (  void   ) 
 

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.

Definition at line 149 of file loader.c.

References ast_enum_reload(), ast_lastreloadtime, ast_mutex_lock, ast_mutex_trylock, ast_mutex_unlock, ast_rtp_reload(), ast_verbose(), option_verbose, reload_manager(), and VERBOSE_PREFIX_3. 

00150 {
00151    struct module *m;
00152 
00153    /* We'll do the logger and manager the favor of calling its reload here first */
00154 
00155    if (ast_mutex_trylock(&reloadlock)) {
00156       ast_verbose("The previous reload command didn't finish yet\n");
00157       return;
00158    }
00159    reload_manager();
00160    ast_enum_reload();
00161    ast_rtp_reload();
00162    time(&ast_lastreloadtime);
00163 
00164    ast_mutex_lock(&modlock);
00165    m = module_list;
00166    while(m) {
00167       if (m->reload) {
00168          if (option_verbose > 2) 
00169             ast_verbose(VERBOSE_PREFIX_3 "Reloading module '%s' (%s)\n", m->resource, m->description());
00170          m->reload();
00171       }
00172       m = m->next;
00173    }
00174    ast_mutex_unlock(&modlock);
00175    ast_mutex_unlock(&reloadlock);
00176 }

int ast_register_atexit (  void(*  func)(void)  ) 
 

Definition at line 121 of file asterisk.c.

References ast_mutex_lock, ast_mutex_unlock, ast_unregister_atexit(), and malloc. 

00122 {
00123    int res = -1;
00124    struct ast_atexit *ae;
00125    ast_unregister_atexit(func);
00126    ae = malloc(sizeof(struct ast_atexit));
00127    ast_mutex_lock(&atexitslock);
00128    if (ae) {
00129       memset(ae, 0, sizeof(struct ast_atexit));
00130       ae->next = atexits;
00131       ae->func = func;
00132       atexits = ae;
00133       res = 0;
00134    }
00135    ast_mutex_unlock(&atexitslock);
00136    return res;
00137 }

int ast_unload_resource (  char *  resource_name,
int  force
) 
 

Unloads a module.

Parameters:
resourcename the name of the module to unload
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)

Definition at line 106 of file loader.c.

References AST_FORCE_FIRM, ast_log(), ast_mutex_lock, ast_mutex_unlock, ast_update_use_count(), dlclose(), free, LOG_WARNING, and module::next.

Referenced by ast_load_resource(). 

00107 {
00108    struct module *m, *ml = NULL;
00109    int res = -1;
00110    if (ast_mutex_lock(&modlock))
00111       ast_log(LOG_WARNING, "Failed to lock\n");
00112    m = module_list;
00113    while(m) {
00114       if (!strcasecmp(m->resource, resource_name)) {
00115          if ((res = m->usecount()) > 0)  {
00116             if (force) 
00117                ast_log(LOG_WARNING, "Warning:  Forcing removal of module %s with use count %d\n", resource_name, res);
00118             else {
00119                ast_log(LOG_WARNING, "Soft unload failed, '%s' has use count %d\n", resource_name, res);
00120                ast_mutex_unlock(&modlock);
00121                return -1;
00122             }
00123          }
00124          res = m->unload_module();
00125          if (res) {
00126             ast_log(LOG_WARNING, "Firm unload failed for %s\n", resource_name);
00127             if (force <= AST_FORCE_FIRM) {
00128                ast_mutex_unlock(&modlock);
00129                return -1;
00130             } else
00131                ast_log(LOG_WARNING, "** Dangerous **: Unloading resource anyway, at user request\n");
00132          }
00133          if (ml)
00134             ml->next = m->next;
00135          else
00136             module_list = m->next;
00137          dlclose(m->lib);
00138          free(m);
00139          break;
00140       }
00141       ml = m;
00142       m = m->next;
00143    }
00144    ast_mutex_unlock(&modlock);
00145    ast_update_use_count();
00146    return res;
00147 }

void ast_unregister_atexit (  void(*  func)(void)  ) 
 

Definition at line 139 of file asterisk.c.

References ast_mutex_lock, and ast_mutex_unlock.

Referenced by ast_register_atexit(). 

00140 {
00141    struct ast_atexit *ae, *prev = NULL;
00142    ast_mutex_lock(&atexitslock);
00143    ae = atexits;
00144    while(ae) {
00145       if (ae->func == func) {
00146          if (prev)
00147             prev->next = ae->next;
00148          else
00149             atexits = ae->next;
00150          break;
00151       }
00152       prev = ae;
00153       ae = ae->next;
00154    }
00155    ast_mutex_unlock(&atexitslock);
00156 }

int ast_update_module_list (  int(*  modentry)(char *module, char *description, int usecnt)  ) 
 

Ask for a list of modules, descriptions, and use counts.

Parameters:
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.

Definition at line 455 of file loader.c.

References ast_mutex_trylock, ast_mutex_unlock, and module::next. 

00456 {
00457    struct module *m;
00458    int unlock = -1;
00459    if (ast_mutex_trylock(&modlock))
00460       unlock = 0;
00461    m = module_list;
00462    while(m) {
00463       modentry(m->resource, m->description(), m->usecount());
00464       m = m->next;
00465    }
00466    if (unlock)
00467       ast_mutex_unlock(&modlock);
00468    return 0;
00469 }

void ast_update_use_count (  void   ) 
 

Notify when usecount has been changed.

This function goes through and calulates use counts. It also notifies anybody trying to keep track of them.

Definition at line 439 of file loader.c.

References ast_log(), ast_mutex_lock, ast_mutex_unlock, and LOG_WARNING.

Referenced by ast_load_resource(), and ast_unload_resource(). 

00440 {
00441    /* Notify any module monitors that the use count for a 
00442       resource has changed */
00443    struct loadupdate *m;
00444    if (ast_mutex_lock(&modlock))
00445       ast_log(LOG_WARNING, "Failed to lock\n");
00446    m = updaters;
00447    while(m) {
00448       m->updater();
00449       m = m->next;
00450    }
00451    ast_mutex_unlock(&modlock);
00452    
00453 }

char* description (  void   ) 
 

Description.

Returns a short description of your module.

Referenced by ast_channel_register(), ast_channel_register_ex(), ast_manager_register2(), ast_register_application(), and load_pbx().

char* key (  void   ) 
 

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;}

Referenced by ast_db_del(), ast_db_deltree(), ast_db_get(), ast_db_gettree(), ast_db_put(), ast_load_resource(), ast_privacy_check(), and ast_privacy_set().

int load_module (  void   ) 
 

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 reload (  void   ) 
 

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 unload_module (  void   ) 
 

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 usecount (  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.

Generated on Sat Jun 12 16:41:41 2004 for Asterisk by doxygen 1.3.7