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_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 214 of file asterisk.h.

Referenced by ast_sip_initialize_sorcery_global(), ast_sip_initialize_system(), conf_load_config(), load_config(), load_module(), stir_shaken_general_load(), and udptl_pre_apply_config().

__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

Examples:

/usr/src/asterisk-18.5.0/main/app.c.

Definition at line 32 of file asterisk.h.

Referenced by __ast_play_and_record(), action_createconfig(), ast_lock_path_lockfile(), ast_monitor_start(), bucket_copy(), chanspy_exec(), convert_bdb_to_sqlite3(), copy(), create_bdb_astdb(), dahdi_cc_callback(), dictate_exec(), extenspy_exec(), festival_exec(), handle_cli_file_convert(), handle_recordfile(), record_exec(), recordthread(), sms_log(), and try_firmware().

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:

/usr/src/asterisk-18.5.0/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(), 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().

{
   return -1;
}

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().

{
   int shutdown_aborted = 0;

   ast_mutex_lock(&safe_system_lock);
   if (shuttingdown >= SHUTDOWN_FAST) {
      shuttingdown = NOT_SHUTTING_DOWN;
      shutdown_pending = 0;
      shutdown_aborted = 1;
   }
   ast_mutex_unlock(&safe_system_lock);
   return shutdown_aborted;
}

ast_fd_init()

int ast_fd_init

(

void

)

Provided by astfd.c

Definition at line 370 of file astfd.c.

Referenced by asterisk_daemon().

{
   return 0;
}

ast_mark()

int64_t ast_mark	(	int	key,
		int	start1_stop0
	)

Definition at line 103 of file astman.c.

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

Referenced by __ast_pthread_mutex_lock(), ao2_weakproxy_unsubscribe(), ast_profile(), and extension_match_core().

{
   return 0;
}

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().

{
   hints = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
      HASH_EXTENHINT_SIZE, hint_hash, NULL, hint_cmp);
   if (hints) {
      ao2_container_register("hints", hints, print_hints_key);
   }
   hintdevices = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
      HASH_EXTENHINT_SIZE, hintdevice_hash_cb, NULL, hintdevice_cmp_multiple);
   if (hintdevices) {
      ao2_container_register("hintdevices", hintdevices, print_hintdevices_key);
   }
   /* This is protected by the context_and_merge lock */
   autohints = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_NOLOCK, 0, HASH_EXTENHINT_SIZE,
      autohint_hash_cb, NULL, autohint_cmp);
   if (autohints) {
      ao2_container_register("autohints", autohints, print_autohint_key);
   }
   statecbs = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_MUTEX, 0, NULL, statecbs_cmp);
   if (statecbs) {
      ao2_container_register("statecbs", statecbs, print_statecbs_key);
   }

   ast_register_cleanup(pbx_shutdown);

   if (STASIS_MESSAGE_TYPE_INIT(hint_change_message_type) != 0) {
      return -1;
   }
   if (STASIS_MESSAGE_TYPE_INIT(hint_remove_message_type) != 0) {
      return -1;
   }

   return (hints && hintdevices && autohints && statecbs) ? 0 : -1;
}

ast_pbx_uuid_get()

int ast_pbx_uuid_get	(	char *	pbx_uuid,
		int	length
	)

Retrieve the PBX UUID.

Parameters

pbx_uuid	A buffer of at least AST_UUID_STR_LEN (36 + 1) size to receive the UUID
length	The buffer length

Definition at line 934 of file asterisk.c.

References ast_db_get().

Referenced by asterisk_daemon(), and handle_show_settings().

{
   return ast_db_get("pbx", "UUID", pbx_uuid, length);
}

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().

{
   return 0;
}

ast_register_atexit()

int ast_register_atexit

(

void(*)(void)

func

)

Register a function to be executed before Asterisk exits.

Parameters

func	The callback function to use.

Return values

0	on success.
-1	on 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().

{
   return 0;
}

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

func	The callback function to use.

Return values

0	on success.
-1	on error.

Examples:

/usr/src/asterisk-18.5.0/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_init(), 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().

{
   return 0;
}

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().

{
   struct sched_param sched;
   memset(&sched, 0, sizeof(sched));
#ifdef __linux__
   if (pri) {
      sched.sched_priority = 10;
      if (sched_setscheduler(0, SCHED_RR, &sched)) {
         return -1;
      }
   } else {
      sched.sched_priority = 0;
      /* According to the manpage, these parameters can never fail. */
      sched_setscheduler(0, SCHED_OTHER, &sched);
   }
#else
   if (pri) {
      if (setpriority(PRIO_PROCESS, 0, -10) == -1) {
         ast_log(LOG_WARNING, "Unable to set high priority\n");
         return -1;
      } else
         ast_verb(1, "Set to high priority\n");
   } else {
      /* According to the manpage, these parameters can never fail. */
      setpriority(PRIO_PROCESS, 0, 0);
   }
#endif
   return 0;
}

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().

{
   return shuttingdown == SHUTTING_DOWN_FINAL;
}

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().

{
   return shutdown_pending;
}

ast_unregister_atexit()

void ast_unregister_atexit

(

void(*)(void)

func

)

Unregister a function registered with ast_register_atexit().

Parameters

func	The 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().

{
   AST_LIST_LOCK(&atexits);
   __ast_unregister_atexit(func);
   AST_LIST_UNLOCK(&atexits);
}