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

#include "asterisk/strings.h"
#include "asterisk/threadstorage.h"

Include dependency graph for app.h:

Data Structures
struct	ast_app_option
	A structure to hold the description of an application 'option'. More...
struct	ast_ivr_menu
struct	ast_ivr_option
Defines
#define	AST_APP_ARG(name) char *name
	Define an application argument.
#define	AST_APP_OPTION(option, flagno) [option] = { .flag = flagno }
	Declares an application option that does not accept an argument.
#define	AST_APP_OPTION_ARG(option, flagno, argno) [option] = { .flag = flagno, .arg_index = argno + 1 }
	Declares an application option that accepts an argument.
#define	AST_APP_OPTIONS(holder, options...) static const struct ast_app_option holder[128] = options
	Declares an array of options for an application.
#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(, arglist) name
	Declare a structure to hold an application's arguments.
#define	AST_DEFINE_APP_ARGS_TYPE(type, arglist)
	Define a structure type to hold an application's arguments.
#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.
#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.
#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	BEGIN_OPTIONS {
#define	END_OPTIONS }
Typedefs
typedef int(*	ast_ivr_callback )(struct ast_channel chan, char option, void *cbdata)
	Callback function for IVR.
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_timelen { TIMELEN_HOURS, TIMELEN_MINUTES, TIMELEN_SECONDS, TIMELEN_MILLISECONDS }
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.
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.
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.
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.
int	ast_app_group_discard (struct ast_channel *chan)
	Discard all group counting for a channel.
int	ast_app_group_get_count (const char group, const char category)
	Get the current channel count of the specified group and category.
struct ast_group_info *	ast_app_group_list_head (void)
	Get the head of the group count list.
int	ast_app_group_list_rdlock (void)
	Read Lock the group count list.
int	ast_app_group_list_unlock (void)
	Unlock the group count list.
int	ast_app_group_list_wrlock (void)
	Write Lock the group count list.
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.
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.
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.
int	ast_app_group_update (struct ast_channel oldchan, struct ast_channel newchan)
	Update all group counting for a channel to a new one.
int	ast_app_has_voicemail (const char mailbox, 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.
int	ast_app_inboxcount (const char mailbox, int newmsgs, int *oldmsgs)
	Determine number of new/old messages in a mailbox.
int	ast_app_inboxcount2 (const char mailbox, int urgentmsgs, int newmsgs, int oldmsgs)
	Determine number of urgent/new/old messages in a mailbox.
int	ast_app_messagecount (const char context, const char mailbox, const char *folder)
	Check number of messages in a given context, mailbox, and folder.
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.
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.
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.
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.
int	ast_app_run_macro (struct ast_channel autoservice_chan, struct ast_channel macro_chan, const char const macro_name, const char const macro_args)
	Run a macro on a channel, placing a second channel into autoservice.
int	ast_app_sayname (struct ast_channel chan, const char mailbox, const char *context)
	Given a mailbox and context, play that mailbox owner's name to the channel specified.
void	ast_close_fds_above_n (int n)
	Common routine for child processes, to close all fds prior to exec(2)
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.
int	ast_dtmf_stream (struct ast_channel chan, struct ast_channel peer, const char *digits, int between, unsigned int duration)
	Send DTMF to a channel.
int	ast_get_encoded_char (const char stream, char result, size_t *consumed)
	Decode an encoded control or extended ASCII character.
char *	ast_get_encoded_str (const char stream, char result, size_t result_len)
	Decode a stream of encoded control or extended ASCII characters.
void	ast_install_vm_functions (int(has_voicemail_func)(const char mailbox, const char folder), int(inboxcount_func)(const char mailbox, int newmsgs, int oldmsgs), int(inboxcount2_func)(const char mailbox, int urgentmsgs, int newmsgs, int oldmsgs), int(messagecount_func)(const char context, const char mailbox, const char folder), int(sayname_func)(struct ast_channel chan, const char mailbox, const char context))
	Set voicemail function callbacks.
int	ast_ivr_menu_run (struct ast_channel c, struct ast_ivr_menu menu, void *cbdata)
	Runs an IVR menu.
int	ast_linear_stream (struct ast_channel chan, const char filename, int fd, int allowoverride)
	Stream a filename (or file descriptor) as a generator.
enum AST_LOCK_RESULT	ast_lock_path (const char *path)
	Lock a filesystem path.
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.
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.
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 silencethreshold, int maxsilence_ms, const char path, const char acceptdtmf, const char *canceldtmf)
	Record a file based on input from a channel This function will play "auth-thankyou" upon successful recording.
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.
char *	ast_read_textfile (const char *file)
	Read a file into asterisk.
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.
void	ast_replace_sigchld (void)
	Replace the SIGCHLD handler.
int	ast_safe_fork (int stop_reaper)
	Common routine to safely fork without a chance of a signal handler firing badly in the child.
void	ast_safe_fork_cleanup (void)
	Common routine to cleanup after fork'ed process is complete (if reaping was stopped)
int	ast_safe_system (const char *s)
	Safely spawn an external program while closing file descriptors.
void	ast_set_lock_type (enum AST_LOCK_TYPE type)
	Set the type of locks used by ast_lock_path()
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.
	AST_THREADSTORAGE_EXTERNAL (ast_str_thread_global_buf)
void	ast_uninstall_vm_functions (void)
int	ast_unlock_path (const char *path)
	Unlock a path.
void	ast_unreplace_sigchld (void)
	Restore the SIGCHLD handler.

Detailed Description

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

Definition in file app.h.

Define Documentation

#define AST_APP_ARG ( name ) char *name

Define an application argument.

Parameters:

name	The name of the argument

Definition at line 418 of file app.h.

Referenced by acf_curl_helper(), acf_if(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_mailbox_exists(), acf_meetme_info(), 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_vmcount_exec(), action_status(), add_agent(), admin_exec(), aelsub_exec(), aes_helper(), agi_exec_full(), aji_join_exec(), aji_leave_exec(), aji_send_exec(), aji_sendgroup_exec(), aji_status_exec(), app_exec(), aqm_exec(), array(), ast_eivr_senddtmf(), ast_queue_log(), asyncgoto_exec(), auth_exec(), background_detect_exec(), bridge_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), cdr_read(), cdr_write(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), controlplayback_exec(), count_exec(), create_addr(), cut_internal(), dahdi_accept_r2_call_exec(), dahdi_send_callrerouting_facility_exec(), determine_starting_point(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_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_header_read(), function_agent(), 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(), hash_read(), hash_write(), hint_read(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), listfilter(), load_values_config(), log_exec(), login_exec(), man_do_variable_value(), math(), misdn_call(), misdn_check_l2l1(), misdn_facility_exec(), misdn_request(), mixmonitor_exec(), my_pri_make_cc_dialstring(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_call(), oss_request(), page_exec(), parkandannounce_exec(), parked_call_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_setvar_multiple(), pbx_builtin_waitexten(), peek_read(), pickupchan_exec(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pp_each_user_helper(), pqm_exec(), privacy_exec(), process_applicationmap_line(), ql_exec(), queue_exec(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), rcvfax_exec(), read_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), reg_source_db(), regex(), reload_single_member(), replace(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayunixtime_exec(), senddtmf_exec(), sendfax_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sig_pri_call(), sig_pri_extract_called_num_subaddr(), sip_request_call(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), speech_background(), speech_load(), srv_result_read(), start_moh_exec(), start_monitor_exec(), transfer_exec(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_box_exists(), vm_check_password_shell(), vm_exec(), vm_execmain(), volume_write(), and zapateller_exec().

#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 584 of file app.h.

#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 595 of file app.h.

#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 575 of file app.h.

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

Definition at line 503 of file app.h.

#define AST_DECLARE_APP_ARGS	(	name,
		arglist
	)	AST_DEFINE_APP_ARGS_TYPE(, arglist) name

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 435 of file app.h.

Referenced by acf_curl_helper(), acf_if(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_mailbox_exists(), acf_meetme_info(), 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_vmcount_exec(), action_status(), add_agent(), admin_exec(), aelsub_exec(), aes_helper(), agi_exec_full(), aji_join_exec(), aji_leave_exec(), aji_send_exec(), aji_sendgroup_exec(), aji_status_exec(), app_exec(), aqm_exec(), array(), ast_eivr_senddtmf(), ast_queue_log(), asyncgoto_exec(), auth_exec(), background_detect_exec(), bridge_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), cdr_read(), cdr_write(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), controlplayback_exec(), count_exec(), create_addr(), cut_internal(), dahdi_accept_r2_call_exec(), dahdi_send_callrerouting_facility_exec(), determine_starting_point(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_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_header_read(), function_agent(), 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(), hash_read(), hash_write(), hint_read(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), listfilter(), load_values_config(), log_exec(), login_exec(), man_do_variable_value(), math(), misdn_call(), misdn_check_l2l1(), misdn_facility_exec(), misdn_request(), mixmonitor_exec(), my_pri_make_cc_dialstring(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_call(), oss_request(), page_exec(), parkandannounce_exec(), parked_call_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_setvar_multiple(), pbx_builtin_waitexten(), peek_read(), pickupchan_exec(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pp_each_user_helper(), pqm_exec(), privacy_exec(), process_applicationmap_line(), ql_exec(), queue_exec(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), rcvfax_exec(), read_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), reg_source_db(), regex(), reload_single_member(), replace(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayunixtime_exec(), senddtmf_exec(), sendfax_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sig_pri_call(), sig_pri_extract_called_num_subaddr(), sip_request_call(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), speech_background(), speech_load(), srv_result_read(), start_moh_exec(), start_monitor_exec(), transfer_exec(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_box_exists(), vm_check_password_shell(), vm_exec(), vm_execmain(), volume_write(), and zapateller_exec().

#define AST_DEFINE_APP_ARGS_TYPE	(	type,
		arglist
	)

Value:

struct type { \
      unsigned int argc; \
      char *argv[0]; \
      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 451 of file app.h.

#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 83 of file app.h.

#define AST_IVR_FLAG_AUTORESTART (1 << 0)

Definition at line 81 of file app.h.

#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 482 of file app.h.

Referenced by acf_if(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_mailbox_exists(), aji_status_exec(), ast_queue_log(), build_profile(), callerid_read(), callerid_write(), connectedline_read(), connectedline_write(), determine_starting_point(), dialgroup_write(), function_agent(), function_db_delete(), function_db_exists(), function_db_read(), function_db_write(), misdn_call(), misdn_request(), my_pri_make_cc_dialstring(), oss_call(), oss_request(), pbx_builtin_setvar_multiple(), record_exec(), redirecting_read(), redirecting_write(), regex(), sig_pri_call(), sig_pri_extract_called_num_subaddr(), sip_request_call(), and vm_check_password_shell().

#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 484 of file app.h.

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

#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 467 of file app.h.

Referenced by acf_curl_helper(), acf_isexten_exec(), acf_jabberreceive_read(), acf_jabberstatus_read(), acf_meetme_info(), 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_vmcount_exec(), action_status(), add_agent(), admin_exec(), aes_helper(), agi_exec_full(), aji_join_exec(), aji_leave_exec(), aji_send_exec(), aji_sendgroup_exec(), aji_status_exec(), app_exec(), aqm_exec(), array(), ast_eivr_senddtmf(), ast_masq_park_call_exten(), ast_park_call_exten(), asyncgoto_exec(), auth_exec(), background_detect_exec(), bridge_exec(), build_profile(), calendar_query_exec(), calendar_query_result_exec(), calendar_write_exec(), callerid_read(), callerid_write(), cdr_read(), cdr_write(), celgenuserevent_exec(), chanavail_exec(), channel_admin_exec(), chanspy_exec(), cli_odbc_read(), cli_odbc_write(), conf_exec(), confbridge_exec(), config_function_read(), connectedline_write(), controlplayback_exec(), count_exec(), cut_internal(), dahdi_accept_r2_call_exec(), dahdi_send_callrerouting_facility_exec(), dial_exec_full(), dialgroup_write(), dictate_exec(), directory_exec(), disa_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_header_read(), function_enum(), function_fieldnum_helper(), function_fieldqty_helper(), function_realtime_read(), function_realtime_readdestroy(), function_realtime_store(), function_realtime_write(), function_txtcidname(), hash_read(), hash_write(), hint_read(), iconv_read(), import_helper(), init_acf_query(), isAnsweringMachine(), isexten_function_read(), listfilter(), log_exec(), login_exec(), man_do_variable_value(), math(), misdn_check_l2l1(), misdn_facility_exec(), mixmonitor_exec(), originate_exec(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), page_exec(), park_call_exec(), parkandannounce_exec(), parked_call_exec(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_setvar_multiple(), pbx_builtin_waitexten(), pickupchan_exec(), play_moh_exec(), playback_exec(), pp_each_extension_helper(), pp_each_user_helper(), pqm_exec(), privacy_exec(), process_applicationmap_line(), ql_exec(), queue_exec(), queue_function_memberpenalty_read(), queue_function_memberpenalty_write(), rcvfax_exec(), read_exec(), readexten_exec(), realtimefield_read(), receivefax_exec(), record_exec(), redirecting_write(), reload_single_member(), replace(), retrydial_exec(), rqm_exec(), saycountedadj_exec(), saycountednoun_exec(), sayunixtime_exec(), senddtmf_exec(), sendfax_exec(), sendurl_exec(), shared_read(), shared_write(), shift_pop(), sla_trunk_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), sms_exec(), sndfax_exec(), softhangup_exec(), speech_background(), speech_load(), srv_result_read(), start_moh_exec(), start_monitor_exec(), transfer_exec(), unshift_push(), upqm_exec(), userevent_exec(), verbose_exec(), vm_box_exists(), vm_exec(), vm_execmain(), volume_write(), xfer_park_call_helper(), and zapateller_exec().

#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 469 of file app.h.

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

#define BEGIN_OPTIONS {

Definition at line 525 of file app.h.

#define END_OPTIONS }

Definition at line 526 of file app.h.

Typedef Documentation

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 42 of file app.h.

Enumeration Type Documentation

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 340 of file 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,
};

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 44 of file 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;

enum AST_LOCK_RESULT

Enumerator:

AST_LOCK_SUCCESS
AST_LOCK_TIMEOUT
AST_LOCK_PATH_NOT_FOUND
AST_LOCK_FAILURE

Definition at line 350 of file app.h.

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

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 358 of file app.h.

                   {
   AST_LOCK_TYPE_LOCKFILE = 0,
   AST_LOCK_TYPE_FLOCK = 1,
};

enum ast_timelen

Enumerator:

TIMELEN_HOURS
TIMELEN_MINUTES
TIMELEN_SECONDS
TIMELEN_MILLISECONDS

Definition at line 87 of file app.h.

                 {
   TIMELEN_HOURS,
   TIMELEN_MINUTES,
   TIMELEN_SECONDS,
   TIMELEN_MILLISECONDS,
};

Function Documentation

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.

Definition at line 1253 of file app.c.

References paren, and quote().

Referenced by ast_app_separate_args().

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

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 seconds

Returns:: 0 if extension does not exist, 1 if extension exists

Definition at line 115 of file app.c.

References 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_channel::caller, ast_tone_zone_sound::data, ast_pbx::dtimeoutms, ast_party_caller::id, LOG_NOTICE, ast_party_id::number, ast_channel::pbx, S_COR, ast_party_number::str, ast_party_number::valid, and ast_channel::zone.

Referenced by builtin_atxfer(), builtin_blindtransfer(), and grab_transfer().

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

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

   if (!timeout && chan->pbx) {
      timeout = chan->pbx->dtimeoutms / 1000.0;
   } else if (!timeout) {
      timeout = 5;
   }

   if ((ts = ast_get_indication_tone(chan->zone, "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(chan->caller.id.number.valid, chan->caller.id.number.str, NULL))) {
         break;
      }
   }

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

   return res;
}

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)

Definition at line 171 of file app.c.

References AST_GETDATA_EMPTY_END_TERMINATED, ast_readstring(), ast_strdupa, ast_streamfile(), ast_strlen_zero(), ast_pbx::dtimeoutms, ast_channel::language, ast_channel::pbx, ast_pbx::rtimeoutms, and strsep().

Referenced by auth_exec(), conf_exec(), dictate_exec(), find_conf(), login_exec(), 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, c->language);
         if (res)
            continue;
      }
      if (ast_strlen_zero(filename)) {
         /* set timeouts for the last prompt */
         fto = c->pbx ? c->pbx->rtimeoutms : 6000;
         to = c->pbx ? c->pbx->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 = c->pbx ? c->pbx->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;
}

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.

Definition at line 224 of file app.c.

References ast_readstring_full(), ast_streamfile(), ast_strlen_zero(), and ast_channel::language.

Referenced by handle_getdata().

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

   if (!ast_strlen_zero(prompt)) {
      res = ast_streamfile(c, prompt, c->language);
      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;
}

int ast_app_group_discard ( struct ast_channel * chan )

Discard all group counting for a channel.

Definition at line 1213 of file 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, and ast_group_info::group_list.

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

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

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

Definition at line 1135 of file app.c.

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

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

struct ast_group_info* ast_app_group_list_head ( void ) [read]

Get the head of the group count list.

Definition at line 1240 of file 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);
}

int ast_app_group_list_rdlock ( void )

Read Lock the group count list.

Definition at line 1235 of file 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);
}

int ast_app_group_list_unlock ( void )

Unlock the group count list.

Definition at line 1245 of file 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);
}

int ast_app_group_list_wrlock ( void )

Write Lock the group count list.

Definition at line 1230 of file app.c.

References AST_RWLIST_WRLOCK.

{
   return AST_RWLIST_WRLOCK(&groups);
}

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.

Definition at line 1155 of file 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, and LOG_NOTICE.

Referenced by 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);
      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;
}

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.

Definition at line 1088 of file app.c.

References ast_app_group_split_group(), 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(), calloc, ast_group_info::category, ast_group_info::chan, free, ast_group_info::group, ast_group_info::group_list, and len().

Referenced by 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);
         free(gi);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;

   if (ast_strlen_zero(group)) {
      /* Enable unsetting the group */
   } else if ((gi = 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;
}

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.

Definition at line 1061 of file app.c.

References ast_copy_string(), and ast_strlen_zero().

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

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

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

Definition at line 1194 of file 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, and ast_group_info::group_list.

Referenced by ast_do_masquerade(), and check_bridge().

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

int ast_app_has_voicemail	(	const char *	mailbox,
		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

Definition at line 297 of file app.c.

References ast_has_voicemail_func, and ast_verb.

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

{
   static int warned = 0;
   if (ast_has_voicemail_func) {
      return ast_has_voicemail_func(mailbox, folder);
   }

   if (warned++ % 10 == 0) {
      ast_verb(3, "Message check requested for mailbox %s/folder %s but voicemail not loaded.\n", mailbox, folder ? folder : "INBOX");
   }
   return 0;
}

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

Determine number of new/old messages in a mailbox.

Since:: 1.0

Parameters:

[in]	mailbox	Mailbox specification in the format mbox[][&mbox2[]][...]
[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

Definition at line 311 of file app.c.

References ast_inboxcount_func, and ast_verb.

Referenced by sip_send_mwi_to_peer(), and update_registry().

{
   static int warned = 0;
   if (newmsgs) {
      *newmsgs = 0;
   }
   if (oldmsgs) {
      *oldmsgs = 0;
   }
   if (ast_inboxcount_func) {
      return ast_inboxcount_func(mailbox, newmsgs, oldmsgs);
   }

   if (warned++ % 10 == 0) {
      ast_verb(3, "Message count requested for mailbox %s but voicemail not loaded.\n", mailbox);
   }

   return 0;
}

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

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

Parameters:

[in]	mailbox	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

Definition at line 331 of file app.c.

References ast_inboxcount2_func, ast_inboxcount_func, and ast_verb.

Referenced by action_mailboxcount(), notify_new_message(), and vm_execmain().

{
   static int warned = 0;
   if (newmsgs) {
      *newmsgs = 0;
   }
   if (oldmsgs) {
      *oldmsgs = 0;
   }
   if (urgentmsgs) {
      *urgentmsgs = 0;
   }
   if (ast_inboxcount_func) {
      return ast_inboxcount2_func(mailbox, urgentmsgs, newmsgs, oldmsgs);
   }

   if (warned++ % 10 == 0) {
      ast_verb(3, "Message count requested for mailbox %s but voicemail not loaded.\n", mailbox);
   }

   return 0;
}

int ast_app_messagecount	(	const char *	context,
		const char *	mailbox,
		const char *	folder
	)

Check number of messages in a given context, mailbox, and folder.

Since:: 1.4

Parameters:

[in]	context	Mailbox context
[in]	mailbox	Mailbox number
[in]	folder	Mailbox folder

Returns:: Number of messages in the given context, mailbox, and folder. If folder is NULL, folder "INBOX" is assumed. If folder is "INBOX", includes number of messages in the "Urgent" folder.

Definition at line 362 of file app.c.

References ast_messagecount_func, and ast_verb.

Referenced by acf_vmcount_exec().

{
   static int warned = 0;
   if (ast_messagecount_func) {
      return ast_messagecount_func(context, mailbox, folder);
   }

   if (!warned) {
      warned++;
      ast_verb(3, "Message count requested for mailbox %s@%s/%s but voicemail not loaded.\n", mailbox, context, folder);
   }

   return 0;
}

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

Definition at line 1976 of file 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';
}

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

Definition at line 1966 of file app.c.

References parse_options().

Referenced by app_exec(), auth_exec(), bridge_exec(), cdr_read(), cdr_write(), chanspy_exec(), confbridge_exec(), connectedline_write(), controlplayback_exec(), directory_exec(), disa_exec(), dundi_query_read(), dundifunc_read(), extenspy_exec(), forkcdr_exec(), handle_options(), hint_read(), minivm_accmess_exec(), minivm_greet_exec(), minivm_record_exec(), mixmonitor_exec(), page_exec(), park_call_exec(), pbx_builtin_background(), pbx_builtin_resetcdr(), pbx_builtin_waitexten(), read_exec(), readexten_exec(), realtime_common(), receivefax_exec(), record_exec(), redirecting_write(), sendfax_exec(), sendurl_exec(), sig_pri_call(), sla_trunk_exec(), smdi_msg_retrieve_read(), sms_exec(), softhangup_exec(), speech_background(), vm_exec(), vm_execmain(), and volume_write().

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

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

Definition at line 1971 of file app.c.

References parse_options().

Referenced by conf_exec(), dial_exec_full(), and find_conf_realtime().

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

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

Definition at line 2176 of file app.c.

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

Referenced by ast_eivr_senddtmf(), pbx_builtin_wait(), pbx_builtin_waitexten(), and senddtmf_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;
   }

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

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

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

Run a macro on a channel, placing a 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. It is very important that the autoservice_chan parameter is not locked prior to calling ast_app_run_macro. A deadlock could result, otherwise.

Parameters:

autoservice_chan	A channel to place into autoservice while the macro is run
macro_chan	The channel to run the 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	failure

Definition at line 247 of file app.c.

References ast_autoservice_start(), ast_autoservice_stop(), ast_log(), ast_strlen_zero(), LOG_WARNING, pbx_exec(), pbx_findapp(), and S_OR.

Referenced by ast_channel_connected_line_macro(), ast_channel_redirecting_macro(), and generic_recall().

{
   struct ast_app *macro_app;
   int res;
   char buf[1024];

   macro_app = pbx_findapp("Macro");
   if (!macro_app) {
      ast_log(LOG_WARNING, "Cannot run macro '%s' because the 'Macro' application in not available\n", macro_name);
      return -1;
   }
   snprintf(buf, sizeof(buf), "%s%s%s", macro_name, ast_strlen_zero(macro_args) ? "" : ",", S_OR(macro_args, ""));
   if (autoservice_chan) {
      ast_autoservice_start(autoservice_chan);
   }
   res = pbx_exec(macro_chan, macro_app, buf);
   if (autoservice_chan) {
      ast_autoservice_stop(autoservice_chan);
   }
   return res;
}

int ast_app_sayname	(	struct ast_channel *	chan,
		const char *	mailbox,
		const char *	context
	)

Given a mailbox and context, play that mailbox owner's name to the channel specified.

Parameters:

[in]	chan	Channel on which to play the name
[in]	mailbox	Mailbox number from which to retrieve the recording
[in]	context	Mailbox context from which to locate the mailbox number

Return values:

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

Since:: 1.6.1

Definition at line 354 of file app.c.

References ast_sayname_func.

Referenced by common_exec(), and play_mailbox_owner().

{
   if (ast_sayname_func) {
      return ast_sayname_func(chan, mailbox, context);
   }
   return -1;
}

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

Definition at line 2102 of file app.c.

References closefrom().

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

{
   closefrom(n + 1);
}

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
file	filename
fwd,rev,stop,pause,restart,skipms,offsetms	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.

Definition at line 559 of file app.c.

References ast_channel::_state, ast_answer(), ast_debug, ast_seekstream(), AST_STATE_UP, ast_stopstream(), ast_streamfile(), ast_tellstream(), ast_verb, ast_waitfordigit(), ast_waitstream_fr(), ast_channel::language, and ast_channel::stream.

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

{
   char *breaks = NULL;
   char *end = NULL;
   int blen = 2;
   int res;
   long pause_restart_point = 0;
   long offset = 0;

   if (offsetms) {
      offset = *offsetms * 8; /* XXX Assumes 8kHz */
   }

   if (stop) {
      blen += strlen(stop);
   }
   if (suspend) {
      blen += strlen(suspend);
   }
   if (restart) {
      blen += strlen(restart);
   }

   if (blen > 2) {
      breaks = alloca(blen + 1);
      breaks[0] = '\0';
      if (stop) {
         strcat(breaks, stop);
      }
      if (suspend) {
         strcat(breaks, suspend);
      }
      if (restart) {
         strcat(breaks, restart);
      }
   }
   if (chan->_state != AST_STATE_UP) {
      res = ast_answer(chan);
   }

   if (file) {
      if ((end = strchr(file, ':'))) {
         if (!strcasecmp(end, ":end")) {
            *end = '\0';
            end++;
         }
      }
   }

   for (;;) {
      ast_stopstream(chan);
      res = ast_streamfile(chan, file, chan->language);
      if (!res) {
         if (pause_restart_point) {
            ast_seekstream(chan->stream, pause_restart_point, SEEK_SET);
            pause_restart_point = 0;
         }
         else if (end || offset < 0) {
            if (offset == -8) {
               offset = 0;
            }
            ast_verb(3, "ControlPlayback seek to offset %ld from end\n", offset);

            ast_seekstream(chan->stream, offset, SEEK_END);
            end = NULL;
            offset = 0;
         } else if (offset) {
            ast_verb(3, "ControlPlayback seek to offset %ld\n", offset);
            ast_seekstream(chan->stream, offset, SEEK_SET);
            offset = 0;
         }
         res = ast_waitstream_fr(chan, breaks, fwd, rev, skipms);
      }

      if (res < 1) {
         break;
      }

      /* We go at next loop if we got the restart char */
      if (restart && strchr(restart, res)) {
         ast_debug(1, "we'll restart the stream here at next loop\n");
         pause_restart_point = 0;
         continue;
      }

      if (suspend && strchr(suspend, res)) {
         pause_restart_point = ast_tellstream(chan->stream);
         for (;;) {
            ast_stopstream(chan);
            if (!(res = ast_waitfordigit(chan, 1000))) {
               continue;
            } else if (res == -1 || strchr(suspend, res) || (stop && strchr(stop, res))) {
               break;
            }
         }
         if (res == *suspend) {
            res = 0;
            continue;
         }
      }

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

      /* if we get one of our stop chars, return it to the calling function */
      if (stop && strchr(stop, res)) {
         break;
      }
   }

   if (pause_restart_point) {
      offset = pause_restart_point;
   } else {
      if (chan->stream) {
         offset = ast_tellstream(chan->stream);
      } else {
         offset = -8;  /* indicate end of file */
      }
   }

   if (offsetms) {
      *offsetms = offset / 8; /* samples --> ms ... XXX Assumes 8 kHz */
   }

   /* If we are returning a digit cast it as char */
   if (res > 0 || chan->stream) {
      res = (char)res;
   }

   ast_stopstream(chan);

   return res;
}

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

Send DTMF 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.

Definition at line 377 of file app.c.

References ast_autoservice_start(), ast_autoservice_stop(), ast_channel_start_silence_generator(), ast_channel_stop_silence_generator(), AST_CONTROL_FLASH, ast_indicate(), ast_log(), ast_opt_transmit_silence, ast_safe_sleep(), ast_senddigit(), ast_waitfor(), and LOG_WARNING.

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

{
   const char *ptr;
   int res = 0;
   struct ast_silence_generator *silgen = NULL;

   if (!between) {
      between = 100;
   }

   if (peer) {
      res = ast_autoservice_start(peer);
   }

   if (!res) {
      res = ast_waitfor(chan, 100);
   }

   /* ast_waitfor will return the number of remaining ms on success */
   if (res < 0) {
      if (peer) {
         ast_autoservice_stop(peer);
      }
      return res;
   }

   if (ast_opt_transmit_silence) {
      silgen = ast_channel_start_silence_generator(chan);
   }

   for (ptr = digits; *ptr; ptr++) {
      if (*ptr == 'w') {
         /* 'w' -- wait half a second */
         if ((res = ast_safe_sleep(chan, 500))) {
            break;
         }
      } else if (strchr("0123456789*#abcdfABCDF", *ptr)) {
         /* Character represents valid DTMF */
         if (*ptr == 'f' || *ptr == 'F') {
            /* ignore return values if not supported by channel */
            ast_indicate(chan, AST_CONTROL_FLASH);
         } else {
            ast_senddigit(chan, *ptr, duration);
         }
         /* pause between digits */
         if ((res = ast_safe_sleep(chan, between))) {
            break;
         }
      } else {
         ast_log(LOG_WARNING, "Illegal DTMF character '%c' in string. (0-9*#aAbBcCdD allowed)\n", *ptr);
      }
   }

   if (peer) {
      /* Stop autoservice on the peer channel, but don't overwrite any error condition
         that has occurred previously while acting on the primary channel */
      if (ast_autoservice_stop(peer) && !res) {
         res = -1;
      }
   }

   if (silgen) {
      ast_channel_stop_silence_generator(chan, silgen);
   }

   return res;
}

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

Definition at line 1987 of file 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;
}

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

Definition at line 2062 of file app.c.

References ast_get_encoded_char().

Referenced by 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;
}

void ast_install_vm_functions	(	int()(const char mailbox, const char *folder)	has_voicemail_func,
		int()(const char mailbox, int newmsgs, int oldmsgs)	inboxcount_func,
		int()(const char mailbox, int urgentmsgs, int newmsgs, int *oldmsgs)	inboxcount2_func,
		int()(const char context, const char mailbox, const char folder)	messagecount_func,
		int()(struct ast_channel chan, const char mailbox, const char context)	sayname_func
	)

Set voicemail function callbacks.

Parameters:

[in]	has_voicemail_func	set function pointer
[in]	inboxcount2_func	set function pointer
[in]	sayname_func	set function pointer
[in]	inboxcount_func	set function pointer
[in]	messagecount_func	set function pointer

Version:: 1.6.1 Added inboxcount2_func, sayname_func

Definition at line 275 of file app.c.

References ast_has_voicemail_func, ast_inboxcount2_func, ast_inboxcount_func, ast_messagecount_func, and ast_sayname_func.

Referenced by load_module().

{
   ast_has_voicemail_func = has_voicemail_func;
   ast_inboxcount_func = inboxcount_func;
   ast_inboxcount2_func = inboxcount2_func;
   ast_messagecount_func = messagecount_func;
   ast_sayname_func = sayname_func;
}

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

Definition at line 1845 of file 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;
}

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

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

Definition at line 529 of file 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, linearstream, and LOG_WARNING.

{
   struct linear_state *lin;
   char tmpf[256];
   int res = -1;
   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);
      }
      if ((fd = open(tmpf, O_RDONLY)) < 0) {
         ast_log(LOG_WARNING, "Unable to open file '%s': %s\n", tmpf, strerror(errno));
         return -1;
      }
   }
   if ((lin = ast_calloc(1, sizeof(*lin)))) {
      lin->fd = fd;
      lin->allowoverride = allowoverride;
      lin->autoclose = autoclose;
      res = ast_activate_generator(chan, &linearstream, lin);
   }
   return res;
}

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

Definition at line 1517 of file app.c.

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

Referenced by ast_module_reload(), 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;
}

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

Definition at line 1054 of file app.c.

References __ast_play_and_record(), default_acceptdtmf, and default_canceldtmf.

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

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.

Definition at line 1049 of file app.c.

References __ast_play_and_record(), default_acceptdtmf, and default_canceldtmf.

Referenced by app_exec(), ast_record_review(), 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);
}

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	silencethreshold,
		int	maxsilence_ms,
		const char *	path,
		const char *	acceptdtmf,
		const char *	canceldtmf
	)

Record a file based on input from a channel 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
acceptdtmf	Character of DTMF to end and accept the recording
canceldtmf	Character of DTMF to end and cancel the recording

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.

Definition at line 1044 of file app.c.

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

Referenced by play_record_review().

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

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.

Definition at line 697 of file app.c.

References AST_DIGIT_ANY, ast_stopstream(), ast_streamfile(), ast_test_suite_event_notify, ast_waitstream(), and ast_channel::language.

{
   int d = 0;

   ast_test_suite_event_notify("PLAYBACK", "Message: %s", fn);
   if ((d = ast_streamfile(chan, fn, chan->language))) {
      return d;
   }

   d = ast_waitstream(chan, AST_DIGIT_ANY);

   ast_stopstream(chan);

   return d;
}

char* ast_read_textfile ( const char * file )

Read a file into asterisk.

Definition at line 1852 of file app.c.

References ast_free, ast_log(), ast_malloc, errno, and LOG_WARNING.

Referenced by readfile_exec().

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

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.

Definition at line 1549 of file 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, silencethreshold, and THRESHOLD_SILENCE.

Referenced by 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;
}

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

Definition at line 1000 of file asterisk.c.

References ast_mutex_lock, ast_mutex_unlock, null_sig_handler, safe_system_level, safe_system_lock, and safe_system_prev_handler.

Referenced by ast_safe_fork(), and ast_safe_system().

{
   unsigned int level;

   ast_mutex_lock(&safe_system_lock);
   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_mutex_unlock(&safe_system_lock);
}

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

Definition at line 2107 of file 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(), errno, zombie::list, LOG_ERROR, LOG_WARNING, zombie::pid, and shaun_of_the_dead().

Referenced by app_exec(), filestream_destructor(), icesencode(), launch_script(), mp3play(), NBScatplay(), send_waveform_to_fd(), spawn_mp3(), spawn_ras(), statpost(), 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();
   }

   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_t cap = cap_from_text("cap_net_admin-eip");

      if (cap_set_proc(cap)) {
         ast_log(LOG_WARNING, "Unable to remove capabilities.\n");
      }
      cap_free(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;
   }
}

void ast_safe_fork_cleanup ( void )

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

Since:: 1.6.1

Definition at line 2171 of file app.c.

References ast_unreplace_sigchld().

Referenced by agi_exec_full(), and run_ras().

{
   ast_unreplace_sigchld();
}

int ast_safe_system ( const char * s )

Safely spawn an external program while closing file descriptors.

Note:: This replaces the system call in all Asterisk modules

Definition at line 1030 of file asterisk.c.

References ast_close_fds_above_n(), ast_log(), ast_opt_high_priority, ast_replace_sigchld(), ast_set_priority(), ast_unreplace_sigchld(), errno, LOG_WARNING, status, WEXITSTATUS, and WIFEXITED.

Referenced by add_email_attachment(), alarmreceiver_exec(), ast_monitor_stop(), consolehandler(), 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;
   int res;
   struct rusage rusage;
   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_CAP
      cap_t cap = cap_from_text("cap_net_admin-eip");

      if (cap_set_proc(cap)) {
         /* Careful with order! Logging cannot happen after we close FDs */
         ast_log(LOG_WARNING, "Unable to remove capabilities.\n");
      }
      cap_free(cap);
#endif
#ifdef HAVE_WORKING_FORK
      if (ast_opt_high_priority)
         ast_set_priority(0);
      /* Close file descriptors and launch system command */
      ast_close_fds_above_n(STDERR_FILENO);
#endif
      execl("/bin/sh", "/bin/sh", "-c", s, (char *) NULL);
      _exit(1);
   } else if (pid > 0) {
      for (;;) {
         res = wait4(pid, &status, 0, &rusage);
         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 /* !defined(HAVE_WORKING_FORK) && !defined(HAVE_WORKING_VFORK) */
   res = -1;
#endif

   return res;
}

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

Definition at line 1512 of file app.c.

References ast_lock_type, and type.

Referenced by ast_readconfig().

{
   ast_lock_type = type;
}

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.

Definition at line 2075 of file app.c.

References ast_get_encoded_char(), ast_str_buffer(), ast_str_make_space(), ast_str_set(), ast_str_size(), ast_str_update(), 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_str_thread_global_buf )

void ast_uninstall_vm_functions ( void )

Definition at line 288 of file app.c.

References ast_has_voicemail_func, ast_inboxcount2_func, ast_inboxcount_func, ast_messagecount_func, and ast_sayname_func.

Referenced by unload_module().

{
   ast_has_voicemail_func = NULL;
   ast_inboxcount_func = NULL;
   ast_inboxcount2_func = NULL;
   ast_messagecount_func = NULL;
   ast_sayname_func = NULL;
}

int ast_unlock_path ( const char * path )

Unlock a path.

Definition at line 1533 of file app.c.

References ast_lock_type, 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(), open_mailbox(), resequence_mailbox(), and save_to_folder().

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

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.

Definition at line 1015 of file asterisk.c.

References ast_mutex_lock, ast_mutex_unlock, safe_system_level, safe_system_lock, and safe_system_prev_handler.

Referenced by ast_safe_fork_cleanup(), and ast_safe_system().

{
   unsigned int level;

   ast_mutex_lock(&safe_system_lock);
   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_mutex_unlock(&safe_system_lock);
}

Asterisk developer's documentation

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation