diff options
Diffstat (limited to 'include/asterisk/app.h')
-rwxr-xr-x | include/asterisk/app.h | 95 |
1 files changed, 52 insertions, 43 deletions
diff --git a/include/asterisk/app.h b/include/asterisk/app.h index b7d0e2fa7..3c9c49e48 100755 --- a/include/asterisk/app.h +++ b/include/asterisk/app.h @@ -29,46 +29,46 @@ extern "C" { /* IVR stuff */ -/* Callback function for IVR, returns 0 on completion, -1 on hangup or digit if - interrupted */ +/*! \brief Callback function for IVR + \return returns 0 on completion, -1 on hangup or digit if interrupted + */ typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata); typedef enum { - 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_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; +/*! + Special "options" are: + \arg "s" - "start here (one time greeting)" + \arg "g" - "greeting/instructions" + \arg "t" - "timeout" + \arg "h" - "hangup" + \arg "i" - "invalid selection" + +*/ struct ast_ivr_option { char *option; ast_ivr_action action; void *adata; }; -/* - Special "options" are: - "s" - "start here (one time greeting)" - "g" - "greeting/instructions" - "t" - "timeout" - "h" - "hangup" - "i" - "invalid selection" - -*/ - struct ast_ivr_menu { - char *title; /* Title of menu */ - unsigned int flags; /* Flags */ - struct ast_ivr_option *options; /* All options */ + char *title; /*!< Title of menu */ + unsigned int flags; /*!< Flags */ + struct ast_ivr_option *options; /*!< All options */ }; #define AST_IVR_FLAG_AUTORESTART (1 << 0) @@ -78,11 +78,11 @@ struct ast_ivr_menu { static struct ast_ivr_menu holder = { title, flags, __options_##holder } -/*! Runs an IVR menu, returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */ +/*! \brief Runs an IVR menu + \return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */ extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata); -/*! Plays a stream and gets DTMF data from a channel */ -/*! +/*! \brief Plays a stream and gets DTMF data from a channel * \param c Which channel one is interacting with * \param prompt File to pass to ast_streamfile (the one that you wish to play) * \param s The location where the DTMF data will be stored @@ -96,7 +96,7 @@ extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, vo */ extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout); -/* Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */ +/*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */ extern int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd); /*! Record voice (after playing prompt if specified), waiting for silence (in ms) up to a given timeout (in s) or '#' */ @@ -113,7 +113,9 @@ int ast_app_has_voicemail(const char *mailbox, const char *folder); /*! Determine number of new/old messages in a mailbox */ int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs); -/*! Safely spawn an external program while closingn file descriptors */ +/*! Safely spawn an external program while closing file descriptors + \note This replaces the \b system call in all Asterisk modules +*/ extern int ast_safe_system(const char *s); /*! Send DTMF to chan (optionally entertain peer) */ @@ -128,13 +130,18 @@ int ast_control_streamfile(struct ast_channel *chan, const char *file, const cha /*! Play a stream and wait for a digit, returning the digit that was pressed */ int ast_play_and_wait(struct ast_channel *chan, const char *fn); -/*! 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. +/*! 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 + \n + 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 */ 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 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. */ +/*! 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 +\n + permitted silence time in milliseconds of 'maxsilence' under + 'silencethreshold' or use '-1' for either or both parameters for defaults. */ 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); enum AST_LOCK_RESULT { @@ -144,17 +151,17 @@ enum AST_LOCK_RESULT { AST_LOCK_FAILURE = -3, }; -/* +/*! * \brief Lock a filesystem path. * \param path the path to be locked - * \return one of AST_LOCK_RESULT values + * \return one of \ref AST_LOCK_RESULT values */ enum AST_LOCK_RESULT ast_lock_path(const char *path); -/* Unlock a path */ +/*! Unlock a path */ int ast_unlock_path(const char *path); -/*Read a file into asterisk*/ +/*! Read a file into asterisk*/ char *ast_read_textfile(const char *file); #define GROUP_CATEGORY_PREFIX "GROUP" @@ -188,7 +195,7 @@ int ast_app_group_match_get_count(char *groupmatch, char *category); argc argument counter. The arguments must be declared using AST_APP_ARG, and they will all be character pointers (strings). - Note: The structure is <b>not</b> initialized, as the call to + \note The structure is <b>not</b> initialized, as the call to ast_separate_app_args() will perform that function before parsing the arguments. */ @@ -329,7 +336,9 @@ struct ast_app_option { */ int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr); -/*! Present a dialtone and collect a certain length extension. Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension. Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */ +/*! \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. +\note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */ int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout); /*! Allow to record message and have a review option */ |