Home page | Mailing list | Docs

Last updated: Sat Feb 3 05:00:59 2007

Asterisk developer's documentation :: Codename Pineapple

---

app.h File Reference

---

Detailed Description

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

Definition in file app.h.

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_app_option
	A structure to hold the description of an application 'option'. More...
struct	ast_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_DECLARE_APP_ARGS(name, arglist)
	Declare a structure to hold the 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, args.argv, (sizeof(args) - sizeof(args.argc)) / sizeof(args.argv[0]))
	Performs the 'nonstandard' argument separation process for an application.
#define	AST_STANDARD_APP_ARGS(args, parse)   args.argc = ast_app_separate_args(parse, '|', args.argv, (sizeof(args) - sizeof(args.argc)) / sizeof(args.argv[0]))
	Performs the 'standard' argument separation process for an application.
#define	GROUP_CATEGORY_PREFIX   "GROUP"
Typedefs
typedef int(*	ast_ivr_callback )(struct ast_channel *chan, char *option, void *cbdata)
	Callback function for IVR.
Enumerations
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 }
Functions
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, 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_get_count (const char *group, const char *category)
int	ast_app_group_match_get_count (const char *groupmatch, const char *category)
int	ast_app_group_set_channel (struct ast_channel *chan, const char *data)
int	ast_app_group_split_group (const char *data, char *group, int group_max, char *category, int category_max)
int	ast_app_has_voicemail (const char *mailbox, const char *folder)
int	ast_app_inboxcount (const char *mailbox, int *newmsgs, int *oldmsgs)
int	ast_app_messagecount (const char *context, const char *mailbox, const char *folder)
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.
unsigned int	ast_app_separate_args (char *buf, char delim, char **array, int arraylen)
	Separate a string into arguments in an array.
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)
int	ast_dtmf_stream (struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between)
	Send DTMF to a channel.
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(*messagecount_func)(const char *context, const char *mailbox, const char *folder))
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)
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 beep, int silencethreshold, int maxsilence_ms)
int	ast_play_and_record (struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path)
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 silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf)
int	ast_play_and_wait (struct ast_channel *chan, const char *fn)
char *	ast_read_textfile (const char *file)
int	ast_record_review (struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path)
void	ast_replace_sigchld (void)
	Replace the SIGCHLD handler.
int	ast_safe_system (const char *s)
void	ast_uninstall_vm_functions (void)
int	ast_unlock_path (const char *path)
void	ast_unreplace_sigchld (void)
	Restore the SIGCHLD handler.

---

Define Documentation

#define AST_APP_ARG (  name   )     char *name

Define an application argument. Parameters: name  The name of the argument Definition at line 226 of file app.h. Referenced by __login_exec(), add_agent(), astman_get_variables(), func_header_read(), function_agent(), oss_call(), oss_request(), pbx_builtin_background(), and pbx_builtin_waitexten().

#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 368 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 379 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 { OPT_JUMP = (1 << 0), OPT_BLAH = (1 << 1), OPT_BLORT = (1 << 2), } my_app_option_flags; enum { 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, } my_app_option_args; 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_parseoptions(my_app_options, &opts, opt_args, options)) { LOCAL_USER_REMOVE(u); return -1; } } Definition at line 359 of file app.h.

#define AST_DECLARE_APP_ARGS (  name, arglist   )

Value: struct { \ unsigned int argc; \ char *argv[0]; \ arglist \ } name Declare a structure to hold the application's arguments. Parameters: name  The name of the structure arglist  The list of arguments, defined using AST_APP_ARG This macro defines 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 243 of file app.h. Referenced by __login_exec(), add_agent(), astman_get_variables(), func_header_read(), function_agent(), oss_call(), oss_request(), pbx_builtin_background(), and pbx_builtin_waitexten().

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

#define AST_IVR_FLAG_AUTORESTART   (1 << 0)

Definition at line 74 of file app.h.

#define AST_NONSTANDARD_APP_ARGS (  args, parse, sep   )     args.argc = ast_app_separate_args(parse, sep, args.argv, (sizeof(args) - sizeof(args.argc)) / 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 272 of file app.h. Referenced by add_agent(), function_agent(), oss_call(), and oss_request().

#define AST_STANDARD_APP_ARGS (  args, parse   )     args.argc = ast_app_separate_args(parse, '|', args.argv, (sizeof(args) - sizeof(args.argc)) / 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 259 of file app.h. Referenced by __login_exec(), astman_get_variables(), func_header_read(), pbx_builtin_background(), and pbx_builtin_waitexten().

#define GROUP_CATEGORY_PREFIX   "GROUP"

Definition at line 208 of file app.h. Referenced by ast_app_group_get_count(), ast_app_group_match_get_count(), ast_app_group_split_group(), clone_variables(), and group_show_channels().

---

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

---

Enumeration Type Documentation

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[] 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 37 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[@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 */ } 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 188 of file app.h. { AST_LOCK_SUCCESS = 0, AST_LOCK_TIMEOUT = -1, AST_LOCK_PATH_NOT_FOUND = -2, AST_LOCK_FAILURE = -3, };

---

Function Documentation

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 Definition at line 63 of file app.c. References ast_get_indication_tone(), ast_ignore_pattern(), ast_log(), ast_matchmore_extension(), ast_playtones_start(), ast_playtones_stop(), ast_waitfordigit(), ind_tone_zone_sound::data, ast_pbx::dtimeout, LOG_NOTICE, ast_channel::pbx, and ast_channel::zone. Referenced by builtin_atxfer(), and builtin_blindtransfer(). { struct ind_tone_zone_sound *ts; int res=0, x=0; if (maxlen > size) maxlen = size; if (!timeout && chan->pbx) timeout = chan->pbx->dtimeout; else if (!timeout) timeout = 5; ts = ast_get_indication_tone(chan->zone,"dial"); if (ts && ts->data[0]) res = ast_playtones_start(chan, 0, ts->data, 0); 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; collect[x++] = res; if (!ast_matchmore_extension(chan, context, collect, 1, chan->cid.cid_num)) { if (collect[x-1] == '#') { /* Not a valid extension, ending in #, assume the # was to finish dialing */ collect[x-1] = '\0'; } break; } } if (res >= 0) res = ast_exists_extension(chan, context, collect, 1, chan->cid.cid_num) ? 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  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 108 of file app.c. References ast_readstring(), ast_strdupa, ast_streamfile(), ast_strlen_zero(), ast_pbx::dtimeout, ast_channel::pbx, ast_pbx::rtimeout, and strsep(). Referenced by __login_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->rtimeout * 1000 : 6000; to = c->pbx ? c->pbx->dtimeout * 1000 : 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->dtimeout * 1000 : 2000; } res = ast_readstring(c, s, maxlen, to, fto, "#"); if (!ast_strlen_zero(s)) return res; } return res; }

int ast_app_getdata_full (  struct ast_channel *  c, 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 153 of file app.c. References ast_readstring_full(), and ast_streamfile(). Referenced by handle_getdata(). { int res, to, fto; if (prompt) { res = ast_streamfile(c, prompt, c->language); if (res < 0) return res; } fto = 6000; to = 2000; 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_get_count (  const char *  group, const char *  category )

Get the current channel count of the specified group and category. Definition at line 832 of file app.c. References ast_channel_unlock, ast_channel_walk_locked(), ast_strlen_zero(), GROUP_CATEGORY_PREFIX, pbx_builtin_getvar_helper(), s, and S_OR. { struct ast_channel *chan; int count = 0; const char *test; char cat[80]; const char *s; if (ast_strlen_zero(group)) return 0; s = S_OR(category, GROUP_CATEGORY_PREFIX); ast_copy_string(cat, s, sizeof(cat)); chan = NULL; while ((chan = ast_channel_walk_locked(chan)) != NULL) { test = pbx_builtin_getvar_helper(chan, cat); if (test && !strcasecmp(test, group)) count++; ast_channel_unlock(chan); } return count; }

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

Get the current channel count of all groups that match the specified pattern and category. Definition at line 857 of file app.c. References ast_channel_unlock, ast_channel_walk_locked(), ast_strlen_zero(), GROUP_CATEGORY_PREFIX, pbx_builtin_getvar_helper(), s, and S_OR. { regex_t regexbuf; struct ast_channel *chan; int count = 0; const char *test; char cat[80]; const char *s; if (ast_strlen_zero(groupmatch)) return 0; /* if regex compilation fails, return zero matches */ if (regcomp(&regexbuf, groupmatch, REG_EXTENDED | REG_NOSUB)) return 0; s = S_OR(category, GROUP_CATEGORY_PREFIX); ast_copy_string(cat, s, sizeof(cat)); chan = NULL; while ((chan = ast_channel_walk_locked(chan)) != NULL) { test = pbx_builtin_getvar_helper(chan, cat); if (test && !regexec(&regexbuf, test, 0, NULL, 0)) count++; ast_channel_unlock(chan); } regfree(&regexbuf); 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 818 of file app.c. References ast_app_group_split_group(), group, and pbx_builtin_setvar_helper(). { int res=0; char group[80] = ""; char category[80] = ""; if (!ast_app_group_split_group(data, group, sizeof(group), category, sizeof(category))) { pbx_builtin_setvar_helper(chan, category, group); } else res = -1; 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 789 of file app.c. References ast_strlen_zero(), and GROUP_CATEGORY_PREFIX. Referenced by ast_app_group_set_channel(). { 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; cat = strchr(tmp, '@'); if (cat) { *cat = '\0'; cat++; } } if (!ast_strlen_zero(grp)) ast_copy_string(group, grp, group_max); else res = -1; if (cat) snprintf(category, category_max, "%s_%s", GROUP_CATEGORY_PREFIX, cat); else ast_copy_string(category, GROUP_CATEGORY_PREFIX, category_max); return res; }

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

Determine if a given mailbox has any voicemail Definition at line 191 of file app.c. References ast_has_voicemail_func, ast_verbose(), option_verbose, and VERBOSE_PREFIX_3. Referenced by action_mailboxstatus(), and has_voicemail(). { static int warned = 0; if (ast_has_voicemail_func) return ast_has_voicemail_func(mailbox, folder); if ((option_verbose > 2) && !warned) { ast_verbose(VERBOSE_PREFIX_3 "Message check requested for mailbox %s/folder %s but voicemail not loaded.\n", mailbox, folder ? folder : "INBOX"); warned++; } return 0; }

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

Determine number of new/old messages in a mailbox Definition at line 205 of file app.c. References ast_inboxcount_func, ast_verbose(), option_verbose, and VERBOSE_PREFIX_3. Referenced by action_mailboxcount(), 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 && (option_verbose > 2)) { warned++; ast_verbose(VERBOSE_PREFIX_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 )

Determine number of messages in a given mailbox and folder Definition at line 223 of file app.c. References ast_messagecount_func, ast_verbose(), option_verbose, and VERBOSE_PREFIX_3. { static int warned = 0; if (ast_messagecount_func) return ast_messagecount_func(context, mailbox, folder); if (!warned && (option_verbose > 2)) { warned++; ast_verbose(VERBOSE_PREFIX_3 "Message count requested for mailbox %s@%s/%s but voicemail not loaded.\n", mailbox, context, folder); } return 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 1324 of file app.c. References ast_app_option::arg_index, ast_clear_flag, AST_FLAGS_ALL, ast_log(), ast_set_flag, LOG_WARNING, and s. Referenced by pbx_builtin_background(), pbx_builtin_resetcdr(), and pbx_builtin_waitexten(). { char *s; int curarg; unsigned int argloc; char *arg; int res = 0; ast_clear_flag(flags, AST_FLAGS_ALL); if (!optstr) return 0; s = optstr; while (*s) { curarg = *s++ & 0x7f; /* the array (in app.h) has 128 entries */ ast_set_flag(flags, options[curarg].flag); argloc = options[curarg].arg_index; if (*s == '(') { /* Has argument */ arg = ++s; if ((s = strchr(s, ')'))) { if (argloc) args[argloc - 1] = arg; *s++ = '\0'; } else { ast_log(LOG_WARNING, "Missing closing parenthesis for argument '%c' in string '%s'\n", curarg, arg); res = -1; break; } } else if (argloc) { args[argloc - 1] = NULL; } } return res; }

unsigned int ast_app_separate_args (  char *  buf, char  delim, 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 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 889 of file app.c. Referenced by pbx_builtin_setvar(). { int argc; char *scan; int paren = 0, quote = 0; if (!buf || !array || !arraylen) return 0; memset(array, 0, arraylen * sizeof(*array)); 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 == '"' && delim != '"') { quote = quote ? 0 : 1; /* Remove quote character from argument */ memmove(scan, scan + 1, strlen(scan)); scan--; } else if (*scan == '\\') { /* Literal character, don't parse */ memmove(scan, scan + 1, strlen(scan)); } else if ((*scan == delim) && !paren && !quote) { *scan++ = '\0'; break; } } } if (*scan) array[argc++] = scan; return argc; }

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 )

Stream a file with fast forward, pause, reverse, restart. Definition at line 385 of file app.c. References ast_channel::_state, ast_answer(), ast_log(), ast_seekstream(), AST_STATE_UP, ast_stopstream(), ast_streamfile(), ast_tellstream(), ast_waitfordigit(), ast_waitstream_fr(), LOG_DEBUG, option_debug, and ast_channel::stream. Referenced by handle_controlstreamfile(). { char *breaks = NULL; char *end = NULL; int blen = 2; int res; long pause_restart_point = 0; if (stop) blen += strlen(stop); if (pause) blen += strlen(pause); if (restart) blen += strlen(restart); if (blen > 2) { breaks = alloca(blen + 1); breaks[0] = '\0'; if (stop) strcat(breaks, stop); if (pause) strcat(breaks, pause); 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) { ast_seekstream(chan->stream, 0, SEEK_END); end = NULL; }; 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)) { if (option_debug) ast_log(LOG_DEBUG, "we'll restart the stream here at next loop\n"); pause_restart_point = 0; continue; } if (pause && strchr(pause, res)) { pause_restart_point = ast_tellstream(chan->stream); for (;;) { ast_stopstream(chan); res = ast_waitfordigit(chan, 1000); if (!res) continue; else if (res == -1 || strchr(pause, res) || (stop && strchr(stop, res))) break; } if (res == *pause) { 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; } ast_stopstream(chan); return res; }

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

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. Definition at line 237 of file app.c. References ast_autoservice_start(), ast_safe_sleep(), and ast_waitfor(). Referenced by ast_bridge_call(), and misdn_send_digit(). { const char *ptr; int res = 0; 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) return res; 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); /* 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; } return res; }

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 *context, const char *mailbox, const char *folder)  messagecount_func )

Definition at line 175 of file app.c. References ast_has_voicemail_func, ast_inboxcount_func, and ast_messagecount_func. { ast_has_voicemail_func = has_voicemail_func; ast_inboxcount_func = inboxcount_func; ast_messagecount_func = messagecount_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 1286 of file app.c. References ast_ivr_menu_run_internal(). { 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 356 of file app.c. References ast_activate_generator(), ast_calloc, ast_config_AST_DATA_DIR, ast_log(), ast_strlen_zero(), linear_state::autoclose, 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); fd = open(tmpf, O_RDONLY); if (fd < 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 931 of file app.c. References AST_FILE_MODE, AST_LOCK_FAILURE, AST_LOCK_PATH_NOT_FOUND, AST_LOCK_SUCCESS, AST_LOCK_TIMEOUT, ast_log(), ast_random(), LOG_ERROR, LOG_WARNING, and s. { char *s; char *fs; int res; int fd; int lp = strlen(path); time_t start; if (!(s = alloca(lp + 10)) || !(fs = alloca(lp + 20))) { ast_log(LOG_WARNING, "Out of memory!\n"); return AST_LOCK_FAILURE; } snprintf(fs, strlen(path) + 19, "%s/.lock-%08lx", path, ast_random()); fd = open(fs, O_WRONLY | O_CREAT | O_EXCL, AST_FILE_MODE); if (fd < 0) { ast_log(LOG_ERROR, "Unable to create lock file '%s': %s\n", path, strerror(errno)); return AST_LOCK_PATH_NOT_FOUND; } close(fd); snprintf(s, strlen(path) + 9, "%s/.lock", path); start = time(NULL); while (((res = link(fs, s)) < 0) && (errno == EEXIST) && (time(NULL) - start < 5)) usleep(1); unlink(fs); if (res) { ast_log(LOG_WARNING, "Failed to lock path '%s': %s\n", path, strerror(errno)); return AST_LOCK_TIMEOUT; } else { if (option_debug) ast_log(LOG_DEBUG, "Locked path '%s'\n", path); return AST_LOCK_SUCCESS; } }

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

Record a message and prepend the message to the given record file after playing the optional playfile (or a beep), storing the duration in 'duration' and with a maximum permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. Definition at line 782 of file app.c. References __ast_play_and_record(). { return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, beep, silencethreshold, maxsilence, NULL, 1, default_acceptdtmf, default_canceldtmf); }

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

Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. calls ast_unlock_path() on 'path' if passed Definition at line 777 of file app.c. References __ast_play_and_record(). Referenced by ast_record_review(). { return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, 0, silencethreshold, maxsilence, path, 0, default_acceptdtmf, default_canceldtmf); }

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

Definition at line 772 of file app.c. References __ast_play_and_record(), and S_OR. { return __ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, 0, silencethreshold, maxsilence, path, 0, S_OR(acceptdtmf, default_acceptdtmf), S_OR(canceldtmf, default_canceldtmf)); }

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 480 of file app.c. References AST_DIGIT_ANY, ast_stopstream(), ast_streamfile(), and ast_waitstream(). Referenced by __ast_play_and_record(), and ast_record_review(). { int d; d = ast_streamfile(chan, fn, chan->language); if (d) 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 1293 of file app.c. References ast_log(), ast_malloc, free, and LOG_WARNING. { int fd; char *output = NULL; struct stat filesize; int count = 0; int res; if (stat(filename, &filesize) == -1) { ast_log(LOG_WARNING, "Error can't stat %s\n", filename); return NULL; } count = filesize.st_size + 1; fd = open(filename, O_RDONLY); if (fd < 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)); 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 992 of file app.c. References AST_DIGIT_ANY, ast_log(), ast_play_and_record(), ast_play_and_wait(), ast_stream_and_wait(), ast_verbose(), ast_waitfordigit(), LOG_WARNING, silencethreshold, and VERBOSE_PREFIX_3. { int silencethreshold = 128; 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 == NULL) { ast_log(LOG_WARNING, "Error ast_record_review called without duration pointer\n"); return -1; } cmd = '3'; /* Want to start by recording */ 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_verbose(VERBOSE_PREFIX_3 "Reviewing the recording\n"); cmd = ast_stream_and_wait(chan, recordfile, AST_DIGIT_ANY); break; case '3': message_exists = 0; /* Record */ if (recorded == 1) ast_verbose(VERBOSE_PREFIX_3 "Re-recording\n"); else ast_verbose(VERBOSE_PREFIX_3 "Recording\n"); recorded = 1; cmd = ast_play_and_record(chan, playfile, recordfile, maxtime, fmt, duration, silencethreshold, maxsilence, path); if (cmd == -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 { cmd = ast_play_and_wait(chan, "vm-torerecord"); if (!cmd) 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 617 of file asterisk.c. References ast_mutex_lock(), ast_mutex_unlock(), and null_sig_handler(). Referenced by 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) safe_system_prev_handler = signal(SIGCHLD, null_sig_handler); ast_mutex_unlock(&safe_system_lock); }

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 645 of file asterisk.c. References ast_opt_high_priority, ast_replace_sigchld(), and ast_set_priority(). Referenced by ast_closestream(), ast_monitor_change_fname(), ast_monitor_start(), ast_monitor_stop(), consolehandler(), process_text_line(), and remoteconsolehandler(). { pid_t pid; #ifdef HAVE_WORKING_FORK int x; #endif 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_WORKING_FORK if (ast_opt_high_priority) ast_set_priority(0); /* Close file descriptors and launch system command */ for (x = STDERR_FILENO + 1; x < 4096; x++) close(x); #endif execl("/bin/sh", "/bin/sh", "-c", s, (char *) NULL); _exit(1); } else if (pid > 0) { for (;;) { res = 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 res = -1; #endif return res; }

void ast_uninstall_vm_functions (  void   )

Definition at line 184 of file app.c. References ast_has_voicemail_func, ast_inboxcount_func, and ast_messagecount_func. { ast_has_voicemail_func = NULL; ast_inboxcount_func = NULL; ast_messagecount_func = NULL; }

int ast_unlock_path (  const char *  path  )

Unlock a path Definition at line 970 of file app.c. References ast_log(), LOG_ERROR, LOG_WARNING, and s. { char *s; int res; if (!(s = alloca(strlen(path) + 10))) { ast_log(LOG_WARNING, "Out of memory!\n"); return -1; } snprintf(s, strlen(path) + 9, "%s/%s", path, ".lock"); if ((res = unlink(s))) ast_log(LOG_ERROR, "Could not unlock path '%s': %s\n", path, strerror(errno)); else { if (option_debug) ast_log(LOG_DEBUG, "Unlocked path '%s'\n", path); } return res; }

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 631 of file asterisk.c. References ast_mutex_lock(), and ast_mutex_unlock(). Referenced by agi_exec_full(). { 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) signal(SIGCHLD, safe_system_prev_handler); ast_mutex_unlock(&safe_system_lock); }

---

Asterisk is a trademark for Digium, inc.. | Edvina.net | Asterisk.org | This documentation was generated with Doxygen