add support for per-module version numbers
[asterisk/asterisk.git] / 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 const char *version(void);
70
71 #define ASTERISK_GPL_KEY \
72         "This paragraph is Copyright (C) 2000, Linux Support Services, Inc.  \
73 In order for your module to load, it must return this key via a function \
74 called \"key\".  Any code which includes this paragraph must be licensed under \
75 the GNU General Public License version 2 or later (at your option).   Linux \
76 Support Services, Inc. reserves the right to allow other parties to license \
77 this paragraph under other terms as well."
78
79 #define AST_MODULE_CONFIG "modules.conf" /*! Module configuration file */
80
81 #define AST_FORCE_SOFT 0
82 #define AST_FORCE_FIRM 1
83 #define AST_FORCE_HARD 2
84
85 /*! Loads a module */
86 /*! 
87  * \param resource_name the filename of the module to load
88  * This function is ran by the PBX to load the modules.  It performs
89  * all loading, setting up of it's module related data structures, etc.
90  * Basically, to load a module, you just give it the name of the module and
91  * it will do the rest.
92  * It returns 0 on success, -1 on error
93  */
94 int ast_load_resource(const char *resource_name);
95
96 /*! Unloads a module */
97 /*! 
98  * \param resourcename the name of the module to unload
99  * \param force the force flag.  Setting this to non-zero will force the module to be unloaded
100  * This function unloads a particular module.  If the force flag is not set,
101  * it will not unload a module with a usecount > 0.  However, if it is set,
102  * it will unload the module regardless of consequences (NOT_RECOMMENDED)
103  */
104 int ast_unload_resource(const char *resource_name, int force);
105
106 /*! Notify when usecount has been changed */
107 /*!
108  * This function goes through and calulates use counts.  It also notifies anybody
109  * trying to keep track of them.
110  */
111 void ast_update_use_count(void);
112
113 /*! Ask for a list of modules, descriptions, and use counts */
114 /*!
115  * \param modentry a callback to an updater function
116  * For each of the modules loaded, modentry will be executed with the resource, description,
117  * version, and usecount values of each particular module.
118  */
119 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *version, const char *like),
120                            const char *like);
121
122 /*! Ask this procedure to be run with modules have been updated */
123 /*!
124  * \param updater the function to run when modules have been updated
125  * This function adds the given function to a linked list of functions to be run
126  * when the modules are updated. 
127  * It returns 0 on success and -1 on failure.
128  */
129 int ast_loader_register(int (*updater)(void));
130
131 /*! No longer run me when modules are updated */
132 /*!
133  * \param updater function to unregister
134  * This removes the given function from the updater list.
135  * It returns 0 on success, -1 on failure.
136  */
137 int ast_loader_unregister(int (*updater)(void));
138
139 /*! Reload all modules */
140 /*!
141  * This reloads all modules set to load in asterisk.  It does NOT run the unload
142  * routine and then loads them again, it runs the given reload routine.
143  */
144 int ast_module_reload(const char *name);
145
146 char *ast_module_helper(char *line, char *word, int pos, int state, int rpos, int needsreload);
147
148 int ast_register_atexit(void (*func)(void));
149 void ast_unregister_atexit(void (*func)(void));
150
151 /* Local user routines keep track of which channels are using a given module resource.
152    They can help make removing modules safer, particularly if they're in use at the time
153    they have been requested to be removed */
154
155 #define STANDARD_LOCAL_USER struct localuser { \
156                                                                 struct ast_channel *chan; \
157                                                                 struct localuser *next; \
158                                                         }
159
160 #define LOCAL_USER_DECL AST_MUTEX_DEFINE_STATIC(localuser_lock); \
161                                                 static struct localuser *localusers = NULL; \
162                                                 static int localusecnt = 0;
163
164 #define LOCAL_USER_ADD(u) { \
165  \
166         if (!(u=(struct localuser *)malloc(sizeof(struct localuser)))) { \
167                 ast_log(LOG_WARNING, "Out of memory\n"); \
168                 return -1; \
169         } \
170         ast_mutex_lock(&localuser_lock); \
171         u->chan = chan; \
172         u->next = localusers; \
173         localusers = u; \
174         localusecnt++; \
175         ast_mutex_unlock(&localuser_lock); \
176         ast_update_use_count(); \
177 }
178
179 #define LOCAL_USER_REMOVE(u) { \
180         struct localuser *uc, *ul = NULL; \
181         ast_mutex_lock(&localuser_lock); \
182         uc = localusers; \
183         while (uc) { \
184                 if (uc == u) { \
185                         if (ul) \
186                                 ul->next = uc->next; \
187                         else \
188                                 localusers = uc->next; \
189                         break; \
190                 } \
191                 ul = uc; \
192                 uc = uc->next; \
193         }\
194         free(u); \
195         localusecnt--; \
196         ast_mutex_unlock(&localuser_lock); \
197         ast_update_use_count(); \
198 }
199
200 #define STANDARD_HANGUP_LOCALUSERS { \
201         struct localuser *u, *ul; \
202         ast_mutex_lock(&localuser_lock); \
203         u = localusers; \
204         while(u) { \
205                 ast_softhangup(u->chan, AST_SOFTHANGUP_APPUNLOAD); \
206                 ul = u; \
207                 u = u->next; \
208                 free(ul); \
209         } \
210         ast_mutex_unlock(&localuser_lock); \
211         localusecnt=0; \
212 }
213
214 #define STANDARD_USECOUNT(res) { \
215         ast_mutex_lock(&localuser_lock); \
216         res = localusecnt; \
217         ast_mutex_unlock(&localuser_lock); \
218 }
219         
220         
221
222 #if defined(__cplusplus) || defined(c_plusplus)
223 }
224 #endif
225 #endif