Adding dialplan function IFMODULE, so you can create dialplans that handle
[asterisk/asterisk.git] / include / asterisk / module.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  * Kevin P. Fleming <kpfleming@digium.com>
8  * Luigi Rizzo <rizzo@icir.org>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20
21 /*! \file
22  * \brief Asterisk module definitions.
23  *
24  * This file contains the definitons for functions Asterisk modules should
25  * provide and some other module related functions.
26  */
27
28 #ifndef _ASTERISK_MODULE_H
29 #define _ASTERISK_MODULE_H
30
31 #include "asterisk/utils.h"
32
33 #if defined(__cplusplus) || defined(c_plusplus)
34 extern "C" {
35 #endif
36
37 /*! \brief The text the key() function should return. */
38 #define ASTERISK_GPL_KEY \
39 "This paragraph is copyright (c) 2006 by Digium, Inc. \
40 In order for your module to load, it must return this \
41 key via a function called \"key\".  Any code which \
42 includes this paragraph must be licensed under the GNU \
43 General Public License version 2 or later (at your \
44 option).  In addition to Digium's general reservations \
45 of rights, Digium expressly reserves the right to \
46 allow other parties to license this paragraph under \
47 different terms. Any use of Digium, Inc. trademarks or \
48 logos (including \"Asterisk\" or \"Digium\") without \
49 express written permission of Digium, Inc. is prohibited.\n"
50
51 #define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
52
53 enum ast_module_unload_mode {
54         AST_FORCE_SOFT = 0, /*!< Softly unload a module, only if not in use */
55         AST_FORCE_FIRM = 1, /*!< Firmly unload a module, even if in use */
56         AST_FORCE_HARD = 2, /*!< as FIRM, plus dlclose() on the module. Not recommended
57                                 as it may cause crashes */
58 };
59
60 enum ast_module_load_result {
61         AST_MODULE_LOAD_SUCCESS = 0,    /*!< Module loaded and configured */
62         AST_MODULE_LOAD_DECLINE = 1,    /*!< Module is not configured */
63         AST_MODULE_LOAD_SKIP = 2,       /*!< Module was skipped for some reason */
64         AST_MODULE_LOAD_FAILURE = -1,   /*!< Module could not be loaded properly */
65 };
66
67 /*! 
68  * \brief Load a module.
69  * \param resource_name The name of the module to load.
70  *
71  * This function is run by the PBX to load the modules.  It performs
72  * all loading and initilization tasks.   Basically, to load a module, just
73  * give it the name of the module and it will do the rest.
74  *
75  * \return See possible enum values for ast_module_load_result.
76  */
77 enum ast_module_load_result ast_load_resource(const char *resource_name);
78
79 /*! 
80  * \brief Unload a module.
81  * \param resource_name The name of the module to unload.
82  * \param ast_module_unload_mode The force flag. This should be set using one of the AST_FORCE flags.
83  *
84  * This function unloads a module.  It will only unload modules that are not in
85  * use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is 
86  * specified.  Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
87  * module regardless of consequences (NOT RECOMMENDED).
88  *
89  * \return Zero on success, -1 on error.
90  */
91 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
92
93 /*! 
94  * \brief Notify when usecount has been changed.
95  *
96  * This function calulates use counts and notifies anyone trying to keep track
97  * of them.  It should be called whenever your module's usecount changes.
98  *
99  * \note The LOCAL_USER macros take care of calling this function for you.
100  */
101 void ast_update_use_count(void);
102
103 /*! 
104  * \brief Ask for a list of modules, descriptions, and use counts.
105  * \param modentry A callback to an updater function.
106  * \param like
107  *
108  * For each of the modules loaded, modentry will be executed with the resource,
109  * description, and usecount values of each particular module.
110  * 
111  * \return the number of modules loaded
112  */
113 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
114                            const char *like);
115
116 /*!
117  * \brief Check if module with the name given is loaded
118  * \param name Module name, like "chan_sip.so"
119  * \return 0 if false, 1 if true 
120  */
121 int ast_module_check(char *name);
122
123 /*! 
124  * \brief Add a procedure to be run when modules have been updated.
125  * \param updater The function to run when modules have been updated.
126  *
127  * This function adds the given function to a linked list of functions to be
128  * run when the modules are updated. 
129  *
130  * \return Zero on success and -1 on failure.
131  */
132 int ast_loader_register(int (*updater)(void));
133
134 /*! 
135  * \brief Remove a procedure to be run when modules are updated.
136  * \param updater The updater function to unregister.
137  *
138  * This removes the given function from the updater list.
139  * 
140  * \return Zero on success, -1 on failure.
141  */
142 int ast_loader_unregister(int (*updater)(void));
143
144 /*! 
145  * \brief Match modules names for the Asterisk cli.
146  * \param line Unused by this function, but this should be the line we are
147  *        matching.
148  * \param word The partial name to match. 
149  * \param pos The position the word we are completing is in.
150  * \param state The possible match to return.
151  * \param rpos The position we should be matching.  This should be the same as
152  *        pos.
153  * \param needsreload This should be 1 if we need to reload this module and 0
154  *        otherwise.  This function will only return modules that are reloadble
155  *        if this is 1.
156  *
157  * \return A possible completion of the partial match, or NULL if no matches
158  * were found.
159  */
160 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
161
162 /* Opaque type for module handles generated by the loader */
163
164 struct ast_module;
165
166 /* User count routines keep track of which channels are using a given module
167    resource.  They can help make removing modules safer, particularly if
168    they're in use at the time they have been requested to be removed */
169
170 struct ast_module_user;
171 struct ast_module_user_list;
172
173 /*! \page ModMngmnt The Asterisk Module management interface
174  *
175  * All modules must implement the module API (load, unload...)
176  * whose functions are exported through fields of a "struct module_symbol";
177  */
178
179 enum ast_module_flags {
180         AST_MODFLAG_DEFAULT = 0,
181         AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
182 };
183
184 struct ast_module_info {
185
186         /* The 'self' pointer for a module; it will be set by the loader before
187            it calls the module's load_module() entrypoint, and used by various
188            other macros that need to identify the module.
189         */
190
191         struct ast_module *self;
192         enum ast_module_load_result (*load)(void);      /* register stuff etc. Optional. */
193         int (*reload)(void);                    /* config etc. Optional. */
194         int (*unload)(void);                    /* unload. called with the module locked */
195         const char *name;                       /* name of the module for loader reference and CLI commands */
196         const char *description;                /* user friendly description of the module. */
197
198         /*! 
199          * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
200          * the Asterisk license as stated in the ASTERISK_GPL_KEY.  Your module will not
201          * load if it does not return the EXACT key string.
202          */
203
204         const char *key;
205         unsigned int flags;
206 };
207
208 void ast_module_register(const struct ast_module_info *);
209 void ast_module_unregister(const struct ast_module_info *);
210
211 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
212 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
213 void __ast_module_user_hangup_all(struct ast_module *);
214
215 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
216 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
217 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
218
219 struct ast_module *ast_module_ref(struct ast_module *);
220 void ast_module_unref(struct ast_module *);
221
222 #if defined(__cplusplus) || defined(c_plusplus)
223 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func)        \
224         static struct ast_module_info __mod_info = {    \
225                 NULL,                                   \
226                 load_func,                              \
227                 unload_func,                            \
228                 reload_func,                            \
229                 AST_MODULE,                             \
230                 desc,                                   \
231                 keystr,                                 \
232                 flags_to_set                            \
233         };                                              \
234         static void  __attribute__ ((constructor)) __reg_module(void) \
235         { \
236                 ast_module_register(&__mod_info); \
237         } \
238         static void  __attribute__ ((destructor)) __unreg_module(void) \
239         { \
240                 ast_module_unregister(&__mod_info); \
241         } \
242         const static __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
243
244 #define AST_MODULE_INFO_STANDARD(keystr, desc)          \
245         AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc,      \
246                         load_module,                    \
247                         unload_module,          \
248                         NULL                    \
249                        )
250 #else
251 /* forward declare this pointer in modules, so that macro/function
252    calls that need it can get it, since it will actually be declared
253    and populated at the end of the module's source file... */
254 const static __attribute__((unused)) struct ast_module_info *ast_module_info;
255
256 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)  \
257         static struct ast_module_info __mod_info = {            \
258                 .name = AST_MODULE,                             \
259                 .flags = flags_to_set,                          \
260                 .description = desc,                            \
261                 .key = keystr,                                  \
262                 fields                                          \
263         };                                                      \
264         static void  __attribute__ ((constructor)) __reg_module(void) \
265         { \
266                 ast_module_register(&__mod_info); \
267         } \
268         static void  __attribute__ ((destructor)) __unreg_module(void) \
269         { \
270                 ast_module_unregister(&__mod_info); \
271         } \
272         const static struct ast_module_info *ast_module_info = &__mod_info
273
274 #define AST_MODULE_INFO_STANDARD(keystr, desc)          \
275         AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc,      \
276                         .load = load_module,                    \
277                         .unload = unload_module,                \
278                        )
279 #endif
280
281 #if defined(__cplusplus) || defined(c_plusplus)
282 }
283 #endif
284
285 #endif /* _ASTERISK_MODULE_H */