Asterisk - The Open Source Telephony Project GIT-master-754dea3
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
Data Structures | Macros | Enumerations | Functions | Variables
module.h File Reference

Asterisk module definitions. More...

#include "asterisk/utils.h"
Include dependency graph for module.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. More...
 
#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. More...
 
#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

◆ AST_MODULE_CONFIG

#define AST_MODULE_CONFIG   "modules.conf"

Module configuration file.

Definition at line 59 of file module.h.

◆ AST_MODULE_INFO

#define AST_MODULE_INFO (   keystr,
  flags_to_set,
  desc,
  fields... 
)
Examples
app_skel.c.

Definition at line 557 of file module.h.

◆ AST_MODULE_INFO_STANDARD

#define AST_MODULE_INFO_STANDARD (   keystr,
  desc 
)

Definition at line 581 of file module.h.

◆ AST_MODULE_INFO_STANDARD_DEPRECATED

#define AST_MODULE_INFO_STANDARD_DEPRECATED (   keystr,
  desc 
)

Definition at line 597 of file module.h.

◆ AST_MODULE_INFO_STANDARD_EXTENDED

#define AST_MODULE_INFO_STANDARD_EXTENDED (   keystr,
  desc 
)

Definition at line 589 of file module.h.

◆ ast_module_ref

#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.

◆ ast_module_running_ref

#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.

◆ ast_module_shutdown_ref

#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.

◆ ast_module_unref

#define ast_module_unref (   mod)    __ast_module_unref(mod, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Release a reference to the module.

Parameters
modModule to release

Definition at line 483 of file module.h.

◆ ast_module_user_add

#define ast_module_user_add (   chan)    __ast_module_user_add(AST_MODULE_SELF, chan)

Definition at line 440 of file module.h.

◆ ast_module_user_hangup_all

#define ast_module_user_hangup_all ( )    __ast_module_user_hangup_all(AST_MODULE_SELF)

Definition at line 442 of file module.h.

◆ ast_module_user_remove

#define ast_module_user_remove (   user)    __ast_module_user_remove(AST_MODULE_SELF, user)

Definition at line 441 of file module.h.

◆ ast_register_application

#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.

◆ ast_register_application_xml

#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.

◆ ASTERISK_GPL_KEY

#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.

Examples
app_skel.c.

Definition at line 46 of file module.h.

◆ SCOPED_MODULE_USE

#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.

Enumeration Type Documentation

◆ ast_module_flags

Enumerator
AST_MODFLAG_DEFAULT 
AST_MODFLAG_GLOBAL_SYMBOLS 
AST_MODFLAG_LOAD_ORDER 

Definition at line 328 of file module.h.

328 {
331 AST_MODFLAG_LOAD_ORDER = (1 << 1),
332};
@ AST_MODFLAG_LOAD_ORDER
Definition: module.h:331
@ AST_MODFLAG_DEFAULT
Definition: module.h:329
@ AST_MODFLAG_GLOBAL_SYMBOLS
Definition: module.h:330

◆ ast_module_helper_type

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};
@ AST_MODULE_HELPER_RELOAD
Definition: module.h:131
@ AST_MODULE_HELPER_LOADED
Definition: module.h:129
@ AST_MODULE_HELPER_UNLOAD
Definition: module.h:135
@ AST_MODULE_HELPER_LOAD
Definition: module.h:133
@ AST_MODULE_HELPER_RUNNING
Definition: module.h:137

◆ ast_module_load_priority

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};
@ AST_MODPRI_APP_DEPEND
Definition: module.h:342
@ AST_MODPRI_DEFAULT
Definition: module.h:346
@ AST_MODPRI_CDR_DRIVER
Definition: module.h:345
@ AST_MODPRI_CHANNEL_DRIVER
Definition: module.h:341
@ AST_MODPRI_CORE
Definition: module.h:338
@ AST_MODPRI_REALTIME_DEPEND
Definition: module.h:335
@ AST_MODPRI_TIMING
Definition: module.h:339
@ AST_MODPRI_REALTIME_DRIVER
Definition: module.h:337
@ AST_MODPRI_CHANNEL_DEPEND
Definition: module.h:340
@ AST_MODPRI_DEVSTATE_CONSUMER
Definition: module.h:347
@ AST_MODPRI_REALTIME_DEPEND2
Definition: module.h:336
@ AST_MODPRI_DEVSTATE_PROVIDER
Definition: module.h:343
@ AST_MODPRI_DEVSTATE_PLUGIN
Definition: module.h:344

◆ ast_module_load_result

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_SKIP 
AST_MODULE_LOAD_PRIORITY 
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 */
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 */
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};
@ AST_MODULE_LOAD_PRIORITY
Definition: module.h:90
@ AST_MODULE_LOAD_FAILURE
Module could not be loaded properly.
Definition: module.h:102
@ AST_MODULE_LOAD_SUCCESS
Definition: module.h:70
@ AST_MODULE_LOAD_DECLINE
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
@ AST_MODULE_LOAD_SKIP
Definition: module.h:84

◆ ast_module_reload_result

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};
@ AST_MODULE_RELOAD_IN_PROGRESS
Definition: module.h:114
@ AST_MODULE_RELOAD_QUEUED
Definition: module.h:111
@ AST_MODULE_RELOAD_SUCCESS
Definition: module.h:110
@ AST_MODULE_RELOAD_ERROR
Definition: module.h:113
@ AST_MODULE_RELOAD_NOT_IMPLEMENTED
Definition: module.h:116
@ AST_MODULE_RELOAD_NOT_FOUND
Definition: module.h:112
@ AST_MODULE_RELOAD_UNINITIALIZED
Definition: module.h:115

◆ ast_module_support_level

Enumerator
AST_MODULE_SUPPORT_UNKNOWN 
AST_MODULE_SUPPORT_CORE 
AST_MODULE_SUPPORT_EXTENDED 
AST_MODULE_SUPPORT_DEPRECATED 

Definition at line 119 of file module.h.

119 {
124};
@ AST_MODULE_SUPPORT_DEPRECATED
Definition: module.h:123
@ AST_MODULE_SUPPORT_CORE
Definition: module.h:121
@ AST_MODULE_SUPPORT_EXTENDED
Definition: module.h:122
@ AST_MODULE_SUPPORT_UNKNOWN
Definition: module.h:120

◆ ast_module_unload_mode

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};
@ AST_FORCE_SOFT
Definition: module.h:62
@ AST_FORCE_HARD
Definition: module.h:64
@ AST_FORCE_FIRM
Definition: module.h:63

Function Documentation

◆ __ast_module_ref()

struct ast_module * __ast_module_ref ( struct ast_module mod,
const char *  file,
int  line,
const char *  func 
)

Definition at line 2877 of file loader.c.

2878{
2879 if (!mod) {
2880 return NULL;
2881 }
2882
2883 if (mod->ref_debug) {
2884 __ao2_ref(mod->ref_debug, +1, "", file, line, func);
2885 }
2886
2889
2890 return mod;
2891}
int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, const char *func)
Definition: astobj2.c:498
void ast_update_use_count(void)
Notify when usecount has been changed.
Definition: loader.c:2707
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:761
#define NULL
Definition: resample.c:96
void * ref_debug
Definition: loader.c:305
int usecount
Definition: loader.c:309

References __ao2_ref(), ast_atomic_fetchadd_int(), ast_update_use_count(), make_ari_stubs::file, NULL, ast_module::ref_debug, and ast_module::usecount.

Referenced by __ast_module_running_ref(), and __ast_module_shutdown_ref().

◆ __ast_module_running_ref()

struct ast_module * __ast_module_running_ref ( struct ast_module mod,
const char *  file,
int  line,
const char *  func 
)

Definition at line 2893 of file loader.c.

2895{
2896 if (!mod || !mod->flags.running) {
2897 return NULL;
2898 }
2899
2900 return __ast_module_ref(mod, file, line, func);
2901}
struct ast_module * __ast_module_ref(struct ast_module *mod, const char *file, int line, const char *func)
Definition: loader.c:2877
unsigned int running
Definition: loader.c:329
struct ast_module::@365 flags

References __ast_module_ref(), make_ari_stubs::file, ast_module::flags, NULL, and ast_module::running.

◆ __ast_module_shutdown_ref()

void __ast_module_shutdown_ref ( struct ast_module mod,
const char *  file,
int  line,
const char *  func 
)

Definition at line 2903 of file loader.c.

2904{
2905 if (!mod || mod->flags.keepuntilshutdown) {
2906 return;
2907 }
2908
2909 __ast_module_ref(mod, file, line, func);
2910 mod->flags.keepuntilshutdown = 1;
2911}
unsigned int keepuntilshutdown
Definition: loader.c:333

References __ast_module_ref(), make_ari_stubs::file, ast_module::flags, and ast_module::keepuntilshutdown.

◆ __ast_module_unref()

void __ast_module_unref ( struct ast_module mod,
const char *  file,
int  line,
const char *  func 
)

Definition at line 2913 of file loader.c.

2914{
2915 if (!mod) {
2916 return;
2917 }
2918
2919 if (mod->ref_debug) {
2920 __ao2_ref(mod->ref_debug, -1, "", file, line, func);
2921 }
2922
2925}

References __ao2_ref(), ast_atomic_fetchadd_int(), ast_update_use_count(), make_ari_stubs::file, ast_module::ref_debug, and ast_module::usecount.

◆ __ast_module_user_add()

struct ast_module_user * __ast_module_user_add ( struct ast_module mod,
struct ast_channel chan 
)

Definition at line 809 of file loader.c.

810{
811 struct ast_module_user *u;
812
813 u = ast_calloc(1, sizeof(*u));
814 if (!u) {
815 return NULL;
816 }
817
818 u->chan = chan;
819
820 AST_LIST_LOCK(&mod->users);
822 AST_LIST_UNLOCK(&mod->users);
823
824 if (mod->ref_debug) {
825 ao2_ref(mod->ref_debug, +1);
826 }
827
829
831
832 return u;
833}
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:711
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
struct ast_module_user::@364 entry
struct ast_channel * chan
Definition: loader.c:137
struct module_user_list users
Definition: loader.c:311

References ao2_ref, ast_atomic_fetchadd_int(), ast_calloc, AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_update_use_count(), ast_module_user::chan, ast_module_user::entry, NULL, ast_module::ref_debug, ast_module::usecount, and ast_module::users.

Referenced by ast_func_read(), ast_func_read2(), ast_func_write(), and pbx_exec().

◆ __ast_module_user_hangup_all()

void __ast_module_user_hangup_all ( struct ast_module mod)

Definition at line 862 of file loader.c.

863{
864 struct ast_module_user *u;
865
866 AST_LIST_LOCK(&mod->users);
867 while ((u = AST_LIST_REMOVE_HEAD(&mod->users, entry))) {
868 if (u->chan) {
870 }
871
872 if (mod->ref_debug) {
873 ao2_ref(mod->ref_debug, -1);
874 }
875
877 ast_free(u);
878 }
879 AST_LIST_UNLOCK(&mod->users);
880
882}
#define ast_free(a)
Definition: astmm.h:180
int ast_softhangup(struct ast_channel *chan, int cause)
Softly hangup up a channel.
Definition: channel.c:2500
@ AST_SOFTHANGUP_APPUNLOAD
Definition: channel.h:1163
#define AST_LIST_REMOVE_HEAD(head, field)
Removes and returns the head entry from a list.
Definition: linkedlists.h:833

References ao2_ref, ast_atomic_fetchadd_int(), ast_free, AST_LIST_LOCK, AST_LIST_REMOVE_HEAD, AST_LIST_UNLOCK, ast_softhangup(), AST_SOFTHANGUP_APPUNLOAD, ast_update_use_count(), ast_module_user::chan, ast_module_user::entry, ast_module::ref_debug, ast_module::usecount, and ast_module::users.

Referenced by auto_unload_resource().

◆ __ast_module_user_remove()

void __ast_module_user_remove ( struct ast_module mod,
struct ast_module_user u 
)

Definition at line 835 of file loader.c.

836{
837 if (!u) {
838 return;
839 }
840
841 AST_LIST_LOCK(&mod->users);
842 u = AST_LIST_REMOVE(&mod->users, u, entry);
843 AST_LIST_UNLOCK(&mod->users);
844 if (!u) {
845 /*
846 * Was not in the list. Either a bad pointer or
847 * __ast_module_user_hangup_all() has been called.
848 */
849 return;
850 }
851
852 if (mod->ref_debug) {
853 ao2_ref(mod->ref_debug, -1);
854 }
855
857 ast_free(u);
858
860}
#define AST_LIST_REMOVE(head, elm, field)
Removes a specific entry from a list.
Definition: linkedlists.h:856

References ao2_ref, ast_atomic_fetchadd_int(), ast_free, AST_LIST_LOCK, AST_LIST_REMOVE, AST_LIST_UNLOCK, ast_update_use_count(), ast_module_user::entry, ast_module::ref_debug, ast_module::usecount, and ast_module::users.

Referenced by ast_func_read(), ast_func_read2(), ast_func_write(), and pbx_exec().

◆ ast_load_resource()

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 1987 of file loader.c.

1988{
1989 struct ast_module *mod;
1990 enum ast_module_load_result res;
1991
1992 /* If we're trying to load a module that previously declined to load,
1993 * transparently unload it first so we dlclose, then dlopen it afresh.
1994 * Otherwise, we won't actually load a (potentially) updated module. */
1995 mod = find_resource(resource_name, 0);
1996 if (mod && mod->flags.declined) {
1997 ast_debug(1, "Module %s previously declined to load, unloading it first before loading again\n", resource_name);
1998 ast_unload_resource(resource_name, 0);
1999 }
2000
2002 res = load_resource(resource_name, 0, NULL, 0, 0);
2003 if (!res) {
2004 ast_test_suite_event_notify("MODULE_LOAD", "Message: %s", resource_name);
2005 }
2007
2008 return res;
2009}
#define AST_DLLIST_LOCK(head)
Locks a list.
Definition: dlinkedlists.h:46
#define AST_DLLIST_UNLOCK(head)
Attempts to unlock a list.
Definition: dlinkedlists.h:123
#define ast_debug(level,...)
Log a DEBUG message.
static struct ast_module * find_resource(const char *resource, int do_lock)
Definition: loader.c:936
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:1931
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode force)
Unload a module.
Definition: loader.c:1457
ast_module_load_result
Definition: module.h:68
unsigned int declined
Definition: loader.c:331
#define ast_test_suite_event_notify(s, f,...)
Definition: test.h:189

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

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

◆ ast_loader_register()

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 2845 of file loader.c.

2846{
2847 struct loadupdate *tmp;
2848
2849 if (!(tmp = ast_malloc(sizeof(*tmp))))
2850 return -1;
2851
2852 tmp->updater = v;
2856
2857 return 0;
2858}
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191
struct loadupdate::@367 entry
int(* updater)(void)
Definition: loader.c:634

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_malloc, loadupdate::entry, and loadupdate::updater.

◆ ast_loader_unregister()

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 2860 of file loader.c.

2861{
2862 struct loadupdate *cur;
2863
2866 if (cur->updater == v) {
2868 break;
2869 }
2870 }
2873
2874 return cur ? 0 : -1;
2875}
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557

References AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, loadupdate::entry, and loadupdate::updater.

◆ ast_module_check()

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 2832 of file loader.c.

2833{
2834 struct ast_module *cur;
2835
2836 if (ast_strlen_zero(name))
2837 return 0; /* FALSE */
2838
2839 cur = find_resource(name, 1);
2840
2841 return (cur != NULL);
2842}
static const char name[]
Definition: format_mp3.c:68
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65

References ast_strlen_zero(), find_resource(), name, and NULL.

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

◆ ast_module_helper()

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 1537 of file loader.c.

1538{
1539 struct ast_module *mod;
1540 int which = 0;
1541 int wordlen = strlen(word);
1542 char *ret = NULL;
1543
1544 if (pos != rpos) {
1545 return NULL;
1546 }
1547
1548 /* Tab completion can't be used during startup, or CLI and loader will deadlock. */
1550 return NULL;
1551 }
1552
1555
1556 return NULL;
1557 }
1558
1561 if (!module_matches_helper_type(mod, type)) {
1562 continue;
1563 }
1564
1565 if (!strncasecmp(word, mod->resource, wordlen) && ++which > state) {
1566 ret = ast_strdup(mod->resource);
1567 break;
1568 }
1569 }
1571
1572 return ret;
1573}
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
static const char type[]
Definition: chan_ooh323.c:109
short word
#define AST_DLLIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: dlinkedlists.h:576
struct ast_flags ast_options
Definition: options.c:61
@ AST_OPT_FLAG_FULLY_BOOTED
Definition: options.h:58
static int module_matches_helper_type(struct ast_module *mod, enum ast_module_helper_type type)
Definition: loader.c:1462
static void module_load_helper(const char *word)
Definition: loader.c:1524
char resource[0]
Definition: loader.c:342
struct ast_module::@366 entry
#define ast_test_flag(p, flag)
Definition: utils.h:63

References AST_DLLIST_LOCK, AST_DLLIST_TRAVERSE, AST_DLLIST_UNLOCK, AST_MODULE_HELPER_LOAD, AST_OPT_FLAG_FULLY_BOOTED, ast_options, ast_strdup, ast_test_flag, ast_module::entry, module_load_helper(), module_matches_helper_type(), NULL, ast_module::resource, and type.

Referenced by handle_debug(), handle_load(), handle_modlist(), handle_refresh(), handle_reload(), handle_trace(), and handle_unload().

◆ ast_module_name()

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 624 of file loader.c.

625{
626 if (!mod || !mod->info) {
627 return NULL;
628 }
629
630 return mod->info->name;
631}
const char * name
Definition: module.h:364
const struct ast_module_info * info
Definition: loader.c:303

References ast_module::info, ast_module_info::name, and NULL.

Referenced by acf_retrieve_docs(), ast_register_application2(), graceful_unload_possible(), resource_list_recursive_decline(), start_resource_list(), and unload_dynamic_module().

◆ ast_module_register()

void ast_module_register ( const struct ast_module_info info)

Definition at line 668 of file loader.c.

669{
670 struct ast_module *mod;
671
672 if (!loader_ready) {
673 mod = ast_std_calloc(1, sizeof(*mod) + strlen(info->name) + 1);
674 if (!mod) {
675 /* We haven't even reached main() yet, if we can't
676 * allocate memory at this point just give up. */
677 fprintf(stderr, "Allocation failure during startup.\n");
678 exit(2);
679 }
680 strcpy(mod->resource, info->name); /* safe */
681 mod->info = info;
682 mod->flags.builtin = 1;
684
685 /* ast_module_register for built-in modules is run again during module preload. */
686 return;
687 }
688
689 /*
690 * This lock protects resource_being_loaded as well as the module
691 * list. Normally we already have a lock on module_list when we
692 * begin the load but locking again from here prevents corruption
693 * if an asterisk module is dlopen'ed from outside the module loader.
694 */
697 if (!mod) {
699 return;
700 }
701
702 ast_debug(5, "Registering module %s\n", info->name);
703
704 /* This tells load_dynamic_module that we're registered. */
706
707 mod->info = info;
708 if (ast_opt_ref_debug) {
710 }
712 AST_VECTOR_INIT(&mod->requires, 0);
714 AST_VECTOR_INIT(&mod->enhances, 0);
716
719
720 /* give the module a copy of its own handle, for later use in registrations and the like */
721 *((struct ast_module **) &(info->self)) = mod;
722
723#if defined(HAVE_PERMANENT_DLOPEN)
724 if (mod->flags.builtin != 1) {
725 struct info_list_obj *obj_tmp = ao2_find(info_list, info->name,
727
728 if (!obj_tmp) {
729 obj_tmp = info_list_obj_alloc(info->name, info);
730 if (obj_tmp) {
731 ao2_link(info_list, obj_tmp);
732 ao2_ref(obj_tmp, -1);
733 }
734 } else {
735 ao2_ref(obj_tmp, -1);
736 }
737 }
738#endif
739}
void * ast_std_calloc(size_t nmemb, size_t size) attribute_malloc
Definition: astmm.c:1724
#define ao2_link(container, obj)
Add an object to a container.
Definition: astobj2.h:1532
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:402
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1736
@ OBJ_SEARCH_KEY
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1101
#define AST_DLLIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:626
static unsigned int loader_ready
Definition: loader.c:159
static struct module_list builtin_module_list
Definition: loader.c:373
static struct ast_module *volatile resource_being_loaded
Definition: loader.c:659
def info(msg)
#define ast_opt_ref_debug
Definition: options.h:135
struct ast_vector_string requires
Definition: loader.c:314
struct ast_vector_string optional_modules
Definition: loader.c:316
struct module_vector reffed_deps
Vector holding pointers to modules we have a reference to.
Definition: loader.c:326
unsigned int builtin
Definition: loader.c:335
struct ast_vector_string enhances
Definition: loader.c:318
#define AST_VECTOR_INIT(vec, size)
Initialize a vector.
Definition: vector.h:113

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_find, ao2_link, ao2_ref, ao2_t_alloc_options, ast_debug, AST_DLLIST_INSERT_TAIL, AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, AST_LIST_HEAD_INIT, ast_opt_ref_debug, ast_std_calloc(), AST_VECTOR_INIT, ast_module::builtin, builtin_module_list, ast_module::enhances, ast_module::entry, ast_module::flags, sip_to_pjsip::info(), ast_module::info, loader_ready, NULL, OBJ_SEARCH_KEY, ast_module::optional_modules, ast_module::ref_debug, ast_module::reffed_deps, ast_module::requires, ast_module::resource, resource_being_loaded, and ast_module::users.

Referenced by loader_builtin_init().

◆ ast_module_reload()

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 1730 of file loader.c.

1731{
1732 struct ast_module *cur;
1734 size_t name_baselen = name ? resource_name_baselen(name) : 0;
1735
1736 /* If we aren't fully booted, we just pretend we reloaded but we queue this
1737 up to run once we are booted up. */
1738 if (!modules_loaded) {
1741 goto module_reload_exit;
1742 }
1743
1745 ast_verb(3, "The previous reload command didn't finish yet\n");
1747 goto module_reload_exit;
1748 }
1749 ast_sd_notify("RELOADING=1");
1751
1753 int try;
1754 int lockres;
1755 for (try = 1, lockres = AST_LOCK_TIMEOUT; try < 6 && (lockres == AST_LOCK_TIMEOUT); try++) {
1757 if (lockres == AST_LOCK_TIMEOUT) {
1758 ast_log(LOG_WARNING, "Failed to grab lock on %s, try %d\n", ast_config_AST_CONFIG_DIR, try);
1759 }
1760 }
1761 if (lockres != AST_LOCK_SUCCESS) {
1762 ast_log(AST_LOG_WARNING, "Cannot grab lock on %s\n", ast_config_AST_CONFIG_DIR);
1764 goto module_reload_done;
1765 }
1766 }
1767
1770 const struct ast_module_info *info = cur->info;
1771
1772 if (name && resource_name_match(name, name_baselen, cur->resource)) {
1773 continue;
1774 }
1775
1776 if (!cur->flags.running || cur->flags.declined) {
1777 if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1779 }
1780 if (!name) {
1781 continue;
1782 }
1783 break;
1784 }
1785
1786 if (!info->reload) { /* cannot be reloaded */
1787 if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1789 }
1790 if (!name) {
1791 continue;
1792 }
1793 break;
1794 }
1795 ast_verb(3, "Reloading module '%s' (%s)\n", cur->resource, info->description);
1796 if (info->reload() == AST_MODULE_LOAD_SUCCESS) {
1798 } else if (res == AST_MODULE_RELOAD_NOT_FOUND) {
1800 }
1801 if (name) {
1802 break;
1803 }
1804 }
1806
1809 }
1810module_reload_done:
1812 ast_sd_notify("READY=1");
1813
1814module_reload_exit:
1816 return res;
1817}
#define ast_log
Definition: astobj2.c:42
@ AST_LOCK_SUCCESS
@ AST_LOCK_TIMEOUT
enum AST_LOCK_RESULT ast_lock_path(const char *path)
Lock a filesystem path.
Definition: main/app.c:2614
int ast_unlock_path(const char *path)
Unlock a path.
Definition: main/app.c:2630
#define AST_LOG_WARNING
#define ast_verb(level,...)
#define LOG_WARNING
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:300
static ast_mutex_t reloadlock
Definition: loader.c:640
static int resource_name_match(const char *name1, size_t baselen1, const char *name2)
Definition: loader.c:927
static void queue_reload_request(const char *module)
Definition: loader.c:1600
static void publish_reload_message(const char *name, enum ast_module_reload_result result)
Definition: loader.c:1722
static size_t resource_name_baselen(const char *name)
Definition: loader.c:916
#define ast_mutex_unlock(a)
Definition: lock.h:194
#define ast_mutex_trylock(a)
Definition: lock.h:195
ast_module_reload_result
Possible return types for ast_module_reload.
Definition: module.h:109
#define ast_opt_lock_confdir
Definition: options.h:133
struct timeval ast_lastreloadtime
Definition: asterisk.c:343
const char * ast_config_AST_CONFIG_DIR
Definition: options.c:151
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159

References ast_config_AST_CONFIG_DIR, AST_DLLIST_LOCK, AST_DLLIST_TRAVERSE, AST_DLLIST_UNLOCK, ast_lastreloadtime, ast_lock_path(), AST_LOCK_SUCCESS, AST_LOCK_TIMEOUT, ast_log, AST_LOG_WARNING, 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_mutex_trylock, ast_mutex_unlock, ast_opt_lock_confdir, ast_sd_notify(), ast_tvnow(), ast_unlock_path(), ast_verb, ast_module::declined, ast_module::entry, ast_module::flags, sip_to_pjsip::info(), ast_module::info, LOG_WARNING, modules_loaded, name, publish_reload_message(), queue_reload_request(), reloadlock, ast_module::resource, resource_name_baselen(), resource_name_match(), and ast_module::running.

Referenced by action_reload(), action_updateconfig(), ast_ari_asterisk_reload_module(), ast_process_pending_reloads(), handle_cli_ael_reload(), handle_cli_moh_reload(), handle_core_reload(), handle_reload(), manager_moduleload(), monitor_sig_flags(), and reload_exec().

◆ ast_module_support_level_to_string()

const char * ast_module_support_level_to_string ( enum ast_module_support_level  support_level)

Definition at line 2934 of file loader.c.

2935{
2936 return support_level_map[support_level];
2937}
const char * support_level_map[]
Definition: loader.c:2927

References support_level_map.

Referenced by identify_module(), modlist_modentry(), and process_module_list().

◆ ast_module_unregister()

void ast_module_unregister ( const struct ast_module_info info)

Definition at line 777 of file loader.c.

778{
779 struct ast_module *mod = NULL;
780
781 /* it is assumed that the users list in the module structure
782 will already be empty, or we cannot have gotten to this
783 point
784 */
787 if (mod->info == info) {
789 break;
790 }
791 }
794
795 if (mod && !mod->usecount) {
796 /*
797 * We are intentionally leaking mod if usecount is not zero.
798 * This is necessary if the module is being forcefully unloaded.
799 * In addition module_destroy is not safe to run after exit()
800 * is called. ast_module_unregister is run during cleanup of
801 * the process when libc releases each module's shared object
802 * library.
803 */
804 ast_debug(5, "Unregistering module %s\n", info->name);
805 module_destroy(mod);
806 }
807}
#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: dlinkedlists.h:888
#define AST_DLLIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: dlinkedlists.h:753
#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_END
Closes a safe loop traversal block.
Definition: dlinkedlists.h:921
static void module_destroy(struct ast_module *mod)
Definition: loader.c:753

References ast_debug, AST_DLLIST_LOCK, AST_DLLIST_REMOVE_CURRENT, AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN, AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_END, AST_DLLIST_UNLOCK, ast_module::entry, sip_to_pjsip::info(), ast_module::info, module_destroy(), NULL, and ast_module::usecount.

◆ ast_refresh_resource()

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 1416 of file loader.c.

1417{
1418 if (recursive) {
1419 /* Recursively unload dependents of this module and then load them back again */
1420 int res, i;
1421 struct ast_vector_const_string dependents;
1422 AST_VECTOR_INIT(&dependents, 0);
1423 res = auto_unload_resource(resource_name, force, recursive, &dependents);
1424 if (res) {
1425 AST_VECTOR_FREE(&dependents);
1426 return 1;
1427 }
1428 /* Start by loading the target again. */
1429 if (ast_load_resource(resource_name)) {
1430 ast_log(LOG_WARNING, "Failed to load module '%s' again automatically\n", resource_name);
1431 AST_VECTOR_FREE(&dependents);
1432 return -1;
1433 }
1434 res = 0;
1435 /* Finally, load again any modules we had to unload in order to refresh the target.
1436 * We must load modules in the reverse order that we unloaded them,
1437 * to preserve dependency requirements. */
1438 for (i = 0; i < AST_VECTOR_SIZE(&dependents); i++) {
1439 const char *depname = AST_VECTOR_GET(&dependents, i);
1440 int mres = ast_load_resource(depname);
1441 if (mres) {
1442 ast_log(LOG_WARNING, "Could not load module '%s' again automatically\n", depname);
1443 }
1444 res |= mres;
1445 }
1446 AST_VECTOR_FREE(&dependents);
1447 return res ? -1 : 0;
1448 }
1449
1450 /* Simple case: just unload and load the module again */
1451 if (ast_unload_resource(resource_name, force)) {
1452 return 1;
1453 }
1454 return ast_load_resource(resource_name);
1455}
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:1294
enum ast_module_load_result ast_load_resource(const char *resource_name)
Load a module.
Definition: loader.c:1987
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:609
#define AST_VECTOR_FREE(vec)
Deallocates this vector.
Definition: vector.h:174
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:680

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

Referenced by handle_refresh(), and manager_moduleload().

◆ ast_register_application2()

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 104 of file pbx_app.c.

105{
106 struct ast_app *tmp;
107 struct ast_app *cur;
108 int length;
109#ifdef AST_XML_DOCS
110 char *tmpxml;
111#endif
112
114 cur = pbx_findapp_nolock(app);
115 if (cur) {
116 ast_log(LOG_WARNING, "Already have an application '%s'\n", app);
118 return -1;
119 }
120
121 length = sizeof(*tmp) + strlen(app) + 1;
122
123 if (!(tmp = ast_calloc(1, length))) {
125 return -1;
126 }
127
128 if (ast_string_field_init(tmp, 128)) {
130 ast_free(tmp);
131 return -1;
132 }
133
134 strcpy(tmp->name, app);
135 tmp->execute = execute;
136 tmp->module = mod;
137
138#ifdef AST_XML_DOCS
139 /* Try to lookup the docs in our XML documentation database */
141 /* load synopsis */
142 tmpxml = ast_xmldoc_build_synopsis("application", app, ast_module_name(tmp->module));
143 ast_string_field_set(tmp, synopsis, tmpxml);
144 ast_free(tmpxml);
145
146 /* load since */
147 tmpxml = ast_xmldoc_build_since("application", app, ast_module_name(tmp->module));
148 ast_string_field_set(tmp, since, tmpxml);
149 ast_free(tmpxml);
150
151 /* load description */
152 tmpxml = ast_xmldoc_build_description("application", app, ast_module_name(tmp->module));
153 ast_string_field_set(tmp, description, tmpxml);
154 ast_free(tmpxml);
155
156 /* load syntax */
157 tmpxml = ast_xmldoc_build_syntax("application", app, ast_module_name(tmp->module));
158 ast_string_field_set(tmp, syntax, tmpxml);
159 ast_free(tmpxml);
160
161 /* load arguments */
162 tmpxml = ast_xmldoc_build_arguments("application", app, ast_module_name(tmp->module));
163 ast_string_field_set(tmp, arguments, tmpxml);
164 ast_free(tmpxml);
165
166 /* load seealso */
167 tmpxml = ast_xmldoc_build_seealso("application", app, ast_module_name(tmp->module));
168 ast_string_field_set(tmp, seealso, tmpxml);
169 ast_free(tmpxml);
170 tmp->docsrc = AST_XML_DOC;
171 } else {
172#endif
175#ifdef AST_XML_DOCS
176 tmp->docsrc = AST_STATIC_DOC;
177 }
178#endif
179
180 /* Store in alphabetical order */
182 if (strcasecmp(tmp->name, cur->name) < 0) {
184 break;
185 }
186 }
188 if (!cur)
189 AST_RWLIST_INSERT_TAIL(&apps, tmp, list);
190
191 ast_verb(5, "Registered application '" COLORIZE_FMT "'\n", COLORIZE(COLOR_BRCYAN, 0, tmp->name));
192
194
195 return 0;
196}
static const char app[]
Definition: app_adsiprog.c:56
static char * synopsis
Definition: func_enum.c:166
static SQLHSTMT execute(struct odbc_obj *obj, void *data, int silent)
Common execution function for SQL queries.
Definition: func_odbc.c:485
#define AST_RWLIST_TRAVERSE_SAFE_BEGIN
Definition: linkedlists.h:545
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define AST_RWLIST_TRAVERSE_SAFE_END
Definition: linkedlists.h:617
#define AST_RWLIST_INSERT_TAIL
Definition: linkedlists.h:741
#define AST_RWLIST_INSERT_BEFORE_CURRENT
Definition: linkedlists.h:610
const char * ast_module_name(const struct ast_module *mod)
Get the name of a module.
Definition: loader.c:624
static struct ast_app * pbx_findapp_nolock(const char *name)
Definition: pbx_app.c:70
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:521
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
Registered applications container.
Definition: pbx_app.c:68
ast_app: A registered application
Definition: pbx_app.c:45
const ast_string_field since
Definition: pbx_app.c:54
const ast_string_field description
Definition: pbx_app.c:54
enum ast_doc_src docsrc
Definition: pbx_app.c:56
const ast_string_field seealso
Definition: pbx_app.c:54
const ast_string_field syntax
Definition: pbx_app.c:54
const ast_string_field arguments
Definition: pbx_app.c:54
int(* execute)(struct ast_channel *chan, const char *data)
Definition: pbx_app.c:46
#define COLOR_BRCYAN
Definition: term.h:63
#define COLORIZE(fg, bg, str)
Definition: term.h:72
#define COLORIZE_FMT
Shortcut macros for coloring a set of text.
Definition: term.h:71
char * ast_xmldoc_build_description(const char *type, const char *name, const char *module)
Generate description documentation from XML.
Definition: xmldoc.c:2356
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_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:2169
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:2333
char * ast_xmldoc_build_since(const char *type, const char *name, const char *module)
Parse the <since> node content.
Definition: xmldoc.c:1787
@ AST_XML_DOC
Definition: xmldoc.h:31
@ AST_STATIC_DOC
Definition: xmldoc.h:32
char * ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
Parse the <see-also> node content.
Definition: xmldoc.c:1702

References app, ast_app::arguments, ast_calloc, ast_free, ast_log, ast_module_name(), AST_RWLIST_INSERT_BEFORE_CURRENT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_string_field_init, ast_string_field_set, ast_strlen_zero(), ast_verb, AST_XML_DOC, ast_xmldoc_build_arguments(), ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_since(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), COLOR_BRCYAN, COLORIZE, COLORIZE_FMT, ast_app::description, ast_app::docsrc, execute(), ast_app::execute, LOG_WARNING, pbx_findapp_nolock(), ast_app::seealso, ast_app::since, synopsis, and ast_app::syntax.

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

◆ ast_unload_resource()

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 1457 of file loader.c.

1458{
1459 return auto_unload_resource(resource_name, force, 0, NULL);
1460}

References auto_unload_resource(), and NULL.

Referenced by ast_ari_asterisk_unload_module(), ast_load_resource(), ast_refresh_resource(), auto_unload_resource(), handle_unload(), manager_moduleload(), and unload_module().

◆ ast_unregister_application()

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.

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
404 cmp = strcasecmp(app, cur->name);
405 if (cmp > 0) {
406 continue;
407 }
408 if (!cmp) {
409 /* Found it. */
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 }
423
425
426 return cur ? 0 : -1;
427}
#define AST_RWLIST_REMOVE_CURRENT
Definition: linkedlists.h:570
void unreference_cached_app(struct ast_app *app)
Definition: pbx.c:6145
int ast_rdlock_contexts(void)
Read locks the context list.
Definition: pbx.c:8483
int ast_unlock_contexts(void)
Unlocks contexts.
Definition: pbx.c:8488
#define ast_string_field_free_memory(x)
free all memory - to be called before destroying the object
Definition: stringfields.h:374

References app, ast_free, ast_rdlock_contexts(), AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_string_field_free_memory, ast_unlock_contexts(), ast_verb, NULL, and unreference_cached_app().

Referenced by __unload_module(), load_module(), message_shutdown(), unload_module(), unload_parking_applications(), unload_pbx_builtins(), and unload_pbx_variables().

◆ ast_update_module_list()

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.
like

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

Definition at line 2746 of file loader.c.

2750{
2751 int total_mod_loaded = 0;
2752 struct module_vector alpha_module_list;
2753
2755
2756 if (!alpha_module_list_create(&alpha_module_list)) {
2757 int idx;
2758
2759 for (idx = 0; idx < AST_VECTOR_SIZE(&alpha_module_list); idx++) {
2760 struct ast_module *cur = AST_VECTOR_GET(&alpha_module_list, idx);
2761
2762 total_mod_loaded += modentry(cur->resource, cur->info->description, cur->usecount,
2763 cur->flags.running ? "Running" : "Not Running", like, cur->info->support_level);
2764 }
2765 }
2766
2768 AST_VECTOR_FREE(&alpha_module_list);
2769
2770 return total_mod_loaded;
2771}
static int alpha_module_list_create(struct module_vector *alpha_module_list)
Definition: loader.c:2729
enum ast_module_support_level support_level
Definition: module.h:430
const char * description
Definition: module.h:366

References alpha_module_list_create(), AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_module_info::description, ast_module::flags, ast_module::info, ast_module::resource, ast_module::running, ast_module_info::support_level, and ast_module::usecount.

Referenced by ast_var_Modules(), and handle_modlist().

◆ ast_update_module_list_condition()

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

Definition at line 2801 of file loader.c.

2807{
2808 int conditions_met = 0;
2809 struct module_vector alpha_module_list;
2810
2812
2813 if (!alpha_module_list_create(&alpha_module_list)) {
2814 int idx;
2815
2816 for (idx = 0; idx < AST_VECTOR_SIZE(&alpha_module_list); idx++) {
2817 struct ast_module *cur = AST_VECTOR_GET(&alpha_module_list, idx);
2818
2819 conditions_met += modentry(cur->resource, cur->info->description, cur->usecount,
2820 cur->flags.running? "Running" : "Not Running", like, cur->info->support_level, data,
2821 condition);
2822 }
2823 }
2824
2826 AST_VECTOR_FREE(&alpha_module_list);
2827
2828 return conditions_met;
2829}

References alpha_module_list_create(), AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_module_info::description, ast_module::flags, ast_module::info, ast_module::resource, ast_module::running, ast_module_info::support_level, and ast_module::usecount.

Referenced by ast_ari_asterisk_get_module().

◆ ast_update_module_list_data()

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 2773 of file loader.c.

2778{
2779 int total_mod_loaded = 0;
2780 struct module_vector alpha_module_list;
2781
2783
2784 if (!alpha_module_list_create(&alpha_module_list)) {
2785 int idx;
2786
2787 for (idx = 0; idx < AST_VECTOR_SIZE(&alpha_module_list); idx++) {
2788 struct ast_module *cur = AST_VECTOR_GET(&alpha_module_list, idx);
2789
2790 total_mod_loaded += modentry(cur->resource, cur->info->description, cur->usecount,
2791 cur->flags.running? "Running" : "Not Running", like, cur->info->support_level, data);
2792 }
2793 }
2794
2796 AST_VECTOR_FREE(&alpha_module_list);
2797
2798 return total_mod_loaded;
2799}

References alpha_module_list_create(), AST_DLLIST_LOCK, AST_DLLIST_UNLOCK, AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_module_info::description, ast_module::flags, ast_module::info, ast_module::resource, ast_module::running, ast_module_info::support_level, and ast_module::usecount.

Referenced by ast_ari_asterisk_list_modules().

◆ ast_update_use_count()

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 2707 of file loader.c.

2708{
2709 /* Notify any module monitors that the use count for a
2710 resource has changed */
2711 struct loadupdate *m;
2712
2715 m->updater();
2717}
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491

References AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, loadupdate::entry, and loadupdate::updater.

Referenced by __ast_module_ref(), __ast_module_unref(), __ast_module_user_add(), __ast_module_user_hangup_all(), __ast_module_user_remove(), auto_unload_resource(), ooh323_hangup(), ooh323_new(), ooh323c_call_thread(), start_resource(), and unistim_new().

Variable Documentation

◆ ast_module_info

const struct ast_module_info* ast_module_info
static

Definition at line 554 of file module.h.