Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Enumerations | Functions | Variables
module.h File Reference

Asterisk module definitions. More...

#include "asterisk/utils.h"

Go to the source code of this file.

Data Structures

struct  ast_module_info
 

Macros

#define AST_MODULE_CONFIG   "modules.conf"
 Module configuration file.
 
#define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)
 
#define AST_MODULE_INFO_STANDARD(keystr, desc)
 
#define AST_MODULE_INFO_STANDARD_DEPRECATED(keystr, desc)
 
#define AST_MODULE_INFO_STANDARD_EXTENDED(keystr, desc)
 
#define ast_module_ref(mod)    __ast_module_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Hold a reference to the module. More...
 
#define ast_module_running_ref(mod)   __ast_module_running_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Hold a reference to the module if it is running. More...
 
#define ast_module_shutdown_ref(mod)   __ast_module_shutdown_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Prevent unload of the module before shutdown. More...
 
#define ast_module_unref(mod)    __ast_module_unref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 Release a reference to the module. More...
 
#define ast_module_user_add(chan)   __ast_module_user_add(AST_MODULE_SELF, chan)
 
#define ast_module_user_hangup_all()   __ast_module_user_hangup_all(AST_MODULE_SELF)
 
#define ast_module_user_remove(user)   __ast_module_user_remove(AST_MODULE_SELF, user)
 
#define ast_register_application(app, execute, synopsis, description)   ast_register_application2(app, execute, synopsis, description, AST_MODULE_SELF)
 Register an application. More...
 
#define ast_register_application_xml(app, execute)   ast_register_application(app, execute, NULL, NULL)
 Register an application using XML documentation. More...
 
#define ASTERISK_GPL_KEY   "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n"
 The text the key() function should return.
 
#define SCOPED_MODULE_USE(module)   RAII_VAR(struct ast_module *, __self__ ## __LINE__, ast_module_ref(module), ast_module_unref)
 

Enumerations

enum  ast_module_flags { AST_MODFLAG_DEFAULT = 0, AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0), AST_MODFLAG_LOAD_ORDER = (1 << 1) }
 
enum  ast_module_helper_type {
  AST_MODULE_HELPER_LOADED = 0, AST_MODULE_HELPER_RELOAD = 1, AST_MODULE_HELPER_LOAD, AST_MODULE_HELPER_UNLOAD,
  AST_MODULE_HELPER_RUNNING
}
 
enum  ast_module_load_priority {
  AST_MODPRI_REALTIME_DEPEND = 10, AST_MODPRI_REALTIME_DEPEND2 = 20, AST_MODPRI_REALTIME_DRIVER = 30, AST_MODPRI_CORE = 40,
  AST_MODPRI_TIMING = 50, AST_MODPRI_CHANNEL_DEPEND = 60, AST_MODPRI_CHANNEL_DRIVER = 70, AST_MODPRI_APP_DEPEND = 80,
  AST_MODPRI_DEVSTATE_PROVIDER = 90, AST_MODPRI_DEVSTATE_PLUGIN = 100, AST_MODPRI_CDR_DRIVER = 110, AST_MODPRI_DEFAULT = 128,
  AST_MODPRI_DEVSTATE_CONSUMER = 150
}
 
enum  ast_module_load_result {
  AST_MODULE_LOAD_SUCCESS = 0, AST_MODULE_LOAD_DECLINE = 1, AST_MODULE_LOAD_SKIP = 2, AST_MODULE_LOAD_PRIORITY = 3,
  AST_MODULE_LOAD_FAILURE = -1
}
 
enum  ast_module_reload_result {
  AST_MODULE_RELOAD_SUCCESS = 0, AST_MODULE_RELOAD_QUEUED, AST_MODULE_RELOAD_NOT_FOUND, AST_MODULE_RELOAD_ERROR,
  AST_MODULE_RELOAD_IN_PROGRESS, AST_MODULE_RELOAD_UNINITIALIZED, AST_MODULE_RELOAD_NOT_IMPLEMENTED
}
 Possible return types for ast_module_reload. More...
 
enum  ast_module_support_level { AST_MODULE_SUPPORT_UNKNOWN, AST_MODULE_SUPPORT_CORE, AST_MODULE_SUPPORT_EXTENDED, AST_MODULE_SUPPORT_DEPRECATED }
 
enum  ast_module_unload_mode { AST_FORCE_SOFT = 0, AST_FORCE_FIRM = 1, AST_FORCE_HARD = 2 }
 

Functions

struct ast_module__ast_module_ref (struct ast_module *mod, const char *file, int line, const char *func)
 
struct ast_module__ast_module_running_ref (struct ast_module *mod, const char *file, int line, const char *func)
 
void __ast_module_shutdown_ref (struct ast_module *mod, const char *file, int line, const char *func)
 
void __ast_module_unref (struct ast_module *mod, const char *file, int line, const char *func)
 
struct ast_module_user__ast_module_user_add (struct ast_module *, struct ast_channel *)
 
void __ast_module_user_hangup_all (struct ast_module *)
 
void __ast_module_user_remove (struct ast_module *, struct ast_module_user *)
 
enum ast_module_load_result ast_load_resource (const char *resource_name)
 Load a module. More...
 
int ast_loader_register (int(*updater)(void))
 Add a procedure to be run when modules have been updated. More...
 
int ast_loader_unregister (int(*updater)(void))
 Remove a procedure to be run when modules are updated. More...
 
int ast_module_check (const char *name)
 Check if module with the name given is loaded. More...
 
char * ast_module_helper (const char *line, const char *word, int pos, int state, int rpos, enum ast_module_helper_type type)
 Match modules names for the Asterisk cli. More...
 
const char * ast_module_name (const struct ast_module *mod)
 Get the name of a module. More...
 
void ast_module_register (const struct ast_module_info *)
 
enum ast_module_reload_result ast_module_reload (const char *name)
 Reload asterisk modules. More...
 
const char * ast_module_support_level_to_string (enum ast_module_support_level support_level)
 
void ast_module_unregister (const struct ast_module_info *)
 
int ast_refresh_resource (const char *resource_name, enum ast_module_unload_mode force, int recursive)
 Unload and load a module again. More...
 
int ast_register_application2 (const char *app, int(*execute)(struct ast_channel *, const char *), const char *synopsis, const char *description, void *mod)
 Register an application. More...
 
int ast_unload_resource (const char *resource_name, enum ast_module_unload_mode)
 Unload a module. More...
 
int ast_unregister_application (const char *app)
 Unregister an application. More...
 
int ast_update_module_list (int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level), const char *like)
 Ask for a list of modules, descriptions, use counts and status. More...
 
int ast_update_module_list_condition (int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data, const char *condition), const char *like, void *data, const char *condition)
 Ask for a list of modules, descriptions, use counts and status. More...
 
int ast_update_module_list_data (int(*modentry)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data), const char *like, void *data)
 Ask for a list of modules, descriptions, use counts and status. More...
 
void ast_update_use_count (void)
 Notify when usecount has been changed. More...
 

Variables

static const struct ast_module_infoast_module_info
 

Detailed Description

Asterisk module definitions.

This file contains the definitons for functions Asterisk modules should provide and some other module related functions.

Definition in file module.h.

Macro Definition Documentation

#define ast_module_ref (   mod)    __ast_module_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Hold a reference to the module.

Parameters
modModule to reference
Returns
mod
Note
A module reference will prevent the module from being unloaded.

Definition at line 457 of file module.h.

Referenced by __ast_datastore_alloc(), ast_iax2_new(), instance_created_observer(), and newpvt().

#define ast_module_running_ref (   mod)    __ast_module_running_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Hold a reference to the module if it is running.

Parameters
modModule to reference
Return values
modif running
NULLif not running

The returned pointer should be released with ast_module_unref.

Note
A module reference will prevent the module from being unloaded.

Definition at line 469 of file module.h.

Referenced by __ast_sorcery_object_type_insert_wizard(), ast_app_exec_sub(), ast_app_expand_sub_args(), ast_cli_command_full(), ast_hook_send_action(), ast_rtp_instance_new(), ast_timer_open(), fax_session_new(), fax_session_reserve(), find_best_technology(), and process_message().

#define ast_module_shutdown_ref (   mod)    __ast_module_shutdown_ref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Prevent unload of the module before shutdown.

Parameters
modModule to hold
Note
This should not be balanced by a call to ast_module_unref.

Definition at line 478 of file module.h.

Referenced by __ast_bucket_scheme_register(), and __ast_format_interface_register().

#define ast_module_unref (   mod)    __ast_module_unref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ast_register_application (   app,
  execute,
  synopsis,
  description 
)    ast_register_application2(app, execute, synopsis, description, AST_MODULE_SELF)

Register an application.

Parameters
appShort name of the application
executea function callback to execute the application. It should return non-zero if the channel needs to be hung up.
synopsisa short description (one line synopsis) of the application
descriptionlong description with all of the details about the use of the application

This registers an application with Asterisk's internal application list.

Note
The individual applications themselves are responsible for registering and unregistering and unregistering their own CLI commands.
Return values
0success
-1failure.

Definition at line 624 of file module.h.

#define ast_register_application_xml (   app,
  execute 
)    ast_register_application(app, execute, NULL, NULL)

Register an application using XML documentation.

Parameters
appShort name of the application
executea function callback to execute the application. It should return non-zero if the channel needs to be hung up.

This registers an application with Asterisk's internal application list.

Note
The individual applications themselves are responsible for registering and unregistering and unregistering their own CLI commands.
Return values
0success
-1failure.
Examples:
app_skel.c.

Definition at line 640 of file module.h.

Referenced by load_module(), and load_parking_applications().

#define SCOPED_MODULE_USE (   module)    RAII_VAR(struct ast_module *, __self__ ## __LINE__, ast_module_ref(module), ast_module_unref)

Macro to safely ref and unref the self module for the current scope

Definition at line 679 of file module.h.

Referenced by ast_parking_blind_transfer_park(), ast_parking_is_exten_park(), ast_parking_park_bridge_channel(), and ast_parking_park_call().

Enumeration Type Documentation

Used to specify which modules should be returned by ast_module_helper.

Enumerator
AST_MODULE_HELPER_LOADED 

Modules that are loaded by dlopen.

AST_MODULE_HELPER_RELOAD 

Running modules that include a reload callback.

AST_MODULE_HELPER_LOAD 

Modules that can be loaded or started.

AST_MODULE_HELPER_UNLOAD 

Modules that can be unloaded.

AST_MODULE_HELPER_RUNNING 

Running modules

Definition at line 127 of file module.h.

127  {
128  /*! Modules that are loaded by dlopen. */
130  /*! Running modules that include a reload callback. */
132  /*! Modules that can be loaded or started. */
134  /*! Modules that can be unloaded. */
136  /*! Running modules */
138 };
Enumerator
AST_MODPRI_REALTIME_DEPEND 

Dependency for a realtime driver

AST_MODPRI_REALTIME_DEPEND2 

Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl)

AST_MODPRI_REALTIME_DRIVER 

A realtime driver, which provides configuration services for other modules

AST_MODPRI_CORE 

A core module originally meant to start between preload and load.

AST_MODPRI_TIMING 

Dependency for a channel (MOH needs timing interfaces to be fully loaded)

AST_MODPRI_CHANNEL_DEPEND 

Channel driver dependency (may depend upon realtime, e.g. MOH)

AST_MODPRI_CHANNEL_DRIVER 

Channel drivers (provide devicestate)

AST_MODPRI_APP_DEPEND 

Dependency for an application

AST_MODPRI_DEVSTATE_PROVIDER 

Applications and other modules that provide devicestate (e.g. meetme)

AST_MODPRI_DEVSTATE_PLUGIN 

Plugin for a module that provides devstate (e.g. res_calendar_*)

AST_MODPRI_CDR_DRIVER 

CDR or CEL backend

AST_MODPRI_DEFAULT 

Modules not otherwise defined (such as most apps) will load here

AST_MODPRI_DEVSTATE_CONSUMER 

Certain modules, which consume devstate, need to load after all others (e.g. app_queue)

Definition at line 334 of file module.h.

334  {
335  AST_MODPRI_REALTIME_DEPEND = 10, /*!< Dependency for a realtime driver */
336  AST_MODPRI_REALTIME_DEPEND2 = 20, /*!< Second level dependency for a realtime driver (func_curl needs res_curl, but is needed by res_config_curl) */
337  AST_MODPRI_REALTIME_DRIVER = 30, /*!< A realtime driver, which provides configuration services for other modules */
338  AST_MODPRI_CORE = 40, /*!< A core module originally meant to start between preload and load. */
339  AST_MODPRI_TIMING = 50, /*!< Dependency for a channel (MOH needs timing interfaces to be fully loaded) */
340  AST_MODPRI_CHANNEL_DEPEND = 60, /*!< Channel driver dependency (may depend upon realtime, e.g. MOH) */
341  AST_MODPRI_CHANNEL_DRIVER = 70, /*!< Channel drivers (provide devicestate) */
342  AST_MODPRI_APP_DEPEND = 80, /*!< Dependency for an application */
343  AST_MODPRI_DEVSTATE_PROVIDER = 90, /*!< Applications and other modules that _provide_ devicestate (e.g. meetme) */
344  AST_MODPRI_DEVSTATE_PLUGIN = 100, /*!< Plugin for a module that provides devstate (e.g. res_calendar_*) */
345  AST_MODPRI_CDR_DRIVER = 110, /*!< CDR or CEL backend */
346  AST_MODPRI_DEFAULT = 128, /*!< Modules not otherwise defined (such as most apps) will load here */
347  AST_MODPRI_DEVSTATE_CONSUMER = 150, /*!< Certain modules, which consume devstate, need to load after all others (e.g. app_queue) */
348 };
Enumerator
AST_MODULE_LOAD_SUCCESS 

Module is loaded and configured.

AST_MODULE_LOAD_DECLINE 

Module has failed to load, may be in an inconsistent state.

This value is used when a module fails to start but does not risk system-wide stability. Declined modules will prevent any other dependent module from starting.

AST_MODULE_LOAD_FAILURE 

Module could not be loaded properly.

This return should only be returned by modules for unrecoverable failures that cause the whole system to become unstable. In almost all cases AST_MODULE_LOAD_DECLINE should be used instead.

Warning
Returning this code from any module will cause startup to abort. If startup is already completed this code has the same effect as AST_MODULE_LOAD_DECLINE.

Definition at line 68 of file module.h.

68  {
69  /*! Module is loaded and configured. */
71  /*!
72  * \brief Module has failed to load, may be in an inconsistent state.
73  *
74  * This value is used when a module fails to start but does not risk
75  * system-wide stability. Declined modules will prevent any other
76  * dependent module from starting.
77  */
79  /*! \internal
80  * \brief Module was skipped for some reason.
81  *
82  * \note For loader.c use only. Should never be returned by modules.
83  */
84  AST_MODULE_LOAD_SKIP = 2,
85  /*! \internal
86  * \brief Module is not loaded yet, but is added to priority list.
87  *
88  * \note For loader.c use only. Should never be returned by modules.
89  */
90  AST_MODULE_LOAD_PRIORITY = 3,
91  /*!
92  * \brief Module could not be loaded properly.
93  *
94  * This return should only be returned by modules for unrecoverable
95  * failures that cause the whole system to become unstable. In almost
96  * all cases \ref AST_MODULE_LOAD_DECLINE should be used instead.
97  *
98  * \warning Returning this code from any module will cause startup to abort.
99  * If startup is already completed this code has the same effect as
100  * \ref AST_MODULE_LOAD_DECLINE.
101  */
103 };
Module could not be loaded properly.
Definition: module.h:102
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78

Possible return types for ast_module_reload.

Since
12
Enumerator
AST_MODULE_RELOAD_SUCCESS 

The module was reloaded succesfully

AST_MODULE_RELOAD_QUEUED 

The module reload request was queued

AST_MODULE_RELOAD_NOT_FOUND 

The requested module was not found

AST_MODULE_RELOAD_ERROR 

An error occurred while reloading the module

AST_MODULE_RELOAD_IN_PROGRESS 

A module reload request is already in progress

AST_MODULE_RELOAD_UNINITIALIZED 

The module has not been initialized

AST_MODULE_RELOAD_NOT_IMPLEMENTED 

This module doesn't support reloading

Definition at line 109 of file module.h.

109  {
110  AST_MODULE_RELOAD_SUCCESS = 0, /*!< The module was reloaded succesfully */
111  AST_MODULE_RELOAD_QUEUED, /*!< The module reload request was queued */
112  AST_MODULE_RELOAD_NOT_FOUND, /*!< The requested module was not found */
113  AST_MODULE_RELOAD_ERROR, /*!< An error occurred while reloading the module */
114  AST_MODULE_RELOAD_IN_PROGRESS, /*!< A module reload request is already in progress */
115  AST_MODULE_RELOAD_UNINITIALIZED, /*!< The module has not been initialized */
116  AST_MODULE_RELOAD_NOT_IMPLEMENTED, /*!< This module doesn't support reloading */
117 };
Enumerator
AST_FORCE_SOFT 

Softly unload a module, only if not in use

AST_FORCE_FIRM 

Firmly unload a module, even if in use

AST_FORCE_HARD 

as FIRM, plus dlclose() on the module. Not recommended as it may cause crashes

Definition at line 61 of file module.h.

61  {
62  AST_FORCE_SOFT = 0, /*!< Softly unload a module, only if not in use */
63  AST_FORCE_FIRM = 1, /*!< Firmly unload a module, even if in use */
64  AST_FORCE_HARD = 2, /*!< as FIRM, plus dlclose() on the module. Not recommended
65  as it may cause crashes */
66 };

Function Documentation

enum ast_module_load_result ast_load_resource ( const char *  resource_name)

Load a module.

Parameters
resource_nameThe name of the module to load.

This function is run by the PBX to load the modules. It performs all loading and initialization tasks. Basically, to load a module, just give it the name of the module and it will do the rest.

Returns
See possible enum values for ast_module_load_result.

Definition at line 1978 of file loader.c.

References ast_debug, AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, ast_test_suite_event_notify, ast_unload_resource(), ast_module::declined, and load_resource().

Referenced by ast_ari_asterisk_load_module(), ast_refresh_resource(), and auto_unload_resource().

1979 {
1980  struct ast_module *mod;
1981  enum ast_module_load_result res;
1982 
1983  /* If we're trying to load a module that previously declined to load,
1984  * transparently unload it first so we dlclose, then dlopen it afresh.
1985  * Otherwise, we won't actually load a (potentially) updated module. */
1986  mod = find_resource(resource_name, 0);
1987  if (mod && mod->flags.declined) {
1988  ast_debug(1, "Module %s previously declined to load, unloading it first before loading again\n", resource_name);
1989  ast_unload_resource(resource_name, 0);
1990  }
1991 
1993  res = load_resource(resource_name, 0, NULL, 0, 0);
1994  if (!res) {
1995  ast_test_suite_event_notify("MODULE_LOAD", "Message: %s", resource_name);
1996  }
1998 
1999  return res;
2000 }
ast_module_load_result
Definition: module.h:68
#define AST_DLLIST_UNLOCK(head)
Attempts to unlock a list.
Definition: dlinkedlists.h:123
unsigned int declined
Definition: loader.c:322
#define ast_debug(level,...)
Log a DEBUG message.
#define ast_test_suite_event_notify(s, f,...)
Definition: test.h:189
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode force)
Unload a module.
Definition: loader.c:1448
#define AST_DLLIST_LOCK(head)
Locks a list.
Definition: dlinkedlists.h:46
static enum ast_module_load_result load_resource(const char *resource_name, unsigned int suppress_logging, struct module_vector *module_priorities, int required, int preload)
Definition: loader.c:1922
int ast_loader_register ( int(*)(void)  updater)

Add a procedure to be run when modules have been updated.

Parameters
updaterThe function to run when modules have been updated.

This function adds the given function to a linked list of functions to be run when the modules are updated.

Return values
0on success
-1on failure.

Definition at line 2836 of file loader.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_UNLOCK, and ast_malloc.

2837 {
2838  struct loadupdate *tmp;
2839 
2840  if (!(tmp = ast_malloc(sizeof(*tmp))))
2841  return -1;
2842 
2843  tmp->updater = v;
2847 
2848  return 0;
2849 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:711
Definition: search.h:40
int ast_loader_unregister ( int(*)(void)  updater)

Remove a procedure to be run when modules are updated.

Parameters
updaterThe updater function to unregister.

This removes the given function from the updater list.

Return values
0on success
-1on failure.

Definition at line 2851 of file loader.c.

References AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, and AST_LIST_UNLOCK.

2852 {
2853  struct loadupdate *cur;
2854 
2857  if (cur->updater == v) {
2859  break;
2860  }
2861  }
2864 
2865  return cur ? 0 : -1;
2866 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557
Definition: search.h:40
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529
int ast_module_check ( const char *  name)

Check if module with the name given is loaded.

Parameters
nameModule name, like "chan_pjsip.so"
Return values
1if true
0if false

Check if module with the name given is loaded.

Definition at line 2823 of file loader.c.

Referenced by ast_ari_asterisk_get_module(), ast_ari_asterisk_load_module(), ast_ari_asterisk_reload_module(), ast_ari_asterisk_unload_module(), and manager_modulecheck().

2824 {
2825  struct ast_module *cur;
2826 
2827  if (ast_strlen_zero(name))
2828  return 0; /* FALSE */
2829 
2830  cur = find_resource(name, 1);
2831 
2832  return (cur != NULL);
2833 }
char* ast_module_helper ( const char *  line,
const char *  word,
int  pos,
int  state,
int  rpos,
enum ast_module_helper_type  type 
)

Match modules names for the Asterisk cli.

Parameters
lineUnused by this function, but this should be the line we are matching.
wordThe partial name to match.
posThe position the word we are completing is in.
stateThe possible match to return.
rposThe position we should be matching. This should be the same as pos.
typeThe type of action that will be performed by CLI.
Return values
Apossible completion of the partial match.
NULLif no matches were found or Asterisk is not yet fully booted.

Definition at line 1528 of file loader.c.

References AST_DLLIST_LOCK, AST_DLLIST_TRAVERSE, AST_DLLIST_UNLOCK, AST_MODULE_HELPER_LOAD, AST_OPT_FLAG_FULLY_BOOTED, and ast_strdup.

1529 {
1530  struct ast_module *mod;
1531  int which = 0;
1532  int wordlen = strlen(word);
1533  char *ret = NULL;
1534 
1535  if (pos != rpos) {
1536  return NULL;
1537  }
1538 
1539  /* Tab completion can't be used during startup, or CLI and loader will deadlock. */
1540  if (!ast_test_flag(&ast_options, AST_OPT_FLAG_FULLY_BOOTED)) {
1541  return NULL;
1542  }
1543 
1544  if (type == AST_MODULE_HELPER_LOAD) {
1545  module_load_helper(word);
1546 
1547  return NULL;
1548  }
1549 
1552  if (!module_matches_helper_type(mod, type)) {
1553  continue;
1554  }
1555 
1556  if (!strncasecmp(word, mod->resource, wordlen) && ++which > state) {
1557  ret = ast_strdup(mod->resource);
1558  break;
1559  }
1560  }
1562 
1563  return ret;
1564 }
#define AST_DLLIST_UNLOCK(head)
Attempts to unlock a list.
Definition: dlinkedlists.h:123
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define AST_DLLIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: dlinkedlists.h:576
Definition: search.h:40
#define AST_DLLIST_LOCK(head)
Locks a list.
Definition: dlinkedlists.h:46
const char* ast_module_name ( const struct ast_module mod)

Get the name of a module.

Parameters
modA pointer to the module.
Returns
the name of the module
Return values
NULLif mod or mod->info is NULL

Definition at line 615 of file loader.c.

References ast_module_info::name.

Referenced by ast_register_application2(), and graceful_unload_possible().

616 {
617  if (!mod || !mod->info) {
618  return NULL;
619  }
620 
621  return mod->info->name;
622 }
const char * name
Definition: module.h:364
enum ast_module_reload_result ast_module_reload ( const char *  name)

Reload asterisk modules.

Parameters
namethe name of the module to reload

This function reloads the specified module, or if no modules are specified, it will reload all loaded modules.

Note
Modules are reloaded using their reload() functions, not unloading them and loading them again.
Return values
Theast_module_reload_result status of the module load request

Definition at line 1721 of file loader.c.

References AST_DLLIST_LOCK, AST_DLLIST_TRAVERSE, AST_DLLIST_UNLOCK, ast_lock_path(), AST_MODULE_LOAD_SUCCESS, AST_MODULE_RELOAD_ERROR, AST_MODULE_RELOAD_IN_PROGRESS, AST_MODULE_RELOAD_NOT_FOUND, AST_MODULE_RELOAD_NOT_IMPLEMENTED, AST_MODULE_RELOAD_QUEUED, AST_MODULE_RELOAD_SUCCESS, AST_MODULE_RELOAD_UNINITIALIZED, ast_sd_notify(), ast_tvnow(), ast_unlock_path(), ast_module::declined, ast_module_info::description, publish_reload_message(), ast_module_info::reload, and ast_module::running.

Referenced by action_reload(), ast_ari_asterisk_reload_module(), and ast_process_pending_reloads().

1722 {
1723  struct ast_module *cur;
1725  size_t name_baselen = name ? resource_name_baselen(name) : 0;
1726 
1727  /* If we aren't fully booted, we just pretend we reloaded but we queue this
1728  up to run once we are booted up. */
1729  if (!modules_loaded) {
1730  queue_reload_request(name);
1732  goto module_reload_exit;
1733  }
1734 
1735  if (ast_mutex_trylock(&reloadlock)) {
1736  ast_verb(3, "The previous reload command didn't finish yet\n");
1738  goto module_reload_exit;
1739  }
1740  ast_sd_notify("RELOADING=1");
1741  ast_lastreloadtime = ast_tvnow();
1742 
1743  if (ast_opt_lock_confdir) {
1744  int try;
1745  int lockres;
1746  for (try = 1, lockres = AST_LOCK_TIMEOUT; try < 6 && (lockres == AST_LOCK_TIMEOUT); try++) {
1747  lockres = ast_lock_path(ast_config_AST_CONFIG_DIR);
1748  if (lockres == AST_LOCK_TIMEOUT) {
1749  ast_log(LOG_WARNING, "Failed to grab lock on %s, try %d\n", ast_config_AST_CONFIG_DIR, try);
1750  }
1751  }
1752  if (lockres != AST_LOCK_SUCCESS) {
1753  ast_log(AST_LOG_WARNING, "Cannot grab lock on %s\n", ast_config_AST_CONFIG_DIR);
1755  goto module_reload_done;
1756  }
1757  }
1758 
1761  const struct ast_module_info *info = cur->info;
1762 
1763  if (name && resource_name_match(name, name_baselen, cur->resource)) {
1764  continue;
1765  }
1766 
1767  if (!cur->flags.running || cur->flags.declined) {
1768  if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1770  }
1771  if (!name) {
1772  continue;
1773  }
1774  break;
1775  }
1776 
1777  if (!info->reload) { /* cannot be reloaded */
1778  if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1780  }
1781  if (!name) {
1782  continue;
1783  }
1784  break;
1785  }
1786  ast_verb(3, "Reloading module '%s' (%s)\n", cur->resource, info->description);
1787  if (info->reload() == AST_MODULE_LOAD_SUCCESS) {
1789  } else if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1791  }
1792  if (name) {
1793  break;
1794  }
1795  }
1797 
1798  if (ast_opt_lock_confdir) {
1799  ast_unlock_path(ast_config_AST_CONFIG_DIR);
1800  }
1801 module_reload_done:
1802  ast_mutex_unlock(&reloadlock);
1803  ast_sd_notify("READY=1");
1804 
1805 module_reload_exit:
1807  return res;
1808 }
const char * description
Definition: module.h:366
unsigned int running
Definition: loader.c:320
ast_module_reload_result
Possible return types for ast_module_reload.
Definition: module.h:109
#define AST_DLLIST_UNLOCK(head)
Attempts to unlock a list.
Definition: dlinkedlists.h:123
static void publish_reload_message(const char *name, enum ast_module_reload_result result)
Definition: loader.c:1713
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159
int ast_unlock_path(const char *path)
Unlock a path.
Definition: main/app.c:2630
enum AST_LOCK_RESULT ast_lock_path(const char *path)
Lock a filesystem path.
Definition: main/app.c:2614
const char * name
Definition: module.h:364
#define AST_DLLIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: dlinkedlists.h:576
int ast_sd_notify(const char *state)
a wrapper for sd_notify(): notify systemd of any state changes.
Definition: io.c:392
static int modules_loaded
Internal flag to indicate all modules have been initially loaded.
Definition: loader.c:291
unsigned int declined
Definition: loader.c:322
int(* reload)(void)
Definition: module.h:360
Definition: search.h:40
#define AST_DLLIST_LOCK(head)
Locks a list.
Definition: dlinkedlists.h:46
int ast_refresh_resource ( const char *  resource_name,
enum ast_module_unload_mode  force,
int  recursive 
)

Unload and load a module again.

Parameters
resource_nameThe name of the module to unload.
ast_module_unload_modeThe force flag. This should be set using one of the AST_FORCE flags.
recursiveAttempt to recursively unload any dependents of this module if that will allow the module to unload, and load them back again afterwards.
Return values
0on success.
1on error unloading modules.
-1on error loading modules back.

Definition at line 1407 of file loader.c.

References ast_load_resource(), ast_unload_resource(), AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_INIT, AST_VECTOR_SIZE, and auto_unload_resource().

1408 {
1409  if (recursive) {
1410  /* Recursively unload dependents of this module and then load them back again */
1411  int res, i;
1412  struct ast_vector_const_string dependents;
1413  AST_VECTOR_INIT(&dependents, 0);
1414  res = auto_unload_resource(resource_name, force, recursive, &dependents);
1415  if (res) {
1416  AST_VECTOR_FREE(&dependents);
1417  return 1;
1418  }
1419  /* Start by loading the target again. */
1420  if (ast_load_resource(resource_name)) {
1421  ast_log(LOG_WARNING, "Failed to load module '%s' again automatically\n", resource_name);
1422  AST_VECTOR_FREE(&dependents);
1423  return -1;
1424  }
1425  res = 0;
1426  /* Finally, load again any modules we had to unload in order to refresh the target.
1427  * We must load modules in the reverse order that we unloaded them,
1428  * to preserve dependency requirements. */
1429  for (i = 0; i < AST_VECTOR_SIZE(&dependents); i++) {
1430  const char *depname = AST_VECTOR_GET(&dependents, i);
1431  int mres = ast_load_resource(depname);
1432  if (mres) {
1433  ast_log(LOG_WARNING, "Could not load module '%s' again automatically\n", depname);
1434  }
1435  res |= mres;
1436  }
1437  AST_VECTOR_FREE(&dependents);
1438  return res ? -1 : 0;
1439  }
1440 
1441  /* Simple case: just unload and load the module again */
1442  if (ast_unload_resource(resource_name, force)) {
1443  return 1;
1444  }
1445  return ast_load_resource(resource_name);
1446 }
#define AST_VECTOR_FREE(vec)
Deallocates this vector.
Definition: vector.h:174
enum ast_module_load_result ast_load_resource(const char *resource_name)
Load a module.
Definition: loader.c:1978
#define AST_VECTOR_INIT(vec, size)
Initialize a vector.
Definition: vector.h:113
static int auto_unload_resource(const char *resource_name, enum ast_module_unload_mode force, int recursive, struct ast_vector_const_string *dependents)
Unload a resource.
Definition: loader.c:1285
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode force)
Unload a module.
Definition: loader.c:1448
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
int ast_register_application2 ( const char *  app,
int(*)(struct ast_channel *, const char *)  execute,
const char *  synopsis,
const char *  description,
void *  mod 
)

Register an application.

Parameters
appShort name of the application
executea function callback to execute the application. It should return non-zero if the channel needs to be hung up.
synopsisa short description (one line synopsis) of the application
descriptionlong description with all of the details about the use of the application
modmodule this application belongs to

This registers an application with Asterisk's internal application list.

Note
The individual applications themselves are responsible for registering and unregistering and unregistering their own CLI commands.
Return values
0success
-1failure.

Register an application.

Definition at line 103 of file pbx_app.c.

References ast_app::arguments, ast_calloc, ast_module_name(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_string_field_init, ast_string_field_set, AST_XML_DOC, ast_xmldoc_build_arguments(), ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), COLORIZE_FMT, ast_app::docsrc, ast_app::seealso, and ast_app::syntax.

Referenced by ast_msg_init(), load_pbx_builtins(), and load_pbx_variables().

104 {
105  struct ast_app *tmp;
106  struct ast_app *cur;
107  int length;
108 #ifdef AST_XML_DOCS
109  char *tmpxml;
110 #endif
111 
113  cur = pbx_findapp_nolock(app);
114  if (cur) {
115  ast_log(LOG_WARNING, "Already have an application '%s'\n", app);
117  return -1;
118  }
119 
120  length = sizeof(*tmp) + strlen(app) + 1;
121 
122  if (!(tmp = ast_calloc(1, length))) {
124  return -1;
125  }
126 
127  if (ast_string_field_init(tmp, 128)) {
129  ast_free(tmp);
130  return -1;
131  }
132 
133  strcpy(tmp->name, app);
134  tmp->execute = execute;
135  tmp->module = mod;
136 
137 #ifdef AST_XML_DOCS
138  /* Try to lookup the docs in our XML documentation database */
139  if (ast_strlen_zero(synopsis) && ast_strlen_zero(description)) {
140  /* load synopsis */
141  tmpxml = ast_xmldoc_build_synopsis("application", app, ast_module_name(tmp->module));
142  ast_string_field_set(tmp, synopsis, tmpxml);
143  ast_free(tmpxml);
144 
145  /* load description */
146  tmpxml = ast_xmldoc_build_description("application", app, ast_module_name(tmp->module));
147  ast_string_field_set(tmp, description, tmpxml);
148  ast_free(tmpxml);
149 
150  /* load syntax */
151  tmpxml = ast_xmldoc_build_syntax("application", app, ast_module_name(tmp->module));
152  ast_string_field_set(tmp, syntax, tmpxml);
153  ast_free(tmpxml);
154 
155  /* load arguments */
156  tmpxml = ast_xmldoc_build_arguments("application", app, ast_module_name(tmp->module));
157  ast_string_field_set(tmp, arguments, tmpxml);
158  ast_free(tmpxml);
159 
160  /* load seealso */
161  tmpxml = ast_xmldoc_build_seealso("application", app, ast_module_name(tmp->module));
162  ast_string_field_set(tmp, seealso, tmpxml);
163  ast_free(tmpxml);
164  tmp->docsrc = AST_XML_DOC;
165  } else {
166 #endif
169 #ifdef AST_XML_DOCS
170  tmp->docsrc = AST_STATIC_DOC;
171  }
172 #endif
173 
174  /* Store in alphabetical order */
175  AST_RWLIST_TRAVERSE_SAFE_BEGIN(&apps, cur, list) {
176  if (strcasecmp(tmp->name, cur->name) < 0) {
177  AST_RWLIST_INSERT_BEFORE_CURRENT(tmp, list);
178  break;
179  }
180  }
181  AST_RWLIST_TRAVERSE_SAFE_END;
182  if (!cur)
183  AST_RWLIST_INSERT_TAIL(&apps, tmp, list);
184 
185  ast_verb(5, "Registered application '" COLORIZE_FMT "'\n", COLORIZE(COLOR_BRCYAN, 0, tmp->name));
186 
188 
189  return 0;
190 }
const ast_string_field description
Definition: pbx_app.c:53
static SQLHSTMT execute(struct odbc_obj *obj, void *data, int silent)
Common execution function for SQL queries.
Definition: func_odbc.c:471
const ast_string_field synopsis
Definition: pbx_app.c:53
Registered applications container.
Definition: pbx_app.c:67
char * ast_xmldoc_build_description(const char *type, const char *name, const char *module)
Generate description documentation from XML.
Definition: xmldoc.c:2271
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:2248
char * ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)
Generate the [arguments] tag based on type of node ('application', 'function' or 'agi') and name...
Definition: xmldoc.c:2084
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
#define COLORIZE_FMT
Shortcut macros for coloring a set of text.
Definition: term.h:71
const ast_string_field syntax
Definition: pbx_app.c:53
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
enum ast_doc_src docsrc
Definition: pbx_app.c:55
char * ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
Get the syntax for a specified application or function.
Definition: xmldoc.c:1252
char * ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
Parse the node content.
Definition: xmldoc.c:1702
const char * ast_module_name(const struct ast_module *mod)
Get the name of a module.
Definition: loader.c:615
ast_app: A registered application
Definition: pbx_app.c:45
const ast_string_field seealso
Definition: pbx_app.c:53
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
const ast_string_field arguments
Definition: pbx_app.c:53
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:521
int ast_unload_resource ( const char *  resource_name,
enum  ast_module_unload_mode 
)

Unload a module.

Parameters
resource_nameThe name of the module to unload.
ast_module_unload_modeThe force flag. This should be set using one of the AST_FORCE flags.

This function unloads a module. It will only unload modules that are not in use (usecount not zero), unless AST_FORCE_FIRM or AST_FORCE_HARD is specified. Setting AST_FORCE_FIRM or AST_FORCE_HARD will unload the module regardless of consequences (NOT RECOMMENDED).

Return values
0on success.
-1on error.

Definition at line 1448 of file loader.c.

References auto_unload_resource().

Referenced by ast_ari_asterisk_unload_module(), ast_load_resource(), ast_refresh_resource(), and auto_unload_resource().

1449 {
1450  return auto_unload_resource(resource_name, force, 0, NULL);
1451 }
static int auto_unload_resource(const char *resource_name, enum ast_module_unload_mode force, int recursive, struct ast_vector_const_string *dependents)
Unload a resource.
Definition: loader.c:1285
int ast_unregister_application ( const char *  app)

Unregister an application.

Parameters
appname of the application (does not have to be the same string as the one that was registered)

This unregisters an application from Asterisk's internal application list.

Return values
0success
-1failure
Examples:
app_skel.c.

Definition at line 392 of file pbx_app.c.

References ast_rdlock_contexts(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_string_field_free_memory, ast_unlock_contexts(), and unreference_cached_app().

Referenced by load_module(), unload_module(), and unload_parking_applications().

393 {
394  struct ast_app *cur;
395  int cmp;
396 
397  /* Anticipate need for conlock in unreference_cached_app(), in order to avoid
398  * possible deadlock with pbx_extension_helper()/pbx_findapp()
399  */
401 
403  AST_RWLIST_TRAVERSE_SAFE_BEGIN(&apps, cur, list) {
404  cmp = strcasecmp(app, cur->name);
405  if (cmp > 0) {
406  continue;
407  }
408  if (!cmp) {
409  /* Found it. */
411  AST_RWLIST_REMOVE_CURRENT(list);
412  ast_verb(5, "Unregistered application '%s'\n", cur->name);
414  ast_free(cur);
415  break;
416  }
417  /* Not in container. */
418  cur = NULL;
419  break;
420  }
421  AST_RWLIST_TRAVERSE_SAFE_END;
423 
425 
426  return cur ? 0 : -1;
427 }
Registered applications container.
Definition: pbx_app.c:67
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
int ast_rdlock_contexts(void)
Read locks the context list.
Definition: pbx.c:8468
int ast_unlock_contexts(void)
Unlocks contexts.
Definition: pbx.c:8473
void unreference_cached_app(struct ast_app *app)
Definition: pbx.c:6130
ast_app: A registered application
Definition: pbx_app.c:45
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define ast_string_field_free_memory(x)
free all memory - to be called before destroying the object
Definition: stringfields.h:374
int ast_update_module_list ( int(*)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level)  modentry,
const char *  like 
)

Ask for a list of modules, descriptions, use counts and status.

Parameters
modentryA callback to an updater function.
likeFor each of the modules loaded, modentry will be executed with the resource, description, and usecount values of each particular module.
Returns
the number of modules loaded
int ast_update_module_list_condition ( int(*)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data, const char *condition)  modentry,
const char *  like,
void *  data,
const char *  condition 
)

Ask for a list of modules, descriptions, use counts and status.

Parameters
modentryA callback to an updater function
like
dataData passed into the callback for manipulation
conditionThe condition to meet

For each of the modules loaded, modentry will be executed with the resource, description, and usecount values of each particular module.

Returns
the number of conditions met
Since
13.5.0

Referenced by ast_ari_asterisk_get_module().

int ast_update_module_list_data ( int(*)(const char *module, const char *description, int usecnt, const char *status, const char *like, enum ast_module_support_level support_level, void *data)  modentry,
const char *  like,
void *  data 
)

Ask for a list of modules, descriptions, use counts and status.

Parameters
modentryA callback to an updater function
like
dataData passed into the callback for manipulation

For each of the modules loaded, modentry will be executed with the resource, description, and usecount values of each particular module.

Returns
the number of modules loaded
Since
13.5.0

Definition at line 2764 of file loader.c.

References AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_module_info::description, ast_module::running, ast_module_info::support_level, and ast_module::usecount.

Referenced by ast_ari_asterisk_list_modules().

2769 {
2770  int total_mod_loaded = 0;
2771  struct module_vector alpha_module_list;
2772 
2774 
2775  if (!alpha_module_list_create(&alpha_module_list)) {
2776  int idx;
2777 
2778  for (idx = 0; idx < AST_VECTOR_SIZE(&alpha_module_list); idx++) {
2779  struct ast_module *cur = AST_VECTOR_GET(&alpha_module_list, idx);
2780 
2781  total_mod_loaded += modentry(cur->resource, cur->info->description, cur->usecount,
2782  cur->flags.running? "Running" : "Not Running", like, cur->info->support_level, data);
2783  }
2784  }
2785 
2787  AST_VECTOR_FREE(&alpha_module_list);
2788 
2789  return total_mod_loaded;
2790 }
const char * description
Definition: module.h:366
#define AST_VECTOR_FREE(vec)
Deallocates this vector.
Definition: vector.h:174
unsigned int running
Definition: loader.c:320
#define AST_DLLIST_UNLOCK(head)
Attempts to unlock a list.
Definition: dlinkedlists.h:123
int usecount
Definition: loader.c:300
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680
enum ast_module_support_level support_level
Definition: module.h:430
#define AST_DLLIST_LOCK(head)
Locks a list.
Definition: dlinkedlists.h:46
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
void ast_update_use_count ( void  )

Notify when usecount has been changed.

This function calculates use counts and notifies anyone trying to keep track of them. It should be called whenever your module's usecount changes.

Note
The ast_module_user_* functions take care of calling this function for you.

Definition at line 2698 of file loader.c.

References AST_LIST_LOCK, AST_LIST_TRAVERSE, and AST_LIST_UNLOCK.

Referenced by auto_unload_resource(), and unistim_new().

2699 {
2700  /* Notify any module monitors that the use count for a
2701  resource has changed */
2702  struct loadupdate *m;
2703 
2706  m->updater();
2708 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
Definition: search.h:40