Asterisk - The Open Source Telephony Project  GIT-master-44aef04
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"

Go to the source code of this file.

Macros

#define __stringify(x)   __stringify_1(x)
 
#define __stringify_1(x)   #x
 
#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)

◆ __stringify_1

#define __stringify_1 (   x)    #x

Definition at line 213 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

◆ DEFAULT_LANGUAGE

#define DEFAULT_LANGUAGE   "en"

Definition at line 44 of file asterisk.h.

Referenced by fileexists_core().

◆ DEFAULT_SAMPLE_RATE

#define DEFAULT_SAMPLE_RATE   8000

Definition at line 46 of file asterisk.h.

Referenced by check_header(), ogg_vorbis_open(), ogg_vorbis_rewrite(), setformat(), and write_header().

◆ DEFAULT_SAMPLES_PER_MS

#define DEFAULT_SAMPLES_PER_MS   ((DEFAULT_SAMPLE_RATE)/1000)

Definition at line 47 of file asterisk.h.

Referenced by ast_stream_fastforward(), ast_stream_rewind(), and isAnsweringMachine().

◆ PATH_MAX

#define PATH_MAX   4096
Examples:
/tmp/asterisk-shallow/main/app.c.

Definition at line 40 of file asterisk.h.

Referenced by __ast_play_and_record(), action_createconfig(), actual_load_config(), add_email_attachment(), add_menu_entry(), add_notify(), adsi_message(), advanced_options(), announce_thread(), app_exec(), append_mailbox(), ast_config_text_file_save2(), ast_logger_rotate_channel(), AST_TEST_DEFINE(), asterisk_daemon(), bucket_file_update_path(), chanspy_exec(), close_mailbox(), conf_rec_name(), conf_run(), copy_message(), copy_plain_file(), create_destination_directory(), delete_config_file(), determine_starting_point(), extenspy_exec(), filename_parse(), find_logchannel(), forward_message(), free_zone(), get_folder(), header_identify_match_check(), iax_firmware_reload(), invent_message(), is_module_loaded(), leave_voicemail(), load_dynamic_module(), load_module(), load_values_config(), logger_queue_init(), logger_queue_restart(), main(), manager_mixmonitor(), manager_modulecheck(), media_cache_handle_refresh_item(), message_range_and_existence_check(), minivm_accmess_exec(), minivm_greet_exec(), minivm_mwi_exec(), minivm_notify_exec(), moh_scan_files(), msg_create_from_file(), notify_new_message(), play_message(), play_message_callerid(), play_record_review(), post_raw(), pp_each_extension_helper(), record_exec(), recordthread(), rename_file(), resequence_mailbox(), rotate_file(), save_to_folder(), sayname(), sendmail(), sendpage(), start_mixmonitor_callback(), test_vm_api_create_voicemail_files(), test_vm_api_remove_voicemail(), testserver_exec(), vm_allocate_dh(), vm_change_password(), vm_forwardoptions(), vm_msg_forward(), vm_msg_play(), vm_msg_snapshot_create(), vm_newuser_setup(), vm_options(), vm_tempgreeting(), vmsayname_exec(), write_config_file(), and writefile_account().

◆ sched_setscheduler

#define sched_setscheduler   __PLEASE_USE_ast_set_priority_INSTEAD_OF_sched_setscheduler__

Definition at line 49 of file asterisk.h.

Referenced by ast_set_priority(), and set_priority_all().

◆ setpriority

#define setpriority   __PLEASE_USE_ast_set_priority_INSTEAD_OF_setpriority__

Definition at line 48 of file asterisk.h.

Referenced by ast_set_priority(), and main().

◆ strtok

#define strtok   __PLEASE_USE_strtok_r_INSTEAD_OF_strtok__

Definition at line 50 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.

References ast_calloc, ast_log(), ast_profile(), ast_realloc, ast_strdup, profile_data::e, profile_data::entries, profile_entry::events, make_ari_stubs::file, format, profile_entry::mark, profile_data::max_size, profile_entry::name, NULL, console::p, profile_entry::scale, and profile_entry::value.

Referenced by ao2_weakproxy_unsubscribe(), and extension_match_core().

93 {
94  return -1;
95 }

◆ 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 1839 of file asterisk.c.

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

Referenced by handle_abort_shutdown().

1840 {
1841  int shutdown_aborted = 0;
1842 
1844  if (shuttingdown >= SHUTDOWN_FAST) {
1846  shutdown_pending = 0;
1847  shutdown_aborted = 1;
1848  }
1850  return shutdown_aborted;
1851 }
static ast_mutex_t safe_system_lock
Definition: asterisk.c:1055
#define ast_mutex_lock(a)
Definition: lock.h:187
static int shutdown_pending
Definition: asterisk.c:381
static shutdown_nice_t shuttingdown
Definition: asterisk.c:378
#define ast_mutex_unlock(a)
Definition: lock.h:188

◆ ast_fd_init()

int ast_fd_init ( void  )

Provided by astfd.c

Definition at line 370 of file astfd.c.

Referenced by asterisk_daemon().

371 {
372  return 0;
373 }

◆ 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 8982 of file pbx.c.

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(), HASH_EXTENHINT_SIZE, hint_cmp(), hint_hash(), hintdevice_cmp_multiple(), hintdevice_hash_cb(), NULL, pbx_shutdown(), print_autohint_key(), print_hintdevices_key(), print_hints_key(), print_statecbs_key(), STASIS_MESSAGE_TYPE_INIT, and statecbs_cmp().

Referenced by asterisk_daemon().

8983 {
8986  if (hints) {
8988  }
8991  if (hintdevices) {
8993  }
8994  /* This is protected by the context_and_merge lock */
8997  if (autohints) {
8999  }
9001  if (statecbs) {
9003  }
9004 
9006 
9007  if (STASIS_MESSAGE_TYPE_INIT(hint_change_message_type) != 0) {
9008  return -1;
9009  }
9010  if (STASIS_MESSAGE_TYPE_INIT(hint_remove_message_type) != 0) {
9011  return -1;
9012  }
9013 
9014  return (hints && hintdevices && autohints && statecbs) ? 0 : -1;
9015 }
static void print_autohint_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8962
static int hint_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:8889
#define STASIS_MESSAGE_TYPE_INIT(name)
Boiler-plate messaging macro for initializing message types.
Definition: stasis.h:1501
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn)
Definition: astobj2.h:1335
static struct ao2_container * hintdevices
Container for hint devices.
Definition: pbx.c:363
static int hint_hash(const void *obj, const int flags)
Definition: pbx.c:8869
static void print_statecbs_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8972
#define NULL
Definition: resample.c:96
static int hintdevice_cmp_multiple(void *obj, void *arg, int flags)
Definition: pbx.c:421
static int statecbs_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:8897
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.
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
#define HASH_EXTENHINT_SIZE
Definition: pbx.c:358
static void pbx_shutdown(void)
Definition: pbx.c:8909
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Definition: astobj2.h:1310
static int autohint_cmp(void *obj, void *arg, int flags)
Definition: pbx.c:474
static int autohint_hash_cb(const void *obj, const int flags)
Definition: pbx.c:453
static void print_hintdevices_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8950
static struct ao2_container * statecbs
Definition: pbx.c:803
static int hintdevice_hash_cb(const void *obj, const int flags)
Definition: pbx.c:395
static void print_hints_key(void *v_obj, void *where, ao2_prnt_fn *prnt)
Definition: pbx.c:8939
static struct ao2_container * autohints
Container for autohint contexts.
Definition: pbx.c:380

◆ 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 934 of file asterisk.c.

References ast_db_get().

Referenced by asterisk_daemon(), and handle_show_settings().

935 {
936  return ast_db_get("pbx", "UUID", pbx_uuid, length);
937 }
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:412

◆ ast_profile()

int64_t ast_profile ( int  key,
int64_t  val 
)

Definition at line 98 of file astman.c.

References ast_mark(), profile_data::e, profile_data::entries, profile_entry::events, rdtsc(), profile_entry::scale, and profile_entry::value.

Referenced by ast_add_profile().

99 {
100  return 0;
101 }

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

References ast_register_cleanup(), ast_atexit::func, and register_atexit().

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

14 {
15  return 0;
16 }

◆ 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.
Examples:
/tmp/asterisk-shallow/main/app.c.

Definition at line 19 of file clicompat.c.

References __ast_cli_register_multiple(), ast_atexit::func, len(), 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_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_register_atexit(), 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_utf8_validator_destroy(), ast_utils_init(), ast_xmldoc_load_documentation(), 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 threadstorage_init().

20 {
21  return 0;
22 }

◆ ast_set_priority()

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.

Provided by asterisk.c

Definition at line 1799 of file asterisk.c.

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

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

1800 {
1801  struct sched_param sched;
1802  memset(&sched, 0, sizeof(sched));
1803 #ifdef __linux__
1804  if (pri) {
1805  sched.sched_priority = 10;
1806  if (sched_setscheduler(0, SCHED_RR, &sched)) {
1807  return -1;
1808  }
1809  } else {
1810  sched.sched_priority = 0;
1811  /* According to the manpage, these parameters can never fail. */
1812  sched_setscheduler(0, SCHED_OTHER, &sched);
1813  }
1814 #else
1815  if (pri) {
1816  if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
1817  ast_log(LOG_WARNING, "Unable to set high priority\n");
1818  return -1;
1819  } else
1820  ast_verb(1, "Set to high priority\n");
1821  } else {
1822  /* According to the manpage, these parameters can never fail. */
1823  setpriority(PRIO_PROCESS, 0, 0);
1824  }
1825 #endif
1826  return 0;
1827 }
#define LOG_WARNING
Definition: logger.h:274
Definition: sched.c:76
#define ast_verb(level,...)
Definition: logger.h:455
#define ast_log
Definition: astobj2.c:42
#define sched_setscheduler
Definition: asterisk.h:49
#define setpriority
Definition: asterisk.h:48

◆ 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 1829 of file asterisk.c.

References SHUTTING_DOWN_FINAL, and shuttingdown.

Referenced by get_name_from_resource(), 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(), and session_inv_on_tsx_state_changed().

1830 {
1832 }
static shutdown_nice_t shuttingdown
Definition: asterisk.c:378

◆ 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 1834 of file asterisk.c.

References shutdown_pending.

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

1835 {
1836  return shutdown_pending;
1837 }
static int shutdown_pending
Definition: asterisk.c:381

◆ 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 1022 of file asterisk.c.

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

Referenced by unload_module().

1023 {
1027 }
static void __ast_unregister_atexit(void(*func)(void))
Definition: asterisk.c:979
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139