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.

{
    return -1;
}

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

{
    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;
}

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 371 of file astfd.c.

{
    return 0;
}

Referenced by asterisk_daemon().

ast_mark()

int64_t ast_mark	(	int	key,
		int	start1_stop0
	)

Definition at line 103 of file astman.c.

{
    return 0;
}

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

Referenced by __ast_pthread_mutex_lock(), and extension_match_core().

ast_pbx_init()

int ast_pbx_init

(

void

)

Provided by pbx.c

Definition at line 8989 of file pbx.c.

{
    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;
}

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_uuid	A buffer of at least AST_UUID_STR_LEN (36 + 1) size to receive the UUID
length	The buffer length

Definition at line 973 of file asterisk.c.

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

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.

{
    return 0;
}

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

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.

{
    return 0;
}

References ast_atexit::func, and register_atexit().

Referenced by ast_rtp_engine_init(), ast_stun_init(), 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

func	The callback function to use.

Return values

0	on success.
-1	on error.

Definition at line 19 of file clicompat.c.

{
    return 0;
}

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_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 1842 of file asterisk.c.

{
    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;
}

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

{
    return shuttingdown == SHUTTING_DOWN_FINAL;
}

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

{
    return shutdown_pending;
}

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

func	The callback function to unregister.

Definition at line 1061 of file asterisk.c.

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

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

Referenced by unload_module().