include/asterisk/module.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   3  *
   4  * Module definitions
   5  *
   6  * Copyright (C) 1999, Mark Spencer
   7  *
   8  * Mark Spencer <markster@linux-support.net>
   9  *
  10  * This program is free software, distributed under the terms of
  11  * the GNU General Public License
  12  */
  13
  14 #ifndef _ASTERISK_MODULE_H
  15 #define _ASTERISK_MODULE_H
  16
  17 #if defined(__cplusplus) || defined(c_plusplus)
  18 extern "C" {
  19 #endif
  20
  21 /* Every module must provide these functions */
  22
  23 //! Initialize the module
  24 /*!
  25  * This function is called at module load time.  Put all code in here
  26  * that needs to set up your module's hardware, software, registrations,
  27  * etc.
  28  */
  29 int load_module(void);
  30
  31 //! Cleanup all module structures, sockets, etc
  32 /*!
  33  * This is called at exit.  Any registrations and memory allocations need
  34  * to be unregistered and free'd here.  Nothing else will do these for you (until exit).
  35  * Return 0 on success, or other than 0 if there is a problem.
  36  */
  37 int unload_module(void);
  38
  39 //! Provides a usecount
  40 /*!
  41  * This function will be called by various parts of asterisk.  Basically, all it has
  42  * to do is to return a usecount when called.  You will need to maintain your usecount
  43  * within the module somewhere.
  44  */
  45 int usecount(void);                     /*! How many channels provided by this module are in use? */
  46
  47 //! Description
  48 /*!
  49  * Returns a short description of your module.
  50  */
  51 char *description(void);                /*! Description of this module */
  52
  53 //! Returns the ASTERISK_GPL_KEY
  54 /*!
  55  * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
  56  * the GPL stated in the ASTERISK_GPL_KEY.  Your module will not load if it does
  57  * not return the EXACT message, i.e.  char *key(void){return ASTERISK_GPL_KEY;}
  58  */
  59 char *key(void);                /*! Return the below mentioned key, unmodified */
  60
  61 //! Reload stuff
  62 /*!
  63  * This function is where any reload routines take place.  Re-read config files,
  64  * change signalling, whatever is appropriate on a reload.
  65  * Return 0 on success, and other than 0 on problem.
  66  */
  67 int reload(void);               /*! reload configs */
  68
  69 #define ASTERISK_GPL_KEY \
  70         "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
  71 In order for your module to load, it must return this key via a function \
  72 called \"key\".  Any code which includes this paragraph must be licensed under \
  73 the GNU General Public License version 2 or later (at your option).   Linux \
  74 Support Services, Inc. reserves the right to allow other parties to license \
  75 this paragraph under other terms as well."
  76
  77 #define AST_MODULE_CONFIG "modules.conf" /*! Module configuration file */
  78
  79 #define AST_FORCE_SOFT 0
  80 #define AST_FORCE_FIRM 1
  81 #define AST_FORCE_HARD 2
  82
  83 //! Loads a module
  84 /*!
  85  * \param resource_name the filename of the module to load
  86  * This function is ran by the PBX to load the modules.  It performs
  87  * all loading, setting up of it's module related data structures, etc.
  88  * Basically, to load a module, you just give it the name of the module and
  89  * it will do the rest.
  90  * It returns 0 on success, -1 on error
  91  */
  92 int ast_load_resource(char *resource_name);
  93
  94 //! Unloads a module
  95 /*!
  96  * \param resourcename the name of the module to unload
  97  * \param force the force flag.  Setting this to non-zero will force the module to be unloaded
  98  * This function unloads a particular module.  If the force flag is not set,
  99  * it will not unload a module with a usecount > 0.  However, if it is set,
 100  * it will unload the module regardless of consequences (NOT_RECOMMENDED)
 101  */
 102 int ast_unload_resource(char *resource_name, int force);
 103
 104 //! Notify when usecount has been changed
 105 /*!
 106  * This function goes through and calulates use counts.  It also notifies anybody
 107  * trying to keep track of them.
 108  */
 109 void ast_update_use_count(void);
 110
 111 //! Ask for a list of modules, descriptions, and use counts
 112 /*!
 113  * \param modentry a callback to an updater function
 114  * For each of the modules loaded, modentry will be executed with the resource, description,
 115  * and usecount values of each particular module.
 116  */
 117 int ast_update_module_list(int (*modentry)(char *module, char *description, int usecnt));
 118
 119 //! Ask this procedure to be run with modules have been updated
 120 /*!
 121  * \param updater the function to run when modules have been updated
 122  * This function adds the given function to a linked list of functions to be run
 123  * when the modules are updated.
 124  * It returns 0 on success and -1 on failure.
 125  */
 126 int ast_loader_register(int (*updater)(void));
 127
 128 //! No longer run me when modules are updated
 129 /*!
 130  * \param updater function to unregister
 131  * This removes the given function from the updater list.
 132  * It returns 0 on success, -1 on failure.
 133  */
 134 int ast_loader_unregister(int (*updater)(void));
 135
 136 //! Reload all modules
 137 /*!
 138  * This reloads all modules set to load in asterisk.  It does NOT run the unload
 139  * routine and then loads them again, it runs the given reload routine.
 140  */
 141 void ast_module_reload(const char *name);
 142
 143 int ast_register_atexit(void (*func)(void));
 144 void ast_unregister_atexit(void (*func)(void));
 145
 146 /* Local user routines keep track of which channels are using a given module resource.
 147    They can help make removing modules safer, particularly if they're in use at the time
 148    they have been requested to be removed */
 149
 150 #define STANDARD_LOCAL_USER struct localuser { \
 151                                                                 struct ast_channel *chan; \
 152                                                                 struct localuser *next; \
 153                                                         }
 154
 155 #define LOCAL_USER_DECL AST_MUTEX_DEFINE_STATIC(localuser_lock); \
 156                                                 static struct localuser *localusers = NULL; \
 157                                                 static int localusecnt = 0;
 158
 159 #define LOCAL_USER_ADD(u) { \
 160  \
 161         if (!(u=(struct localuser *)malloc(sizeof(struct localuser)))) { \
 162                 ast_log(LOG_WARNING, "Out of memory\n"); \
 163                 return -1; \
 164         } \
 165         ast_mutex_lock(&localuser_lock); \
 166         u->chan = chan; \
 167         u->next = localusers; \
 168         localusers = u; \
 169         localusecnt++; \
 170         ast_mutex_unlock(&localuser_lock); \
 171         ast_update_use_count(); \
 172 }
 173
 174 #define LOCAL_USER_REMOVE(u) { \
 175         struct localuser *uc, *ul = NULL; \
 176         ast_mutex_lock(&localuser_lock); \
 177         uc = localusers; \
 178         while (uc) { \
 179                 if (uc == u) { \
 180                         if (ul) \
 181                                 ul->next = uc->next; \
 182                         else \
 183                                 localusers = uc->next; \
 184                         break; \
 185                 } \
 186                 ul = uc; \
 187                 uc = uc->next; \
 188         }\
 189         free(u); \
 190         localusecnt--; \
 191         ast_mutex_unlock(&localuser_lock); \
 192         ast_update_use_count(); \
 193 }
 194
 195 #define STANDARD_HANGUP_LOCALUSERS { \
 196         struct localuser *u, *ul; \
 197         ast_mutex_lock(&localuser_lock); \
 198         u = localusers; \
 199         while(u) { \
 200                 ast_softhangup(u->chan, AST_SOFTHANGUP_APPUNLOAD); \
 201                 ul = u; \
 202                 u = u->next; \
 203                 free(ul); \
 204         } \
 205         ast_mutex_unlock(&localuser_lock); \
 206         localusecnt=0; \
 207 }
 208
 209 #define STANDARD_USECOUNT(res) { \
 210         ast_mutex_lock(&localuser_lock); \
 211         res = localusecnt; \
 212         ast_mutex_unlock(&localuser_lock); \
 213 }
 214
 215
 216
 217 #if defined(__cplusplus) || defined(c_plusplus)
 218 }
 219 #endif
 220 #endif