2001-08-05 21:46:13 +00:00
/*
2005-08-30 18:32:10 +00:00
* Asterisk - - An open source telephony toolkit .
2001-08-05 21:46:13 +00:00
*
2005-01-21 07:06:25 +00:00
* Copyright ( C ) 1999 - 2005 , Digium , Inc .
2001-08-05 21:46:13 +00:00
*
2004-09-17 15:05:29 +00:00
* Mark Spencer < markster @ digium . com >
2005-08-30 18:32:10 +00:00
* See http : //www.asterisk.org for more information about
* the Asterisk project . Please do not directly contact
* any of the maintainers of this project for assistance ;
* the project provides a web site , mailing lists and IRC
* channels for your use .
2001-08-05 21:46:13 +00:00
*
* This program is free software , distributed under the terms of
2005-08-30 18:32:10 +00:00
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree .
*/
2005-10-24 20:12:06 +00:00
/*! \file
* \ brief Application convenience functions , designed to give consistent
2007-12-11 14:17:29 +00:00
* look and feel to Asterisk apps .
2001-08-05 21:46:13 +00:00
*/
# ifndef _ASTERISK_APP_H
# define _ASTERISK_APP_H
2008-12-13 08:36:35 +00:00
# include "asterisk/strings.h"
# include "asterisk/threadstorage.h"
2007-11-22 03:50:04 +00:00
struct ast_flags64 ;
2001-08-05 21:46:13 +00:00
# if defined(__cplusplus) || defined(c_plusplus)
extern " C " {
# endif
2005-02-17 14:57:36 +00:00
2009-03-27 16:21:10 +00:00
AST_THREADSTORAGE_EXTERNAL ( ast_str_thread_global_buf ) ;
2008-12-13 08:36:35 +00:00
2005-02-17 14:57:36 +00:00
/* IVR stuff */
2005-11-06 15:09:47 +00:00
/*! \brief Callback function for IVR
2009-03-09 20:58:17 +00:00
\ return returns 0 on completion , - 1 on hangup or digit if interrupted
2005-11-06 15:09:47 +00:00
*/
2005-02-17 14:57:36 +00:00
typedef int ( * ast_ivr_callback ) ( struct ast_channel * chan , char * option , void * cbdata ) ;
typedef enum {
2005-11-06 15:09:47 +00:00
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 */
2007-05-31 10:26:55 +00:00
AST_ACTION_TRANSFER , /*!< adata is a string with exten\verbatim[@context]\endverbatim */
2005-11-06 15:09:47 +00:00
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 */
2005-02-17 14:57:36 +00:00
} ast_ivr_action ;
2009-03-09 20:58:17 +00:00
/*!
Special " options " are :
2005-11-06 15:09:47 +00:00
\ arg " s " - " start here (one time greeting) "
\ arg " g " - " greeting/instructions "
\ arg " t " - " timeout "
\ arg " h " - " hangup "
\ arg " i " - " invalid selection "
*/
2005-02-17 14:57:36 +00:00
struct ast_ivr_option {
char * option ;
ast_ivr_action action ;
2009-03-09 20:58:17 +00:00
void * adata ;
2005-02-17 14:57:36 +00:00
} ;
struct ast_ivr_menu {
2005-11-06 15:09:47 +00:00
char * title ; /*!< Title of menu */
unsigned int flags ; /*!< Flags */
struct ast_ivr_option * options ; /*!< All options */
2005-02-17 14:57:36 +00:00
} ;
2005-03-05 21:06:26 +00:00
# define AST_IVR_FLAG_AUTORESTART (1 << 0)
2005-11-03 21:19:11 +00:00
# define AST_IVR_DECLARE_MENU(holder, title, flags, foo...) \
2005-02-26 19:06:09 +00:00
static struct ast_ivr_option __options_ # # holder [ ] = foo ; \
static struct ast_ivr_menu holder = { title , flags , __options_ # # holder }
2009-03-09 20:58:17 +00:00
/*! \brief Runs an IVR menu
2005-11-06 15:09:47 +00:00
\ return returns 0 on successful completion , - 1 on hangup , or - 2 on user error in menu */
2006-03-31 00:11:45 +00:00
int ast_ivr_menu_run ( struct ast_channel * c , struct ast_ivr_menu * menu , void * cbdata ) ;
2005-02-17 14:57:36 +00:00
2009-03-09 20:58:17 +00:00
/*! \brief Plays a stream and gets DTMF data from a channel
2001-10-31 15:28:08 +00:00
* \ param c Which channel one is interacting with
2006-11-10 03:59:48 +00:00
* \ param 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 " .
2001-10-31 15:28:08 +00:00
* \ param s The location where the DTMF data will be stored
* \ param maxlen Max Length of the data
* \ param timeout Timeout length waiting for data ( in milliseconds ) . Set to 0 for standard timeout ( six seconds ) , or - 1 for no time out .
*
2009-03-09 20:58:17 +00:00
* 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
2001-10-31 15:28:08 +00:00
* is pressed during playback , it will immediately break out of the message and continue
* execution of your code .
*/
2006-11-10 03:59:48 +00:00
int ast_app_getdata ( struct ast_channel * c , const char * prompt , char * s , int maxlen , int timeout ) ;
2001-08-05 21:46:13 +00:00
2005-11-06 15:09:47 +00:00
/*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
2006-03-31 00:11:45 +00:00
int ast_app_getdata_full ( struct ast_channel * c , char * prompt , char * s , int maxlen , int timeout , int audiofd , int ctrlfd ) ;
2003-02-23 06:00:11 +00:00
2009-03-09 20:58:17 +00:00
/*!
* \ brief Set voicemail function callbacks
* \ param [ in ] inboxcount2_func set function pointer
* \ param [ in ] sayname_func set function pointer
* \ param [ in ] inboxcount_func set function pointer
* \ param [ in ] messagecount_func set function pointer
* \ version 1.6 .1 Added inboxcount2_func , sayname_func
*/
2004-12-31 01:11:33 +00:00
void ast_install_vm_functions ( int ( * has_voicemail_func ) ( const char * mailbox , const char * folder ) ,
2008-07-02 21:27:53 +00:00
int ( * inboxcount_func ) ( const char * mailbox , int * newmsgs , int * oldmsgs ) ,
int ( * inboxcount2_func ) ( const char * mailbox , int * urgentmsgs , int * newmsgs , int * oldmsgs ) ,
2008-04-28 22:38:07 +00:00
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 ) ) ;
2008-07-02 21:27:53 +00:00
2004-12-31 01:11:33 +00:00
void ast_uninstall_vm_functions ( void ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Determine if a given mailbox has any voicemail */
2004-12-31 01:11:33 +00:00
int ast_app_has_voicemail ( const char * mailbox , const char * folder ) ;
2003-03-26 00:15:11 +00:00
2008-07-02 21:27:53 +00:00
/*! \brief Determine number of new/old messages in a mailbox */
int ast_app_inboxcount ( const char * mailbox , int * newmsgs , int * oldmsgs ) ;
2009-03-09 20:58:17 +00:00
/*!
* \ brief Determine number of urgent / new / old messages in a mailbox
* \ param [ in ] mailbox the mailbox context to use
* \ param [ out ] urgentmsgs the urgent message count
* \ param [ out ] newmsgs the new message count
* \ param [ out ] oldmsgs the old message count
* \ return Returns 0 for success , negative upon error
* \ since 1.6 .1
*/
2008-07-02 21:27:53 +00:00
int ast_app_inboxcount2 ( const char * mailbox , int * urgentmsgs , int * newmsgs , int * oldmsgs ) ;
2002-12-26 19:38:27 +00:00
2009-03-09 20:58:17 +00:00
/*!
* \ brief Given a mailbox and context , play that mailbox owner ' s name to the channel specified
* \ param [ in ] chan channel to announce name to
* \ param [ in ] mailbox mailbox to retrieve name for
* \ param [ in ] context context to retrieve name for
* \ return Returns 0 for success , negative upon error
* \ since 1.6 .1
*/
2008-04-28 22:38:07 +00:00
int ast_app_sayname ( struct ast_channel * chan , const char * mailbox , const char * context ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Determine number of messages in a given mailbox and folder */
2006-05-19 18:21:31 +00:00
int ast_app_messagecount ( const char * context , const char * mailbox , const char * folder ) ;
2006-05-18 18:28:52 +00:00
2009-03-09 20:58:17 +00:00
/*! \brief Safely spawn an external program while closing file descriptors
2005-11-06 15:09:47 +00:00
\ note This replaces the \ b system call in all Asterisk modules
*/
2006-03-31 00:11:45 +00:00
int ast_safe_system ( const char * s ) ;
2004-03-21 18:15:37 +00:00
2006-05-25 18:31:19 +00:00
/*!
* \ brief 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 ,
2006-12-12 22:32:20 +00:00
* then this signal handler needs to be temporarily replaced .
2006-05-25 18:31:19 +00:00
*
* Code that executes this function * must * call ast_unreplace_sigchld ( )
* after it is finished doing the wait * ( ) .
*/
void ast_replace_sigchld ( void ) ;
/*!
* \ brief 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 .
*/
void ast_unreplace_sigchld ( void ) ;
2006-01-11 05:23:19 +00:00
/*!
\ brief Send DTMF to a channel
\ param chan The channel that will receive the DTMF frames
2006-07-30 15:02:34 +00:00
\ param peer ( optional ) Peer channel that will be autoserviced while the
primary channel is receiving DTMF
\ param 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 .
\ param 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 .
2007-08-06 21:52:30 +00:00
\ param duration This is the duration that each DTMF digit should have .
2006-01-11 05:23:19 +00:00
*/
2007-08-06 21:52:30 +00:00
int ast_dtmf_stream ( struct ast_channel * chan , struct ast_channel * peer , const char * digits , int between , unsigned int duration ) ;
2004-05-07 20:39:14 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Stream a filename (or file descriptor) as a generator. */
2004-05-13 19:01:10 +00:00
int ast_linear_stream ( struct ast_channel * chan , const char * filename , int fd , int allowoverride ) ;
2009-03-09 20:58:17 +00:00
/*!
* \ brief Stream a file with fast forward , pause , reverse , restart .
* \ param chan
2007-07-09 04:09:16 +00:00
* \ param file filename
2009-03-09 20:58:17 +00:00
* \ param fwd , rev , stop , pause , restart , skipms , offsetms
2007-12-11 14:17:29 +00:00
*
2009-03-09 20:58:17 +00:00
* Before calling this function , set this to be the number
2007-07-09 04:09:16 +00:00
* 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 .
2007-06-08 21:02:46 +00:00
*/
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 ) ;
2004-05-26 15:22:54 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
2005-01-10 14:46:59 +00:00
int ast_play_and_wait ( struct ast_channel * chan , const char * fn ) ;
2004-09-17 15:05:29 +00:00
2006-05-05 19:10:11 +00:00
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 ) ;
2009-03-09 20:58:17 +00:00
/*! \brief 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
2005-11-06 15:09:47 +00:00
\ n
2009-03-09 20:58:17 +00:00
permitted silence time in milliseconds of ' maxsilence ' under ' silencethreshold ' or use ' - 1 ' for either or both parameters for defaults .
2005-01-23 09:05:01 +00:00
calls ast_unlock_path ( ) on ' path ' if passed */
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 ) ;
2004-09-17 15:05:29 +00:00
2009-03-09 20:58:17 +00:00
/*! \brief 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
2007-12-11 14:17:29 +00:00
' silencethreshold ' or use ' - 1 ' for either or both parameters for defaults . */
2004-09-18 14:01:35 +00:00
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 ) ;
2004-09-17 15:05:29 +00:00
2009-03-03 23:21:18 +00:00
enum ast_getdata_result {
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 ,
} ;
2005-07-13 19:27:09 +00:00
enum AST_LOCK_RESULT {
AST_LOCK_SUCCESS = 0 ,
AST_LOCK_TIMEOUT = - 1 ,
AST_LOCK_PATH_NOT_FOUND = - 2 ,
AST_LOCK_FAILURE = - 3 ,
} ;
2007-08-28 16:28:26 +00:00
/*! \brief Type of locking to use in ast_lock_path / ast_unlock_path */
enum AST_LOCK_TYPE {
AST_LOCK_TYPE_LOCKFILE = 0 ,
AST_LOCK_TYPE_FLOCK = 1 ,
} ;
/*!
* \ brief Set the type of locks used by ast_lock_path ( )
* \ param type the locking type to use
*/
void ast_set_lock_type ( enum AST_LOCK_TYPE type ) ;
2005-11-06 15:09:47 +00:00
/*!
2005-07-13 19:27:09 +00:00
* \ brief Lock a filesystem path .
* \ param path the path to be locked
2005-11-06 15:09:47 +00:00
* \ return one of \ ref AST_LOCK_RESULT values
2005-07-13 19:27:09 +00:00
*/
enum AST_LOCK_RESULT ast_lock_path ( const char * path ) ;
2005-01-23 09:05:01 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Unlock a path */
2005-01-23 09:05:01 +00:00
int ast_unlock_path ( const char * path ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Read a file into asterisk*/
2005-02-27 19:07:46 +00:00
char * ast_read_textfile ( const char * file ) ;
2007-11-22 03:50:04 +00:00
struct ast_group_info ;
2004-10-03 16:34:52 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Split a group string into group and category, returning a default category if none is provided. */
2005-12-03 19:25:33 +00:00
int ast_app_group_split_group ( const char * data , char * group , int group_max , char * category , int category_max ) ;
2004-10-03 16:34:52 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Set the group for a channel, splitting the provided data into group and category, if specified. */
2005-12-03 19:25:33 +00:00
int ast_app_group_set_channel ( struct ast_channel * chan , const char * data ) ;
2004-10-03 16:34:52 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Get the current channel count of the specified group and category. */
2005-12-03 19:25:33 +00:00
int ast_app_group_get_count ( const char * group , const char * category ) ;
2004-10-03 16:34:52 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Get the current channel count of all groups that match the specified pattern and category. */
2005-12-03 19:25:33 +00:00
int ast_app_group_match_get_count ( const char * groupmatch , const char * category ) ;
2004-10-03 16:34:52 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Discard all group counting for a channel */
2007-04-25 19:27:42 +00:00
int ast_app_group_discard ( struct ast_channel * chan ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Update all group counting for a channel to a new one */
2007-05-31 18:43:59 +00:00
int ast_app_group_update ( struct ast_channel * oldchan , struct ast_channel * newchan ) ;
2007-05-07 21:47:08 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Write Lock the group count list */
2007-06-13 18:23:12 +00:00
int ast_app_group_list_wrlock ( void ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Read Lock the group count list */
2007-06-13 18:23:12 +00:00
int ast_app_group_list_rdlock ( void ) ;
2007-04-25 19:27:42 +00:00
2007-12-11 14:17:29 +00:00
/*! \brief Get the head of the group count list */
2007-04-25 19:27:42 +00:00
struct ast_group_info * ast_app_group_list_head ( void ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Unlock the group count list */
2007-04-25 19:27:42 +00:00
int ast_app_group_list_unlock ( void ) ;
2005-10-28 16:19:43 +00:00
/*!
\ brief Define an application argument
\ param name The name of the argument
*/
# define AST_APP_ARG(name) char *name
/*!
2008-01-24 22:26:04 +00:00
\ brief Declare a structure to hold an application ' s arguments .
2005-10-28 16:19:43 +00:00
\ param name The name of the structure
\ param arglist The list of arguments , defined using AST_APP_ARG
2008-01-24 22:26:04 +00:00
This macro declares a structure intended to be used in a call
2005-11-10 23:08:00 +00:00
to ast_app_separate_args ( ) . The structure includes all the
2005-10-28 16:19:43 +00:00
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 ) .
2005-11-06 15:09:47 +00:00
\ note The structure is < b > not < / b > initialized , as the call to
2005-11-10 23:08:00 +00:00
ast_app_separate_args ( ) will perform that function before parsing
2005-10-28 16:19:43 +00:00
the arguments .
*/
2008-01-24 22:26:04 +00:00
# define AST_DECLARE_APP_ARGS(name, arglist) AST_DEFINE_APP_ARGS_TYPE(, arglist) name
/*!
\ brief Define a structure type to hold an application ' s arguments .
\ param type The name of the structure type
\ param 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 .
*/
# define AST_DEFINE_APP_ARGS_TYPE(type, arglist) \
2008-01-24 22:36:19 +00:00
struct type { \
2005-11-03 21:19:11 +00:00
unsigned int argc ; \
2005-10-28 16:19:43 +00:00
char * argv [ 0 ] ; \
arglist \
2008-01-24 22:26:04 +00:00
}
2005-10-28 16:19:43 +00:00
/*!
\ brief Performs the ' standard ' argument separation process for an application .
\ param args An argument structure defined using AST_DECLARE_APP_ARGS
\ param parse A modifiable buffer containing the input to be parsed
This function will separate the input string using the standard argument
2008-01-02 20:19:40 +00:00
separator character ' , ' and fill in the provided structure , including
2005-10-28 16:19:43 +00:00
the argc argument counter field .
*/
# define AST_STANDARD_APP_ARGS(args, parse) \
2008-01-24 22:01:55 +00:00
args . argc = ast_app_separate_args ( parse , ' , ' , args . argv , ( ( sizeof ( args ) - offsetof ( typeof ( args ) , argv ) ) / sizeof ( args . argv [ 0 ] ) ) )
2009-03-09 20:58:17 +00:00
2006-01-13 18:30:49 +00:00
/*!
\ brief Performs the ' nonstandard ' argument separation process for an application .
\ param args An argument structure defined using AST_DECLARE_APP_ARGS
\ param parse A modifiable buffer containing the input to be parsed
\ param 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 .
*/
# define AST_NONSTANDARD_APP_ARGS(args, parse, sep) \
2008-01-24 22:01:55 +00:00
args . argc = ast_app_separate_args ( parse , sep , args . argv , ( ( sizeof ( args ) - offsetof ( typeof ( args ) , argv ) ) / sizeof ( args . argv [ 0 ] ) ) )
2009-03-09 20:58:17 +00:00
2005-05-04 03:43:10 +00:00
/*!
\ brief Separate a string into arguments in an array
\ param buf The string to be parsed ( this must be a writable copy , as it will be modified )
\ param delim The character to be used to delimit arguments
\ param array An array of ' char * ' to be filled in with pointers to the found arguments
\ param 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 .
2005-10-28 16:19:43 +00:00
The array will be completely zeroed by this function before it populates any entries .
2005-05-04 03:43:10 +00:00
\ return The number of arguments found , or zero if the function arguments are not valid .
*/
2005-11-03 21:19:11 +00:00
unsigned int ast_app_separate_args ( char * buf , char delim , char * * array , int arraylen ) ;
/*!
\ brief A structure to hold the description of an application ' option ' .
Application ' options ' are single - character flags that can be supplied
to the application to affect its behavior ; they can also optionally
accept arguments enclosed in parenthesis .
These structures are used by the ast_app_parse_options function , uses
this data to fill in a flags structure ( to indicate which options were
supplied ) and array of argument pointers ( for those options that had
arguments supplied ) .
*/
struct ast_app_option {
/*! \brief The flag bit that represents this option. */
2007-11-30 21:19:57 +00:00
uint64_t flag ;
2005-11-03 21:19:11 +00:00
/*! \brief The index of the entry in the arguments array
that should be used for this option ' s argument . */
unsigned int arg_index ;
} ;
2007-02-10 00:40:57 +00:00
# define BEGIN_OPTIONS {
# define END_OPTIONS }
2005-11-03 21:19:11 +00:00
/*!
\ brief Declares an array of options for an application .
\ param holder The name of the array to be created
\ param options The actual options to be placed into the array
\ sa ast_app_parse_options
This macro declares a ' static const ' array of \ c struct \ c 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 :
\ code
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 ) ) {
2007-12-13 20:23:48 +00:00
ast_module_user_remove ( u ) ;
2005-11-03 21:19:11 +00:00
return - 1 ;
}
}
\ endcode
*/
# define AST_APP_OPTIONS(holder, options...) \
static const struct ast_app_option holder [ 128 ] = options
/*!
\ brief Declares an application option that does not accept an argument .
\ param option The single character representing the option
\ param flagno The flag index to be set if this option is present
\ sa AST_APP_OPTIONS , ast_app_parse_options
*/
# define AST_APP_OPTION(option, flagno) \
[ option ] = { . flag = flagno }
/*!
\ brief Declares an application option that accepts an argument .
\ param option The single character representing the option
\ param flagno The flag index to be set if this option is present
\ param argno The index into the argument array where the argument should
be placed
\ sa AST_APP_OPTIONS , ast_app_parse_options
*/
# define AST_APP_OPTION_ARG(option, flagno, argno) \
2005-11-08 03:41:10 +00:00
[ option ] = { . flag = flagno , . arg_index = argno + 1 }
2005-11-03 21:19:11 +00:00
/*!
\ brief Parses a string containing application options and sets flags / arguments .
\ param options The array of possible options declared with AST_APP_OPTIONS
\ param flags The flag structure to have option flags set
\ param args The array of argument pointers to hold arguments found
\ param optstr The string containing the options to be parsed
\ return zero for success , non - zero if an error occurs
\ sa AST_APP_OPTIONS
*/
int ast_app_parse_options ( const struct ast_app_option * options , struct ast_flags * flags , char * * args , char * optstr ) ;
2004-12-29 18:43:38 +00:00
After some study, thought, comparing, etc. I've backed out the previous universal mod to make ast_flags a 64 bit thing. Instead, I added a 64-bit version of ast_flags (ast_flags64), and 64-bit versions of the test-flag, set-flag, etc. macros, and an app_parse_options64 routine, and I use these in app_dial alone, to eliminate the 30-option limit it had grown to meet. There is room now for 32 more options and flags. I was heavily tempted to implement some of the other ideas that were presented, but this solution does not intro any new versions of dial, doesn't have a different API, has a minimal/zero impact on code outside of dial, and doesn't seriously (I hope) affect the code structure of dial. It's the best I can think of right now. My goal was NOT to rewrite dial. I leave that to a future, coordinated effort.
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@75983 65c4cc65-6c06-0410-ace0-fbb531ad65f3
2007-07-19 23:24:27 +00:00
/*!
\ brief Parses a string containing application options and sets flags / arguments .
\ param options The array of possible options declared with AST_APP_OPTIONS
\ param flags The 64 - bit flag structure to have option flags set
\ param args The array of argument pointers to hold arguments found
\ param optstr The string containing the options to be parsed
\ return zero for success , non - zero if an error occurs
\ sa AST_APP_OPTIONS
*/
int ast_app_parse_options64 ( const struct ast_app_option * options , struct ast_flags64 * flags , char * * args , char * optstr ) ;
2008-03-01 01:30:37 +00:00
/*! \brief Given a list of options array, return an option string based on passed flags
\ param options The array of possible options declared with AST_APP_OPTIONS
\ param flags The flags of the options that you wish to populate the buffer with
\ param buf The buffer to fill with the string of options
\ param len The maximum length of buf
*/
void ast_app_options2str64 ( const struct ast_app_option * options , struct ast_flags64 * flags , char * buf , size_t len ) ;
/*! \brief Present a dialtone and collect a certain length extension.
\ return Returns 1 on valid extension entered , - 1 on hangup , or 0 on invalid extension .
2005-11-06 15:09:47 +00:00
\ note Note that if ' collect ' holds digits already , new digits will be appended , so be sure it ' s initialized properly */
2005-01-05 19:56:47 +00:00
int ast_app_dtget ( struct ast_channel * chan , const char * context , char * collect , size_t size , int maxlen , int timeout ) ;
2007-12-11 14:17:29 +00:00
/*! \brief Allow to record message and have a review option */
2005-01-23 09:05:01 +00:00
int ast_record_review ( struct ast_channel * chan , const char * playfile , const char * recordfile , int maxtime , const char * fmt , int * duration , const char * path ) ;
2005-01-07 07:23:31 +00:00
2009-01-29 13:21:31 +00:00
/*! \brief Decode an encoded control or extended ASCII character
\ return Returns a pointer to the result string
*/
2007-10-26 00:11:31 +00:00
int ast_get_encoded_char ( const char * stream , char * result , size_t * consumed ) ;
2008-11-05 21:58:48 +00:00
/*! \brief Decode a stream of encoded control or extended ASCII characters */
2009-01-29 13:21:31 +00:00
char * ast_get_encoded_str ( const char * stream , char * result , size_t result_len ) ;
2008-11-05 21:58:48 +00:00
2009-02-20 17:29:51 +00:00
/*! \brief Decode a stream of encoded control or extended ASCII characters */
int ast_str_get_encoded_str ( struct ast_str * * str , int maxlen , const char * stream ) ;
2009-03-09 20:58:17 +00:00
/*!
* \ brief Common routine for child processes , to close all fds prior to exec ( 2 )
* \ param [ in ] n starting file descriptor number for closing all higher file descriptors
* \ since 1.6 .1
*/
2008-04-16 22:57:54 +00:00
void ast_close_fds_above_n ( int n ) ;
2009-03-09 20:58:17 +00:00
/*!
* \ brief Common routine to safely fork without a chance of a signal handler firing badly in the child
* \ param [ in ] stop_reaper flag to determine if sigchld handler is replaced or not
* \ since 1.6 .1
*/
2008-04-16 22:57:54 +00:00
int ast_safe_fork ( int stop_reaper ) ;
2009-03-09 20:58:17 +00:00
/*!
* \ brief Common routine to cleanup after fork ' ed process is complete ( if reaping was stopped )
* \ since 1.6 .1
*/
2008-04-16 22:57:54 +00:00
void ast_safe_fork_cleanup ( void ) ;
2001-08-05 21:46:13 +00:00
# if defined(__cplusplus) || defined(c_plusplus)
}
# endif
2005-08-30 18:32:10 +00:00
# endif /* _ASTERISK_APP_H */