Sat Mar 24 23:51:52 2007

Asterisk developer's documentation


module.h File Reference

Asterisk module definitions. More...

Go to the source code of this file.

Defines

#define AST_FORCE_FIRM   1
 Firmly unload a module.
#define AST_FORCE_HARD   2
 Unconditionally unload a module.
#define AST_FORCE_SOFT   0
 Softly unload a module.
#define AST_MODULE_CONFIG   "modules.conf"
 Module configuration file.
#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."
 The text the key() function should return.
#define LOCAL_USER_ACF_ADD(u)
#define LOCAL_USER_ADD(u)
 Add a localuser.
#define LOCAL_USER_DECL
 The localuser declaration.
#define LOCAL_USER_REMOVE(u)
 Remove a localuser.
#define STANDARD_DECREMENT_USECOUNT
#define STANDARD_HANGUP_LOCALUSERS
 Hangup all localusers.
#define STANDARD_INCREMENT_USECOUNT
#define STANDARD_LOCAL_USER
 Standard localuser struct definition.
#define STANDARD_USECOUNT(res)
 Set the specfied integer to the current usecount.

Functions

int ast_load_resource (const char *resource_name)
 Load a module.
int ast_loader_register (int(*updater)(void))
 Add a procedure to be run when modules have been updated.
int ast_loader_unregister (int(*updater)(void))
 Remove a procedure to be run when modules are updated.
char * ast_module_helper (char *line, char *word, int pos, int state, int rpos, int needsreload)
 Match modules names for the Asterisk cli.
int ast_module_reload (const char *name)
 Reload asterisk modules.
int ast_register_atexit (void(*func)(void))
 Register a function to be executed before Asterisk exits.
int ast_unload_resource (const char *resource_name, int force)
 Unloads a module.
void ast_unregister_atexit (void(*func)(void))
 Unregister a function registered with ast_register_atexit().
int ast_update_module_list (int(*modentry)(const char *module, const char *description, int usecnt, const char *like), const char *like)
 Ask for a list of modules, descriptions, and use counts.
void ast_update_use_count (void)
 Notify when usecount has been changed.
char * description (void)
 Provides a description of the module.
char * key (void)
 Returns the ASTERISK_GPL_KEY.
int load_module (void)
 Initialize the module.
int reload (void)
 Reload stuff.
int unload_module (void)
 Cleanup all module structures, sockets, etc.
int usecount (void)
 Provides a usecount.


Detailed Description

Asterisk module definitions.

This file contains the definitons for functions Asterisk modules should provide and some other module related functions.

Definition in file module.h.


Define Documentation

#define AST_FORCE_FIRM   1

Firmly unload a module.

This flag signals ast_unload_resource() to attempt to unload a module even if it is in use. It will attempt to use the module's unload_module function.

Definition at line 130 of file module.h.

#define AST_FORCE_HARD   2

Unconditionally unload a module.

This flag signals ast_unload_resource() to first attempt to unload a module using the module's unload_module function, then if that fails to unload the module using dlclose. The module will be unloaded even if it is still in use. Use of this flag is not recommended.

Definition at line 140 of file module.h.

#define AST_FORCE_SOFT   0

Softly unload a module.

This flag signals ast_unload_resource() to unload a module only if it is not in use, according to the module's usecount.

Definition at line 121 of file module.h.

#define LOCAL_USER_ADD (  ) 

Add a localuser.

Parameters:
u a pointer to a localuser struct
This macro adds a localuser to the list of users and increments the usecount. It expects a variable named chan of type ast_channel in the current scope.

Note:
This function dynamically allocates memory. If this operation fails it will cause your function to return -1 to the caller.

Definition at line 316 of file module.h.

#define LOCAL_USER_DECL

Value:

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

This macro should be used in combination with STANDARD_LOCAL_USER. It creates a localuser mutex and several other variables used for keeping the use count.

Sample Usage:

Definition at line 289 of file module.h.

#define LOCAL_USER_REMOVE (  ) 

Remove a localuser.

Parameters:
u the user to add, should be of type struct localuser
This macro removes a localuser from the list of users and decrements the usecount.

Definition at line 353 of file module.h.

#define STANDARD_DECREMENT_USECOUNT

Value:

ast_mutex_lock(&localuser_lock); \
   localusecnt--; \
   ast_mutex_unlock(&localuser_lock); \
   ast_update_use_count();

Definition at line 299 of file module.h.

#define STANDARD_HANGUP_LOCALUSERS

Hangup all localusers.

This macro hangs up on all current localusers and sets the usecount to zero when finished.

Definition at line 380 of file module.h.

#define STANDARD_INCREMENT_USECOUNT

Value:

ast_mutex_lock(&localuser_lock); \
   localusecnt++; \
   ast_mutex_unlock(&localuser_lock); \
   ast_update_use_count();

Definition at line 293 of file module.h.

#define STANDARD_LOCAL_USER

Value:

struct localuser { \
                  struct ast_channel *chan; \
                  struct localuser *next; \
                    }
Standard localuser struct definition.

This macro defines a localuser struct. The channel.h file must be included to use this macro because it refrences ast_channel.

Definition at line 271 of file module.h.

#define STANDARD_USECOUNT ( res   ) 

Value:

{ \
   res = localusecnt; \
}
Set the specfied integer to the current usecount.

Parameters:
res the integer variable to set.
This macro sets the specfied integer variable to the local usecount.

Sample Usage:

 int usecount(void)
 {
    int res;
    STANDARD_USECOUNT(res);
    return res;
 }

Definition at line 411 of file module.h.


Function Documentation

int ast_load_resource ( const char *  resource_name  ) 

Load a module.

Parameters:
resource_name The filename of the module to load.
This function is run by the PBX to load the modules. It performs all loading and initilization tasks. Basically, to load a module, just give it the name of the module and it will do the rest.

Returns:
Zero on success, -1 on error.

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

Add a procedure to be run when 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.

Returns:
Zero on success and -1 on failure.

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

Remove a procedure to be run when modules are updated.

Parameters:
updater The updater function to unregister.
This removes the given function from the updater list.

Returns:
Zero on success, -1 on failure.

char* ast_module_helper ( char *  line,
char *  word,
int  pos,
int  state,
int  rpos,
int  needsreload 
)

Match modules names for the Asterisk cli.

Parameters:
line Unused by this function, but this should be the line we are matching.
word The partial name to match.
pos The position the word we are completing is in.
state The possible match to return.
rpos The position we should be matching. This should be the same as pos.
needsreload This should be 1 if we need to reload this module and 0 otherwise. This function will only return modules that are reloadble if this is 1.
Returns:
A possible completion of the partial match, or NULL if no matches were found.

int ast_module_reload ( const char *  name  ) 

Reload asterisk modules.

Parameters:
name the name of the module to reload
This function reloads the specified module, or if no modules are specified, it will reload all loaded modules.

Note:
Modules are reloaded using their reload() functions, not unloading them and loading them again.
Returns:
Zero if the specified module was not found, 1 if the module was found but cannot be reloaded, -1 if a reload operation is already in progress, and 2 if the specfied module was found and reloaded.

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

Register a function to be executed before Asterisk exits.

Parameters:
func The callback function to use.
Returns:
Zero on success, -1 on error.

int ast_unload_resource ( const char *  resource_name,
int  force 
)

Unloads a module.

Parameters:
resource_name The name of the module to unload.
force The force flag. This should be set using one of the AST_FORCE* flags.
This function unloads a module. It will only unload modules that are not in use (usecount not zero), unless AST_FORCE_FIRM or AST_FORCE_HARD is specified. Setting AST_FORCE_FIRM or AST_FORCE_HARD will unload the module regardless of consequences (NOT_RECOMMENDED).

Returns:
Zero on success, -1 on error.

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

Unregister a function registered with ast_register_atexit().

Parameters:
func The callback function to unregister.

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

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

Parameters:
modentry A callback to an updater function.
like For each of the modules loaded, modentry will be executed with the resource, description, and usecount values of each particular module.
Returns:
the number of modules loaded

void ast_update_use_count ( void   ) 

Notify when usecount has been changed.

This function calulates use counts and notifies anyone trying to keep track of them. It should be called whenever your module's usecount changes.

Note:
The LOCAL_USER macros take care of calling this function for you.

char* description ( void   ) 

Provides a description of the module.

Returns:
a short description of your module

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:

 char *key(void) {
         return ASTERISK_GPL_KEY;
 }

Returns:
ASTERISK_GPL_KEY

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.

Returns:
This function should return 0 on success and non-zero on failure. If the module is not loaded successfully, Asterisk will call its unload_module() function.

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.

Returns:
The return value is not used.

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).

Returns:
Zero on success, or non-zero on error.

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. The usecount should be how many channels provided by this module are in use.

Returns:
The module's usecount.


Generated on Sat Mar 24 23:51:52 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1