diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/astobj2.h | 42 | ||||
-rw-r--r-- | include/asterisk/audiohook.h | 8 | ||||
-rw-r--r-- | include/asterisk/bridging.h | 10 | ||||
-rw-r--r-- | include/asterisk/bridging_technology.h | 2 | ||||
-rw-r--r-- | include/asterisk/ccss.h | 8 | ||||
-rw-r--r-- | include/asterisk/channel.h | 16 | ||||
-rw-r--r-- | include/asterisk/config.h | 8 | ||||
-rw-r--r-- | include/asterisk/config_options.h | 48 | ||||
-rw-r--r-- | include/asterisk/crypto.h | 6 | ||||
-rw-r--r-- | include/asterisk/datastore.h | 1 | ||||
-rw-r--r-- | include/asterisk/format.h | 8 | ||||
-rw-r--r-- | include/asterisk/format_cap.h | 8 | ||||
-rw-r--r-- | include/asterisk/format_pref.h | 4 | ||||
-rw-r--r-- | include/asterisk/framehook.h | 18 | ||||
-rw-r--r-- | include/asterisk/heap.h | 3 | ||||
-rw-r--r-- | include/asterisk/manager.h | 2 | ||||
-rw-r--r-- | include/asterisk/message.h | 2 | ||||
-rw-r--r-- | include/asterisk/netsock2.h | 14 | ||||
-rw-r--r-- | include/asterisk/pbx.h | 2 | ||||
-rw-r--r-- | include/asterisk/presencestate.h | 12 | ||||
-rw-r--r-- | include/asterisk/rtp_engine.h | 4 | ||||
-rw-r--r-- | include/asterisk/strings.h | 2 | ||||
-rw-r--r-- | include/asterisk/translate.h | 20 | ||||
-rw-r--r-- | include/asterisk/utils.h | 5 |
24 files changed, 157 insertions, 96 deletions
diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h index 5cf770a7c..d7d9d79d2 100644 --- a/include/asterisk/astobj2.h +++ b/include/asterisk/astobj2.h @@ -522,6 +522,7 @@ enum ao2_lock_req { * Lock an object. * * \param a A pointer to the object we want to lock. + * \param lock_how, file, func, line, var * \return 0 on success, other values on error. */ int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var); @@ -533,6 +534,7 @@ int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char * Unlock an object. * * \param a A pointer to the object we want unlock. + * \param file, func, line, var * \return 0 on success, other values on error. */ int __ao2_unlock(void *a, const char *file, const char *func, int line, const char *var); @@ -542,6 +544,7 @@ int __ao2_unlock(void *a, const char *file, const char *func, int line, const ch * Try locking-- (don't block if fail) * * \param a A pointer to the object we want to lock. + * \param lock_how, file, func, line, var * \return 0 on success, other values on error. */ int __ao2_trylock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var); @@ -1044,7 +1047,6 @@ struct ao2_container *__ao2_container_clone_debug(struct ao2_container *orig, en * * \param container The container to operate on. * \param obj The object to be added. - * \param flags search_flags to control linking the object. (OBJ_NOLOCK) * \param tag used for debugging. * * \retval NULL on errors. @@ -1062,6 +1064,24 @@ struct ao2_container *__ao2_container_clone_debug(struct ao2_container *orig, en #define ao2_t_link(container, obj, tag) __ao2_link_debug((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_link(container, obj) __ao2_link_debug((container), (obj), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) +/*! + * \brief Add an object to a container. + * + * \param container The container to operate on. + * \param obj The object to be added. + * \param flags search_flags to control linking the object. (OBJ_NOLOCK) + * \param tag used for debugging. + * + * \retval NULL on errors. + * \retval !NULL on success. + * + * This function inserts an object in a container according its key. + * + * \note Remember to set the key before calling this function. + * + * \note This function automatically increases the reference count to account + * for the reference that the container now holds to the object. + */ #define ao2_t_link_flags(container, obj, flags, tag) __ao2_link_debug((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_link_flags(container, obj, flags) __ao2_link_debug((container), (obj), (flags), "", __FILE__, __LINE__, __PRETTY_FUNCTION__) @@ -1083,7 +1103,6 @@ void *__ao2_link(struct ao2_container *c, void *obj_new, int flags); * * \param container The container to operate on. * \param obj The object to unlink. - * \param flags search_flags to control unlinking the object. (OBJ_NOLOCK) * \param tag used for debugging. * * \retval NULL, always @@ -1101,6 +1120,25 @@ void *__ao2_link(struct ao2_container *c, void *obj_new, int flags); #define ao2_t_unlink(container, obj, tag) __ao2_unlink_debug((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_unlink(container, obj) __ao2_unlink_debug((container), (obj), 0, "", __FILE__, __LINE__, __PRETTY_FUNCTION__) +/*! + * \brief Remove an object from a container + * + * \param container The container to operate on. + * \param obj The object to unlink. + * \param flags search_flags to control unlinking the object. (OBJ_NOLOCK) + * \param tag used for debugging. + * + * \retval NULL, always + * + * \note The object requested to be unlinked must be valid. However, if it turns + * out that it is not in the container, this function is still safe to + * be called. + * + * \note If the object gets unlinked from the container, the container's + * reference to the object will be automatically released. (The + * refcount will be decremented). + */ + #define ao2_t_unlink_flags(container, obj, flags, tag) __ao2_unlink_debug((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__) #define ao2_unlink_flags(container, obj, flags) __ao2_unlink_debug((container), (obj), (flags), "", __FILE__, __LINE__, __PRETTY_FUNCTION__) diff --git a/include/asterisk/audiohook.h b/include/asterisk/audiohook.h index 5e8fc1812..516c59f6d 100644 --- a/include/asterisk/audiohook.h +++ b/include/asterisk/audiohook.h @@ -154,10 +154,10 @@ struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments. * \param audiohook Audiohook structure * \param samples Number of samples wanted - * \param direction Direction the audio frame came from - * \param format Format of frame remote side wants back - * \param ast_frame read_frame - if available, we'll copy the read buffer to this. - * \param ast_frame write_frame - if available, we'll copy the write buffer to this. + * \param ast_format Format of frame remote side wants back + * \param read_frame if available, we'll copy the read buffer to this. + * \param write_frame if available, we'll copy the write buffer to this. + * \param direction * \return Returns frame on success, NULL on failure */ struct ast_frame *ast_audiohook_read_frame_all(struct ast_audiohook *audiohook, size_t samples, struct ast_format *format, struct ast_frame **read_frame, struct ast_frame **write_frame); diff --git a/include/asterisk/bridging.h b/include/asterisk/bridging.h index 831f340c8..0f194f418 100644 --- a/include/asterisk/bridging.h +++ b/include/asterisk/bridging.h @@ -312,7 +312,7 @@ int ast_bridge_destroy(struct ast_bridge *bridge); * \param chan Channel to join * \param swap Channel to swap out if swapping * \param features Bridge features structure - * \param (Optional) Bridging tech optimization parameters for this channel. + * \param tech_args Optional Bridging tech optimization parameters for this channel. * * \retval state that channel exited the bridge with * @@ -504,8 +504,8 @@ void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast /*! \brief Adjust the internal mixing sample rate of a bridge used during * multimix mode. * - * \param bridge_channel Channel to change the sample rate on. - * \param sample rate, the sample rate to change to. If a + * \param bridge Channel to change the sample rate on. + * \param sample_rate the sample rate to change to. If a * value of 0 is passed here, the bridge will be free to pick * what ever sample rate it chooses. * @@ -515,8 +515,8 @@ void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int /*! \brief Adjust the internal mixing interval of a bridge used during * multimix mode. * - * \param bridge_channel Channel to change the sample rate on. - * \param mixing_interval, the sample rate to change to. If 0 is set + * \param bridge Channel to change the sample rate on. + * \param mixing_interval the sample rate to change to. If 0 is set * the bridge tech is free to choose any mixing interval it uses by default. */ void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval); diff --git a/include/asterisk/bridging_technology.h b/include/asterisk/bridging_technology.h index 3d2e870b6..ccc87fb63 100644 --- a/include/asterisk/bridging_technology.h +++ b/include/asterisk/bridging_technology.h @@ -153,7 +153,7 @@ void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel * * \param bridge The bridge that the channel is a part of. * \param bridge_channel The bridge channel that has either started or stopped talking. - * \param started_talking, set to 1 when this indicates the channel has started talking, set to 0 + * \param started_talking set to 1 when this indicates the channel has started talking set to 0 * when this indicates the channel has stopped talking. */ void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking); diff --git a/include/asterisk/ccss.h b/include/asterisk/ccss.h index acb3148c7..cf2f21996 100644 --- a/include/asterisk/ccss.h +++ b/include/asterisk/ccss.h @@ -1365,8 +1365,8 @@ int ast_cc_monitor_count(const char * const name, const char * const type); * The code in the core will take care of making sure that the information gets passed * up the ladder correctly. * - * \param core_id The core ID of the corresponding CC transaction - * \param debug + * \par core_id The core ID of the corresponding CC transaction + * \par debug * \retval 0 Request successfully queued * \retval -1 Request could not be queued */ @@ -1482,7 +1482,7 @@ int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan); /*! * \since 1.8 * \brief Set the CC_INTERFACES channel variable for a channel using an - * extension@context as a starting point + * \verbatim extension@context \endverbatim as a starting point * * \details * The CC_INTERFACES channel variable will have the interfaces that should be @@ -1498,7 +1498,7 @@ int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan); * * \param chan The channel to set the CC_INTERFACES variable on * \param extension The name of the extension for which we're setting the variable. - * This should be in the form of "exten@context" + * This should be in the form of \verbatim exten@context \endverbatim */ int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension); diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index abfe18139..3641a1be2 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -1280,7 +1280,7 @@ struct ast_channel *ast_request(const char *type, struct ast_format_cap *request * by the low level module and attempt to place a call on it * * \param type type of channel to request - * \param format capabilities for requested channel + * \param cap format capabilities for requested channel * \param requestor channel asking for data * \param addr destination of the call * \param timeout maximum amount of time to wait for an answer @@ -1298,7 +1298,7 @@ struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap * \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 capabilities for requested channel + * \param cap format capabilities for requested channel * \param requestor channel requesting data * \param addr destination of the call * \param timeout maximum amount of time to wait for an answer @@ -1317,7 +1317,7 @@ struct ast_channel *__ast_request_and_dial(const char *type, struct ast_format_c * \param caller in channel that requested orig * \param orig channel being replaced by the call forward channel * \param timeout maximum amount of time to wait for setup of new forward channel - * \param format capabilities for requested channel + * \param cap format capabilities for requested channel * \param oh outgoing helper used with original channel * \param outstate reason why unsuccessful (if uncuccessful) * \return Returns the forwarded call's ast_channel on success or NULL on failure @@ -1794,7 +1794,7 @@ int ast_set_read_format_from_cap(struct ast_channel *chan, struct ast_format_cap /*! * \brief Sets read format on channel chan * \param chan channel to change - * \param formats, format to set for reading + * \param format format to set for reading * \return Returns 0 on success, -1 on failure */ int ast_set_read_format(struct ast_channel *chan, struct ast_format *format); @@ -1802,7 +1802,7 @@ int ast_set_read_format(struct ast_channel *chan, struct ast_format *format); /*! * \brief Sets read format on channel chan by id * \param chan channel to change - * \param format id to set for reading, only used for formats without attributes + * \param id format id to set for reading, only used for formats without attributes * \return Returns 0 on success, -1 on failure */ int ast_set_read_format_by_id(struct ast_channel *chan, enum ast_format_id id); @@ -1819,7 +1819,7 @@ int ast_set_write_format_from_cap(struct ast_channel *chan, struct ast_format_ca /*! * \brief Sets write format on channel chan * \param chan channel to change - * \param formats, format to set for writing + * \param format format to set for writing * \return Returns 0 on success, -1 on failure */ int ast_set_write_format(struct ast_channel *chan, struct ast_format *format); @@ -1827,7 +1827,7 @@ int ast_set_write_format(struct ast_channel *chan, struct ast_format *format); /*! * \brief Sets write format on channel chan * \param chan channel to change - * \param format id to set for writing, only used for formats without attributes + * \param id format id to set for writing, only used for formats without attributes * \return Returns 0 on success, -1 on failure */ int ast_set_write_format_by_id(struct ast_channel *chan, enum ast_format_id id); @@ -2100,7 +2100,7 @@ int ast_channel_setoption(struct ast_channel *channel, int option, void *data, i /*! * \brief Pick the best codec * - * \param capabilities to pick best codec out of + * \param cap capabilities to pick best codec out of * \param result stucture to store the best codec in. * \retval on success, pointer to result structure * \retval on failure, NULL diff --git a/include/asterisk/config.h b/include/asterisk/config.h index 1f4ce2970..cd29bb362 100644 --- a/include/asterisk/config.h +++ b/include/asterisk/config.h @@ -193,7 +193,7 @@ struct ast_variable *ast_category_root(struct ast_config *config, char *cat); * \brief Sorts categories in a config in the order of a numerical value contained within them. * * \param config The config structure you wish to sort - * \param variable Which numerical value you wish to sort by + * \param comparator variable Which numerical value you wish to sort by * \param descending If true, we sort highest to lowest instead of lowest to highest * * \details @@ -741,9 +741,9 @@ enum ast_parse_flags { * * \param arg the string to parse. It is not modified. * \param flags combination of ast_parse_flags to specify the - * return type and additional checks. + * return type and additional checks. * \param result pointer to the result. NULL is valid here, and can - * be used to perform only the validity checks. + * be used to perform only the validity checks. * \param ... extra arguments are required according to flags. * * \retval 0 in case of success, != 0 otherwise. @@ -841,7 +841,7 @@ int ast_rq_is_int(require_type type), * \param chunk Data to be decoded * \return The decoded data, in the original buffer * \since 1.8 - * \warn This function modifies the original buffer + * \warning This function modifies the original buffer */ char *ast_realtime_decode_chunk(char *chunk); diff --git a/include/asterisk/config_options.h b/include/asterisk/config_options.h index 6de8d28cf..1b0beb206 100644 --- a/include/asterisk/config_options.h +++ b/include/asterisk/config_options.h @@ -176,7 +176,6 @@ void *aco_pending_config(struct aco_info *info); /*! \def CONFIG_INFO_STANDARD * \brief Declare an aco_info struct with default module and preload values * \param name The name of the struct - * \param fn The filename of the config * \param arr The global object array for holding the user-defined config object * \param alloc The allocater for the user-defined config object * @@ -462,7 +461,6 @@ enum aco_process_status aco_process_config(struct aco_info *info, int reload); * \param info The aco_info to be used for handling the config * \param file The file attached to aco_info that the config represents * \param cfg A pointer to a loaded ast_config to parse - * \param reload Whether or not this is a reload * * \retval ACO_PROCESS_OK Success * \retval ACO_PROCESS_ERROR Failure @@ -496,7 +494,7 @@ int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable int aco_process_category_options(struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj); /*! \brief Set all default options of \a obj - * \param info The aco_type with the options + * \param type The aco_type with the options * \param category The configuration category from which \a obj is being configured * \param obj The object being configured * @@ -511,11 +509,12 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj); * * \param info The aco_info holding this module's config information * \param name The name of the option + * \param match_type * \param types An array of valid option types for matching categories to the correct struct type * \param default_val The default value of the option in the same format as defined in a config file * \param type The option type (only for default handlers) * \param handler The handler function for the option (only for non-default types) - * \param flags \a type specific flags, stored in the option and available to the handler + * \param flags a type specific flags, stored in the option and available to the handler * \param argc The number for variadic arguments * \param ... field offsets to store for default handlers * @@ -528,10 +527,12 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc /*! \brief Register a config option * \param info A pointer to the aco_info struct * \param name The name of the option + * \param matchtype * \param types An array of valid option types for matching categories to the correct struct type * \param default_val The default value of the option in the same format as defined in a config file * \param opt_type The option type for default option type handling - * \param flags \a type specific flags, stored in the option and available to the handler + * \param flags a type specific flags, stored in the option and available to the handler + * \param ... * * \retval 0 Success * \retval -1 Failure @@ -542,6 +543,7 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc /*! \brief Register a config option * \param info A pointer to the aco_info struct * \param name The name of the option + * \param matchtype * \param types An array of valid option types for matching categories to the correct struct type * \param default_val The default value of the option in the same format as defined in a config file * \param handler The handler callback for the option @@ -570,14 +572,15 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * passed in. It is currently limited to 8 arguments, but 8 variadic * arguments, like 640K, should be good enough for anyone. If not, it is * easy to add more. - * */ + * + */ -/*! \def ARGMAP(func, func_arg, x, ...) +/*! * \brief Map \a func(\a func_arg, field) across all fields including \a x * \param func The function (almost certainly offsetof) to map across the fields * \param func_arg The first argument (almost certainly a type (e.g. "struct mystruct") * \param x The first field - * \param varargs The rest of the fields + * \param ... varargs The rest of the fields * * Example usage: * \code @@ -588,17 +591,19 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * }; * ARGMAP(offsetof, struct foo, a, c) * \endcode + * * produces the string: + * * \code * 2, offsetof(struct foo, a), offsetof(struct foo, b) - * \encode + * \endcode * which can be passed as the varargs to some other function * * The macro isn't limited to offsetof, but that is the only purpose for * which it has been tested. * * As an example of how the processing works: - * + * \verbatim * ARGMAP(offsetof, struct foo, a, b, c) -> * ARGMAP_(3, offsetof, struct foo, a, b, c) -> * ARGMAP_3(offsetof, struct foo, 3, a, b, c) -> @@ -606,12 +611,15 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) -> * ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) -> * 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c) + * \endverbatim + * */ #define ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__) /*! \note This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so * that the accumulation both works properly for the first argument (since "in" can't be empty) and - * we get the number of arguments in our varargs as a bonus */ + * we get the number of arguments in our varargs as a bonus + */ #define ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__) /*! \def PASTE(arg1, arg2) @@ -629,7 +637,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * \param func_arg The first argument to func (most likely a type e.g. "struct my_struct") * \param in The accumulated function-mapped field names so far * \param x The next field name - * \param varargs The rest of the field names + * \param ... varargs The rest of the field names */ #define ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x)) #define ARGMAP_2(func, func_arg, in, x, ...)\ @@ -651,18 +659,19 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * \brief Results in the number of arguments passed to it * \note Currently only up to 8, but expanding is easy. This macro basically counts * commas + 1. To visualize: - * + * \verbatim * VA_NARGS(one, two, three) -> v * VA_NARGS1(one, two, three, 8, 7, 6, 5, 4, 3, 2, 1, 0) -> * VA_NARGS1( _1, _2, _3, _4, _5, _6, _7, _8, N, ... ) N -> 3 - * + * * Note that VA_NARGS *does not* work when there are no arguments passed. Pasting an empty * __VA_ARGS__ with a comma like ", ##__VA_ARGS__" will delete the leading comma, but it * does not work when __VA_ARGS__ is the first argument. Instead, 1 is returned instead of 0: - * + * * VA_NARGS() -> v * VA_NARGS1( , 8, 7, 6, 5, 4, 3, 2, 1, 0) -> * VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N) -> 1 + * \endverbatim */ #define VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0) #define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N @@ -670,7 +679,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru /*! \def FLDSET(type, ...) * \brief Convert a struct and list of fields to an argument list of field offsets * \param type The type with the fields (e.g. "struct my_struct") - * \param varags The fields in the struct whose offsets are needed as arguments + * \param ... varags The fields in the struct whose offsets are needed as arguments * * For example: * \code @@ -692,7 +701,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * default stringfield option handler, so registering options that point to stringfields requires * this macro to be called instead of the FLDSET macro. * \param type The type with the fields (e.g. "struct my_struct") - * \param varargs The fields in the struct whose offsets are needed as arguments + * \param ... varargs The fields in the struct whose offsets are needed as arguments */ #define STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr) @@ -710,9 +719,10 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru * FLDSET. This is because a call to FLDSET may be followed by additional arguments in * aco_register_option, so the true number of arguments will possibly be different than what * ARGMAP returns. - * \params varags A list of arguments - * + * \param ... varags A list of arguments + * \verbatim * POPPED(a, b, c) -> b, c + * \endverbatim */ #define POPPED(...) POPPED1(__VA_ARGS__) #define POPPED1(x, ...) __VA_ARGS__ diff --git a/include/asterisk/crypto.h b/include/asterisk/crypto.h index 1f87811f4..c911404d7 100644 --- a/include/asterisk/crypto.h +++ b/include/asterisk/crypto.h @@ -46,8 +46,8 @@ struct ast_key; /*! * \brief Retrieve a key - * \param name of the key we are retrieving - * \param int type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE) + * \param key Name of the key we are retrieving + * \param type Intger type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE) * * \retval the key on success. * \retval NULL on failure. @@ -70,6 +70,7 @@ AST_OPTIONAL_API(int, ast_check_signature, (struct ast_key *key, const char *msg * \brief Check the authenticity of a message signature using a given public key * \param key a public key to use to verify * \param msg the message that has been signed + * \param msglen * \param sig the proposed valid signature in raw binary representation * * \retval 0 if the signature is valid. @@ -95,6 +96,7 @@ AST_OPTIONAL_API(int, ast_sign, (struct ast_key *key, char *msg, char *sig), { r * \brief Sign a message signature using a given private key * \param key a private key to use to create the signature * \param msg the message to sign + * \param msglen * \param sig a pointer to a buffer of at least 128 bytes in which the * raw encoded signature will be stored * diff --git a/include/asterisk/datastore.h b/include/asterisk/datastore.h index 5f7e52348..9060a5f82 100644 --- a/include/asterisk/datastore.h +++ b/include/asterisk/datastore.h @@ -63,6 +63,7 @@ struct ast_datastore { * \brief Create a data store object * \param[in] info information describing the data store object * \param[in] uid unique identifer + * \param file, line, function * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc */ struct ast_datastore * attribute_malloc __ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid, diff --git a/include/asterisk/format.h b/include/asterisk/format.h index 61ddf9041..961b2c124 100644 --- a/include/asterisk/format.h +++ b/include/asterisk/format.h @@ -264,9 +264,9 @@ void ast_format_sdp_generate(const struct ast_format *format, unsigned int paylo * with optional format attributes represented by format specific key value pairs. * * \param format to set - * \param id, format id to set on format + * \param id format id to set on format * \param set_attributes, are there attributes to set on this format. 0 == false, 1 == True. - * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; + * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; * * \details Example usage. * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW @@ -290,7 +290,7 @@ struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id * set additional format attributes to the structure. * * \param format to set - * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; + * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; * * \details Example usage. * ast_format_set(format, AST_FORMAT_SILK, 0); @@ -421,7 +421,7 @@ const char* ast_getformatname(const struct ast_format *format); /*! \brief Returns a string containing all formats pertaining to an format id. * \param buf a buffer for the output string * \param size size of buf (bytes) - * \param format id. + * \param id format id. * \return The return value is buf. */ char* ast_getformatname_multiple_byid(char *buf, size_t size, enum ast_format_id id); diff --git a/include/asterisk/format_cap.h b/include/asterisk/format_cap.h index 234767685..fc56d8b35 100644 --- a/include/asterisk/format_cap.h +++ b/include/asterisk/format_cap.h @@ -119,7 +119,7 @@ int ast_format_cap_is_empty(const struct ast_format_cap *cap); /*! * \brief Remove format capability from capability structure. * - * \Note format must match Exactly to format in ast_format_cap object in order + * \note format must match Exactly to format in ast_format_cap object in order * to be removed. * * \retval 0, remove was successful @@ -131,7 +131,7 @@ int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format) * \brief Remove all format capabilities from capability * structure for a specific format id. * - * \Note This will remove _ALL_ formats matching the format id from the + * \note This will remove _ALL_ formats matching the format id from the * capabilities structure. * * \retval 0, remove was successful @@ -263,7 +263,7 @@ void ast_format_cap_iter_start(struct ast_format_cap *cap); * } * ast_format_cap_iter_end(Cap); * - * \Note Unless the container was alloced using no_lock, the container + * \note Unless the container was alloced using no_lock, the container * will be locked during the entire iteration until ast_format_cap_iter_end * is called. XXX Remember this, and do not attempt to lock any containers * within this iteration that will violate locking order. @@ -298,7 +298,7 @@ void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src); /*! \brief Get the names of a set of formats * \param buf a buffer for the output string * \param size size of buf (bytes) - * \param format the format (combined IDs of codecs) + * \param cap format the format (combined IDs of codecs) * Prints a list of readable codec names corresponding to "format". * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)" * \return The return value is buf. diff --git a/include/asterisk/format_pref.h b/include/asterisk/format_pref.h index b034c18be..9a7e06741 100644 --- a/include/asterisk/format_pref.h +++ b/include/asterisk/format_pref.h @@ -59,9 +59,9 @@ void ast_codec_pref_init(struct ast_codec_pref *pref); /*! * \brief Codec located at a particular place in the preference index. - * \param preference structure to get the codec out of + * \param pref preference structure to get the codec out of * \param index to retrieve from - * \param retult ast_format structure to store the index value in + * \param result ast_format structure to store the index value in * \return pointer to input ast_format on success, NULL on failure */ struct ast_format *ast_codec_pref_index(struct ast_codec_pref *pref, int index, struct ast_format *result); diff --git a/include/asterisk/framehook.h b/include/asterisk/framehook.h index 0b2e6cd95..52993b55c 100644 --- a/include/asterisk/framehook.h +++ b/include/asterisk/framehook.h @@ -219,9 +219,9 @@ struct ast_framehook_interface { * \brief Attach an framehook onto a channel for frame interception. * \since 1.8 * - * \param ast_channel, The channel to attach the hook on to. - * \param framehook interface, The framehook's callback functions and stored data. -* + * \param chan ast_channel The channel to attach the hook on to. + * \param i framehook interface, The framehook's callback functions and stored data. + * * \pre XXX The Channel must be locked during this function all. * * \note The data pointer is never touched by the framehook API except to @@ -242,8 +242,8 @@ int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interfac * the framehook will be detached and destroyed during channel * destruction. * - * \param The channel the framehook is attached to - * \param The framehook's id + * \param chan The channel the framehook is attached to + * \param framehook_id The framehook's id * * \retval 0 success * \retval -1 framehook did not exist on the channel. This means the @@ -258,7 +258,7 @@ int ast_framehook_detach(struct ast_channel *chan, int framehook_id); * * \pre XXX The Channel must be locked during this function all. * - * \param channel containing the framehook list to destroy. + * \param chan channel containing the framehook list to destroy. * \retval 0 success * \retval -1 failure */ @@ -274,7 +274,7 @@ int ast_framehook_list_destroy(struct ast_channel *chan); * * \pre XXX The Channel must be locked during this function all. * - * \param framehook list to push event to. + * \param framehooks list to push event to. * \param frame being pushed to the framehook list. * * \return The resulting frame after being viewed and modified by the framehook callbacks. @@ -291,7 +291,7 @@ struct ast_frame *ast_framehook_list_read_event(struct ast_framehook_list *frame * * \pre XXX The Channel must be locked during this function all. * - * \param framehook list to push event to. + * \param framehooks list to push event to. * \param frame being pushed to the framehook list. * * \return The resulting frame after being viewed and modified by the framehook callbacks. @@ -303,7 +303,7 @@ struct ast_frame *ast_framehook_list_write_event(struct ast_framehook_list *fram * \since 1.8 * \pre XXX The Channel must be locked during this function all. * - * \param the framehook list + * \param framehooks the framehook list * \retval 0, not empty * \retval 1, is empty */ diff --git a/include/asterisk/heap.h b/include/asterisk/heap.h index 86f4e3d5c..a868ac589 100644 --- a/include/asterisk/heap.h +++ b/include/asterisk/heap.h @@ -213,6 +213,7 @@ size_t ast_heap_size(struct ast_heap *h); * \brief Write-Lock a heap * * \param h the heap + * \param file, func, line * * A lock is provided for convenience. It can be assumed that none of the * ast_heap API calls are thread safe. This lock does not have to be used @@ -227,6 +228,7 @@ int __ast_heap_wrlock(struct ast_heap *h, const char *file, const char *func, in * \brief Read-Lock a heap * * \param h the heap + * \param file, func, line * * A lock is provided for convenience. It can be assumed that none of the * ast_heap API calls are thread safe. This lock does not have to be used @@ -241,6 +243,7 @@ int __ast_heap_rdlock(struct ast_heap *h, const char *file, const char *func, in * \brief Unlock a heap * * \param h the heap + * \param file, func, line * * \return see the documentation for pthread_rwlock_unlock() * \since 1.6.1 diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h index 257e939cf..fd58b7ae7 100644 --- a/include/asterisk/manager.h +++ b/include/asterisk/manager.h @@ -247,7 +247,9 @@ int astman_verify_session_writepermissions(uint32_t ident, int perm); * \param event Event name * \param chancount Number of channels in chans parameter * \param chans A pointer to an array of channels involved in the event + * \param file, line, func * \param contents Format string describing event + * \param ... * \since 1.8 */ int __ast_manager_event_multichan(int category, const char *event, int chancount, diff --git a/include/asterisk/message.h b/include/asterisk/message.h index 31ed0b28a..d1f0bd722 100644 --- a/include/asterisk/message.h +++ b/include/asterisk/message.h @@ -167,6 +167,7 @@ int __attribute__((format(printf, 2, 3))) * \brief Set a variable on the message going to the dialplan. * \note Setting a variable that already exists overwrites the existing variable value * + * \param msg * \param name Name of variable to set * \param value Value of variable to set * @@ -179,6 +180,7 @@ int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value); * \brief Set a variable on the message being sent to a message tech directly. * \note Setting a variable that already exists overwrites the existing variable value * + * \param msg * \param name Name of variable to set * \param value Value of variable to set * diff --git a/include/asterisk/netsock2.h b/include/asterisk/netsock2.h index b14c1af97..435eda53d 100644 --- a/include/asterisk/netsock2.h +++ b/include/asterisk/netsock2.h @@ -73,7 +73,7 @@ struct ast_sockaddr { * if you know what you're doing. * * \param addr The IPv4-mapped address to convert - * \param mapped_addr The resulting IPv4 address + * \param ast_mapped The resulting IPv4 address * \retval 0 Unable to make the conversion * \retval 1 Successful conversion */ @@ -310,10 +310,10 @@ static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr) * \brief * Splits a string into its host and port components * - * \param str[in] The string to parse. May be modified by writing a NUL at the end of + * \param[in] str The string to parse. May be modified by writing a NUL at the end of * the host part. - * \param host[out] Pointer to the host component within \a str. - * \param port[out] Pointer to the port component within \a str. + * \param[out] host Pointer to the host component within \a str. + * \param[out] port Pointer to the port component within \a str. * \param flags If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a * port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE, * a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT @@ -467,7 +467,7 @@ int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr); * \brief * Determine if an IPv4 address is a multicast address * - * \parm addr the address to check + * \param addr the address to check * * This function checks if an address is in the 224.0.0.0/4 network block. * @@ -647,9 +647,9 @@ int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr, /*! * \since 1.8 * - * \brief - * Converts a struct sockaddr_in to a struct ast_sockaddr. + * \brief Converts a struct sockaddr_in to a struct ast_sockaddr. * + * \param addr * \param sin The sockaddr_in to convert * \return an ast_sockaddr structure */ diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index 7e374345c..c20e2b873 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -821,7 +821,7 @@ int ast_context_add_include(const char *context, const char *include, * \brief Add a context include * * \param con context to add the include to - * \param include include to add + * \param value include include to add * \param registrar who registered the context * * Adds an include taking a struct ast_context as the first parameter diff --git a/include/asterisk/presencestate.h b/include/asterisk/presencestate.h index dbbe5dcab..6c6a6a48b 100644 --- a/include/asterisk/presencestate.h +++ b/include/asterisk/presencestate.h @@ -62,9 +62,9 @@ enum ast_presence_state ast_presence_state_val(const char *val); /*! * \brief Asks a presence state provider for the current presence state. * - * \param presence_provider, The presence provider to retrieve the state from. - * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned - * \param message, The output paramenter to store the message string in. Must be freed if returned + * \param presence_provider The presence provider to retrieve the state from. + * \param subtype The output paramenter to store the subtype string in. Must be freed if returned + * \param message The output paramenter to store the message string in. Must be freed if returned * * \retval presence state value on success, * \retval -1 on failure. @@ -78,9 +78,9 @@ enum ast_presence_state ast_presence_state(const char *presence_provider, char * * requested (such as a base64 decode). In such instances, use of the event cache is not suitable * and should be bypassed. * - * \param presence_provider, The presence provider to retrieve the state from. - * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned - * \param message, The output paramenter to store the message string in. Must be freed if returned + * \param presence_provider The presence provider to retrieve the state from. + * \param subtype The output paramenter to store the subtype string in. Must be freed if returned + * \param message The output paramenter to store the message string in. Must be freed if returned * * \retval presence state value on success, * \retval -1 on failure. diff --git a/include/asterisk/rtp_engine.h b/include/asterisk/rtp_engine.h index d71311114..c1b21b6ed 100644 --- a/include/asterisk/rtp_engine.h +++ b/include/asterisk/rtp_engine.h @@ -1164,7 +1164,7 @@ struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *code * \brief Get the sample rate associated with known RTP payload types * * \param asterisk_format True if the value in format is to be used. - * \param An asterisk format + * \param format An asterisk format * \param code from AST_RTP list * * \return the sample rate if the format was found, zero if it was not found @@ -1815,7 +1815,7 @@ void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int ti * \brief Set the RTP keepalive interval * * \param instance The RTP instance - * \param period Value to set the keepalive interval to + * \param timeout Value to set the keepalive interval to * * Example usage: * diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h index 7d8069032..6861477f1 100644 --- a/include/asterisk/strings.h +++ b/include/asterisk/strings.h @@ -804,6 +804,8 @@ AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct a * \brief Append to a dynamic string using a va_list * * Same as ast_str_set_va(), but append to the current content. + * + * \param buf, max_len, fmt, ap */ AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap), { diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h index 8545f0ae5..602c3097c 100644 --- a/include/asterisk/translate.h +++ b/include/asterisk/translate.h @@ -236,7 +236,7 @@ struct ast_trans_pvt; * \brief Register a translator * This registers a codec translator with asterisk * \param t populated ast_translator structure - * \param module handle to the module that owns this translator + * \param mod module handle to the module that owns this translator * \return 0 on success, -1 on failure */ int __ast_register_translator(struct ast_translator *t, struct ast_module *module); @@ -276,10 +276,10 @@ void ast_translator_deactivate(struct ast_translator *t); * Given a list of sources, and a designed destination format, which should * I choose? * - * \param destination capabilities - * \param source capabilities - * \param destination format chosen out of destination capabilities - * \param source format chosen out of source capabilities + * \param dst_cap destination capabilities + * \param src_cap source capabilities + * \param dst_fmt_out destination format chosen out of destination capabilities + * \param src_fmt_out source format chosen out of source capabilities * \return Returns 0 on success, -1 if no path could be found. * * \note dst_cap and src_cap are not mondified. @@ -292,8 +292,8 @@ int ast_translator_best_choice(struct ast_format_cap *dst_cap, /*! * \brief Builds a translator path * Build a path (possibly NULL) from source to dest - * \param dest destination format - * \param source source format + * \param dst dest destination format + * \param src source source format * \return ast_trans_pvt on success, NULL on failure * */ struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source); @@ -309,7 +309,7 @@ void ast_translator_free_path(struct ast_trans_pvt *tr); * \brief translates one or more frames * Apply an input frame into the translator and receive zero or one output frames. Consume * determines whether the original frame should be freed - * \param tr translator structure to use for translation + * \param path tr translator structure to use for translation * \param f frame to translate * \param consume Whether or not to free the original frame * \return an ast_frame of the new translation format on success, NULL on failure @@ -342,8 +342,8 @@ void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_for /*! * \brief Puts a string representation of the translation path into outbuf - * \param translator structure containing the translation path - * \param ast_str output buffer + * \param t translator structure containing the translation path + * \param str ast_str output buffer * \retval on success pointer to beginning of outbuf. on failure "". */ const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str); diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h index a417cf4d3..014a62ec5 100644 --- a/include/asterisk/utils.h +++ b/include/asterisk/utils.h @@ -858,7 +858,6 @@ int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2); /*! * \brief Get current thread ID - * \param None * \return the ID if platform is supported, else -1 */ int ast_get_tid(void); @@ -897,12 +896,14 @@ char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size); * RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup); * ... * } + * \endcode * * \note This macro is especially useful for working with ao2 objects. A common idiom * would be a function that needed to look up an ao2 object and might have several error * conditions after the allocation that would normally need to unref the ao2 object. * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor * function. For example: + * * \code * void do_stuff(const char *name) * { @@ -915,7 +916,7 @@ char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size); * } * do_stuff_with_thing(thing); * } - * \encode + * \endcode */ #define RAII_VAR(vartype, varname, initval, dtor) \ auto void _dtor_ ## varname (vartype * v); \ |