[asterisk-commits] russell: trunk r78541 - in /trunk: include/asterisk/ main/ pbx/ res/ utils/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Aug 7 18:04:02 CDT 2007
Author: russell
Date: Tue Aug 7 18:04:01 2007
New Revision: 78541
URL: http://svn.digium.com/view/asterisk?view=rev&rev=78541
Log:
Add another big set of doxygen documentation improvements from snuffy.
(closes issue #9892)
(closes issue #10395)
Modified:
trunk/include/asterisk/features.h
trunk/main/pbx.c
trunk/main/sha1.c
trunk/pbx/pbx_spool.c
trunk/res/res_crypto.c
trunk/res/res_features.c
trunk/utils/smsq.c
Modified: trunk/include/asterisk/features.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/features.h?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/include/asterisk/features.h (original)
+++ trunk/include/asterisk/features.h Tue Aug 7 18:04:01 2007
@@ -48,31 +48,37 @@
-/*! \brief Park a call and read back parked location
- * \param chan the channel to actually be parked
- \param host the channel which will have the parked location read to
- Park the channel chan, and read back the parked location to the
- host. If the call is not picked up within a specified period of
- time, then the call will return to the last step that it was in
- (in terms of exten, priority and context)
- \param timeout is a timeout in milliseconds
- \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+/*!
+ * \brief Park a call and read back parked location
+ * \param chan the channel to actually be parked
+ * \param host the channel which will have the parked location read to.
+ * \param timeout is a timeout in milliseconds
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * Park the channel chan, and read back the parked location to the host.
+ * If the call is not picked up within a specified period of time,
+ * then the call will return to the last step that it was in
+ * (in terms of exten, priority and context)
+ * \retval 0 on success.
+ * \retval -1 on failure.
*/
int ast_park_call(struct ast_channel *chan, struct ast_channel *host, int timeout, int *extout);
-/*! \brief Park a call via a masqueraded channel
- * \param rchan the real channel to be parked
- \param host the channel to have the parking read to
- Masquerade the channel rchan into a new, empty channel which is then
- parked with ast_park_call
- \param timeout is a timeout in milliseconds
- \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+/*!
+ * \brief Park a call via a masqueraded channel
+ * \param rchan the real channel to be parked
+ * \param host the channel to have the parking read to.
+ * \param timeout is a timeout in milliseconds
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * Masquerade the channel rchan into a new, empty channel which is then parked with ast_park_call
+ * \retval 0 on success.
+ * \retval -1 on failure.
*/
int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *host, int timeout, int *extout);
-/*! \brief Determine system parking extension
- * Returns the call parking extension for drivers that provide special
- call parking help */
+/*!
+ * \brief Determine system parking extension
+ * \returns the call parking extension for drivers that provide special call parking help
+*/
const char *ast_parking_ext(void);
/*! \brief Determine system call pickup extension */
Modified: trunk/main/pbx.c
URL: http://svn.digium.com/view/asterisk/trunk/main/pbx.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/main/pbx.c (original)
+++ trunk/main/pbx.c Tue Aug 7 18:04:01 2007
@@ -775,21 +775,24 @@
* third argument to extension_match_core.
*/
enum ext_match_t {
- E_MATCHMORE = 0x00, /* extension can match but only with more 'digits' */
- E_CANMATCH = 0x01, /* extension can match with or without more 'digits' */
- E_MATCH = 0x02, /* extension is an exact match */
- E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */
- E_SPAWN = 0x12, /* want to spawn an extension. Requires exact match */
- E_FINDLABEL = 0x22 /* returns the priority for a given label. Requires exact match */
+ E_MATCHMORE = 0x00, /*!< extension can match but only with more 'digits' */
+ E_CANMATCH = 0x01, /*!< extension can match with or without more 'digits' */
+ E_MATCH = 0x02, /*!< extension is an exact match */
+ E_MATCH_MASK = 0x03, /*!< mask for the argument to extension_match_core() */
+ E_SPAWN = 0x12, /*!< want to spawn an extension. Requires exact match */
+ E_FINDLABEL = 0x22 /*!< returns the priority for a given label. Requires exact match */
};
-/*
- * Internal function for ast_extension_{match|close}
- * return 0 on no-match, 1 on match, 2 on early match.
+/*!
+ * \internal
+ * \brief used ast_extension_{match|close}
* mode is as follows:
* E_MATCH success only on exact match
* E_MATCHMORE success only on partial match (i.e. leftover digits in pattern)
* E_CANMATCH either of the above.
+ * \retval 0 on no-match
+ * \retval 1 on match
+ * \retval 2 on early match.
*/
static int _extension_match_core(const char *pattern, const char *data, enum ext_match_t mode)
@@ -944,7 +947,7 @@
return ast_extension_match(cidpattern, callerid);
}
-/* request and result for pbx_find_extension */
+/*! request and result for pbx_find_extension */
struct pbx_find_info {
#if 0
const char *context;
@@ -1082,8 +1085,9 @@
return NULL;
}
-/*! \brief extract offset:length from variable name.
- * Returns 1 if there is a offset:length part, which is
+/*!
+ * \brief extract offset:length from variable name.
+ * \return 1 if there is a offset:length part, which is
* trimmed off (values go into variables)
*/
static int parse_variable_name(char *var, int *offset, int *length, int *isfunc)
@@ -1108,12 +1112,15 @@
return 0;
}
-/*! \brief takes a substring. It is ok to call with value == workspace.
- *
- * offset < 0 means start from the end of the string and set the beginning
+/*!
+ *\brief takes a substring. It is ok to call with value == workspace.
+ * \param value
+ * \param offset < 0 means start from the end of the string and set the beginning
* to be that many characters back.
- * length is the length of the substring. A value less than 0 means to leave
+ * \param length is the length of the substring, a value less than 0 means to leave
* that many off the end.
+ * \param workspace
+ * \param workspace_len
* Always return a copy in workspace.
*/
static char *substring(const char *value, int offset, int length, char *workspace, size_t workspace_len)
@@ -1730,7 +1737,9 @@
* E_FINDLABEL maps the label to a priority, and returns
* the priority on success, ... XXX
* E_SPAWN, spawn an application,
- * and return 0 on success, -1 on failure.
+ *
+ * \retval 0 on success.
+ * \retval -1 on failure.
*/
static int pbx_extension_helper(struct ast_channel *c, struct ast_context *con,
const char *context, const char *exten, int priority,
@@ -1836,7 +1845,7 @@
}
}
-/*! \brief ast_hint_extension: Find hint for given extension in context */
+/*! \brief Find hint for given extension in context */
static struct ast_exten *ast_hint_extension(struct ast_channel *c, const char *context, const char *exten)
{
struct ast_exten *e;
@@ -1849,7 +1858,7 @@
return e;
}
-/*! \brief ast_extensions_state2: Check state of extension by using hints */
+/*! \brief Check state of extension by using hints */
static int ast_extension_state2(struct ast_exten *e)
{
char hint[AST_MAX_EXTENSION];
@@ -1934,7 +1943,7 @@
return AST_EXTENSION_NOT_INUSE;
}
-/*! \brief ast_extension_state2str: Return extension_state as string */
+/*! \brief Return extension_state as string */
const char *ast_extension_state2str(int extension_state)
{
int i;
@@ -1946,7 +1955,7 @@
return "Unknown";
}
-/*! \brief ast_extension_state: Check extension state for an extension by using hint */
+/*! \brief Check extension state for an extension by using hint */
int ast_extension_state(struct ast_channel *c, const char *context, const char *exten)
{
struct ast_exten *e;
@@ -2042,7 +2051,7 @@
return NULL;
}
-/*! \brief ast_extension_state_add: Add watcher for extension states */
+/*! \brief Add watcher for extension states */
int ast_extension_state_add(const char *context, const char *exten,
ast_state_cb_type callback, void *data)
{
@@ -2117,7 +2126,7 @@
return cblist->id;
}
-/*! \brief ast_extension_state_del: Remove a watcher from the callback list */
+/*! \brief Remove a watcher from the callback list */
int ast_extension_state_del(int id, ast_state_cb_type callback)
{
struct ast_state_cb **p_cur = NULL; /* address of pointer to us */
@@ -2154,7 +2163,7 @@
return ret;
}
-/*! \brief ast_add_hint: Add hint to hint list, check initial extension state */
+/*! \brief Add hint to hint list, check initial extension state */
static int ast_add_hint(struct ast_exten *e)
{
struct ast_hint *hint;
@@ -2188,7 +2197,7 @@
return 0;
}
-/*! \brief ast_change_hint: Change hint for an extension */
+/*! \brief Change hint for an extension */
static int ast_change_hint(struct ast_exten *oe, struct ast_exten *ne)
{
struct ast_hint *hint;
@@ -2207,7 +2216,7 @@
return res;
}
-/*! \brief ast_remove_hint: Remove hint from extension */
+/*! \brief Remove hint from extension */
static int ast_remove_hint(struct ast_exten *e)
{
/* Cleanup the Notifys if hint is removed */
@@ -2242,7 +2251,7 @@
}
-/*! \brief ast_get_hint: Get hint for channel */
+/*! \brief Get hint for channel */
int ast_get_hint(char *hint, int hintsize, char *name, int namesize, struct ast_channel *c, const char *context, const char *exten)
{
struct ast_exten *e = ast_hint_extension(c, context, exten);
@@ -2290,7 +2299,7 @@
return pbx_extension_helper(c, NULL, context, exten, priority, NULL, callerid, E_SPAWN);
}
-/* helper function to set extension and priority */
+/*! helper function to set extension and priority */
static void set_ext_pri(struct ast_channel *c, const char *exten, int pri)
{
ast_copy_string(c->exten, exten, sizeof(c->exten));
@@ -2298,9 +2307,10 @@
}
/*!
- * \brief collect digits from the channel into the buffer,
- * return -1 on error, 0 on timeout or done.
- */
+ * \brief collect digits from the channel into the buffer.
+ * \retval 0 on timeout or done.
+ * \retval -1 on error.
+*/
static int collect_digits(struct ast_channel *c, int waittime, char *buf, int buflen, int pos)
{
int digit;
@@ -2531,7 +2541,11 @@
return 0;
}
-/* Returns 0 on success, non-zero if a configured limit (maxcalls, maxload, minmemfree) was reached */
+/*!
+ * \brief Increase call count for channel
+ * \retval 0 on success
+ * \retval non-zero if a configured limit (maxcalls, maxload, minmemfree) was reached
+*/
static int increase_call_count(const struct ast_channel *c)
{
int failed = 0;
@@ -2661,9 +2675,11 @@
return oldval;
}
-/* lookup for a context with a given name,
- * return with conlock held if found, NULL if not found
- */
+/*!
+ * \brief lookup for a context with a given name,
+ * \retval with conlock held if found.
+ * \retval NULL if not found.
+*/
static struct ast_context *find_context_locked(const char *context)
{
struct ast_context *c = NULL;
@@ -2678,11 +2694,12 @@
return NULL;
}
-/*
+/*!
+ * \brief Remove included contexts.
* This function locks contexts list by &conlist, search for the right context
* structure, leave context list locked and call ast_context_remove_include2
* which removes include, unlock contexts list and return ...
- */
+*/
int ast_context_remove_include(const char *context, const char *include, const char *registrar)
{
int ret = -1;
@@ -2696,13 +2713,14 @@
return ret;
}
-/*
+/*!
+ * \brief Locks context, remove included contexts, unlocks context.
* When we call this function, &conlock lock must be locked, because when
* we giving *con argument, some process can remove/change this context
* and after that there can be segfault.
*
- * This function locks given context, removes include, unlock context and
- * return.
+ * \retval 0 on success.
+ * \retval -1 on failure.
*/
int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar)
{
@@ -4673,9 +4691,11 @@
return count;
}
-/*! \brief add the extension in the priority chain.
- * returns 0 on success, -1 on failure
- */
+/*!
+ * \brief add the extension in the priority chain.
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
static int add_pri(struct ast_context *con, struct ast_exten *tmp,
struct ast_exten *el, struct ast_exten *e, int replace)
{
@@ -4953,11 +4973,10 @@
return NULL;
}
-/*! Function to post an empty cdr after a spool call fails.
- *
- * This function posts an empty cdr for a failed spool call
- *
- */
+/*!
+ * \brief Function to post an empty cdr after a spool call fails.
+ * \note This function posts an empty cdr for a failed spool call
+*/
static int ast_pbx_outgoing_cdr_failed(void)
{
/* allocate a channel */
Modified: trunk/main/sha1.c
URL: http://svn.digium.com/view/asterisk/trunk/main/sha1.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/main/sha1.c (original)
+++ trunk/main/sha1.c Tue Aug 7 18:04:01 2007
@@ -1,6 +1,6 @@
-/*
- *
- * Based on the RFC 3174
+/*! \file
+ *
+ * \brief Based on the RFC 3174
*
* Full Copyright Statement
*
@@ -63,9 +63,7 @@
#include "asterisk/sha1.h"
-/*
- * Define the SHA1 circular left shift macro
- */
+/*! Define the SHA1 circular left shift macro */
#define SHA1CircularShift(bits,word) \
(((word) << (bits)) | ((word) >> (32-(bits))))
@@ -73,20 +71,12 @@
void SHA1PadMessage(SHA1Context *);
void SHA1ProcessMessageBlock(SHA1Context *);
-/*
- * SHA1Reset
- *
- * Description:
- * This function will initialize the SHA1Context in preparation
- * for computing a new SHA1 message digest.
- *
- * Parameters:
- * context: [in/out]
- * The context to reset.
- *
- * Returns:
- * sha Error Code.
- *
+/*!
+ * \brief SHA1Reset
+ * \param context the context to be reset
+ * This function will initialize the SHA1Context in preparation
+ * for computing a new SHA1 message digest.
+ * \return sha Error Code.
*/
int SHA1Reset(SHA1Context *context)
{
@@ -110,24 +100,15 @@
return shaSuccess;
}
-/*
- * SHA1Result
- *
- * Description:
- * This function will return the 160-bit message digest into the
- * Message_Digest array provided by the caller.
- * NOTE: The first octet of hash is stored in the 0th element,
- * the last octet of hash in the 19th element.
- *
- * Parameters:
- * context: [in/out]
- * The context to use to calculate the SHA-1 hash.
- * Message_Digest: [out]
- * Where the digest is returned.
- *
- * Returns:
- * sha Error Code.
- *
+/*!
+ * \brief SHA1Result
+ * \param context [in/out] The context to use to calculate the SHA-1 hash.
+ * \param Message_Digest [out] Where the digest is returned.
+ * This function will return the 160-bit message digest into the
+ * Message_Digest array provided by the caller.
+ * \note The first octet of hash is stored in the 0th element,
+ * the last octet of hash in the 19th element.
+ * \return sha Error Code.
*/
int SHA1Result( SHA1Context *context,
uint8_t Message_Digest[SHA1HashSize])
@@ -160,25 +141,15 @@
return shaSuccess;
}
-/*
- * SHA1Input
- *
- * Description:
- * This function accepts an array of octets as the next portion
- * of the message.
- *
- * Parameters:
- * context: [in/out]
- * The SHA context to update
- * message_array: [in]
- * An array of characters representing the next portion of
+/*!
+ * \brief SHA1Input
+ * \param context [in/out] The SHA context to update
+ * \param message_array [in] An array of characters representing the next portion of
* the message.
- * length: [in]
- * The length of the message in message_array
- *
- * Returns:
- * sha Error Code.
- *
+ * \param length [in] The length of the message in message_array
+ * This function accepts an array of octets as the next portion
+ * of the message.
+ * \return sha Error Code.
*/
int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned length)
{
@@ -221,25 +192,13 @@
return shaSuccess;
}
-/*
- * SHA1ProcessMessageBlock
- *
- * Description:
- * This function will process the next 512 bits of the message
- * stored in the Message_Block array.
- *
- * Parameters:
- * None.
- *
- * Returns:
- * Nothing.
- *
- * Comments:
- * Many of the variable names in this code, especially the
+/*!
+ * \brief Process the next 512 bits of the message stored in the Message_Block array.
+ * \param context [in/out] The SHA context to update
+ * \note Many of the variable names in this code, especially the
* single character names, were used because those were the
* names used in the publication.
- *
- *
+ * \returns nothing.
*/
void SHA1ProcessMessageBlock(SHA1Context *context)
{
@@ -320,27 +279,20 @@
}
-/*
- * SHA1PadMessage
- *
- * Description:
- * According to the standard, the message must be padded to an even
- * 512 bits. The first padding bit must be a '1'. The last 64
- * bits represent the length of the original message. All bits in
- * between should be 0. This function will pad the message
- * according to those rules by filling the Message_Block array
- * accordingly. It will also call the ProcessMessageBlock function
- * provided appropriately. When it returns, it can be assumed that
- * the message digest has been computed.
- *
- * Parameters:
- * context: [in/out]
- * The context to pad
- * ProcessMessageBlock: [in]
- * The appropriate SHA*ProcessMessageBlock function
- * Returns:
- * Nothing.
- *
+/*!
+ * \brief Pad message to be 512 bits.
+ * \param context [in/out] The context to pad
+ *
+ * According to the standard, the message must be padded to an even
+ * 512 bits. The first padding bit must be a '1'. The last 64
+ * bits represent the length of the original message. All bits in
+ * between should be 0. This function will pad the message
+ * according to those rules by filling the Message_Block array
+ * accordingly. It will also call the ProcessMessageBlock function
+ * provided appropriately. When it returns, it can be assumed that
+ * the message digest has been computed.
+ *
+ * \returns nothing.
*/
void SHA1PadMessage(SHA1Context *context)
Modified: trunk/pbx/pbx_spool.c
URL: http://svn.digium.com/view/asterisk/trunk/pbx/pbx_spool.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/pbx/pbx_spool.c (original)
+++ trunk/pbx/pbx_spool.c Tue Aug 7 18:04:01 2007
@@ -68,18 +68,18 @@
struct outgoing {
char fn[256];
- /* Current number of retries */
+ /*! Current number of retries */
int retries;
- /* Maximum number of retries permitted */
+ /*! Maximum number of retries permitted */
int maxretries;
- /* How long to wait between retries (in seconds) */
+ /*! How long to wait between retries (in seconds) */
int retrytime;
- /* How long to wait for an answer */
+ /*! How long to wait for an answer */
int waittime;
- /* PID which is currently calling */
+ /*! PID which is currently calling */
long callingpid;
- /* What to connect to outgoing */
+ /*! What to connect to outgoing */
char tech[256];
char dest[256];
@@ -96,16 +96,16 @@
char cid_num[256];
char cid_name[256];
- /* account code */
+ /*! account code */
char account[AST_MAX_ACCOUNT_CODE];
- /* Variables and Functions */
+ /*! Variables and Functions */
struct ast_variable *vars;
- /* Maximum length of call */
+ /*! Maximum length of call */
int maxlen;
- /* options */
+ /*! options */
struct ast_flags options;
};
Modified: trunk/res/res_crypto.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_crypto.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/res/res_crypto.c (original)
+++ trunk/res/res_crypto.c Tue Aug 7 18:04:01 2007
@@ -93,6 +93,16 @@
};
static AST_RWLIST_HEAD_STATIC(keys, ast_key);
+
+/*!
+ * \brief setting of priv key
+ * \param buf
+ * \param size
+ * \param rwflag
+ * \param userdata
+ * \return length of string,-1 on failure
+*/
+
/*!
* \brief setting of priv key
@@ -283,6 +293,10 @@
* \brief signs outgoing message with public key
* \see ast_sign_bin
*/
+/*!
+ * \brief signs outgoing message with public key
+ * \see ast_sign_bin
+*/
static int __ast_sign_bin(struct ast_key *key, const char *msg, int msglen, unsigned char *dsig)
{
unsigned char digest[20];
Modified: trunk/res/res_features.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_features.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/res/res_features.c (original)
+++ trunk/res/res_features.c Tue Aug 7 18:04:01 2007
@@ -197,7 +197,10 @@
-/*! \brief store context, priority and extension */
+/*!
+ * \brief store context, extension and priority
+ * \param chan, context, ext, pri
+*/
static void set_c_e_p(struct ast_channel *chan, const char *context, const char *ext, int pri)
{
ast_copy_string(chan->context, context, sizeof(chan->context));
@@ -205,6 +208,13 @@
chan->priority = pri;
}
+/*!
+ * \brief Check goto on transfer
+ * \param chan
+ * Check if channel has 'GOTO_ON_BLINDXFR' set, if not exit.
+ * When found make sure the types are compatible. Check if channel is valid
+ * if so start the new channel else hangup the call.
+*/
static void check_goto_on_transfer(struct ast_channel *chan)
{
struct ast_channel *xferchan;
@@ -243,7 +253,13 @@
static struct ast_channel *ast_feature_request_and_dial(struct ast_channel *caller, struct ast_channel *transferee, const char *type, int format, void *data, int timeout, int *outstate, const char *cid_num, const char *cid_name, int igncallerstate);
-
+/*!
+ * \brief bridge the call
+ * \param data thread bridge
+ * Set Last Data for respective channels, reset cdr for channels
+ * bridge call, check if we're going back to dialplan
+ * if not hangup both legs of the call
+*/
static void *ast_bridge_call_thread(void *data)
{
struct ast_bridge_thread_obj *tobj = data;
@@ -290,6 +306,11 @@
return NULL;
}
+/*!
+ * \brief create thread for the parked call
+ * \param data
+ * Create thread and attributes, call ast_bridge_call_thread
+*/
static void ast_bridge_call_thread_launch(void *data)
{
pthread_t thread;
@@ -304,6 +325,14 @@
pthread_setschedparam(thread, SCHED_RR, &sched);
}
+/*!
+ * \brief Announce call parking by ADSI
+ * \param chan
+ * \param parkingexten
+ * Create message to show for ADSI, display message.
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
static int adsi_announce_park(struct ast_channel *chan, char *parkingexten)
{
int res;
@@ -349,9 +378,7 @@
return AST_DEVICE_INUSE;
}
-/*! \brief Park a call
- \note We put the user in the parking list, then wake up the parking thread to be sure it looks
- after these channels too */
+/* Park a call */
int ast_park_call(struct ast_channel *chan, struct ast_channel *peer, int timeout, int *extout)
{
struct parkeduser *pu, *cur;
@@ -479,6 +506,7 @@
return 0;
}
+/* Park call via masquraded channel */
int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *peer, int timeout, int *extout)
{
struct ast_channel *chan;
@@ -519,9 +547,11 @@
#define FEATURE_SENSE_CHAN (1 << 0)
#define FEATURE_SENSE_PEER (1 << 1)
-/*! \brief
- * set caller and callee according to the direction
- */
+/*!
+ * \brief set caller and callee according to the direction
+ * \param caller, callee, peer, chan, sense
+ * Detect who triggered feature and set callee/caller variables accordingly
+*/
static void set_peers(struct ast_channel **caller, struct ast_channel **callee,
struct ast_channel *peer, struct ast_channel *chan, int sense)
{
@@ -534,7 +564,16 @@
}
}
-/*! \brief support routing for one touch call parking */
+/*!
+ * \brief support routing for one touch call parking
+ * \param chan channel parking call
+ * \param peer channel to be parked
+ * \param config unsed
+ * \param code unused
+ * \param sense feature options
+ * Setup channel, set return exten,priority to 's,1'
+ * answer chan, sleep chan, park call
+*/
static int builtin_parkcall(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
struct ast_channel *parker;
@@ -568,6 +607,18 @@
}
+/*!
+ * \brief Monitor a channel by DTMF
+ * \param chan channel requesting monitor
+ * \param peer channel to be monitored
+ * \param config
+ * \param code
+ * \param sense
+ * Check monitor app enabled, setup channels, both caller/callee chans not null
+ * get TOUCH_MONITOR variable for filename if exists, exec monitor app.
+ * \retval FEATURE_RETURN_SUCCESS on success.
+ * \retval -1 on error.
+*/
static int builtin_automonitor(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
char *caller_chan_id = NULL, *callee_chan_id = NULL, *args = NULL, *touch_filename = NULL;
@@ -663,7 +714,13 @@
return ast_autoservice_stop(chan);
}
-/*! \brief Find the context for the transfer */
+/*!
+ * \brief Find the context for the transfer
+ * \param transferer
+ * \param transferee
+ * Grab the TRANSFER_CONTEXT, if fails try grabbing macrocontext.
+ * \return a context string
+*/
static const char *real_ctx(struct ast_channel *transferer, struct ast_channel *transferee)
{
const char *s = pbx_builtin_getvar_helper(transferer, "TRANSFER_CONTEXT");
@@ -676,6 +733,18 @@
return s;
}
+/*!
+ * \brief Blind transfer user to another extension
+ * \param chan channel initiated blind transfer
+ * \param peer channel to be transfered
+ * \param config
+ * \param code
+ * \param sense
+ * Place peer on hold, check if tranfered to parkinglot extension,
+ * otherwise check extension exists and transfer caller.
+ * \retval FEATURE_RETURN_SUCCESS.
+ * \retval -1 on failure.
+*/
static int builtin_blindtransfer(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
struct ast_channel *transferer;
@@ -763,6 +832,13 @@
return FEATURE_RETURN_SUCCESS;
}
+/*!
+ * \brief make channels compatible
+ * \param c
+ * \param newchan
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
static int check_compat(struct ast_channel *c, struct ast_channel *newchan)
{
if (ast_channel_make_compatible(c, newchan) < 0) {
@@ -774,6 +850,18 @@
return 0;
}
+/*!
+ * \brief Attended transfer
+ * \param chan
+ * \param peer
+ * \param config
+ * \param code
+ * \param sense
+ * Get extension to transfer to, if you cannot generate channel (or find extension)
+ * return to host channel. After called channel answered wait for hangup of transferer,
+ * bridge call between transfer peer (taking them off hold) to attended transfer channel.
+ * \return -1 means what failure/success both?
+*/
static int builtin_atxfer(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
struct ast_channel *transferer;
@@ -1034,7 +1122,12 @@
ast_verb(2, "Registered Feature '%s'\n",feature->sname);
}
-/*! \brief This function must be called while feature_groups is locked... */
+/*!
+ * \brief Add new feature group
+ * \param fgname feature group name
+ * Add new feature group to the feature group list insert at head of list.
+ * \note This function MUST be called while feature_groups is locked.
+*/
static struct feature_group* register_group(const char *fgname)
{
struct feature_group *fg;
@@ -1061,8 +1154,14 @@
return fg;
}
-/*! \brief This function must be called while feature_groups is locked... */
-
+/*!
+ * \brief Add feature to group
+ * \param fg feature group
+ * \param exten
+ * \param feature feature to add
+ * Check fg and feature specified, add feature to list
+ * \note This function MUST be called while feature_groups is locked.
+*/
static void register_group_feature(struct feature_group *fg, const char *exten, struct ast_call_feature *feature)
{
struct feature_group_exten *fge;
@@ -1095,7 +1194,6 @@
feature->sname, fg->gname, exten);
}
-/*! \brief unregister feature from feature_list */
void ast_unregister_feature(struct ast_call_feature *feature)
{
if (!feature)
@@ -1131,7 +1229,7 @@
return tmp;
}
-/*! \brief Remove all groups in the list */
+/*! \brief Remove all feature groups in the list */
static void ast_unregister_groups(void)
{
struct feature_group *fg;
@@ -1150,7 +1248,12 @@
AST_RWLIST_UNLOCK(&feature_groups);
}
-/*! \brief Find a group by name */
+/*!
+ * \brief Find a group by name
+ * \param name feature name
+ * \retval feature group on success.
+ * \retval NULL on failure.
+*/
static struct feature_group *find_group(const char *name) {
struct feature_group *fg = NULL;
@@ -1162,6 +1265,12 @@
return fg;
}
+/*!
+ * \brief Find a feature extension
+ * \param fg, code
+ * \retval feature group extension on success.
+ * \retval NULL on failure.
+*/
static struct feature_group_exten *find_group_exten(struct feature_group *fg, const char *code) {
struct feature_group_exten *fge = NULL;
@@ -1183,7 +1292,6 @@
ast_rwlock_unlock(&features_lock);
}
-/*! \brief find a call feature by name */
struct ast_call_feature *ast_find_call_feature(const char *name)
{
int x;
@@ -1194,7 +1302,14 @@
return NULL;
}
-/*! \brief exec an app by feature */
+/*!
+ * \brief exec an app by feature
+ * \param chan,peer,config,code,sense
+ * Find a feature, determine which channel activated
+ * \retval FEATURE_RETURN_PBX_KEEPALIVE,FEATURE_RETURN_NO_HANGUP_PEER
+ * \retval -1 error.
+ * \retval -2 when an application cannot be found.
+*/
static int feature_exec_app(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
struct ast_app *app;
@@ -1291,6 +1406,13 @@
return res;
}
+/*!
+ * \brief Check the dynamic features
+ * \param chan,peer,config,code,sense
+ * Lock features list, browse for code, unlock list
+ * \retval res on success.
+ * \retval -1 on failure.
+*/
static int ast_feature_interpret(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
{
int x;
@@ -1405,7 +1527,15 @@
}
}
-/*! \todo XXX Check - this is very similar to the code in channel.c */
+/*!
+ * \brief
+ * \param caller,transferee,type,format,data,timeout,outstate,cid_num,cid_name,igncallerstate
+ * Request channel, set channel variables, initiate call,check if they want to disconnect
+ * go into loop, check if timeout has elapsed, check if person to be transfered hung up,
+ * check for answer break loop, set cdr return channel.
+ * \todo XXX Check - this is very similar to the code in channel.c
+ * \return always a channel
+*/
static struct ast_channel *ast_feature_request_and_dial(struct ast_channel *caller, struct ast_channel *transferee, const char *type, int format, void *data, int timeout, int *outstate, const char *cid_num, const char *cid_name, int igncallerstate)
{
int state = 0;
@@ -1587,6 +1717,14 @@
return chan;
}
+/*!
+ * \brief bridge the call and set CDR
+ * \param chan,peer,config
+ * Set start time, check for two channels,check if monitor on
+ * check for feature activation, create new CDR
+ * \retval res on success.
+ * \retval -1 on failure to bridge.
+*/
int ast_bridge_call(struct ast_channel *chan,struct ast_channel *peer,struct ast_bridge_config *config)
{
/* Copy voice back and forth between the two channels. Give the peer
@@ -1878,7 +2016,13 @@
);
}
-/*! \brief Take care of parked calls and unpark them if needed */
+/*!
+ * \brief Take care of parked calls and unpark them if needed
+ * \param ignore unused var
+ * Start inf loop, lock parking lot, check if any parked channels have gone above timeout
+ * if so, remove channel from parking lot and return it to the extension that parked it.
+ * Check if parked channel decided to hangup, wait until next FD via select().
+*/
static void *do_parking_thread(void *ignore)
{
char parkingslot[AST_MAX_EXTENSION];
@@ -2240,6 +2384,13 @@
" Tone: (Yes|No) Play courtesy tone to Channel 2\n"
"\n";
+/*!
+ * \brief Actual bridge
+ * \param chan
+ * \param tmpchan
+ * Stop hold music, lock both channels, masq channels,
+ * after bridge return channel to next priority.
+*/
static void do_bridge_masquerade(struct ast_channel *chan, struct ast_channel *tmpchan)
{
ast_moh_stop(chan);
@@ -2256,6 +2407,18 @@
ast_mutex_unlock(&chan->lock);
}
+/*!
+ * \brief Bridge channels together
+ * \param s
+ * \param m
+ * Make sure valid channels were specified,
+ * send errors if any of the channels could not be found/locked, answer channels if needed,
+ * create the placeholder channels and grab the other channels
+ * make the channels compatible, send error if we fail doing so
+ * setup the bridge thread object and start the bridge.
+ * \retval 0 on success or on incorrect use.
+ * \retval 1 on failure to bridge channels.
+*/
static int action_bridge(struct mansession *s, const struct message *m)
{
const char *channela = astman_get_header(m, "Channel1");
@@ -2355,6 +2518,16 @@
"Usage: feature list\n"
" Lists currently configured features.\n";
+/*!
+ * \brief CLI command to list parked calls
+ * \param e
+ * \param cmd
+ * \param a
+ * Check right usage, lock parking lot, display parked calls, unlock parking lot list.
+ * \retval CLI_SUCCESS on success.
+ * \retval CLI_SHOWUSAGE on incorrect number of arguements.
+ * \retval NULL when tab completion is used.
+*/
static char *handle_parkedcalls(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
struct parkeduser *cur;
@@ -2410,7 +2583,13 @@
NEW_CLI(handle_parkedcalls, "List currently parked calls", .deprecate_cmd = &cli_show_parkedcalls_deprecated),
};
-/*! \brief Dump lot status */
+/*!
+ * \brief Dump parking lot status
+ * \param s
+ * \param m
+ * Lock parking lot, iterate list and append parked calls status, unlock parking lot.
+ * \return Always RESULT_SUCCESS
+*/
static int manager_parking_status(struct mansession *s, const struct message *m)
{
struct parkeduser *cur;
@@ -2458,6 +2637,13 @@
" *Channel2: Channel to announce park info to (and return to if timeout)\n"
" Timeout: Number of milliseconds to wait before callback.\n";
+/*!
+ * \brief Create manager event for parked calls
+ * \param s
+ * \param m
+ * Get channels involved in park, create event.
+ * \return Always 0
+*/
static int manager_park(struct mansession *s, const struct message *m)
{
const char *channel = astman_get_header(m, "Channel");
@@ -2512,7 +2698,13 @@
return 0;
}
-
+/*!
+ * \brief Pickup a call
+ * \param chan channel that initiated pickup
+ * Walk list of channels, checking it is not itself, channel is pbx one,
+ * check that the callgroup for both channels are the same and the channel is ringing.
+ * Answer calling channel, flag channel as answered on queue, masq channels together.
+*/
int ast_pickup_call(struct ast_channel *chan)
{
struct ast_channel *cur = NULL;
@@ -2546,7 +2738,12 @@
return res;
}
-/*! \brief Add parking hints for all defined parking lots */
+/*!
+ * \brief Add parking hints for all defined parking lots
+ * \param context
+ * \param start starting parkinglot number
+ * \param stop ending parkinglot number
+*/
static void park_add_hints(char *context, int start, int stop)
{
int numext;
@@ -2868,6 +3065,14 @@
AST_APP_OPTION('p', BRIDGE_OPT_PLAYTONE)
END_OPTIONS );
+/*!
+ * \brief Bridge channels
+ * \param chan
+ * \param data channel to bridge with
+ * Split data, check we aren't bridging with ourself, check valid channel,
+ * answer call if not already, check compatible channels, setup bridge config
+ * now bridge call, if transfered party hangs up return to PBX extension.
+*/
static int bridge_exec(struct ast_channel *chan, void *data)
{
struct ast_module_user *u;
Modified: trunk/utils/smsq.c
URL: http://svn.digium.com/view/asterisk/trunk/utils/smsq.c?view=diff&rev=78541&r1=78540&r2=78541
==============================================================================
--- trunk/utils/smsq.c (original)
+++ trunk/utils/smsq.c Tue Aug 7 18:04:01 2007
@@ -38,9 +38,11 @@
#endif
-/* reads next USC character from null terminated UTF-8 string and advanced pointer */
-/* for non valid UTF-8 sequences, returns character as is */
-/* Does not advance pointer for null termination */
+/*!
+ * \brief reads next USC character from null terminated UTF-8 string and advanced pointer
+ * for non valid UTF-8 sequences.
+ * \return character as is Does \b NOT advance pointer for null termination
+*/
static int utf8decode (unsigned char **pp)
{
unsigned char *p = *pp;
@@ -90,8 +92,13 @@
return *p; /* not sensible */
}
-/* check for any queued messages in specific queue (queue="" means any queue) */
-/* returns 0 if nothing queued, 1 if queued and outgoing set up OK, 2 of outgoing exists */
+/*!
+ * \brief check for any queued messages in specific queue (queue="" means any queue)
+ * \param dir,queue,subaddress,channel,callerid,wait,delay,retries,concurrent
+ * \retval 0 if nothing queued
+ * \retval 1 if queued and outgoing set up OK
+ * \retval 2 of outgoing exists
+*/
static char txqcheck (char *dir, char *queue, char subaddress, char *channel, char *callerid, int wait, int delay, int retries, int concurrent)
{
char ogname[100],
@@ -186,7 +193,10 @@
return 2;
}
-/* Process received queue entries and run through a process, setting environment variables */
+/*!
+ * \brief Process received queue entries
+ * Run through a process, setting environment variables
+*/
static void rxqcheck (char *dir, char *queue, char *process)
{
char *p;
More information about the asterisk-commits
mailing list