diff options
Diffstat (limited to 'main')
-rw-r--r-- | main/pbx.c | 115 | ||||
-rw-r--r-- | main/sha1.c | 136 |
2 files changed, 111 insertions, 140 deletions
diff --git a/main/pbx.c b/main/pbx.c index 419523db9..7d1b554d0 100644 --- a/main/pbx.c +++ b/main/pbx.c @@ -775,21 +775,24 @@ static int ext_cmp(const char *a, const char *b) * 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 @@ static int matchcid(const char *cidpattern, const char *callerid) 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 @@ static struct ast_exten *pbx_find_extension(struct ast_channel *chan, 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 @@ static int parse_variable_name(char *var, int *offset, int *length, int *isfunc) 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 @@ static void pbx_substitute_variables(char *passdata, int datalen, struct ast_cha * 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 @@ static int pbx_extension_helper(struct ast_channel *c, struct ast_context *con, } } -/*! \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 @@ static struct ast_exten *ast_hint_extension(struct ast_channel *c, const char *c 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 @@ static int ast_extension_state2(struct ast_exten *e) 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 @@ const char *ast_extension_state2str(int extension_state) 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 @@ static void *device_state_thread(void *data) 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 @@ int ast_extension_state_add(const char *context, const char *exten, 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 @@ int ast_extension_state_del(int id, ast_state_cb_type callback) 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 @@ static int ast_add_hint(struct ast_exten *e) 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 @@ static int ast_change_hint(struct ast_exten *oe, struct ast_exten *ne) 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 @@ static int ast_remove_hint(struct ast_exten *e) } -/*! \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 @@ int ast_spawn_extension(struct ast_channel *c, const char *context, const char * 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 @@ static void set_ext_pri(struct ast_channel *c, const char *exten, int pri) } /*! - * \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 @@ static int __ast_pbx_run(struct ast_channel *c) 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 @@ int pbx_set_autofallthrough(int newval) 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 @@ static struct ast_context *find_context_locked(const char *context) 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 @@ int ast_context_remove_include(const char *context, const char *include, const c 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 @@ static int ext_strncpy(char *dst, const char *src, int len) 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 @@ static void *async_wait(void *data) 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 */ diff --git a/main/sha1.c b/main/sha1.c index 16ddd6aa3..2dba8a26f 100644 --- a/main/sha1.c +++ b/main/sha1.c @@ -1,6 +1,6 @@ -/* +/*! \file * - * Based on the RFC 3174 + * \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 @@ int SHA1Reset(SHA1Context *context) 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 @@ int SHA1Result( SHA1Context *context, 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 @@ int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned lengt 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 @@ void SHA1ProcessMessageBlock(SHA1Context *context) } -/* - * 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) |