major dialplan functions update
[asterisk/asterisk.git] / include / asterisk / module.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Asterisk module definitions.
21  *
22  * This file contains the definitons for functions Asterisk modules should
23  * provide and some other module related functions.
24  */
25
26 #ifndef _ASTERISK_MODULE_H
27 #define _ASTERISK_MODULE_H
28
29 #if defined(__cplusplus) || defined(c_plusplus)
30 extern "C" {
31 #endif
32
33 /* Every module should provide these functions */
34
35 /*! 
36  * \brief Initialize the module.
37  * 
38  * This function is called at module load time.  Put all code in here
39  * that needs to set up your module's hardware, software, registrations,
40  * etc.
41  *
42  * \return This function should return 0 on success and non-zero on failure.
43  * If the module is not loaded successfully, Asterisk will call its
44  * unload_module() function.
45  */
46 int load_module(void);
47
48 /*! 
49  * \brief Cleanup all module structures, sockets, etc.
50  *
51  * This is called at exit.  Any registrations and memory allocations need to be
52  * unregistered and free'd here.  Nothing else will do these for you (until
53  * exit).
54  *
55  * \return Zero on success, or non-zero on error.
56  */
57 int unload_module(void);
58
59 /*! 
60  * \brief Provides a usecount.
61  *
62  * This function will be called by various parts of asterisk.  Basically, all
63  * it has to do is to return a usecount when called.  You will need to maintain
64  * your usecount within the module somewhere.  The usecount should be how many
65  * channels provided by this module are in use.
66  *
67  * \return The module's usecount.
68  */
69 int usecount(void);                     /* How many channels provided by this module are in use? */
70
71 /*! \brief Provides a description of the module.
72  *
73  * \return a short description of your module
74  */
75 char *description(void);                /* Description of this module */
76
77 /*! 
78  * \brief Returns the ASTERISK_GPL_KEY
79  *
80  * This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
81  * the GPL stated in the ASTERISK_GPL_KEY.  Your module will not load if it does
82  * not return the EXACT message:
83  *
84  * \code
85  * char *key(void) {
86  *         return ASTERISK_GPL_KEY;
87  * }
88  * \endcode
89  *
90  * \return ASTERISK_GPL_KEY
91  */
92 char *key(void);                /* Return the below mentioned key, unmodified */
93
94 /*! 
95  * \brief Reload stuff.
96  *
97  * This function is where any reload routines take place.  Re-read config files,
98  * change signalling, whatever is appropriate on a reload.
99  *
100  * \return The return value is not used.
101  */
102 int reload(void);               /* reload configs */
103
104 /*! \brief The text the key() function should return. */
105 #define ASTERISK_GPL_KEY \
106         "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
107 In order for your module to load, it must return this key via a function \
108 called \"key\".  Any code which includes this paragraph must be licensed under \
109 the GNU General Public License version 2 or later (at your option).   Linux \
110 Support Services, Inc. reserves the right to allow other parties to license \
111 this paragraph under other terms as well."
112
113 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
114
115 /*! 
116  * \brief Softly unload a module.
117  *
118  * This flag signals ast_unload_resource() to unload a module only if it is not
119  * in use, according to the module's usecount.
120  */
121 #define AST_FORCE_SOFT 0
122
123 /*! 
124  * \brief Firmly unload a module.
125  *
126  * This flag signals ast_unload_resource() to attempt to unload a module even
127  * if it is in use.  It will attempt to use the module's unload_module
128  * function.
129  */
130 #define AST_FORCE_FIRM 1
131
132 /*! 
133  * \brief Unconditionally unload a module.
134  *
135  * This flag signals ast_unload_resource() to first attempt to unload a module
136  * using the module's unload_module function, then if that fails to unload the
137  * module using dlclose.  The module will be unloaded even if it is still in
138  * use.  Use of this flag is not recommended.
139  */
140 #define AST_FORCE_HARD 2
141
142 /*! 
143  * \brief Load a module.
144  * \param resource_name The filename of the module to load.
145  *
146  * This function is run by the PBX to load the modules.  It performs
147  * all loading and initilization tasks.   Basically, to load a module, just
148  * give it the name of the module and it will do the rest.
149  *
150  * \return Zero on success, -1 on error.
151  */
152 int ast_load_resource(const char *resource_name);
153
154 /*! 
155  * \brief Unloads a module.
156  * \param resource_name The name of the module to unload.
157  * \param force The force flag.  This should be set using one of the AST_FORCE*
158  *        flags.
159  *
160  * This function unloads a module.  It will only unload modules that are not in
161  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
162  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
163  * module regardless of consequences (NOT_RECOMMENDED).
164  *
165  * \return Zero on success, -1 on error.
166  */
167 int ast_unload_resource(const char *resource_name, int force);
168
169 /*! 
170  * \brief Notify when usecount has been changed.
171  *
172  * This function calulates use counts and notifies anyone trying to keep track
173  * of them.  It should be called whenever your module's usecount changes.
174  *
175  * \note The LOCAL_USER macros take care of calling this function for you.
176  */
177 void ast_update_use_count(void);
178
179 /*! 
180  * \brief Ask for a list of modules, descriptions, and use counts.
181  * \param modentry A callback to an updater function.
182  * \param like
183  *
184  * For each of the modules loaded, modentry will be executed with the resource,
185  * description, and usecount values of each particular module.
186  * 
187  * \return the number of modules loaded
188  */
189 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
190                            const char *like);
191
192 /*! 
193  * \brief Add a procedure to be run when modules have been updated.
194  * \param updater The function to run when modules have been updated.
195  *
196  * This function adds the given function to a linked list of functions to be
197  * run when the modules are updated. 
198  *
199  * \return Zero on success and -1 on failure.
200  */
201 int ast_loader_register(int (*updater)(void));
202
203 /*! 
204  * \brief Remove a procedure to be run when modules are updated.
205  * \param updater The updater function to unregister.
206  *
207  * This removes the given function from the updater list.
208  * 
209  * \return Zero on success, -1 on failure.
210  */
211 int ast_loader_unregister(int (*updater)(void));
212
213 /*! 
214  * \brief Reload asterisk modules.
215  * \param name the name of the module to reload
216  *
217  * This function reloads the specified module, or if no modules are specified,
218  * it will reload all loaded modules.
219  *
220  * \note Modules are reloaded using their reload() functions, not unloading
221  * them and loading them again.
222  *
223  * \return Zero if the specified module was not found, 1 if the module was
224  * found but cannot be reloaded, -1 if a reload operation is already in
225  * progress, and 2 if the specfied module was found and reloaded.
226  */
227 int ast_module_reload(const char *name);
228
229 /*! 
230  * \brief Match modules names for the Asterisk cli.
231  * \param line Unused by this function, but this should be the line we are
232  *        matching.
233  * \param word The partial name to match. 
234  * \param pos The position the word we are completing is in.
235  * \param state The possible match to return.
236  * \param rpos The position we should be matching.  This should be the same as
237  *        pos.
238  * \param needsreload This should be 1 if we need to reload this module and 0
239  *        otherwise.  This function will only return modules that are reloadble
240  *        if this is 1.
241  *
242  * \return A possible completion of the partial match, or NULL if no matches
243  * were found.
244  */
245 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
246
247 /*! 
248  * \brief Register a function to be executed before Asterisk exits.
249  * \param func The callback function to use.
250  *
251  * \return Zero on success, -1 on error.
252  */
253 int ast_register_atexit(void (*func)(void));
254
255 /*! 
256  * \brief Unregister a function registered with ast_register_atexit().
257  * \param func The callback function to unregister.
258  */
259 void ast_unregister_atexit(void (*func)(void));
260
261 /* Local user routines keep track of which channels are using a given module
262    resource.  They can help make removing modules safer, particularly if
263    they're in use at the time they have been requested to be removed */
264
265 /*! 
266  * \brief Standard localuser struct definition.
267  *
268  * This macro defines a localuser struct.  The channel.h file must be included
269  * to use this macro because it refrences ast_channel.
270  */
271 #define STANDARD_LOCAL_USER struct localuser { \
272                                                 struct ast_channel *chan; \
273                                                 struct localuser *next; \
274                                              }
275
276 /*! 
277  * \brief The localuser declaration.
278  *
279  * This macro should be used in combination with #STANDARD_LOCAL_USER.  It
280  * creates a localuser mutex and several other variables used for keeping the
281  * use count.
282  *
283  * <b>Sample Usage:</b>
284  * \code
285  * STANDARD_LOCAL_USER;
286  * LOCAL_USER_DECL;
287  * \endcode
288  */
289 #define LOCAL_USER_DECL AST_MUTEX_DEFINE_STATIC(localuser_lock); \
290                                                 static struct localuser *localusers = NULL; \
291                                                 static int localusecnt = 0;
292
293 #define STANDARD_USECOUNT_DECL \
294         AST_MUTEX_DEFINE_STATIC(localuser_lock); \
295         static int localusecnt = 0;     
296
297 #define STANDARD_INCREMENT_USECOUNT \
298         ast_mutex_lock(&localuser_lock); \
299         localusecnt++; \
300         ast_mutex_unlock(&localuser_lock); \
301         ast_update_use_count();
302
303 #define STANDARD_DECREMENT_USECOUNT \
304         ast_mutex_lock(&localuser_lock); \
305         localusecnt--; \
306         ast_mutex_unlock(&localuser_lock); \
307         ast_update_use_count();
308
309 /*! 
310  * \brief Add a localuser.
311  * \param u a pointer to a localuser struct
312  *
313  * This macro adds a localuser to the list of users and increments the
314  * usecount.  It expects a variable named \p chan of type \p ast_channel in the
315  * current scope.
316  *
317  * \note This function dynamically allocates memory.  If this operation fails
318  * it will cause your function to return -1 to the caller.
319  */
320 #define LOCAL_USER_ADD(u) { \
321  \
322         if (!(u=calloc(1,sizeof(*u)))) { \
323                 ast_log(LOG_WARNING, "Out of memory\n"); \
324                 return -1; \
325         } \
326         ast_mutex_lock(&localuser_lock); \
327         u->chan = chan; \
328         u->next = localusers; \
329         localusers = u; \
330         localusecnt++; \
331         ast_mutex_unlock(&localuser_lock); \
332         ast_update_use_count(); \
333 }
334
335 #define LOCAL_USER_ACF_ADD(u) { \
336  \
337         if (!(u=calloc(1,sizeof(*u)))) { \
338                 ast_log(LOG_WARNING, "Out of memory\n"); \
339                 return -1; \
340         } \
341         ast_mutex_lock(&localuser_lock); \
342         u->chan = chan; \
343         u->next = localusers; \
344         localusers = u; \
345         localusecnt++; \
346         ast_mutex_unlock(&localuser_lock); \
347         ast_update_use_count(); \
348 }
349
350 /*! 
351  * \brief Remove a localuser.
352  * \param u the user to add, should be of type struct localuser
353  *
354  * This macro removes a localuser from the list of users and decrements the
355  * usecount.
356  */
357 #define LOCAL_USER_REMOVE(u) { \
358         struct localuser *uc, *ul = NULL; \
359         ast_mutex_lock(&localuser_lock); \
360         uc = localusers; \
361         while (uc) { \
362                 if (uc == u) { \
363                         if (ul) \
364                                 ul->next = uc->next; \
365                         else \
366                                 localusers = uc->next; \
367                         break; \
368                 } \
369                 ul = uc; \
370                 uc = uc->next; \
371         }\
372         free(u); \
373         localusecnt--; \
374         ast_mutex_unlock(&localuser_lock); \
375         ast_update_use_count(); \
376 }
377
378 /*! 
379  * \brief Hangup all localusers.
380  *
381  * This macro hangs up on all current localusers and sets the usecount to zero
382  * when finished.
383  */
384 #define STANDARD_HANGUP_LOCALUSERS { \
385         struct localuser *u, *ul; \
386         ast_mutex_lock(&localuser_lock); \
387         u = localusers; \
388         while(u) { \
389                 ast_softhangup(u->chan, AST_SOFTHANGUP_APPUNLOAD); \
390                 ul = u; \
391                 u = u->next; \
392                 free(ul); \
393         } \
394         localusecnt=0; \
395         ast_mutex_unlock(&localuser_lock); \
396         ast_update_use_count(); \
397 }
398
399 /*!
400  * \brief Set the specfied integer to the current usecount.
401  * \param res the integer variable to set.
402  *
403  * This macro sets the specfied integer variable to the local usecount.
404  *
405  * <b>Sample Usage:</b>
406  * \code
407  * int usecount(void)
408  * {
409  *    int res;
410  *    STANDARD_USECOUNT(res);
411  *    return res;
412  * }
413  * \endcode
414  */
415 #define STANDARD_USECOUNT(res) { \
416         res = localusecnt; \
417 }
418         
419 #if defined(__cplusplus) || defined(c_plusplus)
420 }
421 #endif
422
423 #endif /* _ASTERISK_MODULE_H */