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