dect
/
asterisk
Archived
13
0
Fork 0
Code Releases Activity

Merge a bunch of doxygen updates to header files. This includes changes to 

use the \retval tag for documenting return values, fixing various warnings
when generating the documentation, and various other things.
(closes issue #10203, snuffy)


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@75164 f38db490-d61c-443f-a65b-d21fe96a405b
This commit is contained in:
russell 2007-07-16 02:51:56 +00:00
parent 040609f7b5
commit 2bf80313d6
26 changed files with 566 additions and 410 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
include/asterisk/abstract_jb.h
View File

@ -113,7 +113,8 @@ struct ast_jb
* appropriate internal jb flags to the channels, determining further behaviour
* of the bridged jitterbuffers.
*
* \return zero if there are no jitter buffers in use, non-zero if there are
* \retval zero if there are no jitter buffers in use
* \retval non-zero if there are
*/
int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
@ -150,7 +151,8 @@ int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, in
* Dropped by the jb implementation frames are considered successfuly enqueued as
* far as they should not be delivered at all.
*
* \return zero if the frame was queued, -1 if not.
* \retval 0 if the frame was queued
* \retval -1 if not
*/
int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);

149
include/asterisk/adsi.h
View File

@ -117,13 +117,12 @@
#define ADSI_DIR_FROM_LEFT (0)
#define ADSI_DIR_FROM_RIGHT (1)
/*! Perform Asterisk ADSI initialization (for channel drivers that want */
/* to support ADSI when the handset is first lifted) */
/*!
/*! Perform Asterisk ADSI initialization (for channel drivers that want
* to support ADSI when the handset is first lifted)
* \param chan Channel to initialize for ADSI (if supported)
*
* Returns 0 on success (or adsi unavailable) and -1 on hangup
*
* \retval 0 on success (or adsi unavailable.
* \retval -1 on hangup.
*/
extern int (*ast_adsi_channel_init)(struct ast_channel *chan);
@ -131,39 +130,39 @@ extern int (*ast_adsi_begin_download)(struct ast_channel *chan, char *service, u
extern int (*ast_adsi_end_download)(struct ast_channel *chan);
/*! Restore ADSI initialization (for applications that play with ADSI */
/* and want to restore it to normal. If you touch "INFO" then you */
/* have to use the ast_adsi_channel_init again instead. */
/*!
/*! Restore ADSI initialization (for applications that play with ADSI
* and want to restore it to normal. If you touch "INFO" then you
* have to use the ast_adsi_channel_init again instead.
* \param chan Channel to restore
*
* Returns 0 on success (or adsi unavailable) and -1 on hangup
*
* \retval 0 on success (or adsi unavailable)
* \retval -1 on hangup
*/
extern int (*ast_adsi_channel_restore)(struct ast_channel *chan);
/*! Display some stuff on the screen */
/*!
/*!
* \brief Display some stuff on the screen
* \param chan Channel to display on
* \param lines NULL-terminated list of things to print (no more than 4 recommended)
* \param align list of alignments to use (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CEN, etc..)
* \param voice whether to jump into voice mode when finished
*
* Return 0 on success (or adsi unavailable) and -1 on hangup
*
* \retval 0 on success (or adsi unavailable)
* \retval -1 on hangup
*/
extern int (*ast_adsi_print)(struct ast_channel *chan, char **lines, int *align, int voice);
/*! Check if scripts for a given app are already loaded. Version may be -1 */
/* if any version is okay, or 0-255 for a specific version. */
/*!
/*!
* \brief Check if scripts for a given app are already loaded.
* Version may be -1, if any version is okay, or 0-255 for a specific version.
* \param chan Channel to test for loaded app
* \param app Four character app name (must be unique to your application)
* \param ver optional version number
* \param data Non-zero if you want to be put in data mode
*
* Returns 0 if scripts is not loaded or not an ADSI CPE. Returns -1
* on hangup. Returns 1 if script already loaded.
* \retval 0 if scripts is not loaded or not an ADSI CPE
* \retval -1 on hangup
* \retval 1 if script already loaded.
*/
extern int (*ast_adsi_load_session)(struct ast_channel *chan, unsigned char *app, int ver, int data);
extern int (*ast_adsi_unload_session)(struct ast_channel *chan);
@ -172,35 +171,32 @@ extern int (*ast_adsi_unload_session)(struct ast_channel *chan);
extern int (*ast_adsi_transmit_messages)(struct ast_channel *chan, unsigned char **msg, int *msglen, int *msgtype);
extern int (*ast_adsi_transmit_message)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype);
extern int (*ast_adsi_transmit_message_full)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype, int dowait);
/*! Read some encoded DTMF data. */
/*!
/*! Read some encoded DTMF data.
* Returns number of bytes received
*/
extern int (*ast_adsi_read_encoded_dtmf)(struct ast_channel *chan, unsigned char *buf, int maxlen);
/* ADSI Layer 3 creation functions */
/*! Connects an ADSI Display Session */
/*!
/*!
* \brief Connects an ADSI Display Session
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param fdn Optional 4 byte Feature Download Number (for loading soft keys)
* \param ver Optional version number (0-255, or -1 to omit)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_connect_session)(unsigned char *buf, unsigned char *fdn, int ver);
/*! Build Query CPE ID of equipment */
/*!
/*! Build Query CPE ID of equipment.
* Returns number of bytes added to message
*/
extern int (*ast_adsi_query_cpeid)(unsigned char *buf);
extern int (*ast_adsi_query_cpeinfo)(unsigned char *buf);
/*! Get CPE ID from an attached ADSI compatible CPE. */
/*!
/*! Get CPE ID from an attached ADSI compatible CPE.
* Returns 1 on success, storing 4 bytes of CPE ID at buf
* or -1 on hangup, or 0 if there was no hangup but it failed to find the
* device ID. Returns to voice mode if "voice" is non-zero.
@ -209,68 +205,67 @@ extern int (*ast_adsi_get_cpeid)(struct ast_channel *chan, unsigned char *cpeid,
extern int (*ast_adsi_get_cpeinfo)(struct ast_channel *chan, int *width, int *height, int *buttons, int voice);
/*! Begin an ADSI script download */
/*!
/*!
* \brief Begin an ADSI script download
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param service a 1-18 byte name of the feature
* \param fdn 4 byte Feature Download Number (for loading soft keys)
* \param sec 4 byte vendor security code
* \param ver version number (0-255, or -1 to omit)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_download_connect)(unsigned char *buf, char *service, unsigned char *fdn, unsigned char *sec, int ver);
/*! Disconnects a running session */
/*!
/*!
* \brief Disconnects a running session.
* \param buf Character buffer to create parameter in (must have at least 256 free)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_disconnect_session)(unsigned char *buf);
/*! Disconnects (and hopefully saves) a downloaded script */
/*!
/*!
* \brief Disconnects (and hopefully saves) a downloaded script
* \param buf Character buffer to create parameter in (must have at least 256 free)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_download_disconnect)(unsigned char *buf);
/*! Puts CPE in data mode... */
/*!
/*!
* \brief Puts CPE in data mode.
* \param buf Character buffer to create parameter in (must have at least 256 free)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_data_mode)(unsigned char *buf);
extern int (*ast_adsi_clear_soft_keys)(unsigned char *buf);
extern int (*ast_adsi_clear_screen)(unsigned char *buf);
/*! Puts CPE in voice mode... */
/*!
/*!
* \brief Puts CPE in voice mode.
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param when (a time in seconds) to make the switch
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_voice_mode)(unsigned char *buf, int when);
/*! Returns non-zero if Channel does or might support ADSI */
/*!
/*!
* \brief Returns non-zero if Channel does or might support ADSI
* \param chan Channel to check
*
*/
extern int (*ast_adsi_available)(struct ast_channel *chan);
/*! Loads a line of info into the display */
/*!
/*!
* \brief Loads a line of info into the display.
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param page Page to load (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
* \param line Line number to load (1-4 for Comm page, 1-33 for info page)
@ -279,26 +274,26 @@ extern int (*ast_adsi_available)(struct ast_channel *chan);
* \param col1 Text to place in first column
* \param col2 Text to place in second column
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_display)(unsigned char *buf, int page, int line, int just, int wrap, char *col1, char *col2);
/*! Sets the current line and page */
/*!
/*!
* \brief Sets the current line and page.
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param page Which page (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
* \param line Line number (1-33 for info page, 1-4 for comm page)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_set_line)(unsigned char *buf, int page, int line);
/*! Creates "load soft key" parameters */
/*!
/*!
* \brief Creates "load soft key" parameters
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param key Key code from 2 to 33, for which key we are loading
* \param llabel Long label for key (1-18 bytes)
@ -306,24 +301,24 @@ extern int (*ast_adsi_set_line)(unsigned char *buf, int page, int line);
* \param ret Optional return sequence (NULL for none)
* \param data whether to put CPE in data mode before sending digits
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_load_soft_key)(unsigned char *buf, int key, const char *llabel, const char *slabel, char *ret, int data);
/*! Set which soft keys should be displayed */
/*!
/*!
* \brief Set which soft keys should be displayed
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param keys Array of 8 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
* But remember, the last two keys aren't real keys, they're for scrolling
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_set_keys)(unsigned char *buf, unsigned char *keys);
/*! Set input information */
/*!
/*!
* \brief Set input information
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param page Which page to input on (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
* \param line Line number to input on
@ -331,13 +326,13 @@ extern int (*ast_adsi_set_keys)(unsigned char *buf, unsigned char *keys);
* \param format Format number to use (0-7)
* \param just Justification (left, right center, indent)
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_input_control)(unsigned char *buf, int page, int line, int display, int format, int just);
/*! Set input format */
/*!
/*!
* \brief Set input format
* \param buf Character buffer to create parameter in (must have at least 256 free)
* \param num Which format we are setting
* \param dir Which direction (ADSI_DIR_FROM_LEFT or ADSI_DIR_FROM_RIGHT)
@ -345,8 +340,8 @@ extern int (*ast_adsi_input_control)(unsigned char *buf, int page, int line, int
* \param format1 Format for column 1
* \param format2 Format for column 2
*
* Returns number of bytes added to buffer or -1 on error.
*
* \retval number of bytes added to buffer
* \retval -1 on error.
*/
extern int (*ast_adsi_input_format)(unsigned char *buf, int num, int dir, int wrap, char *format1, char *format2);

118
include/asterisk/cdr.h
View File

@ -84,12 +84,12 @@ struct ast_cdr {
char accountcode[AST_MAX_ACCOUNT_CODE];
/*! flags */
unsigned int flags;
/* Unique Channel Identifier */
/*! Unique Channel Identifier */
char uniqueid[32];
/* User field */
/*! User field */
char userfield[AST_MAX_USER_FIELD];
/* A linked list for variables */
/*! A linked list for variables */
struct varshead varshead;
struct ast_cdr *next;
@ -106,134 +106,141 @@ typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
/*! \brief Return TRUE if CDR subsystem is enabled */
int check_cdr_enabled(void);
/*! \brief Allocate a CDR record
* Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
/*!
* \brief Allocate a CDR record
* \retval a malloc'd ast_cdr structure
* \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_alloc(void);
/*! \brief Duplicate a record
* Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
/*!
* \brief Duplicate a record
* \retval a malloc'd ast_cdr structure,
* \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
/*! \brief Free a CDR record
/*!
* \brief Free a CDR record
* \param cdr ast_cdr structure to free
* Returns nothing
*/
void ast_cdr_free(struct ast_cdr *cdr);
/*! \brief Discard and free a CDR record
/*!
* \brief Discard and free a CDR record
* \param cdr ast_cdr structure to free
* Returns nothing -- same as free, but no checks or complaints
*/
void ast_cdr_discard(struct ast_cdr *cdr);
/*! \brief Initialize based on a channel
/*!
* \brief Initialize based on a channel
* \param cdr Call Detail Record to use for channel
* \param chan Channel to bind CDR with
* Initializes a CDR and associates it with a particular channel
* Return is negligible. (returns 0 by default)
* \return 0 by default
*/
int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
/*! Initialize based on a channel */
/*!
* \brief Initialize based on a channel
* \param cdr Call Detail Record to use for channel
* \param chan Channel to bind CDR with
* Initializes a CDR and associates it with a particular channel
* Return is negligible. (returns 0 by default)
* \return 0 by default
*/
int ast_cdr_setcid(struct ast_cdr *cdr, struct ast_channel *chan);
/*! Register a CDR handling engine */
/*!
/*!
* \brief Register a CDR handling engine
* \param name name associated with the particular CDR handler
* \param desc description of the CDR handler
* \param be function pointer to a CDR handler
* Used to register a Call Detail Record handler.
* Returns -1 on error, 0 on success.
* \retval 0 on success.
* \retval -1 on error
*/
int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
/*! Unregister a CDR handling engine */
/*!
/*!
* \brief Unregister a CDR handling engine
* \param name name of CDR handler to unregister
* Unregisters a CDR by it's name
*/
void ast_cdr_unregister(const char *name);
/*! Start a call */
/*!
/*!
* \brief Start a call
* \param cdr the cdr you wish to associate with the call
* Starts all CDR stuff necessary for monitoring a call
* Returns nothing
*/
void ast_cdr_start(struct ast_cdr *cdr);
/*! Answer a call */
/*!
/*! \brief Answer a call
* \param cdr the cdr you wish to associate with the call
* Starts all CDR stuff necessary for doing CDR when answering a call
* NULL argument is just fine.
* \note NULL argument is just fine.
*/
void ast_cdr_answer(struct ast_cdr *cdr);
/*! A call wasn't answered */
/*!
/*!
* \brief A call wasn't answered
* \param cdr the cdr you wish to associate with the call
* Marks the channel disposition as "NO ANSWER"
*/
extern void ast_cdr_noanswer(struct ast_cdr *cdr);
/*! Busy a call */
/*!
/*!
* \brief Busy a call
* \param cdr the cdr you wish to associate with the call
* Returns nothing
*/
void ast_cdr_busy(struct ast_cdr *cdr);
/*! Fail a call */
/*!
/*!
* \brief Fail a call
* \param cdr the cdr you wish to associate with the call
* Returns nothing
*/
void ast_cdr_failed(struct ast_cdr *cdr);
/*! Save the result of the call based on the AST_CAUSE_* */
/*!
/*!
* \brief Save the result of the call based on the AST_CAUSE_*
* \param cdr the cdr you wish to associate with the call
* Returns nothing
* \param cause the AST_CAUSE_*
* Returns nothing
*/
int ast_cdr_disposition(struct ast_cdr *cdr, int cause);
/*! End a call */
/*!
/*!
* \brief End a call
* \param cdr the cdr you have associated the call with
* Registers the end of call time in the cdr structure.
* Returns nothing
*/
void ast_cdr_end(struct ast_cdr *cdr);
/*! Detaches the detail record for posting (and freeing) either now or at a
* later time in bulk with other records during batch mode operation */
/*!
* \brief Detaches the detail record for posting (and freeing) either now or at a
* later time in bulk with other records during batch mode operation.
* \param cdr Which CDR to detach from the channel thread
* Prevents the channel thread from blocking on the CDR handling
* Returns nothing
*/
void ast_cdr_detach(struct ast_cdr *cdr);
/*! Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines */
/*!
/*!
* \brief Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines
* \param shutdown Whether or not we are shutting down
* Blocks the asterisk shutdown procedures until the CDR data is submitted.
* Returns nothing
*/
void ast_cdr_submit_batch(int shutdown);
/*! Set the destination channel, if there was one */
/*!
/*!
* \brief Set the destination channel, if there was one
* \param cdr Which cdr it's applied to
* \param chan Channel to which dest will be
* Sets the destination channel the CDR is applied to
@ -241,8 +248,8 @@ void ast_cdr_submit_batch(int shutdown);
*/
void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
/*! Set the last executed application */
/*!
/*!
* \brief Set the last executed application
* \param cdr which cdr to act upon
* \param app the name of the app you wish to change it to
* \param data the data you want in the data field of app you set it to
@ -251,40 +258,41 @@ void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
*/
void ast_cdr_setapp(struct ast_cdr *cdr, char *app, char *data);
/*! Convert a string to a detail record AMA flag */
/*!
/*!
* \brief Convert a string to a detail record AMA flag
* \param flag string form of flag
* Converts the string form of the flag to the binary form.
* Returns the binary form of the flag
* \return the binary form of the flag
*/
int ast_cdr_amaflags2int(const char *flag);
/*! Disposition to a string */
/*!
/*!
* \brief Disposition to a string
* \param disposition input binary form
* Converts the binary form of a disposition to string form.
* Returns a pointer to the string form
* \return a pointer to the string form
*/
char *ast_cdr_disp2str(int disposition);
/*! Reset the detail record, optionally posting it first */
/*!
/*!
* \brief Reset the detail record, optionally posting it first
* \param cdr which cdr to act upon
* \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
* |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
*/
void ast_cdr_reset(struct ast_cdr *cdr, struct ast_flags *flags);
/*! Flags to a string */
/*!
/*!
* \brief Flags to a string
* \param flags binary flag
* Converts binary flags to string flags
* Returns string with flag name
*/
char *ast_cdr_flags2str(int flags);
/*! Move the non-null data from the "from" cdr to the "to" cdr
* \param to the cdr to get the goodies
/*!
* \brief Move the non-null data from the "from" cdr to the "to" cdr
* \param to the cdr to get the goodies
* \param from the cdr to give the goodies
*/
void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
@ -297,7 +305,7 @@ int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
/* Update CDR on a channel */
/*! Update CDR on a channel */
int ast_cdr_update(struct ast_channel *chan);

2
include/asterisk/channel.h
View File

@ -396,7 +396,7 @@ struct ast_channel {
AST_STRING_FIELD(uniqueid); /*!< Unique Channel Identifier */
);
/*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. See \ref AstFileDesc */
/*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. See \arg \ref AstFileDesc */
int fds[AST_MAX_FDS];
void *music_state; /*!< Music State*/

34
include/asterisk/cli.h
View File

@ -55,7 +55,7 @@ void ast_cli(int fd, const char *fmt, ...)
*/
#define ESS(x) ((x) == 1 ? "" : "s")
/*! \page CLI_command_api CLI command API
/*! \page CLI_command_API CLI command API
CLI commands are described by a struct ast_cli_entry that contains
all the components for their implementation.
@ -123,8 +123,8 @@ static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args
*/
/*! \brief calling arguments for new-style handlers
See \ref CLI_command_API
/*! \brief calling arguments for new-style handlers.
* \arg \ref CLI_command_API
*/
enum ast_cli_fn {
CLI_INIT = -2, /* return the usage string */
@ -147,8 +147,8 @@ struct ast_cli_entry;
typedef int (*old_cli_fn)(int fd, int argc, char *argv[]);
typedef char *(*new_cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
/*! \brief descriptor for a cli entry
See \ref CLI_command_API
/*! \brief descriptor for a cli entry.
* \arg \ref CLI_command_API
*/
struct ast_cli_entry {
char * const cmda[AST_MAX_CMD_LEN]; /*!< words making up the command.
@ -217,16 +217,20 @@ struct ast_cli_entry {
*/
char *ast_cli_complete(const char *word, char *const choices[], int pos);
/*! \brief Interprets a command
/*!
* \brief Interprets a command
* Interpret a command s, sending output to fd
* Returns 0 on succes, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_cli_command(int fd, const char *s);
/*! \brief Registers a command or an array of commands
/*!
* \brief Registers a command or an array of commands
* \param e which cli entry to register
* Register your own command
* Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_cli_register(struct ast_cli_entry *e);
@ -237,11 +241,11 @@ int ast_cli_register(struct ast_cli_entry *e);
*/
int ast_cli_register_multiple(struct ast_cli_entry *e, int len);
/*! \brief Unregisters a command or an array of commands
*
/*!
* \brief Unregisters a command or an array of commands
* \param e which cli entry to unregister
* Unregister your own command. You must pass a completed ast_cli_entry structure
* Returns 0.
* \return 0.
*/
int ast_cli_unregister(struct ast_cli_entry *e);
@ -252,9 +256,11 @@ int ast_cli_unregister(struct ast_cli_entry *e);
*/
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
/*! \brief Readline madness
/*!
* \brief Readline madness
* Useful for readline, that's about it
* Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
char *ast_cli_generator(const char *, const char *, int);

52
include/asterisk/config.h
View File

@ -70,7 +70,8 @@ struct ast_config_engine {
* \param filename path of file to open. If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
* Create a config structure from a given configuration file.
*
* Returns NULL on error, or an ast_config data structure on success
* \retval an ast_config data structure on success
* \retval NULL on error
*/
struct ast_config *ast_config_load(const char *filename);
struct ast_config *ast_config_load_with_comments(const char *filename);
@ -82,52 +83,62 @@ struct ast_config *ast_config_load_with_comments(const char *filename);
*/
void ast_config_destroy(struct ast_config *config);
/*! \brief Goes through categories
/*!
* \brief Goes through categories
* \param config Which config structure you wish to "browse"
* \param prev A pointer to a previous category.
* This funtion is kind of non-intuitive in it's use. To begin, one passes NULL as the second arguement. It will return a pointer to the string of the first category in the file. From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
*
* Returns a category on success, or NULL on failure/no-more-categories
* \retval a category on success
* \retval NULL on failure/no-more-categories
*/
char *ast_category_browse(struct ast_config *config, const char *prev);
/*! \brief Goes through variables
/*!
* \brief Goes through variables
* Somewhat similar in intent as the ast_category_browse.
* List variables of config file category
*
* Returns ast_variable list on success, or NULL on failure
* \retval ast_variable list on success
* \retval NULL on failure
*/
struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
/*! \brief Gets a variable
/*!
* \brief Gets a variable
* \param config which (opened) config to use
* \param category category under which the variable lies
* \param variable which variable you wish to get the data for
* Goes through a given config file in the given category and searches for the given variable
*
* Returns the variable value on success, or NULL if unable to find it.
* \retval The variable value on success
* \retval NULL if unable to find it.
*/
const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
/*! \brief Retrieve a category if it exists
/*!
* \brief Retrieve a category if it exists
* \param config which config to use
* \param category_name name of the category you're looking for
* This will search through the categories within a given config file for a match.
*
* Returns pointer to category if found, NULL if not.
* \retval pointer to category if found
* \retval NULL if not.
*/
struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
/*! \brief Check for category duplicates
/*!
* \brief Check for category duplicates
* \param config which config to use
* \param category_name name of the category you're looking for
* This will search through the categories within a given config file for a match.
*
* Return non-zero if found
* \return non-zero if found
*/
int ast_category_exist(const struct ast_config *config, const char *category_name);
/*! \brief Retrieve realtime configuration
/*!
* \brief Retrieve realtime configuration
* \param family which family/config to lookup
* This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Note
@ -137,7 +148,8 @@ int ast_category_exist(const struct ast_config *config, const char *category_nam
struct ast_variable *ast_load_realtime(const char *family, ...);
struct ast_variable *ast_load_realtime_all(const char *family, ...);
/*! \brief Retrieve realtime configuration
/*!
* \brief Retrieve realtime configuration
* \param family which family/config to lookup
* This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Unlike
@ -147,7 +159,8 @@ struct ast_variable *ast_load_realtime_all(const char *family, ...);
*/
struct ast_config *ast_load_realtime_multientry(const char *family, ...);
/*! \brief Update realtime configuration
/*!
* \brief Update realtime configuration
* \param family which family/config to be updated
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@ -156,14 +169,16 @@ struct ast_config *ast_load_realtime_multientry(const char *family, ...);
*/
int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
/*! \brief Create realtime configuration
/*!
* \brief Create realtime configuration
* \param family which family/config to be created
* This function is used to create a parameter in realtime configuration space.
*
*/
int ast_store_realtime(const char *family, ...);
/*! \brief Destroy realtime configuration
/*!
* \brief Destroy realtime configuration
* \param family which family/config to be destroyed
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@ -173,9 +188,10 @@ int ast_store_realtime(const char *family, ...);
*/
int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...);
/*! \brief Check if realtime engine is configured for family
* returns 1 if family is configured in realtime and engine exists
/*!
* \brief Check if realtime engine is configured for family
* \param family which family/config to be checked
* \return 1 if family is configured in realtime and engine exists
*/
int ast_check_realtime(const char *family);

34
include/asterisk/crypto.h
View File

@ -32,76 +32,90 @@ extern "C" {
struct ast_key;
/*! \brief Retrieve a key
/*!
* \brief Retrieve a key
* \param name of the key we are retrieving
* \param int type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE)
*
* Returns the key on success or NULL on failure
* \retval the key on success.
* \retval NULL on failure.
*/
struct ast_key *(*ast_key_get)(const char *key, int type);
/*! \brief Check the authenticity of a message signature using a given public key
/*!
* \brief Check the authenticity of a message signature using a given public key
* \param key a public key to use to verify
* \param msg the message that has been signed
* \param sig the proposed valid signature in mime64-like encoding
*
* Returns 0 if the signature is valid, or -1 otherwise
* \retval 0 if the signature is valid.
* \retval -1 otherwise.
*
*/
int (*ast_check_signature)(struct ast_key *key, const char *msg, const char *sig);
/*! \brief Check the authenticity of a message signature using a given public key
/*!
* \brief Check the authenticity of a message signature using a given public key
* \param key a public key to use to verify
* \param msg the message that has been signed
* \param sig the proposed valid signature in raw binary representation
*
* Returns 0 if the signature is valid, or -1 otherwise
* \retval 0 if the signature is valid.
* \retval -1 otherwise.
*
*/
int (*ast_check_signature_bin)(struct ast_key *key, const char *msg, int msglen, const unsigned char *sig);
/*!
* \brief Sign a message signature using a given private key
* \param key a private key to use to create the signature
* \param msg the message to sign
* \param sig a pointer to a buffer of at least 256 bytes in which the
* mime64-like encoded signature will be stored
*
* Returns 0 on success or -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*
*/
int (*ast_sign)(struct ast_key *key, char *msg, char *sig);
/*!
* \brief Sign a message signature using a given private key
* \param key a private key to use to create the signature
* \param msg the message to sign
* \param sig a pointer to a buffer of at least 128 bytes in which the
* raw encoded signature will be stored
*
* Returns 0 on success or -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*
*/
int (*ast_sign_bin)(struct ast_key *key, const char *msg, int msglen, unsigned char *sig);
/*!
* \brief Encrypt a message using a given private key
* \param key a private key to use to encrypt
* \param src the message to encrypt
* \param srclen the length of the message to encrypt
* \param dst a pointer to a buffer of at least srclen * 1.5 bytes in which the encrypted
* answer will be stored
*
* Returns length of encrypted data on success or -1 on failure.
* \retval length of encrypted data on success.
* \retval -1 on failure.
*
*/
int (*ast_encrypt_bin)(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key);
/*!
* \brief Decrypt a message using a given private key
* \param key a private key to use to decrypt
* \param src the message to decrypt
* \param srclen the length of the message to decrypt
* \param dst a pointer to a buffer of at least srclen bytes in which the decrypted
* answer will be stored
*
* Returns length of decrypted data on success or -1 on failure.
* \retval length of dencrypted data on success.
* \retval -1 on failure.
*
*/
int (*ast_decrypt_bin)(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key);

36
include/asterisk/devicestate.h
View File

@ -78,53 +78,63 @@ const char *ast_devstate_str(enum ast_device_state devstate);
*/
enum ast_device_state ast_devstate_val(const char *val);
/*! \brief Search the Channels by Name
/*!
* \brief Search the Channels by Name
* \param device like a dialstring
* Search the Device in active channels by compare the channelname against
* the devicename. Compared are only the first chars to the first '-' char.
* Returns an AST_DEVICE_UNKNOWN if no channel found or
* AST_DEVICE_INUSE if a channel is found
* \retval an AST_DEVICE_UNKNOWN if no channel found
* \retval AST_DEVICE_INUSE if a channel is found
*/
enum ast_device_state ast_parse_device_state(const char *device);
/*! \brief Asks a channel for device state
/*!
* \brief Asks a channel for device state
* \param device like a dialstring
* Asks a channel for device state, data is normaly a number from dialstring
* used by the low level module
* Trys the channel devicestate callback if not supported search in the
* active channels list for the device.
* Returns an AST_DEVICE_??? state -1 on failure
* \retval an AST_DEVICE_??? state
* \retval -1 on failure
*/
enum ast_device_state ast_device_state(const char *device);
/*! \brief Tells Asterisk the State for Device is changed
/*!
* \brief Tells Asterisk the State for Device is changed
* \param fmt devicename like a dialstring with format parameters
* Asterisk polls the new extensionstates and calls the registered
* callbacks for the changed extensions
* Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_device_state_changed(const char *fmt, ...)
__attribute__ ((format (printf, 1, 2)));
/*! \brief Tells Asterisk the State for Device is changed
/*!
* \brief Tells Asterisk the State for Device is changed
* \param device devicename like a dialstring
* Asterisk polls the new extensionstates and calls the registered
* callbacks for the changed extensions
* Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_device_state_changed_literal(const char *device);
/*! \brief Add device state provider
/*!
* \brief Add device state provider
* \param label to use in hint, like label:object
* \param callback Callback
* \retval -1 failure
* \retval 0 success
* \retval -1 failure
*/
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback);
/*! \brief Remove device state provider
/*!
* \brief Remove device state provider
* \param label to use in hint, like label:object
* Return -1 on failure, 0 on success
* \retval 0 on success
* \retval -1 on failure
*/
int ast_devstate_prov_del(const char *label);

8
include/asterisk/doxyref.h
View File

@ -500,19 +500,21 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
/*! \addtogroup cdr_drivers Module: CDR Drivers
* \section CDR_generic Asterisk CDR Drivers
* \brief CDR drivers are loaded dynamically (see \ref Config_mod "Modules Configuration"). Each loaded CDR driver produce a billing record for each call.
* \brief CDR drivers are loaded dynamically, each loaded CDR driver produce a billing record for each call.
* \arg \ref Config_mod "Modules Configuration"
* \arg \ref Config_cdr "CDR Configuration"
*/
/*! \addtogroup channel_drivers Module: Asterisk Channel Drivers
* \section channel_generic Asterisk Channel Drivers
* \brief Channel drivers are loaded dynamically (see \ref Config_mod "Modules Configuration").
* \brief Channel drivers are loaded dynamically.
* \arg \ref Config_mod "Modules Configuration"
*/
/*! \addtogroup applications Module: Dial plan applications
* \section app_generic Asterisk Dial Plan Applications
* \brief Applications support the dialplan. They register dynamically with \ref ast_register_application() and unregister with ast_unregister_application()
* \brief Applications support the dialplan. They register dynamically with \see ast_register_application() and unregister with \see ast_unregister_application()
* \par See also
* \arg \ref functions
*

11
include/asterisk/dundi.h
View File

@ -18,7 +18,7 @@
/*! \file
* \brief Distributed Universal Number Discovery (DUNDi)
* See also \ref AstDUNDi
* See also \arg \ref AstDUNDi
*/
#ifndef _ASTERISK_DUNDI_H
@ -213,8 +213,13 @@ struct dundi_entity_info {
char ipaddr[80];
};
/*! \brief Lookup the given number in the given dundi context (or e164 if unspecified) using the given callerid (if specified) and return up to maxret results in the array specified.
returns the number of results found or -1 on a hangup of teh channel. */
/*!
* \brief Lookup the given number in the given dundi context.
* Lookup number in a given dundi context (if unspecified use e164), the given callerid (if specified)
* and return up to maxret results in the array specified.
* \retval the number of results found.
* \retval -1 on a hangup of the channel.
*/
int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
/*! \brief Retrieve information on a specific EID */

5
include/asterisk/enum.h
View File

@ -52,7 +52,7 @@ struct enum_context {
};
/*! \brief Lookup entry in ENUM Returns 1 if found, 0 if not found, -1 on hangup
/*! \brief Lookup entry in ENUM
\param chan Channel
\param number E164 number with or without the leading +
\param location Number returned (or SIP uri)
@ -65,6 +65,9 @@ struct enum_context {
\param options Options ('c' to count number of NAPTR RR)
\param record The position of required RR in the answer list
\param argcontext Argument for caching results into an enum_context pointer (NULL is used for not caching)
\retval 1 if found
\retval 0 if not found
\retval -1 on hangup
*/
int ast_get_enum(struct ast_channel *chan, const char *number, char *location, int maxloc, char *technology,
int maxtech, char* suffix, char* options, unsigned int record, struct enum_context **argcontext);

227
include/asterisk/file.h
View File

@ -62,28 +62,32 @@ struct ast_format_lock {
* structure as an argument.
*/
struct ast_format {
char name[80]; /*! Name of format */
char exts[80]; /*! Extensions (separated by | if more than one)
char name[80]; /*!< Name of format */
char exts[80]; /*!< Extensions (separated by | if more than one)
this format can read. First is assumed for writing (e.g. .mp3) */
int format; /*! Format of frames it uses/provides (one only) */
/*! Prepare an input stream for playback. Return 0 on success, -1 on error.
int format; /*!< Format of frames it uses/provides (one only) */
/*!
* \brief Prepare an input stream for playback.
* \return 0 on success, -1 on error.
* The FILE is already open (in s->f) so this function only needs to perform
* any applicable validity checks on the file. If none is required, the
* function can be omitted.
*/
int (*open)(struct ast_filestream *s);
/*! Prepare a stream for output, and comment it appropriately if applicable.
* Return 0 on success, -1 on error. Same as the open, the FILE is already
* open so the function just needs to prepare any header and other fields,
* if any. The function can be omitted if nothing is needed.
/*!
* \brief Prepare a stream for output, and comment it appropriately if applicable.
* \return 0 on success, -1 on error.
* Same as the open, the FILE is already open so the function just needs to
* prepare any header and other fields, if any.
* The function can be omitted if nothing is needed.
*/
int (*rewrite)(struct ast_filestream *s, const char *comment);
/*! Write a frame to a channel */
int (*write)(struct ast_filestream *, struct ast_frame *);
/*! seek num samples into file, whence - like a normal seek but with offset in samples */
int (*seek)(struct ast_filestream *, off_t, int);
int (*trunc)(struct ast_filestream *fs); /*! trunc file to current position */
off_t (*tell)(struct ast_filestream *fs); /*! tell current position */
int (*trunc)(struct ast_filestream *fs); /*!< trunc file to current position */
off_t (*tell)(struct ast_filestream *fs); /*!< tell current position */
/*! Read the next frame from the filestream (if available) and report
* when to get next frame (in samples)
*/
@ -91,9 +95,9 @@ struct ast_format {
/*! Do any closing actions, if any. The descriptor and structure are closed
* and destroyed by the generic routines, so they must not be done here. */
void (*close)(struct ast_filestream *);
char * (*getcomment)(struct ast_filestream *); /*! Retrieve file comment */
char * (*getcomment)(struct ast_filestream *); /*!< Retrieve file comment */
AST_LIST_ENTRY(ast_format) list; /*! Link */
AST_LIST_ENTRY(ast_format) list; /*!< Link */
/*!
* If the handler needs a buffer (for read, typically)
@ -103,13 +107,13 @@ struct ast_format {
* When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET
* spare bytes at the bginning.
*/
int buf_size; /*! size of frame buffer, if any, aligned to 8 bytes. */
int desc_size; /*! size of private descriptor, if any */
int buf_size; /* size of frame buffer, if any, aligned to 8 bytes. */
int desc_size; /*!< size of private descriptor, if any */
struct ast_module *module;
};
/*
/*!
* This structure is allocated by file.c in one chunk,
* together with buf_size and desc_size bytes of memory
* to be used for private purposes (e.g. buffers etc.)
@ -137,77 +141,84 @@ struct ast_filestream {
#define SEEK_FORCECUR 10
/*! Register a new file format capability
/*!
* \brief Register a new file format capability.
* Adds a format to Asterisk's format abilities.
* returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int __ast_format_register(const struct ast_format *f, struct ast_module *mod);
#define ast_format_register(f) __ast_format_register(f, ast_module_info->self)
/*! Unregisters a file format */
/*!
/*!
* \brief Unregisters a file format
* \param name the name of the format you wish to unregister
* Unregisters a format based on the name of the format.
* Returns 0 on success, -1 on failure to unregister
* \retval 0 on success
* \retval -1 on failure to unregister
*/
int ast_format_unregister(const char *name);
/*! Streams a file */
/*!
/*!
* \brief Streams a file
* \param c channel to stream the file to
* \param filename the name of the file you wish to stream, minus the extension
* \param preflang the preferred language you wish to have the file streamed to you in
* Prepares a channel for the streaming of a file. To start the stream, afterward do a ast_waitstream() on the channel
* Also, it will stop any existing streams on the channel.
* Returns 0 on success, or -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_streamfile(struct ast_channel *c, const char *filename, const char *preflang);
/*
* if the file name is non-empty, try to play it.
* Return 0 if success, -1 if error, digit if interrupted by a digit.
* If digits == "" then we can simply check for non-zero.
/*!
* \brief stream file until digit
* If the file name is non-empty, try to play it.
* \note If digits == "" then we can simply check for non-zero.
* \return 0 if success.
* \retval -1 if error.
* \retval digit if interrupted by a digit.
*/
int ast_stream_and_wait(struct ast_channel *chan, const char *file, const char *digits);
/*! Stops a stream */
/*!
/*!
* \brief Stops a stream
* \param c The channel you wish to stop playback on
* Stop playback of a stream
* Returns 0 regardless
* \return 0 regardless
*/
int ast_stopstream(struct ast_channel *c);
/*! Checks for the existence of a given file */
/*!
/*!
* \brief Checks for the existence of a given file
* \param filename name of the file you wish to check, minus the extension
* \param fmt the format you wish to check (the extension)
* \param preflang (the preferred language you wisht to find the file in)
* See if a given file exists in a given format. If fmt is NULL, any format is accepted.
* Returns -1 if file does not exist, non-zero positive otherwise.
* \return -1 if file does not exist, non-zero positive otherwise.
*/
int ast_fileexists(const char *filename, const char *fmt, const char *preflang);
/*! Renames a file */
/*!
* \brief Renames a file
* \param oldname the name of the file you wish to act upon (minus the extension)
* \param newname the name you wish to rename the file to (minus the extension)
* \param fmt the format of the file
* Rename a given file in a given format, or if fmt is NULL, then do so for all
* Returns -1 on failure
* \return -1 on failure
*/
int ast_filerename(const char *oldname, const char *newname, const char *fmt);
/*! Deletes a file */
/*!
/*!
* \brief Deletes a file
* \param filename name of the file you wish to delete (minus the extension)
* \param fmt of the file
* Delete a given file in a given format, or if fmt is NULL, then do so for all
*/
int ast_filedelete(const char *filename, const char *fmt);
/*! Copies a file */
/*!
/*!
* \brief Copies a file
* \param oldname name of the file you wish to copy (minus extension)
* \param newname name you wish the file to be copied to (minus extension)
* \param fmt the format of the file
@ -215,36 +226,42 @@ int ast_filedelete(const char *filename, const char *fmt);
*/
int ast_filecopy(const char *oldname, const char *newname, const char *fmt);
/*! Waits for a stream to stop or digit to be pressed */
/*!
/*!
* \brief Waits for a stream to stop or digit to be pressed
* \param c channel to waitstream on
* \param breakon string of DTMF digits to break upon
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a given digit to arrive, Returns 0
* if the stream finishes, the character if it was interrupted, and -1 on error
* Wait for a stream to stop or for any one of a given digit to arrive,
* \retval 0 if the stream finishes
* \retval the character if it was interrupted,
* \retval -1 on error
*/
int ast_waitstream(struct ast_channel *c, const char *breakon);
/*! Waits for a stream to stop or digit matching a valid one digit exten to be pressed */
/*!
/*!
* \brief Waits for a stream to stop or digit matching a valid one digit exten to be pressed
* \param c channel to waitstream on
* \param context string of context to match digits to break upon
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a valid extension digit to arrive, Returns 0
* if the stream finishes, the character if it was interrupted, and -1 on error
* Wait for a stream to stop or for any one of a valid extension digit to arrive,
* \retval 0 if the stream finishes.
* \retval the character if it was interrupted.
* \retval -1 on error.
*/
int ast_waitstream_exten(struct ast_channel *c, const char *context);
/*! Same as waitstream but allows stream to be forwarded or rewound */
/*!
/*!
* \brief Same as waitstream but allows stream to be forwarded or rewound
* \param c channel to waitstream on
* \param breakon string of DTMF digits to break upon
* \param forward DTMF digit to fast forward upon
* \param rewind DTMF digit to rewind upon
* \param ms How many miliseconds to skip forward/back
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a given digit to arrive, Returns 0
* if the stream finishes, the character if it was interrupted, and -1 on error
* Wait for a stream to stop or for any one of a given digit to arrive,
* \retval 0 if the stream finishes.
* \retval the character if it was interrupted.
* \retval -1 on error.
*/
int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms);
@ -252,8 +269,8 @@ int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *fo
1 if monfd is ready for reading */
int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd);
/*! Starts reading from a file */
/*!
/*!
* \brief Starts reading from a file
* \param filename the name of the file to read from
* \param type format of file you wish to read from
* \param comment comment to go with
@ -264,12 +281,13 @@ int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd,
* if check is non-zero, then it will not read a file if there are any files that
* start with that name and have an extension
* Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution.
* Returns a struct ast_filestream on success, NULL on failure
* \retval a struct ast_filestream on success.
* \retval NULL on failure.
*/
struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
/*! Starts writing a file */
/*!
/*!
* \brief Starts writing a file
* \param filename the name of the file to write to
* \param type format of file you wish to write out to
* \param comment comment to go with
@ -280,119 +298,132 @@ struct ast_filestream *ast_readfile(const char *filename, const char *type, cons
* if check is non-zero, then it will not write a file if there are any files that
* start with that name and have an extension
* Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution.
* Returns a struct ast_filestream on success, NULL on failure
* \retval a struct ast_filestream on success.
* \retval NULL on failure.
*/
struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
/*! Writes a frame to a stream */
/*!
* \brief Writes a frame to a stream
* \param fs filestream to write to
* \param f frame to write to the filestream
* Send a frame to a filestream -- note: does NOT free the frame, call ast_frfree manually
* Returns 0 on success, -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_writestream(struct ast_filestream *fs, struct ast_frame *f);
/*! Closes a stream */
/*!
/*!
* \brief Closes a stream
* \param f filestream to close
* Close a playback or recording stream
* Returns 0 on success, -1 on failure
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_closestream(struct ast_filestream *f);
/*! Opens stream for use in seeking, playing */
/*!
/*!
* \brief Opens stream for use in seeking, playing
* \param chan channel to work with
* \param filename to use
* \param preflang prefered language to use
* Returns a ast_filestream pointer if it opens the file, NULL on error
* \retval a ast_filestream pointer if it opens the file.
* \retval NULL on error.
*/
struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang);
/*! Opens stream for use in seeking, playing */
/*!
/*!
* \brief Opens stream for use in seeking, playing
* \param chan channel to work with
* \param filename to use
* \param preflang prefered language to use
* \param asis if set, don't clear generators
* Returns a ast_filestream pointer if it opens the file, NULL on error
* \retval a ast_filestream pointer if it opens the file.
* \retval NULL on error.
*/
struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char *filename, const char *preflang, int asis);
/*! Opens stream for use in seeking, playing */
/*!
/*!
* \brief Opens stream for use in seeking, playing
* \param chan channel to work with
* \param filename to use
* \param preflang prefered language to use
* Returns a ast_filestream pointer if it opens the file, NULL on error
* \retval a ast_filestream pointer if it opens the file.
* \retval NULL on error.
*/
struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang);
/*! Applys a open stream to a channel. */
/*!
/*!
* \brief Applys a open stream to a channel.
* \param chan channel to work
* \param s ast_filestream to apply
* Returns 0 for success, -1 on failure
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_applystream(struct ast_channel *chan, struct ast_filestream *s);
/*! play a open stream on a channel. */
/*!
/*!
* \brief Play a open stream on a channel.
* \param s filestream to play
* Returns 0 for success, -1 on failure
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_playstream(struct ast_filestream *s);
/*! Seeks into stream */
/*!
/*!
* \brief Seeks into stream
* \param fs ast_filestream to perform seek on
* \param sample_offset numbers of samples to seek
* \param whence SEEK_SET, SEEK_CUR, SEEK_END
* Returns 0 for success, or -1 for error
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_seekstream(struct ast_filestream *fs, off_t sample_offset, int whence);
/*! Trunc stream at current location */
/*!
/*!
* \brief Trunc stream at current location
* \param fs filestream to act on
* Returns 0 for success, or -1 for error
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_truncstream(struct ast_filestream *fs);
/*! Fast forward stream ms */
/*!
/*!
* \brief Fast forward stream ms
* \param fs filestream to act on
* \param ms milliseconds to move
* Returns 0 for success, or -1 for error
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_stream_fastforward(struct ast_filestream *fs, off_t ms);
/*! Rewind stream ms */
/*!
/*!
* \brief Rewind stream ms
* \param fs filestream to act on
* \param ms milliseconds to move
* Returns 0 for success, or -1 for error
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_stream_rewind(struct ast_filestream *fs, off_t ms);
/*! Tell where we are in a stream */
/*!
/*!
* \brief Tell where we are in a stream
* \param fs fs to act on
* Returns a long as a sample offset into stream
* \return a long as a sample offset into stream
*/
off_t ast_tellstream(struct ast_filestream *fs);
/*! Read a frame from a filestream */
/*!
/*!
* \brief Read a frame from a filestream
* \param s ast_filestream to act on
* Returns a frame or NULL if read failed
* \return a frame.
* \retval NULL if read failed.
*/
struct ast_frame *ast_readframe(struct ast_filestream *s);
/*! Initialize file stuff */
/*!
/*!
* \brief Initialize file stuff
* Initializes all the various file stuff. Basically just registers the cli stuff
* Returns 0 all the time
* \return 0 all the time
*/
int ast_file_init(void);

10
include/asterisk/frame.h
View File

@ -508,10 +508,16 @@ void ast_frame_dump(const char *name, struct ast_frame *f, char *prefix);
can't be transcoded and we just have to pick whatever is supported
*/
/*! \brief Initialize an audio codec preference to "no preference" See \ref AudioCodecPref */
/*!
*\brief Initialize an audio codec preference to "no preference".
* \arg \ref AudioCodecPref
*/
void ast_codec_pref_init(struct ast_codec_pref *pref);
/*! \brief Codec located at a particular place in the preference index See \ref AudioCodecPref */
/*!
* \brief Codec located at a particular place in the preference index.
* \arg \ref AudioCodecPref
*/
int ast_codec_pref_index(struct ast_codec_pref *pref, int index);
/*! \brief Remove audio a codec from a preference list */

38
include/asterisk/image.h
View File

@ -43,53 +43,55 @@ struct ast_imager {
AST_LIST_ENTRY(ast_imager) list;
};
/*! Check for image support on a channel */
/*!
/*!
* \brief Check for image support on a channel
* \param chan channel to check
* Checks the channel to see if it supports the transmission of images
* Returns non-zero if image transmission is supported
* \return non-zero if image transmission is supported
*/
int ast_supports_images(struct ast_channel *chan);
/*! Sends an image */
/*!
/*!
* \brief Sends an image
* \param chan channel to send image on
* \param filename filename of image to send (minus extension)
* Sends an image on the given channel.
* Returns 0 on success, -1 on error
* \retval 0 on success
* \retval -1 on error
*/
int ast_send_image(struct ast_channel *chan, char *filename);
/*! Make an image */
/*!
/*!
* \brief Make an image
* \param filename filename of image to prepare
* \param preflang preferred language to get the image...?
* \param format the format of the file
* Make an image from a filename ??? No estoy positivo
* Returns an ast_frame on success, NULL on failure
* \retval an ast_frame on success
* \retval NULL on failure
*/
struct ast_frame *ast_read_image(char *filename, const char *preflang, int format);
/*! Register image format */
/*!
/*!
* \brief Register image format
* \param imgdrv Populated ast_imager structure with info to register
* Registers an image format
* Returns 0 regardless
* \return 0 regardless
*/
int ast_image_register(struct ast_imager *imgdrv);
/*! Unregister an image format */
/*!
/*!
* \brief Unregister an image format
* \param imgdrv pointer to the ast_imager structure you wish to unregister
* Unregisters the image format passed in
* Unregisters the image format passed in.
* Returns nothing
*/
void ast_image_unregister(struct ast_imager *imgdrv);
/*! Initialize image stuff */
/*!
/*!
* \brief Initialize image stuff
* Initializes all the various image stuff. Basically just registers the cli stuff
* Returns 0 all the time
* \return 0 all the time
*/
int ast_image_init(void);

55
include/asterisk/io.h
View File

@ -48,7 +48,7 @@ extern "C" {
/*! Invalid fd */
#define AST_IO_NVAL POLLNVAL
/*
/*!
* An Asterisk IO callback takes its id, a file descriptor, list of events, and
* callback data as arguments and returns 0 if it should not be
* run again, or non-zero if it should be run again.
@ -56,16 +56,16 @@ extern "C" {
struct io_context;
/*! Creates a context */
/*!
/*!
* \brief Creates a context
* Create a context for I/O operations
* Basically mallocs an IO structure and sets up some default values.
* Returns an allocated io_context structure
* \return an allocated io_context structure
*/
struct io_context *io_context_create(void);
/*! Destroys a context */
/*
/*!
* \brief Destroys a context
* \param ioc structure to destroy
* Destroy a context for I/O operations
* Frees all memory associated with the given io_context structure along with the structure itself
@ -75,53 +75,58 @@ void io_context_destroy(struct io_context *ioc);
typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
#define AST_IO_CB(a) ((ast_io_cb)(a))
/*! Adds an IO context */
/*!
/*!
* \brief Adds an IO context
* \param ioc which context to use
* \param fd which fd to monitor
* \param callback callback function to run
* \param events event mask of events to wait for
* \param data data to pass to the callback
* Watch for any of revents activites on fd, calling callback with data as
* callback data. Returns a pointer to ID of the IO event, or NULL on failure.
* callback data.
* \retval a pointer to ID of the IO event
* \retval NULL on failure
*/
int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
/*! Changes an IO handler */
/*!
/*!
* \brief Changes an IO handler
* \param ioc which context to use
* \param id
* \param fd the fd you wish it to contain now
* \param callback new callback function
* \param events event mask to wait for
* \param data data to pass to the callback function
* Change an i/o handler, updating fd if > -1, callback if non-null, and revents
* if >-1, and data if non-null. Returns a pointero to the ID of the IO event,
* or NULL on failure.
* Change an I/O handler, updating fd if > -1, callback if non-null,
* and revents if >-1, and data if non-null.
* \retval a pointer to the ID of the IO event
* \retval NULL on failure
*/
int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
/*! Removes an IO context */
/*!
/*!
* \brief Removes an IO context
* \param ioc which io_context to remove it from
* \param id which ID to remove
* Remove an I/O id from consideration Returns 0 on success or -1 on failure.
* Remove an I/O id from consideration
* \retval 0 on success
* \retval -1 on failure
*/
int ast_io_remove(struct io_context *ioc, int *id);
/*! Waits for IO */
/*!
/*!
* \brief Waits for IO
* \param ioc which context to act upon
* \param howlong how many milliseconds to wait
* Wait for I/O to happen, returning after
* howlong milliseconds, and after processing
* any necessary I/O. Returns the number of
* I/O events which took place.
* any necessary I/O.
* \return he number of I/O events which took place.
*/
int ast_io_wait(struct io_context *ioc, int howlong);
/*! Dumps the IO array */
/*
/*!
* \brief Dumps the IO array.
* Debugging: Dump everything in the I/O array
*/
void ast_io_dump(struct io_context *ioc);
@ -130,8 +135,8 @@ void ast_io_dump(struct io_context *ioc);
int ast_hide_password(int fd);
/*! Restores TTY mode */
/*
/*!
* \brief Restores TTY mode.
* Call with result from previous ast_hide_password
*/
int ast_restore_tty(int fd, int oldstatus);

2
include/asterisk/jabber.h
View File

@ -18,7 +18,7 @@
/*! \file
* \brief AJI - The Asterisk Jabber Interface
* \ref AJI_intro
* \arg \ref AJI_intro
* \ref res_jabber.c
* \author Matt O'Gorman <mogorman@digium.com>
* \extref IKSEMEL http://iksemel.jabberstudio.org

21
include/asterisk/linkedlists.h
View File

@ -33,7 +33,8 @@
This macro attempts to place an exclusive lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_LIST_LOCK(head) \
ast_mutex_lock(&(head)->lock)
@ -44,7 +45,8 @@
This macro attempts to place an exclusive write lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_RWLIST_WRLOCK(head) \
ast_rwlock_wrlock(&(head)->lock)
@ -55,7 +57,8 @@
This macro attempts to place a read lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_RWLIST_RDLOCK(head) \
ast_rwlock_rdlock(&(head)->lock)
@ -66,7 +69,8 @@
This macro attempts to place an exclusive lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_LIST_TRYLOCK(head) \
ast_mutex_trylock(&(head)->lock)
@ -77,7 +81,8 @@
This macro attempts to place an exclusive write lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_RWLIST_TRYWRLOCK(head) \
ast_rwlock_trywrlock(&(head)->lock)
@ -88,7 +93,8 @@
This macro attempts to place a read lock in the
list head structure pointed to by head.
Returns 0 on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure
*/
#define AST_RWLIST_TRYRDLOCK(head) \
ast_rwlock_tryrdlock(&(head)->lock)
@ -408,7 +414,8 @@ struct { \
\brief Checks whether the specified list contains any entries.
\param head This is a pointer to the list head structure
Returns non-zero if the list has entries, zero if not.
\return non-zero if the list has entries
\return zero if not.
*/
#define AST_LIST_EMPTY(head) (AST_LIST_FIRST(head) == NULL)

6
include/asterisk/manager.h
View File

@ -144,7 +144,8 @@ int ast_manager_unregister( char *action );
* \brief Verify a session's read permissions against a permission mask.
* \param ident session identity
* \param perm permission mask to verify
* \returns 1 if the session has the permission mask capabilities, otherwise 0
* \retval 1 if the session has the permission mask capabilities
* \retval 0 otherwise
*/
int astman_verify_session_readpermissions(unsigned long ident, int perm);
@ -152,7 +153,8 @@ int astman_verify_session_readpermissions(unsigned long ident, int perm);
* \brief Verify a session's write permissions against a permission mask.
* \param ident session identity
* \param perm permission mask to verify
* \returns 1 if the session has the permission mask capabilities, otherwise 0
* \retval 1 if the session has the permission mask capabilities, otherwise 0
* \retval 0 otherwise
*/
int astman_verify_session_writepermissions(unsigned long ident, int perm);

32
include/asterisk/module.h
View File

@ -86,7 +86,8 @@ enum ast_module_load_result ast_load_resource(const char *resource_name);
* specified. Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
* module regardless of consequences (NOT RECOMMENDED).
*
* \return Zero on success, -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
@ -116,7 +117,8 @@ int ast_update_module_list(int (*modentry)(const char *module, const char *descr
/*!
* \brief Check if module with the name given is loaded
* \param name Module name, like "chan_sip.so"
* \return 0 if false, 1 if true
* \retval 1 if true
* \retval 0 if false
*/
int ast_module_check(const char *name);
@ -127,7 +129,8 @@ int ast_module_check(const char *name);
* This function adds the given function to a linked list of functions to be
* run when the modules are updated.
*
* \return Zero on success and -1 on failure.
* \retval 0 on success
* \retval -1 on failure.
*/
int ast_loader_register(int (*updater)(void));
@ -137,7 +140,8 @@ int ast_loader_register(int (*updater)(void));
*
* This removes the given function from the updater list.
*
* \return Zero on success, -1 on failure.
* \retval 0 on success
* \retval -1 on failure.
*/
int ast_loader_unregister(int (*updater)(void));
@ -161,8 +165,8 @@ void ast_module_shutdown(void);
* otherwise. This function will only return modules that are reloadble
* if this is 1.
*
* \return A possible completion of the partial match, or NULL if no matches
* were found.
* \retval A possible completion of the partial match.
* \retval NULL if no matches were found.
*/
char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
@ -190,19 +194,19 @@ enum ast_module_flags {
struct ast_module_info {
/* The 'self' pointer for a module; it will be set by the loader before
/*! The 'self' pointer for a module; it will be set by the loader before
it calls the module's load_module() entrypoint, and used by various
other macros that need to identify the module.
*/
struct ast_module *self;
enum ast_module_load_result (*load)(void); /* register stuff etc. Optional. */
int (*reload)(void); /* config etc. Optional. */
int (*unload)(void); /* unload. called with the module locked */
int (*backup_globals)(void); /* for embedded modules, backup global data */
void (*restore_globals)(void); /* for embedded modules, restore global data */
const char *name; /* name of the module for loader reference and CLI commands */
const char *description; /* user friendly description of the module. */
enum ast_module_load_result (*load)(void); /*!< register stuff etc. Optional. */
int (*reload)(void); /*!< config etc. Optional. */
int (*unload)(void); /*!< unload. called with the module locked */
int (*backup_globals)(void); /*!< for embedded modules, backup global data */
void (*restore_globals)(void); /*!< for embedded modules, restore global data */
const char *name; /*!< name of the module for loader reference and CLI commands */
const char *description; /*!< user friendly description of the module. */
/*!
* This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of

4
include/asterisk/musiconhold.h
View File

@ -36,8 +36,8 @@ extern "C" {
* \param interpclass The class to use if the musicclass is not currently set on
* the channel structure or in the mclass argument.
*
* \retval 0 success
* \retval non-zero failure
* \retval Zero on success
* \retval non-zero on failure
*/
int ast_moh_start(struct ast_channel *chan, const char *mclass, const char *interpclass);

15
include/asterisk/pbx.h
View File

@ -228,9 +228,7 @@ void ast_context_destroy(struct ast_context *con, const char *registrar);
*/
struct ast_context *ast_context_find(const char *name);
/*! \brief The result codes when starting the PBX on a channel
with \ref ast_pbx_start()
/*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
*/
enum ast_pbx_result {
@ -244,10 +242,11 @@ enum ast_pbx_result {
*
* \param c channel to start the pbx on
*
* See ast_pbx_run for a synchronous function to run the PBX in the
* \see ast_pbx_run for a synchronous function to run the PBX in the
* current thread, as opposed to starting a new one.
*
* \return Zero on success, non-zero on failure
* \retval Zero on success
* \retval non-zero on failure
*/
enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
@ -261,7 +260,8 @@ enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
* See ast_pbx_start for an asynchronous function to run the PBX in a
* new thread as opposed to the current one.
*
* \return Zero on success, non-zero on failure
* \retval Zero on success
* \retval non-zero on failure
*/
enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
@ -419,7 +419,8 @@ int ast_exists_extension(struct ast_channel *c, const char *context, const char
* \param label label of the action within the extension to match to priority
* \param callerid callerid to search for
*
* \return the priority which matches the given label in the extension or -1 if not found.
* \retval the priority which matches the given label in the extension
* \retval -1 if not found.
*/
int ast_findlabel_extension(struct ast_channel *c, const char *context,
const char *exten, const char *label, const char *callerid);

28
include/asterisk/res_odbc.h
View File

@ -33,6 +33,7 @@
typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
/*! \brief ODBC container */
struct odbc_obj {
ast_mutex_t lock;
SQLHDBC con; /* ODBC Connection Handle */
@ -44,10 +45,12 @@ struct odbc_obj {
/* functions */
/*! \brief Executes a prepared statement handle
/*!
* \brief Executes a prepared statement handle
* \param obj The non-NULL result of odbc_request_obj()
* \param stmt The prepared statement handle
* \return Returns 0 on success or -1 on failure
* \retval 0 on success
* \retval -1 on failure
*
* This function was originally designed simply to execute a prepared
* statement handle and to retry if the initial execution failed.
@ -62,10 +65,12 @@ struct odbc_obj {
*/
int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt); /* DEPRECATED */
/*! \brief Retrieves a connected ODBC object
/*!
* \brief Retrieves a connected ODBC object
* \param name The name of the ODBC class for which a connection is needed.
* \param check Whether to ensure that a connection is valid before returning the handle. Usually unnecessary.
* \return Returns an ODBC object or NULL if there is no connection available with the requested name.
* \retval ODBC object
* \retval NULL if there is no connection available with the requested name.
*
* Connection classes may, in fact, contain multiple connection handles. If
* the connection is pooled, then each connection will be dedicated to the
@ -74,22 +79,27 @@ int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt); /* DEPRECATED *
*/
struct odbc_obj *ast_odbc_request_obj(const char *name, int check);
/*! \brief Releases an ODBC object previously allocated by odbc_request_obj()
/*!
* \brief Releases an ODBC object previously allocated by odbc_request_obj()
* \param obj The ODBC object
*/
void ast_odbc_release_obj(struct odbc_obj *obj);
/*! \brief Checks an ODBC object to ensure it is still connected
/*!
* \brief Checks an ODBC object to ensure it is still connected
* \param obj The ODBC object
* \return Returns 0 if connected, -1 otherwise.
* \retval 0 if connected
* \retval -1 otherwise.
*/
int ast_odbc_sanity_check(struct odbc_obj *obj);
/*! \brief Prepares, executes, and returns the resulting statement handle.
/*!
* \brief Prepares, executes, and returns the resulting statement handle.
* \param obj The ODBC object
* \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
* \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
* \return Returns a statement handle or NULL on error.
* \retval a statement handle
* \retval NULL on error
*/
SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);

28
include/asterisk/say.h
View File

@ -66,14 +66,17 @@ static int say_stub(struct ast_channel *chan, ...)
#define SAY_EXTERN extern
#endif
/* says a number
/*
* \brief says a number
* \param chan channel to say them number on
* \param num number to say on the channel
* \param ints which dtmf to interrupt on
* \param lang language to speak the number
* \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
* Vocally says a number on a given channel
* Returns 0 on success, DTMF digit on interrupt, -1 on failure
* \retval 0 on success
* \retval DTMF digit on interrupt
* \retval -1 on failure
*/
int ast_say_number(struct ast_channel *chan, int num,
const char *ints, const char *lang, const char *options);
@ -81,7 +84,8 @@ int ast_say_number(struct ast_channel *chan, int num,
/* Same as above with audiofd for received audio and returns 1 on ctrlfd being readable */
SAY_EXTERN int (* ast_say_number_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_number_full);
/* says an enumeration
/*
* \brief says an enumeration
* \param chan channel to say them enumeration on
* \param num number to say on the channel
* \param ints which dtmf to interrupt on
@ -89,20 +93,25 @@ SAY_EXTERN int (* ast_say_number_full)(struct ast_channel *chan, int num, const
* \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
* Vocally says a enumeration on a given channel (first, sencond, third, forth, thirtyfirst, hundredth, ....)
* especially useful for dates and messages. says 'last' if num equals to INT_MAX
* Returns 0 on success, DTMF digit on interrupt, -1 on failure
* \retval 0 on success
* \retval DTMF digit on interrupt
* \retval -1 on failure
*/
int ast_say_enumeration(struct ast_channel *chan, int num,
const char *ints, const char *lang, const char *options);
SAY_EXTERN int (* ast_say_enumeration_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_enumeration_full);
/* says digits
/*
* \brief says digits
* \param chan channel to act upon
* \param num number to speak
* \param ints which dtmf to interrupt on
* \param lang language to speak
* Vocally says digits of a given number
* Returns 0 on success, dtmf if interrupted, -1 on failure
* \retval 0 on success
* \retval DTMF if interrupted
* \retval -1 on failure
*/
int ast_say_digits(struct ast_channel *chan, int num,
const char *ints, const char *lang);
@ -110,13 +119,16 @@ int ast_say_digits(struct ast_channel *chan, int num,
int ast_say_digits_full(struct ast_channel *chan, int num,
const char *ints, const char *lang, int audiofd, int ctrlfd);
/* says digits of a string
/*
* \brief says digits of a string
* \param chan channel to act upon
* \param num string to speak
* \param ints which dtmf to interrupt on
* \param lang language to speak in
* Vocally says the digits of a given string
* Returns 0 on success, dtmf if interrupted, -1 on failure
* \retval 0 on succes
* \retval DTMF if interrupted
* \retval -1 on failure
*/
int ast_say_digit_str(struct ast_channel *chan, const char *num,
const char *ints, const char *lang);

28
include/asterisk/strings.h
View File

@ -186,7 +186,8 @@ void ast_copy_string(char *dst, const char *src, size_t size),
\arg buffer current position in buffer to place string into (will be updated on return)
\arg space remaining space in buffer (will be updated on return)
\arg fmt printf-style format string
\return 0 on success, non-zero on failure.
\retval 0 on success
\retval non-zero on failure.
*/
int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));
@ -204,21 +205,27 @@ int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attri
*/
int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list ap);
/*! Make sure something is true */
/*!
/*!
* \brief Make sure something is true.
* Determine if a string containing a boolean value is "true".
* This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
* This function checks to see whether a string passed to it is an indication of an "true" value.
* It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
*
* Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
* \retval 0 if val is a NULL pointer.
* \retval -1 if "true".
* \retval 0 otherwise.
*/
int ast_true(const char *val);
/*! Make sure something is false */
/*!
/*!
* \brief Make sure something is false.
* Determine if a string containing a boolean value is "false".
* This function checks to see whether a string passed to it is an indication of an "false" value. It checks to see if the string is "no", "false", "n", "f", "off" or "0".
* This function checks to see whether a string passed to it is an indication of an "false" value.
* It checks to see if the string is "no", "false", "n", "f", "off" or "0".
*
* Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
* \retval 0 if val is a NULL pointer.
* \retval -1 if "true".
* \retval 0 otherwise.
*/
int ast_false(const char *val);
@ -240,7 +247,8 @@ void ast_join(char *s, size_t len, char * const w[]);
\param dst Destination
\param _default Value to use if the string does not contain a valid time
\param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
\return zero on success, non-zero on failure
\retval 0 on success
\retval non-zero on failure.
*/
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);

25
include/asterisk/tdd.h
View File

@ -34,29 +34,35 @@ typedef struct tdd_state TDDSTATE;
*/
void tdd_init(void);
/*! Generates a CallerID FSK stream in ulaw format suitable for transmission.
/*!
* \brief Generates a CallerID FSK stream in ulaw format suitable for transmission.
* \param tdd tdd structure
* \param buf Buffer to use. This needs to be large enough to accomodate all the generated samples.
* \param string This is the string to send.
* This function creates a stream of TDD data in ulaw format. It returns the size
* (in bytes) of the data (if it returns a size of 0, there is probably an error)
* This function creates a stream of TDD data in ulaw format.
* \return The size (in bytes) of the data (if it returns a size of 0, there is probably an error)
*/
int tdd_generate(struct tdd_state *tdd, unsigned char *buf, const char *string);
/*! Create a TDD state machine
/*!
* \brief Create a TDD state machine.
* This function returns a malloc'd instance of the tdd_state data structure.
* Returns a pointer to a malloc'd tdd_state structure, or NULL on error.
* \retval a pointer to a malloc'd tdd_state structure
* \retval NULL on error.
*/
struct tdd_state *tdd_new(void);
/*! Read samples into the state machine, and return character (if any).
/*!
* \brief Read samples into the state machine, and return character (if any).
* \param tdd Which state machine to act upon
* \param ubuf containing your samples
* \param samples number of samples contained within the buffer.
*
* Send received audio to the TDD demodulator.
* Returns -1 on error, 0 for "needs more samples",
* and > 0 (the character) if reception of a character is complete.
*
* \retval -1 on error
* \retval 0 for "needs more samples"
* \retval > 0 (the character) if reception of a character is complete.
*/
int tdd_feed(struct tdd_state *tdd, unsigned char *ubuf, int samples);
@ -69,7 +75,8 @@ void tdd_free(struct tdd_state *tdd);
/*! Generate Echo Canceller disable tone (2100HZ)
* \param outbuf This is the buffer to receive the tone data
* \param len This is the length (in samples) of the tone data to generate
* Returns 0 if no error, and -1 if error.
* \retval 0 if no error
* \retval -1 if error.
*/
int ast_tdd_gen_ecdisa(unsigned char *outbuf, int len);

2
include/asterisk/translate.h
View File

@ -240,7 +240,7 @@ unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src);
* The result will include all formats from 'dest' that are either present
* in 'src' or translatable from a format present in 'src'.
*
* Note that only a single audio format and a single video format can be
* \note Only a single audio format and a single video format can be
* present in 'src', or the function will produce unexpected results.
*/
unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src);