[asterisk-commits] rmudgett: branch group/issue8824 r140165 - /team/group/issue8824/include/aste...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Aug 26 12:54:41 CDT 2008
Author: rmudgett
Date: Tue Aug 26 12:54:41 2008
New Revision: 140165
URL: http://svn.digium.com/view/asterisk?view=rev&rev=140165
Log:
* Updated/corrected some doxygen comments.
Modified:
team/group/issue8824/include/asterisk/channel.h
Modified: team/group/issue8824/include/asterisk/channel.h
URL: http://svn.digium.com/view/asterisk/team/group/issue8824/include/asterisk/channel.h?view=diff&rev=140165&r1=140164&r2=140165
==============================================================================
--- team/group/issue8824/include/asterisk/channel.h (original)
+++ team/group/issue8824/include/asterisk/channel.h Tue Aug 26 12:54:41 2008
@@ -28,7 +28,7 @@
A phone call through Asterisk consists of an incoming
connection and an outbound connection. Each call comes
in through a channel driver that supports one technology,
- like SIP, DAHDI, IAX2 etc.
+ like SIP, DAHDI, IAX2 etc.
\par
Each channel driver, technology, has it's own private
channel or dialog structure, that is technology-dependent.
@@ -38,13 +38,13 @@
\par Call scenario
This happens when an incoming call arrives to Asterisk
-# Call arrives on a channel driver interface
- -# Channel driver creates a PBX channel and starts a
+ -# Channel driver creates a PBX channel and starts a
pbx thread on the channel
-# The dial plan is executed
-# At this point at least two things can happen:
- -# The call is answered by Asterisk and
+ -# The call is answered by Asterisk and
Asterisk plays a media stream or reads media
- -# The dial plan forces Asterisk to create an outbound
+ -# The dial plan forces Asterisk to create an outbound
call somewhere with the dial (see \ref app_dial.c)
application
.
@@ -67,14 +67,14 @@
Asterisk in order to be able to provide a proper CDR record
for the call.
-
+
\par Masquerading channels
In some cases, a channel can masquerade itself into another
- channel. This happens frequently in call transfers, where
+ channel. This happens frequently in call transfers, where
a new channel takes over a channel that is already involved
in a call. The new channel sneaks in and takes over the bridge
and the old channel, now a zombie, is hung up.
-
+
\par Reference
\arg channel.c - generic functions
\arg channel.h - declarations of functions, flags and structures
@@ -86,11 +86,11 @@
*/
/*! \page Def_Bridge Asterisk Channel Bridges
- In Asterisk, there's several media bridges.
+ In Asterisk, there's several media bridges.
The Core bridge handles two channels (a "phone call") and bridge
them together.
-
+
The conference bridge (meetme) handles several channels simultaneously
with the support of an external timer (DAHDI timer). This is used
not only by the Conference application (meetme) but also by the
@@ -102,7 +102,7 @@
can create a native bridge without sending media through the
core.
- Native briding can be disabled by a number of reasons,
+ Native bridging can be disabled by a number of reasons,
like DTMF being needed by the core or codecs being incompatible
so a transcoding module is needed.
@@ -111,11 +111,11 @@
\li \see ast_channel_bridge()
\li \see app_meetme.c
\li \ref AstRTPbridge
- \li \see ast_rtp_bridge()
+ \li \see ast_rtp_bridge()
\li \ref Def_Channel
*/
-/*! \page AstFileDesc File descriptors
+/*! \page AstFileDesc File descriptors
Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
in the \ref ast_channel structure.
*/
@@ -173,7 +173,7 @@
typedef unsigned long long ast_group_t;
-/*! \todo Add an explanation of an Asterisk generator
+/*! \todo Add an explanation of an Asterisk generator
*/
struct ast_generator {
void *(*alloc)(struct ast_channel *chan, void *params);
@@ -191,16 +191,16 @@
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* Also, NULL and "" must be considered equivalent.
- *
+ *
* SIP and IAX2 has utf8 encoded Unicode caller ID names.
* In some cases, we also have an alternative (RPID) E.164 number that can be used
- * as caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to pstn gateway).
+ * as caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to PSTN gateway).
*
* \todo Implement settings for transliteration between UTF8 caller ID names in
* to Ascii Caller ID's (DAHDI). Östen Åsklund might be transliterated into
- * Osten Asklund or Oesten Aasklund depending upon language and person...
- * We need automatic routines for incoming calls and static settings for
- * our own accounts.
+ * Osten Asklund or Oesten Aasklund depending upon language and person...
+ * We need automatic routines for incoming calls and static settings for
+ * our own accounts.
*/
struct ast_callerid {
char *cid_dnid; /*!< Malloc'd Dialed Number Identifier */
@@ -214,7 +214,7 @@
int cid_tns; /*!< Callerid Transit Network Select */
};
-/* \brief Structure for all kinds of connected line indentifications.
+/*! \brief Structure for all kinds of connected line indentifications.
* \note All string fields here are malloc'ed, so they need to be
* freed when the structure is deleted.
* Also, NULL and "" must be considered equivalent.
@@ -231,18 +231,19 @@
int lid_tns; /*!< Line Transit Network Select */
};
-/*! \brief
- Structure to describe a channel "technology", ie a channel driver
- See for examples:
- \arg chan_iax2.c - The Inter-Asterisk exchange protocol
- \arg chan_sip.c - The SIP channel driver
- \arg chan_dahdi.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
-
- If you develop your own channel driver, this is where you
- tell the PBX at registration of your driver what properties
- this driver supports and where different callbacks are
- implemented.
-*/
+/*! \brief
+ * Structure to describe a channel "technology", ie a channel driver
+ * See for examples:
+ * \arg chan_iax2.c - The Inter-Asterisk exchange protocol
+ * \arg chan_sip.c - The SIP channel driver
+ * \arg chan_dahdi.c - PSTN connectivity (TDM, PRI, T1/E1, FXO, FXS)
+ *
+ * \details
+ * If you develop your own channel driver, this is where you
+ * tell the PBX at registration of your driver what properties
+ * this driver supports and where different callbacks are
+ * implemented.
+ */
struct ast_channel_tech {
const char * const type;
const char * const description;
@@ -256,22 +257,22 @@
int (* const devicestate)(void *data); /*!< Devicestate call back */
- /*!
- * \brief Start sending a literal DTMF digit
+ /*!
+ * \brief Start sending a literal DTMF digit
*
- * \note The channel is not locked when this function gets called.
+ * \note The channel is not locked when this function gets called.
*/
int (* const send_digit_begin)(struct ast_channel *chan, char digit);
- /*!
- * \brief Stop sending a literal DTMF digit
+ /*!
+ * \brief Stop sending a literal DTMF digit
*
- * \note The channel is not locked when this function gets called.
+ * \note The channel is not locked when this function gets called.
*/
int (* const send_digit_end)(struct ast_channel *chan, char digit, unsigned int duration);
/*! \brief Call a given phone number (address, etc), but don't
- take longer than timeout seconds to do so. */
+ * take longer than timeout seconds to do so. */
int (* const call)(struct ast_channel *chan, char *addr, int timeout);
/*! \brief Hangup (and possibly destroy) the channel */
@@ -337,7 +338,7 @@
/*! \brief Retrieve base channel (agent and local) */
struct ast_channel* (* get_base_channel)(struct ast_channel *chan);
-
+
/*! \brief Set base channel (agent and local) */
int (* set_base_channel)(struct ast_channel *chan, struct ast_channel *base);
@@ -370,7 +371,7 @@
AST_ADSI_OFFHOOKONLY,
};
-/*!
+/*!
* \brief ast_channel states
*
* \note Bits 0-15 of state are reserved for the state (up/down) of the line
@@ -402,7 +403,8 @@
T38_STATE_NEGOTIATED, /*!< T38 established */
};
-/*! \brief Main Channel structure associated with a channel.
+/*!
+ * \brief Main Channel structure associated with a channel.
* This is the side of it mostly used by the pbx and call management.
*
* \note XXX It is important to remember to increment .cleancount each time
@@ -416,7 +418,6 @@
* and 8-byte fields causes 4 bytes of padding to be added before many
* 8-byte fields.
*/
-
struct ast_channel {
const struct ast_channel_tech *tech; /*!< Technology (point to channel driver) */
void *tech_pvt; /*!< Private data used by the technology driver */
@@ -424,8 +425,8 @@
void *generatordata; /*!< Current generator data if there is any */
struct ast_generator *generator; /*!< Current active data generator */
struct ast_channel *_bridge; /*!< Who are we bridged to, if we're bridged.
- Who is proxying for us, if we are proxied (i.e. chan_agent).
- Do not access directly, use ast_bridged_channel(chan) */
+ * Who is proxying for us, if we are proxied (i.e. chan_agent).
+ * Do not access directly, use ast_bridged_channel(chan) */
struct ast_channel *masq; /*!< Channel that will masquerade as us */
struct ast_channel *masqr; /*!< Who we are masquerading as */
const char *blockproc; /*!< Procedure causing blocking */
@@ -442,7 +443,7 @@
struct ast_audiohook_list *audiohooks;
struct ast_cdr *cdr; /*!< Call Detail Record */
struct ind_tone_zone *zone; /*!< Tone zone as set in indications.conf or
- in the CHANNEL dialplan function */
+ * in the CHANNEL dialplan function */
struct ast_channel_monitor *monitor; /*!< Channel monitoring */
#ifdef HAVE_EPOLL
struct ast_epoll_data *epfd_data[AST_MAX_FDS];
@@ -458,7 +459,7 @@
AST_STRING_FIELD(parkinglot); /*! Default parking lot, if empty, default parking lot */
AST_STRING_FIELD(dialcontext); /*!< Dial: Extension context that we were called from */
);
-
+
struct timeval whentohangup; /*!< Non-zero, set to actual time when channel is to be hung up */
pthread_t blocker; /*!< If anyone is blocking, this is them */
ast_mutex_t lock_dont_use; /*!< Lock a channel for some operations. See ast_channel_lock() */
@@ -478,11 +479,11 @@
unsigned long outsmpl; /*!< Track the read/written samples for monitor use */
int fds[AST_MAX_FDS]; /*!< File descriptors for channel -- Drivers will poll on
- these file descriptors, so at least one must be non -1.
- See \arg \ref AstFileDesc */
+ * these file descriptors, so at least one must be non -1.
+ * See \arg \ref AstFileDesc */
int cdrflags; /*!< Call Detail Record Flags */
int _softhangup; /*!< Whether or not we have been hung up... Do not set this value
- directly, use ast_softhangup() */
+ * directly, use ast_softhangup() */
int fdno; /*!< Which fd had an event detected on */
int streamid; /*!< For streaming playback, the schedule ID */
int vstreamid; /*!< For streaming video playback, the schedule ID */
@@ -495,9 +496,9 @@
int amaflags; /*!< Set BEFORE PBX is started to determine AMA flags */
enum ast_channel_adsicpe adsicpe; /*!< Whether or not ADSI is detected on CPE */
unsigned int fin; /*!< Frames in counters. The high bit is a debug mask, so
- the counter is only in the remaining bits */
+ * the counter is only in the remaining bits */
unsigned int fout; /*!< Frames out counters. The high bit is a debug mask, so
- the counter is only in the remaining bits */
+ * the counter is only in the remaining bits */
int hangupcause; /*!< Why is the channel hanged up. See causes.h */
unsigned int flags; /*!< channel flags of AST_FLAG_ type */
int alertpipe[2];
@@ -512,7 +513,7 @@
#endif
int visible_indication; /*!< Indication currently playing on the channel */
- unsigned short transfercapability; /*!< ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
+ unsigned short transfercapability; /*!< ISDN Transfer Capability - AST_FLAG_DIGITAL is not enough */
char dtmfq[AST_MAX_EXTENSION]; /*!< Any/all queued DTMF characters */
char context[AST_MAX_CONTEXT]; /*!< Dialplan: Current extension context */
@@ -524,17 +525,17 @@
/*! \brief ast_channel_tech Properties */
enum {
- /*! \brief Channels have this property if they can accept input with jitter;
+ /*! \brief Channels have this property if they can accept input with jitter;
* i.e. most VoIP channels */
AST_CHAN_TP_WANTSJITTER = (1 << 0),
- /*! \brief Channels have this property if they can create jitter;
+ /*! \brief Channels have this property if they can create jitter;
* i.e. most VoIP channels */
AST_CHAN_TP_CREATESJITTER = (1 << 1),
};
/*! \brief ast_channel flags */
enum {
- /*! Queue incoming dtmf, to be released when this flag is turned off */
+ /*! Queue incoming DTMF, to be released when this flag is turned off */
AST_FLAG_DEFER_DTMF = (1 << 1),
/*! write should be interrupt generator */
AST_FLAG_WRITE_INT = (1 << 2),
@@ -558,14 +559,14 @@
AST_FLAG_OUTGOING = (1 << 10),
/*! A DTMF_BEGIN frame has been read from this channel, but not yet an END */
AST_FLAG_IN_DTMF = (1 << 12),
- /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
+ /*! A DTMF_END was received when not IN_DTMF, so the length of the digit is
* currently being emulated */
AST_FLAG_EMULATE_DTMF = (1 << 13),
/*! This is set to tell the channel not to generate DTMF begin frames, and
* to instead only generate END frames. */
AST_FLAG_END_DTMF_ONLY = (1 << 14),
/*! Flag to show channels that this call is hangup due to the fact that the call
- was indeed anwered, but in another channel */
+ was indeed answered, but in another channel */
AST_FLAG_ANSWERED_ELSEWHERE = (1 << 15),
/*! This flag indicates that on a masquerade, an active stream should not
* be carried over */
@@ -640,13 +641,13 @@
CHANNEL_MANAGER_RELOAD,
};
-/*!
+/*!
* \note None of the datastore API calls lock the ast_channel they are using.
* So, the channel should be locked before calling the functions that
* take a channel argument.
*/
-/*!
+/*!
* \brief Create a channel data store object
* \deprecated You should use the ast_datastore_alloc() generic function instead.
*/
@@ -663,19 +664,18 @@
/*! \brief Inherit datastores from a parent to a child. */
int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *to);
-/*!
- * \brief Add a datastore to a channel
+/*!
+ * \brief Add a datastore to a channel
*
* \note The channel should be locked before calling this function.
*
* \retval 0 success
* \retval non-zero failure
*/
-
int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore);
-/*!
- * \brief Remove a datastore from a channel
+/*!
+ * \brief Remove a datastore from a channel
*
* \note The channel should be locked before calling this function.
*
@@ -684,8 +684,8 @@
*/
int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore);
-/*!
- * \brief Find a datastore on a channel
+/*!
+ * \brief Find a datastore on a channel
*
* \note The channel should be locked before calling this function.
*
@@ -700,8 +700,8 @@
/*! \brief Change the state of a channel */
int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
-/*!
- * \brief Create a channel structure
+/*!
+ * \brief Create a channel structure
*
* \retval NULL failure
* \retval non-NULL successfully allocated channel
@@ -711,21 +711,21 @@
*/
struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...);
-/*!
- * \brief Queue an outgoing frame
+/*!
+ * \brief Queue an outgoing frame
*
* \note The channel does not need to be locked before calling this function.
*/
int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
-/*!
- * \brief Queue a hangup frame
+/*!
+ * \brief Queue a hangup frame
*
* \note The channel does not need to be locked before calling this function.
*/
int ast_queue_hangup(struct ast_channel *chan);
-/*!
+/*!
* \brief Queue a hangup frame with hangupcause set
*
* \note The channel does not need to be locked before calling this function.
@@ -758,6 +758,7 @@
* \retval 0 success
* \retval non-zero failure
*
+ * \details
* The supplied payload data is copied into the frame, so the caller's copy
* is not modified nor freed, and the resulting frame will retain a copy of
* the data even if the caller frees their local copy.
@@ -774,8 +775,8 @@
int ast_queue_control_data(struct ast_channel *chan, enum ast_control_frame_type control,
const void *data, size_t datalen);
-/*!
- * \brief Change channel name
+/*!
+ * \brief Change channel name
*
* \note The channel must be locked before calling this function.
*/
@@ -784,15 +785,16 @@
/*! \brief Free a channel structure */
void ast_channel_free(struct ast_channel *);
-/*!
- * \brief Requests a channel
+/*!
+ * \brief Requests a channel
*
* \param type type of channel to request
* \param format requested channel format (codec)
* \param data data to pass to the channel requester
* \param status status
*
- * Request a channel of a given type, with data as optional information used
+ * \details
+ * Request a channel of a given type, with data as optional information used
* by the low level module
*
* \retval NULL failure
@@ -801,7 +803,7 @@
struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
/*!
- * \brief Request a channel of a given type, with data as optional information used
+ * \brief Request a channel of a given type, with data as optional information used
* by the low level module and attempt to place a call on it
*
* \param type type of channel to request
@@ -819,7 +821,7 @@
int timeout, int *reason, const char *cid_num, const char *cid_name);
/*!
- * \brief Request a channel of a given type, with data as optional information used
+ * \brief Request a channel of a given type, with data as optional information used
* by the low level module and attempt to place a call on it
* \param type type of channel to request
* \param format requested channel format
@@ -835,14 +837,14 @@
struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data,
int timeout, int *reason, const char *cid_num, const char *cid_name, struct outgoing_helper *oh);
-/*!\brief Register a channel technology (a new channel driver)
+/*! \brief Register a channel technology (a new channel driver)
* Called by a channel module to register the kind of channels it supports.
* \param tech Structure defining channel technology or "type"
* \return Returns 0 on success, -1 on failure.
*/
int ast_channel_register(const struct ast_channel_tech *tech);
-/*! \brief Unregister a channel technology
+/*! \brief Unregister a channel technology
* \param tech Structure defining channel technology or "type" that was previously registered
* \return No return value.
*/
@@ -882,7 +884,7 @@
int ast_channel_trace_serialize(struct ast_channel *chan, struct ast_str **out);
#endif
-/*! \brief Hang up a channel
+/*! \brief Hang up a channel
* \note This function performs a hard hangup on a channel. Unlike the soft-hangup, this function
* performs all stream stopping, etc, on the channel that needs to end.
* chan is no longer valid after this call.
@@ -891,13 +893,14 @@
*/
int ast_hangup(struct ast_channel *chan);
-/*!
- * \brief Softly hangup up a channel
+/*!
+ * \brief Softly hangup up a channel
*
* \param chan channel to be soft-hung-up
* \param cause Ast hangupcause for hangup
*
- * Call the protocol layer, but don't destroy the channel structure
+ * \details
+ * Call the protocol layer, but don't destroy the channel structure
* (use this if you are trying to
* safely hangup a channel managed by another thread.
*
@@ -907,23 +910,24 @@
*/
int ast_softhangup(struct ast_channel *chan, int cause);
-/*! \brief Softly hangup up a channel (no channel lock)
+/*! \brief Softly hangup up a channel (no channel lock)
* \param chan channel to be soft-hung-up
* \param cause Ast hangupcause for hangup (see cause.h) */
int ast_softhangup_nolock(struct ast_channel *chan, int cause);
-/*! \brief Check to see if a channel is needing hang up
+/*! \brief Check to see if a channel is needing hang up
* \param chan channel on which to check for hang up
* This function determines if the channel is being requested to be hung up.
* \return Returns 0 if not, or 1 if hang up is requested (including time-out).
*/
int ast_check_hangup(struct ast_channel *chan);
-/*! \brief Compare a offset with the settings of when to hang a channel up
+/*! \brief Compare a offset with the settings of when to hang a channel up
* \param chan channel on which to check for hang up
* \param offset offset in seconds and useconds from current time
* \return 1, 0, or -1
- * This function compares a offset from current time with the absolute time
+ * \details
+ * This function compares a offset from current time with the absolute time
* out on a channel (when to hang up). If the absolute time out on a channel
* is earlier than current time plus the offset, it returns 1, if the two
* time values are equal, it return 0, otherwise, it return -1.
@@ -931,11 +935,12 @@
int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset) __attribute__ ((deprecated));
int ast_channel_cmpwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
-/*! \brief Set when to hang a channel up
+/*! \brief Set when to hang a channel up
*
* \param chan channel on which to check for hang up
* \param offset offset in seconds and useconds relative to the current time of when to hang up
*
+ * \details
* This function sets the absolute time out on a channel (when to hang up).
*
* \note This function does not require that the channel is locked before
@@ -946,11 +951,12 @@
void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset) __attribute__ ((deprecated));
void ast_channel_setwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
-/*!
+/*!
* \brief Answer a channel
- *
+ *
* \param chan channel to answer
*
+ * \details
* This function answers a channel and handles all necessary call
* setup functions.
*
@@ -962,18 +968,19 @@
int ast_answer(struct ast_channel *chan);
int __ast_answer(struct ast_channel *chan, unsigned int delay);
-/*! \brief Make a call
+/*! \brief Make a call
* \param chan which channel to make the call on
* \param addr destination of the call
* \param timeout time to wait on for connect
- * Place a call, take no longer than timeout ms.
- \return Returns -1 on failure, 0 on not enough time
- (does not automatically stop ringing), and
- the number of seconds the connect took otherwise.
- */
+ * \details
+ * Place a call, take no longer than timeout ms.
+ * \return -1 on failure, 0 on not enough time
+ * (does not automatically stop ringing), and
+ * the number of seconds the connect took otherwise.
+ */
int ast_call(struct ast_channel *chan, char *addr, int timeout);
-/*! \brief Indicates condition of channel
+/*! \brief Indicates condition of channel
* \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
* \param chan channel to change the indication
* \param condition which condition to indicate on the channel
@@ -993,33 +1000,37 @@
/* Misc stuff ------------------------------------------------ */
-/*! \brief Wait for input on a channel
+/*! \brief Wait for input on a channel
* \param chan channel to wait on
* \param ms length of time to wait on the channel
- * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
- \return Returns < 0 on failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
+ * \details
+ * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
+ * \return Returns < 0 on failure, 0 if nothing ever arrived, and the # of ms remaining otherwise
+ */
int ast_waitfor(struct ast_channel *chan, int ms);
-/*! \brief Wait for a specified amount of time, looking for hangups
+/*! \brief Wait for a specified amount of time, looking for hangups
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
+ * \details
* Waits for a specified amount of time, servicing the channel as required.
* \return returns -1 on hangup, otherwise 0.
*/
int ast_safe_sleep(struct ast_channel *chan, int ms);
-/*! \brief Wait for a specified amount of time, looking for hangups and a condition argument
+/*! \brief Wait for a specified amount of time, looking for hangups and a condition argument
* \param chan channel to wait for
* \param ms length of time in milliseconds to sleep
* \param cond a function pointer for testing continue condition
* \param data argument to be passed to the condition test function
* \return returns -1 on hangup, otherwise 0.
+ * \details
* Waits for a specified amount of time, servicing the channel as required. If cond
* returns 0, this function returns.
*/
int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
-/*! \brief Waits for activity on a group of channels
+/*! \brief Waits for activity on a group of channels
* \param chan an array of pointers to channels
* \param n number of channels that are to be waited upon
* \param fds an array of fds to wait upon
@@ -1027,44 +1038,50 @@
* \param exception exception flag
* \param outfd fd that had activity on it
* \param ms how long the wait was
+ * \details
* Big momma function here. Wait for activity on any of the n channels, or any of the nfds
- file descriptors.
- \return Returns the channel with activity, or NULL on error or if an FD
- came first. If the FD came first, it will be returned in outfd, otherwise, outfd
- will be -1 */
+ * file descriptors.
+ * \return Returns the channel with activity, or NULL on error or if an FD
+ * came first. If the FD came first, it will be returned in outfd, otherwise, outfd
+ * will be -1
+ */
struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n,
int *fds, int nfds, int *exception, int *outfd, int *ms);
/*! \brief Waits for input on a group of channels
- Wait for input on an array of channels for a given # of milliseconds.
- \return Return channel with activity, or NULL if none has activity.
- \param chan an array of pointers to channels
- \param n number of channels that are to be waited upon
- \param ms time "ms" is modified in-place, if applicable */
+ * Wait for input on an array of channels for a given # of milliseconds.
+ * \return Return channel with activity, or NULL if none has activity.
+ * \param chan an array of pointers to channels
+ * \param n number of channels that are to be waited upon
+ * \param ms time "ms" is modified in-place, if applicable
+ */
struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
/*! \brief Waits for input on an fd
- This version works on fd's only. Be careful with it. */
+ * This version works on fd's only. Be careful with it.
+ */
int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
/*! \brief Reads a frame
* \param chan channel to read a frame from
* \return Returns a frame, or NULL on error. If it returns NULL, you
- best just stop reading frames and assume the channel has been
- disconnected. */
+ * best just stop reading frames and assume the channel has been
+ * disconnected.
+ */
struct ast_frame *ast_read(struct ast_channel *chan);
-/*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
- \param chan channel to read a frame from
- \return Returns a frame, or NULL on error. If it returns NULL, you
- best just stop reading frames and assume the channel has been
- disconnected.
- \note Audio is replaced with AST_FRAME_NULL to avoid
- transcode when the resulting audio is not necessary. */
+/*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
+ * \param chan channel to read a frame from
+ * \return Returns a frame, or NULL on error. If it returns NULL, you
+ * best just stop reading frames and assume the channel has been
+ * disconnected.
+ * \note Audio is replaced with AST_FRAME_NULL to avoid
+ * transcode when the resulting audio is not necessary.
+ */
struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
-/*! \brief Write a frame to a channel
+/*! \brief Write a frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1072,7 +1089,7 @@
*/
int ast_write(struct ast_channel *chan, struct ast_frame *frame);
-/*! \brief Write video frame to a channel
+/*! \brief Write video frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1080,7 +1097,7 @@
*/
int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
-/*! \brief Write text frame to a channel
+/*! \brief Write text frame to a channel
* This function writes the given frame to the indicated channel.
* \param chan destination channel of the frame
* \param frame frame that will be written
@@ -1092,7 +1109,7 @@
int ast_prod(struct ast_channel *chan);
/*! \brief Sets read format on channel chan
- * Set read format for channel to whichever component of "format" is best.
+ * Set read format for channel to whichever component of "format" is best.
* \param chan channel to change
* \param format format to change to
* \return Returns 0 on success, -1 on failure
@@ -1100,24 +1117,25 @@
int ast_set_read_format(struct ast_channel *chan, int format);
/*! \brief Sets write format on channel chan
- * Set write format for channel to whichever component of "format" is best.
+ * Set write format for channel to whichever component of "format" is best.
* \param chan channel to change
* \param format new format for writing
* \return Returns 0 on success, -1 on failure
*/
int ast_set_write_format(struct ast_channel *chan, int format);
-/*!
- * \brief Sends text to a channel
+/*!
+ * \brief Sends text to a channel
*
* \param chan channel to act upon
* \param text string of text to send on the channel
*
+ * \details
* Write text to a display on a channel
*
* \note The channel does not need to be locked before calling this function.
*
- * \retval 0 on success
+ * \retval 0 on success
* \retval -1 on failure
*/
int ast_sendtext(struct ast_channel *chan, const char *text);
@@ -1125,31 +1143,28 @@
/*! \brief Receives a text character from a channel
* \param chan channel to act upon
* \param timeout timeout in milliseconds (0 for infinite wait)
+ * \details
* Read a char of text from a channel
- * Returns 0 on success, -1 on failure
+ * \return 0 on success, -1 on failure
*/
int ast_recvchar(struct ast_channel *chan, int timeout);
-/*! \brief Send a DTMF digit to a channel
- * Send a DTMF digit to a channel.
+/*! \brief Send a DTMF digit to a channel.
* \param chan channel to act upon
* \param digit the DTMF digit to send, encoded in ASCII
* \param duration the duration of the digit ending in ms
- * \return Returns 0 on success, -1 on failure
+ * \return 0 on success, -1 on failure
*/
int ast_senddigit(struct ast_channel *chan, char digit, unsigned int duration);
-/*! \brief Send a DTMF digit to a channel
- * Send a DTMF digit to a channel.
+/*! \brief Send a DTMF digit to a channel.
* \param chan channel to act upon
* \param digit the DTMF digit to send, encoded in ASCII
- * \return Returns 0 on success, -1 on failure
+ * \return 0 on success, -1 on failure
*/
int ast_senddigit_begin(struct ast_channel *chan, char digit);
-/*! \brief Send a DTMF digit to a channel
-
- * Send a DTMF digit to a channel.
+/*! \brief Send a DTMF digit to a channel.
* \param chan channel to act upon
* \param digit the DTMF digit to send, encoded in ASCII
* \param duration the duration of the digit ending in ms
@@ -1166,10 +1181,10 @@
char *ast_recvtext(struct ast_channel *chan, int timeout);
/*! \brief Browse channels in use
- * Browse the channels currently in use
+ * Browse the channels currently in use
* \param prev where you want to start in the channel list
* \return Returns the next channel in the list, NULL on end.
- * If it returns a channel, that channel *has been locked*!
+ * If it returns a channel, that channel *has been locked*!
*/
struct ast_channel *ast_channel_walk_locked(const struct ast_channel *prev);
@@ -1189,14 +1204,14 @@
struct ast_channel *ast_walk_channel_by_exten_locked(const struct ast_channel *chan, const char *exten,
const char *context);
-/*! ! \brief Waits for a digit
+/*! \brief Waits for a digit
* \param c channel to wait for a digit on
* \param ms how many milliseconds to wait
* \return Returns <0 on error, 0 on no entry, and the digit on success. */
int ast_waitfordigit(struct ast_channel *c, int ms);
/*! \brief Wait for a digit
- Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
+ * Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
* \param c channel to wait for a digit on
* \param ms how many milliseconds to wait
* \param audiofd audio file descriptor to write to if audio frames are received
@@ -1204,105 +1219,109 @@
* \return Returns 1 if ctrlfd becomes available */
int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
-/*! Reads multiple digits
+/*! \brief Reads multiple digits
* \param c channel to read from
* \param s string to read in to. Must be at least the size of your length
* \param len how many digits to read (maximum)
* \param timeout how long to timeout between digits
* \param rtimeout timeout to wait on the first digit
* \param enders digits to end the string
- * Read in a digit string "s", max length "len", maximum timeout between
- digits "timeout" (-1 for none), terminated by anything in "enders". Give them rtimeout
- for the first digit. Returns 0 on normal return, or 1 on a timeout. In the case of
- a timeout, any digits that were read before the timeout will still be available in s.
- RETURNS 2 in full version when ctrlfd is available, NOT 1*/
+ * \details
+ * Read in a digit string "s", max length "len", maximum timeout between
+ * digits "timeout" (-1 for none), terminated by anything in "enders". Give them rtimeout
+ * for the first digit.
+ * \return Returns 0 on normal return, or 1 on a timeout. In the case of
+ * a timeout, any digits that were read before the timeout will still be available in s.
+ * RETURNS 2 in full version when ctrlfd is available, NOT 1
+ */
int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
/*! \brief Report DTMF on channel 0 */
-#define AST_BRIDGE_DTMF_CHANNEL_0 (1 << 0)
+#define AST_BRIDGE_DTMF_CHANNEL_0 (1 << 0)
/*! \brief Report DTMF on channel 1 */
-#define AST_BRIDGE_DTMF_CHANNEL_1 (1 << 1)
+#define AST_BRIDGE_DTMF_CHANNEL_1 (1 << 1)
/*! \brief Return all voice frames on channel 0 */
-#define AST_BRIDGE_REC_CHANNEL_0 (1 << 2)
+#define AST_BRIDGE_REC_CHANNEL_0 (1 << 2)
/*! \brief Return all voice frames on channel 1 */
-#define AST_BRIDGE_REC_CHANNEL_1 (1 << 3)
+#define AST_BRIDGE_REC_CHANNEL_1 (1 << 3)
/*! \brief Ignore all signal frames except NULL */
-#define AST_BRIDGE_IGNORE_SIGS (1 << 4)
-
-
-/*! \brief Makes two channel formats compatible
+#define AST_BRIDGE_IGNORE_SIGS (1 << 4)
+
+
+/*! \brief Makes two channel formats compatible
* \param c0 first channel to make compatible
* \param c1 other channel to make compatible
- * Set two channels to compatible formats -- call before ast_channel_bridge in general .
+ * \details
+ * Set two channels to compatible formats -- call before ast_channel_bridge in general .
* \return Returns 0 on success and -1 if it could not be done */
int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
-/*! Bridge two channels together (early)
+/*! \brief Bridge two channels together (early)
* \param c0 first channel to bridge
* \param c1 second channel to bridge
+ * \details
* Bridge two channels (c0 and c1) together early. This implies either side may not be answered yet.
* \return Returns 0 on success and -1 if it could not be done */
int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
-/*! Bridge two channels together
+/*! \brief Bridge two channels together
* \param c0 first channel to bridge
* \param c1 second channel to bridge
* \param config config for the channels
* \param fo destination frame(?)
* \param rc destination channel(?)
+ * \details
* Bridge two channels (c0 and c1) together. If an important frame occurs, we return that frame in
- *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
+ * *rf (remember, it could be NULL) and which channel (0 or 1) in rc
+ */
/* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,
struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
-/*!
+/*!
* \brief Weird function made for call transfers
*
* \param original channel to make a copy of
* \param clone copy of the original channel
*
+ * \details
* This is a very strange and freaky function used primarily for transfer. Suppose that
* "original" and "clone" are two channels in random situations. This function takes
* the guts out of "clone" and puts them into the "original" channel, then alerts the
* channel driver of the change, asking it to fixup any private information (like the
* p->owner pointer) that is affected by the change. The physical layer of the original
- * channel is hung up.
+ * channel is hung up.
*
* \note Neither channel passed here needs to be locked before calling this function.
*/
int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
-/*! Gives the string form of a given cause code */
-/*!
+/*! \brief Gives the string form of a given cause code.
+ *
* \param state cause to get the description of
- * Give a name to a cause code
- * Returns the text form of the binary cause code given
+ * \return the text form of the binary cause code given
*/
const char *ast_cause2str(int state) attribute_pure;
-/*! Convert the string form of a cause code to a number */
-/*!
+/*! \brief Convert the string form of a cause code to a number
+ *
* \param name string form of the cause
- * Returns the cause code
+ * \return the cause code
*/
int ast_str2cause(const char *name) attribute_pure;
-/*! Gives the string form of a given channel state */
-/*!
+/*! \brief Gives the string form of a given channel state
+ *
[... 371 lines stripped ...]
More information about the asterisk-commits
mailing list