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  * \retval 0 on success.
  90  * \retval -1 on error.
  91  */
  92 int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
  93
  94 /*!
  95  * \brief Notify when usecount has been changed.
  96  *
  97  * This function calulates use counts and notifies anyone trying to keep track
  98  * of them.  It should be called whenever your module's usecount changes.
  99  *
 100  * \note The LOCAL_USER macros take care of calling this function for you.
 101  */
 102 void ast_update_use_count(void);
 103
 104 /*!
 105  * \brief Ask for a list of modules, descriptions, and use counts.
 106  * \param modentry A callback to an updater function.
 107  * \param like
 108  *
 109  * For each of the modules loaded, modentry will be executed with the resource,
 110  * description, and usecount values of each particular module.
 111  *
 112  * \return the number of modules loaded
 113  */
 114 int ast_update_module_list(int (*modentry)(const char *module, const char *description, int usecnt, const char *like),
 115                            const char *like);
 116
 117 /*!
 118  * \brief Check if module with the name given is loaded
 119  * \param name Module name, like "chan_sip.so"
 120  * \retval 1 if true
 121  * \retval 0 if false
 122  */
 123 int ast_module_check(const char *name);
 124
 125 /*!
 126  * \brief Add a procedure to be run when modules have been updated.
 127  * \param updater The function to run when modules have been updated.
 128  *
 129  * This function adds the given function to a linked list of functions to be
 130  * run when the modules are updated.
 131  *
 132  * \retval 0 on success
 133  * \retval -1 on failure.
 134  */
 135 int ast_loader_register(int (*updater)(void));
 136
 137 /*!
 138  * \brief Remove a procedure to be run when modules are updated.
 139  * \param updater The updater function to unregister.
 140  *
 141  * This removes the given function from the updater list.
 142  *
 143  * \retval 0 on success
 144  * \retval -1 on failure.
 145  */
 146 int ast_loader_unregister(int (*updater)(void));
 147
 148 /*!
 149  * \brief Run the unload() callback for all loaded modules
 150  *
 151  * This function should be called when Asterisk is shutting down gracefully.
 152  */
 153 void ast_module_shutdown(void);
 154
 155 /*!
 156  * \brief Match modules names for the Asterisk cli.
 157  * \param line Unused by this function, but this should be the line we are
 158  *        matching.
 159  * \param word The partial name to match.
 160  * \param pos The position the word we are completing is in.
 161  * \param state The possible match to return.
 162  * \param rpos The position we should be matching.  This should be the same as
 163  *        pos.
 164  * \param needsreload This should be 1 if we need to reload this module and 0
 165  *        otherwise.  This function will only return modules that are reloadble
 166  *        if this is 1.
 167  *
 168  * \retval A possible completion of the partial match.
 169  * \retval NULL if no matches were found.
 170  */
 171 char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
 172
 173 /* Opaque type for module handles generated by the loader */
 174
 175 struct ast_module;
 176
 177 /* User count routines keep track of which channels are using a given module
 178    resource.  They can help make removing modules safer, particularly if
 179    they're in use at the time they have been requested to be removed */
 180
 181 struct ast_module_user;
 182 struct ast_module_user_list;
 183
 184 /*! \page ModMngmnt The Asterisk Module management interface
 185  *
 186  * All modules must implement the module API (load, unload...)
 187  * whose functions are exported through fields of a "struct module_symbol";
 188  */
 189
 190 enum ast_module_flags {
 191         AST_MODFLAG_DEFAULT = 0,
 192         AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
 193 };
 194
 195 struct ast_module_info {
 196
 197         /*! The 'self' pointer for a module; it will be set by the loader before
 198            it calls the module's load_module() entrypoint, and used by various
 199            other macros that need to identify the module.
 200         */
 201
 202         struct ast_module *self;
 203         enum ast_module_load_result (*load)(void);      /*!< register stuff etc. Optional. */
 204         int (*reload)(void);                    /*!< config etc. Optional. */
 205         int (*unload)(void);                    /*!< unload. called with the module locked */
 206         int (*backup_globals)(void);            /*!< for embedded modules, backup global data */
 207         void (*restore_globals)(void);          /*!< for embedded modules, restore global data */
 208         const char *name;                       /*!< name of the module for loader reference and CLI commands */
 209         const char *description;                /*!< user friendly description of the module. */
 210
 211         /*!
 212          * This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
 213          * the Asterisk license as stated in the ASTERISK_GPL_KEY.  Your module will not
 214          * load if it does not return the EXACT key string.
 215          */
 216
 217         const char *key;
 218         unsigned int flags;
 219         unsigned int buildopt_sum[4];           /* The value of AST_BUILDOPT_SUM when this module was compiled */
 220 };
 221
 222 void ast_module_register(const struct ast_module_info *);
 223 void ast_module_unregister(const struct ast_module_info *);
 224
 225 struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
 226 void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
 227 void __ast_module_user_hangup_all(struct ast_module *);
 228
 229 #define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
 230 #define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
 231 #define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
 232
 233 struct ast_module *ast_module_ref(struct ast_module *);
 234 void ast_module_unref(struct ast_module *);
 235
 236 #if defined(__cplusplus) || defined(c_plusplus)
 237 #define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func)        \
 238         static struct ast_module_info __mod_info = {    \
 239                 NULL,                                   \
 240                 load_func,                              \
 241                 reload_func,                            \
 242                 unload_func,                            \
 243                 AST_MODULE,                             \
 244                 desc,                                   \
 245                 keystr,                                 \
 246                 flags_to_set,                           \
 247                 AST_BUILDOPT_SUM,                       \
 248         };                                              \
 249         static void  __attribute__ ((constructor)) __reg_module(void) \
 250         { \
 251                 ast_module_register(&__mod_info); \
 252         } \
 253         static void  __attribute__ ((destructor)) __unreg_module(void) \
 254         { \
 255                 ast_module_unregister(&__mod_info); \
 256         } \
 257         const static __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
 258
 259 #define AST_MODULE_INFO_STANDARD(keystr, desc)          \
 260         AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc,      \
 261                         load_module,                    \
 262                         unload_module,          \
 263                         NULL                    \
 264                        )
 265 #else
 266 /* forward declare this pointer in modules, so that macro/function
 267    calls that need it can get it, since it will actually be declared
 268    and populated at the end of the module's source file... */
 269 const static __attribute__((unused)) struct ast_module_info *ast_module_info;
 270
 271 #if defined(EMBEDDED_MODULE)
 272
 273 #define make_var_sub(mod, type) __ ## mod ## _ ## type
 274 #define make_var(mod, type) make_var_sub(mod, type)
 275
 276 extern void make_var(EMBEDDED_MODULE, bss_start);
 277 extern void make_var(EMBEDDED_MODULE, bss_end);
 278 extern void make_var(EMBEDDED_MODULE, data_start);
 279 extern void make_var(EMBEDDED_MODULE, data_end);
 280
 281 static void * __attribute__((section(".embed_module"))) __global_backup;
 282
 283 static int __backup_globals(void)
 284 {
 285         size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
 286
 287         if (__global_backup)
 288                 return 0;
 289
 290         if (!data_size)
 291                 return 0;
 292
 293         if (!(__global_backup = ast_malloc(data_size)))
 294                 return -1;
 295
 296         memcpy(__global_backup, & make_var(EMBEDDED_MODULE, data_start), data_size);
 297
 298         return 0;
 299 }
 300
 301 static void __restore_globals(void)
 302 {
 303         size_t data_size = & make_var(EMBEDDED_MODULE, data_end) - & make_var(EMBEDDED_MODULE, data_start);
 304         size_t bss_size = & make_var(EMBEDDED_MODULE, bss_end) - & make_var(EMBEDDED_MODULE, bss_start);
 305
 306         if (bss_size)
 307                 memset(& make_var(EMBEDDED_MODULE, bss_start), 0, bss_size);
 308
 309         if (!data_size || !__global_backup)
 310                 return;
 311
 312         memcpy(& make_var(EMBEDDED_MODULE, data_start), __global_backup, data_size);
 313 }
 314
 315 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)  \
 316         static struct ast_module_info                           \
 317                  __attribute__((section(".embed_module")))      \
 318                 __mod_info = {                                  \
 319                 .backup_globals = __backup_globals,             \
 320                 .restore_globals = __restore_globals,           \
 321                 .name = AST_MODULE,                             \
 322                 .flags = flags_to_set,                          \
 323                 .description = desc,                            \
 324                 .key = keystr,                                  \
 325                 fields                                          \
 326         };                                                      \
 327         static void  __attribute__ ((constructor)) __reg_module(void) \
 328         { \
 329                 ast_module_register(&__mod_info); \
 330         } \
 331         static void  __attribute__ ((destructor)) __unreg_module(void) \
 332         { \
 333                 ast_module_unregister(&__mod_info); \
 334         } \
 335         const static struct ast_module_info *ast_module_info = &__mod_info
 336
 337 #undef make_var
 338 #undef make_var_sub
 339
 340 #else /* !defined(EMBEDDED_MODULE) */
 341
 342 #define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)  \
 343         static struct ast_module_info __mod_info = {            \
 344                 .name = AST_MODULE,                             \
 345                 .flags = flags_to_set,                          \
 346                 .description = desc,                            \
 347                 .key = keystr,                                  \
 348                 .buildopt_sum = AST_BUILDOPT_SUM,               \
 349                 fields                                          \
 350         };                                                      \
 351         static void  __attribute__ ((constructor)) __reg_module(void) \
 352         { \
 353                 ast_module_register(&__mod_info); \
 354         } \
 355         static void  __attribute__ ((destructor)) __unreg_module(void) \
 356         { \
 357                 ast_module_unregister(&__mod_info); \
 358         } \
 359         const static struct ast_module_info *ast_module_info = &__mod_info
 360
 361 #endif /* !defined(EMBEDDED_MODULE) */
 362
 363 #define AST_MODULE_INFO_STANDARD(keystr, desc)          \
 364         AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc,      \
 365                         .load = load_module,                    \
 366                         .unload = unload_module,                \
 367                        )
 368 #endif
 369
 370 #if defined(__cplusplus) || defined(c_plusplus)
 371 }
 372 #endif
 373
 374 #endif /* _ASTERISK_MODULE_H */