Asterisk - The Open Source Telephony Project GIT-master-67613d1
Macros | Functions
asterisk.h File Reference

Asterisk main include file. File version handling, generic pbx functions. More...

#include "asterisk/autoconfig.h"
#include "asterisk/compat.h"
#include "asterisk/astmm.h"
Include dependency graph for asterisk.h:

Go to the source code of this file.

Macros

#define __stringify(x)   __stringify_1(x)
 
#define __stringify_1(x)   #x
 
#define AST_CURL_USER_AGENT   "asterisk-libcurl-agent/1.0"
 
#define AST_DIR_MODE   0777
 
#define AST_FILE_MODE   0666
 
#define DEFAULT_LANGUAGE   "en"
 
#define DEFAULT_SAMPLE_RATE   8000
 
#define DEFAULT_SAMPLES_PER_MS   ((DEFAULT_SAMPLE_RATE)/1000)
 
#define PATH_MAX   4096
 
#define sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__
 
#define setpriority   __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__
 
#define strtok   __PLEASE_USE_strtok_r_INSTEAD_OF_strtok__
 

Functions

int ast_add_profile (const char *, uint64_t scale)
 support for event profiling More...
 
int ast_cancel_shutdown (void)
 Cancel an existing shutdown and return to normal operation. More...
 
int ast_fd_init (void)
 
int64_t ast_mark (int, int start1_stop0)
 
int ast_pbx_init (void)
 
int ast_pbx_uuid_get (char *pbx_uuid, int length)
 Retrieve the PBX UUID. More...
 
int64_t ast_profile (int, int64_t)
 
int ast_register_atexit (void(*func)(void))
 Register a function to be executed before Asterisk exits. More...
 
int ast_register_cleanup (void(*func)(void))
 Register a function to be executed before Asterisk gracefully exits. More...
 
int ast_set_priority (int)
 We set ourselves to a high priority, that we might pre-empt everything else. If your PBX has heavy activity on it, this is a good thing. More...
 
int ast_shutdown_final (void)
 
int ast_shutting_down (void)
 
void ast_unregister_atexit (void(*func)(void))
 Unregister a function registered with ast_register_atexit(). More...
 

Detailed Description

Asterisk main include file. File version handling, generic pbx functions.

Definition in file asterisk.h.

Macro Definition Documentation

◆ __stringify

#define __stringify (   x)    __stringify_1(x)

Definition at line 216 of file asterisk.h.

◆ __stringify_1

#define __stringify_1 (   x)    #x

Definition at line 215 of file asterisk.h.

◆ AST_CURL_USER_AGENT

#define AST_CURL_USER_AGENT   "asterisk-libcurl-agent/1.0"

Definition at line 44 of file asterisk.h.

◆ AST_DIR_MODE

#define AST_DIR_MODE   0777

Definition at line 29 of file asterisk.h.

◆ AST_FILE_MODE

#define AST_FILE_MODE   0666

Definition at line 32 of file asterisk.h.

◆ DEFAULT_LANGUAGE

#define DEFAULT_LANGUAGE   "en"

Definition at line 46 of file asterisk.h.

◆ DEFAULT_SAMPLE_RATE

#define DEFAULT_SAMPLE_RATE   8000

Definition at line 48 of file asterisk.h.

◆ DEFAULT_SAMPLES_PER_MS

#define DEFAULT_SAMPLES_PER_MS   ((DEFAULT_SAMPLE_RATE)/1000)

Definition at line 49 of file asterisk.h.

◆ PATH_MAX

#define PATH_MAX   4096

Definition at line 40 of file asterisk.h.

◆ sched_setscheduler

#define sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__

Definition at line 51 of file asterisk.h.

◆ setpriority

#define setpriority   __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__

Definition at line 50 of file asterisk.h.

◆ strtok

#define strtok   __PLEASE_USE_strtok_r_INSTEAD_OF_strtok__

Definition at line 52 of file asterisk.h.

Function Documentation

◆ ast_add_profile()

int ast_add_profile ( const char *  name,
uint64_t  scale 
)

support for event profiling

(note, this must be documented a lot more) ast_add_profile allocates a generic 'counter' with a given name, which can be shown with the command 'core show profile <name>'

The counter accumulates positive or negative values supplied by

See also
ast_add_profile(), dividing them by the 'scale' value passed in the create call, and also counts the number of 'events'. Values can also be taked by the TSC counter on ia32 architectures, in which case you can mark the start of an event calling ast_mark(id, 1) and then the end of the event with ast_mark(id, 0). For non-i386 architectures, these two calls return 0.

support for event profiling

Returns
Returns the identifier of the counter.

Definition at line 92 of file astman.c.

93{
94 return -1;
95}

References ast_calloc, ast_realloc, ast_strdup, profile_data::e, profile_data::entries, profile_entry::events, profile_entry::mark, profile_data::max_size, name, profile_entry::name, no_comp, NULL, prof_data, profile_entry::scale, and profile_entry::value.

Referenced by extension_match_core().

◆ ast_cancel_shutdown()

int ast_cancel_shutdown ( void  )

Cancel an existing shutdown and return to normal operation.

Note
Shutdown can be cancelled while the server is waiting for any existing channels to be destroyed before shutdown becomes irreversible.
Returns
non-zero if shutdown cancelled.

Definition at line 1877 of file asterisk.c.

1878{
1879 int shutdown_aborted = 0;
1880
1882 if (shuttingdown >= SHUTDOWN_FAST) {
1884 shutdown_pending = 0;
1885 shutdown_aborted = 1;
1886 }
1888 return shutdown_aborted;
1889}
static shutdown_nice_t shuttingdown
Definition: asterisk.c:378
static int shutdown_pending
Definition: asterisk.c:381
@ SHUTDOWN_FAST
Definition: asterisk.c:369
@ NOT_SHUTTING_DOWN
Definition: asterisk.c:358
static ast_mutex_t safe_system_lock
Definition: asterisk.c:1093
#define ast_mutex_unlock(a)
Definition: lock.h:190
#define ast_mutex_lock(a)
Definition: lock.h:189

References ast_mutex_lock, ast_mutex_unlock, NOT_SHUTTING_DOWN, safe_system_lock, SHUTDOWN_FAST, shutdown_pending, and shuttingdown.

Referenced by handle_abort_shutdown().

◆ ast_fd_init()

int ast_fd_init ( void  )

Provided by astfd.c

Definition at line 370 of file astfd.c.

371{
372 return 0;
373}

Referenced by asterisk_daemon().

◆ ast_mark()

int64_t ast_mark ( int  key,
int  start1_stop0 
)

◆ ast_pbx_init()

int ast_pbx_init ( void  )

Provided by pbx.c

Definition at line 8989 of file pbx.c.

8990{
8993 if (hints) {
8995 }
8998 if (hintdevices) {
9000 }
9001 /* This is protected by the context_and_merge lock */
9004 if (autohints) {
9006 }
9008 if (statecbs) {
9010 }
9011
9013
9014 if (STASIS_MESSAGE_TYPE_INIT(hint_change_message_type) != 0) {
9015 return -1;
9016 }
9017 if (STASIS_MESSAGE_TYPE_INIT(hint_remove_message_type) != 0) {
9018 return -1;
9019 }
9020
9021 return (hints && hintdevices && autohints && statecbs) ? 0 : -1;
9022}
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
int ao2_container_register(const char *name, struct ao2_container *self, ao2_prnt_obj_fn *prnt_obj)
Register a container for CLI stats and integrity check.
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Allocate and initialize a list container.
Definition: astobj2.h:1327
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
static struct ao2_container * statecbs
Definition: pbx.c:808
static void print_autohint_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8969
static void print_statecbs_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8979
static int hint_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:8896
static struct ao2_container * autohints
Container for autohint contexts.
Definition: pbx.c:387
static int hintdevice_hash_cb(const void *obj, const int flags)
Definition: pbx.c:402
static int hint_hash(const void *obj, const int flags)
Definition: pbx.c:8876
static int statecbs_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:8904
static int autohint_hash_cb(const void *obj, const int flags)
Definition: pbx.c:460
static void print_hintdevices_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8957
static struct ao2_container * hintdevices
Container for hint devices.
Definition: pbx.c:370
static void print_hints_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8946
#define HASH_EXTENHINT_SIZE
Definition: pbx.c:365
static int hintdevice_cmp_multiple(void *obj, void *arg, int flags)
Definition: pbx.c:428
static void pbx_shutdown(void)
Definition: pbx.c:8916
static int autohint_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:481
#define NULL
Definition: resample.c:96
#define STASIS_MESSAGE_TYPE_INIT(name)
Boiler-plate messaging macro for initializing message types.
Definition: stasis.h:1493

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_container_alloc_hash, ao2_container_alloc_list, ao2_container_register(), ast_register_cleanup(), autohint_cmp(), autohint_hash_cb(), autohints, HASH_EXTENHINT_SIZE, hint_cmp(), hint_hash(), hintdevice_cmp_multiple(), hintdevice_hash_cb(), hintdevices, NULL, pbx_shutdown(), print_autohint_key(), print_hintdevices_key(), print_hints_key(), print_statecbs_key(), STASIS_MESSAGE_TYPE_INIT, statecbs, and statecbs_cmp().

Referenced by asterisk_daemon().

◆ ast_pbx_uuid_get()

int ast_pbx_uuid_get ( char *  pbx_uuid,
int  length 
)

Retrieve the PBX UUID.

Parameters
pbx_uuidA buffer of at least AST_UUID_STR_LEN (36 + 1) size to receive the UUID
lengthThe buffer length

Definition at line 972 of file asterisk.c.

973{
974 return ast_db_get("pbx", "UUID", pbx_uuid, length);
975}
int ast_db_get(const char *family, const char *key, char *value, int valuelen)
Get key value specified by family/key.
Definition: main/db.c:427

References ast_db_get().

Referenced by asterisk_daemon(), and handle_show_settings().

◆ ast_profile()

int64_t ast_profile ( int  key,
int64_t  val 
)

Definition at line 98 of file astman.c.

99{
100 return 0;
101}

References profile_data::e, profile_data::entries, profile_entry::events, prof_data, profile_entry::scale, and profile_entry::value.

◆ ast_register_atexit()

int ast_register_atexit ( void(*)(void)  func)

Register a function to be executed before Asterisk exits.

Parameters
funcThe callback function to use.
Return values
0on success.
-1on error.
Note
This function should be rarely used in situations where something must be shutdown to avoid corruption, excessive data loss, or when external programs must be stopped. All other cleanup in the core should use ast_register_cleanup.

Definition at line 13 of file clicompat.c.

14{
15 return 0;
16}

References ast_atexit::func, and register_atexit().

Referenced by astdb_init(), asterisk_daemon(), and load_module().

◆ ast_register_cleanup()

int ast_register_cleanup ( void(*)(void)  func)

Register a function to be executed before Asterisk gracefully exits.

Since
11.9

If Asterisk is immediately shutdown (core stop now, or sending the TERM signal), the callback is not run. When the callbacks are run, they are run in sequence with ast_register_atexit() callbacks, in the reverse order of registration.

Parameters
funcThe callback function to use.
Return values
0on success.
-1on error.

Definition at line 19 of file clicompat.c.

20{
21 return 0;
22}

References ast_atexit::func, and register_atexit().

Referenced by aco_init(), app_init(), ast_aoc_cli_init(), ast_autoservice_init(), ast_bridging_init(), ast_bucket_init(), ast_builtins_init(), ast_channels_init(), ast_cli_channels_init(), ast_codec_init(), ast_device_state_engine_init(), ast_dns_system_resolver_init(), ast_endpoint_init(), ast_endpoint_stasis_init(), ast_file_init(), ast_format_cache_init(), ast_format_init(), ast_image_init(), ast_local_init(), ast_media_cache_init(), ast_msg_init(), ast_named_locks_init(), ast_parking_stasis_init(), ast_pbx_init(), ast_pickup_init(), ast_presence_state_engine_init(), ast_refer_init(), ast_rtp_engine_init(), ast_security_stasis_init(), ast_sorcery_init(), ast_stasis_bridging_init(), ast_stasis_channels_init(), ast_stasis_system_init(), ast_stun_init(), ast_test_init(), ast_timing_init(), ast_tps_init(), ast_translate_init(), ast_utils_init(), asterisk_daemon(), astobj2_init(), container_init(), devstate_init(), dns_core_init(), load_module(), load_pbx(), load_pbx_app(), load_pbx_builtins(), load_pbx_functions_cli(), load_pbx_hangup_handler(), load_pbx_switch(), load_pbx_variables(), manager_bridging_init(), manager_channels_init(), manager_endpoints_init(), manager_mwi_init(), manager_system_init(), mwi_init(), register_config_cli(), stasis_cache_init(), stasis_init(), and xmldoc_load_documentation().

◆ ast_set_priority()

int ast_set_priority ( int  pri)

We set ourselves to a high priority, that we might pre-empt everything else. If your PBX has heavy activity on it, this is a good thing.

Provided by asterisk.c

Definition at line 1837 of file asterisk.c.

1838{
1839 struct sched_param sched;
1840 memset(&sched, 0, sizeof(sched));
1841#ifdef __linux__
1842 if (pri) {
1843 sched.sched_priority = 10;
1844 if (sched_setscheduler(0, SCHED_RR, &sched)) {
1845 return -1;
1846 }
1847 } else {
1848 sched.sched_priority = 0;
1849 /* According to the manpage, these parameters can never fail. */
1850 sched_setscheduler(0, SCHED_OTHER, &sched);
1851 }
1852#else
1853 if (pri) {
1854 if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
1855 ast_log(LOG_WARNING, "Unable to set high priority\n");
1856 return -1;
1857 } else
1858 ast_verb(1, "Set to high priority\n");
1859 } else {
1860 /* According to the manpage, these parameters can never fail. */
1861 setpriority(PRIO_PROCESS, 0, 0);
1862 }
1863#endif
1864 return 0;
1865}
#define sched_setscheduler
Definition: asterisk.h:51
#define setpriority
Definition: asterisk.h:50
#define ast_log
Definition: astobj2.c:42
#define ast_verb(level,...)
#define LOG_WARNING
Definition: sched.c:76

References ast_log, ast_verb, LOG_WARNING, sched_setscheduler, and setpriority.

Referenced by app_exec(), asterisk_daemon(), launch_script(), main(), mp3play(), safe_exec_prep(), send_waveform_to_fd(), set_priority_all(), and spawn_mp3().

◆ ast_shutdown_final()

int ast_shutdown_final ( void  )
Returns
non-zero if the server is actively shutting down.
Since
13.3.0

The server is releasing resources and unloading modules. It won't be long now.

Definition at line 1867 of file asterisk.c.

1868{
1870}
@ SHUTTING_DOWN_FINAL
Definition: asterisk.c:360

References SHUTTING_DOWN_FINAL, and shuttingdown.

Referenced by httpd_process_request(), load_resource(), send_notify(), session_inv_on_media_update(), session_inv_on_redirected(), session_inv_on_rx_offer(), session_inv_on_state_changed(), session_inv_on_tsx_state_changed(), and unload_module().

◆ ast_shutting_down()

int ast_shutting_down ( void  )

The server is preventing new channel creation in preparation for shutdown and may actively be releasing resources. The shutdown process may be canceled by ast_cancel_shutdown() if it is not too late.

Note
The preparation to shutdown phase can be quite lengthy if we are gracefully shutting down. How long existing calls will last is not up to us.
Returns
non-zero if the server is preparing to or actively shutting down.

Definition at line 1872 of file asterisk.c.

1873{
1874 return shutdown_pending;
1875}

References shutdown_pending.

Referenced by __ast_channel_alloc_ap(), ast_cli_command_full(), ast_unregister_translator(), confbridge_exec(), options_on_rx_request(), and process_message().

◆ ast_unregister_atexit()

void ast_unregister_atexit ( void(*)(void)  func)

Unregister a function registered with ast_register_atexit().

Parameters
funcThe callback function to unregister.

Definition at line 1060 of file asterisk.c.

1061{
1065}
static void __ast_unregister_atexit(void(*func)(void))
Definition: asterisk.c:1017
#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

References __ast_unregister_atexit(), AST_LIST_LOCK, AST_LIST_UNLOCK, and ast_atexit::func.

Referenced by unload_module().