include/asterisk/app.h File Reference

Application convenience functions, designed to give consistent look and feel to Asterisk apps. More...

#include "asterisk/stringfields.h"
#include "asterisk/strings.h"
#include "asterisk/threadstorage.h"
#include "asterisk/file.h"
#include "asterisk/linkedlists.h"
#include "asterisk/utils.h"
#include "asterisk/stasis.h"

Include dependency graph for include/asterisk/app.h:

Go to the source code of this file.

Data Structures
struct	ast_app_option
	A structure to hold the description of an application 'option'. More...
struct	ast_app_stack_funcs
	Stack applications callback functions. More...
struct	ast_ivr_menu
struct	ast_ivr_option
struct	ast_vm_functions
	Voicemail function table definition. More...
struct	ast_vm_greeter_functions
	Voicemail greeter function table definition. More...
struct	ast_vm_mailbox_snapshot
struct	ast_vm_msg_snapshot
struct	ast_vm_recording_data
	Structure used for ast_copy_recording_to_vm in order to cleanly supply data needed for making the recording from the recorded file. More...

Macros
#define	AST_APP_ARG(name)   char *name
	Define an application argument. More...
#define	AST_APP_OPTION(option, flagno)   [option] = { .flag = flagno }
	Declares an application option that does not accept an argument. More...
#define	AST_APP_OPTION_ARG(option, flagno, argno)   [option] = { .flag = flagno, .arg_index = argno + 1 }
	Declares an application option that accepts an argument. More...
#define	AST_APP_OPTIONS(holder, options...)   static const struct ast_app_option holder[128] = options
	Declares an array of options for an application. More...
#define	ast_app_separate_args(a, b, c, d)   __ast_app_separate_args(a,b,1,c,d)
#define	AST_DECLARE_APP_ARGS(name, arglist)   AST_DEFINE_APP_ARGS_TYPE(argtype_##name, arglist) name = { 0, }
	Declare a structure to hold an application's arguments. More...
#define	AST_DEFINE_APP_ARGS_TYPE(type, arglist)
	Define a structure type to hold an application's arguments. More...
#define	AST_IVR_DECLARE_MENU(holder, title, flags, foo...)
#define	AST_IVR_FLAG_AUTORESTART   (1 << 0)
#define	AST_NONSTANDARD_APP_ARGS(args, parse, sep)   args.argc = __ast_app_separate_args(parse, sep, 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
	Performs the 'nonstandard' argument separation process for an application. More...
#define	AST_NONSTANDARD_RAW_ARGS(args, parse, sep)   args.argc = __ast_app_separate_args(parse, sep, 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
#define	AST_STANDARD_APP_ARGS(args, parse)   args.argc = __ast_app_separate_args(parse, ',', 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
	Performs the 'standard' argument separation process for an application. More...
#define	AST_STANDARD_RAW_ARGS(args, parse)   args.argc = __ast_app_separate_args(parse, ',', 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
#define	ast_vm_greeter_register(vm_table)   __ast_vm_greeter_register(vm_table, AST_MODULE_SELF)
	See __ast_vm_greeter_register() More...
#define	ast_vm_register(vm_table)   __ast_vm_register(vm_table, AST_MODULE_SELF)
	See __ast_vm_register() More...
#define	BEGIN_OPTIONS   {
#define	END_OPTIONS   }
#define	VM_GREETER_MODULE_VERSION   1
#define	VM_MODULE_VERSION   2

Typedefs
typedef int()	ast_copy_recording_to_vm_fn(struct ast_vm_recording_data *vm_rec_data)
	Creates a voicemail based on a specified file to a mailbox. More...
typedef int()	ast_has_voicemail_fn(const char *mailboxes, const char *folder)
	Determines if the given folder has messages. More...
typedef int()	ast_inboxcount2_fn(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs)
	Gets the number of messages that exist for the mailbox list. More...
typedef int()	ast_inboxcount_fn(const char *mailboxes, int *newmsgs, int *oldmsgs)
	Gets the number of messages that exist for the mailbox list. More...
typedef int()	ast_ivr_callback(struct ast_channel *chan, char *option, void *cbdata)
	Callback function for IVR. More...
typedef int()	ast_messagecount_fn(const char *mailbox_id, const char *folder)
	Gets the number of messages that exist in a mailbox folder. More...
typedef int()	ast_sayname_fn(struct ast_channel *chan, const char *mailbox_id)
	Play a recorded user name for the mailbox to the specified channel. More...
typedef const char *()	ast_vm_index_to_foldername_fn(int id)
	Convert the mailbox folder id to a folder name. More...
typedef struct ast_vm_mailbox_snapshot *()	ast_vm_mailbox_snapshot_create_fn(const char *user, const char *context, const char *folder, int descending, enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD)
	Create a snapshot of a mailbox which contains information about every msg. More...
typedef struct ast_vm_mailbox_snapshot *()	ast_vm_mailbox_snapshot_destroy_fn(struct ast_vm_mailbox_snapshot *mailbox_snapshot)
	destroy a snapshot More...
typedef int()	ast_vm_msg_forward_fn(const char *from_mailbox, const char *from_context, const char *from_folder, const char *to_mailbox, const char *to_context, const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old)
	forward a message from one mailbox to another. More...
typedef int()	ast_vm_msg_move_fn(const char *mailbox, const char *context, size_t num_msgs, const char *oldfolder, const char *old_msg_ids[], const char *newfolder)
	Move messages from one folder to another. More...
typedef void()	ast_vm_msg_play_cb(struct ast_channel *chan, const char *playfile, int duration)
	Voicemail playback callback function definition. More...
typedef int()	ast_vm_msg_play_fn(struct ast_channel *chan, const char *mailbox, const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb)
	Play a voicemail msg back on a channel. More...
typedef int()	ast_vm_msg_remove_fn(const char *mailbox, const char *context, size_t num_msgs, const char *folder, const char *msgs[])
	Remove/delete messages from a mailbox folder. More...
typedef int()	ast_vm_test_create_user_fn(const char *context, const char *user)
typedef int()	ast_vm_test_destroy_user_fn(const char *context, const char *user)

Enumerations
enum	ast_getdata_result {   AST_GETDATA_FAILED = -1, AST_GETDATA_COMPLETE = 0, AST_GETDATA_TIMEOUT = 1, AST_GETDATA_INTERRUPTED = 2,   AST_GETDATA_EMPTY_END_TERMINATED = 3 }
enum	ast_ivr_action {   AST_ACTION_UPONE, AST_ACTION_EXIT, AST_ACTION_CALLBACK, AST_ACTION_PLAYBACK,   AST_ACTION_BACKGROUND, AST_ACTION_PLAYLIST, AST_ACTION_MENU, AST_ACTION_REPEAT,   AST_ACTION_RESTART, AST_ACTION_TRANSFER, AST_ACTION_WAITOPTION, AST_ACTION_NOOP,   AST_ACTION_BACKLIST }
enum	AST_LOCK_RESULT { AST_LOCK_SUCCESS = 0, AST_LOCK_TIMEOUT = -1, AST_LOCK_PATH_NOT_FOUND = -2, AST_LOCK_FAILURE = -3 }
enum	AST_LOCK_TYPE { AST_LOCK_TYPE_LOCKFILE = 0, AST_LOCK_TYPE_FLOCK = 1 }
	Type of locking to use in ast_lock_path / ast_unlock_path. More...
enum	ast_record_if_exists { AST_RECORD_IF_EXISTS_ERROR = -1, AST_RECORD_IF_EXISTS_FAIL, AST_RECORD_IF_EXISTS_OVERWRITE, AST_RECORD_IF_EXISTS_APPEND }
enum	ast_timelen { TIMELEN_HOURS, TIMELEN_MINUTES, TIMELEN_SECONDS, TIMELEN_MILLISECONDS }
enum	ast_vm_snapshot_sort_val { AST_VM_SNAPSHOT_SORT_BY_ID = 0, AST_VM_SNAPSHOT_SORT_BY_TIME }

Functions
unsigned int	__ast_app_separate_args (char *buf, char delim, int remove_chars, char **array, int arraylen)
	Separate a string into arguments in an array. More...
int	__ast_vm_greeter_register (const struct ast_vm_greeter_functions *vm_table, struct ast_module *module)
	Set voicemail greeter function callbacks. More...
int	__ast_vm_register (const struct ast_vm_functions *vm_table, struct ast_module *module)
	Set voicemail function callbacks. More...
int	app_init (void)
	Initialize the application core. More...
int	ast_app_copy_recording_to_vm (struct ast_vm_recording_data *vm_rec_data)
	param[in] vm_rec_data Contains data needed to make the recording. retval 0 voicemail successfully created from recording. retval -1 Failure More...
int	ast_app_dtget (struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout)
	Present a dialtone and collect a certain length extension. More...
int	ast_app_exec_macro (struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const char *macro_args)
	Run a macro on a channel, placing an optional second channel into autoservice. More...
int	ast_app_exec_sub (struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_args, int ignore_hangup)
	Run a subroutine on a channel, placing an optional second channel into autoservice. More...
const char *	ast_app_expand_sub_args (struct ast_channel *chan, const char *args)
	Add missing context/exten to subroutine argument string. More...
int	ast_app_getdata (struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout)
	Plays a stream and gets DTMF data from a channel. More...
int	ast_app_getdata_full (struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd)
	Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions. More...
int	ast_app_group_discard (struct ast_channel *chan)
	Discard all group counting for a channel. More...
int	ast_app_group_get_count (const char *group, const char *category)
	Get the current channel count of the specified group and category. More...
struct ast_group_info *	ast_app_group_list_head (void)
	Get the head of the group count list. More...
int	ast_app_group_list_rdlock (void)
	Read Lock the group count list. More...
int	ast_app_group_list_unlock (void)
	Unlock the group count list. More...
int	ast_app_group_list_wrlock (void)
	Write Lock the group count list. More...
int	ast_app_group_match_get_count (const char *groupmatch, const char *category)
	Get the current channel count of all groups that match the specified pattern and category. More...
int	ast_app_group_set_channel (struct ast_channel *chan, const char *data)
	Set the group for a channel, splitting the provided data into group and category, if specified. More...
int	ast_app_group_split_group (const char *data, char *group, int group_max, char *category, int category_max)
	Split a group string into group and category, returning a default category if none is provided. More...
int	ast_app_group_update (struct ast_channel *oldchan, struct ast_channel *newchan)
	Update all group counting for a channel to a new one. More...
int	ast_app_has_voicemail (const char *mailboxes, const char *folder)
	Determine if a given mailbox has any voicemail If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the number of messages in the "Urgent" folder. More...
int	ast_app_inboxcount (const char *mailboxes, int *newmsgs, int *oldmsgs)
	Determine number of new/old messages in a mailbox. More...
int	ast_app_inboxcount2 (const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs)
	Determine number of urgent/new/old messages in a mailbox. More...
int	ast_app_messagecount (const char *mailbox_id, const char *folder)
	Get the number of messages in a given mailbox folder. More...
void	ast_app_options2str64 (const struct ast_app_option *options, struct ast_flags64 *flags, char *buf, size_t len)
	Given a list of options array, return an option string based on passed flags. More...
int	ast_app_parse_options (const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr)
	Parses a string containing application options and sets flags/arguments. More...
int	ast_app_parse_options64 (const struct ast_app_option *options, struct ast_flags64 *flags, char **args, char *optstr)
	Parses a string containing application options and sets flags/arguments. More...
int	ast_app_parse_timelen (const char *timestr, int *result, enum ast_timelen defunit)
	Common routine to parse time lengths, with optional time unit specifier. More...
int	ast_app_run_macro (struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const char *macro_name, const char *macro_args)
	Run a macro on a channel, placing an optional second channel into autoservice. More...
int	ast_app_run_sub (struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_location, const char *sub_args, int ignore_hangup)
	Run a subroutine on a channel, placing an optional second channel into autoservice. More...
int	ast_app_sayname (struct ast_channel *chan, const char *mailbox_id)
	Play a recorded user name for the mailbox to the specified channel. More...
void	ast_close_fds_above_n (int n)
	Common routine for child processes, to close all fds prior to exec(2) More...
int	ast_control_streamfile (struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms)
	Stream a file with fast forward, pause, reverse, restart. More...
int	ast_control_streamfile_lang (struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *suspend, const char *restart, int skipms, const char *lang, long *offsetms)
	Version of ast_control_streamfile() which allows the language of the media file to be specified. More...
int	ast_control_streamfile_w_cb (struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms, ast_waitstream_fr_cb cb)
	Stream a file with fast forward, pause, reverse, restart. More...
int	ast_control_tone (struct ast_channel *chan, const char *tone)
	Controls playback of a tone. More...
int	ast_dtmf_stream (struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration)
	Send a string of DTMF digits to a channel. More...
void	ast_dtmf_stream_external (struct ast_channel *chan, const char *digits, int between, unsigned int duration)
	Send a string of DTMF digits to a channel from an external thread. More...
int	ast_get_encoded_char (const char *stream, char *result, size_t *consumed)
	Decode an encoded control or extended ASCII character. More...
char *	ast_get_encoded_str (const char *stream, char *result, size_t result_len)
	Decode a stream of encoded control or extended ASCII characters. More...
void	ast_install_stack_functions (const struct ast_app_stack_funcs *funcs)
	Set stack application function callbacks. More...
void	ast_install_vm_test_functions (ast_vm_test_create_user_fn *vm_test_create_user_func, ast_vm_test_destroy_user_fn *vm_test_destroy_user_func)
int	ast_ivr_menu_run (struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata)
	Runs an IVR menu. More...
int	ast_linear_stream (struct ast_channel *chan, const char *filename, int fd, int allowoverride)
	Stream a filename (or file descriptor) as a generator. More...
enum AST_LOCK_RESULT	ast_lock_path (const char *path)
	Lock a filesystem path. More...
int	ast_mf_stream (struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration, unsigned int durationkp, unsigned int durationst, int is_external)
	Send a string of MF digits to a channel. More...
int	ast_play_and_prepend (struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int *sound_duration, int beep, int silencethreshold, int maxsilence_ms)
	Record a file based on input frm a channel. Recording is performed in 'prepend' mode which works a little differently from normal recordings This function will not play a success message due to post-recording control in the application this was added for. More...
int	ast_play_and_record (struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int silencethreshold, int maxsilence_ms, const char *path)
	Record a file based on input from a channel. Use default accept and cancel DTMF. This function will play "auth-thankyou" upon successful recording. More...
int	ast_play_and_record_full (struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int beep, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf, int skip_confirmation_sound, enum ast_record_if_exists if_exists)
	Record a file based on input from a channel This function will play "auth-thankyou" upon successful recording if skip_confirmation_sound is false. More...
int	ast_play_and_wait (struct ast_channel *chan, const char *fn)
	Play a stream and wait for a digit, returning the digit that was pressed. More...
struct stasis_topic *	ast_queue_topic (const char *queuename)
	Get the Stasis Message Bus API topic for queue messages for a particular queue name. More...
struct stasis_topic *	ast_queue_topic_all (void)
	Get the Stasis Message Bus API topic for queue messages. More...
char *	ast_read_textfile (const char *file)
	Read a file into asterisk. More...
int	ast_record_review (struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path)
	Allow to record message and have a review option. More...
void	ast_replace_sigchld (void)
	Replace the SIGCHLD handler. More...
int	ast_safe_execvp (int dualfork, const char *file, char *const argv[])
	Safely spawn an external program while closing file descriptors. More...
int	ast_safe_fork (int stop_reaper)
	Common routine to safely fork without a chance of a signal handler firing badly in the child. More...
void	ast_safe_fork_cleanup (void)
	Common routine to cleanup after fork'ed process is complete (if reaping was stopped) More...
int	ast_safe_system (const char *s)
	Safely spawn an OS shell command while closing file descriptors. More...
void	ast_set_lock_type (enum AST_LOCK_TYPE type)
	Set the type of locks used by ast_lock_path() More...
int	ast_str_get_encoded_str (struct ast_str **str, int maxlen, const char *stream)
	Decode a stream of encoded control or extended ASCII characters. More...
	AST_THREADSTORAGE_EXTERNAL (ast_str_thread_global_buf)
void	ast_uninstall_vm_test_functions (void)
int	ast_unlock_path (const char *path)
	Unlock a path. More...
void	ast_unreplace_sigchld (void)
	Restore the SIGCHLD handler. More...
int	ast_vm_greeter_is_registered (void)
	Determine if a voicemail greeter provider is registered. More...
void	ast_vm_greeter_unregister (const char *module_name)
	Unregister the specified voicemail greeter provider. More...
const char *	ast_vm_index_to_foldername (int id)
	Return name of folder, given an id. More...
int	ast_vm_is_registered (void)
	Determine if a voicemail provider is registered. More...
struct ast_vm_mailbox_snapshot *	ast_vm_mailbox_snapshot_create (const char *mailbox, const char *context, const char *folder, int descending, enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD)
	Create a snapshot of a mailbox which contains information about every msg. More...
struct ast_vm_mailbox_snapshot *	ast_vm_mailbox_snapshot_destroy (struct ast_vm_mailbox_snapshot *mailbox_snapshot)
	destroy a snapshot More...
int	ast_vm_msg_forward (const char *from_mailbox, const char *from_context, const char *from_folder, const char *to_mailbox, const char *to_context, const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old)
	forward a message from one mailbox to another. More...
int	ast_vm_msg_move (const char *mailbox, const char *context, size_t num_msgs, const char *oldfolder, const char *old_msg_ids[], const char *newfolder)
	Move messages from one folder to another. More...
int	ast_vm_msg_play (struct ast_channel *chan, const char *mailbox, const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb)
	Play a voicemail msg back on a channel. More...
int	ast_vm_msg_remove (const char *mailbox, const char *context, size_t num_msgs, const char *folder, const char *msgs[])
	Remove/delete messages from a mailbox folder. More...
int	ast_vm_test_create_user (const char *context, const char *mailbox)
int	ast_vm_test_destroy_user (const char *context, const char *mailbox)
void	ast_vm_test_swap_table_in (const struct ast_vm_functions *vm_table)
	Swap out existing voicemail functions with a temporary set of functions for use with unit tests. More...
void	ast_vm_test_swap_table_out (void)
	Used after ast_vm_test_swap_table_in to restore the original set of voicemail functions. More...
void	ast_vm_unregister (const char *module_name)
	Unregister the specified voicemail provider. More...

Detailed Description

Application convenience functions, designed to give consistent look and feel to Asterisk apps.

Definition in file include/asterisk/app.h.

Macro Definition Documentation

AST_APP_ARG

#define AST_APP_ARG

(

name

)

char *name

Define an application argument.

Parameters

name	The name of the argument

Definition at line 1232 of file include/asterisk/app.h.

Referenced by acf_abs_exec(), acf_curl_exec(), acf_curl_write(), acf_if(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_max_exec(), acf_meetme_info(), acf_min_exec(), acf_odbc_read(), acf_odbc_write(), acf_rand_exec(), acf_sprintf(), acf_strftime(), acf_strptime(), acf_transaction_read(), acf_transaction_write(), acf_version_exec(), acf_vm_info(), acf_vmcount_exec(), action_status(), add_action_to_menu_entry(), admin_exec(), aelsub_exec(), aes_helper(), agent_function_read(), agent_login_exec(), agent_request_exec(), agi_exec_full(), aMYSQL_connect(), aMYSQL_fetch(), aMYSQL_nextresult(), aMYSQL_query(), aMYSQL_set(), app_exec(), applicationmap_handler(), aqm_exec(), array(), ast_eivr_senddtmf(), ast_queue_log(), asyncgoto_exec(), attended_transfer_exec(), audiosocket_exec(), audiosocket_request(), auth_exec(), background_detect_exec(), blind_transfer_exec(), bridge_exec(), bridgewait_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), cb_events(), cdr_prop_write_callback(), cdr_read_callback(), cdr_write(), cdr_write_callback(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), channelvars_handler(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), confkick_exec(), controlplayback_exec(), count_exec(), create_addr(), cut_internal(), dahdi_call(), destroy_all_channels(), detect_write(), determine_starting_point(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_exec(), dtmfstore_exec(), dundi_query_read(), dundi_result_read(), dundifunc_read(), enable_jack_hook(), enum_query_read(), enum_result_read(), execif_exec(), extenspy_exec(), festival_exec(), file_count_line(), file_read(), file_write(), filter(), find_conf(), find_realtime_gw(), find_table_cb(), forkcdr_exec(), func_confbridge_helper(), func_confbridge_info(), func_get_parkingslot_channel(), func_header_read(), func_headers_read2(), func_mixmonitor_read(), func_read_header(), func_write_header(), function_amiclient(), function_db_delete(), function_db_exists(), function_db_read(), function_db_write(), function_enum(), function_fieldnum_helper(), function_fieldqty_helper(), function_realtime_read(), function_realtime_readdestroy(), function_realtime_store(), function_realtime_write(), function_txtcidname(), gosub_exec(), gosubif_exec(), hangupcause_read(), hash_read(), hash_write(), hint_read(), hook_on(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), jb_helper(), jingle_request(), listfilter(), load_channelvars(), load_values_config(), log_exec(), man_do_variable_value(), math(), mbl_sendsms_exec(), mbl_status_exec(), misdn_call(), misdn_check_l2l1(), misdn_facility_exec(), misdn_request(), mixmonitor_exec(), msg_send_exec(), multicast_rtp_request(), my_on_hook(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_call(), oss_request(), page_exec(), park_and_announce_app_exec(), park_app_parse_data(), parked_call_app_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_saycharacters_case(), pbx_builtin_setvar_multiple(), pbx_builtin_waitdigit(), pbx_builtin_waitexten(), peek_read(), pickupchan_exec(), pjsip_acf_channel_read(), pjsip_acf_dial_contacts_read(), pjsip_acf_parse_uri_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pqm_exec(), presence_read(), privacy_exec(), ql_exec(), queue_exec(), queue_function_mem_read(), queue_function_mem_write(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), queue_function_queuegetchannel(), qupd_exec(), rcvfax_exec(), read_exec(), read_mf_exec(), read_sf_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), reg_source_db(), regex(), reload(), reload_single_member(), replace(), request(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayfile_exec(), sayunixtime_exec(), scramble_write(), senddtmf_exec(), sendfax_exec(), sendmf_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sip_acf_channel_read(), sip_parse_register_line(), sip_request_call(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), sorcery_function_read(), speech_background(), speech_load(), srv_result_read(), stackpeek_read(), start_moh_exec(), start_monitor_exec(), statsd_exec(), stir_shaken_read(), stop_mixmonitor_full(), stream_echo_exec(), strreplace(), talk_detect_fn_write(), transfer_exec(), unicast_rtp_request(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_check_password_shell(), vm_exec(), vm_execmain(), vm_playmsgexec(), volume_read(), volume_write(), wait_exec(), waitfor_exec(), xmpp_join_exec(), xmpp_leave_exec(), xmpp_send_exec(), xmpp_sendgroup_exec(), and zapateller_exec().

AST_APP_OPTION

#define AST_APP_OPTION	(		option,
			flagno
	)		[option] = { .flag = flagno }

Declares an application option that does not accept an argument.

Parameters

option	The single character representing the option
flagno	The flag index to be set if this option is present

See also

AST_APP_OPTIONS, ast_app_parse_options

Definition at line 1402 of file include/asterisk/app.h.

AST_APP_OPTION_ARG

#define AST_APP_OPTION_ARG	(		option,
			flagno,
			argno
	)		[option] = { .flag = flagno, .arg_index = argno + 1 }

Declares an application option that accepts an argument.

Parameters

option	The single character representing the option
flagno	The flag index to be set if this option is present
argno	The index into the argument array where the argument should be placed

See also

AST_APP_OPTIONS, ast_app_parse_options

Definition at line 1413 of file include/asterisk/app.h.

Referenced by AST_TEST_DEFINE().

AST_APP_OPTIONS

#define AST_APP_OPTIONS	(		holder,
			options...
	)		static const struct ast_app_option holder[128] = options

Declares an array of options for an application.

Parameters

holder	The name of the array to be created
options	The actual options to be placed into the array

See also

ast_app_parse_options

This macro declares a 'static const' array of struct ast_option elements to hold the list of available options for an application. Each option must be declared using either the AST_APP_OPTION() or AST_APP_OPTION_ARG() macros.

Example usage:

enum my_app_option_flags {
      OPT_JUMP = (1 << 0),
      OPT_BLAH = (1 << 1),
      OPT_BLORT = (1 << 2),
};

enum my_app_option_args {
      OPT_ARG_BLAH = 0,
      OPT_ARG_BLORT,
      !! this entry tells how many possible arguments there are,
         and must be the last entry in the list
      OPT_ARG_ARRAY_SIZE,
};

AST_APP_OPTIONS(my_app_options, {
      AST_APP_OPTION('j', OPT_JUMP),
      AST_APP_OPTION_ARG('b', OPT_BLAH, OPT_ARG_BLAH),
      AST_APP_OPTION_BLORT('B', OPT_BLORT, OPT_ARG_BLORT),
});

static int my_app_exec(struct ast_channel *chan, void *data)
{
   char *options;
 struct ast_flags opts = { 0, };
 char *opt_args[OPT_ARG_ARRAY_SIZE];

   ... do any argument parsing here ...

 if (ast_app_parse_options(my_app_options, &opts, opt_args, options)) {
   return -1;
 }
}

Definition at line 1393 of file include/asterisk/app.h.

Referenced by AST_TEST_DEFINE().

ast_app_separate_args

#define ast_app_separate_args	(		a,
			b,
			c,
			d
	)		__ast_app_separate_args(a,b,1,c,d)

Definition at line 1321 of file include/asterisk/app.h.

Referenced by ast_ari_applications_subscribe_cb(), ast_ari_applications_unsubscribe_cb(), ast_ari_asterisk_get_info_cb(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_play_cb(), ast_ari_bridges_play_with_id_cb(), ast_ari_bridges_remove_channel_cb(), ast_ari_channels_play_cb(), ast_ari_channels_play_with_id_cb(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_ari_events_user_event_cb(), common_exec(), minivm_accmess_exec(), minivm_greet_exec(), minivm_mwi_exec(), minivm_notify_exec(), minivm_record_exec(), and process_echocancel().

AST_DECLARE_APP_ARGS

#define AST_DECLARE_APP_ARGS	(		name,
			arglist
	)		AST_DEFINE_APP_ARGS_TYPE(argtype_##name, arglist) name = { 0, }

Declare a structure to hold an application's arguments.

Parameters

name	The name of the structure
arglist	The list of arguments, defined using AST_APP_ARG

This macro declares a structure intended to be used in a call to ast_app_separate_args(). The structure includes all the arguments specified, plus an argv array that overlays them and an argc argument counter. The arguments must be declared using AST_APP_ARG, and they will all be character pointers (strings).

Note

The structure is not initialized, as the call to ast_app_separate_args() will perform that function before parsing the arguments.

Definition at line 1249 of file include/asterisk/app.h.

Referenced by acf_abs_exec(), acf_curl_exec(), acf_curl_write(), acf_if(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_max_exec(), acf_meetme_info(), acf_min_exec(), acf_odbc_read(), acf_odbc_write(), acf_rand_exec(), acf_sprintf(), acf_strftime(), acf_strptime(), acf_transaction_read(), acf_transaction_write(), acf_version_exec(), acf_vm_info(), acf_vmcount_exec(), action_status(), add_action_to_menu_entry(), admin_exec(), aelsub_exec(), aes_helper(), agent_function_read(), agent_login_exec(), agent_request_exec(), agi_exec_full(), aMYSQL_connect(), aMYSQL_fetch(), aMYSQL_nextresult(), aMYSQL_query(), aMYSQL_set(), app_exec(), applicationmap_handler(), aqm_exec(), array(), ast_eivr_senddtmf(), ast_queue_log(), asyncgoto_exec(), attended_transfer_exec(), audiosocket_exec(), audiosocket_request(), auth_exec(), background_detect_exec(), blind_transfer_exec(), bridge_exec(), bridgewait_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), cb_events(), cdr_prop_write_callback(), cdr_read_callback(), cdr_write(), cdr_write_callback(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), channelvars_handler(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), confkick_exec(), controlplayback_exec(), count_exec(), create_addr(), cut_internal(), dahdi_call(), destroy_all_channels(), detect_write(), determine_starting_point(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_exec(), dtmfstore_exec(), dundi_query_read(), dundi_result_read(), dundifunc_read(), enable_jack_hook(), enum_query_read(), enum_result_read(), execif_exec(), extenspy_exec(), festival_exec(), file_count_line(), file_read(), file_write(), filter(), find_conf(), find_realtime_gw(), find_table_cb(), forkcdr_exec(), func_confbridge_helper(), func_confbridge_info(), func_get_parkingslot_channel(), func_header_read(), func_headers_read2(), func_mixmonitor_read(), func_read_header(), func_write_header(), function_amiclient(), function_db_delete(), function_db_exists(), function_db_read(), function_db_write(), function_enum(), function_fieldnum_helper(), function_fieldqty_helper(), function_realtime_read(), function_realtime_readdestroy(), function_realtime_store(), function_realtime_write(), function_txtcidname(), gosub_exec(), gosubif_exec(), hangupcause_read(), hash_read(), hash_write(), hint_read(), hook_on(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), jb_helper(), jingle_request(), listfilter(), load_channelvars(), load_values_config(), log_exec(), man_do_variable_value(), math(), mbl_sendsms_exec(), mbl_status_exec(), misdn_call(), misdn_check_l2l1(), misdn_facility_exec(), misdn_request(), mixmonitor_exec(), msg_send_exec(), multicast_rtp_request(), my_on_hook(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_call(), oss_request(), page_exec(), park_and_announce_app_exec(), park_app_parse_data(), parked_call_app_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_saycharacters_case(), pbx_builtin_setvar_multiple(), pbx_builtin_waitdigit(), pbx_builtin_waitexten(), peek_read(), pickupchan_exec(), pjsip_acf_channel_read(), pjsip_acf_dial_contacts_read(), pjsip_acf_parse_uri_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pqm_exec(), presence_read(), privacy_exec(), ql_exec(), queue_exec(), queue_function_mem_read(), queue_function_mem_write(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), queue_function_queuegetchannel(), qupd_exec(), rcvfax_exec(), read_exec(), read_mf_exec(), read_sf_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), reg_source_db(), regex(), reload_single_member(), replace(), request(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayfile_exec(), sayunixtime_exec(), scramble_write(), senddtmf_exec(), sendfax_exec(), sendmf_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sip_acf_channel_read(), sip_parse_register_line(), sip_request_call(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), sorcery_function_read(), speech_background(), speech_load(), srv_result_read(), stackpeek_read(), start_moh_exec(), start_monitor_exec(), statsd_exec(), stir_shaken_read(), stop_mixmonitor_full(), stream_echo_exec(), strreplace(), talk_detect_fn_write(), transfer_exec(), unicast_rtp_request(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_check_password_shell(), vm_exec(), vm_execmain(), vm_playmsgexec(), volume_read(), volume_write(), wait_exec(), waitfor_exec(), xmpp_join_exec(), xmpp_leave_exec(), xmpp_send_exec(), xmpp_sendgroup_exec(), and zapateller_exec().

AST_DEFINE_APP_ARGS_TYPE

#define AST_DEFINE_APP_ARGS_TYPE	(		type,
			arglist
	)

Define a structure type to hold an application's arguments.

Parameters

type	The name of the structure type
arglist	The list of arguments, defined using AST_APP_ARG

This macro defines a structure type intended to be used in a call to ast_app_separate_args(). The structure includes all the arguments specified, plus an argv array that overlays them and an argc argument counter. The arguments must be declared using AST_APP_ARG, and they will all be character pointers (strings).

Note

This defines a structure type, but does not declare an instance of the structure. That must be done separately.

Definition at line 1266 of file include/asterisk/app.h.

Referenced by reload().

AST_IVR_DECLARE_MENU

#define AST_IVR_DECLARE_MENU	(		holder,
			title,
			flags,
			foo...
	)

Value:

static struct ast_ivr_option __options_##holder[] = foo;\
   static struct ast_ivr_menu holder = { title, flags, __options_##holder }

Definition at line 109 of file include/asterisk/app.h.

Referenced by ivr_demo_func().

AST_IVR_FLAG_AUTORESTART

#define AST_IVR_FLAG_AUTORESTART   (1 << 0)

Definition at line 107 of file include/asterisk/app.h.

AST_NONSTANDARD_APP_ARGS

#define AST_NONSTANDARD_APP_ARGS	(		args,
			parse,
			sep
	)		args.argc = __ast_app_separate_args(parse, sep, 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))

Performs the 'nonstandard' argument separation process for an application.

Parameters

args	An argument structure defined using AST_DECLARE_APP_ARGS
parse	A modifiable buffer containing the input to be parsed
sep	A nonstandard separator character

This function will separate the input string using the nonstandard argument separator character and fill in the provided structure, including the argc argument counter field.

Definition at line 1300 of file include/asterisk/app.h.

Referenced by acf_if(), acf_jabberreceive_read(), acf_jabberstatus_read(), agent_function_read(), aMYSQL_connect(), aMYSQL_fetch(), aMYSQL_nextresult(), aMYSQL_query(), aMYSQL_set(), ast_queue_log(), audiosocket_request(), build_profile(), callerid_read(), callerid_write(), connectedline_read(), connectedline_write(), dahdi_call(), determine_starting_point(), dialgroup_write(), function_db_delete(), function_db_exists(), function_db_read(), function_db_write(), jingle_request(), misdn_call(), misdn_request(), multicast_rtp_request(), my_on_hook(), oss_call(), oss_request(), pbx_builtin_setvar_multiple(), redirecting_read(), redirecting_write(), regex(), request(), sip_request_call(), unicast_rtp_request(), and vm_check_password_shell().

AST_NONSTANDARD_RAW_ARGS

#define AST_NONSTANDARD_RAW_ARGS	(		args,
			parse,
			sep
	)		args.argc = __ast_app_separate_args(parse, sep, 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))

Definition at line 1302 of file include/asterisk/app.h.

Referenced by create_addr(), execif_exec(), gosubif_exec(), reg_source_db(), and sip_parse_register_line().

AST_STANDARD_APP_ARGS

#define AST_STANDARD_APP_ARGS	(		args,
			parse
	)		args.argc = __ast_app_separate_args(parse, ',', 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))

Performs the 'standard' argument separation process for an application.

Parameters

args	An argument structure defined using AST_DECLARE_APP_ARGS
parse	A modifiable buffer containing the input to be parsed

This function will separate the input string using the standard argument separator character ',' and fill in the provided structure, including the argc argument counter field.

Definition at line 1285 of file include/asterisk/app.h.

Referenced by acf_abs_exec(), acf_curl_exec(), acf_curl_write(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_max_exec(), acf_meetme_info(), acf_min_exec(), acf_odbc_read(), acf_odbc_write(), acf_rand_exec(), acf_sprintf(), acf_strftime(), acf_strptime(), acf_transaction_read(), acf_transaction_write(), acf_version_exec(), acf_vm_info(), acf_vmcount_exec(), action_status(), add_action_to_menu_entry(), admin_exec(), aes_helper(), agent_login_exec(), agent_request_exec(), agi_exec_full(), app_exec(), applicationmap_handler(), aqm_exec(), array(), ast_eivr_senddtmf(), asyncgoto_exec(), attended_transfer_exec(), audiosocket_exec(), auth_exec(), background_detect_exec(), blind_transfer_exec(), bridge_exec(), bridgewait_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), callerid_write(), cb_events(), cdr_prop_write_callback(), cdr_read_callback(), cdr_write(), cdr_write_callback(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), channelvars_handler(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), confkick_exec(), connectedline_write(), controlplayback_exec(), count_exec(), cut_internal(), destroy_all_channels(), detect_write(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_exec(), dtmfstore_exec(), dundi_query_read(), dundi_result_read(), dundifunc_read(), enable_jack_hook(), enum_query_read(), enum_result_read(), execif_exec(), extenspy_exec(), festival_exec(), file_count_line(), file_read(), file_write(), find_conf(), find_realtime_gw(), find_table_cb(), forkcdr_exec(), func_confbridge_helper(), func_confbridge_info(), func_get_parkingslot_channel(), func_header_read(), func_headers_read2(), func_mixmonitor_read(), func_read_header(), func_write_header(), function_amiclient(), function_enum(), function_fieldnum_helper(), function_fieldqty_helper(), function_realtime_read(), function_realtime_readdestroy(), function_realtime_store(), function_realtime_write(), function_txtcidname(), hangupcause_read(), hash_read(), hash_write(), hint_read(), hook_on(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), jb_helper(), listfilter(), load_channelvars(), log_exec(), man_do_variable_value(), math(), mbl_sendsms_exec(), mbl_status_exec(), misdn_check_l2l1(), misdn_facility_exec(), mixmonitor_exec(), msg_send_exec(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), page_exec(), park_and_announce_app_exec(), park_app_parse_data(), parked_call_app_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_saycharacters_case(), pbx_builtin_setvar_multiple(), pbx_builtin_waitdigit(), pbx_builtin_waitexten(), pickupchan_exec(), pjsip_acf_channel_read(), pjsip_acf_dial_contacts_read(), pjsip_acf_parse_uri_read(), pjsip_aor_function_read(), pjsip_contact_function_read(), pjsip_endpoint_function_read(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pqm_exec(), presence_read(), privacy_exec(), ql_exec(), queue_exec(), queue_function_mem_read(), queue_function_mem_write(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), queue_function_queuegetchannel(), qupd_exec(), rcvfax_exec(), read_exec(), read_mf_exec(), read_sf_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), redirecting_write(), reload(), reload_single_member(), replace(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayfile_exec(), sayunixtime_exec(), scramble_write(), senddtmf_exec(), sendfax_exec(), sendmf_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sip_acf_channel_read(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), sorcery_function_read(), speech_background(), speech_load(), srv_result_read(), stackpeek_read(), start_moh_exec(), start_monitor_exec(), statsd_exec(), stir_shaken_read(), stop_mixmonitor_full(), stream_echo_exec(), strreplace(), talk_detect_fn_write(), transfer_exec(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_exec(), vm_execmain(), vm_playmsgexec(), volume_read(), volume_write(), wait_exec(), waitfor_exec(), xmpp_join_exec(), xmpp_leave_exec(), xmpp_send_exec(), xmpp_sendgroup_exec(), and zapateller_exec().

AST_STANDARD_RAW_ARGS

#define AST_STANDARD_RAW_ARGS	(		args,
			parse
	)		args.argc = __ast_app_separate_args(parse, ',', 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))

Definition at line 1287 of file include/asterisk/app.h.

Referenced by aelsub_exec(), filter(), gosub_exec(), load_values_config(), and peek_read().

ast_vm_greeter_register

#define ast_vm_greeter_register

(

vm_table

)

__ast_vm_greeter_register(vm_table, AST_MODULE_SELF)

See __ast_vm_greeter_register()

Definition at line 657 of file include/asterisk/app.h.

Referenced by load_module().

ast_vm_register

#define ast_vm_register

(

vm_table

)

__ast_vm_register(vm_table, AST_MODULE_SELF)

See __ast_vm_register()

Definition at line 588 of file include/asterisk/app.h.

Referenced by load_module().

BEGIN_OPTIONS

#define BEGIN_OPTIONS   {

Definition at line 1343 of file include/asterisk/app.h.

END_OPTIONS

#define END_OPTIONS   }

Definition at line 1344 of file include/asterisk/app.h.

VM_GREETER_MODULE_VERSION

#define VM_GREETER_MODULE_VERSION   1

Examples:

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

Definition at line 615 of file include/asterisk/app.h.

Referenced by __ast_vm_greeter_register().

VM_MODULE_VERSION

#define VM_MODULE_VERSION   2

Examples:

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

Definition at line 536 of file include/asterisk/app.h.

Referenced by __ast_vm_register().

Typedef Documentation

ast_copy_recording_to_vm_fn

typedef int() ast_copy_recording_to_vm_fn(struct ast_vm_recording_data *vm_rec_data)

Creates a voicemail based on a specified file to a mailbox.

Parameters

vm_rec_data

A record containing filename and voicemail txt info.

Return values

0	on success
-1	on failure

Definition at line 414 of file include/asterisk/app.h.

ast_has_voicemail_fn

typedef int() ast_has_voicemail_fn(const char *mailboxes, const char *folder)

Determines if the given folder has messages.

Parameters

mailboxes	Comma or & delimited list of mailboxes (user). If no context is found, uses 'default' for the context.
folder	The folder to look in. Default is INBOX if not provided.

Return values

1	if the folder has one or more messages.
0	otherwise.

Definition at line 344 of file include/asterisk/app.h.

ast_inboxcount2_fn

typedef int() ast_inboxcount2_fn(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs)

Gets the number of messages that exist for the mailbox list.

Parameters

mailboxes	Comma or space delimited list of mailboxes (user). If no context is found, uses 'default' for the context.
urgentmsgs	Where to put the count of urgent messages. (Can be NULL)
newmsgs	Where to put the count of new messages. (Can be NULL)
oldmsgs	Where to put the count of old messages. (Can be NULL)

Simultaneously determines the count of new, old, and urgent messages. The total messages would then be the sum of these three.

Return values

0	on success
-1	on failure

Definition at line 380 of file include/asterisk/app.h.

ast_inboxcount_fn

typedef int() ast_inboxcount_fn(const char *mailboxes, int *newmsgs, int *oldmsgs)

Gets the number of messages that exist for the mailbox list.

Parameters

mailboxes	Comma or space delimited list of mailboxes (user). If no context is found, uses 'default' for the context.
newmsgs	Where to put the count of new messages. (Can be NULL)
oldmsgs	Where to put the count of old messages. (Can be NULL)

Simultaneously determines the count of new + urgent and old messages. The total messages would then be the sum of these.

Return values

0	on success
-1	on failure

Definition at line 361 of file include/asterisk/app.h.

ast_ivr_callback

typedef int() ast_ivr_callback(struct ast_channel *chan, char *option, void *cbdata)

Callback function for IVR.

Returns

returns 0 on completion, -1 on hangup or digit if interrupted

Definition at line 47 of file include/asterisk/app.h.

ast_messagecount_fn

typedef int() ast_messagecount_fn(const char *mailbox_id, const char *folder)

Gets the number of messages that exist in a mailbox folder.

Parameters

mailbox_id	The mailbox name.
folder	The folder to look in. Default is INBOX if not provided.

Note

If requesting INBOX then the returned count is INBOX + Urgent.

Returns

The number of messages in the mailbox folder (zero or more).

Definition at line 392 of file include/asterisk/app.h.

ast_sayname_fn

typedef int() ast_sayname_fn(struct ast_channel *chan, const char *mailbox_id)

Play a recorded user name for the mailbox to the specified channel.

Parameters

chan	Where to play the recorded name file.
mailbox_id	The mailbox name.

Return values

0	Name played without interruption
dtmf	ASCII value of the DTMF which interrupted playback.
-1	Unable to locate mailbox or hangup occurred.

Definition at line 404 of file include/asterisk/app.h.

ast_vm_index_to_foldername_fn

typedef const char*() ast_vm_index_to_foldername_fn(int id)

Convert the mailbox folder id to a folder name.

Parameters

id	Mailbox folder id to convert.

Deprecated:

Nothing calls it and nothing ever should.

Returns

The folder name associated with the id.

Definition at line 425 of file include/asterisk/app.h.

ast_vm_mailbox_snapshot_create_fn

typedef struct ast_vm_mailbox_snapshot*() ast_vm_mailbox_snapshot_create_fn(const char *user, const char *context, const char *folder, int descending, enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD)

Create a snapshot of a mailbox which contains information about every msg.

Parameters

user	The user part of user.
context	The context part of user. Must be explicit.
folder	When not NULL only msgs from the specified folder will be included.
descending	list the msgs in descending order rather than ascending order.
sort_val	What to sort in the snapshot.
combine_INBOX_and_OLD	When this argument is set, The OLD folder will be represented in the INBOX folder of the snapshot. This allows the snapshot to represent the OLD and INBOX messages in sorted order merged together.

Note

Only used by voicemail unit tests.

Return values

snapshot	on success
NULL	on failure

Definition at line 444 of file include/asterisk/app.h.

ast_vm_mailbox_snapshot_destroy_fn

typedef struct ast_vm_mailbox_snapshot*() ast_vm_mailbox_snapshot_destroy_fn(struct ast_vm_mailbox_snapshot *mailbox_snapshot)

destroy a snapshot

Parameters

mailbox_snapshot

The snapshot to destroy.

Note

Only used by voicemail unit tests.

Return values

NULL

Definition at line 457 of file include/asterisk/app.h.

ast_vm_msg_forward_fn

typedef int() ast_vm_msg_forward_fn(const char *from_mailbox, const char *from_context, const char *from_folder, const char *to_mailbox, const char *to_context, const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old)

forward a message from one mailbox to another.

from_mailbox The original mailbox the message is being forwarded from from_context The voicemail context of the from_mailbox from_folder The folder from which the message is being forwarded to_mailbox The mailbox to forward the message to to_context The voicemail context of the to_mailbox to_folder The folder to which the message is being forwarded num_msgs The number of messages being forwarded msg_ids The message IDs of the messages in from_mailbox to forward delete_old If non-zero, the forwarded messages are also deleted from from_mailbox. Otherwise, the messages will remain in the from_mailbox.

Note

Only used by voicemail unit tests.

Return values

-1	Failure
0	Success

Definition at line 514 of file include/asterisk/app.h.

ast_vm_msg_move_fn

typedef int() ast_vm_msg_move_fn(const char *mailbox, const char *context, size_t num_msgs, const char *oldfolder, const char *old_msg_ids[], const char *newfolder)

Move messages from one folder to another.

Parameters

mailbox	The mailbox to which the folders belong
context	The voicemail context for the mailbox
num_msgs	The number of messages to move
oldfolder	The folder from where messages should be moved
old_msg_ids	The message IDs of the messages to move
newfolder	The folder to which messages should be moved new folder. This array must be num_msgs sized.

Note

Only used by voicemail unit tests.

Return values

-1	Failure
0	Success

Definition at line 475 of file include/asterisk/app.h.

ast_vm_msg_play_cb

typedef void() ast_vm_msg_play_cb(struct ast_channel *chan, const char *playfile, int duration)

Voicemail playback callback function definition.

Parameters

chan	Channel to play the file back on.
playfile	Location of file on disk
duration	of file in seconds. This will be zero if msg is very short or has an unknown duration.

Examples:

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

Definition at line 332 of file include/asterisk/app.h.

ast_vm_msg_play_fn

typedef int() ast_vm_msg_play_fn(struct ast_channel *chan, const char *mailbox, const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb)

Play a voicemail msg back on a channel.

Parameters

chan
mailbox	msg is in.
context	of mailbox.
folder	voicemail folder to look in.
msg_num	message number in the voicemailbox to playback to the channel.
cb

Note

Only used by voicemail unit tests.

Return values

0	success
-1	failure

Definition at line 533 of file include/asterisk/app.h.

ast_vm_msg_remove_fn

typedef int() ast_vm_msg_remove_fn(const char *mailbox, const char *context, size_t num_msgs, const char *folder, const char *msgs[])

Remove/delete messages from a mailbox folder.

Parameters

mailbox	The mailbox from which to delete messages
context	The voicemail context for the mailbox
num_msgs	The number of messages to delete
folder	The folder from which to remove messages
msgs	The message IDs of the messages to delete

Note

Only used by voicemail unit tests.

Return values

-1	Failure
0	Success

Definition at line 492 of file include/asterisk/app.h.

ast_vm_test_create_user_fn

typedef int() ast_vm_test_create_user_fn(const char *context, const char *user)

Examples:

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

Definition at line 670 of file include/asterisk/app.h.

ast_vm_test_destroy_user_fn

typedef int() ast_vm_test_destroy_user_fn(const char *context, const char *user)

Examples:

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

Definition at line 671 of file include/asterisk/app.h.

Enumeration Type Documentation

ast_getdata_result

enum ast_getdata_result

Enumerator
AST_GETDATA_FAILED
AST_GETDATA_COMPLETE
AST_GETDATA_TIMEOUT
AST_GETDATA_INTERRUPTED
AST_GETDATA_EMPTY_END_TERMINATED	indicates a user terminated empty string rather than an empty string resulting from a timeout or other factors

Definition at line 1154 of file include/asterisk/app.h.

                        {
   AST_GETDATA_FAILED = -1,
   AST_GETDATA_COMPLETE = 0,
   AST_GETDATA_TIMEOUT = 1,
   AST_GETDATA_INTERRUPTED = 2,
   /*! indicates a user terminated empty string rather than an empty string resulting
    * from a timeout or other factors */
   AST_GETDATA_EMPTY_END_TERMINATED = 3,
};

ast_ivr_action

enum ast_ivr_action

Enumerator
AST_ACTION_UPONE	adata is unused
AST_ACTION_EXIT	adata is the return value for ast_ivr_menu_run if channel was not hungup
AST_ACTION_CALLBACK	adata is an ast_ivr_callback
AST_ACTION_PLAYBACK	adata is file to play
AST_ACTION_BACKGROUND	adata is file to play
AST_ACTION_PLAYLIST	adata is list of files, separated by ; to play
AST_ACTION_MENU	adata is a pointer to an ast_ivr_menu
AST_ACTION_REPEAT	adata is max # of repeats, cast to a pointer
AST_ACTION_RESTART	adata is like repeat, but resets repeats to 0
AST_ACTION_TRANSFER	adata is a string with exten [@context]
AST_ACTION_WAITOPTION	adata is a timeout, or 0 for defaults
AST_ACTION_NOOP	adata is unused
AST_ACTION_BACKLIST	adata is list of files separated by ; allows interruption

Definition at line 49 of file include/asterisk/app.h.

             {
   AST_ACTION_UPONE, /*!< adata is unused */
   AST_ACTION_EXIT,  /*!< adata is the return value for ast_ivr_menu_run if channel was not hungup */
   AST_ACTION_CALLBACK, /*!< adata is an ast_ivr_callback */
   AST_ACTION_PLAYBACK, /*!< adata is file to play */
   AST_ACTION_BACKGROUND,  /*!< adata is file to play */
   AST_ACTION_PLAYLIST, /*!< adata is list of files, separated by ; to play */
   AST_ACTION_MENU,  /*!< adata is a pointer to an ast_ivr_menu */
   AST_ACTION_REPEAT,   /*!< adata is max # of repeats, cast to a pointer */
   AST_ACTION_RESTART,  /*!< adata is like repeat, but resets repeats to 0 */
   AST_ACTION_TRANSFER, /*!< adata is a string with exten\verbatim[@context]\endverbatim */
   AST_ACTION_WAITOPTION,  /*!< adata is a timeout, or 0 for defaults */
   AST_ACTION_NOOP,  /*!< adata is unused */
   AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */
} ast_ivr_action;

AST_LOCK_RESULT

enum AST_LOCK_RESULT

Enumerator
AST_LOCK_SUCCESS
AST_LOCK_TIMEOUT
AST_LOCK_PATH_NOT_FOUND
AST_LOCK_FAILURE

Definition at line 1164 of file include/asterisk/app.h.

                     {
   AST_LOCK_SUCCESS = 0,
   AST_LOCK_TIMEOUT = -1,
   AST_LOCK_PATH_NOT_FOUND = -2,
   AST_LOCK_FAILURE = -3,
};

AST_LOCK_TYPE

enum AST_LOCK_TYPE

Type of locking to use in ast_lock_path / ast_unlock_path.

Enumerator
AST_LOCK_TYPE_LOCKFILE
AST_LOCK_TYPE_FLOCK

Definition at line 1172 of file include/asterisk/app.h.

                   {
   AST_LOCK_TYPE_LOCKFILE = 0,
   AST_LOCK_TYPE_FLOCK = 1,
};

ast_record_if_exists

enum ast_record_if_exists

Possible actions to take if a recording already exists

Since

12

Enumerator
AST_RECORD_IF_EXISTS_ERROR	Return an Error State for IF_Exists
AST_RECORD_IF_EXISTS_FAIL	Fail the recording.
AST_RECORD_IF_EXISTS_OVERWRITE	Overwrite the existing recording.
AST_RECORD_IF_EXISTS_APPEND	Append to the existing recording.

Definition at line 1072 of file include/asterisk/app.h.

                          {
   /*! Return an Error State for IF_Exists */
   AST_RECORD_IF_EXISTS_ERROR = -1,
   /*! Fail the recording. */
   AST_RECORD_IF_EXISTS_FAIL,
   /*! Overwrite the existing recording. */
   AST_RECORD_IF_EXISTS_OVERWRITE,
   /*! Append to the existing recording. */
   AST_RECORD_IF_EXISTS_APPEND,
};

ast_timelen

enum ast_timelen

Enumerator
TIMELEN_HOURS
TIMELEN_MINUTES
TIMELEN_SECONDS
TIMELEN_MILLISECONDS

Definition at line 113 of file include/asterisk/app.h.

                 {
   TIMELEN_HOURS,
   TIMELEN_MINUTES,
   TIMELEN_SECONDS,
   TIMELEN_MILLISECONDS,
};

ast_vm_snapshot_sort_val

enum ast_vm_snapshot_sort_val

Enumerator
AST_VM_SNAPSHOT_SORT_BY_ID
AST_VM_SNAPSHOT_SORT_BY_TIME

Definition at line 295 of file include/asterisk/app.h.

                              {
   AST_VM_SNAPSHOT_SORT_BY_ID = 0,
   AST_VM_SNAPSHOT_SORT_BY_TIME,
};

Function Documentation

__ast_app_separate_args()

unsigned int __ast_app_separate_args	(	char *	buf,
		char	delim,
		int	remove_chars,
		char **	array,
		int	arraylen
	)

Separate a string into arguments in an array.

Parameters

buf	The string to be parsed (this must be a writable copy, as it will be modified)
delim	The character to be used to delimit arguments
remove_chars	Remove backslashes and quote characters, while parsing
array	An array of 'char *' to be filled in with pointers to the found arguments
arraylen	The number of elements in the array (i.e. the number of arguments you will accept)

Note: if there are more arguments in the string than the array will hold, the last element of the array will contain the remaining arguments, not separated.

The array will be completely zeroed by this function before it populates any entries.

Returns

The number of arguments found, or zero if the function arguments are not valid.

Examples:

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

Definition at line 2199 of file main/app.c.

References buf, NULL, paren, and quote().

{
   int argc;
   char *scan, *wasdelim = NULL;
   int paren = 0, quote = 0, bracket = 0;

   if (!array || !arraylen) {
      return 0;
   }

   memset(array, 0, arraylen * sizeof(*array));

   if (!buf) {
      return 0;
   }

   scan = buf;

   for (argc = 0; *scan && (argc < arraylen - 1); argc++) {
      array[argc] = scan;
      for (; *scan; scan++) {
         if (*scan == '(') {
            paren++;
         } else if (*scan == ')') {
            if (paren) {
               paren--;
            }
         } else if (*scan == '[') {
            bracket++;
         } else if (*scan == ']') {
            if (bracket) {
               bracket--;
            }
         } else if (*scan == '"' && delim != '"') {
            quote = quote ? 0 : 1;
            if (remove_chars) {
               /* Remove quote character from argument */
               memmove(scan, scan + 1, strlen(scan));
               scan--;
            }
         } else if (*scan == '\\') {
            if (remove_chars) {
               /* Literal character, don't parse */
               memmove(scan, scan + 1, strlen(scan));
            } else {
               scan++;
            }
         } else if ((*scan == delim) && !paren && !quote && !bracket) {
            wasdelim = scan;
            *scan++ = '\0';
            break;
         }
      }
   }

   /* If the last character in the original string was the delimiter, then
    * there is one additional argument. */
   if (*scan || (scan > buf && (scan - 1) == wasdelim)) {
      array[argc++] = scan;
   }

   return argc;
}

__ast_vm_greeter_register()

int __ast_vm_greeter_register	(	const struct ast_vm_greeter_functions *	vm_table,
		struct ast_module *	module
	)

Set voicemail greeter function callbacks.

Since

13.0.0

Parameters

vm_table	Voicemail greeter function table to install.
module	Pointer to the module implementing the interface

Return values

0	on success.
-1	on error.
AST_MODULE_LOAD_DECLINE	if there's already another greeter registered.

Examples:

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

Definition at line 552 of file main/app.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_replace_unref, ast_log, AST_MODULE_LOAD_DECLINE, LOG_ERROR, LOG_WARNING, ast_vm_greeter_functions::module, ast_vm_greeter_functions::module_name, ast_vm_greeter_functions::module_version, NULL, RAII_VAR, table, VM_GREETER_MODULE_VERSION, and vm_table.

{
   RAII_VAR(struct ast_vm_greeter_functions *, table, NULL, ao2_cleanup);

   if (!vm_table->module_name) {
      ast_log(LOG_ERROR, "Voicemail greeter provider missing required information.\n");
      return -1;
   }
   if (vm_table->module_version != VM_GREETER_MODULE_VERSION) {
      ast_log(LOG_ERROR, "Voicemail greeter provider '%s' has incorrect version\n",
         vm_table->module_name);
      return -1;
   }

   table = ao2_global_obj_ref(vm_greeter_provider);
   if (table) {
      ast_log(LOG_WARNING, "Voicemail greeter provider already registered by %s.\n",
         table->module_name);
      return AST_MODULE_LOAD_DECLINE;
   }

   table = ao2_alloc_options(sizeof(*table), NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!table) {
      return -1;
   }
   *table = *vm_table;
   table->module = module;

   ao2_global_obj_replace_unref(vm_greeter_provider, table);
   return 0;
}

__ast_vm_register()

int __ast_vm_register	(	const struct ast_vm_functions *	vm_table,
		struct ast_module *	module
	)

Set voicemail function callbacks.

Parameters

vm_table	Voicemail function table to install.
module	Pointer to the module implementing the interface

Return values

0	on success.
-1	on error.
AST_MODULE_LOAD_DECLINE	if there's already another provider registered.

Examples:

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

Definition at line 441 of file main/app.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_replace_unref, ast_log, AST_MODULE_LOAD_DECLINE, LOG_ERROR, LOG_WARNING, ast_vm_functions::module, ast_vm_functions::module_name, ast_vm_functions::module_version, NULL, RAII_VAR, table, VM_MODULE_VERSION, and vm_table.

{
   RAII_VAR(struct ast_vm_functions *, table, NULL, ao2_cleanup);

   if (!vm_table->module_name) {
      ast_log(LOG_ERROR, "Voicemail provider missing required information.\n");
      return -1;
   }
   if (vm_table->module_version != VM_MODULE_VERSION) {
      ast_log(LOG_ERROR, "Voicemail provider '%s' has incorrect version\n",
         vm_table->module_name);
      return -1;
   }

   table = ao2_global_obj_ref(vm_provider);
   if (table) {
      ast_log(LOG_WARNING, "Voicemail provider already registered by %s.\n",
         table->module_name);
      return AST_MODULE_LOAD_DECLINE;
   }

   table = ao2_alloc_options(sizeof(*table), NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!table) {
      return -1;
   }
   *table = *vm_table;
   table->module = module;

   ao2_global_obj_replace_unref(vm_provider, table);
   return 0;
}

app_init()

int app_init

(

void

)

Initialize the application core.

Return values

0	Success
-1	Failure

Since

12

Examples:

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

Definition at line 3205 of file main/app.c.

References app_cleanup(), ast_register_cleanup(), child_cap, stasis_topic_create(), and stasis_topic_pool_create().

Referenced by asterisk_daemon().

{
   ast_register_cleanup(app_cleanup);
#ifdef HAVE_CAP
   child_cap = cap_from_text("cap_net_admin-eip");
#endif
   queue_topic_all = stasis_topic_create("queue:all");
   if (!queue_topic_all) {
      return -1;
   }
   queue_topic_pool = stasis_topic_pool_create(queue_topic_all);
   if (!queue_topic_pool) {
      return -1;
   }
   return 0;
}

ast_app_copy_recording_to_vm()

int ast_app_copy_recording_to_vm

(

struct ast_vm_recording_data *

vm_rec_data

)

param[in] vm_rec_data Contains data needed to make the recording. retval 0 voicemail successfully created from recording. retval -1 Failure

Examples:

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

Definition at line 669 of file main/app.c.

References VM_API_CALL.

Referenced by copy_to_voicemail().

{
   int res = -1;

   VM_API_CALL(res, copy_recording_to_vm, (vm_rec_data));
   return res;
}

ast_app_dtget()

int ast_app_dtget	(	struct ast_channel *	chan,
		const char *	context,
		char *	collect,
		size_t	size,
		int	maxlen,
		int	timeout
	)

Present a dialtone and collect a certain length extension.

Returns

Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension.

Note

Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly

Present a dialtone and collect a certain length extension.

Parameters

chan	struct.
context
collect
size
maxlen
timeout	timeout in milliseconds

Returns

0 if extension does not exist, 1 if extension exists

Examples:

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

Definition at line 139 of file main/app.c.

References ast_channel_caller(), ast_channel_pbx(), ast_channel_zone(), ast_exists_extension(), ast_get_indication_tone(), ast_ignore_pattern(), ast_log, ast_matchmore_extension(), ast_playtones_start(), ast_playtones_stop(), ast_tone_zone_sound_unref(), ast_waitfordigit(), ast_tone_zone_sound::data, ast_pbx::dtimeoutms, LOG_NOTICE, NULL, and S_COR.

Referenced by grab_transfer().

{
   struct ast_tone_zone_sound *ts;
   int res = 0, x = 0;

   if (maxlen > size) {
      maxlen = size;
   }

   if (!timeout) {
      if (ast_channel_pbx(chan) && ast_channel_pbx(chan)->dtimeoutms) {
         timeout = ast_channel_pbx(chan)->dtimeoutms;
      } else {
         timeout = 5000;
      }
   }

   if ((ts = ast_get_indication_tone(ast_channel_zone(chan), "dial"))) {
      res = ast_playtones_start(chan, 0, ts->data, 0);
      ts = ast_tone_zone_sound_unref(ts);
   } else {
      ast_log(LOG_NOTICE, "Huh....? no dial for indications?\n");
   }

   for (x = strlen(collect); x < maxlen; ) {
      res = ast_waitfordigit(chan, timeout);
      if (!ast_ignore_pattern(context, collect)) {
         ast_playtones_stop(chan);
      }
      if (res < 1) {
         break;
      }
      if (res == '#') {
         break;
      }
      collect[x++] = res;
      if (!ast_matchmore_extension(chan, context, collect, 1,
         S_COR(ast_channel_caller(chan)->id.number.valid, ast_channel_caller(chan)->id.number.str, NULL))) {
         break;
      }
   }

   if (res >= 0) {
      res = ast_exists_extension(chan, context, collect, 1,
         S_COR(ast_channel_caller(chan)->id.number.valid, ast_channel_caller(chan)->id.number.str, NULL)) ? 1 : 0;
   }

   return res;
}

ast_app_exec_macro()

int ast_app_exec_macro	(	struct ast_channel *	autoservice_chan,
		struct ast_channel *	macro_chan,
		const char *	macro_args
	)

Run a macro on a channel, placing an optional second channel into autoservice.

Since

11.0

This is a shorthand method that makes it very easy to run a macro on any given channel. It is perfectly reasonable to supply a NULL autoservice_chan here in case there is no channel to place into autoservice.

Note

Absolutely NO channel locks should be held before calling this function.

Parameters

autoservice_chan	A channel to place into autoservice while the macro is run
macro_chan	Channel to execute macro on.
macro_args	Macro application argument string.

Return values

0	success
-1	on error

Examples:

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

Definition at line 273 of file main/app.c.

References ast_autoservice_start(), ast_autoservice_stop(), ast_channel_context(), ast_channel_exten(), ast_channel_name(), ast_channel_priority(), ast_check_hangup_locked(), ast_debug, ast_log, ast_queue_hangup(), LOG_WARNING, pbx_exec(), and pbx_findapp().

Referenced by ast_app_run_macro(), dial_exec_full(), generic_recall(), run_app_helper(), and try_calling().

{
   struct ast_app *macro_app;
   int res;

   macro_app = pbx_findapp("Macro");
   if (!macro_app) {
      ast_log(LOG_WARNING,
         "Cannot run 'Macro(%s)'.  The application is not available.\n", macro_args);
      return -1;
   }
   if (autoservice_chan) {
      ast_autoservice_start(autoservice_chan);
   }

   ast_debug(4, "%s Original location: %s,%s,%d\n", ast_channel_name(macro_chan),
      ast_channel_context(macro_chan), ast_channel_exten(macro_chan),
      ast_channel_priority(macro_chan));

   res = pbx_exec(macro_chan, macro_app, macro_args);
   ast_debug(4, "Macro exited with status %d\n", res);

   /*
    * Assume anything negative from Macro is an error.
    * Anything else is success.
    */
   if (res < 0) {
      res = -1;
   } else {
      res = 0;
   }

   ast_debug(4, "%s Ending location: %s,%s,%d\n", ast_channel_name(macro_chan),
      ast_channel_context(macro_chan), ast_channel_exten(macro_chan),
      ast_channel_priority(macro_chan));

   if (autoservice_chan) {
      ast_autoservice_stop(autoservice_chan);
   }

   if (ast_check_hangup_locked(macro_chan)) {
      ast_queue_hangup(macro_chan);
   }

   return res;
}

ast_app_exec_sub()

int ast_app_exec_sub	(	struct ast_channel *	autoservice_chan,
		struct ast_channel *	sub_chan,
		const char *	sub_args,
		int	ignore_hangup
	)

Run a subroutine on a channel, placing an optional second channel into autoservice.

Since

11

This is a shorthand method that makes it very easy to run a subroutine on any given channel. It is perfectly reasonable to supply a NULL autoservice_chan here in case there is no channel to place into autoservice.

Note

Absolutely NO channel locks should be held before calling this function.

Parameters

autoservice_chan	A channel to place into autoservice while the subroutine is run
sub_chan	Channel to execute subroutine on.
sub_args	Gosub application argument string.
ignore_hangup	TRUE if a hangup does not stop execution of the routine.

Return values

0	success
-1	on error

Examples:

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

Definition at line 370 of file main/app.c.

References app_stack_callbacks, ast_autoservice_start(), ast_autoservice_stop(), ast_check_hangup_locked(), ast_log, ast_module_running_ref, ast_module_unref, ast_queue_hangup(), LOG_WARNING, ast_app_stack_funcs::module, and ast_app_stack_funcs::run_sub.

Referenced by app_exec(), ast_app_run_sub(), ast_pbx_hangup_handler_run(), ast_pre_call(), dial_exec_full(), generic_recall(), originate_exec(), page_exec(), queue_exec(), run_app_helper(), and try_calling().

{
   const struct ast_app_stack_funcs *funcs;
   int res;

   funcs = app_stack_callbacks;
   if (!funcs || !funcs->run_sub || !ast_module_running_ref(funcs->module)) {
      ast_log(LOG_WARNING,
         "Cannot run 'Gosub(%s)'.  The app_stack module is not available.\n",
         sub_args);
      return -1;
   }

   if (autoservice_chan) {
      ast_autoservice_start(autoservice_chan);
   }

   res = funcs->run_sub(sub_chan, sub_args, ignore_hangup);
   ast_module_unref(funcs->module);

   if (autoservice_chan) {
      ast_autoservice_stop(autoservice_chan);
   }

   if (!ignore_hangup && ast_check_hangup_locked(sub_chan)) {
      ast_queue_hangup(sub_chan);
   }

   return res;
}

ast_app_expand_sub_args()

const char* ast_app_expand_sub_args	(	struct ast_channel *	chan,
		const char *	args
	)

Add missing context/exten to subroutine argument string.

Parameters

chan	Channel to obtain context/exten.
args	Gosub application argument string.

Fills in the optional context and exten from the given channel.

Return values

New-args	Gosub argument string on success. Must be freed.
NULL	on error.

Examples:

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

Definition at line 351 of file main/app.c.

References app_stack_callbacks, ast_log, ast_module_running_ref, ast_module_unref, ast_app_stack_funcs::expand_sub_args, LOG_WARNING, ast_app_stack_funcs::module, and NULL.

Referenced by app_exec(), ast_pbx_hangup_handler_push(), dial_exec_full(), and page_exec().

{
   const struct ast_app_stack_funcs *funcs;
   const char *new_args;

   funcs = app_stack_callbacks;
   if (!funcs || !funcs->expand_sub_args || !ast_module_running_ref(funcs->module)) {
      ast_log(LOG_WARNING,
         "Cannot expand 'Gosub(%s)' arguments.  The app_stack module is not available.\n",
         args);
      return NULL;
   }

   new_args = funcs->expand_sub_args(chan, args);
   ast_module_unref(funcs->module);

   return new_args;
}

ast_app_getdata()

int ast_app_getdata	(	struct ast_channel *	c,
		const char *	prompt,
		char *	s,
		int	maxlen,
		int	timeout
	)

Plays a stream and gets DTMF data from a channel.

Parameters

c	Which channel one is interacting with
prompt	File to pass to ast_streamfile (the one that you wish to play). It is also valid for this to be multiple files concatenated by "&". For example, "file1&file2&file3".
s	The location where the DTMF data will be stored
maxlen	Max Length of the data
timeout	Timeout length waiting for data(in milliseconds). Set to 0 for standard timeout(six seconds), or -1 for no time out.

This function was designed for application programmers for situations where they need to play a message and then get some DTMF data in response to the message. If a digit is pressed during playback, it will immediately break out of the message and continue execution of your code.

Plays a stream and gets DTMF data from a channel.

Parameters

c	The channel to read from
prompt	The file to stream to the channel
s	The string to read in to. Must be at least the size of your length
maxlen	How many digits to read (maximum)
timeout	set timeout to 0 for "standard" timeouts. Set timeout to -1 for "ludicrous time" (essentially never times out)

Examples:

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

Definition at line 197 of file main/app.c.

References ast_channel_language(), ast_channel_pbx(), AST_GETDATA_EMPTY_END_TERMINATED, ast_readstring(), ast_strdupa, ast_streamfile(), ast_strlen_zero, ast_pbx::dtimeoutms, ast_pbx::rtimeoutms, strsep(), and timeout.

Referenced by auth_exec(), conf_exec(), conf_get_pin(), dictate_exec(), find_conf(), read_exec(), testclient_exec(), testserver_exec(), and vm_exec().

{
   int res = 0, to, fto;
   char *front, *filename;

   /* XXX Merge with full version? XXX */

   if (maxlen)
      s[0] = '\0';

   if (!prompt)
      prompt = "";

   filename = ast_strdupa(prompt);
   while ((front = strsep(&filename, "&"))) {
      if (!ast_strlen_zero(front)) {
         res = ast_streamfile(c, front, ast_channel_language(c));
         if (res)
            continue;
      }
      if (ast_strlen_zero(filename)) {
         /* set timeouts for the last prompt */
         fto = ast_channel_pbx(c) ? ast_channel_pbx(c)->rtimeoutms : 6000;
         to = ast_channel_pbx(c) ? ast_channel_pbx(c)->dtimeoutms : 2000;

         if (timeout > 0) {
            fto = to = timeout;
         }
         if (timeout < 0) {
            fto = to = 1000000000;
         }
      } else {
         /* there is more than one prompt, so
          * get rid of the long timeout between
          * prompts, and make it 50ms */
         fto = 50;
         to = ast_channel_pbx(c) ? ast_channel_pbx(c)->dtimeoutms : 2000;
      }
      res = ast_readstring(c, s, maxlen, to, fto, "#");
      if (res == AST_GETDATA_EMPTY_END_TERMINATED) {
         return res;
      }
      if (!ast_strlen_zero(s)) {
         return res;
      }
   }

   return res;
}

ast_app_getdata_full()

int ast_app_getdata_full	(	struct ast_channel *	c,
		const char *	prompt,
		char *	s,
		int	maxlen,
		int	timeout,
		int	audiofd,
		int	ctrlfd
	)

Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions.

Examples:

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

Definition at line 250 of file main/app.c.

References ast_channel_language(), ast_readstring_full(), ast_streamfile(), ast_strlen_zero, and timeout.

Referenced by handle_getdata().

{
   int res, to = 2000, fto = 6000;

   if (!ast_strlen_zero(prompt)) {
      res = ast_streamfile(c, prompt, ast_channel_language(c));
      if (res < 0) {
         return res;
      }
   }

   if (timeout > 0) {
      fto = to = timeout;
   }
   if (timeout < 0) {
      fto = to = 1000000000;
   }

   res = ast_readstring_full(c, s, maxlen, to, fto, "#", audiofd, ctrlfd);

   return res;
}

ast_app_group_discard()

int ast_app_group_discard

(

struct ast_channel *

chan

)

Discard all group counting for a channel.

Examples:

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

Definition at line 2162 of file main/app.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_group_info::chan, ast_group_info::group_list, and NULL.

Referenced by ast_channel_destructor().

{
   struct ast_group_info *gi = NULL;

   AST_RWLIST_WRLOCK(&groups);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&groups, gi, group_list) {
      if (gi->chan == chan) {
         AST_RWLIST_REMOVE_CURRENT(group_list);
         ast_free(gi);
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&groups);

   return 0;
}

ast_app_group_get_count()

int ast_app_group_get_count	(	const char *	group,
		const char *	category
	)

Get the current channel count of the specified group and category.

Examples:

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

Definition at line 2083 of file main/app.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strlen_zero, ast_group_info::category, ast_group_info::group, ast_group_info::group_list, and NULL.

Referenced by group_count_function_read().

{
   struct ast_group_info *gi = NULL;
   int count = 0;

   if (ast_strlen_zero(group)) {
      return 0;
   }

   AST_RWLIST_RDLOCK(&groups);
   AST_RWLIST_TRAVERSE(&groups, gi, group_list) {
      if (!strcasecmp(gi->group, group) && (ast_strlen_zero(category) || (!ast_strlen_zero(gi->category) && !strcasecmp(gi->category, category)))) {
         count++;
      }
   }
   AST_RWLIST_UNLOCK(&groups);

   return count;
}

ast_app_group_list_head()

struct ast_group_info* ast_app_group_list_head

(

void

)

Get the head of the group count list.

Examples:

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

Definition at line 2189 of file main/app.c.

References AST_RWLIST_FIRST.

Referenced by group_count_function_read(), group_function_read(), group_list_function_read(), and group_show_channels().

{
   return AST_RWLIST_FIRST(&groups);
}

ast_app_group_list_rdlock()

int ast_app_group_list_rdlock

(

void

)

Read Lock the group count list.

Examples:

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

Definition at line 2184 of file main/app.c.

References AST_RWLIST_RDLOCK.

Referenced by group_count_function_read(), group_function_read(), group_list_function_read(), and group_show_channels().

{
   return AST_RWLIST_RDLOCK(&groups);
}

ast_app_group_list_unlock()

int ast_app_group_list_unlock

(

void

)

Unlock the group count list.

Examples:

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

Definition at line 2194 of file main/app.c.

References AST_RWLIST_UNLOCK.

Referenced by group_count_function_read(), group_function_read(), group_list_function_read(), and group_show_channels().

{
   return AST_RWLIST_UNLOCK(&groups);
}

ast_app_group_list_wrlock()

int ast_app_group_list_wrlock

(

void

)

Write Lock the group count list.

Examples:

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

Definition at line 2179 of file main/app.c.

References AST_RWLIST_WRLOCK.

{
   return AST_RWLIST_WRLOCK(&groups);
}

ast_app_group_match_get_count()

int ast_app_group_match_get_count	(	const char *	groupmatch,
		const char *	category
	)

Get the current channel count of all groups that match the specified pattern and category.

Examples:

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

Definition at line 2103 of file main/app.c.

References ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strlen_zero, ast_group_info::category, ast_group_info::group, ast_group_info::group_list, LOG_ERROR, LOG_NOTICE, and NULL.

Referenced by AST_TEST_DEFINE(), and group_match_count_function_read().

{
   struct ast_group_info *gi = NULL;
   regex_t regexbuf_group;
   regex_t regexbuf_category;
   int count = 0;

   if (ast_strlen_zero(groupmatch)) {
      ast_log(LOG_NOTICE, "groupmatch empty\n");
      return 0;
   }

   /* if regex compilation fails, return zero matches */
   if (regcomp(&regexbuf_group, groupmatch, REG_EXTENDED | REG_NOSUB)) {
      ast_log(LOG_ERROR, "Regex compile failed on: %s\n", groupmatch);
      return 0;
   }

   if (!ast_strlen_zero(category) && regcomp(&regexbuf_category, category, REG_EXTENDED | REG_NOSUB)) {
      ast_log(LOG_ERROR, "Regex compile failed on: %s\n", category);
      regfree(&regexbuf_group);
      return 0;
   }

   AST_RWLIST_RDLOCK(&groups);
   AST_RWLIST_TRAVERSE(&groups, gi, group_list) {
      if (!regexec(&regexbuf_group, gi->group, 0, NULL, 0) && (ast_strlen_zero(category) || (!ast_strlen_zero(gi->category) && !regexec(&regexbuf_category, gi->category, 0, NULL, 0)))) {
         count++;
      }
   }
   AST_RWLIST_UNLOCK(&groups);

   regfree(&regexbuf_group);
   if (!ast_strlen_zero(category)) {
      regfree(&regexbuf_category);
   }

   return count;
}

ast_app_group_set_channel()

int ast_app_group_set_channel	(	struct ast_channel *	chan,
		const char *	data
	)

Set the group for a channel, splitting the provided data into group and category, if specified.

Examples:

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

Definition at line 2036 of file main/app.c.

References ast_app_group_split_group(), ast_calloc, ast_free, AST_RWLIST_INSERT_TAIL, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero, ast_group_info::category, ast_group_info::chan, ast_group_info::group, ast_group_info::group_list, len(), and NULL.

Referenced by AST_TEST_DEFINE(), dial_exec_full(), and group_function_write().

{
   int res = 0;
   char group[80] = "", category[80] = "";
   struct ast_group_info *gi = NULL;
   size_t len = 0;

   if (ast_app_group_split_group(data, group, sizeof(group), category, sizeof(category))) {
      return -1;
   }

   /* Calculate memory we will need if this is new */
   len = sizeof(*gi) + strlen(group) + 1;
   if (!ast_strlen_zero(category)) {
      len += strlen(category) + 1;
   }

   AST_RWLIST_WRLOCK(&groups);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&groups, gi, group_list) {
      if ((gi->chan == chan) && ((ast_strlen_zero(category) && ast_strlen_zero(gi->category)) || (!ast_strlen_zero(gi->category) && !strcasecmp(gi->category, category)))) {
         AST_RWLIST_REMOVE_CURRENT(group_list);
         ast_free(gi);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;

   if (ast_strlen_zero(group)) {
      /* Enable unsetting the group */
   } else if ((gi = ast_calloc(1, len))) {
      gi->chan = chan;
      gi->group = (char *) gi + sizeof(*gi);
      strcpy(gi->group, group);
      if (!ast_strlen_zero(category)) {
         gi->category = (char *) gi + sizeof(*gi) + strlen(group) + 1;
         strcpy(gi->category, category);
      }
      AST_RWLIST_INSERT_TAIL(&groups, gi, group_list);
   } else {
      res = -1;
   }

   AST_RWLIST_UNLOCK(&groups);

   return res;
}

ast_app_group_split_group()

int ast_app_group_split_group	(	const char *	data,
		char *	group,
		int	group_max,
		char *	category,
		int	category_max
	)

Split a group string into group and category, returning a default category if none is provided.

Examples:

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

Definition at line 2009 of file main/app.c.

References ast_copy_string(), ast_strlen_zero, NULL, and tmp().

Referenced by ast_app_group_set_channel(), group_count_function_read(), and group_match_count_function_read().

{
   int res = 0;
   char tmp[256];
   char *grp = NULL, *cat = NULL;

   if (!ast_strlen_zero(data)) {
      ast_copy_string(tmp, data, sizeof(tmp));
      grp = tmp;
      if ((cat = strchr(tmp, '@'))) {
         *cat++ = '\0';
      }
   }

   if (!ast_strlen_zero(grp)) {
      ast_copy_string(group, grp, group_max);
   } else {
      *group = '\0';
   }

   if (!ast_strlen_zero(cat)) {
      ast_copy_string(category, cat, category_max);
   }

   return res;
}

ast_app_group_update()

int ast_app_group_update	(	struct ast_channel *	oldchan,
		struct ast_channel *	newchan
	)

Update all group counting for a channel to a new one.

Examples:

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

Definition at line 2143 of file main/app.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_group_info::chan, ast_group_info::group_list, and NULL.

Referenced by channel_do_masquerade().

{
   struct ast_group_info *gi = NULL;

   AST_RWLIST_WRLOCK(&groups);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&groups, gi, group_list) {
      if (gi->chan == old) {
         gi->chan = new;
      } else if (gi->chan == new) {
         AST_RWLIST_REMOVE_CURRENT(group_list);
         ast_free(gi);
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&groups);

   return 0;
}

ast_app_has_voicemail()

int ast_app_has_voicemail	(	const char *	mailboxes,
		const char *	folder
	)

Determine if a given mailbox has any voicemail If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the number of messages in the "Urgent" folder.

Return values

1	Mailbox has voicemail
0	No new voicemail in specified mailbox
-1	Failure

Since

1.0

Examples:

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

Definition at line 655 of file main/app.c.

References has_voicemail(), and VM_API_CALL.

Referenced by action_mailboxstatus(), AST_TEST_DEFINE(), has_voicemail(), mwi_update_cb(), notify_new_message(), play_dialtone(), poll_mailbox(), run_externnotify(), skinny_register(), and unistim_send_mwi_to_peer().

{
   int res = 0;

   VM_API_CALL(res, has_voicemail, (mailboxes, folder));
   return res;
}

ast_app_inboxcount()

int ast_app_inboxcount	(	const char *	mailboxes,
		int *	newmsgs,
		int *	oldmsgs
	)

Determine number of new/old messages in a mailbox.

Since

1.0

Parameters

[in]	mailboxes	Mailbox specification in the format /code mbox[@context][&mbox2[@context2]][...] /code
[out]	newmsgs	Number of messages in the "INBOX" folder. Includes number of messages in the "Urgent" folder, if any.
[out]	oldmsgs	Number of messages in the "Old" folder.

Return values

0	Success
-1	Failure

Examples:

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

Definition at line 677 of file main/app.c.

References inboxcount(), and VM_API_CALL.

Referenced by AST_TEST_DEFINE(), sip_send_mwi_to_peer(), and update_registry().

{
   int res = 0;

   if (newmsgs) {
      *newmsgs = 0;
   }
   if (oldmsgs) {
      *oldmsgs = 0;
   }

   VM_API_CALL(res, inboxcount, (mailboxes, newmsgs, oldmsgs));
   return res;
}

ast_app_inboxcount2()

int ast_app_inboxcount2	(	const char *	mailboxes,
		int *	urgentmsgs,
		int *	newmsgs,
		int *	oldmsgs
	)

Determine number of urgent/new/old messages in a mailbox.

Parameters

[in]	mailboxes	the mailbox context to use
[out]	urgentmsgs	the urgent message count
[out]	newmsgs	the new message count
[out]	oldmsgs	the old message count

Returns

Returns 0 for success, negative upon error

Since

1.6.1

Examples:

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

Definition at line 692 of file main/app.c.

References inboxcount2(), and VM_API_CALL.

Referenced by action_mailboxcount(), AST_TEST_DEFINE(), mwi_retrieve_then_create_state(), notify_new_message(), notify_new_state(), and vm_execmain().

{
   int res = 0;

   if (newmsgs) {
      *newmsgs = 0;
   }
   if (oldmsgs) {
      *oldmsgs = 0;
   }
   if (urgentmsgs) {
      *urgentmsgs = 0;
   }

   VM_API_CALL(res, inboxcount2, (mailboxes, urgentmsgs, newmsgs, oldmsgs));
   return res;
}

ast_app_messagecount()

int ast_app_messagecount	(	const char *	mailbox_id,
		const char *	folder
	)

Get the number of messages in a given mailbox folder.

Parameters

[in]	mailbox_id	Mailbox name
[in]	folder	The folder to look in. Default is INBOX if not provided.

Note

If requesting INBOX then the returned count is INBOX + Urgent.

Returns

The number of messages in the mailbox folder (zero or more).

Examples:

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

Definition at line 718 of file main/app.c.

References messagecount(), and VM_API_CALL.

Referenced by acf_vmcount_exec(), and AST_TEST_DEFINE().

{
   int res = 0;

   VM_API_CALL(res, messagecount, (mailbox_id, folder));
   return res;
}

ast_app_options2str64()

void ast_app_options2str64	(	const struct ast_app_option *	options,
		struct ast_flags64 *	flags,
		char *	buf,
		size_t	len
	)

Given a list of options array, return an option string based on passed flags.

Parameters

options	The array of possible options declared with AST_APP_OPTIONS
flags	The flags of the options that you wish to populate the buffer with
buf	The buffer to fill with the string of options
len	The maximum length of buf

Examples:

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

Definition at line 2916 of file main/app.c.

References ast_test_flag64, and len().

{
   unsigned int i, found = 0;
   for (i = 32; i < 128 && found < len; i++) {
      if (ast_test_flag64(flags, options[i].flag)) {
         buf[found++] = i;
      }
   }
   buf[found] = '\0';
}

ast_app_parse_options()

int ast_app_parse_options	(	const struct ast_app_option *	options,
		struct ast_flags *	flags,
		char **	args,
		char *	optstr
	)

Parses a string containing application options and sets flags/arguments.

Parameters

options	The array of possible options declared with AST_APP_OPTIONS
flags	The flag structure to have option flags set
args	The array of argument pointers to hold arguments found
optstr	The string containing the options to be parsed

Returns

zero for success, non-zero if an error occurs

See also

AST_APP_OPTIONS

Examples:

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

Definition at line 2906 of file main/app.c.

References parse_options().

Referenced by agent_login_exec(), app_exec(), ast_multicast_rtp_create_options(), AST_TEST_DEFINE(), audiosocket_request(), auth_exec(), bridge_exec(), bridgewait_exec(), cdr_read_callback(), cdr_write_callback(), chanspy_exec(), connectedline_write(), controlplayback_exec(), detect_write(), directory_exec(), disa_exec(), dundi_query_read(), dundifunc_read(), extenspy_exec(), forkcdr_exec(), handle_options(), hint_read(), manager_mixmonitor(), minivm_accmess_exec(), minivm_greet_exec(), minivm_record_exec(), mixmonitor_exec(), page_exec(), park_app_parse_data(), pbx_builtin_background(), pbx_builtin_waitexten(), pickupchan_exec(), queue_exec(), read_exec(), read_mf_exec(), read_sf_exec(), readexten_exec(), realtime_common(), receivefax_exec(), record_exec(), redirecting_write(), resetcdr_exec(), sendfax_exec(), sendurl_exec(), sla_trunk_exec(), smdi_msg_retrieve_read(), sms_exec(), softhangup_exec(), speech_background(), start_monitor_exec(), unicast_rtp_request(), vm_exec(), vm_execmain(), volume_write(), and wait_exec().

{
   return parse_options(options, flags, args, optstr, 32);
}

ast_app_parse_options64()

int ast_app_parse_options64	(	const struct ast_app_option *	options,
		struct ast_flags64 *	flags,
		char **	args,
		char *	optstr
	)

Parses a string containing application options and sets flags/arguments.

Parameters

options	The array of possible options declared with AST_APP_OPTIONS
flags	The 64-bit flag structure to have option flags set
args	The array of argument pointers to hold arguments found
optstr	The string containing the options to be parsed

Returns

zero for success, non-zero if an error occurs

See also

AST_APP_OPTIONS

Examples:

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

Definition at line 2911 of file main/app.c.

References parse_options().

Referenced by AST_TEST_DEFINE(), conf_exec(), dial_exec_full(), find_conf_realtime(), originate_exec(), and sayunixtime_exec().

{
   return parse_options(options, flags, args, optstr, 64);
}

ast_app_parse_timelen()

int ast_app_parse_timelen	(	const char *	timestr,
		int *	result,
		enum ast_timelen	defunit
	)

Common routine to parse time lengths, with optional time unit specifier.

Parameters

[in]	timestr	String to parse
[in]	defunit	Default unit type
[out]	result	Resulting value, specified in milliseconds

Return values

0	Success
-1	Failure

Since

1.8

Examples:

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

Definition at line 3113 of file main/app.c.

References FMT, TIMELEN_HOURS, TIMELEN_MILLISECONDS, TIMELEN_MINUTES, and TIMELEN_SECONDS.

Referenced by ast_eivr_senddtmf(), ast_parse_arg(), new_realtime_sqlite3_db(), pbx_builtin_wait(), pbx_builtin_waitdigit(), pbx_builtin_waitexten(), senddtmf_exec(), and sendmf_exec().

{
   int res;
   char u[10];
#ifdef HAVE_LONG_DOUBLE_WIDER
   long double amount;
   #define FMT "%30Lf%9s"
#else
   double amount;
   #define FMT "%30lf%9s"
#endif
   if (!timestr) {
      return -1;
   }

   res = sscanf(timestr, FMT, &amount, u);

   if (res == 0 || res == EOF) {
#undef FMT
      return -1;
   } else if (res == 2) {
      switch (u[0]) {
      case 'h':
      case 'H':
         unit = TIMELEN_HOURS;
         if (u[1] != '\0') {
            return -1;
         }
         break;
      case 's':
      case 'S':
         unit = TIMELEN_SECONDS;
         if (u[1] != '\0') {
            return -1;
         }
         break;
      case 'm':
      case 'M':
         if (toupper(u[1]) == 'S') {
            unit = TIMELEN_MILLISECONDS;
            if (u[2] != '\0') {
               return -1;
            }
         } else if (u[1] == '\0') {
            unit = TIMELEN_MINUTES;
         } else {
            return -1;
         }
         break;
      default:
         return -1;
      }
   }

   switch (unit) {
   case TIMELEN_HOURS:
      amount *= 60;
      /* fall-through */
   case TIMELEN_MINUTES:
      amount *= 60;
      /* fall-through */
   case TIMELEN_SECONDS:
      amount *= 1000;
      /* fall-through */
   case TIMELEN_MILLISECONDS:
      ;
   }
   *result = amount > INT_MAX ? INT_MAX : (int) amount;
   return 0;
}

ast_app_run_macro()

int ast_app_run_macro	(	struct ast_channel *	autoservice_chan,
		struct ast_channel *	macro_chan,
		const char *	macro_name,
		const char *	macro_args
	)

Run a macro on a channel, placing an optional second channel into autoservice.

Since

1.8

This is a shorthand method that makes it very easy to run a macro on any given channel. It is perfectly reasonable to supply a NULL autoservice_chan here in case there is no channel to place into autoservice.

Note

Absolutely NO channel locks should be held before calling this function.

Parameters

autoservice_chan	A channel to place into autoservice while the macro is run
macro_chan	Channel to execute macro on.
macro_name	The name of the macro to run.
macro_args	The arguments to pass to the macro.

Return values

0	success
-1	on error

Examples:

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

Definition at line 320 of file main/app.c.

References ast_app_exec_macro(), ast_free, ast_malloc, and ast_strlen_zero.

Referenced by ast_channel_connected_line_macro(), and ast_channel_redirecting_macro().

{
   int res;
   char *args_str;
   size_t args_len;

   if (ast_strlen_zero(macro_args)) {
      return ast_app_exec_macro(autoservice_chan, macro_chan, macro_name);
   }

   /* Create the Macro application argument string. */
   args_len = strlen(macro_name) + strlen(macro_args) + 2;
   args_str = ast_malloc(args_len);
   if (!args_str) {
      return -1;
   }
   snprintf(args_str, args_len, "%s,%s", macro_name, macro_args);

   res = ast_app_exec_macro(autoservice_chan, macro_chan, args_str);
   ast_free(args_str);
   return res;
}

ast_app_run_sub()

int ast_app_run_sub	(	struct ast_channel *	autoservice_chan,
		struct ast_channel *	sub_chan,
		const char *	sub_location,
		const char *	sub_args,
		int	ignore_hangup
	)

Run a subroutine on a channel, placing an optional second channel into autoservice.

Since

11

This is a shorthand method that makes it very easy to run a subroutine on any given channel. It is perfectly reasonable to supply a NULL autoservice_chan here in case there is no channel to place into autoservice.

Note

Absolutely NO channel locks should be held before calling this function.

Parameters

autoservice_chan	A channel to place into autoservice while the subroutine is run
sub_chan	Channel to execute subroutine on.
sub_location	The location of the subroutine to run.
sub_args	The arguments to pass to the subroutine.
ignore_hangup	TRUE if a hangup does not stop execution of the routine.

Return values

0	success
-1	on error

Examples:

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

Definition at line 401 of file main/app.c.

References AO2_GLOBAL_OBJ_STATIC(), ast_app_exec_sub(), ast_free, ast_malloc, and ast_strlen_zero.

Referenced by ast_channel_connected_line_sub(), and ast_channel_redirecting_sub().

{
   int res;
   char *args_str;
   size_t args_len;

   if (ast_strlen_zero(sub_args)) {
      return ast_app_exec_sub(autoservice_chan, sub_chan, sub_location, ignore_hangup);
   }

   /* Create the Gosub application argument string. */
   args_len = strlen(sub_location) + strlen(sub_args) + 3;
   args_str = ast_malloc(args_len);
   if (!args_str) {
      return -1;
   }
   snprintf(args_str, args_len, "%s(%s)", sub_location, sub_args);

   res = ast_app_exec_sub(autoservice_chan, sub_chan, args_str, ignore_hangup);
   ast_free(args_str);
   return res;
}

ast_app_sayname()

int ast_app_sayname	(	struct ast_channel *	chan,
		const char *	mailbox_id
	)

Play a recorded user name for the mailbox to the specified channel.

Parameters

chan	Where to play the recorded name file.
mailbox_id	The mailbox name.

Return values

0	Name played without interruption
dtmf	ASCII value of the DTMF which interrupted playback.
-1	Unable to locate mailbox or hangup occurred.

Examples:

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

Definition at line 710 of file main/app.c.

References sayname(), and VM_GREETER_API_CALL.

Referenced by play_mailbox_owner(), and spy_sayname().

{
   int res = -1;

   VM_GREETER_API_CALL(res, sayname, (chan, mailbox_id));
   return res;
}

ast_close_fds_above_n()

void ast_close_fds_above_n

(

int

n

)

Common routine for child processes, to close all fds prior to exec(2)

Parameters

[in]

n

starting file descriptor number for closing all higher file descriptors

Since

1.6.1

Examples:

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

Definition at line 3042 of file main/app.c.

References closefrom().

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

{
   closefrom(n + 1);
}

ast_control_streamfile()

int ast_control_streamfile	(	struct ast_channel *	chan,
		const char *	file,
		const char *	fwd,
		const char *	rev,
		const char *	stop,
		const char *	pause,
		const char *	restart,
		int	skipms,
		long *	offsetms
	)

Stream a file with fast forward, pause, reverse, restart.

Parameters

chan	Channel
file	File to play.
fwd,rev,stop,pause,restart	DTMF keys for media control
skipms	Number of milliseconds to skip for fwd/rev.
offsetms	Number of milliseconds to skip when starting the media.

Before calling this function, set this to be the number of ms to start from the beginning of the file. When the function returns, it will be the number of ms from the beginning where the playback stopped. Pass NULL if you don't care.

Return values

0	on success
Non-zero	on failure

Examples:

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

Definition at line 1319 of file main/app.c.

References control_streamfile(), and NULL.

Referenced by controlplayback_exec(), handle_controlstreamfile(), and wait_file().

{
   return control_streamfile(chan, file, fwd, rev, stop, suspend, restart, skipms, offsetms, NULL, NULL);
}

ast_control_streamfile_lang()

int ast_control_streamfile_lang	(	struct ast_channel *	chan,
		const char *	file,
		const char *	fwd,
		const char *	rev,
		const char *	stop,
		const char *	suspend,
		const char *	restart,
		int	skipms,
		const char *	lang,
		long *	offsetms
	)

Version of ast_control_streamfile() which allows the language of the media file to be specified.

Return values

0	on success
Non-zero	on failure

Examples:

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

Definition at line 1327 of file main/app.c.

References control_streamfile(), and NULL.

Referenced by play_on_channel().

{
   return control_streamfile(chan, file, fwd, rev, stop, suspend, restart, skipms, offsetms, lang, NULL);
}

ast_control_streamfile_w_cb()

int ast_control_streamfile_w_cb	(	struct ast_channel *	chan,
		const char *	file,
		const char *	fwd,
		const char *	rev,
		const char *	stop,
		const char *	pause,
		const char *	restart,
		int	skipms,
		long *	offsetms,
		ast_waitstream_fr_cb	cb
	)

Stream a file with fast forward, pause, reverse, restart.

Parameters

chan
file	filename
fwd,rev,stop,pause,restart,skipms,offsetms
cb	waitstream callback to invoke when fastforward or rewind occurrs.

Before calling this function, set this to be the number of ms to start from the beginning of the file. When the function returns, it will be the number of ms from the beginning where the playback stopped. Pass NULL if you don't care.

Examples:

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

Definition at line 1305 of file main/app.c.

References control_streamfile(), and NULL.

{
   return control_streamfile(chan, file, fwd, rev, stop, suspend, restart, skipms, offsetms, NULL, cb);
}

ast_control_tone()

int ast_control_tone	(	struct ast_channel *	chan,
		const char *	tone
	)

Controls playback of a tone.

Return values

0	on success
Non-zero	on failure

Examples:

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

Definition at line 1399 of file main/app.c.

References ast_channel_zone(), AST_FRAME_CONTROL, ast_get_indication_tone(), ast_get_indication_zone(), ast_playtones_start(), ast_read_noaudio(), ast_strdupa, ast_strlen_zero, ast_tone_zone_sound_unref(), ast_tone_zone_unref(), ast_waitfor(), control_tone_frame_response(), CONTROL_TONE_RESPONSE_FAILED, CONTROL_TONE_RESPONSE_FINISHED, ast_tone_zone_sound::data, ast_frame::frametype, NULL, and parse_tone_uri().

Referenced by play_on_channel().

{
   struct ast_tone_zone *zone = NULL;
   struct ast_tone_zone_sound *ts;
   int paused = 0;
   int res = 0;

   const char *tone_indication = NULL;
   const char *tone_zone = NULL;
   char *tone_uri_parser;

   if (ast_strlen_zero(tone)) {
      return -1;
   }

   tone_uri_parser = ast_strdupa(tone);

   if (parse_tone_uri(tone_uri_parser, &tone_indication, &tone_zone)) {
      return -1;
   }

   if (tone_zone) {
      zone = ast_get_indication_zone(tone_zone);
   }

   ts = ast_get_indication_tone(zone ? zone : ast_channel_zone(chan), tone_indication);

   if (ast_playtones_start(chan, 0, ts ? ts->data : tone_indication, 0)) {
      res = -1;
   }

   while (!res) {
      struct ast_frame *fr;

      if (ast_waitfor(chan, -1) < 0) {
         res = -1;
         break;
      }

      fr = ast_read_noaudio(chan);

      if (!fr) {
         res = -1;
         break;
      }

      if (fr->frametype != AST_FRAME_CONTROL) {
         continue;
      }

      res = control_tone_frame_response(chan, fr, ts, tone_indication, &paused);
      if (res == CONTROL_TONE_RESPONSE_FINISHED) {
         res = 0;
         break;
      } else if (res == CONTROL_TONE_RESPONSE_FAILED) {
         res = -1;
         break;
      }
   }

   if (ts) {
      ast_tone_zone_sound_unref(ts);
   }

   if (zone) {
      ast_tone_zone_unref(zone);
   }

   return res;
}

ast_dtmf_stream()

int ast_dtmf_stream	(	struct ast_channel *	chan,
		struct ast_channel *	peer,
		const char *	digits,
		int	between,
		unsigned int	duration
	)

Send a string of DTMF digits to a channel.

Parameters

chan	The channel that will receive the DTMF frames
peer	(optional) Peer channel that will be autoserviced while the primary channel is receiving DTMF
digits	This is a string of characters representing the DTMF digits to be sent to the channel. Valid characters are "0123456789*#abcdABCD". Note: You can pass arguments 'f' or 'F', if you want to Flash the channel (if supported by the channel), or 'w' to add a 500 millisecond pause to the DTMF sequence.
between	This is the number of milliseconds to wait in between each DTMF digit. If zero milliseconds is specified, then the default value of 100 will be used.
duration	This is the duration that each DTMF digit should have.

Precondition

This must only be called by the channel's media handler thread.

Return values

0	on success.
-1	on failure or a channel hung up.

Examples:

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

Definition at line 981 of file main/app.c.

References ast_autoservice_start(), ast_autoservice_stop(), and dtmf_stream().

Referenced by ast_eivr_senddtmf(), bridge_channel_dtmf_stream(), dial_exec_full(), dtmf_no_bridge(), handle_cli_misdn_send_digit(), senddtmf_exec(), testclient_exec(), testserver_exec(), and wait_for_answer().

{
   int res;

   if (peer && ast_autoservice_start(peer)) {
      return -1;
   }
   res = dtmf_stream(chan, digits, between, duration, 0);
   if (peer && ast_autoservice_stop(peer)) {
      res = -1;
   }

   return res;
}

ast_dtmf_stream_external()

void ast_dtmf_stream_external	(	struct ast_channel *	chan,
		const char *	digits,
		int	between,
		unsigned int	duration
	)

Send a string of DTMF digits to a channel from an external thread.

Parameters

chan	The channel that will receive the DTMF frames
digits	This is a string of characters representing the DTMF digits to be sent to the channel. Valid characters are "0123456789*#abcdABCD". Note: You can pass arguments 'f' or 'F', if you want to Flash the channel (if supported by the channel), or 'w' to add a 500 millisecond pause to the DTMF sequence.
between	This is the number of milliseconds to wait in between each DTMF digit. If zero milliseconds is specified, then the default value of 100 will be used.
duration	This is the duration that each DTMF digit should have.

Precondition

This must only be called by threads that are not the channel's media handler thread.

Returns

Nothing

Examples:

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

Definition at line 996 of file main/app.c.

References dtmf_stream().

Referenced by dtmf_in_bridge().

{
   dtmf_stream(chan, digits, between, duration, 1);
}

ast_get_encoded_char()

int ast_get_encoded_char	(	const char *	stream,
		char *	result,
		size_t *	consumed
	)

Decode an encoded control or extended ASCII character.

Parameters

[in]	stream	String to decode
[out]	result	Decoded character
[out]	consumed	Number of characters used in stream to encode the character

Return values

-1	Stream is of zero length
0	Success

Examples:

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

Definition at line 2927 of file main/app.c.

References ast_debug, ast_log, ast_strlen_zero, and LOG_ERROR.

Referenced by ast_get_encoded_str(), ast_str_get_encoded_str(), cut_internal(), filter(), function_fieldnum_helper(), function_fieldqty_helper(), replace(), shift_pop(), and unshift_push().

{
   int i;
   *consumed = 1;
   *result = 0;
   if (ast_strlen_zero(stream)) {
      *consumed = 0;
      return -1;
   }

   if (*stream == '\\') {
      *consumed = 2;
      switch (*(stream + 1)) {
      case 'n':
         *result = '\n';
         break;
      case 'r':
         *result = '\r';
         break;
      case 't':
         *result = '\t';
         break;
      case 'x':
         /* Hexadecimal */
         if (strchr("0123456789ABCDEFabcdef", *(stream + 2)) && *(stream + 2) != '\0') {
            *consumed = 3;
            if (*(stream + 2) <= '9') {
               *result = *(stream + 2) - '0';
            } else if (*(stream + 2) <= 'F') {
               *result = *(stream + 2) - 'A' + 10;
            } else {
               *result = *(stream + 2) - 'a' + 10;
            }
         } else {
            ast_log(LOG_ERROR, "Illegal character '%c' in hexadecimal string\n", *(stream + 2));
            return -1;
         }

         if (strchr("0123456789ABCDEFabcdef", *(stream + 3)) && *(stream + 3) != '\0') {
            *consumed = 4;
            *result <<= 4;
            if (*(stream + 3) <= '9') {
               *result += *(stream + 3) - '0';
            } else if (*(stream + 3) <= 'F') {
               *result += *(stream + 3) - 'A' + 10;
            } else {
               *result += *(stream + 3) - 'a' + 10;
            }
         }
         break;
      case '0':
         /* Octal */
         *consumed = 2;
         for (i = 2; ; i++) {
            if (strchr("01234567", *(stream + i)) && *(stream + i) != '\0') {
               (*consumed)++;
               ast_debug(5, "result was %d, ", *result);
               *result <<= 3;
               *result += *(stream + i) - '0';
               ast_debug(5, "is now %d\n", *result);
            } else {
               break;
            }
         }
         break;
      default:
         *result = *(stream + 1);
      }
   } else {
      *result = *stream;
      *consumed = 1;
   }
   return 0;
}

ast_get_encoded_str()

char* ast_get_encoded_str	(	const char *	stream,
		char *	result,
		size_t	result_len
	)

Decode a stream of encoded control or extended ASCII characters.

Parameters

[in]	stream	Encoded string
[out]	result	Decoded string
[in]	result_len	Maximum size of the result buffer

Returns

A pointer to the result string

Examples:

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

Definition at line 3002 of file main/app.c.

References ast_get_encoded_char(), and result.

Referenced by chan_pjsip_new(), listfilter(), mgcp_new(), replace(), sip_addheader(), and sip_new().

{
   char *cur = result;
   size_t consumed;

   while (cur < result + result_size - 1 && !ast_get_encoded_char(stream, cur, &consumed)) {
      cur++;
      stream += consumed;
   }
   *cur = '\0';
   return result;
}

ast_install_stack_functions()

void ast_install_stack_functions

(

const struct ast_app_stack_funcs *

funcs

)

Set stack application function callbacks.

Since

11

Parameters

funcs

Stack applications callback functions.

Examples:

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

Definition at line 346 of file main/app.c.

Referenced by load_module(), and unload_module().

{
   app_stack_callbacks = funcs;
}

ast_install_vm_test_functions()

void ast_install_vm_test_functions	(	ast_vm_test_create_user_fn *	vm_test_create_user_func,
		ast_vm_test_destroy_user_fn *	vm_test_destroy_user_func
	)

Examples:

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

Definition at line 599 of file main/app.c.

References ast_vm_test_create_user_func, and ast_vm_test_destroy_user_func.

Referenced by load_module().

{
   ast_vm_test_create_user_func = vm_test_create_user_func;
   ast_vm_test_destroy_user_func = vm_test_destroy_user_func;
}

ast_ivr_menu_run()

int ast_ivr_menu_run	(	struct ast_channel *	c,
		struct ast_ivr_menu *	menu,
		void *	cbdata
	)

Runs an IVR menu.

Returns

returns 0 on successful completion, -1 on hangup, or -2 on user error in menu

Examples:

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

Definition at line 2785 of file main/app.c.

References ast_ivr_menu_run_internal().

Referenced by skel_exec().

{
   int res = ast_ivr_menu_run_internal(chan, menu, cbdata);
   /* Hide internal coding */
   return res > 0 ? 0 : res;
}

ast_linear_stream()

int ast_linear_stream	(	struct ast_channel *	chan,
		const char *	filename,
		int	fd,
		int	allowoverride
	)

Stream a filename (or file descriptor) as a generator.

Examples:

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

Definition at line 1089 of file main/app.c.

References linear_state::allowoverride, ast_activate_generator(), ast_calloc, ast_config_AST_DATA_DIR, ast_copy_string(), ast_log, ast_strlen_zero, linear_state::autoclose, errno, linear_state::fd, and LOG_WARNING.

{
   struct linear_state *lin;
   char tmpf[256];
   int autoclose = 0;

   if (fd < 0) {
      if (ast_strlen_zero(filename)) {
         return -1;
      }

      autoclose = 1;

      if (filename[0] == '/') {
         ast_copy_string(tmpf, filename, sizeof(tmpf));
      } else {
         snprintf(tmpf, sizeof(tmpf), "%s/%s/%s", ast_config_AST_DATA_DIR, "sounds", filename);
      }

      fd = open(tmpf, O_RDONLY);
      if (fd < 0) {
         ast_log(LOG_WARNING, "Unable to open file '%s': %s\n", tmpf, strerror(errno));
         return -1;
      }
   }

   lin = ast_calloc(1, sizeof(*lin));
   if (!lin) {
      if (autoclose) {
         close(fd);
      }

      return -1;
   }

   lin->fd = fd;
   lin->allowoverride = allowoverride;
   lin->autoclose = autoclose;

   return ast_activate_generator(chan, &linearstream, lin);
}

ast_lock_path()

enum AST_LOCK_RESULT ast_lock_path

(

const char *

path

)

Lock a filesystem path.

Parameters

path	the path to be locked

Returns

one of AST_LOCK_RESULT values

Examples:

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

Definition at line 2457 of file main/app.c.

References AST_LOCK_FAILURE, ast_lock_path_flock(), ast_lock_path_lockfile(), AST_LOCK_TYPE_FLOCK, and AST_LOCK_TYPE_LOCKFILE.

Referenced by ast_module_reload(), test_vm_api_create_voicemail_files(), and vm_lock_path().

{
   enum AST_LOCK_RESULT r = AST_LOCK_FAILURE;

   switch (ast_lock_type) {
   case AST_LOCK_TYPE_LOCKFILE:
      r = ast_lock_path_lockfile(path);
      break;
   case AST_LOCK_TYPE_FLOCK:
      r = ast_lock_path_flock(path);
      break;
   }

   return r;
}

ast_mf_stream()

int ast_mf_stream	(	struct ast_channel *	chan,
		struct ast_channel *	peer,
		const char *	digits,
		int	between,
		unsigned int	duration,
		unsigned int	durationkp,
		unsigned int	durationst,
		int	is_external
	)

Send a string of MF digits to a channel.

Parameters

chan	The channel that will receive the MF frames
peer	(optional) Peer channel that will be autoserviced while the primary channel is receiving MF
digits	This is a string of characters representing the MF digits to be sent to the channel. Valid characters are "0123456789*#abcdABCD". Note: You can pass arguments 'f' or 'F', if you want to Flash the channel (if supported by the channel), or 'w' or 'W' to add a wink (if supported by the channel).
between	This is the number of milliseconds to wait in between each MF digit. If zero milliseconds is specified, then the default value of 50 will be used.
duration	This is the duration that each numeric MF digit should have. Default value is 55.
durationkp	This is the duration that each KP digit should have. Default is 120.
durationst	This is the duration that each ST, STP, ST2P, or ST3P digit should have. Default is 65.
is_external	1 if called by a thread that is not the channel's media handler thread, 0 if called by the channel's media handler thread.

Return values

0	on success.
-1	on failure or a channel hung up.

Examples:

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

Definition at line 967 of file main/app.c.

References ast_autoservice_start(), ast_autoservice_stop(), and mf_stream().

Referenced by dial_exec_full(), manager_play_mf(), sendmf_exec(), and wait_for_answer().

{
   int res;
   if (!is_external && peer && ast_autoservice_start(peer)) {
      return -1;
   }
   res = mf_stream(chan, digits, between, duration, durationkp, durationst, is_external);
   if (!is_external && peer && ast_autoservice_stop(peer)) {
      res = -1;
   }
   return res;
}

ast_play_and_prepend()

int ast_play_and_prepend	(	struct ast_channel *	chan,
		char *	playfile,
		char *	recordfile,
		int	maxtime_sec,
		char *	fmt,
		int *	duration,
		int *	sound_duration,
		int	beep,
		int	silencethreshold,
		int	maxsilence_ms
	)

Record a file based on input frm a channel. Recording is performed in 'prepend' mode which works a little differently from normal recordings This function will not play a success message due to post-recording control in the application this was added for.

Parameters

chan	the channel being recorded
playfile	Filename of sound to play before recording begins
recordfile	Filename to save the recording
maxtime_sec	Longest possible message length in seconds
fmt	string containing all formats to be recorded delimited by '|'
duration	pointer to integer for storing length of the recording
sound_duration	pointer to integer for storing length of the recording minus all silence
beep	whether to play a beep to prompt the recording
silencethreshold	tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
maxsilence_ms	length of time in milliseconds which will trigger a timeout from silence, -1 for default.

Return values

-1	failure or hangup
'S'	Recording ended from silence timeout
't'	Recording either exceeded maximum duration or the call was ended via DTMF

Examples:

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

Definition at line 2002 of file main/app.c.

References __ast_play_and_record(), AST_RECORD_IF_EXISTS_OVERWRITE, default_acceptdtmf, default_canceldtmf, and NULL.

Referenced by vm_forwardoptions().

{
   return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, sound_duration, beep, silencethreshold, maxsilence, NULL, 1, default_acceptdtmf, default_canceldtmf, 1, AST_RECORD_IF_EXISTS_OVERWRITE);
}

ast_play_and_record()

int ast_play_and_record	(	struct ast_channel *	chan,
		const char *	playfile,
		const char *	recordfile,
		int	maxtime_sec,
		const char *	fmt,
		int *	duration,
		int *	sound_duration,
		int	silencethreshold,
		int	maxsilence_ms,
		const char *	path
	)

Record a file based on input from a channel. Use default accept and cancel DTMF. This function will play "auth-thankyou" upon successful recording.

Parameters

chan	the channel being recorded
playfile	Filename of sound to play before recording begins
recordfile	Filename to save the recording
maxtime_sec	Longest possible message length in seconds
fmt	string containing all formats to be recorded delimited by '|'
duration	pointer to integer for storing length of the recording
sound_duration	pointer to integer for storing length of the recording minus all silence
silencethreshold	tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
maxsilence_ms	length of time in milliseconds which will trigger a timeout from silence, -1 for default
path	Optional filesystem path to unlock

Return values

-1	failure or hangup
'S'	Recording ended from silence timeout
't'	Recording ended from the message exceeding the maximum duration
dtmfchar	Recording ended via the return value's DTMF character for either cancel or accept.

Examples:

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

Definition at line 1997 of file main/app.c.

References __ast_play_and_record(), AST_RECORD_IF_EXISTS_OVERWRITE, default_acceptdtmf, and default_canceldtmf.

Referenced by app_exec(), ast_record_review(), conf_rec_name(), conf_run(), and setup_privacy_args().

{
   return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, sound_duration, 0, silencethreshold, maxsilence, path, 0, default_acceptdtmf, default_canceldtmf, 0, AST_RECORD_IF_EXISTS_OVERWRITE);
}

ast_play_and_record_full()

int ast_play_and_record_full	(	struct ast_channel *	chan,
		const char *	playfile,
		const char *	recordfile,
		int	maxtime_sec,
		const char *	fmt,
		int *	duration,
		int *	sound_duration,
		int	beep,
		int	silencethreshold,
		int	maxsilence_ms,
		const char *	path,
		const char *	acceptdtmf,
		const char *	canceldtmf,
		int	skip_confirmation_sound,
		enum ast_record_if_exists	if_exists
	)

Record a file based on input from a channel This function will play "auth-thankyou" upon successful recording if skip_confirmation_sound is false.

Parameters

chan	the channel being recorded
playfile	Filename of sound to play before recording begins. A beep is also played when playfile completes, before the recording begins.
recordfile	Filename to save the recording
maxtime_sec	Longest possible message length in seconds
fmt	string containing all formats to be recorded delimited by '|'
duration	pointer to integer for storing length of the recording
beep	If true, play a beep before recording begins (and doesn't play playfile)
sound_duration	pointer to integer for storing length of the recording minus all silence
silencethreshold	tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
maxsilence_ms	Length of time in milliseconds which will trigger a timeout from silence, -1 for default
path	Optional filesystem path to unlock
acceptdtmf	Character of DTMF to end and accept the recording
canceldtmf	Character of DTMF to end and cancel the recording
skip_confirmation_sound	If true, don't play auth-thankyou at end. Nice for custom recording prompts in apps.
if_exists	Action to take if recording already exists.

Return values

-1	failure or hangup
'S'	Recording ended from silence timeout
't'	Recording ended from the message exceeding the maximum duration
dtmfchar	Recording ended via the return value's DTMF character for either cancel or accept.

Examples:

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

Definition at line 1992 of file main/app.c.

References __ast_play_and_record(), default_canceldtmf, and S_OR.

Referenced by play_record_review(), and record_file().

{
   return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, sound_duration, beep, silencethreshold, maxsilence, path, 0, S_OR(acceptdtmf, ""), S_OR(canceldtmf, default_canceldtmf), skip_confirmation_sound, if_exists);
}

ast_play_and_wait()

int ast_play_and_wait	(	struct ast_channel *	chan,
		const char *	fn
	)

Play a stream and wait for a digit, returning the digit that was pressed.

Examples:

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

Definition at line 1470 of file main/app.c.

References ast_channel_language(), AST_DIGIT_ANY, ast_stopstream(), ast_streamfile(), ast_waitstream(), and d.

Referenced by __ast_play_and_record(), advanced_options(), ast_record_review(), ast_say_counted_adjective(), ast_say_counted_noun(), dialout(), forward_message(), get_folder(), get_folder2(), get_folder_ja(), leave_voicemail(), minivm_greet_exec(), play_message_category(), play_message_duration(), play_record_review(), valid_priv_reply(), vm_allocate_dh(), vm_authenticate(), vm_browse_messages_en(), vm_browse_messages_es(), vm_browse_messages_gr(), vm_browse_messages_he(), vm_browse_messages_it(), vm_browse_messages_ja(), vm_browse_messages_pt(), vm_browse_messages_vi(), vm_browse_messages_zh(), vm_exec(), vm_execmain(), vm_forwardoptions(), vm_instructions_en(), vm_instructions_ja(), vm_instructions_zh(), vm_intro(), vm_intro_cs(), vm_intro_de(), vm_intro_en(), vm_intro_es(), vm_intro_fr(), vm_intro_gr(), vm_intro_he(), vm_intro_is(), vm_intro_it(), vm_intro_ja(), vm_intro_multilang(), vm_intro_nl(), vm_intro_no(), vm_intro_pl(), vm_intro_pt(), vm_intro_pt_BR(), vm_intro_se(), vm_intro_vi(), vm_intro_zh(), vm_newuser_setup(), vm_options(), vm_play_folder_name(), vm_play_folder_name_gr(), vm_play_folder_name_ja(), vm_play_folder_name_pl(), vm_play_folder_name_ua(), vm_tempgreeting(), and vmauthenticate().

{
   int d = 0;

   if ((d = ast_streamfile(chan, fn, ast_channel_language(chan)))) {
      return d;
   }

   d = ast_waitstream(chan, AST_DIGIT_ANY);

   ast_stopstream(chan);

   return d;
}

ast_queue_topic()

struct stasis_topic* ast_queue_topic

(

const char *

queuename

)

Get the Stasis Message Bus API topic for queue messages for a particular queue name.

Parameters

queuename

The name for which to get the topic

Return values

The	topic structure for queue messages for a given name
NULL	if it failed to be found or allocated

Since

12

Examples:

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

Definition at line 3189 of file main/app.c.

References stasis_topic_pool_get_topic().

Referenced by send_agent_complete().

{
   return stasis_topic_pool_get_topic(queue_topic_pool, queuename);
}

ast_queue_topic_all()

struct stasis_topic* ast_queue_topic_all

(

void

)

Get the Stasis Message Bus API topic for queue messages.

Return values

The	topic structure for queue messages
NULL	if it has not been allocated

Since

12

Examples:

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

Definition at line 3184 of file main/app.c.

References queue_topic_all.

Referenced by load_module().

{
   return queue_topic_all;
}

ast_read_textfile()

char* ast_read_textfile

(

const char *

file

)

Read a file into asterisk.

Examples:

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

Definition at line 2792 of file main/app.c.

References ast_free, ast_log, ast_malloc, errno, LOG_WARNING, and NULL.

Referenced by ast_tcptls_server_start().

{
   int fd, count = 0, res;
   char *output = NULL;
   struct stat filesize;

   if (stat(filename, &filesize) == -1) {
      ast_log(LOG_WARNING, "Error can't stat %s\n", filename);
      return NULL;
   }

   count = filesize.st_size + 1;

   if ((fd = open(filename, O_RDONLY)) < 0) {
      ast_log(LOG_WARNING, "Cannot open file '%s' for reading: %s\n", filename, strerror(errno));
      return NULL;
   }

   if ((output = ast_malloc(count))) {
      res = read(fd, output, count - 1);
      if (res == count - 1) {
         output[res] = '\0';
      } else {
         ast_log(LOG_WARNING, "Short read of %s (%d of %d): %s\n", filename, res, count - 1, strerror(errno));
         ast_free(output);
         output = NULL;
      }
   }

   close(fd);

   return output;
}

ast_record_review()

int ast_record_review	(	struct ast_channel *	chan,
		const char *	playfile,
		const char *	recordfile,
		int	maxtime,
		const char *	fmt,
		int *	duration,
		const char *	path
	)

Allow to record message and have a review option.

Examples:

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

Definition at line 2489 of file main/app.c.

References AST_DIGIT_ANY, ast_dsp_get_threshold_from_settings(), ast_log, ast_play_and_record(), ast_play_and_wait(), ast_stream_and_wait(), ast_verb, ast_waitfordigit(), LOG_WARNING, maxsilence, NULL, silencethreshold, and THRESHOLD_SILENCE.

Referenced by conf_rec_name(), and conf_run().

{
   int silencethreshold;
   int maxsilence = 0;
   int res = 0;
   int cmd = 0;
   int max_attempts = 3;
   int attempts = 0;
   int recorded = 0;
   int message_exists = 0;
   /* Note that urgent and private are for flagging messages as such in the future */

   /* barf if no pointer passed to store duration in */
   if (!duration) {
      ast_log(LOG_WARNING, "Error ast_record_review called without duration pointer\n");
      return -1;
   }

   cmd = '3';   /* Want to start by recording */

   silencethreshold = ast_dsp_get_threshold_from_settings(THRESHOLD_SILENCE);

   while ((cmd >= 0) && (cmd != 't')) {
      switch (cmd) {
      case '1':
         if (!message_exists) {
            /* In this case, 1 is to record a message */
            cmd = '3';
            break;
         } else {
            ast_stream_and_wait(chan, "vm-msgsaved", "");
            cmd = 't';
            return res;
         }
      case '2':
         /* Review */
         ast_verb(3, "Reviewing the recording\n");
         cmd = ast_stream_and_wait(chan, recordfile, AST_DIGIT_ANY);
         break;
      case '3':
         message_exists = 0;
         /* Record */
         ast_verb(3, "R%secording\n", recorded == 1 ? "e-r" : "");
         recorded = 1;
         if ((cmd = ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, NULL, silencethreshold, maxsilence, path)) == -1) {
            /* User has hung up, no options to give */
            return cmd;
         }
         if (cmd == '0') {
            break;
         } else if (cmd == '*') {
            break;
         } else {
            /* If all is well, a message exists */
            message_exists = 1;
            cmd = 0;
         }
         break;
      case '4':
      case '5':
      case '6':
      case '7':
      case '8':
      case '9':
      case '*':
      case '#':
         cmd = ast_play_and_wait(chan, "vm-sorry");
         break;
      default:
         if (message_exists) {
            cmd = ast_play_and_wait(chan, "vm-review");
         } else {
            if (!(cmd = ast_play_and_wait(chan, "vm-torerecord"))) {
               cmd = ast_waitfordigit(chan, 600);
            }
         }

         if (!cmd) {
            cmd = ast_waitfordigit(chan, 6000);
         }
         if (!cmd) {
            attempts++;
         }
         if (attempts > max_attempts) {
            cmd = 't';
         }
      }
   }
   if (cmd == 't') {
      cmd = 0;
   }
   return cmd;
}

ast_replace_sigchld()

void ast_replace_sigchld

(

void

)

Replace the SIGCHLD handler.

Normally, Asterisk has a SIGCHLD handler that is cleaning up all zombie processes from forking elsewhere in Asterisk. However, if you want to wait*() on the process to retrieve information about it's exit status, then this signal handler needs to be temporarily replaced.

Code that executes this function must call ast_unreplace_sigchld() after it is finished doing the wait*().

Examples:

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

Definition at line 801 of file extconf.c.

References ast_mutex_lock, ast_mutex_unlock, ast_unreplace_sigchld(), safe_system_lock, and safe_system_prev_handler.

Referenced by ast_safe_fork(), ast_safe_system(), and safe_exec_prep().

{
   unsigned int level;

   level = safe_system_level++;

   /* only replace the handler if it has not already been done */
   if (level == 0) {
      sigaction(SIGCHLD, &null_sig_handler, &safe_system_prev_handler);
   }
}

ast_safe_execvp()

int ast_safe_execvp	(	int	dualfork,
		const char *	file,
		char *const	argv[]
	)

Safely spawn an external program while closing file descriptors.

Note

This replaces the execvp call in all Asterisk modules

Parameters

dualfork	Non-zero to simulate running the program in the background by forking twice. The option provides similar functionality to the '&' in the OS shell command "cmd &". The option allows Asterisk to run a reaper loop to watch the first fork which immediately exits after spaning the second fork. The actual program is run in the second fork.
file	execvp(file, argv) file parameter
argv	execvp(file, argv) argv parameter

Definition at line 1180 of file asterisk.c.

References safe_exec_prep(), and safe_exec_wait().

Referenced by run_externnotify().

{
   pid_t pid = safe_exec_prep(dualfork);

   if (pid == 0) {
      execvp(file, argv);
      _exit(1);
      /* noreturn from _exit */
   }

   return safe_exec_wait(pid);
}

ast_safe_fork()

int ast_safe_fork

(

int

stop_reaper

)

Common routine to safely fork without a chance of a signal handler firing badly in the child.

Parameters

[in]

stop_reaper

flag to determine if sigchld handler is replaced or not

Since

1.6.1

Examples:

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

Definition at line 3047 of file main/app.c.

References ast_calloc, AST_LIST_INSERT_TAIL, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_log, ast_pthread_create_background, AST_PTHREADT_NULL, ast_replace_sigchld(), child_cap, errno, zombie::list, LOG_ERROR, LOG_WARNING, NULL, zombie::pid, shaun_of_the_dead(), and shaun_of_the_dead_thread.

Referenced by app_exec(), filestream_destructor(), icesencode(), launch_script(), mp3play(), NBScatplay(), send_waveform_to_fd(), spawn_mp3(), spawn_ras(), and vm_check_password_shell().

{
   sigset_t signal_set, old_set;
   int pid;

   /* Don't let the default signal handler for children reap our status */
   if (stop_reaper) {
      ast_replace_sigchld();
   }

   /* GCC 4.9 gives a bogus "right-hand operand of comma expression has
    * no effect" warning */
   (void) sigfillset(&signal_set);
   pthread_sigmask(SIG_BLOCK, &signal_set, &old_set);

   pid = fork();

   if (pid != 0) {
      /* Fork failed or parent */
      pthread_sigmask(SIG_SETMASK, &old_set, NULL);
      if (!stop_reaper && pid > 0) {
         struct zombie *cur = ast_calloc(1, sizeof(*cur));
         if (cur) {
            cur->pid = pid;
            AST_LIST_LOCK(&zombies);
            AST_LIST_INSERT_TAIL(&zombies, cur, list);
            AST_LIST_UNLOCK(&zombies);
            if (shaun_of_the_dead_thread == AST_PTHREADT_NULL) {
               if (ast_pthread_create_background(&shaun_of_the_dead_thread, NULL, shaun_of_the_dead, NULL)) {
                  ast_log(LOG_ERROR, "Shaun of the Dead wants to kill zombies, but can't?!!\n");
                  shaun_of_the_dead_thread = AST_PTHREADT_NULL;
               }
            }
         }
      }
      return pid;
   } else {
      /* Child */
#ifdef HAVE_CAP
      cap_set_proc(child_cap);
#endif

      /* Before we unblock our signals, return our trapped signals back to the defaults */
      signal(SIGHUP, SIG_DFL);
      signal(SIGCHLD, SIG_DFL);
      signal(SIGINT, SIG_DFL);
      signal(SIGURG, SIG_DFL);
      signal(SIGTERM, SIG_DFL);
      signal(SIGPIPE, SIG_DFL);
      signal(SIGXFSZ, SIG_DFL);

      /* unblock important signal handlers */
      if (pthread_sigmask(SIG_UNBLOCK, &signal_set, NULL)) {
         ast_log(LOG_WARNING, "unable to unblock signals: %s\n", strerror(errno));
         _exit(1);
      }

      return pid;
   }
}

ast_safe_fork_cleanup()

void ast_safe_fork_cleanup

(

void

)

Common routine to cleanup after fork'ed process is complete (if reaping was stopped)

Since

1.6.1

Examples:

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

Definition at line 3108 of file main/app.c.

References ast_unreplace_sigchld().

Referenced by agi_exec_full(), and run_ras().

{
   ast_unreplace_sigchld();
}

ast_safe_system()

int ast_safe_system

(

const char *

s

)

Safely spawn an OS shell command while closing file descriptors.

Note

This replaces the system call in all Asterisk modules

Parameters

s	- OS shell command string to execute.

Warning

Command injection can happen using this call if the passed in string is created using untrusted data from an external source. It is best not to use untrusted data. However, the caller could filter out dangerous characters to avoid command injection.

Definition at line 829 of file extconf.c.

References ast_log(), ast_replace_sigchld(), ast_unreplace_sigchld(), errno, LOG_WARNING, NULL, safe_exec_prep(), safe_exec_wait(), status, WEXITSTATUS, WIFEXITED, and ast_channel::x.

Referenced by add_email_attachment(), alarmreceiver_exec(), ast_monitor_stop(), AST_TEST_DEFINE(), ast_unreplace_sigchld(), consolehandler(), convert_bdb_to_sqlite3(), mixmonitor_thread(), notify_message(), process_text_line(), remoteconsolehandler(), rotate_file(), run_externnotify(), sendmail(), sendpage(), system_exec_helper(), and vm_change_password_shell().

{
   pid_t pid;
#ifdef HAVE_WORKING_FORK
   int x;
#endif
   int res;
   int status;

#if defined(HAVE_WORKING_FORK) || defined(HAVE_WORKING_VFORK)
   ast_replace_sigchld();

#ifdef HAVE_WORKING_FORK
   pid = fork();
#else
   pid = vfork();
#endif

   if (pid == 0) {
#ifdef HAVE_WORKING_FORK
      /* Close file descriptors and launch system command */
      for (x = STDERR_FILENO + 1; x < 4096; x++)
         close(x);
#endif
      execl("/bin/sh", "/bin/sh", "-c", s, (char *) NULL);
      _exit(1);
   } else if (pid > 0) {
      for(;;) {
         res = waitpid(pid, &status, 0);
         if (res > -1) {
            res = WIFEXITED(status) ? WEXITSTATUS(status) : -1;
            break;
         } else if (errno != EINTR)
            break;
      }
   } else {
      ast_log(LOG_WARNING, "Fork failed: %s\n", strerror(errno));
      res = -1;
   }

   ast_unreplace_sigchld();
#else
   res = -1;
#endif

   return res;
}

ast_set_lock_type()

void ast_set_lock_type

(

enum AST_LOCK_TYPE

type

)

Set the type of locks used by ast_lock_path()

Parameters

type	the locking type to use

Examples:

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

Definition at line 2452 of file main/app.c.

References type.

Referenced by load_asterisk_conf().

{
   ast_lock_type = type;
}

ast_str_get_encoded_str()

int ast_str_get_encoded_str	(	struct ast_str **	str,
		int	maxlen,
		const char *	stream
	)

Decode a stream of encoded control or extended ASCII characters.

Examples:

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

Definition at line 3015 of file main/app.c.

References ast_get_encoded_char(), ast_str_buffer(), ast_str_make_space, ast_str_set(), ast_str_size(), ast_str_update(), buf, and zombie::next.

Referenced by sendtext_exec(), and system_exec_helper().

{
   char next, *buf;
   size_t offset = 0;
   size_t consumed;

   if (strchr(stream, '\\')) {
      while (!ast_get_encoded_char(stream, &next, &consumed)) {
         if (offset + 2 > ast_str_size(*str) && maxlen > -1) {
            ast_str_make_space(str, maxlen > 0 ? maxlen : (ast_str_size(*str) + 48) * 2 - 48);
         }
         if (offset + 2 > ast_str_size(*str)) {
            break;
         }
         buf = ast_str_buffer(*str);
         buf[offset++] = next;
         stream += consumed;
      }
      buf = ast_str_buffer(*str);
      buf[offset++] = '\0';
      ast_str_update(*str);
   } else {
      ast_str_set(str, maxlen, "%s", stream);
   }
   return 0;
}

AST_THREADSTORAGE_EXTERNAL()

AST_THREADSTORAGE_EXTERNAL

(

ast_str_thread_global_buf

)

ast_uninstall_vm_test_functions()

void ast_uninstall_vm_test_functions

(

void

)

Examples:

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

Definition at line 606 of file main/app.c.

References ast_vm_test_create_user_func, ast_vm_test_destroy_user_func, and NULL.

Referenced by unload_module().

{
   ast_vm_test_create_user_func = NULL;
   ast_vm_test_destroy_user_func = NULL;
}

ast_unlock_path()

int ast_unlock_path

(

const char *

path

)

Unlock a path.

Examples:

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

Definition at line 2473 of file main/app.c.

References AST_LOCK_TYPE_FLOCK, AST_LOCK_TYPE_LOCKFILE, ast_unlock_path_flock(), and ast_unlock_path_lockfile().

Referenced by __ast_play_and_record(), access_counter_file(), ast_module_reload(), close_mailbox(), copy_message(), count_messages(), leave_voicemail(), msg_create_from_file(), open_mailbox(), resequence_mailbox(), save_to_folder(), and test_vm_api_create_voicemail_files().

{
   int r = 0;

   switch (ast_lock_type) {
   case AST_LOCK_TYPE_LOCKFILE:
      r = ast_unlock_path_lockfile(path);
      break;
   case AST_LOCK_TYPE_FLOCK:
      r = ast_unlock_path_flock(path);
      break;
   }

   return r;
}

ast_unreplace_sigchld()

void ast_unreplace_sigchld

(

void

)

Restore the SIGCHLD handler.

This function is called after a call to ast_replace_sigchld. It restores the SIGCHLD handler that cleans up any zombie processes.

Examples:

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

Definition at line 815 of file extconf.c.

References ast_mutex_lock, ast_mutex_unlock, ast_safe_system(), NULL, safe_system_level, safe_system_lock, and safe_system_prev_handler.

Referenced by ast_replace_sigchld(), ast_safe_fork_cleanup(), ast_safe_system(), AST_TEST_DEFINE(), and safe_exec_wait().

{
   unsigned int level;

   level = --safe_system_level;

   /* only restore the handler if we are the last one */
   if (level == 0) {
      sigaction(SIGCHLD, &safe_system_prev_handler, NULL);
   }
}

ast_vm_greeter_is_registered()

int ast_vm_greeter_is_registered

(

void

)

Determine if a voicemail greeter provider is registered.

Since

13.0.0

Return values

0	if no provider registered.
1	if a provider is registered.

Examples:

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

Definition at line 541 of file main/app.c.

References ao2_cleanup, ao2_global_obj_ref, and table.

{
   struct ast_vm_greeter_functions *table;
   int is_registered;

   table = ao2_global_obj_ref(vm_greeter_provider);
   is_registered = table ? 1 : 0;
   ao2_cleanup(table);
   return is_registered;
}

ast_vm_greeter_unregister()

void ast_vm_greeter_unregister

(

const char *

module_name

)

Unregister the specified voicemail greeter provider.

Since

13.0.0

Parameters

The	module name of the provider to unregister

Returns

Nothing

Examples:

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

Definition at line 584 of file main/app.c.

References ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_release, ast_vm_greeter_functions::module_name, and table.

Referenced by unload_module().

{
   struct ast_vm_greeter_functions *table;

   table = ao2_global_obj_ref(vm_greeter_provider);
   if (table && !strcmp(table->module_name, module_name)) {
      ao2_global_obj_release(vm_greeter_provider);
   }
   ao2_cleanup(table);
}

ast_vm_index_to_foldername()

const char* ast_vm_index_to_foldername

(

int

id

)

Return name of folder, given an id.

Parameters

[in]

id

Folder id

Returns

Name of folder

Examples:

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

Definition at line 726 of file main/app.c.

References NULL, and VM_API_CALL.

{
   const char *res = NULL;

   VM_API_CALL(res, index_to_foldername, (id));
   return res;
}

ast_vm_is_registered()

int ast_vm_is_registered

(

void

)

Determine if a voicemail provider is registered.

Since

12.0.0

Return values

0	if no provider registered.
1	if a provider is registered.

Examples:

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

Definition at line 430 of file main/app.c.

References ao2_cleanup, ao2_global_obj_ref, and table.

{
   struct ast_vm_functions *table;
   int is_registered;

   table = ao2_global_obj_ref(vm_provider);
   is_registered = table ? 1 : 0;
   ao2_cleanup(table);
   return is_registered;
}

ast_vm_mailbox_snapshot_create()

struct ast_vm_mailbox_snapshot* ast_vm_mailbox_snapshot_create	(	const char *	mailbox,
		const char *	context,
		const char *	folder,
		int	descending,
		enum ast_vm_snapshot_sort_val	sort_val,
		int	combine_INBOX_and_OLD
	)

Create a snapshot of a mailbox which contains information about every msg.

Parameters

mailbox,the	mailbox to look for
context,the	context to look for the mailbox in
folder,OPTIONAL.	When not NULL only msgs from the specified folder will be included.
descending,list	the msgs in descending order rather than ascending order.
combine_INBOX_and_OLD,When	this argument is set, The OLD folder will be represented in the INBOX folder of the snapshot. This allows the snapshot to represent the OLD and INBOX messages in sorted order merged together.

Return values

snapshot	on success
NULL	on failure

Examples:

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

Definition at line 734 of file main/app.c.

References NULL, and VM_API_CALL.

Referenced by test_vm_api_remove_all_messages().

{
   struct ast_vm_mailbox_snapshot *res = NULL;

   VM_API_CALL(res, mailbox_snapshot_create, (mailbox, context, folder, descending,
      sort_val, combine_INBOX_and_OLD));
   return res;
}

ast_vm_mailbox_snapshot_destroy()

struct ast_vm_mailbox_snapshot* ast_vm_mailbox_snapshot_destroy

(

struct ast_vm_mailbox_snapshot *

mailbox_snapshot

)

destroy a snapshot

Parameters

mailbox_snapshot

The snapshot to destroy.

Return values

NULL

Examples:

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

Definition at line 748 of file main/app.c.

References NULL, and VM_API_CALL.

Referenced by AST_TEST_DEFINE(), and test_vm_api_remove_all_messages().

{
   struct ast_vm_mailbox_snapshot *res = NULL;

   VM_API_CALL(res, mailbox_snapshot_destroy, (mailbox_snapshot));
   return res;
}

ast_vm_msg_forward()

int ast_vm_msg_forward	(	const char *	from_mailbox,
		const char *	from_context,
		const char *	from_folder,
		const char *	to_mailbox,
		const char *	to_context,
		const char *	to_folder,
		size_t	num_msgs,
		const char *	msg_ids[],
		int	delete_old
	)

forward a message from one mailbox to another.

from_mailbox The original mailbox the message is being forwarded from from_context The voicemail context of the from_mailbox from_folder The folder from which the message is being forwarded to_mailbox The mailbox to forward the message to to_context The voicemail context of the to_mailbox to_folder The folder to which the message is being forwarded num_msgs The number of messages being forwarded msg_ids The message IDs of the messages in from_mailbox to forward delete_old If non-zero, the forwarded messages are also deleted from from_mailbox. Otherwise, the messages will remain in the from_mailbox.

Return values

-1	Failure
0	Success

Examples:

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

Definition at line 782 of file main/app.c.

References VM_API_CALL.

{
   int res = 0;

   VM_API_CALL(res, msg_forward, (from_mailbox, from_context, from_folder, to_mailbox,
      to_context, to_folder, num_msgs, msg_ids, delete_old));
   return res;
}

ast_vm_msg_move()

int ast_vm_msg_move	(	const char *	mailbox,
		const char *	context,
		size_t	num_msgs,
		const char *	oldfolder,
		const char *	old_msg_ids[],
		const char *	newfolder
	)

Move messages from one folder to another.

Parameters

mailbox	The mailbox to which the folders belong
context	The voicemail context for the mailbox
num_msgs	The number of messages to move
oldfolder	The folder from where messages should be moved
old_msg_ids	The message IDs of the messages to move
newfolder	The folder to which messages should be moved new folder. This array must be num_msgs sized.

Return values

-1	Failure
0	Success

Examples:

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

Definition at line 756 of file main/app.c.

References VM_API_CALL.

{
   int res = 0;

   VM_API_CALL(res, msg_move, (mailbox, context, num_msgs, oldfolder, old_msg_ids,
      newfolder));
   return res;
}

ast_vm_msg_play()

int ast_vm_msg_play	(	struct ast_channel *	chan,
		const char *	mailbox,
		const char *	context,
		const char *	folder,
		const char *	msg_num,
		ast_vm_msg_play_cb *	cb
	)

Play a voicemail msg back on a channel.

Parameters

chan
mailbox	msg is in.
context	of mailbox.
folder	voicemail folder to look in.
msg_num	message number in the voicemailbox to playback to the channel.
cb

Return values

0	success
-1	failure

Examples:

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

Definition at line 799 of file main/app.c.

References VM_API_CALL.

{
   int res = 0;

   VM_API_CALL(res, msg_play, (chan, mailbox, context, folder, msg_num, cb));
   return res;
}

ast_vm_msg_remove()

int ast_vm_msg_remove	(	const char *	mailbox,
		const char *	context,
		size_t	num_msgs,
		const char *	folder,
		const char *	msgs[]
	)

Remove/delete messages from a mailbox folder.

Parameters

mailbox	The mailbox from which to delete messages
context	The voicemail context for the mailbox
num_msgs	The number of messages to delete
folder	The folder from which to remove messages
msgs	The message IDs of the messages to delete

Return values

-1	Failure
0	Success

Examples:

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

Definition at line 770 of file main/app.c.

References VM_API_CALL.

{
   int res = 0;

   VM_API_CALL(res, msg_remove, (mailbox, context, num_msgs, folder, msgs));
   return res;
}

ast_vm_test_create_user()

int ast_vm_test_create_user	(	const char *	context,
		const char *	mailbox
	)

Examples:

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

Definition at line 813 of file main/app.c.

References ast_vm_test_create_user_func.

Referenced by test_vm_api_test_setup().

{
   if (ast_vm_test_create_user_func) {
      return ast_vm_test_create_user_func(context, mailbox);
   }
   return 0;
}

ast_vm_test_destroy_user()

int ast_vm_test_destroy_user	(	const char *	context,
		const char *	mailbox
	)

Examples:

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

Definition at line 821 of file main/app.c.

References ast_vm_test_destroy_user_func.

Referenced by test_vm_api_test_teardown().

{
   if (ast_vm_test_destroy_user_func) {
      return ast_vm_test_destroy_user_func(context, mailbox);
   }
   return 0;
}

ast_vm_test_swap_table_in()

void ast_vm_test_swap_table_in

(

const struct ast_vm_functions *

vm_table

)

Swap out existing voicemail functions with a temporary set of functions for use with unit tests.

Parameters

vm_table

function table to use for testing

Note

ast_vm_test_swap_table_out should be called to restore the original set before testing concludes

Examples:

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

Definition at line 489 of file main/app.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_replace_unref, ast_log, LOG_ERROR, NULL, provider_is_swapped, RAII_VAR, and vm_table.

{
   RAII_VAR(struct ast_vm_functions *, holding_table, NULL, ao2_cleanup);
   RAII_VAR(struct ast_vm_functions *, new_table, NULL, ao2_cleanup);

   if (provider_is_swapped) {
      ast_log(LOG_ERROR, "Attempted to swap in test function table without swapping out old test table.\n");
      return;
   }

   holding_table = ao2_global_obj_ref(vm_provider);

   if (holding_table) {
      ao2_global_obj_replace_unref(vm_provider_holder, holding_table);
   }

   new_table = ao2_alloc_options(sizeof(*new_table), NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!new_table) {
      return;
   }
   *new_table = *vm_table;

   ao2_global_obj_replace_unref(vm_provider, new_table);
   provider_is_swapped = 1;
}

ast_vm_test_swap_table_out()

void ast_vm_test_swap_table_out

(

void

)

Used after ast_vm_test_swap_table_in to restore the original set of voicemail functions.

Examples:

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

Definition at line 515 of file main/app.c.

References ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_release, ao2_global_obj_replace_unref, AO2_GLOBAL_OBJ_STATIC(), ast_log, LOG_ERROR, NULL, provider_is_swapped, and RAII_VAR.

{
   RAII_VAR(struct ast_vm_functions *, held_table, NULL, ao2_cleanup);

   if (!provider_is_swapped) {
      ast_log(LOG_ERROR, "Attempted to swap out test function table, but none is currently installed.\n");
      return;
   }

   held_table = ao2_global_obj_ref(vm_provider_holder);
   if (!held_table) {
      return;
   }

   ao2_global_obj_replace_unref(vm_provider, held_table);
   ao2_global_obj_release(vm_provider_holder);
   provider_is_swapped = 0;
}

ast_vm_unregister()

void ast_vm_unregister

(

const char *

module_name

)

Unregister the specified voicemail provider.

Parameters

The	module name of the provider to unregister

Returns

Nothing

Examples:

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

Definition at line 473 of file main/app.c.

References ao2_cleanup, ao2_global_obj_ref, ao2_global_obj_release, AO2_GLOBAL_OBJ_STATIC(), ast_vm_functions::module_name, and table.

Referenced by unload_module().

{
   struct ast_vm_functions *table;

   table = ao2_global_obj_ref(vm_provider);
   if (table && !strcmp(table->module_name, module_name)) {
      ao2_global_obj_release(vm_provider);
   }
   ao2_cleanup(table);
}