sysmocom
/
asterisk
11
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

main: Fix for Doxygen. 

ASTERISK-29763

Change-Id: Ib8359e3590a9109eb04a5376559d040e5e21867e
This commit is contained in:
Alexander Traud 2021-11-19 16:47:25 +01:00 committed by Friendly Automation
parent cc025026b7
commit 9440f6ec58
129 changed files with 1138 additions and 1573 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
include/asterisk/_private.h
View File

@ -61,15 +61,11 @@ int dns_core_init(void); /*!< Provided by dns_core.c */
* \brief Initialize malloc debug phase 1.
*
* \note Must be called first thing after forking.
*
* \return Nothing
*/
void load_astmm_phase_1(void);
/*!
* \brief Initialize malloc debug phase 2.
*
* \return Nothing
*/
void load_astmm_phase_2(void);

16
include/asterisk/acl.h
View File

@ -83,7 +83,6 @@ AST_LIST_HEAD(ast_acl_list, ast_acl);
* HAs are freed
*
* \param ha The head of the list of HAs to free
* \retval void
*/
void ast_free_ha(struct ast_ha *ha);
@ -109,7 +108,6 @@ struct ast_acl_list *ast_free_acl_list(struct ast_acl_list *acl);
*
* \param from Source HA to copy
* \param to Destination HA to copy to
* \retval void
*/
void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
@ -195,8 +193,8 @@ void ast_append_acl(const char *sense, const char *stuff, struct ast_acl_list **
* \brief Determines if an ACL is empty or if it contains entries
*
* \param acl_list The ACL list being checked
* \retval 0 - the list is not empty
* \retval 1 - the list is empty
* \retval 0 the list is not empty
* \retval 1 the list is empty
*/
int ast_acl_list_is_empty(struct ast_acl_list *acl_list);
@ -318,7 +316,7 @@ int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
*
* \param iface The interface name whose IP address we wish to find
* \param[out] address The interface's IP address is placed into this param
* \retval -1 Failure. address is filled with 0s
* \retval -1 Failure, address is filled with 0s
* \retval 0 Success
*/
int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
@ -332,7 +330,7 @@ int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
* of the input parameter when finished.
*
* \param original The ast_ha to copy
* \retval The head of the list of duplicated ast_has
* \return The head of the list of duplicated ast_has
*/
struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
@ -346,7 +344,7 @@ struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
* finished.
*
* \param original The ast_acl_list to copy
* \retval The new duplicated ast_acl_list
* \return The new duplicated ast_acl_list
*/
struct ast_acl_list *ast_duplicate_acl_list(struct ast_acl_list *original);
@ -413,7 +411,7 @@ const char *ast_tos2str(unsigned int tos);
* \param[out] is_realtime will be true if the ACL being returned is from realtime
* \param[out] is_undefined will be true if no ACL profile can be found for the requested name
*
* \retval A copy of the named ACL as an ast_ha
* \return A copy of the named ACL as an ast_ha
* \retval NULL if no ACL could be found.
*/
struct ast_ha *ast_named_acl_find(const char *name, int *is_realtime, int *is_undefined);
@ -423,7 +421,7 @@ struct ast_ha *ast_named_acl_find(const char *name, int *is_realtime, int *is_un
* \since 12
*
* \retval NULL on error
* \retval \ref stasis_message_type for named ACL changes
* \return \ref stasis_message_type for named ACL changes
*
* \note Messages of this type should always be issued on and expected from the
* \ref ast_security_topic \ref stasis_topic

35
include/asterisk/alertpipe.h
View File

@ -32,9 +32,10 @@ typedef enum {
* \brief Initialize an alert pipe
* \since 13.16.0
*
* \param p a two-element array to hold the alert pipe's file descriptors
* \param alert_pipe a two-element array to hold the alert pipe's file descriptors
*
* \return non-zero if a failure occurred, zero otherwise.
* \retval non-zero if a failure occurred.
* \retval zero otherwise.
*/
int ast_alertpipe_init(int alert_pipe[2]);
@ -42,7 +43,7 @@ int ast_alertpipe_init(int alert_pipe[2]);
* \brief Close an alert pipe
* \since 13.16.0
*
* \param p a two-element containing the alert pipe's file descriptors
* \param alert_pipe a two-element containing the alert pipe's file descriptors
*/
void ast_alertpipe_close(int alert_pipe[2]);
@ -50,7 +51,7 @@ void ast_alertpipe_close(int alert_pipe[2]);
* \brief Read an event from an alert pipe
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \retval AST_ALERT_READ_SUCCESS on success
* \retval AST_ALERT_NOT_READABLE if the alert pipe is not readable
@ -63,7 +64,7 @@ ast_alert_status_t ast_alertpipe_read(int alert_pipe[2]);
* \brief Write an event to an alert pipe
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \retval 0 Success
* \retval 1 Failure
@ -74,7 +75,7 @@ ssize_t ast_alertpipe_write(int alert_pipe[2]);
* \brief Consume all alerts written to the alert pipe
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \retval AST_ALERT_READ_SUCCESS on success
* \retval AST_ALERT_NOT_READABLE if the alert pipe is not readable
@ -87,7 +88,7 @@ ast_alert_status_t ast_alertpipe_flush(int alert_pipe[2]);
* \brief Sets the alert pipe file descriptors to default values
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*/
AST_INLINE_API(
void ast_alertpipe_clear(int alert_pipe[2]),
@ -100,9 +101,10 @@ void ast_alertpipe_clear(int alert_pipe[2]),
* \brief Determine if the alert pipe is readable
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \return non-zero if the alert pipe is readable, zero otherwise.
* \retval non-zero if the alert pipe is readable.
* \retval zero otherwise.
*/
AST_INLINE_API(
int attribute_pure ast_alertpipe_readable(int alert_pipe[2]),
@ -115,9 +117,10 @@ int attribute_pure ast_alertpipe_readable(int alert_pipe[2]),
* \brief Determine if the alert pipe is writable
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \return non-zero if the alert pipe is writable, zero otherwise.
* \retval non-zero if the alert pipe is writable.
* \retval zero otherwise.
*/
AST_INLINE_API(
int attribute_pure ast_alertpipe_writable(int alert_pipe[2]),
@ -130,10 +133,10 @@ int attribute_pure ast_alertpipe_writable(int alert_pipe[2]),
* \brief Get the alert pipe's read file descriptor
* \since 13.16.0
*
* \param p a two-element array containing the alert pipe's file descriptors
* \param alert_pipe a two-element array containing the alert pipe's file descriptors
*
* \return -1 if the file descriptor is not initialized, a non-negative value
* otherwise.
* \retval -1 if the file descriptor is not initialized.
* \retval non-negative otherwise.
*/
AST_INLINE_API(
int attribute_pure ast_alertpipe_readfd(int alert_pipe[2]),
@ -146,8 +149,8 @@ int attribute_pure ast_alertpipe_readfd(int alert_pipe[2]),
* \brief Swap the file descriptors from two alert pipes
* \since 13.16.0
*
* \param p1 a two-element array containing an alert pipe's file descriptors
* \param p2 a two-element array containing an alert pipe's file descriptors
* \param alert_pipe_1 a two-element array containing an alert pipe's file descriptors
* \param alert_pipe_2 a two-element array containing an alert pipe's file descriptors
*/
AST_INLINE_API(
void ast_alertpipe_swap(int alert_pipe_1[2], int alert_pipe_2[2]),

177
include/asterisk/astobj2.h
View File

@ -71,11 +71,11 @@ On return from ao2_alloc():
causing the destructor to be called (and then memory freed) when
the refcount goes to 0.
- ao2_ref(o, +1) can be used to modify the refcount on the
object in case we want to pass it around.
ao2_ref(o, +1) can be used to modify the refcount on the
object in case we want to pass it around.
- ao2_lock(obj), ao2_unlock(obj), ao2_trylock(obj) can be used
to manipulate the lock associated with the object.
ao2_lock(obj), ao2_unlock(obj), ao2_trylock(obj) can be used
to manipulate the lock associated with the object.
\section AstObj2_UsageContainers USAGE - CONTAINERS
@ -354,8 +354,6 @@ murf
* This is called just before freeing the memory for the object.
* It is passed a pointer to the user-defined data of the
* object.
*
* \return Nothing
*/
typedef void (*ao2_destructor_fn)(void *vdoomed);
@ -423,7 +421,7 @@ void *__ao2_alloc(size_t data_size, ao2_destructor_fn destructor_fn, unsigned in
* \param data_size The sizeof() of the user-defined structure.
* \param destructor_fn The destructor function (can be NULL)
* \param lockobj A separate ao2 object that will provide locking.
* \param debug_msg An ao2 object debug tracing message.
* \param tag An ao2 object debug tracing message.
* \return A pointer to user-data.
*
* \see \ref ao2_alloc for additional details.
@ -441,7 +439,6 @@ void *__ao2_alloc_with_lockobj(size_t data_size, ao2_destructor_fn destructor_fn
*
* \param o A pointer to the object
* \param delta Value to add to the reference counter.
* \param tag used for debugging
* \return The value of the reference counter before the operation.
*
* Increase/decrease the reference counter according
@ -459,9 +456,8 @@ void *__ao2_alloc_with_lockobj(size_t data_size, ao2_destructor_fn destructor_fn
*
* @{
*/
#define ao2_t_ref(o,delta,tag) __ao2_ref((o), (delta), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_ref(o,delta) __ao2_ref((o), (delta), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_ref(o,delta,tag) __ao2_ref((o), (delta), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Retrieve the ao2 options used to create the object.
@ -478,8 +474,12 @@ unsigned int ao2_options_get(void *obj);
* count. Also \c NULL safe, for even more convenience.
*
* \param obj AO2 object to bump the refcount on.
* \retval The given \a obj pointer.
*
* \return The given \a obj pointer.
*/
#define ao2_bump(obj) \
ao2_t_bump((obj), NULL)
#define ao2_t_bump(obj, tag) \
({ \
typeof(obj) __obj_ ## __LINE__ = (obj); \
@ -488,8 +488,6 @@ unsigned int ao2_options_get(void *obj);
} \
__obj_ ## __LINE__; \
})
#define ao2_bump(obj) \
ao2_t_bump((obj), NULL)
int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, const char *func);
@ -500,6 +498,9 @@ int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, c
* \param dst Pointer to the object that will be cleaned up.
* \param src Pointer to the object replacing it.
*/
#define ao2_replace(dst, src) \
ao2_t_replace((dst), (src), NULL)
#define ao2_t_replace(dst, src, tag) \
{\
typeof(dst) *__dst_ ## __LINE__ = &dst; \
@ -514,8 +515,6 @@ int __ao2_ref(void *o, int delta, const char *tag, const char *file, int line, c
*__dst_ ## __LINE__ = __src_ ## __LINE__; \
} \
}
#define ao2_replace(dst, src) \
ao2_t_replace((dst), (src), NULL)
/*! @} */
@ -548,15 +547,15 @@ struct ao2_weakproxy {
* \note "struct ao2_weakproxy" must be the first field of any object.
* This can be done by using AO2_WEAKPROXY to declare your structure.
*/
void *__ao2_weakproxy_alloc(size_t data_size, ao2_destructor_fn destructor_fn,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
#define ao2_weakproxy_alloc(data_size, destructor_fn) \
__ao2_weakproxy_alloc(data_size, destructor_fn, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_weakproxy_alloc(data_size, destructor_fn, tag) \
__ao2_weakproxy_alloc(data_size, destructor_fn, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
void *__ao2_weakproxy_alloc(size_t data_size, ao2_destructor_fn destructor_fn,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
/*!
* \since 14.0.0
* \brief Associate weakproxy with obj.
@ -577,15 +576,15 @@ void *__ao2_weakproxy_alloc(size_t data_size, ao2_destructor_fn destructor_fn,
* \note The only way to unset an object is for it to be destroyed.
* Any call to this function while an object is already set will fail.
*/
int __ao2_weakproxy_set_object(void *weakproxy, void *obj, int flags,
const char *tag, const char *file, int line, const char *func);
#define ao2_weakproxy_set_object(weakproxy, obj, flags) \
__ao2_weakproxy_set_object(weakproxy, obj, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_weakproxy_set_object(weakproxy, obj, flags, tag) \
__ao2_weakproxy_set_object(weakproxy, obj, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int __ao2_weakproxy_set_object(void *weakproxy, void *obj, int flags,
const char *tag, const char *file, int line, const char *func);
/*!
* \since 14.0.0
* \brief Run ao2_t_ref on the object associated with weakproxy.
@ -599,15 +598,15 @@ int __ao2_weakproxy_set_object(void *weakproxy, void *obj, int flags,
*
* \return The value of the reference counter before the operation.
*/
int __ao2_weakproxy_ref_object(void *weakproxy, int delta, int flags,
const char *tag, const char *file, int line, const char *func);
#define ao2_weakproxy_ref_object(weakproxy, delta, flags) \
ao2_t_weakproxy_ref_object(weakproxy, delta, flags, NULL)
#define ao2_t_weakproxy_ref_object(weakproxy, delta, flags, tag) \
__ao2_weakproxy_ref_object(weakproxy, delta, flags, \
tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_weakproxy_ref_object(weakproxy, delta, flags) \
ao2_t_weakproxy_ref_object(weakproxy, delta, flags, NULL)
int __ao2_weakproxy_ref_object(void *weakproxy, int delta, int flags,
const char *tag, const char *file, int line, const char *func);
/*!
* \since 14.0.0
@ -619,15 +618,15 @@ int __ao2_weakproxy_ref_object(void *weakproxy, int delta, int flags,
* \return A reference to the object previously set by ao2_weakproxy_set_object.
* \retval NULL Either no object was set or the previously set object has been freed.
*/
void *__ao2_weakproxy_get_object(void *weakproxy, int flags,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
#define ao2_weakproxy_get_object(weakproxy, flags) \
__ao2_weakproxy_get_object(weakproxy, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_weakproxy_get_object(weakproxy, flags, tag) \
__ao2_weakproxy_get_object(weakproxy, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
void *__ao2_weakproxy_get_object(void *weakproxy, int flags,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
/*!
* \since 14.0.0
* \brief Request notification when weakproxy points to NULL.
@ -686,14 +685,14 @@ int ao2_weakproxy_unsubscribe(void *weakproxy, ao2_weakproxy_notification_cb cb,
*
* \return The weakproxy object
*/
void *__ao2_get_weakproxy(void *obj,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
#define ao2_get_weakproxy(obj) \
__ao2_get_weakproxy(obj, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_get_weakproxy(obj, tag) \
__ao2_get_weakproxy(obj, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
void *__ao2_get_weakproxy(void *obj,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
/*! @} */
@ -856,14 +855,11 @@ struct ao2_global_obj {
* \since 11.0
*
* \param holder Global ao2 object holder.
* \param tag used for debugging
*
* \return Nothing
*/
#define ao2_t_global_obj_release(holder, tag) \
__ao2_global_obj_replace_unref(&holder, NULL, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_global_obj_release(holder) \
__ao2_global_obj_replace_unref(&holder, NULL, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_t_global_obj_release(holder, tag) \
__ao2_global_obj_replace_unref(&holder, NULL, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
/*!
* \brief Replace an ao2 object in the global holder.
@ -871,20 +867,20 @@ struct ao2_global_obj {
*
* \param holder Global ao2 object holder.
* \param obj Object to put into the holder. Can be NULL.
* \param tag used for debugging
*
* \note This function automatically increases the reference
* count to account for the reference that the global holder now
* holds to the object.
*
* \retval Reference to previous global ao2 object stored.
* \return Reference to previous global ao2 object stored.
* \retval NULL if no object available.
*/
#define ao2_t_global_obj_replace(holder, obj, tag) \
__ao2_global_obj_replace(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_global_obj_replace(holder, obj) \
__ao2_global_obj_replace(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_t_global_obj_replace(holder, obj, tag) \
__ao2_global_obj_replace(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
void *__ao2_global_obj_replace(struct ao2_global_obj *holder, void *obj, const char *tag, const char *file, int line, const char *func, const char *name) attribute_warn_unused_result;
/*!
@ -893,7 +889,6 @@ void *__ao2_global_obj_replace(struct ao2_global_obj *holder, void *obj, const c
*
* \param holder Global ao2 object holder.
* \param obj Object to put into the holder. Can be NULL.
* \param tag used for debugging
*
* \note This function automatically increases the reference
* count to account for the reference that the global holder now
@ -903,11 +898,12 @@ void *__ao2_global_obj_replace(struct ao2_global_obj *holder, void *obj, const c
* \retval 0 The global object was previously empty
* \retval 1 The global object was not previously empty
*/
#define ao2_t_global_obj_replace_unref(holder, obj, tag) \
__ao2_global_obj_replace_unref(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_global_obj_replace_unref(holder, obj) \
__ao2_global_obj_replace_unref(&holder, (obj), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_t_global_obj_replace_unref(holder, obj, tag) \
__ao2_global_obj_replace_unref(&holder, (obj), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
int __ao2_global_obj_replace_unref(struct ao2_global_obj *holder, void *obj, const char *tag, const char *file, int line, const char *func, const char *name);
/*!
@ -915,16 +911,16 @@ int __ao2_global_obj_replace_unref(struct ao2_global_obj *holder, void *obj, con
* \since 11.0
*
* \param holder Global ao2 object holder.
* \param tag used for debugging
*
* \retval Reference to current ao2 object stored in the holder.
* \return Reference to current ao2 object stored in the holder.
* \retval NULL if no object available.
*/
#define ao2_t_global_obj_ref(holder, tag) \
__ao2_global_obj_ref(&holder, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_global_obj_ref(holder) \
__ao2_global_obj_ref(&holder, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
#define ao2_t_global_obj_ref(holder, tag) \
__ao2_global_obj_ref(&holder, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__, #holder)
void *__ao2_global_obj_ref(struct ao2_global_obj *holder, const char *tag, const char *file, int line, const char *func, const char *name) attribute_warn_unused_result;
@ -1273,9 +1269,9 @@ typedef int (ao2_hash_fn)(const void *obj, int flags);
*
* \note This function must be idempotent.
*
* \retval <0 if obj_left < obj_right
* \retval =0 if obj_left == obj_right
* \retval >0 if obj_left > obj_right
* \retval negtaive if obj_left < obj_right
* \retval 0 if obj_left == obj_right
* \retval positive if obj_left > obj_right
*/
typedef int (ao2_sort_fn)(const void *obj_left, const void *obj_right, int flags);
@ -1299,17 +1295,16 @@ struct ao2_container;
* \param hash_fn Pointer to a function computing a hash value. (NULL if everyting goes in first bucket.)
* \param sort_fn Pointer to a sort function. (NULL to not sort the buckets.)
* \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
* \param tag used for debugging.
*
* \return A pointer to a struct container.
*
* \note Destructor is set implicitly.
*/
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn) \
__ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn, tag) \
__ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn) \
__ao2_container_alloc_hash((ao2_options), (container_options), (n_buckets), (hash_fn), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ao2_container *__ao2_container_alloc_hash(unsigned int ao2_options,
unsigned int container_options, unsigned int n_buckets, ao2_hash_fn *hash_fn,
@ -1323,18 +1318,17 @@ struct ao2_container *__ao2_container_alloc_hash(unsigned int ao2_options,
* \param container_options Container behaviour options (See enum ao2_container_opts)
* \param sort_fn Pointer to a sort function. (NULL if list not sorted.)
* \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
* \param tag used for debugging.
*
* \return A pointer to a struct container.
*
* \note Destructor is set implicitly.
* \note Implemented as a degenerate hash table.
*/
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn) \
__ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn, tag) \
__ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_container_alloc_list(ao2_options, container_options, sort_fn, cmp_fn) \
__ao2_container_alloc_list((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ao2_container *__ao2_container_alloc_list(unsigned int ao2_options,
unsigned int container_options, ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn,
@ -1347,17 +1341,16 @@ struct ao2_container *__ao2_container_alloc_list(unsigned int ao2_options,
* \param container_options Container behaviour options (See enum ao2_container_opts)
* \param sort_fn Pointer to a sort function.
* \param cmp_fn Pointer to a compare function used by ao2_find. (NULL to match everything)
* \param tag used for debugging.
*
* \return A pointer to a struct container.
*
* \note Destructor is set implicitly.
*/
#define ao2_container_alloc_rbtree(ao2_options, container_options, sort_fn, cmp_fn) \
__ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_container_alloc_rbtree(ao2_options, container_options, sort_fn, cmp_fn, tag) \
__ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_container_alloc_rbtree(ao2_options, container_options, sort_fn, cmp_fn) \
__ao2_container_alloc_rbtree((ao2_options), (container_options), (sort_fn), (cmp_fn), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ao2_container *__ao2_container_alloc_rbtree(unsigned int ao2_options, unsigned int container_options,
ao2_sort_fn *sort_fn, ao2_callback_fn *cmp_fn,
@ -1403,7 +1396,7 @@ int ao2_container_dup(struct ao2_container *dest, struct ao2_container *src, enu
* needed for every object in the src container.
*
* \note Every object inside the container is locked by \ref ao2_weakproxy_get_object.
* Any weakproxy in \ref src with no associated object is ignored.
* Any weakproxy in \p src with no associated object is ignored.
*
* \retval 0 on success.
* \retval -1 on error.
@ -1420,16 +1413,17 @@ int ao2_container_dup_weakproxy_objs(struct ao2_container *dest, struct ao2_cont
* \note This can potentially be expensive because a malloc is
* needed for every object in the orig container.
*
* \retval Clone container on success.
* \return Clone container on success.
* \retval NULL on error.
*/
struct ao2_container *__ao2_container_clone(struct ao2_container *orig, enum search_flags flags,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
#define ao2_container_clone(orig, flags) \
__ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_container_clone(orig, flags, tag) \
__ao2_container_clone(orig, flags, tag, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_container_clone(orig, flags) \
__ao2_container_clone(orig, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ao2_container *__ao2_container_clone(struct ao2_container *orig, enum search_flags flags,
const char *tag, const char *file, int line, const char *func) attribute_warn_unused_result;
/*!
* \brief Print output.
@ -1437,8 +1431,6 @@ struct ao2_container *__ao2_container_clone(struct ao2_container *orig, enum sea
*
* \param where User data pointer needed to determine where to put output.
* \param fmt printf type format string.
*
* \return Nothing
*/
typedef void (ao2_prnt_fn)(void *where, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
@ -1449,8 +1441,6 @@ typedef void (ao2_prnt_fn)(void *where, const char *fmt, ...) __attribute__((for
* \param v_obj A pointer to the object we want the key printed.
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
*
* \return Nothing
*/
typedef void (ao2_prnt_obj_fn)(void *v_obj, void *where, ao2_prnt_fn *prnt);
@ -1464,8 +1454,6 @@ typedef void (ao2_prnt_obj_fn)(void *v_obj, void *where, ao2_prnt_fn *prnt);
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
* \param prnt_obj Callback function to print the given object's key. (NULL if not available)
*
* \return Nothing
*/
void ao2_container_dump(struct ao2_container *self, enum search_flags flags, const char *name, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj);
@ -1478,8 +1466,6 @@ void ao2_container_dump(struct ao2_container *self, enum search_flags flags, con
* \param name Container name. (NULL if anonymous)
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
*
* \return Nothing
*/
void ao2_container_stats(struct ao2_container *self, enum search_flags flags, const char *name, void *where, ao2_prnt_fn *prnt);
@ -1513,8 +1499,6 @@ int ao2_container_register(const char *name, struct ao2_container *self, ao2_prn
* \since 12.0.0
*
* \param name Name the container is registered under.
*
* \return Nothing
*/
void ao2_container_unregister(const char *name);
@ -1534,7 +1518,6 @@ void ao2_container_unregister(const char *name);
*
* \param container The container to operate on.
* \param obj The object to be added.
* \param tag used for debugging.
*
* \retval 0 on errors.
* \retval 1 on success.
@ -1546,10 +1529,10 @@ void ao2_container_unregister(const char *name);
* \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(container, obj, tag) \
__ao2_link((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_link(container, obj) \
__ao2_link((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_link(container, obj, tag) \
__ao2_link((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Add an object to a container.
@ -1557,7 +1540,6 @@ void ao2_container_unregister(const char *name);
* \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 0 on errors.
* \retval 1 on success.
@ -1569,10 +1551,10 @@ void ao2_container_unregister(const char *name);
* \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((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_link_flags(container, obj, flags) \
__ao2_link((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_link_flags(container, obj, flags, tag) \
__ao2_link((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
int __ao2_link(struct ao2_container *c, void *obj_new, int flags,
const char *tag, const char *file, int line, const char *func);
@ -1582,9 +1564,8 @@ int __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 tag used for debugging.
*
* \retval NULL, always
* \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
@ -1594,11 +1575,10 @@ int __ao2_link(struct ao2_container *c, void *obj_new, int flags,
* reference to the object will be automatically released. (The
* refcount will be decremented).
*/
#define ao2_t_unlink(container, obj, tag) \
__ao2_unlink((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_unlink(container, obj) \
__ao2_unlink((container), (obj), 0, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_unlink(container, obj, tag) \
__ao2_unlink((container), (obj), 0, (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Remove an object from a container
@ -1606,9 +1586,8 @@ int __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
* \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
@ -1618,11 +1597,11 @@ int __ao2_link(struct ao2_container *c, void *obj_new, int flags,
* reference to the object will be automatically released. (The
* refcount will be decremented).
*/
#define ao2_unlink_flags(container, obj, flags) \
__ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_unlink_flags(container, obj, flags, tag) \
__ao2_unlink((container), (obj), (flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_unlink_flags(container, obj, flags) \
__ao2_unlink((container), (obj), (flags), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
void *__ao2_unlink(struct ao2_container *c, void *obj, int flags,
const char *tag, const char *file, int line, const char *func);
@ -1661,14 +1640,13 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags,
* flags is the same as flags passed into ao2_callback (flags are
* also used by ao2_callback).
* \param arg passed to the callback.
* \param tag used for debugging.
*
* \retval NULL on failure or no matching object found.
*
* \retval object found if OBJ_MULTIPLE is not set in the flags
* \return object found if OBJ_MULTIPLE is not set in the flags
* parameter.
*
* \retval ao2_iterator pointer if OBJ_MULTIPLE is set in the
* \return ao2_iterator pointer if OBJ_MULTIPLE is set in the
* flags parameter. The iterator must be destroyed with
* ao2_iterator_destroy() when the caller no longer needs it.
*
@ -1712,11 +1690,11 @@ void *__ao2_unlink(struct ao2_container *c, void *obj, int flags,
*
* @{
*/
#define ao2_callback(c, flags, cb_fn, arg) \
__ao2_callback((c), (flags), (cb_fn), (arg), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_t_callback(c, flags, cb_fn, arg, tag) \
__ao2_callback((c), (flags), (cb_fn), (arg), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ao2_callback(c, flags, cb_fn, arg) \
__ao2_callback((c), (flags), (cb_fn), (arg), NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
void *__ao2_callback(struct ao2_container *c, enum search_flags flags,
ao2_callback_fn *cb_fn, void *arg, const char *tag, const char *file, int line,
@ -1903,7 +1881,7 @@ enum ao2_iterator_flags {
* \param c the container
* \param flags one or more flags from ao2_iterator_flags.
*
* \retval the constructed iterator
* \return the constructed iterator
*
* \note This function does \b not take a pointer to an iterator;
* rather, it returns an iterator structure that should be
@ -1919,8 +1897,6 @@ struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attrib
*
* \param iter the iterator to destroy
*
* \retval none
*
* This function will release the container reference held by the iterator
* and any other resources it may be holding.
*/
@ -1946,8 +1922,6 @@ void *__ao2_iterator_next(struct ao2_iterator *iter,
* \note A restart is not going to have any effect if the
* iterator was created with the AO2_ITERATOR_UNLINK flag. Any
* previous objects returned were removed from the container.
*
* \retval none
*/
void ao2_iterator_restart(struct ao2_iterator *iter);
@ -1966,7 +1940,7 @@ void ao2_iterator_cleanup(struct ao2_iterator *iter);
*
* \param iter the iterator to query
*
* \retval The number of objects in the iterated container
* \return The number of objects in the iterated container
*/
int ao2_iterator_count(struct ao2_iterator *iter);
@ -2014,6 +1988,7 @@ static int stype ## _hash_fn(const void *obj, const int flags) \
* \param partial_key_cmp Partial key comparison function like strncmp
* \param transform A macro that takes the cmp result as an argument
* and transforms it to a return value.
* \param argconst
*
* Do not use this macro directly, instead use macro's starting with
* AST_STRING_FIELD.

4
include/asterisk/autochan.h
View File

@ -113,8 +113,6 @@ struct ast_autochan *ast_autochan_setup(struct ast_channel *chan);
* which was made in ast_autochan_setup
*
* \param autochan The autochan that you wish to destroy
*
* \retval void
*/
void ast_autochan_destroy(struct ast_autochan *autochan);
@ -131,8 +129,6 @@ void ast_autochan_destroy(struct ast_autochan *autochan);
*
* \param old_chan The channel that autochans may currently point to
* \param new_chan The channel that we want to point those autochans to now
*
* \retval void
*/
void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);

16
include/asterisk/backtrace.h
View File

@ -42,7 +42,7 @@
#define ast_bt_free_symbols(string_vector) NULL
#endif
/* \brief
/*! \brief
*
* A structure to hold backtrace information. This structure provides an easy means to
* store backtrace information or pass backtraces to other functions.
@ -58,15 +58,16 @@ struct ast_bt {
#ifdef HAVE_BKTR
/* \brief
/*! \brief
* Allocates memory for an ast_bt and stores addresses and symbols.
*
* \return Returns NULL on failure, or the allocated ast_bt on success
* \retval NULL on failure
* \return the allocated ast_bt on success
* \since 1.6.1
*/
struct ast_bt *__ast_bt_create(void);
/* \brief
/*! \brief
* Fill an allocated ast_bt with addresses
*
* \retval 0 Success
@ -75,16 +76,15 @@ struct ast_bt *__ast_bt_create(void);
*/
int __ast_bt_get_addresses(struct ast_bt *bt);
/* \brief
/*! \brief
*
* Free dynamically allocated portions of an ast_bt
*
* \retval NULL.
* \since 1.6.1
*/
void *__ast_bt_destroy(struct ast_bt *bt);
/* \brief Retrieve symbols for a set of backtrace addresses
/* !\brief Retrieve symbols for a set of backtrace addresses
*
* \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
* \param num_frames Number of addresses in the addresses list
@ -99,7 +99,7 @@ void *__ast_bt_destroy(struct ast_bt *bt);
*/
struct ast_vector_string *__ast_bt_get_symbols(void **addresses, size_t num_frames);
/* \brief Free symbols returned from ast_bt_get_symbols
/*! \brief Free symbols returned from ast_bt_get_symbols
*
* \param symbols The symbol string vector
*

35
include/asterisk/bridge.h
View File

@ -172,8 +172,6 @@ struct ast_bridge_video_mode {
* \brief Destroy the bridge.
*
* \param self Bridge to operate upon.
*
* \return Nothing
*/
typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
@ -187,8 +185,6 @@ typedef void (*ast_bridge_destructor_fn)(struct ast_bridge *self);
* references to the bridge so it can be destroyed.
*
* \note On entry, self must NOT be locked.
*
* \return Nothing
*/
typedef void (*ast_bridge_dissolving_fn)(struct ast_bridge *self);
@ -224,8 +220,6 @@ typedef int (*ast_bridge_push_channel_fn)(struct ast_bridge *self, struct ast_br
* bridge_channel->bridge_pvt.
*
* \note On entry, self is already locked.
*
* \return Nothing
*/
typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
@ -240,8 +234,6 @@ typedef void (*ast_bridge_pull_channel_fn)(struct ast_bridge *self, struct ast_b
* to re-evaluate this a channel in the bridge.
*
* \note On entry, self is already locked.
*
* \return Nothing
*/
typedef void (*ast_bridge_notify_masquerade_fn)(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel);
@ -423,10 +415,10 @@ extern struct ast_bridge_methods ast_bridge_base_v_table;
* \brief Returns the global bridges container
* \since 17.0
*
* \retval a pointer to the bridges container success
* \return a pointer to the bridges container success
* \retval NULL on failure
*
* \note You must use ao2_ref(<container>, -1) when done with it
* \note You must use \verbatim ao2_ref(<container>, -1) \endverbatim when done with it
*
* \warning You must not attempt to modify the container returned.
*/
@ -441,7 +433,7 @@ struct ao2_container *ast_bridges(void);
* \param name Name given to the bridge by its creator (optional, requires named creator)
* \param id Unique ID given to the bridge by its creator (optional)
*
* \retval a pointer to a new bridge on success
* \return a pointer to a new bridge on success
* \retval NULL on failure
*
* Example usage:
@ -474,8 +466,6 @@ static inline int _ast_bridge_trylock(struct ast_bridge *bridge, const char *fil
* \brief Lock the bridge.
*
* \param bridge Bridge to lock
*
* \return Nothing
*/
#define ast_bridge_lock(bridge) _ast_bridge_lock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
@ -487,8 +477,6 @@ static inline void _ast_bridge_lock(struct ast_bridge *bridge, const char *file,
* \brief Unlock the bridge.
*
* \param bridge Bridge to unlock
*
* \return Nothing
*/
#define ast_bridge_unlock(bridge) _ast_bridge_unlock(bridge, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge)
static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *file, const char *function, int line, const char *var)
@ -539,8 +527,6 @@ int ast_bridge_destroy(struct ast_bridge *bridge, int cause);
* \since 12.0.0
*
* \param chan Channel just involved in a masquerade
*
* \return Nothing
*/
void ast_bridge_notify_masquerade(struct ast_channel *chan);
@ -803,8 +789,6 @@ int ast_bridge_move(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge
* \param bridge What to operate on.
* \param request Inhibit request increment.
* (Positive to add requests. Negative to remove requests.)
*
* \return Nothing
*/
void ast_bridge_merge_inhibit(struct ast_bridge *bridge, int request);
@ -860,10 +844,9 @@ int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
*
* \pre chan must be locked before calling
*
* \param name channel name of the bridged peer
* \param chan channel name of the bridged peer
* \param name
* \param pvtid Private CallID of the bridged peer
*
* \return nothing
*/
void ast_bridge_vars_set(struct ast_channel *chan, const char *name, const char *pvtid);
@ -919,7 +902,7 @@ enum ast_bridge_optimization {
* AST_BRIDGE_OPTIMIZE_PROHIBITED guarantees that an optimization attempt will
* never succeed.
*
* \returns Optimization allowability for the bridges
* \return Optimization allowability for the bridges
*/
enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *chan_bridge,
struct ast_bridge *peer_bridge);
@ -1067,7 +1050,7 @@ int ast_bridge_number_video_src(struct ast_bridge *bridge);
* \brief Determine if a channel is a video src for the bridge
*
* \retval 0 Not a current video source of the bridge.
* \retval None 0, is a video source of the bridge, The number
* \retval non-zero is a video source of the bridge, The number
* returned represents the priority this video stream has
* on the bridge where 1 is the highest priority.
*/
@ -1083,7 +1066,7 @@ void ast_bridge_remove_video_src(struct ast_bridge *bridge, struct ast_channel *
*
* \param video_mode The video mode
*
* \retval A string representation of \c video_mode
* \return A string representation of \c video_mode
*/
const char *ast_bridge_video_mode_to_string(enum ast_bridge_video_mode_type video_mode);
@ -1281,8 +1264,6 @@ struct ast_channel *ast_bridge_peer(struct ast_bridge *bridge, struct ast_channe
*
* \param features Bridge features structure
* \param flags Determinator for whether hook is removed.
*
* \return Nothing
*/
void ast_bridge_features_remove(struct ast_bridge_features *features, enum ast_bridge_hook_remove_flags flags);

39
include/asterisk/bridge_after.h
View File

@ -60,10 +60,8 @@ enum ast_bridge_after_cb_reason {
*
* \note chan is locked by this function.
*
* \details Add a channel datastore to setup the goto location
* when the channel leaves the bridge and run a PBX from there.
*
* \return Nothing
* Add a channel datastore to setup the goto location when the
* channel leaves the bridge and run a PBX from there.
*/
void ast_bridge_set_after_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
@ -76,10 +74,8 @@ void ast_bridge_set_after_goto(struct ast_channel *chan, const char *context, co
*
* \note chan is locked by this function.
*
* \details Add a channel datastore to setup the goto location
* when the channel leaves the bridge and run a PBX from there.
*
* \return Nothing
* Add a channel datastore to setup the goto location when the
* channel leaves the bridge and run a PBX from there.
*/
void ast_bridge_set_after_h(struct ast_channel *chan, const char *context);
@ -95,14 +91,12 @@ void ast_bridge_set_after_h(struct ast_channel *chan, const char *context);
*
* \note chan is locked by this function.
*
* \details Add a channel datastore to setup the goto location
* when the channel leaves the bridge and run a PBX from there.
* Add a channel datastore to setup the goto location when the
* channel leaves the bridge and run a PBX from there.
*
* If parseable_goto then use the given context/exten/priority
* as the relative position for the parseable_goto.
* Else goto the given context/exten/priority+1.
*
* \return Nothing
*/
void ast_bridge_set_after_go_on(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *parseable_goto);
@ -114,8 +108,8 @@ void ast_bridge_set_after_go_on(struct ast_channel *chan, const char *context, c
*
* \note chan is locked by this function.
*
* \details Pull off any after bridge goto location datastore and
* setup for dialplan execution there.
* Pull off any after bridge goto location datastore and setup for
* dialplan execution there.
*
* \retval 0 on success. The goto location is set for a PBX to run it.
* \retval non-zero on error or no goto location.
@ -130,8 +124,6 @@ int ast_bridge_setup_after_goto(struct ast_channel *chan);
* \since 12.0.0
*
* \param chan Channel to run after bridge callback.
*
* \return Nothing
*/
void ast_bridge_run_after_callback(struct ast_channel *chan);
@ -140,8 +132,7 @@ void ast_bridge_run_after_callback(struct ast_channel *chan);
* \since 12.0.0
*
* \param chan Channel to run after bridge callback.
*
* \return Nothing
* \param reason
*/
void ast_bridge_discard_after_callback(struct ast_channel *chan, enum ast_bridge_after_cb_reason reason);
@ -153,13 +144,11 @@ void ast_bridge_discard_after_callback(struct ast_channel *chan, enum ast_bridge
*
* \note chan is locked by this function.
*
* \details Pull off any after bridge goto location datastore
* and run a PBX at that location.
* Pull off any after bridge goto location datastore and run a PBX at that
* location.
*
* \note On return, the chan pointer is no longer valid because
* the channel has hung up.
*
* \return Nothing
*/
void ast_bridge_run_after_goto(struct ast_channel *chan);
@ -170,8 +159,6 @@ void ast_bridge_run_after_goto(struct ast_channel *chan);
* \param chan Channel to discard after bridge goto location.
*
* \note chan is locked by this function.
*
* \return Nothing
*/
void ast_bridge_discard_after_goto(struct ast_channel *chan);
@ -194,8 +181,6 @@ void ast_bridge_read_after_goto(struct ast_channel *chan, char *buffer, size_t b
*
* \note Called when the channel leaves the bridging system or
* is destroyed.
*
* \return Nothing
*/
typedef void (*ast_bridge_after_cb_failed)(enum ast_bridge_after_cb_reason reason, void *data);
@ -205,8 +190,6 @@ typedef void (*ast_bridge_after_cb_failed)(enum ast_bridge_after_cb_reason reaso
*
* \param chan Channel just leaving bridging system.
* \param data Extra data what setup the callback wanted to pass.
*
* \return Nothing
*/
typedef void (*ast_bridge_after_cb)(struct ast_channel *chan, void *data);

7
include/asterisk/bridge_basic.h
View File

@ -70,7 +70,7 @@ int ast_bridge_features_ds_get_string(struct ast_channel *chan, char *buffer, si
* \note The channel should be locked before calling this function.
* \note The channel must remain locked until the flags returned have been consumed.
*
* \retval flags on success.
* \return flags on success.
* \retval NULL if the datastore does not exist.
*/
struct ast_flags *ast_bridge_features_ds_get(struct ast_channel *chan);
@ -111,7 +111,7 @@ extern struct ast_bridge_methods ast_bridge_basic_v_table;
/*!
* \brief Create a new basic class bridge
*
* \retval a pointer to a new bridge on success
* \return a pointer to a new bridge on success
* \retval NULL on failure
*
* Example usage:
@ -134,7 +134,8 @@ struct ast_bridge *ast_bridge_basic_new(void);
* ensure that after operations such as an attended transfer,
* the bridge will maintain the flags that were set on it.
*
* \params Flags to set on the bridge. These are added to the flags already set.
* \param bridge
* \param flags These are added to the flags already set.
*/
void ast_bridge_basic_set_flags(struct ast_bridge *bridge, unsigned int flags);

20
include/asterisk/bridge_channel_internal.h
View File

@ -78,7 +78,7 @@ enum bridge_channel_action_type {
* \param bridge The bridge to make the bridge_channel for
*
* \retval NULL on error
* \retval ao2 ref counted object on success
* \return ao2 ref counted object on success
*/
struct ast_bridge_channel *bridge_channel_internal_alloc(struct ast_bridge *bridge);
@ -187,20 +187,21 @@ int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel);
/*!
* \internal
* \brief Temporarily suspend a channel from a bridge, handing control over to some
* other system
* \brief Suspend a channel from a bridge.
*
* \param bridge_channel The channel in the bridge
* \note This function assumes that \ref bridge_channel is already locked
* \param bridge_channel Channel to suspend.
*
* \note This function assumes bridge_channel->bridge is locked.
*/
void bridge_channel_internal_suspend_nolock(struct ast_bridge_channel *bridge_channel);
/*!
* \internal
* \brief Unsuspend a channel that was previously suspended
* \brief Unsuspend a channel from a bridge.
*
* \param bridge_channel The channel in the bridge
* \note This function assumes that \ref bridge_channel is already locked
* \param bridge_channel Channel to unsuspend.
*
* \note This function assumes bridge_channel->bridge is locked.
*/
void bridge_channel_internal_unsuspend_nolock(struct ast_bridge_channel *bridge_channel);
@ -215,8 +216,7 @@ void bridge_channel_internal_unsuspend_nolock(struct ast_bridge_channel *bridge_
*
* \param transferee The channel to have the action queued on
* \param exten The destination extension for the transferee
* \param context The destination context for the transferee
* \param hook Frame hook to attach to transferee
* \param context, new_channel_cb, user_data
*
* \retval 0 on success.
* \retval -1 on error.

25
include/asterisk/bridge_features.h
View File

@ -124,14 +124,11 @@ struct ast_bridge_channel;
* \param bridge_channel Channel executing the feature
* \param hook_pvt Private data passed in when the hook was created
*
* For interval hooks:
* \retval 0 Setup to fire again at the last interval.
* \retval positive Setup to fire again at the new interval returned.
* \retval -1 Remove the callback hook.
*
* For other hooks:
* \retval 0 Keep the callback hook.
* \retval -1 Remove the callback hook.
* \retval 0 for interval hooks: setup to fire again at the last interval.
* for other hooks: keep the callback hook.
* \retval positive for interval hooks: Setup to fire again at the new interval returned.
* for other hooks: n/a
* \retval -1 for all hooks: remove the callback hook.
*/
typedef int (*ast_bridge_hook_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt);
@ -454,7 +451,7 @@ int ast_bridge_interval_register(enum ast_bridge_builtin_interval interval, ast_
*
* \code
* ast_bridge_interval_unregister(AST_BRIDGE_BULTIN_INTERVAL_LIMITS)
* /endcode
* \endcode
*
* This unregisters the function that is handling the built in duration limit feature.
*/
@ -666,7 +663,7 @@ int ast_bridge_talk_detector_hook(struct ast_bridge_features *features,
* ast_bridge_move_hook(&features, move_callback, NULL, NULL, 0);
* \endcode
*
* This makes the bridging core call \ref callback when a
* This makes the bridging core call \p callback when a
* channel is moved from one bridge to another. A
* pointer to useful data may be provided to the hook_pvt
* parameter.
@ -763,8 +760,6 @@ int ast_bridge_features_set_limits(struct ast_bridge_features *features, struct
* \param features Bridge channel features structure
* \param flag Flag to enable
*
* \return Nothing
*
* Example usage:
*
* \code
@ -813,8 +808,6 @@ int ast_bridge_features_init(struct ast_bridge_features *features);
*
* \param features Bridge features structure
*
* \return Nothing
*
* Example usage:
*
* \code
@ -842,7 +835,7 @@ void ast_bridge_features_cleanup(struct ast_bridge_features *features);
* ast_bridge_features_destroy(features);
* \endcode
*
* \retval features New allocated features struct.
* \return features New allocated features struct.
* \retval NULL on error.
*/
struct ast_bridge_features *ast_bridge_features_new(void);
@ -860,8 +853,6 @@ struct ast_bridge_features *ast_bridge_features_new(void);
* features = ast_bridge_features_new();
* ast_bridge_features_destroy(features);
* \endcode
*
* \return Nothing
*/
void ast_bridge_features_destroy(struct ast_bridge_features *features);

17
include/asterisk/bridge_internal.h
View File

@ -63,7 +63,7 @@ struct ast_bridge_methods;
* \note After a bridge is registered, ast_bridge_destroy() must
* eventually be called to get rid of the bridge.
*
* \retval bridge on success.
* \return bridge on success.
* \retval NULL on error.
*/
struct ast_bridge *bridge_register(struct ast_bridge *bridge);
@ -76,7 +76,7 @@ struct ast_bridge *bridge_register(struct ast_bridge *bridge);
* \param size Size of the bridge class structure to allocate.
* \param v_table Bridge class virtual method table.
*
* \retval bridge on success.
* \return bridge on success.
* \retval NULL on error.
*/
struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
@ -91,7 +91,7 @@ struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_
* \param name Name given to the bridge by its creator (optional, requires named creator)
* \param id Unique ID given to the bridge by its creator (optional)
*
* \retval self on success
* \return self on success
* \retval NULL on failure, self is already destroyed
*
* Example usage:
@ -139,8 +139,6 @@ int bridge_do_move(struct ast_bridge *dst_bridge, struct ast_bridge_channel *bri
* \param num_kick Number of channels in the kick_me array.
* \param optimized Indicates whether the merge is part of an unreal channel optimization.
*
* \return Nothing
*
* \note The two bridges are assumed already locked.
*
* This moves the channels in src_bridge into the bridge pointed
@ -158,7 +156,7 @@ void bridge_do_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridg
*
* \note On entry, bridge is already locked.
*
* \retval bridge_channel if channel is in the bridge.
* \return bridge_channel if channel is in the bridge.
* \retval NULL if not in bridge.
*/
struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct ast_channel *chan);
@ -173,8 +171,6 @@ struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct
* (Positive to add requests. Negative to remove requests.)
*
* \note This function assumes bridge is locked.
*
* \return Nothing
*/
void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
@ -186,15 +182,12 @@ void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
* \param bridge Reconfigured bridge.
* \param colp_update Whether to perform COLP updates.
*
* \details
* After a series of bridge_channel_internal_push and
* bridge_channel_internal_pull calls, you need to call this function
* to cause the bridge to complete restructuring for the change
* in the channel makeup of the bridge.
*
* \note On entry, the bridge is already locked.
*
* \return Nothing
*/
void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
@ -211,8 +204,6 @@ void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
* bridge. Any new channels joining will leave immediately.
*
* \note On entry, bridge is already locked.
*
* \return Nothing
*/
void bridge_dissolve(struct ast_bridge *bridge, int cause);

2
include/asterisk/bridge_roles.h
View File

@ -65,7 +65,7 @@ void ast_channel_clear_bridge_roles(struct ast_channel *chan);
* \param option Name of the option
* \param value Value of the option
*
* \param 0 on success
* \retval 0 on success
* \retval -1 on failure
*/
int ast_channel_set_bridge_role_option(struct ast_channel *channel, const char *role_name, const char *option, const char *value);

20
include/asterisk/bucket.h
View File

@ -19,11 +19,11 @@
/*! \file
* \brief Bucket File API
* \author Joshua Colp <jcolp@digium.com>
* \ref AstBucket
* \ref bucket "AstBucket"
*/
/*!
* \page bucket AstBucket Bucket File API
* \page bucket Bucket File API
*
* Bucket is an API which provides directory and file access in a generic fashion. It is
* implemented as a thin wrapper over the sorcery data access layer API and is written in
@ -210,8 +210,8 @@ void ast_bucket_file_metadata_callback(struct ast_bucket_file *file, ao2_callbac
*
* \param uri Complete URI for the bucket
*
* \param non-NULL success
* \param NULL failure
* \retval non-NULL success
* \retval NULL failure
*
* \note This only creates a local bucket object, to persist in backend storage you must call
* ast_bucket_create
@ -235,7 +235,7 @@ int ast_bucket_create(struct ast_bucket *bucket);
* all properties of the \c ast_bucket structure are copied, any metadata
* in the original structure simply has its reference count increased.
*
* \param file The bucket to clone
* \param bucket The bucket to clone
*
* \retval non-NULL success
* \retval NULL failure
@ -320,8 +320,8 @@ struct ast_json *ast_bucket_json(const struct ast_bucket *bucket);
*
* \param uri Complete URI for the bucket file
*
* \param non-NULL success
* \param NULL failure
* \retval non-NULL success
* \retval NULL failure
*
* \note This only creates a local bucket file object, to persist in backend storage you must call
* ast_bucket_file_create
@ -415,10 +415,10 @@ struct ast_bucket_file *ast_bucket_file_retrieve(const char *uri);
* caller of this function would like to update the object, it should perform
* a retrieve operation.
*
* \param bucket_file The bucket file object to check
* \param file The bucket file object to check
*
* \retval 0 if \c bucket_file is not stale
* \retval 1 if \c bucket_file is stale
* \retval 0 if \p file is not stale
* \retval 1 if \p file is stale
*/
int ast_bucket_file_is_stale(struct ast_bucket_file *file);

14
include/asterisk/callerid.h
View File

@ -150,8 +150,6 @@ int callerid_feed_jp(struct callerid_state *cid, unsigned char *ubuf, int sample
* This function extracts a callerid string out of a callerid_state state machine.
* If no number is found, *number will be set to NULL. Likewise for the name.
* Flags can contain any of the following:
*
* \return Returns nothing.
*/
void callerid_get(struct callerid_state *cid, char **number, char **name, int *flags);
@ -211,7 +209,8 @@ int ast_callerid_callwaiting_generate(unsigned char *buf, const char *name, cons
* " foo bar " <123> 123 ' foo bar ' (with spaces around)
* " foo bar " NULL 'foo bar' (without spaces around)
* The parsing of leading and trailing space/quotes should be more consistent.
* \return Returns 0 on success, -1 on failure.
* \retval 0 on success
* \retval -1 on failure
*/
int ast_callerid_parse(char *instr, char **name, char **location);
@ -221,21 +220,22 @@ int ast_callerid_parse(char *instr, char **name, char **location);
* \param sas Non-zero if CAS should be preceeded by SAS
* \param len How many samples to generate.
* \param codec Which codec (AST_FORMAT_ALAW or AST_FORMAT_ULAW)
* \return Returns -1 on error (if len is less than 2400), 0 on success.
* \retval -1 on error (if len is less than 2400)
* \retval 0 on success
*/
int ast_gen_cas(unsigned char *outbuf, int sas, int len, struct ast_format *codec);
/*!
* \brief Shrink a phone number in place to just digits (more accurately it just removes ()'s, .'s, and -'s...
* \param n The number to be stripped/shrunk
* \return Returns nothing important
*/
void ast_shrink_phone_number(char *n);
/*!
* \brief Check if a string consists only of digits and + \#
* \param n number to be checked.
* \return Returns 0 if n is a number, 1 if it's not.
* \retval 0 if \p n is a number
* \retval 1 if not
*/
int ast_isphonenumber(const char *n);
@ -243,7 +243,7 @@ int ast_isphonenumber(const char *n);
* \brief Check if a string consists only of digits and + \# ( ) - .
* (meaning it can be cleaned with ast_shrink_phone_number)
* \param exten The extension (or URI) to be checked.
* \retval 1 if string is valid AST shrinkable phone number
* \retval 1 if \p exten is valid AST shrinkable phone number
* \retval 0 if not
*/
int ast_is_shrinkable_phonenumber(const char *exten);

26
include/asterisk/ccss.h
View File

@ -141,7 +141,6 @@ struct ast_cc_config_params *__ast_cc_config_params_init(const char *file, int l
* Just a call to ast_free for now...
*
* \param params Pointer to structure whose memory we need to free
* \retval void
*/
void ast_cc_config_params_destroy(struct ast_cc_config_params *params);
@ -197,8 +196,6 @@ int ast_cc_is_config_param(const char * const name);
* You are simply "copying" defaults into the destination.
*
* \param params CC config params to set to default values.
*
* \return Nothing
*/
void ast_cc_default_config_params(struct ast_cc_config_params *params);
@ -214,8 +211,6 @@ void ast_cc_default_config_params(struct ast_cc_config_params *params);
*
* \param src The structure from which data is copied
* \param dest The structure to which data is copied
*
* \return Nothing
*/
void ast_cc_copy_config_params(struct ast_cc_config_params *dest, const struct ast_cc_config_params *src);
@ -268,7 +263,6 @@ unsigned int ast_get_cc_offer_timer(struct ast_cc_config_params *config);
* \brief Set the cc_offer_timer
* \param config The configuration to set the cc_offer_timer on
* \param value The new cc_offer_timer we want to change to
* \retval void
*/
void ast_set_cc_offer_timer(struct ast_cc_config_params *config, unsigned int value);
@ -285,7 +279,6 @@ unsigned int ast_get_ccnr_available_timer(struct ast_cc_config_params *config);
* \brief Set the ccnr_available_timer
* \param config The configuration to set the ccnr_available_timer on
* \param value The new ccnr_available_timer we want to change to
* \retval void
*/
void ast_set_ccnr_available_timer(struct ast_cc_config_params *config, unsigned int value);
@ -302,7 +295,6 @@ unsigned int ast_get_cc_recall_timer(struct ast_cc_config_params *config);
* \brief Set the cc_recall_timer
* \param config The configuration to set the cc_recall_timer on
* \param value The new cc_recall_timer we want to change to
* \retval void
*/
void ast_set_cc_recall_timer(struct ast_cc_config_params *config, unsigned int value);
@ -319,7 +311,6 @@ unsigned int ast_get_ccbs_available_timer(struct ast_cc_config_params *config);
* \brief Set the ccbs_available_timer
* \param config The configuration to set the ccbs_available_timer on
* \param value The new ccbs_available_timer we want to change to
* \retval void
*/
void ast_set_ccbs_available_timer(struct ast_cc_config_params *config, unsigned int value);
@ -336,7 +327,6 @@ const char *ast_get_cc_agent_dialstring(struct ast_cc_config_params *config);
* \brief Set the cc_agent_dialstring
* \param config The configuration to set the cc_agent_dialstring on
* \param value The new cc_agent_dialstring we want to change to
* \retval void
*/
void ast_set_cc_agent_dialstring(struct ast_cc_config_params *config, const char *const value);
@ -353,7 +343,6 @@ unsigned int ast_get_cc_max_agents(struct ast_cc_config_params *config);
* \brief Set the cc_max_agents
* \param config The configuration to set the cc_max_agents on
* \param value The new cc_max_agents we want to change to
* \retval void
*/
void ast_set_cc_max_agents(struct ast_cc_config_params *config, unsigned int value);
@ -370,7 +359,6 @@ unsigned int ast_get_cc_max_monitors(struct ast_cc_config_params *config);
* \brief Set the cc_max_monitors
* \param config The configuration to set the cc_max_monitors on
* \param value The new cc_max_monitors we want to change to
* \retval void
*/
void ast_set_cc_max_monitors(struct ast_cc_config_params *config, unsigned int value);
@ -387,7 +375,6 @@ const char *ast_get_cc_callback_macro(struct ast_cc_config_params *config);
* \brief Set the callback_macro name
* \param config The configuration to set the callback_macro on
* \param value The new callback macro we want to change to
* \retval void
*/
void ast_set_cc_callback_macro(struct ast_cc_config_params *config, const char * const value);
@ -404,7 +391,6 @@ const char *ast_get_cc_callback_sub(struct ast_cc_config_params *config);
* \brief Set the callback subroutine name
* \param config The configuration to set the callback_sub on
* \param value The new callback subroutine we want to change to
* \retval void
*/
void ast_set_cc_callback_sub(struct ast_cc_config_params *config, const char * const value);
@ -438,8 +424,6 @@ int ast_cc_monitor_register(const struct ast_cc_monitor_callbacks *callbacks);
* unregister its monitor callbacks with the core.
*
* \param callbacks The callbacks used by the monitor implementation
* \retval 0 Successfully unregistered
* \retval -1 Failure to unregister
*/
void ast_cc_monitor_unregister(const struct ast_cc_monitor_callbacks *callbacks);
@ -469,8 +453,6 @@ int ast_cc_agent_register(const struct ast_cc_agent_callbacks *callbacks);
* unregister its agent callbacks with the core.
*
* \param callbacks The callbacks used by the agent implementation
* \retval 0 Successfully unregistered
* \retval -1 Failure to unregister
*/
void ast_cc_agent_unregister(const struct ast_cc_agent_callbacks *callbacks);
@ -695,7 +677,6 @@ int ast_cc_available_timer_expire(const void *data);
* CC processing should be ignored, this function should be called.
*
* \param chan The channel for which further CC processing should be ignored.
* \retval void
*/
void ast_ignore_cc(struct ast_channel *chan);
@ -713,7 +694,6 @@ void ast_ignore_cc(struct ast_channel *chan);
* \param inbound The inbound channel
* \param outbound The outbound channel (The one from which the CC frame was read)
* \param frame_data The ast_frame's data.ptr field.
* \retval void
*/
void ast_handle_cc_control_frame(struct ast_channel *inbound, struct ast_channel *outbound, void *frame_data);
@ -753,7 +733,6 @@ int ast_cc_call_init(struct ast_channel *chan, int *ignore_cc);
* \param incoming The caller's channel
* \param dialstring The dialstring used when requesting the outbound channel
* \param device_name The device name associated with the requested outbound channel
* \retval void
*/
void ast_cc_extension_monitor_add_dialstring(struct ast_channel *incoming, const char * const dialstring, const char * const device_name);
@ -1242,7 +1221,6 @@ int __attribute__((format(printf, 2, 3))) ast_cc_failed(int core_id, const char
* \param core_id The core ID for the CC transaction
* \param monitor_name The name of the monitor on which the failure occurred
* \param debug A debug message to print to the CC log
* \return void
*/
int __attribute__((format(printf, 3, 4))) ast_cc_monitor_failed(int core_id, const char * const monitor_name, const char * const debug, ...);
@ -1596,8 +1574,6 @@ int ast_cc_build_frame(struct ast_channel *chan, struct ast_cc_config_params *cc
* For channel types that fail ast_request when the device is busy, we call into the
* channel driver with ast_cc_callback. This is the callback that is called in that
* case for each device found which could have been returned by ast_request.
*
* \return Nothing
*/
typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_config_params *cc_params,
const char *monitor_type, const char * const device_name, const char * const dialstring, void *private_data);
@ -1614,7 +1590,7 @@ typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_confi
* \param tech Channel technology to use
* \param dest Channel/group/peer or whatever the specific technology uses
* \param callback Function to call when a target is reached
* \retval Always 0, I guess.
* \retval 0 Always, I guess.
*/
int ast_cc_callback(struct ast_channel *inbound, const char * const tech, const char * const dest, ast_cc_callback_fn callback);

36
include/asterisk/cdr.h
View File

@ -97,9 +97,9 @@
* state transitions to Dial
* \li If a \ref ast_channel_snapshot is received indicating that the channel
* has hung up, the state transitions to Finalized
* \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
* \li If a \ref ast_bridge_blob is received indicating a Bridge Enter, the
* state transitions to Bridge
* \li If a \ref ast_bridge_blob_type message indicating an entrance to a
* \li If a \ref ast_bridge_blob message indicating an entrance to a
* holding bridge with a subclass type of "parking" is received, the CDR is
* transitioned to the Parked state.
*
@ -117,12 +117,12 @@
*
* The following transitions can occur while in the Dial state:
* \li If a \ref ast_channel_dial_type indicating a Dial End is received where
* the \ref dial_status is not ANSWER, the state transitions to Finalized
* the \c dial_status is not ANSWER, the state transitions to Finalized
* \li If a \ref ast_channel_snapshot is received indicating that the channel
* has hung up, the state transitions to Finalized
* \li If a \ref ast_channel_dial_type indicating a Dial End is received where
* the \ref dial_status is ANSWER, the state transitions to DialedPending
* \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
* the \c dial_status is ANSWER, the state transitions to DialedPending
* \li If a \ref ast_bridge_blob is received indicating a Bridge Enter, the
* state transitions to Bridge
*
* \par DialedPending
@ -139,9 +139,9 @@
* \li If a \ref ast_channel_snapshot is received that indicates that the
* channel has begun executing dialplan, we transition to the Finalized state
* if we have a Party B. Otherwise, we transition to the Single state.
* \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
* \li If a \ref ast_bridge_blob is received indicating a Bridge Enter, the
* state transitions to Bridge (through the Dial state)
* \li If a \ref ast_bridge_blob_type message indicating an entrance to a
* \li If a \ref ast_bridge_blob message indicating an entrance to a
* holding bridge with a subclass type of "parking" is received, the CDR is
* transitioned to the Parked state.
*
@ -172,12 +172,12 @@
* \li New CDRs are now generated. A gets a new CDR for A -> C. B is dialed, and
* hence cannot get any CDR.
* \li Now say another Originated channel, D, joins the bridge. Say D has the
* \ref party_a flag set on it, such that it is always the preferred Party A.
* As such, it takes A as its Party B.
* \ref AST_CDR_FLAG_PARTY_A flag set on it, such that it is always the
* preferred Party A. As such, it takes A as its Party B.
* \li New CDRs are generated. D gets new CDRs for D -> B and D -> C.
*
* The following transitions can occur while in the Bridge state:
* \li If a \ref ast_bridge_blob_type message indicating a leave is received,
* \li If a \ref ast_bridge_blob message indicating a leave is received,
* the state transitions to the Finalized state.
*
* \par Parked
@ -202,7 +202,7 @@
* subsequent channel snapshot updates.
*
* The following transitions can occur while in the Parked state:
* \li If a \ref ast_bridge_blob_type message indicating a leave is received,
* \li If a \ref ast_bridge_blob message indicating a leave is received,
* the state transitions to the Finalized state
*
* \par Finalized
@ -333,7 +333,7 @@ struct ast_cdr {
* decrement the ref count when finished with the configuration.
*
* \retval NULL on error
* \retval The current CDR configuration
* \return The current CDR configuration
*/
struct ast_cdr_config *ast_cdr_get_config(void);
@ -353,7 +353,7 @@ void ast_cdr_set_config(struct ast_cdr_config *config);
* \param name The name of the variable
* \param ret Pointer to the formatted buffer
* \param workspace A pointer to the buffer to use to format the variable
* \param workspacelen The size of \ref workspace
* \param workspacelen The size of \p workspace
* \param raw If non-zero and a date/time is extracted, provide epoch seconds. Otherwise format as a date/time stamp
*/
void ast_cdr_format_var(struct ast_cdr *cdr, const char *name, char **ret, char *workspace, int workspacelen, int raw);
@ -404,7 +404,7 @@ int ast_cdr_fork(const char *channel_name, struct ast_flags *options);
* This function sets specific administrative properties on a CDR for a channel.
* This includes properties like preventing a CDR from being dispatched, to
* setting the channel as the preferred Party A in future CDRs. See
* \ref enum ast_cdr_options for more information.
* \ref ast_cdr_options for more information.
*
* \param channel_name The CDR's channel
* \param option Option to apply to the CDR
@ -445,7 +445,7 @@ int ast_cdr_reset(const char *channel_name, int keep_variables);
* \param buf A buffer to use for formatting the data
* \param delim A delimeter to use to separate variable keys/values
* \param sep A separator to use between nestings
* \retval the total number of serialized variables
* \return the total number of serialized variables
*/
int ast_cdr_serialize_variables(const char *channel_name, struct ast_str **buf, char delim, char sep);
@ -462,7 +462,7 @@ int ast_cdr_is_enabled(void);
/*!
* \brief Allocate a CDR record
* \retval a malloc'd ast_cdr structure
* \return a malloc'd ast_cdr structure
* \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_alloc(void);
@ -478,7 +478,7 @@ struct stasis_message_router;
* this function.
*
* \retval NULL if the CDR engine is disabled or unavailable
* \retval the \ref stasis_message_router otherwise
* \return the \ref stasis_message_router otherwise
*/
struct stasis_message_router *ast_cdr_message_router(void);
@ -486,7 +486,7 @@ struct stasis_message_router *ast_cdr_message_router(void);
* \brief Duplicate a public CDR
* \param cdr the record to duplicate
*
* \retval a malloc'd ast_cdr structure,
* \return a malloc'd ast_cdr structure,
* \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);

6
include/asterisk/cli.h
View File

@ -241,7 +241,7 @@ int ast_cli_command_full(int uid, int gid, int fd, const char *s);
* \param fd pipe
* \param size is the total size of the string
* \param s incoming string
* \retval number of commands executed
* \return number of commands executed
*/
int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s);
@ -365,8 +365,8 @@ char *ast_complete_channels(const char *line, const char *word, int pos, int sta
* \brief Print on cli a duration in seconds in format
* %s year(s), %s week(s), %s day(s), %s hour(s), %s second(s)
*
* \param ast_cli_args fd to print by ast_cli
* \param duration The time (in seconds) to print
* \param fd fd to print by ast_cli
* \param seconds The time (in seconds) to print
* \param prefix A Prefix string to add before of duration formatted
*/
void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix);

39
include/asterisk/config.h
View File

@ -181,12 +181,12 @@ struct ast_config *ast_config_load2(const char *filename, const char *who_asked,
/*!
* \brief Destroys a config
*
* \param config pointer to config data structure
* \param cfg pointer to config data structure
*
* \details
* Free memory associated with a given config
*/
void ast_config_destroy(struct ast_config *config);
void ast_config_destroy(struct ast_config *cfg);
/*!
* \brief returns the root ast_variable of a config
@ -219,7 +219,7 @@ void ast_config_sort_categories(struct ast_config *config, int descending,
* Pass NULL to not restrict by category name.
* \param prev A pointer to the starting category structure.
* Pass NULL to start at the beginning.
* \param filter An optional comma-separated list of <name_regex>=<value_regex>
* \param filter An optional comma-separated list of \<name_regex\>=\<value_regex\>
* pairs. Only categories with matching variables will be returned.
* The special name 'TEMPLATES' can be used with the special values
* 'include' or 'restrict' to include templates in the result or
@ -259,7 +259,7 @@ char *ast_category_browse(struct ast_config *config, const char *prev_name);
* \brief Browse variables
* \param config Which config structure you wish to "browse"
* \param category_name Which category to "browse"
* \param filter an optional comma-separated list of <name_regex>=<value_regex>
* \param filter an optional comma-separated list of \<name_regex\>=\<value_regex\>
* pairs. Only categories with matching variables will be browsed.
* The special name 'TEMPLATES' can be used with the special values
* 'include' or 'restrict' to include templates in the result or
@ -292,7 +292,7 @@ struct ast_variable *ast_category_first(struct ast_category *cat);
* \param config which (opened) config to use
* \param category category under which the variable lies
* \param variable which variable you wish to get the data for
* \param filter an optional comma-separated list of <name_regex>=<value_regex>
* \param filter an optional comma-separated list of \<name_regex\>=\<value_regex\>
* pairs. Only categories with matching variables will be searched.
* The special name 'TEMPLATES' can be used with the special values
* 'include' or 'restrict' to include templates in the result or
@ -356,7 +356,7 @@ const char *ast_variable_find_last_in_list(const struct ast_variable *list, cons
* \since 13.9.0
*
* \param list variable list to search
* \param variable name you wish to get the data for
* \param variable_name name you wish to get the data for
*
* \details
* Goes through a given variable list and searches for the given variable
@ -373,7 +373,7 @@ const struct ast_variable *ast_variable_find_variable_in_list(const struct ast_v
* \param category_name name of the category you're looking for
* \param filter If a config contains more than 1 category with the same name,
* you can specify a filter to narrow the search. The filter is a comma-separated
* list of <name_regex>=<value_regex> pairs. Only a category with matching
* list of \<name_regex\>=\<value_regex\> pairs. Only a category with matching
* variables will be returned. The special name 'TEMPLATES' can be used with the
* special values 'include' or 'restrict' to include templates in the result or
* restrict the result to only templates.
@ -422,7 +422,7 @@ struct ast_str *ast_category_get_templates(const struct ast_category *category);
*
* \param config which config to use
* \param category_name name of the category you're looking for
* \param filter an optional comma-separated list of <name_regex>=<value_regex>
* \param filter an optional comma-separated list of \<name_regex\>=\<value_regex\>
* pairs. Only categories with matching variables will be returned.
* The special name 'TEMPLATES' can be used with the special values
* 'include' or 'restrict' to include templates in the result or
@ -440,6 +440,7 @@ int ast_category_exist(const struct ast_config *config, const char *category_nam
* \brief Retrieve realtime configuration
*
* \param family which family/config to lookup
* \param fields which fields to lookup
*
* \details
* This will use builtin configuration backends to look up a particular
@ -864,23 +865,23 @@ int ast_category_insert(struct ast_config *config, struct ast_category *cat, con
/*!
* \brief Delete a category
*
* \param config which config to use
* \param category category to delete
* \param cfg which config to use
* \param cat category to delete
*
* \return the category after the deleted one which could be NULL.
*
* \note It is not safe to call ast_category_delete while browsing with
* ast_category_browse. It is safe with ast_category_browse_filtered.
*/
struct ast_category *ast_category_delete(struct ast_config *cfg, struct ast_category *category);
struct ast_category *ast_category_delete(struct ast_config *cfg, struct ast_category *cat);
/*!
* \brief Appends a category to a config
*
* \param config which config to use
* \param cat category to insert
* \param category category to insert
*/
void ast_category_append(struct ast_config *config, struct ast_category *cat);
void ast_category_append(struct ast_config *config, struct ast_category *category);
/*!
* \brief Applies base (template) to category.
@ -989,7 +990,8 @@ int ast_variable_update(struct ast_category *category, const char *variable,
* \param generator generator
* \param flags List of config_save_flags
*
* \return 0 on success or -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_config_text_file_save2(const char *filename, const struct ast_config *cfg, const char *generator, uint32_t flags);
@ -1000,7 +1002,8 @@ int ast_config_text_file_save2(const char *filename, const struct ast_config *cf
* \param cfg ast_config
* \param generator generator
*
* \return 0 on success or -1 on failure.
* \retval 0 on success.
* \retval -1 on failure.
*/
int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
@ -1075,7 +1078,7 @@ void ast_config_hook_unregister(const char *name);
* a set of flags to specify the result format and checks to perform,
* a pointer to the result, and optionally some additional arguments.
*
* \return It returns 0 on success, != 0 otherwise.
* \return 0 on success, != 0 otherwise.
*/
enum ast_parse_flags {
/* low 4 bits of flags are used for the operand type */
@ -1141,7 +1144,7 @@ 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.
* \param result pointer to the result. NULL is valid here, and can
* \param p_result pointer to the result. NULL is valid here, and can
* be used to perform only the validity checks.
* \param ... extra arguments are required according to flags.
*
@ -1174,7 +1177,7 @@ enum ast_parse_flags {
* returns 1 because port is missing, sa contains address
*/
int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
void *result, ...);
void *p_result, ...);
/*
* Parsing config file options in C is slightly annoying because we cannot use

52
include/asterisk/config_options.h
View File

@ -76,7 +76,7 @@ enum aco_matchtype {
typedef void *(*aco_type_item_alloc)(const char *category);
/*! \brief Find a item given a category and container of items
* \param container The container to search for the item
* \param newcontainer The container to search for the item
* \param category The category associated with the item
* \retval non-NULL item from the container
* \retval NULL item does not exist in container
@ -265,13 +265,13 @@ enum aco_option_type {
* FLDSET macro with the field of type struct ast_ha *.
*
* Example:
* {code}
* \code
* struct test_item {
* struct ast_ha *ha;
* };
* aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
* aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
* {code}
* \endcode
*/
OPT_ACL_T,
@ -284,12 +284,12 @@ enum aco_option_type {
* cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
*
* Example:
* {code}
* \code
* struct test_item {
* int enabled;
* };
* aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
* {endcode}
* \endcode
*/
OPT_BOOL_T,
@ -302,13 +302,13 @@ enum aco_option_type {
* The flag to set
*
* Example:
* {code}
* \code
* #define MY_TYPE_ISQUIET 1 << 4
* struct test_item {
* unsigned int flags;
* };
* aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET);
* {endcode}
* \endcode
*/
OPT_BOOLFLAG_T,
@ -320,12 +320,12 @@ enum aco_option_type {
* CHARFLDSET macro with a field of type char[]
*
* Example:
* {code}
* \code
* struct test_item {
* char description[128];
* };
* aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description));
* {endcode}
* \endcode
*/
OPT_CHAR_ARRAY_T,
@ -337,13 +337,13 @@ enum aco_option_type {
* FLDSET macro with field representing a struct ast_format_cap *
*
* Example:
* {code}
* \code
* struct test_item {
* struct ast_format cap *cap;
* };
* aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
* aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
* {endcode}
* \endcode
*/
OPT_CODEC_T,
@ -361,9 +361,9 @@ enum aco_option_type {
* struct test_item {
* double dub;
* };
* {code}
* \code
* aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
* {endcode}
* \endcode
*/
OPT_DOUBLE_T,
@ -385,9 +385,9 @@ enum aco_option_type {
* struct test_item {
* int32_t intopt;
* };
* {code}
* \code
* aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
* {endcode}
* \endcode
*/
OPT_INT_T,
@ -406,12 +406,12 @@ enum aco_option_type {
* FLDSET macro with the field being of type struct ast_sockaddr.
*
* Example:
* {code}
* \code
* struct test_item {
* struct ast_sockaddr addr;
* };
* aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
* {endcode}
* \endcode
*/
OPT_SOCKADDR_T,
@ -423,14 +423,14 @@ enum aco_option_type {
* STRFLDSET macro with the field being the field created by AST_STRING_FIELD
*
* Example:
* {code}
* \code
* struct test_item {
* AST_DECLARE_STRING_FIELDS(
* AST_STRING_FIELD(thing);
* );
* };
* aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing));
* {endcode}
* \endcode
*/
OPT_STRINGFIELD_T,
@ -452,9 +452,9 @@ enum aco_option_type {
* struct test_item {
* int32_t intopt;
* };
* {code}
* \code
* aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
* {endcode}
* \endcode
*/
OPT_UINT_T,
@ -471,12 +471,12 @@ enum aco_option_type {
* "yes" or "no".
*
* Example:
* {code}
* \code
* struct test_item {
* int enabled;
* };
* aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled));
* {endcode}
* \endcode
*/
OPT_YESNO_T,
@ -498,9 +498,9 @@ enum aco_option_type {
* struct test_item {
* int timelen;
* };
* {code}
* \code
* aco_option_register(&cfg_info, "timelen", ACO_EXACT, my_types, "3", OPT_TIMELEN_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), TIMELEN_MILLISECONDS, -10, 10);
* {endcode}
* \endcode
*/
OPT_TIMELEN_T,
@ -681,7 +681,7 @@ unsigned int aco_option_get_flags(const struct aco_option *option);
* \brief Get the offset position for an argument within a config option
*
* \param option Pointer to the aco_option struct
* \param arg Argument number
* \param position Argument number
*
* \retval position of the argument
*/

15
include/asterisk/core_unreal.h
View File

@ -95,7 +95,7 @@ struct ast_unreal_pvt {
struct ast_format_cap *reqcap; /*!< Requested format capabilities */
struct ast_jb_conf jb_conf; /*!< jitterbuffer configuration */
unsigned int flags; /*!< Private option flags */
/*! Base name of the unreal channels. exten@context or other name. */
/*! Base name of the unreal channels. exten\@context or other name. */
char name[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
struct ast_stream_topology *reqtopology; /*!< Requested stream topology */
struct ast_stream_topology *owner_old_topology; /*!< Stored topology for owner side when we need to restore later (faxing) */
@ -176,8 +176,6 @@ int ast_unreal_setoption(struct ast_channel *chan, int option, void *data, int d
* \since 12.0.0
*
* \param vdoomed Object to destroy.
*
* \return Nothing
*/
void ast_unreal_destructor(void *vdoomed);
@ -189,7 +187,7 @@ void ast_unreal_destructor(void *vdoomed);
* \param destructor Destructor callback.
* \param cap Format capabilities to give the unreal private struct.
*
* \retval pvt on success.
* \return pvt on success.
* \retval NULL on error.
*/
struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructor, struct ast_format_cap *cap);
@ -201,9 +199,9 @@ struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructo
*
* \param size Size of the unreal struct to allocate.
* \param destructor Destructor callback.
* \param cap Format capabilities to give the unreal private struct.
* \param topology
*
* \retval pvt on success.
* \return pvt on success.
* \retval NULL on error.
*/
struct ast_unreal_pvt *ast_unreal_alloc_stream_topology(size_t size, ao2_destructor_fn destructor, struct ast_stream_topology *topology);
@ -218,10 +216,11 @@ struct ast_unreal_pvt *ast_unreal_alloc_stream_topology(size_t size, ao2_destruc
* \param semi2_state State to start the semi2(outgoing chan) channel in.
* \param exten Exten to start the chennels in. (NULL if s)
* \param context Context to start the channels in. (NULL if default)
* \param assignedids
* \param requestor Channel requesting creation. (NULL if none)
* \param callid Thread callid to use.
*
* \retval semi1_channel on success.
* \return semi1_channel on success.
* \retval NULL on error.
*/
struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
@ -237,8 +236,6 @@ struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
* \param semi2 Outgoing channel of unreal channel pair.
*
* \note On entry, the semi1 and semi2 channels are already locked.
*
* \return Nothing
*/
void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2);

14
include/asterisk/crypto.h
View File

@ -46,13 +46,13 @@ struct ast_key;
/*!
* \brief Retrieve a key
* \param key Name of the key we are retrieving
* \param type Intger type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE)
* \param kname Name of the key we are retrieving
* \param ktype Intger type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE)
*
* \retval the key on success.
* \retval NULL on failure.
*/
AST_OPTIONAL_API(struct ast_key *, ast_key_get, (const char *key, int type), { return NULL; });
AST_OPTIONAL_API(struct ast_key *, ast_key_get, (const char *kname, int ktype), { return NULL; });
/*!
* \brief Check the authenticity of a message signature using a given public key
@ -71,13 +71,13 @@ AST_OPTIONAL_API(int, ast_check_signature, (struct ast_key *key, const char *msg
* \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
* \param dsig the proposed valid signature in raw binary representation
*
* \retval 0 if the signature is valid.
* \retval -1 otherwise.
*
*/
AST_OPTIONAL_API(int, ast_check_signature_bin, (struct ast_key *key, const char *msg, int msglen, const unsigned char *sig), { return -1; });
AST_OPTIONAL_API(int, ast_check_signature_bin, (struct ast_key *key, const char *msg, int msglen, const unsigned char *dsig), { return -1; });
/*!
* \brief Sign a message signature using a given private key
@ -97,14 +97,14 @@ AST_OPTIONAL_API(int, ast_sign, (struct ast_key *key, char *msg, char *sig), { r
* \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
* \param dsig a pointer to a buffer of at least 128 bytes in which the
* raw encoded signature will be stored
*
* \retval 0 on success.
* \retval -1 on failure.
*
*/
AST_OPTIONAL_API(int, ast_sign_bin, (struct ast_key *key, const char *msg, int msglen, unsigned char *sig), { return -1; });
AST_OPTIONAL_API(int, ast_sign_bin, (struct ast_key *key, const char *msg, int msglen, unsigned char *dsig), { return -1; });
/*!
* \brief Encrypt a message using a given private key

6
include/asterisk/data_buffer.h
View File

@ -43,7 +43,7 @@ struct ast_data_buffer;
/*!
* \brief A callback function to free a data payload in a data buffer
*
* \param The data payload
* \param data The data payload
*/
typedef void (*ast_data_buffer_free_callback)(void *data);
@ -153,7 +153,7 @@ void ast_data_buffer_free(struct ast_data_buffer *buffer);
*
* \param buffer The data buffer
*
* \retval the number of data payloads
* \return the number of data payloads
*
* \since 15.4.0
*/
@ -164,7 +164,7 @@ size_t ast_data_buffer_count(const struct ast_data_buffer *buffer);
*
* \param buffer The data buffer
*
* \retval the maximum number of data payloads
* \return the maximum number of data payloads
*
* \since 15.4.0
*/

18
include/asterisk/devicestate.h
View File

@ -128,7 +128,7 @@ enum ast_device_state ast_parse_device_state(const char *device);
* Tries the channel device state callback if not supported search in the
* active channels list for the device.
*
* \retval an AST_DEVICE_??? state
* \return an AST_DEVICE_??? state
*/
enum ast_device_state ast_device_state(const char *device);
@ -196,7 +196,6 @@ struct ast_devstate_aggregate;
*
* \param[in] agg the state object
*
* \return nothing
* \since 1.6.1
*/
void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
@ -207,7 +206,6 @@ void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
* \param[in] agg the state object
* \param[in] state the state to add
*
* \return nothing
* \since 1.6.1
*/
void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_device_state state);
@ -256,7 +254,7 @@ struct ast_device_state_message {
/*!
* \brief Get the Stasis topic for device state messages
* \retval The topic for device state messages
* \return The topic for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
@ -264,8 +262,8 @@ struct stasis_topic *ast_device_state_topic_all(void);
/*!
* \brief Get the Stasis topic for device state messages for a specific device
* \param uniqueid The device for which to get the topic
* \retval The topic structure for MWI messages for a given device
* \param device The device for which to get the topic
* \return The topic structure for MWI messages for a given device
* \retval NULL if it failed to be found or allocated
* \since 12
*/
@ -273,7 +271,7 @@ struct stasis_topic *ast_device_state_topic(const char *device);
/*!
* \brief Get the Stasis caching topic for device state messages
* \retval The caching topic for device state messages
* \return The caching topic for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
@ -281,14 +279,14 @@ struct stasis_topic *ast_device_state_topic_cached(void);
/*!
* \brief Backend cache for ast_device_state_topic_cached()
* \retval Cache of \ref ast_device_state_message.
* \return Cache of \ref ast_device_state_message.
* \since 12
*/
struct stasis_cache *ast_device_state_cache(void);
/*!
* \brief Get the Stasis message type for device state messages
* \retval The message type for device state messages
* \return The message type for device state messages
* \retval NULL if it has not been allocated
* \since 12
*/
@ -296,7 +294,7 @@ struct stasis_message_type *ast_device_state_message_type(void);
/*!
* \brief Clear the device from the stasis cache.
* \param The device to clear
* \param device The device to clear
* \retval 0 if successful
* \retval -1 nothing to clear
* \since 12

22
include/asterisk/dial.h
View File

@ -93,7 +93,7 @@ int ast_dial_append_channel(struct ast_dial *dial, struct ast_channel *chan);
* \param chan Optional dialing channel
* \param cap Optional requested capabilities
* \retval -1 failure
* \reval 0 success
* \retval 0 success
*/
int ast_dial_prerun(struct ast_dial *dial, struct ast_channel *chan, struct ast_format_cap *cap);
@ -136,7 +136,8 @@ void ast_dial_hangup(struct ast_dial *dial);
/*! \brief Destroys a dialing structure
* \note Cancels dialing and destroys (free's) the given ast_dial structure
* \param dial Dialing structure to free
* \return Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_dial_destroy(struct ast_dial *dial);
@ -144,7 +145,8 @@ int ast_dial_destroy(struct ast_dial *dial);
* \param dial Dial structure to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data);
@ -153,14 +155,16 @@ int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option op
* \param num Channel number to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data);
/*! \brief Disables an option globally
* \param dial Dial structure to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option);
@ -168,7 +172,8 @@ int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option o
* \param dial Dial structure
* \param num Channel number to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option);
@ -189,27 +194,23 @@ struct ast_channel *ast_dial_get_channel(struct ast_dial *dial, int num);
/*! \brief Set a callback for state changes
* \param dial The dial structure to watch for state changes
* \param callback the callback
* \return nothing
*/
void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback);
/*! \brief Set user data on a dial structure
* \param dial The dial structure to set a user data pointer on
* \param user_data The user data pointer
* \return nothing
*/
void ast_dial_set_user_data(struct ast_dial *dial, void *user_data);
/*! \brief Return the user data on a dial structure
* \param dial The dial structure
* \return A pointer to the user data
*/
void *ast_dial_get_user_data(struct ast_dial *dial);
/*! \brief Set the maximum time (globally) allowed for trying to ring phones
* \param dial The dial structure to apply the time limit to
* \param timeout Maximum time allowed in milliseconds
* \return nothing
*/
void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout);
@ -217,7 +218,6 @@ void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout);
* \param dial The dial structure the channel belongs to
* \param num Channel number to set timeout on
* \param timeout Maximum time allowed in milliseconds
* \return nothing
*/
void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout);

4
include/asterisk/dns.h
View File

@ -38,10 +38,8 @@ enum ast_dns_search_result {
* \param dname Domain name to lookup (host, SRV domain, TXT record name).
* \param class Record Class (see "man res_search").
* \param type Record type (see "man res_search").
* \param answer The full DNS response.
* \param len The length of the full DNS response.
* \param callback Callback function for handling the discovered resource records from
* the DNS search.
* the DNS search. len gets the length of the full DNS response.
*
* \retval -1 on search failure
* \retval 0 on no records found

2
include/asterisk/dns_core.h
View File

@ -109,7 +109,7 @@ unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result);
/*!
* \brief Get the error rcode of a DN result
*
* \param query The DNS result
* \param result The DNS result
*
* \return the DNS rcode
*/

2
include/asterisk/dns_recurring.h
View File

@ -60,7 +60,7 @@ struct ast_dns_query_recurring *ast_dns_resolve_recurring(const char *name, int
/*!
* \brief Cancel an asynchronous recurring DNS resolution
*
* \param query The DNS query returned from ast_dns_resolve_recurring
* \param recurring The DNS query returned from ast_dns_resolve_recurring
*
* \retval 0 success - any active query has been cancelled and the query will no longer occur
* \retval -1 failure - an active query was in progress and could not be cancelled

2
include/asterisk/dns_resolver.h
View File

@ -83,7 +83,7 @@ void *ast_dns_resolver_get_data(const struct ast_dns_query *query);
* \brief Set result information for a DNS query
*
* \param query The DNS query
* \param result Whether the result is secured or not
* \param secure Whether the result is secured or not
* \param bogus Whether the result is bogus or not
* \param rcode Optional response code
* \param canonical The canonical name

2
include/asterisk/dnsmgr.h
View File

@ -80,8 +80,6 @@ struct ast_dnsmgr_entry *ast_dnsmgr_get_family(const char *name, struct ast_sock
* \brief Free a DNS manager entry
*
* \param entry the DNS manager entry to free
*
* \return nothing
*/
void ast_dnsmgr_release(struct ast_dnsmgr_entry *entry);

3
include/asterisk/event.h
View File

@ -100,9 +100,6 @@ struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
* \brief Destroy an event
*
* \param event the event to destroy
*
* \return Nothing
*
*/
void ast_event_destroy(struct ast_event *event);

6
include/asterisk/event_defs.h
View File

@ -332,11 +332,7 @@ enum ast_event_ie_pltype {
AST_EVENT_IE_PLTYPE_BITFLAGS,
};
/*!
* \brief Results for checking for subscribers
*
* \ref ast_event_check_subscriber()
*/
/*! \brief Results for checking for subscribers */
enum ast_event_subscriber_res {
/*! No subscribers exist */
AST_EVENT_SUB_NONE,

4
include/asterisk/features_config.h
View File

@ -203,7 +203,7 @@ struct ast_featuremap_config *ast_get_chan_featuremap_config(struct ast_channel
* \param chan The channel to get the option from
* \param feature The short name of the feature (as it appears in features.conf)
* \param[out] buf The buffer to write the DTMF value into
* \param size The size of the buffer in bytes
* \param len The size of the buffer in bytes
* \retval 0 Success
* \retval non-zero Unrecognized builtin feature name
*/
@ -222,7 +222,7 @@ int ast_get_builtin_feature(struct ast_channel *chan, const char *feature, char
* \param chan The channel to get the option from
* \param feature The short name of the feature
* \param[out] buf The buffer to write the DTMF value into
* \param size The size of the buffer in bytes
* \param len The size of the buffer in bytes
* \retval 0 Success
* \retval non-zero Unrecognized feature name
*/

42
include/asterisk/file.h
View File

@ -80,7 +80,7 @@ int ast_streamfile(struct ast_channel *c, const char *filename, const char *pref
* \brief stream file until digit
* If the file name is non-empty, try to play it.
* \note If digits == "" then we can simply check for non-zero.
* \return 0 if success.
* \retval 0 if success.
* \retval -1 if error.
* \retval digit if interrupted by a digit.
*/
@ -105,8 +105,8 @@ int ast_stopstream(struct ast_channel *c);
* \param fmt the format you wish to check (the extension)
* \param preflang (the preferred language you wisht to find the file in)
* See if a given file exists in a given format. If fmt is NULL, any format is accepted.
* \retval 0, false. The file does not exist
* \retval 1, true. The file does exist.
* \retval 0 The file does not exist
* \retval 1 The file does exist.
*/
int ast_fileexists(const char *filename, const char *fmt, const char *preflang);
@ -116,7 +116,7 @@ int ast_fileexists(const char *filename, const char *fmt, const char *preflang);
* \param newname the name you wish to rename the file to (minus the extension)
* \param fmt the format of the file
* Rename a given file in a given format, or if fmt is NULL, then do so for all
* \return -1 on failure
* \retval -1 on failure
*/
int ast_filerename(const char *oldname, const char *newname, const char *fmt);
@ -151,7 +151,7 @@ FILE *ast_file_mkftemp(char *template, mode_t mode);
* \param dir_name the name of the directory
* \param filename the name of the file
* \param obj user data object
* \return non-zero to stop reading, otherwise zero to continue
* \retval non-zero to stop reading, otherwise zero to continue
*
* \note dir_name is not processed by realpath or other functions,
* symbolic links are not resolved. This ensures dir_name
@ -166,7 +166,9 @@ typedef int (*ast_file_on_file)(const char *dir_name, const char *filename, void
* \param on_file callback called on each file
* \param obj user data object
* \param max_depth re-curse into sub-directories up to a given maximum (-1 = infinite)
* \return -1 or errno on failure, otherwise 0
* \retval -1 on failure
* \retval errno on failure
* \retval 0 otherwise
*/
int ast_file_read_dirs(const char *dir_name, ast_file_on_file on_file, void *obj, int max_depth);
@ -175,7 +177,9 @@ int ast_file_read_dirs(const char *dir_name, ast_file_on_file on_file, void *obj
* \param dir_name the name of the directory to search
* \param on_file callback called on each file
* \param obj user data object
* \return -1 or errno on failure, otherwise 0
* \return -1
* \retval errno on failure
* \retval 0 otherwise
*/
#define ast_file_read_dir(dir_name, on_file, obj) ast_file_read_dirs(dir_name, on_file, obj, 1)
@ -186,7 +190,7 @@ int ast_file_read_dirs(const char *dir_name, ast_file_on_file on_file, void *obj
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a given digit to arrive,
* \retval 0 if the stream finishes
* \retval the character if it was interrupted by the channel.
* \retval character if it was interrupted by the channel.
* \retval -1 on error
*/
int ast_waitstream(struct ast_channel *c, const char *breakon);
@ -198,7 +202,7 @@ int ast_waitstream(struct ast_channel *c, const char *breakon);
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a valid extension digit to arrive,
* \retval 0 if the stream finishes.
* \retval the character if it was interrupted.
* \retval character if it was interrupted.
* \retval -1 on error.
*/
int ast_waitstream_exten(struct ast_channel *c, const char *context);
@ -213,8 +217,8 @@ int ast_waitstream_exten(struct ast_channel *c, const char *context);
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a given digit to arrive,
* \retval 0 if the stream finishes.
* \retval the character if it was interrupted,
* \retval the value of the control frame if it was interrupted by some other party,
* \retval character if it was interrupted,
* \return the value of the control frame if it was interrupted by some other party,
* \retval -1 on error.
*/
int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms);
@ -231,8 +235,8 @@ int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *fo
* Begins playback of a stream...
* Wait for a stream to stop or for any one of a given digit to arrive,
* \retval 0 if the stream finishes.
* \retval the character if it was interrupted,
* \retval the value of the control frame if it was interrupted by some other party,
* \retval character if it was interrupted,
* \return the value of the control frame if it was interrupted by some other party,
* \retval -1 on error.
*/
int ast_waitstream_fr_w_cb(struct ast_channel *c,
@ -245,7 +249,7 @@ int ast_waitstream_fr_w_cb(struct ast_channel *c,
/*!
* Same as waitstream, but with audio output to fd and monitored fd checking.
*
* \return 1 if monfd is ready for reading
* \retval 1 if monfd is ready for reading
*/
int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd);
@ -261,7 +265,7 @@ int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd,
* if check is non-zero, then it will not read a file if there are any files that
* start with that name and have an extension
* Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution.
* \retval a struct ast_filestream on success.
* \return a struct ast_filestream on success.
* \retval NULL on failure.
*/
struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
@ -278,7 +282,7 @@ struct ast_filestream *ast_readfile(const char *filename, const char *type, cons
* if check is non-zero, then it will not write a file if there are any files that
* start with that name and have an extension
* Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution.
* \retval a struct ast_filestream on success.
* \return a struct ast_filestream on success.
* \retval NULL on failure.
*/
struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
@ -307,7 +311,7 @@ int ast_closestream(struct ast_filestream *f);
* \param chan channel to work with
* \param filename to use
* \param preflang prefered language to use
* \retval a ast_filestream pointer if it opens the file.
* \return a ast_filestream pointer if it opens the file.
* \retval NULL on error.
*/
struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang);
@ -327,7 +331,7 @@ struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char
* \param chan channel to work with
* \param filename to use
* \param preflang prefered language to use
* \retval a ast_filestream pointer if it opens the file.
* \return a ast_filestream pointer if it opens the file.
* \retval NULL on error.
*/
struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang);
@ -432,7 +436,7 @@ char *ast_format_str_reduce(char *fmts);
* \param file_ext The file extension for which to find the format
*
* \retval NULL if not found
* \retval A pointer to the ast_format associated with this file extension
* \return A pointer to the ast_format associated with this file extension
*/
struct ast_format *ast_get_format_for_file_ext(const char *file_ext);

10
include/asterisk/format.h
View File

@ -66,7 +66,7 @@ struct ast_format_interface {
* \param format1 First format to compare
* \param format2 Second format which the first is compared against
*
* \retval ast_format_cmp_res representing the result of comparing format1 and format2.
* \return \ref ast_format_cmp_res representing the result of comparing format1 and format2.
*/
enum ast_format_cmp_res (* const format_cmp)(const struct ast_format *format1,
const struct ast_format *format2);
@ -188,7 +188,7 @@ struct ast_format *ast_format_clone(const struct ast_format *format);
/*!
* \brief Compare two formats
*
* \retval ast_format_cmp_res representing the result of comparing format1 and format2.
* \return \ref ast_format_cmp_res representing the result of comparing format1 and format2.
*/
enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
@ -301,7 +301,7 @@ const char *ast_format_get_name(const struct ast_format *format);
/*!
* \brief Get the channel count on a format
*
* \param The media format
* \param format The media format
*
* \return Currently set channel count
*/
@ -434,7 +434,7 @@ unsigned int ast_format_determine_length(const struct ast_format *format, unsign
* \since 12
* \brief Get the message type used for signaling a format registration
*
* \retval Stasis message type for format registration
* \return Stasis message type for format registration
* \retval NULL on error
*/
struct stasis_message_type *ast_format_register_type(void);
@ -443,7 +443,7 @@ struct stasis_message_type *ast_format_register_type(void);
* \since 12
* \brief Get the message type used for signaling a format unregistration
*
* \retval Stasis message type for format unregistration
* \return Stasis message type for format unregistration
* \retval NULL on error
*/
struct stasis_message_type *ast_format_unregister_type(void);

6
include/asterisk/format_cache.h
View File

@ -275,14 +275,12 @@ int ast_format_cache_set(struct ast_format *format);
* \note The returned format has its reference count incremented. It must be
* dropped using ao2_ref or ao2_cleanup.
*/
struct ast_format *__ast_format_cache_get(const char *name,
const char *tag, const char *file, int line, const char *func);
#define ast_format_cache_get(name) \
__ast_format_cache_get((name), "ast_format_cache_get", __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ast_t_format_cache_get(name, tag) \
__ast_format_cache_get((name), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ast_format *__ast_format_cache_get(const char *name,
const char *tag, const char *file, int line, const char *func);
/*!
* \brief Retrieve the best signed linear format given a sample rate.

20
include/asterisk/format_cap.h
View File

@ -43,17 +43,16 @@ enum ast_format_cap_flags {
*
* \param flags Modifiers of struct behavior.
*
* \retval ast_format_cap object on success.
* \return ast_format_cap object on success.
* \retval NULL on failure.
*/
struct ast_format_cap *__ast_format_cap_alloc(enum ast_format_cap_flags flags,
const char *tag, const char *file, int line, const char *func);
#define ast_format_cap_alloc(flags) \
__ast_format_cap_alloc((flags), "ast_format_cap_alloc", \
__FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ast_t_format_cap_alloc(flags, tag) \
__ast_format_cap_alloc((flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ast_format_cap *__ast_format_cap_alloc(enum ast_format_cap_flags flags,
const char *tag, const char *file, int line, const char *func);
/*!
* \brief Set the global framing.
@ -74,7 +73,7 @@ void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing
* \param cap The capabilities structure.
*
* \retval 0 if no formats are in the structure and no framing has been provided
* \retval The global framing value (in milliseconds)
* \return The global framing value (in milliseconds)
*
* \note This will be the minimum framing allowed across all formats in the
* capabilities structure, or an overridden value
@ -97,15 +96,14 @@ unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap);
*
* \note If framing is specified here it overrides any global framing that has been set.
*/
int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing,
const char *tag, const char *file, int line, const char *func);
#define ast_format_cap_append(cap, format, framing) \
__ast_format_cap_append((cap), (format), (framing), "ast_format_cap_append", \
__FILE__, __LINE__, __PRETTY_FUNCTION__)
#define ast_t_format_cap_append(cap, format, framing, tag) \
__ast_format_cap_append((cap), (format), (framing), (tag), \
__FILE__, __LINE__, __PRETTY_FUNCTION__)
int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing,
const char *tag, const char *file, int line, const char *func);
/*!
* \brief Add all codecs Asterisk knows about for a specific type to
@ -218,8 +216,8 @@ unsigned int ast_format_cap_get_format_framing(const struct ast_format_cap *cap,
*
* \note format must be an exact pointer match to remove from capabilities structure.
*
* \retval 0, remove was successful
* \retval -1, remove failed. Could not find format to remove
* \retval 0 remove was successful
* \retval -1 remove failed. Could not find format to remove
*/
int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
@ -248,7 +246,7 @@ struct ast_format *ast_format_cap_get_compatible_format(const struct ast_format_
/*!
* \brief Find if ast_format is within the capabilities of the ast_format_cap object.
*
* \retval ast_format_cmp_res representing the result of the compatibility check between cap and format.
* \return ast_format_cmp_res representing the result of the compatibility check between cap and format.
*/
enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format);

9
include/asterisk/fskmodem_float.h
View File

@ -57,14 +57,13 @@ typedef struct {
float cola_demod[NCOLA]; /*!< Queue of demodulated samples */
} fsk_data;
/* \brief Retrieve a serial byte into outbyte.
/*! \brief Retrieve a serial byte into outbyte.
Buffer is a pointer into a series of
shorts and len records the number of bytes in the buffer. len will be
overwritten with the number of bytes left that were not consumed.
\return return value is as follows:
\arg 0: Still looking for something...
\arg 1: An output byte was received and stored in outbyte
\arg -1: An error occured in the transmission
\retval 0 Still looking for something...
\retval 1 An output byte was received and stored in outbyte
\retval -1 An error occured in the transmission
He must be called with at least 80 bytes of buffer. */
int fsk_serial(fsk_data *fskd, short *buffer, int *len, int *outbyte);

9
include/asterisk/fskmodem_int.h
View File

@ -66,15 +66,6 @@ typedef struct {
} fsk_data;
/* \brief Retrieve a serial byte into outbyte.
Buffer is a pointer into a series of
shorts and len records the number of bytes in the buffer. len will be
overwritten with the number of bytes left that were not consumed.
\return return value is as follows:
\arg 0: Still looking for something...
\arg 1: An output byte was received and stored in outbyte
\arg -1: An error occured in the transmission
This must be called with at least 80 bytes of buffer. */
int fsk_serial(fsk_data *fskd, short *buffer, int *len, int *outbyte);
int fskmodem_init(fsk_data *fskd);

23
include/asterisk/hashtab.h
View File

@ -126,8 +126,8 @@ int ast_is_prime(int num);
* \param a a character string
* \param b a character string
* \retval 0 if the strings match
* \retval <0 if string a is less than string b
* \retval >0 if string a is greater than string b
* \retval negative if string a is less than string b
* \retval positive if string a is greater than string b
*/
int ast_hashtab_compare_strings(const void *a, const void *b);
@ -137,8 +137,8 @@ int ast_hashtab_compare_strings(const void *a, const void *b);
* \param a a character string
* \param b a character string
* \retval 0 if the strings match
* \retval <0 if string a is less than string b
* \retval >0 if string a is greater than string b
* \retval negative if string a is less than string b
* \retval positive if string a is greater than string b
*/
int ast_hashtab_compare_strings_nocase(const void *a, const void *b);
@ -190,7 +190,7 @@ int ast_hashtab_resize_tight(struct ast_hashtab *tab);
* of load factor.
*
* \param tab the hash table to operate on
* \return 0 is always returned
* \retval 0 is always returned
*/
int ast_hashtab_resize_none(struct ast_hashtab *tab);
@ -251,6 +251,8 @@ unsigned int ast_hashtab_hash_short(const short num);
* \param hash a func ptr to do the hashing
* \param do_locking use locks to guarantee safety of iterators/insertion/deletion -- real simpleminded right now
*/
#define ast_hashtab_create(initial_buckets, compare, resize, newsize, hash, do_locking) \
_ast_hashtab_create(initial_buckets, compare, resize, newsize, hash, do_locking, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ast_hashtab *_ast_hashtab_create(int initial_buckets,
int (*compare)(const void *a, const void *b),
int (*resize)(struct ast_hashtab *),
@ -258,8 +260,6 @@ struct ast_hashtab *_ast_hashtab_create(int initial_buckets,
unsigned int (*hash)(const void *obj),
int do_locking,
const char *file, int lineno, const char *function);
#define ast_hashtab_create(initial_buckets, compare, resize, newsize, hash, do_locking) \
_ast_hashtab_create(initial_buckets, compare, resize, newsize, hash, do_locking, __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief This func will free the hash table and all its memory.
@ -287,9 +287,9 @@ void ast_hashtab_destroy( struct ast_hashtab *tab, void (*objdestroyfunc)(void *
* \retval 1 on success
* \retval 0 if there's a problem
*/
int _ast_hashtab_insert_immediate(struct ast_hashtab *tab, const void *obj, const char *file, int lineno, const char *func);
#define ast_hashtab_insert_immediate(tab, obj) \
_ast_hashtab_insert_immediate(tab, obj, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int _ast_hashtab_insert_immediate(struct ast_hashtab *tab, const void *obj, const char *file, int lineno, const char *func);
/*!
* \brief Insert without checking, hashing or locking
@ -301,15 +301,16 @@ int _ast_hashtab_insert_immediate(struct ast_hashtab *tab, const void *obj, cons
* \retval 1 on success
* \retval 0 if there's a problem
*/
int _ast_hashtab_insert_immediate_bucket(struct ast_hashtab *tab, const void *obj, unsigned int h, const char *file, int lineno, const char *func);
#define ast_hashtab_insert_immediate_bucket(tab, obj, h) \
_ast_hashtab_insert_immediate_bucket(tab, obj, h, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int _ast_hashtab_insert_immediate_bucket(struct ast_hashtab *tab, const void *obj, unsigned int h, const char *file, int lineno, const char *func);
/*!
* \brief Check and insert new object only if it is not there.
* \note Will force a resize if the resize func returns 1
* \retval 1 on success
* \retval 0 if there's a problem, or it's already there.
* \retval 0 if there's a problem, or it's already there.
*/
int _ast_hashtab_insert_safe(struct ast_hashtab *tab, const void *obj, const char *file, int lineno, const char *func);
#define ast_hashtab_insert_safe(tab, obj) \
@ -319,7 +320,7 @@ int _ast_hashtab_insert_safe(struct ast_hashtab *tab, const void *obj, const cha
* \brief Lookup this object in the hash table.
* \param tab
* \param obj
* \retval a ptr if found
* \return a ptr if found
* \retval NULL if not found
*/
void * ast_hashtab_lookup(struct ast_hashtab *tab, const void *obj);

11
include/asterisk/heap.h
View File

@ -97,17 +97,17 @@ typedef int (*ast_heap_cmp_fn)(void *elm1, void *elm2);
* \return An instance of a max heap
* \since 1.6.1
*/
struct ast_heap *_ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_fn,
ssize_t index_offset, const char *file, int lineno, const char *func);
#define ast_heap_create(init_height, cmp_fn, index_offset) \
_ast_heap_create(init_height, cmp_fn, index_offset, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ast_heap *_ast_heap_create(unsigned int init_height, ast_heap_cmp_fn cmp_fn,
ssize_t index_offset, const char *file, int lineno, const char *func);
/*!
* \brief Destroy a max heap
*
* \param h the heap to destroy
*
* \return NULL for convenience
* \retval NULL for convenience
* \since 1.6.1
*/
struct ast_heap *ast_heap_destroy(struct ast_heap *h);
@ -122,9 +122,9 @@ struct ast_heap *ast_heap_destroy(struct ast_heap *h);
* \retval non-zero failure
* \since 1.6.1
*/
int _ast_heap_push(struct ast_heap *h, void *elm, const char *file, int lineno, const char *func);
#define ast_heap_push(h, elm) \
_ast_heap_push(h, elm, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int _ast_heap_push(struct ast_heap *h, void *elm, const char *file, int lineno, const char *func);
/*!
* \brief Pop the max element off of the heap
@ -145,7 +145,8 @@ void *ast_heap_pop(struct ast_heap *h);
* \param h the heap to remove from
* \param elm the element to remove
*
* \return elm, if the removal was successful, or NULL if it failed
* \return elm, if the removal was successful
* \retval NULL if it failed
*
* \note the index_offset parameter to ast_heap_create() is required to be able
* to use this function.

28
include/asterisk/http.h
View File

@ -136,7 +136,7 @@ struct ast_http_auth {
*
* \param headers HTTP request headers.
* \return HTTP auth structure.
* \return \c NULL if no supported HTTP auth headers present.
* \retval NULL if no supported HTTP auth headers present.
* \since 12
*/
struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
@ -246,8 +246,6 @@ void ast_http_prefix(char *buf, int len);
* \param ser HTTP TCP/TLS session object.
*
* \note Call before ast_http_error() to make the connection close.
*
* \return Nothing
*/
void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *ser);
@ -257,8 +255,6 @@ void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *se
*
* \param ser HTTP TCP/TLS session object.
* \param read_success TRUE if body was read successfully.
*
* \return Nothing
*/
void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
@ -291,7 +287,7 @@ struct ast_json;
* \param ser TCP/TLS session object
* \param headers List of HTTP headers
* \return Parsed JSON content body
* \return \c NULL on error, if no content, or if different content type.
* \retval NULL on error, if no content, or if different content type.
* \since 12
*/
struct ast_json *ast_http_get_json(
@ -302,7 +298,7 @@ struct ast_json *ast_http_get_json(
* \param buf the http response line information
* \param version the expected http version (e.g. HTTP/1.1)
* \param code the expected status code
* \return -1 if version didn't match or status code conversion fails.
* \retval -1 if version didn't match or status code conversion fails.
* \return status code (>0)
* \since 13
*/
@ -317,9 +313,9 @@ int ast_http_response_status_line(const char *buf, const char *version, int code
* \param buf a string containing the name/value to point to
* \param name out parameter pointing to the header name
* \param value out parameter pointing to header value
* \return -1 if buf is empty
* \return 0 if buf could be separated into name and value
* \return 1 if name or value portion don't exist
* \retval -1 if buf is empty
* \retval 0 if buf could be separated into name and value
* \retval 1 if name or value portion don't exist
* \since 13
*/
int ast_http_header_parse(char *buf, char **name, char **value);
@ -331,9 +327,9 @@ int ast_http_header_parse(char *buf, char **name, char **value);
* \param expected_name the expected name of the header
* \param value header value to check
* \param expected_value the expected value of the header
* \return 0 if the name and expected name do not match
* \return -1 if the value and expected value do not match
* \return 1 if the both the name and value match their expected value
* \retval 0 if the name and expected name do not match
* \retval -1 if the value and expected value do not match
* \retval 1 if the both the name and value match their expected value
* \since 13
*/
int ast_http_header_match(const char *name, const char *expected_name,
@ -348,9 +344,9 @@ int ast_http_header_match(const char *name, const char *expected_name,
* \param expected_name the expected name of the header
* \param value header value to check if in expected value
* \param expected_value the expected value(s)
* \return 0 if the name and expected name do not match
* \return -1 if the value and is not in the expected value
* \return 1 if the name matches expected name and value is in expected value
* \retval 0 if the name and expected name do not match
* \retval -1 if the value and is not in the expected value
* \retval 1 if the name matches expected name and value is in expected value
* \since 13
*/
int ast_http_header_match_in(const char *name, const char *expected_name,

38
include/asterisk/io.h
View File

@ -81,7 +81,7 @@ typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
* \param data data to pass to the callback
* Watch for any of revents activities on fd, calling callback with data as
* callback data.
* \retval a pointer to ID of the IO event
* \return a pointer to ID of the IO event
* \retval NULL on failure
*/
int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
@ -94,9 +94,9 @@ int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events
* \param callback new callback function
* \param events event mask to wait for
* \param data data to pass to the callback function
* Change an I/O handler, updating fd if > -1, callback if non-null,
* and revents if >-1, and data if non-null.
* \retval a pointer to the ID of the IO event
* Change an I/O handler, updating fd if \> -1, callback if non-null,
* and revents if \> -1, and data if non-null.
* \return a pointer to the ID of the IO event
* \retval NULL on failure
*/
int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
@ -118,26 +118,36 @@ int ast_io_remove(struct io_context *ioc, int *id);
* Wait for I/O to happen, returning after
* howlong milliseconds, and after processing
* any necessary I/O.
* \return he number of I/O events which took place.
* \return the number of I/O events which took place.
*/
int ast_io_wait(struct io_context *ioc, int howlong);
/*!
* \brief Dumps the IO array.
* \param ioc
* Debugging: Dump everything in the I/O array
*/
void ast_io_dump(struct io_context *ioc);
/*! Set fd into non-echoing mode (if fd is a tty) */
/*!
* \brief Hide password.
* \param fd
* Set fd into non-echoing mode (if fd is a tty)
*/
int ast_hide_password(int fd);
/*!
* \brief Restores TTY mode.
* Call with result from previous ast_hide_password
* \param fd, oldstatus
* Call with result from previous \ref ast_hide_password
*/
int ast_restore_tty(int fd, int oldstatus);
/*!
* \brief Columns of Terminal.
* \param fd
* Falls back to 80 if the underlying ioctl fails.
*/
int ast_get_termcols(int fd);
/*!
@ -145,7 +155,9 @@ int ast_get_termcols(int fd);
* \param state a string that states the changes. See sd_notify(3).
* The wrapper does nothing if systemd ('s development headers) was not
* detected on the system.
* \returns >=0 on success, negative value on error.
* \retval 0 on success.
* \retval positie on success.
* \retval negative on error.
*/
int ast_sd_notify(const char *state);
@ -153,8 +165,8 @@ int ast_sd_notify(const char *state);
* \brief Find a listening file descriptor provided by socket activation.
* \param type SOCK_STREAM or SOCK_DGRAM
* \param addr The socket address of the bound listener.
* \retval <0 No match.
* \retval >0 File Descriptor matching sockaddr.
* \retval negative No match.
* \retval positive File Descriptor matching sockaddr.
*
* \note This function returns -1 if systemd's development headers were not
* detected on the system.
@ -165,8 +177,8 @@ int ast_sd_get_fd(int type, const struct ast_sockaddr *addr);
* \brief Find a listening AF_LOCAL file descriptor provided by socket activation.
* \param type SOCK_STREAM or SOCK_DGRAM
* \param path The path of the listener.
* \retval <0 No match.
* \retval >0 File Descriptor matching path.
* \retval negative No match.
* \retval positive File Descriptor matching path.
*
* \note This function returns -1 if systemd's development headers were not
* detected on the system.

20
include/asterisk/iostream.h
View File

@ -43,8 +43,6 @@ struct ast_iostream; /* forward declaration */
* \brief Disable the iostream timeout timer.
*
* \param stream A pointer to an iostream
*
* \return Nothing
*/
void ast_iostream_set_timeout_disable(struct ast_iostream *stream);
@ -59,8 +57,6 @@ void ast_iostream_set_timeout_disable(struct ast_iostream *stream);
*
* \note Setting timeout to -1 disables the timeout.
* \note Setting this timeout replaces the I/O sequence timeout timer.
*
* \return Nothing
*/
void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout);
@ -79,8 +75,6 @@ void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeou
* \a timeout_reset to \c 30000.
*
* \note Setting either of these timeouts to -1 will disable them.
*
* \return Nothing
*/
void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int timeout, int timeout_reset);
@ -97,8 +91,6 @@ void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int t
*
* \note Setting timeout to -1 disables the timeout.
* \note Setting this timeout replaces the inactivity timeout timer.
*
* \return Nothing
*/
void ast_iostream_set_timeout_sequence(struct ast_iostream *stream, struct timeval start, int timeout);
@ -111,8 +103,6 @@ void ast_iostream_set_timeout_sequence(struct ast_iostream *stream, struct timev
* trying to send data.
*
* \note The stream timeouts still need to be set.
*
* \return Nothing
*/
void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive_input);
@ -121,8 +111,8 @@ void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive
*
* \param stream A pointer to an iostream
*
* \return The file descriptor for the given iostream, or -1 if the iostream has no open
* file descriptor.
* \return The file descriptor for the given iostream
* \retval -1 if the iostream has no open file descriptor.
*/
int ast_iostream_get_fd(struct ast_iostream *stream);
@ -144,8 +134,6 @@ int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout);
* \brief Make an iostream non-blocking.
*
* \param stream A pointer to an iostream
*
* \return Nothing
*/
void ast_iostream_nonblock(struct ast_iostream *stream);
@ -154,8 +142,8 @@ void ast_iostream_nonblock(struct ast_iostream *stream);
*
* \param stream A pointer to an iostream
*
* \return A pointer to the OpenSSL \c SSL structure for the given iostream, or
* \c NULL if TLS has not been initiated.
* \return A pointer to the OpenSSL \c SSL structure for the given iostream
* \retval NULL if TLS has not been initiated.
*
* \note If OpenSSL support is not included in the build, this will always return
* \c NULL.

179
include/asterisk/json.h
View File

@ -184,7 +184,7 @@ enum ast_json_type ast_json_typeof(const struct ast_json *value);
* \since 12.0.0
* \param type Type to convert to string.
* \return Simple string for the type name (object, array, string, etc.)
* \return \c "?" for invalid types.
* \retval "?" for invalid types.
*/
const char *ast_json_typename(enum ast_json_type type);
@ -271,24 +271,24 @@ struct ast_json *ast_json_null(void);
/*!
* \brief Check if \a value is JSON true.
* \since 12.0.0
* \return True (non-zero) if \a value == \ref ast_json_true().
* \return False (zero) otherwise..
* \retval True (non-zero) if \a value == \ref ast_json_true().
* \retval False (zero) otherwise..
*/
int ast_json_is_true(const struct ast_json *value);
/*!
* \brief Check if \a value is JSON false.
* \since 12.0.0
* \return True (non-zero) if \a value == \ref ast_json_false().
* \return False (zero) otherwise.
* \retval True (non-zero) if \a value == \ref ast_json_false().
* \retval False (zero) otherwise.
*/
int ast_json_is_false(const struct ast_json *value);
/*!
* \brief Check if \a value is JSON null.
* \since 12.0.0
* \return True (non-zero) if \a value == \ref ast_json_false().
* \return False (zero) otherwise.
* \retval True (non-zero) if \a value == \ref ast_json_false().
* \retval False (zero) otherwise.
*/
int ast_json_is_null(const struct ast_json *value);
@ -304,7 +304,7 @@ int ast_json_is_null(const struct ast_json *value);
*
* \param value Value of new JSON string.
* \return Newly constructed string element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_string_create(const char *value);
@ -313,7 +313,7 @@ struct ast_json *ast_json_string_create(const char *value);
* \since 12.0.0
* \param string JSON string.
* \return Value of the string.
* \return \c NULL on error.
* \retval NULL on error.
*/
const char *ast_json_string_get(const struct ast_json *string);
@ -325,8 +325,8 @@ const char *ast_json_string_get(const struct ast_json *string);
*
* \param string JSON string to modify.
* \param value New value to store in \a string.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_string_set(struct ast_json *string, const char *value);
@ -338,7 +338,7 @@ int ast_json_string_set(struct ast_json *string, const char *value);
*
* \param format \c printf style format string.
* \return Newly allocated string.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_stringf(const char *format, ...) __attribute__((format(printf, 1, 2)));
@ -349,8 +349,10 @@ struct ast_json *ast_json_stringf(const char *format, ...) __attribute__((format
* The formatted value must be a valid ASCII or UTF-8 encoded string.
*
* \param format \c printf style format string.
* \param args
*
* \return Newly allocated string.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_vstringf(const char *format, va_list args) __attribute__((format(printf, 1, 0)));
@ -363,7 +365,7 @@ struct ast_json *ast_json_vstringf(const char *format, va_list args) __attribute
* \since 12.0.0
* \param value Value of the new JSON integer.
* \return Newly allocated integer.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_integer_create(intmax_t value);
@ -372,7 +374,7 @@ struct ast_json *ast_json_integer_create(intmax_t value);
* \since 12.0.0
* \param integer JSON integer.
* \return Value of a JSON integer.
* \return 0 if \a integer is not a JSON integer.
* \retval 0 if \a integer is not a JSON integer.
*/
intmax_t ast_json_integer_get(const struct ast_json *integer);
@ -381,8 +383,8 @@ intmax_t ast_json_integer_get(const struct ast_json *integer);
* \since 12.0.0
* \param integer JSON integer to modify.
* \param value New value for \a integer.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_integer_set(struct ast_json *integer, intmax_t value);
@ -391,7 +393,7 @@ int ast_json_integer_set(struct ast_json *integer, intmax_t value);
* \since 12.0.0
* \param value Value of the new JSON real number.
* \return Newly allocated real number.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_real_create(double value);
@ -400,17 +402,17 @@ struct ast_json *ast_json_real_create(double value);
* \since 12.0.0
* \param real JSON real number.
* \return Value of a JSON real number.
* \return 0 if \a real is not a JSON real number.
* \retval 0 if \a real is not a JSON real number.
*/
double ast_json_real_get(const struct ast_json *real);
/*!
* \brief Set the value of a JSON real number.
* \since 12.0.0
* \param integer JSON real number to modify.
* \param real JSON real number to modify.
* \param value New value for \a real.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_real_set(struct ast_json *real, double value);
@ -422,7 +424,7 @@ int ast_json_real_set(struct ast_json *real, double value);
* \brief Create a empty JSON array.
* \since 12.0.0
* \return Newly allocated array.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_array_create(void);
@ -431,7 +433,7 @@ struct ast_json *ast_json_array_create(void);
* \since 12.0.0
* \param array JSON array.
* \return Size of \a array.
* \return 0 if array is not a JSON array.
* \retval 0 if array is not a JSON array.
*/
size_t ast_json_array_size(const struct ast_json *array);
@ -445,8 +447,8 @@ size_t ast_json_array_size(const struct ast_json *array);
* \param array JSON array.
* \param index Zero-based index into \a array.
* \return The specified element.
* \return \c NULL if \a array not an array.
* \return \c NULL if \a index is out of bounds.
* \retval NULL if \a array not an array.
* if \a index is out of bounds.
*/
struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
@ -460,8 +462,8 @@ struct ast_json *ast_json_array_get(const struct ast_json *array, size_t index);
* \param array JSON array to modify.
* \param index Zero-based index into array.
* \param value New JSON value to store in \a array at \a index.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *value);
@ -474,8 +476,8 @@ int ast_json_array_set(struct ast_json *array, size_t index, struct ast_json *va
*
* \param array JSON array to modify.
* \param value New JSON value to store at the end of \a array.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_append(struct ast_json *array, struct ast_json *value);
@ -489,8 +491,8 @@ int ast_json_array_append(struct ast_json *array, struct ast_json *value);
* \param array JSON array to modify.
* \param index Zero-based index into array.
* \param value New JSON value to store in \a array at \a index.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json *value);
@ -499,8 +501,8 @@ int ast_json_array_insert(struct ast_json *array, size_t index, struct ast_json
* \since 12.0.0
* \param array JSON array to modify.
* \param index Zero-based index into array.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_remove(struct ast_json *array, size_t index);
@ -508,8 +510,8 @@ int ast_json_array_remove(struct ast_json *array, size_t index);
* \brief Remove all elements from an array.
* \since 12.0.0
* \param array JSON array to clear.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_clear(struct ast_json *array);
@ -521,8 +523,8 @@ int ast_json_array_clear(struct ast_json *array);
*
* \param array JSON array to modify.
* \param tail JSON array with contents to append to \a array.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_array_extend(struct ast_json *array, struct ast_json *tail);
@ -534,7 +536,7 @@ int ast_json_array_extend(struct ast_json *array, struct ast_json *tail);
* \brief Create a new JSON object.
* \since 12.0.0
* \return Newly allocated object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_object_create(void);
@ -543,7 +545,7 @@ struct ast_json *ast_json_object_create(void);
* \param variables A list of Asterisk variables
* \param excludes Comma separated string of variable names to exclude (optional)
* \return Newly allocated object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_object_create_vars(const struct ast_variable *variables, const char *excludes);
@ -552,7 +554,7 @@ struct ast_json *ast_json_object_create_vars(const struct ast_variable *variable
* \since 12.0.0
* \param object JSON object.
* \return Size of \a object.
* \return Zero of \a object is not a JSON object.
* \retval Zero of \a object is not a JSON object.
*/
size_t ast_json_object_size(struct ast_json *object);
@ -566,7 +568,7 @@ size_t ast_json_object_size(struct ast_json *object);
* \param object JSON object.
* \param key Key of field to look up.
* \return Value with given \a key.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
@ -577,15 +579,16 @@ struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
* \param object JSON object.
* \param key Key of string field to look up.
* \return String value of given \a key.
* \return \c NULL on error, or key value is not a string.
* \retval NULL on error, or key value is not a string.
*/
#define ast_json_object_string_get(object, key) ast_json_string_get(ast_json_object_get(object, key))
/*!
* \brief Get an integer field from a JSON object.
* \param integer JSON integer.
* \param object JSON object.
* \param key Key of integer field to look up.
* \return Value of a JSON integer.
* \return 0 if \a integer is not a JSON integer.
* \retval 0 if \a integer is not a JSON integer.
*/
#define ast_json_object_integer_get(object, key) ast_json_integer_get(ast_json_object_get(object, key))
@ -599,8 +602,8 @@ struct ast_json *ast_json_object_get(struct ast_json *object, const char *key);
* \param object JSON object to modify.
* \param key Key of field to set.
* \param value JSON value to set for field.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_set(struct ast_json *object, const char *key, struct ast_json *value);
@ -610,7 +613,7 @@ int ast_json_object_set(struct ast_json *object, const char *key, struct ast_jso
*
* \param object JSON object to modify.
* \param key Key of field to delete.
* \return 0 on success, or -1 if key does not exist.
* \retval 0 on success, or -1 if key does not exist.
*/
int ast_json_object_del(struct ast_json *object, const char *key);
@ -618,8 +621,8 @@ int ast_json_object_del(struct ast_json *object, const char *key);
* \brief Delete all elements from a JSON object.
* \since 12.0.0
* \param object JSON object to clear.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_clear(struct ast_json *object);
@ -632,8 +635,8 @@ int ast_json_object_clear(struct ast_json *object);
*
* \param object JSON object to modify.
* \param other JSON object to copy into \a object.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_update(struct ast_json *object, struct ast_json *other);
@ -647,8 +650,8 @@ int ast_json_object_update(struct ast_json *object, struct ast_json *other);
*
* \param object JSON object to modify.
* \param other JSON object to copy into \a object.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_update_existing(struct ast_json *object, struct ast_json *other);
@ -662,8 +665,8 @@ int ast_json_object_update_existing(struct ast_json *object, struct ast_json *ot
*
* \param object JSON object to modify.
* \param other JSON object to copy into \a object.
* \return 0 on success.
* \return -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_update_missing(struct ast_json *object, struct ast_json *other);
@ -687,8 +690,8 @@ struct ast_json_iter;
*
* \param object JSON object.
* \return Iterator to the first field in \a object.
* \return \c NULL \a object is empty.
* \return \c NULL on error.
* \retval NULL \a object is empty.
* on error.
*/
struct ast_json_iter *ast_json_object_iter(struct ast_json *object);
@ -701,8 +704,8 @@ struct ast_json_iter *ast_json_object_iter(struct ast_json *object);
* \param object JSON object to iterate.
* \param key Key of field to lookup.
* \return Iterator pointing to the field with the given \a key.
* \return \c NULL if \a key does not exist.
* \return \c NULL on error.
* \retval NULL if \a key does not exist.
* on error.
*/
struct ast_json_iter *ast_json_object_iter_at(struct ast_json *object, const char *key);
@ -712,7 +715,7 @@ struct ast_json_iter *ast_json_object_iter_at(struct ast_json *object, const cha
* \param object JSON object \a iter was obtained from.
* \param iter JSON object iterator.
* \return Iterator to next field in \a object.
* \return \c NULL if \a iter was the last field.
* \retval NULL if \a iter was the last field.
*/
struct ast_json_iter *ast_json_object_iter_next(struct ast_json *object, struct ast_json_iter *iter);
@ -740,14 +743,14 @@ struct ast_json *ast_json_object_iter_value(struct ast_json_iter *iter);
* \brief Set the value of the field pointed to by an iterator.
* \since 12.0.0
*
* \note The object steals the \a value reference even if it returns error;
* \note The object steals the \p value reference even if it returns error;
* use ast_json_ref() to safely keep a pointer to it.
*
* \param object JSON object \a iter was obtained from.
* \param object JSON object \p iter was obtained from.
* \param iter JSON object iterator.
* \param value JSON value to store in \iter's field.
* \return 0 on success.
* \return -1 on error.
* \param value JSON value to store in \p iter's field.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_json_object_iter_set(struct ast_json *object, struct ast_json_iter *iter, struct ast_json *value);
@ -775,7 +778,7 @@ enum ast_json_encoding_format
*
* \param root JSON value.
* \return String encoding of \a root.
* \return \c NULL on error.
* \retval NULL on error.
*/
#define ast_json_dump_string(root) ast_json_dump_string_format(root, AST_JSON_COMPACT)
@ -788,7 +791,7 @@ enum ast_json_encoding_format
* \param root JSON value.
* \param format encoding format type.
* \return String encoding of \a root.
* \return \c NULL on error.
* \retval NULL on error.
*/
char *ast_json_dump_string_format(struct ast_json *root, enum ast_json_encoding_format format);
@ -803,8 +806,8 @@ char *ast_json_dump_string_format(struct ast_json *root, enum ast_json_encoding_
* \param root JSON value.
* \param dst \ref ast_str to store JSON encoding.
* \param format encoding format type.
* \return 0 on success.
* \return -1 on error. The contents of \a dst are undefined.
* \retval 0 on success.
* \retval -1 on error. The contents of \a dst are undefined.
*/
int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum ast_json_encoding_format format);
@ -817,8 +820,8 @@ int ast_json_dump_str_format(struct ast_json *root, struct ast_str **dst, enum a
* \param root JSON value.
* \param output File to write JSON encoding to.
* \param format encoding format type.
* \return 0 on success.
* \return -1 on error. The contents of \a output are undefined.
* \retval 0 on success.
* \retval -1 on error. The contents of \a output are undefined.
*/
int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json_encoding_format format);
@ -831,8 +834,8 @@ int ast_json_dump_file_format(struct ast_json *root, FILE *output, enum ast_json
* \param root JSON value.
* \param path Path to file to write JSON encoding to.
* \param format encoding format type.
* \return 0 on success.
* \return -1 on error. The contents of \a output are undefined.
* \retval 0 on success.
* \retval -1 on error. The contents of \a output are undefined.
*/
int ast_json_dump_new_file_format(struct ast_json *root, const char *path, enum ast_json_encoding_format format);
@ -852,7 +855,7 @@ struct ast_json_error {
int position;
/*! Error message */
char text[AST_JSON_ERROR_TEXT_LENGTH];
/*! Source of the error (filename or <string>) */
/*! Source of the error (filename or \<string\>) */
char source[AST_JSON_ERROR_TEXT_LENGTH];
};
@ -862,7 +865,7 @@ struct ast_json_error {
* \param input String to parse.
* \param[out] error Filled with information on error.
* \return Parsed JSON element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_load_string(const char *input, struct ast_json_error *error);
@ -872,7 +875,7 @@ struct ast_json *ast_json_load_string(const char *input, struct ast_json_error *
* \param input \ref ast_str to parse.
* \param[out] error Filled with information on error.
* \return Parsed JSON element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_load_str(const struct ast_str *input, struct ast_json_error *error);
@ -883,7 +886,7 @@ struct ast_json *ast_json_load_str(const struct ast_str *input, struct ast_json_
* \param buflen Length of \a buffer.
* \param[out] error Filled with information on error.
* \return Parsed JSON element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_load_buf(const char *buffer, size_t buflen, struct ast_json_error *error);
@ -893,7 +896,7 @@ struct ast_json *ast_json_load_buf(const char *buffer, size_t buflen, struct ast
* \param input \c FILE to parse.
* \param[out] error Filled with information on error.
* \return Parsed JSON element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_load_file(FILE *input, struct ast_json_error *error);
@ -903,7 +906,7 @@ struct ast_json *ast_json_load_file(FILE *input, struct ast_json_error *error);
* \param path Path of file to parse.
* \param[out] error Filled with information on error.
* \return Parsed JSON element.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_load_new_file(const char *path, struct ast_json_error *error);
@ -937,8 +940,8 @@ struct ast_json *ast_json_vpack(char const *format, va_list ap);
*
* \param lhs Value to compare.
* \param rhs Other value to compare.
* \return True (non-zero) if \a lhs and \a rhs are equal.
* \return False (zero) if they are not.
* \retval True (non-zero) if \a lhs and \a rhs are equal.
* \retval False (zero) if they are not.
*/
int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs);
@ -950,7 +953,7 @@ int ast_json_equal(const struct ast_json *lhs, const struct ast_json *rhs);
*
* \param value JSON value to copy.
* \return Shallow copy of \a value.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_copy(const struct ast_json *value);
@ -962,7 +965,7 @@ struct ast_json *ast_json_copy(const struct ast_json *value);
*
* \param value JSON value to copy.
* \return Deep copy of \a value.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_deep_copy(const struct ast_json *value);
@ -978,8 +981,8 @@ struct ast_json *ast_json_deep_copy(const struct ast_json *value);
* \brief Simple name/number pair.
* \param name Name
* \param number Number
* \return NULL if error (non-UTF8 characters, NULL inputs, etc.)
* \return JSON object with name and number fields
* \retval NULL on error (non-UTF8 characters, NULL inputs, etc.)
*/
struct ast_json *ast_json_name_number(const char *name, const char *number);
@ -993,7 +996,7 @@ struct ast_json *ast_json_name_number(const char *name, const char *number);
* \param tv \c timeval to encode.
* \param zone Text string of a standard system zoneinfo file. If NULL, the system localtime will be used.
* \return JSON string with ISO 8601 formatted date/time.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_timeval(const struct timeval tv, const char *zone);
@ -1005,7 +1008,7 @@ struct ast_json *ast_json_timeval(const struct timeval tv, const char *zone);
* \param addr ast_sockaddr to encode
* \param transport_type ast_transport to include in the address string if any. Should just be one.
* \return JSON string containing the IP address with optional transport information
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_json_ipaddr(const struct ast_sockaddr *addr, enum ast_transport transport_type);
@ -1048,8 +1051,8 @@ struct ast_json_payload {
*
* \param json the ast_json blob we are loading
*
* \return pointer to the ast_json_payload created
* \retval NULL if we fail to alloc it
* \retval pointer to the ast_json_payload created
*/
struct ast_json_payload *ast_json_payload_create(struct ast_json *json);

29
include/asterisk/logger.h
View File

@ -333,7 +333,7 @@ int ast_logger_register_level(const char *name);
/*!
* \brief Retrieve dynamic logging level id
* \param name The name of the level
* \retval The unique integer id for the given level
* \return The unique integer id for the given level
* \retval -1 if level name not found
*/
int ast_logger_get_dynamic_level(const char *name);
@ -341,7 +341,6 @@ int ast_logger_get_dynamic_level(const char *name);
/*!
* \brief Unregister a previously registered logger level
* \param name The name of the level to be unregistered
* \return nothing
* \since 1.8
*/
void ast_logger_unregister_level(const char *name);
@ -349,7 +348,7 @@ void ast_logger_unregister_level(const char *name);
/*!
* \brief Get the logger configured date format
*
* \retval The date format string
* \return The date format string
*
* \since 13.0.0
*/
@ -358,7 +357,7 @@ const char *ast_logger_get_dateformat(void);
/*!
* \brief factory function to create a new uniquely identifying callid.
*
* \retval The call id
* \return The call id
*/
ast_callid ast_create_callid(void);
@ -433,7 +432,6 @@ void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid);
* the data for these must be provided as additional parameters after
* the log message.
*
* \return nothing
* \since 1.8
*/
@ -477,8 +475,6 @@ extern int ast_verb_sys_level;
/*!
* \brief Re-evaluate the system max verbosity level (ast_verb_sys_level).
*
* \return Nothing
*/
void ast_verb_update(void);
@ -486,22 +482,18 @@ void ast_verb_update(void);
* \brief Register this thread's console verbosity level pointer.
*
* \param level Where the verbose level value is.
*
* \return Nothing
*/
void ast_verb_console_register(int *level);
/*!
* \brief Unregister this thread's console verbosity level.
*
* \return Nothing
*/
void ast_verb_console_unregister(void);
/*!
* \brief Get this thread's console verbosity level.
*
* \retval verbosity level of the console.
* \return verbosity level of the console.
*/
int ast_verb_console_get(void);
@ -509,8 +501,6 @@ int ast_verb_console_get(void);
* \brief Set this thread's console verbosity level.
*
* \param verb_level New level to set.
*
* \return Nothing
*/
void ast_verb_console_set(int verb_level);
@ -525,8 +515,6 @@ int ast_is_logger_initialized(void);
* \brief Set the maximum number of messages allowed in the processing queue
*
* \param queue_limit
*
* \return Nothing
*/
void ast_logger_set_queue_limit(int queue_limit);
@ -548,7 +536,8 @@ To start using it:
* You must have used --enable-dev-mode.
* In logger.conf, set a logger channel to output the "trace" level.
* Instrument your code as specified below.
* Use the cli or cli.conf to enable tracing: CLI> core set trace <trace_level> [ module ]
* Use the cli or cli.conf to enable tracing:
\verbatim CLI> core set trace <trace_level> [ module ] \endverbatim
Its simplest usage requires only 1 macro call that...
- Registers a destructor for a special variable that gets called when the
@ -697,7 +686,7 @@ void __attribute__((format (printf, 6, 7))) __ast_trace(const char *file, int li
/*!
* \brief Get the current indent level
*
* \returns The current indent level
* \return The current indent level
*/
unsigned long _ast_trace_get_indent(void);
#define ast_trace_get_indent() _ast_trace_get_indent()
@ -713,7 +702,7 @@ void _ast_trace_set_indent(unsigned long indent);
/*!
* \brief Increment the indent level
*
* \returns The new indent level
* \return The new indent level
*/
unsigned long _ast_trace_inc_indent(void);
#define ast_trace_inc_indent() _ast_trace_inc_indent()
@ -721,7 +710,7 @@ unsigned long _ast_trace_inc_indent(void);
/*!
* \brief Decrement the indent level
*
* \returns The new indent level
* \return The new indent level
*/
unsigned long _ast_trace_dec_indent(void);
#define ast_trace_dec_indent() _ast_trace_dec_indent()

29
include/asterisk/logger_category.h
View File

@ -33,7 +33,8 @@
/*!
* \brief Load/Initialize system wide logger category functionality
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -44,7 +45,8 @@ int ast_logger_category_load(void);
/*!
* \brief Unload system wide logger category functionality
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -56,10 +58,9 @@ int ast_logger_category_unload(void);
* \brief Register a debug level logger category
*
* \param name The name of the category
* \param id The unique id of the category
*
* \retval 0 if failed to register/retrieve an id. Otherwise it returns the id
* for the registered category.
* \retval 0 if failed to register/retrieve an id
* \return id for the registered category
*
* \since 16.14
* \since 17.8
@ -70,7 +71,8 @@ uintmax_t ast_debug_category_register(const char *name);
/*!
* \brief Un-register a debug level logger category
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -88,7 +90,8 @@ int ast_debug_category_unregister(const char *name);
* \param name The name of the category
* \param sublevel The debug sublevel output number
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -101,8 +104,7 @@ int ast_debug_category_set_sublevel(const char *name, int sublevel);
*
* Accepts an array of category names, and optional associated sublevels. Sublevels can
* be associated with a name by using a ':' as a separator. For example:
*
* <category name>:<category sublevel>
* \verbatim <category name>:<category sublevel> \endverbatim
*
* The given default sublevel is used if no sublevel is associated with a name.
*
@ -110,7 +112,8 @@ int ast_debug_category_set_sublevel(const char *name, int sublevel);
* \param size The size of the array (number of elements)
* \param default_sublevel The sublevel value to use if one is not associated with a name
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -126,7 +129,8 @@ int ast_debug_category_set_sublevels(const char * const *names, size_t size, int
* \param word The word to complete
* \param state The state
*
* \retval 0 Success, -1 Failure
* \retval 0 Success
* \retval -1 Failure
*
* \since 16.14
* \since 17.8
@ -143,7 +147,8 @@ char *ast_debug_category_complete(const char * const *argv, int argc, const char
* \param sublevel Current set sublevel must be this sublevel or less
* \param ids One or more unique category ids to check
*
* \retval 1 if allowed, 0 if not allowed
* \retval 1 if allowed
* \retval 0 if not allowed
*
* \since 16.14
* \since 17.8

42
include/asterisk/manager.h
View File

@ -314,8 +314,6 @@ void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
*
* \note You need to call astman_send_list_complete_start() and
* astman_send_list_complete_end() to send the AMI list completion event.
*
* \return Nothing
*/
void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
@ -334,8 +332,6 @@ void astman_send_listack(struct mansession *s, const struct message *m, char *ms
* \note Between calling astman_send_list_complete_start() and
* astman_send_list_complete_end() you can add additonal headers
* using astman_append().
*
* \return Nothing
*/
void astman_send_list_complete_start(struct mansession *s, const struct message *m, const char *event_name, int count);
@ -351,8 +347,6 @@ void astman_send_list_complete_start(struct mansession *s, const struct message
* \note Between calling astman_send_list_complete_start() and
* astman_send_list_complete_end() you can add additonal headers
* using astman_append().
*
* \return Nothing
*/
void astman_send_list_complete_end(struct mansession *s);
@ -383,7 +377,7 @@ int astman_datastore_remove(struct mansession *s, struct ast_datastore *datastor
/*!
* \brief Find a datastore on a session
*
* \retval pointer to the datastore if found
* \return pointer to the datastore if found
* \retval NULL if not found
* \since 1.6.1
*/
@ -416,7 +410,7 @@ struct ast_channel_snapshot;
* \param prefix What to prepend to the channel fields
*
* \retval NULL on error
* \retval ast_str* on success (must be ast_freed by caller)
* \return ast_str* on success (must be ast_freed by caller)
*/
struct ast_str *ast_manager_build_channel_state_string_prefix(
const struct ast_channel_snapshot *snapshot,
@ -430,7 +424,7 @@ struct ast_str *ast_manager_build_channel_state_string_prefix(
* body
*
* \retval NULL on error
* \retval ast_str* on success (must be ast_freed by caller)
* \return ast_str* on success (must be ast_freed by caller)
*/
struct ast_str *ast_manager_build_channel_state_string(
const struct ast_channel_snapshot *snapshot);
@ -458,7 +452,7 @@ struct ast_json;
* \param exclusion_cb A \ref key_exclusion_cb pointer to a function that will exclude
* keys from the final AMI string
*
* \retval A malloc'd \ref ast_str object. Callers of this function should free
* \return A malloc'd \ref ast_str object. Callers of this function should free
* the returned \ref ast_str object
* \retval NULL on error
*/
@ -473,7 +467,7 @@ struct ast_str *ast_manager_str_from_json_object(struct ast_json *blob, key_excl
* \param prefix What to prepend to the bridge fields
*
* \retval NULL on error
* \retval ast_str* on success (must be ast_freed by caller)
* \return ast_str* on success (must be ast_freed by caller)
*/
struct ast_str *ast_manager_build_bridge_state_string_prefix(
const struct ast_bridge_snapshot *snapshot,
@ -487,7 +481,7 @@ struct ast_str *ast_manager_build_bridge_state_string_prefix(
* body
*
* \retval NULL on error
* \retval ast_str* on success (must be ast_freed by caller)
* \return ast_str* on success (must be ast_freed by caller)
*/
struct ast_str *ast_manager_build_bridge_state_string(
const struct ast_bridge_snapshot *snapshot);
@ -512,8 +506,8 @@ struct ast_manager_event_blob {
* \param extra_fields_fmt Format string for extra fields to include.
* Or NO_EXTRA_FIELDS for no extra fields.
*
* \return New \ref ast_manager_snapshot_event object.
* \return \c NULL on error.
* \return New \ref ast_manager_event_blob object.
* \retval NULL on error.
*/
struct ast_manager_event_blob *
__attribute__((format(printf, 3, 4)))
@ -552,16 +546,16 @@ int manager_mwi_init(void);
/*!
* \brief Initialize support for AMI channel events.
* \return 0 on success.
* \return non-zero on error.
* \retval 0 on success.
* \retval non-zero on error.
* \since 12
*/
int manager_bridging_init(void);
/*!
* \brief Initialize support for AMI endpoint events.
* \return 0 on success.
* \return non-zero on error.
* \retval 0 on success.
* \retval non-zero on error.
* \since 12
*/
int manager_endpoints_init(void);
@ -578,7 +572,7 @@ int manager_endpoints_init(void);
* - class_type is the class authorization type for the event
* - event is a list of key/value tuples to be sent out in the message
*
* \retval A \ref stasis_message_type for AMI messages
* \return A \ref stasis_message_type for AMI messages
*/
struct stasis_message_type *ast_manager_get_generic_type(void);
@ -586,7 +580,7 @@ struct stasis_message_type *ast_manager_get_generic_type(void);
* \since 12
* \brief Get the \ref stasis topic for AMI
*
* \retval The \ref stasis topic for AMI
* \return The \ref stasis topic for AMI
* \retval NULL on error
*/
struct stasis_topic *ast_manager_get_topic(void);
@ -600,9 +594,9 @@ struct stasis_topic *ast_manager_get_topic(void);
* \param obj The event data to be published.
*
* Publishes a message to the \ref stasis message bus solely for the consumption of AMI.
* The message will be of the type provided by \ref ast_manager_get_type, and will be
* published to the topic provided by \ref ast_manager_get_topic. As such, the JSON must
* be constructed as defined by the \ref ast_manager_get_type message.
* The message will be of the type provided by \ref ast_manager_get_generic_type, and
* will be published to the topic provided by \ref ast_manager_get_topic. As such, the
* JSON must be constructed as defined by the \ref ast_manager_get_generic_type message.
*/
void ast_manager_publish_event(const char *type, int class_type, struct ast_json *obj);
@ -610,7 +604,7 @@ void ast_manager_publish_event(const char *type, int class_type, struct ast_json
* \since 12
* \brief Get the \ref stasis_message_router for AMI
*
* \retval The \ref stasis_message_router for AMI
* \return The \ref stasis_message_router for AMI
* \retval NULL on error
*/
struct stasis_message_router *ast_manager_get_message_router(void);

2
include/asterisk/max_forwards.h
View File

@ -56,7 +56,7 @@ int ast_max_forwards_get(struct ast_channel *chan);
*
* \pre chan is locked
*
* \chan The channel for which the max forwards value should be decremented
* \param chan The channel for which the max forwards value should be decremented
* \retval 0 Success
* \retval -1 Failure
*/

12
include/asterisk/message.h
View File

@ -168,7 +168,7 @@ struct ast_msg *ast_msg_alloc(void);
* This should only be called on a message if it was not
* passed on to ast_msg_queue().
*
* \return NULL, always.
* \retval NULL always.
*/
struct ast_msg *ast_msg_destroy(struct ast_msg *msg);
@ -296,7 +296,7 @@ const char *ast_msg_get_body(const struct ast_msg *msg);
*
* \param msg The message to get the soure from
*
* \retval The source of the message
* \return The source of the message
* \retval NULL or empty string if the message has no source
*/
const char *ast_msg_get_from(const struct ast_msg *msg);
@ -308,7 +308,7 @@ const char *ast_msg_get_from(const struct ast_msg *msg);
*
* \param msg The message to get the destination from
*
* \retval The destination of the message
* \return The destination of the message
* \retval NULL or empty string if the message has no destination
*/
const char *ast_msg_get_to(const struct ast_msg *msg);
@ -320,7 +320,7 @@ const char *ast_msg_get_to(const struct ast_msg *msg);
*
* \param msg The message to get the technology from
*
* \retval The technology of the message
* \return The technology of the message
* \retval NULL or empty string if the message has no associated technology
*/
const char *ast_msg_get_tech(const struct ast_msg *msg);
@ -332,7 +332,7 @@ const char *ast_msg_get_tech(const struct ast_msg *msg);
*
* \param msg The message to get the endpoint from
*
* \retval The endpoint associated with the message
* \return The endpoint associated with the message
* \retval NULL or empty string if the message has no associated endpoint
*/
const char *ast_msg_get_endpoint(const struct ast_msg *msg);
@ -485,7 +485,7 @@ struct ast_msg_data *ast_msg_data_alloc(enum ast_msg_data_source_type source,
* \since 16.12.0
* \since 17.6.0
*
* \param source The source type of the message
* \param source_type The source type of the message
* \param to Where the message is sent to
* \param from Where the message is sent from
* \param content_type Content type of the body

2
include/asterisk/multicast_rtp.h
View File

@ -51,7 +51,7 @@ void ast_multicast_rtp_free_options(struct ast_multicast_rtp_options *mcast_opti
*
* \param mcast_options The options where a codec was specified
* \retval NULL No format specified in the options
* \revval non-NULL The format to use for communication
* \retval non-NULL The format to use for communication
*/
struct ast_format *ast_multicast_rtp_options_get_format(struct ast_multicast_rtp_options *mcast_options);

40
include/asterisk/mwi.h
View File

@ -33,7 +33,7 @@
*
* MWI state is managed via an underlying \ref stasis_state_manager (if interested see the
* stasis_state.c module for the gory details). As such all last known mailbox state can be
* retrieve and iterated over by using the \ref ast_mwi_callback function.
* retrieve and iterated over by using the \ref ast_mwi_subscribe_pool function.
*
* \par ast_mwi_subscriber
*
@ -122,7 +122,7 @@ struct ast_mwi_subscriber;
*
* \param mailbox The subscription state mailbox id
*
* \retval An MWI subscriber object
* \return An MWI subscriber object
* \retval NULL on error
*
* \since 13.28.0
@ -145,7 +145,7 @@ struct ast_mwi_subscriber *ast_mwi_add_subscriber(const char *mailbox);
* \param callback The stasis subscription callback
* \param data A user data object passed to the stasis subscription
*
* \retval An MWI subscriber object
* \return An MWI subscriber object
* \retval NULL on error
*
* \since 13.28.0
@ -159,8 +159,6 @@ struct ast_mwi_subscriber *ast_mwi_subscribe_pool(const char *mailbox,
*
* \param sub An MWI subscriber
*
* \retval NULL
*
* \since 13.28.0
* \since 16.5.0
*/
@ -172,8 +170,6 @@ void *ast_mwi_unsubscribe(struct ast_mwi_subscriber *sub);
*
* \param sub An MWI subscriber
*
* \retval NULL
*
* \since 13.28.0
* \since 16.5.0
*/
@ -187,7 +183,7 @@ void *ast_mwi_unsubscribe_and_join(struct ast_mwi_subscriber *sub);
*
* \param sub An MWI subscriber
*
* \retval A stasis topic subscribed to by the subscriber
* \return A stasis topic subscribed to by the subscriber
*
* \since 13.28.0
* \since 16.5.0
@ -201,7 +197,7 @@ struct stasis_topic *ast_mwi_subscriber_topic(struct ast_mwi_subscriber *sub);
*
* \param sub An MWI subscriber
*
* \retval The state data object
* \return The state data object
*
* \since 13.28.0
* \since 16.5.0
@ -213,7 +209,7 @@ struct ast_mwi_state *ast_mwi_subscriber_data(struct ast_mwi_subscriber *sub);
*
* \param sub An MWI subscriber
*
* \retval The subscriber's stasis subscription
* \return The subscriber's stasis subscription
* \retval NULL if no subscription available
*
* \since 13.28.0
@ -240,7 +236,7 @@ struct ast_mwi_publisher;
*
* \param mailbox The mailbox id to publish to
*
* \retval An MWI publisher object
* \return An MWI publisher object
* \retval NULl on error
*
* \since 13.28.0
@ -272,7 +268,8 @@ struct ast_mwi_observer {
*
* \param observer The observer handling events
*
* \retval 0 if successfully registered, -1 otherwise
* \retval 0 if successfully registered
* \retval -1 otherwise
*
* \since 13.28.0
* \since 16.5.0
@ -295,7 +292,8 @@ void ast_mwi_remove_observer(struct ast_mwi_observer *observer);
* \param mwi_state The mwi state object
* \param data User data passed in by the initiator
*
* \retval 0 to continue traversing, or CMP_STOP (2) to stop traversing
* \retval 0 to continue traversing
* \retval CMP_STOP (2) to stop traversing
*
* \since 13.28.0
* \since 16.5.0
@ -482,7 +480,7 @@ struct ast_mwi_blob {
* \param[in] mailbox The mailbox identifier string.
* \param[in] context The context this mailbox resides in (NULL or "" if only using mailbox)
*
* \retval \ref ast_mwi_state object on success
* \return \ref ast_mwi_state object on success
* \retval NULL on error
*/
struct ast_mwi_state *ast_mwi_create(const char *mailbox, const char *context);
@ -499,7 +497,7 @@ struct ast_mwi_state *ast_mwi_create(const char *mailbox, const char *context);
* \param message_type The type of message to create
* \param blob JSON object representing the data.
* \return \ref ast_mwi_blob message.
* \return \c NULL on error
* \retval NULL on error
*/
struct stasis_message *ast_mwi_blob_create(struct ast_mwi_state *mwi_state,
struct stasis_message_type *message_type,
@ -507,7 +505,7 @@ struct stasis_message *ast_mwi_blob_create(struct ast_mwi_state *mwi_state,
/*!
* \brief Get the \ref stasis topic for MWI messages
* \retval The topic structure for MWI messages
* \return The topic structure for MWI messages
* \retval NULL if it has not been allocated
* \since 12
*/
@ -516,7 +514,7 @@ struct stasis_topic *ast_mwi_topic_all(void);
/*!
* \brief Get the \ref stasis topic for MWI messages on a unique ID
* \param uniqueid The unique id for which to get the topic
* \retval The topic structure for MWI messages for a given uniqueid
* \return The topic structure for MWI messages for a given uniqueid
* \retval NULL if it failed to be found or allocated
* \since 12
*/
@ -524,7 +522,7 @@ struct stasis_topic *ast_mwi_topic(const char *uniqueid);
/*!
* \brief Get the \ref stasis caching topic for MWI messages
* \retval The caching topic structure for MWI messages
* \return The caching topic structure for MWI messages
* \retval NULL if it has not been allocated
* \since 12
*/
@ -532,13 +530,13 @@ struct stasis_topic *ast_mwi_topic_cached(void);
/*!
* \brief Backend cache for ast_mwi_topic_cached().
* \retval Cache of \ref ast_mwi_state.
* \return Cache of \ref ast_mwi_state.
*/
struct stasis_cache *ast_mwi_state_cache(void);
/*!
* \brief Get the \ref stasis message type for MWI messages
* \retval The message type structure for MWI messages
* \return The message type structure for MWI messages
* \retval NULL on error
* \since 12
*/
@ -554,7 +552,7 @@ struct stasis_message_type *ast_mwi_state_type(void);
*
* At least one key/value tuple must have a key value of "Event".
*
* \retval The \ref stasis_message_type for voicemail application specific messages
* \return The \ref stasis_message_type for voicemail application specific messages
* \retval NULL on error
* \since 12
*/

13
include/asterisk/netsock2.h
View File

@ -134,8 +134,6 @@ static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr)
*
* \brief
* Sets address \a addr to null.
*
* \retval void
*/
static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
{
@ -149,7 +147,6 @@ static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
* \param dst The destination ast_sockaddr
* \param src The source sockaddr
* \param len Length of the value stored in sockaddr
* \retval void
*/
static inline void ast_sockaddr_copy_sockaddr(struct ast_sockaddr *dst,
struct sockaddr *src, socklen_t len)
@ -166,7 +163,6 @@ static inline void ast_sockaddr_copy_sockaddr(struct ast_sockaddr *dst,
*
* \param dst The destination ast_sockaddr
* \param src The source ast_sockaddr
* \retval void
*/
static inline void ast_sockaddr_copy(struct ast_sockaddr *dst,
const struct ast_sockaddr *src)
@ -245,7 +241,7 @@ int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockadd
*
* \retval "(null)" \a addr is null
* \retval "" An error occurred during processing
* \retval string The stringified form of the address
* \return string The stringified form of the address
*/
char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
@ -472,7 +468,7 @@ int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
*
* \param[out] addr The resulting ast_sockaddr
* \param name The string to parse
* \param flags If set to zero, a port MAY be present. If set to
* \param flag 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 be present.
@ -532,7 +528,6 @@ uint16_t _ast_sockaddr_port(const struct ast_sockaddr *addr, const char *file, i
*
* \param addr Address on which to set the port
* \param port The port you wish to set the address to use
* \retval void
*/
#define ast_sockaddr_set_port(addr,port) _ast_sockaddr_set_port(addr,port,__FILE__,__LINE__,__PRETTY_FUNCTION__)
void _ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port, const char *file, int line, const char *func);
@ -650,8 +645,8 @@ int ast_sockaddr_hash(const struct ast_sockaddr *addr);
* \brief
* Returns a string representation of an ast_transport
*
* \retval Name of the tranpsort if it is defined
* \retval Undefined if the transport is undefined
* \return Name of the tranpsort if it is defined
* \return Undefined if the transport is undefined
*/
const char *ast_transport2str(enum ast_transport transport);

63
include/asterisk/pbx.h
View File

@ -180,15 +180,17 @@ struct ast_timing {
/*!
* \brief Construct a timing bitmap, for use in time-based conditionals.
* \param i Pointer to an ast_timing structure.
* \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
* \retval Returns 1 on success or 0 on failure.
* \param info_in Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
* \retval 1 on success.
* \retval 0 on failure.
*/
int ast_build_timing(struct ast_timing *i, const char *info);
int ast_build_timing(struct ast_timing *i, const char *info_in);
/*!
* \brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
* \param i Pointer to an ast_timing structure.
* \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range.
* \retval 1 if the time matches.
* \retval 0 if the current time falls outside of the specified range.
*/
int ast_check_timing(const struct ast_timing *i);
@ -196,7 +198,8 @@ int ast_check_timing(const struct ast_timing *i);
* \brief Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified.
* \param i Pointer to an ast_timing structure.
* \param tv Specified time
* \retval Returns 1, if the time matches or 0, if the time falls outside of the specified range.
* \retval 1 if the time matches.
* \retval 0 if the time falls outside of the specified range.
*/
int ast_check_timing2(const struct ast_timing *i, const struct timeval tv);
@ -233,8 +236,6 @@ int ast_register_switch(struct ast_switch *sw);
* \param sw switch to unregister
*
* Unregisters a switch from asterisk.
*
* \return nothing
*/
void ast_unregister_switch(struct ast_switch *sw);
@ -330,8 +331,6 @@ int ast_context_destroy_by_name(const char *context, const char *registrar);
*
* You can optionally leave out either parameter. It will find it
* based on either the ast_context or the registrar name.
*
* \return nothing
*/
void ast_context_destroy(struct ast_context *con, const char *registrar);
@ -422,8 +421,6 @@ enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args
*
* \param chan Channel to run the h exten on.
* \param context Context the h exten is in.
*
* \return Nothing
*/
void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context);
@ -445,8 +442,6 @@ int ast_pbx_hangup_handler_run(struct ast_channel *chan);
* \since 11.0
*
* \param chan Channel to init the hangup handler container on.
*
* \return Nothing
*/
void ast_pbx_hangup_handler_init(struct ast_channel *chan);
@ -455,8 +450,6 @@ void ast_pbx_hangup_handler_init(struct ast_channel *chan);
* \since 11.0
*
* \param chan Channel to destroy the hangup handler container on.
*
* \return Nothing
*/
void ast_pbx_hangup_handler_destroy(struct ast_channel *chan);
@ -476,8 +469,6 @@ int ast_pbx_hangup_handler_pop(struct ast_channel *chan);
*
* \param chan Channel to push the hangup handler onto.
* \param handler Gosub application parameter string.
*
* \return Nothing
*/
void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler);
@ -509,10 +500,25 @@ int ast_add_extension(const char *context, int replace, const char *extension,
/*!
* \brief Add an extension to an extension context, this time with an ast_context *.
*
* \param con context to add the extension to
* \param replace
* \param extension extension to add
* \param priority priority level of extension addition
* \param label extension label
* \param callerid pattern to match CallerID, or NULL to match any CallerID
* \param application application to run on the extension with that priority level
* \param data data to pass to the application
* \param datad a pointer to a function that will deallocate \c data when needed
* or NULL if \c data does not need to be freed.
* \param registrar who registered the extension
* \param registrar_file optional configuration file that defines this extension
* \param registrar_line optional line number of configuration file that defines extension
*
* \note For details about the other arguments, check ast_add_extension()
* \note On any failure, the function pointed to by \c datap will be called and passed the
* \c data pointer.
*
* \retval 0 success
* \retval -1 failure
*/
int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
int priority, const char *label, const char *callerid,
@ -896,25 +902,17 @@ 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 value include value to add
* \param registrar who registered the context
*
* Adds an include taking a struct ast_context as the first parameter
*
* \retval 0 on success
* \retval -1 on failure
* \note See ast_context_add_include for information on arguments
*/
int ast_context_add_include2(struct ast_context *con, const char *include,
int ast_context_add_include2(struct ast_context *con, const char *value,
const char *registrar);
/*!
* \brief Remove a context include
*
* \note See ast_context_add_include for information on arguments
*
* \retval 0 on success
* \retval -1 on failure
*/
int ast_context_remove_include(const char *context, const char *include,
const char *registrar);
@ -922,10 +920,7 @@ int ast_context_remove_include(const char *context, const char *include,
/*!
* \brief Removes an include by an ast_context structure
*
* \note See ast_context_add_include2 for information on arguments
*
* \retval 0 on success
* \retval -1 on success
* \note See ast_context_add_include for information on arguments
*/
int ast_context_remove_include2(struct ast_context *con, const char *include,
const char *registrar);
@ -1174,8 +1169,8 @@ enum ast_pbx_outgoing_sync {
* If \c AST_OUTGOING_WAIT_COMPLETE then wait for the call to complete or
* fail.
* If \c AST_OUTGOING_WAIT or \c AST_OUTGOING_WAIT_COMPLETE is specified,
* the call doesn't answer, and \c failed@context exists then run a channel
* named \c OutgoingSpoolFailed at \c failed@context.
* the call doesn't answer, and \c failed\@context exists then run a channel
* named \c OutgoingSpoolFailed at \c failed\@context.
* \param cid_num The caller ID number to set on the outbound channel
* \param cid_name The caller ID name to set on the outbound channel
* \param vars Variables to set on the outbound channel

6
include/asterisk/pickup.h
View File

@ -34,7 +34,7 @@
*
* \note This function assumes that chan is locked.
*
* \return TRUE if channel can be picked up.
* \retval TRUE if channel can be picked up.
*/
int ast_can_pickup(struct ast_channel *chan);
@ -43,7 +43,7 @@ int ast_can_pickup(struct ast_channel *chan);
*
* \param chan channel that initiated pickup.
*
* \retval target on success. The returned channel is locked and reffed.
* \return target on success. The returned channel is locked and reffed.
* \retval NULL on error.
*/
struct ast_channel *ast_pickup_find_by_group(struct ast_channel *chan);
@ -75,7 +75,7 @@ int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
* \brief accessor for call pickup message type
* \since 12.0.0
*
* \retval pointer to the stasis message type
* \return pointer to the stasis message type
* \retval NULL if not initialized
*/
struct stasis_message_type *ast_call_pickup_type(void);

72
include/asterisk/rtp_engine.h
View File

@ -783,7 +783,7 @@ enum ast_rtp_extension_direction {
* \brief Allocation routine for \ref ast_rtp_payload_type
*
* \retval NULL on error
* \retval An ao2 ref counted \c ast_rtp_payload_type on success.
* \return An ao2 ref counted \c ast_rtp_payload_type on success.
*
* \note The \c ast_rtp_payload_type returned by this function is an
* ao2 ref counted object.
@ -1274,7 +1274,7 @@ void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_p
* \param instance The RTP instance to get the property from
* \param property The property to get
*
* \retval Current value of the property
* \return Current value of the property
*
* Example usage:
*
@ -1375,7 +1375,7 @@ size_t ast_rtp_instance_extmap_count(struct ast_rtp_instance *instance);
* \param instance The RTP instance to retrieve the extension from
* \param id The negotiated RTP extension id
*
* \retval extension the extension that maps to the id
* \return extension the extension that maps to the id
*
* \since 15.5.0
*
@ -1390,7 +1390,7 @@ enum ast_rtp_extension ast_rtp_instance_extmap_get_extension(struct ast_rtp_inst
* \param instance The RTP instance to retrieve the direction from
* \param id The negotiated RTP extension id
*
* \retval direction the direction that has been negotiated
* \return direction the direction that has been negotiated
*
* \since 15.5.0
*/
@ -1402,7 +1402,7 @@ enum ast_rtp_extension_direction ast_rtp_instance_extmap_get_direction(struct as
* \param instance The RTP instance to retrieve the direction from
* \param id The negotiated RTP extension id
*
* \retval uri The URI for the RTP extension
* \return The URI for the RTP extension
*
* \since 15.5.0
*/
@ -1488,8 +1488,6 @@ void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_cod
* \param src The source codecs structure
* \param dest The destination codecs structure that the values from src will be copied to
* \param instance Optionally the instance that the dst codecs structure belongs to
*
* \return Nothing
*/
void ast_rtp_codecs_payloads_xover(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
@ -1598,7 +1596,7 @@ enum ast_media_type ast_rtp_codecs_get_stream_type(struct ast_rtp_codecs *codecs
* \param codecs Codecs structure to look in
* \param payload Numerical payload to look up
*
* \retval Payload information.
* \return Payload information.
* \retval NULL if payload does not exist.
*
* \note The payload returned by this function has its reference count increased.
@ -1635,7 +1633,7 @@ int ast_rtp_codecs_payload_replace_format(struct ast_rtp_codecs *codecs, int pay
* \param codecs Codecs structure to look in
* \param payload Numerical payload type to look up
*
* \retval pointer to format structure on success
* \return pointer to format structure on success
* \retval NULL on failure
*
* \note The format returned by this function has its reference count increased.
@ -1660,7 +1658,7 @@ void ast_rtp_codecs_set_framing(struct ast_rtp_codecs *codecs, unsigned int fram
*
* \param codecs Codecs structure to get the framing from
*
* \retval The framing to be used for the media stream associated with these codecs
* \return The framing to be used for the media stream associated with these codecs
*
* \since 13.0.0
*/
@ -1715,7 +1713,7 @@ void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_fo
* is an Asterisk format or non-format code. If one is currently not
* assigned then create a rx payload type mapping.
*
* \retval Numerical payload type
* \return Numerical payload type
* \retval -1 if could not assign.
*
* Example usage:
@ -1753,7 +1751,7 @@ int ast_rtp_codecs_payload_set_rx(struct ast_rtp_codecs *codecs, int code, struc
* \param format Asterisk format to look for
* \param code The format to look for
*
* \retval Numerical payload type
* \return Numerical payload type
* \retval -1 if not found.
*/
int ast_rtp_codecs_payload_code_tx(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
@ -1764,7 +1762,7 @@ int ast_rtp_codecs_payload_code_tx(struct ast_rtp_codecs *codecs, int asterisk_f
* \param codecs Codecs structure to look in
* \param payload The payload type format to look for
*
* \retval Numerical payload type or -1 if unable to find payload in codecs
* \return Numerical payload type or -1 if unable to find payload in codecs
*
* Example usage:
*
@ -1784,7 +1782,7 @@ int ast_rtp_codecs_find_payload_code(struct ast_rtp_codecs *codecs, int payload)
* \param code RTP code to look up
* \param options Additional options that may change the result
*
* \retval Mime subtype success
* \return Mime subtype success
* \retval NULL failure
*
* Example usage:
@ -1900,7 +1898,7 @@ int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_r
*
* \param instance The RTP instance to get the DTMF mode of
*
* \retval DTMF mode
* \return DTMF mode
*
* Example usage:
*
@ -2040,7 +2038,7 @@ struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
*
* \param instance The RTP instance
*
* \retval The unique ID of the channel
* \return The unique ID of the channel
* \retval Empty string if no channel owns this RTP instance
*
* \since 12
@ -2393,7 +2391,7 @@ void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeo
*
* \param instance The RTP instance
*
* \retval timeout value
* \return timeout value
*
* Example usage:
*
@ -2412,7 +2410,7 @@ int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
*
* \param instance The RTP instance
*
* \retval timeout value
* \return timeout value
*
* Example usage:
*
@ -2431,7 +2429,7 @@ int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
*
* \param instance The RTP instance
*
* \retval period Keepalive interval value
* \return period Keepalive interval value
*
* Example usage:
*
@ -2450,7 +2448,7 @@ int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
*
* \param instance The RTP instance
*
* \retval pointer to the engine
* \return pointer to the engine
*
* Example usage:
*
@ -2469,7 +2467,7 @@ struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *inst
*
* \param instance The RTP instance
*
* \retval pointer to the glue
* \return pointer to the glue
*
* Example:
*
@ -2514,7 +2512,7 @@ int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct a
*
* \param instance the RTP instance
* \param rtcp 1 to request instance for RTCP
* \retval the SRTP instance on success
* \return the SRTP instance on success
* \retval NULL if no SRTP instance exists
*/
struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance, int rtcp);
@ -2533,7 +2531,7 @@ int ast_rtp_engine_unload_format(struct ast_format *format);
*
* \param instance the RTP instance
*
* \retval ICE support if present
* \return ICE support if present
* \retval NULL if no ICE support available
*/
struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *instance);
@ -2544,7 +2542,7 @@ struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *ins
*
* \param instance the RTP instance
*
* \retval test callbacks if present
* \return test callbacks if present
* \retval NULL if not present
*/
struct ast_rtp_engine_test *ast_rtp_instance_get_test(struct ast_rtp_instance *instance);
@ -2555,7 +2553,7 @@ struct ast_rtp_engine_test *ast_rtp_instance_get_test(struct ast_rtp_instance *i
*
* \param instance the RTP instance
*
* \retval DTLS support if present
* \return DTLS support if present
* \retval NULL if no DTLS support available
*/
struct ast_rtp_engine_dtls *ast_rtp_instance_get_dtls(struct ast_rtp_instance *instance);
@ -2603,7 +2601,7 @@ struct ast_json;
* \brief Allocate an ao2 ref counted instance of \ref ast_rtp_rtcp_report
*
* \param report_blocks The number of report blocks to allocate
* \retval An ao2 ref counted \ref ast_rtp_rtcp_report object on success
* \return An ao2 ref counted \ref ast_rtp_rtcp_report object on success
* \retval NULL on error
*/
struct ast_rtp_rtcp_report *ast_rtp_rtcp_report_alloc(unsigned int report_blocks);
@ -2639,7 +2637,7 @@ time_t ast_rtp_instance_get_last_tx(const struct ast_rtp_instance *rtp);
*/
void ast_rtp_instance_set_last_tx(struct ast_rtp_instance *rtp, time_t time);
/*
/*!
* \brief Get the last RTP reception time
*
* \param rtp The instance from which to get the last reception time
@ -2698,7 +2696,7 @@ void ast_rtp_instance_set_remote_ssrc(struct ast_rtp_instance *rtp, unsigned int
* \brief Set the stream number for an RTP instance
* \since 15.0.0
*
* \param rtp The RTP instance
* \param instance The RTP instance
* \param stream_num The stream identifier number
*/
void ast_rtp_instance_set_stream_num(struct ast_rtp_instance *instance, int stream_num);
@ -2711,7 +2709,7 @@ void ast_rtp_instance_set_stream_num(struct ast_rtp_instance *instance, int stre
* \since 12
* \brief Message type for an RTCP message sent from this Asterisk instance
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_rtp_rtcp_sent_type(void);
@ -2719,7 +2717,7 @@ struct stasis_message_type *ast_rtp_rtcp_sent_type(void);
* \since 12
* \brief Message type for an RTCP message received from some external source
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_rtp_rtcp_received_type(void);
@ -2730,7 +2728,7 @@ struct stasis_message_type *ast_rtp_rtcp_received_type(void);
* \brief Get the maximum size of the receive buffer
*
* \param instance The RTP instance
* \retval The recv_buffer max size if it exists, else 0
* \return The recv_buffer max size if it exists, else 0
*/
size_t ast_rtp_instance_get_recv_buffer_max(struct ast_rtp_instance *instance);
@ -2738,7 +2736,7 @@ size_t ast_rtp_instance_get_recv_buffer_max(struct ast_rtp_instance *instance);
* \brief Get the current size of the receive buffer
*
* \param instance The RTP instance
* \retval The recv_buffer size if it exists, else 0
* \return The recv_buffer size if it exists, else 0
*/
size_t ast_rtp_instance_get_recv_buffer_count(struct ast_rtp_instance *instance);
@ -2746,7 +2744,7 @@ size_t ast_rtp_instance_get_recv_buffer_count(struct ast_rtp_instance *instance)
* \brief Get the current size of the send buffer
*
* \param instance The RTP instance
* \retval The send_buffer size if it exists, else 0
* \return The send_buffer size if it exists, else 0
*/
size_t ast_rtp_instance_get_send_buffer_count(struct ast_rtp_instance *instance);
@ -2792,14 +2790,14 @@ void ast_rtp_instance_reset_test_engine(struct ast_rtp_instance *instance);
/*!
* \brief Convert given stat instance into json format
* \param stats
* \retval A json format stat
* \return A json format stat
*/
struct ast_json *ast_rtp_convert_stats_json(const struct ast_rtp_instance_stats *stats);
/*!
* \brief Retrieve statistics about an RTP instance in json format
* \param instance
* \retval json object of stats
* \return json object of stats
*/
struct ast_json *ast_rtp_instance_get_stats_all_json(struct ast_rtp_instance *instance);
@ -2810,7 +2808,7 @@ struct ast_json *ast_rtp_instance_get_stats_all_json(struct ast_rtp_instance *in
*
* \param format The media format
*
* \retval The sample rate
* \return The sample rate
*/
int ast_rtp_get_rate(const struct ast_format *format);
@ -2818,7 +2816,7 @@ int ast_rtp_get_rate(const struct ast_format *format);
* \since 12
* \brief \ref stasis topic for RTP and RTCP related messages
*
* \retval A \ref stasis topic
* \return A \ref stasis topic
*/
struct stasis_topic *ast_rtp_topic(void);

29
include/asterisk/sched.h
View File

@ -153,7 +153,8 @@ extern "C" {
/*!
* \brief Create a scheduler context
*
* \return Returns a malloc'd sched_context structure, NULL on failure
* \retval NULL on failure
* \return a malloc'd sched_context structure
*/
struct ast_sched_context *ast_sched_context_create(void);
@ -215,7 +216,8 @@ void ast_sched_report(struct ast_sched_context *con, struct ast_str **buf, struc
* \param callback function to call when the amount of time expires
* \param data data to pass to the callback
*
* \return Returns a schedule item ID on success, -1 on failure
* \retval -1 on failure
* \return schedule item ID
*/
int ast_sched_add(struct ast_sched_context *con, int when, ast_sched_cb callback, const void *data) attribute_warn_unused_result;
@ -227,8 +229,8 @@ int ast_sched_add(struct ast_sched_context *con, int when, ast_sched_cb callback
* calls ast_sched_add to create a new entry. A negative old_id will
* be ignored.
*
* \retval -1 failure
* \retval otherwise, returns scheduled item ID
* \retval -1 on failure
* \return scheduled item ID
*/
int ast_sched_replace(int old_id, struct ast_sched_context *con, int when, ast_sched_cb callback, const void *data) attribute_warn_unused_result;
@ -248,7 +250,8 @@ int ast_sched_replace(int old_id, struct ast_sched_context *con, int when, ast_s
*
* If callback returns 0, no further events will be re-scheduled
*
* \return Returns a schedule item ID on success, -1 on failure
* \retval -1 on failure
* \return scheduled item ID
*/
int ast_sched_add_variable(struct ast_sched_context *con, int when, ast_sched_cb callback, const void *data, int variable) attribute_warn_unused_result;
@ -260,8 +263,8 @@ int ast_sched_add_variable(struct ast_sched_context *con, int when, ast_sched_cb
* calls ast_sched_add to create a new entry. A negative old_id will
* be ignored.
*
* \retval -1 failure
* \retval otherwise, returns scheduled item ID
* \retval -1 on failure
* \return scheduled item ID
*/
int ast_sched_replace_variable(int old_id, struct ast_sched_context *con, int when, ast_sched_cb callback, const void *data, int variable) attribute_warn_unused_result;
@ -270,7 +273,9 @@ int ast_sched_replace_variable(int old_id, struct ast_sched_context *con, int wh
*
* \param con scheduling context in which to search fro the matching id
* \param id ID of the scheduled item to find
* \return the data field from the matching sched struct if found; else return NULL if not found.
*
* \retval NULL if not found
* \return the data field from the matching sched struct if found.
*
* \since 1.6.1
*/
@ -287,7 +292,8 @@ const void *ast_sched_find_data(struct ast_sched_context *con, int id);
* \param con scheduling context to delete item from
* \param id ID of the scheduled item to delete
*
* \return Returns 0 on success, -1 on failure
* \retval -1 on failure
* \retval 0 on success
*/
int ast_sched_del(struct ast_sched_context *con, int id) attribute_warn_unused_result;
@ -301,7 +307,7 @@ int ast_sched_del(struct ast_sched_context *con, int id) attribute_warn_unused_r
*
* \param con context to act upon
*
* \return Returns "-1" if there is nothing there are no scheduled events
* \retval -1 if there is nothing there are no scheduled events
* (and thus the poll should not timeout)
*/
int ast_sched_wait(struct ast_sched_context *con) attribute_warn_unused_result;
@ -313,9 +319,8 @@ int ast_sched_wait(struct ast_sched_context *con) attribute_warn_unused_result;
* at this time.
*
* \param con Scheduling context to run
* \param con context to act upon
*
* \return Returns the number of events processed.
* \return the number of events processed.
*/
int ast_sched_runq(struct ast_sched_context *con);

20
include/asterisk/sdp_srtp.h
View File

@ -53,7 +53,7 @@ struct ast_sdp_srtp {
/*!
* \brief allocate a ast_sdp_srtp structure
* \retval a new malloc'd ast_sdp_srtp structure on success
* \return a new malloc'd ast_sdp_srtp structure on success
* \retval NULL on failure
*/
struct ast_sdp_srtp *ast_sdp_srtp_alloc(void);
@ -74,7 +74,7 @@ typedef void (*sdp_crypto_destroy_cb)(struct ast_sdp_crypto *crypto);
* This function allocates a new ast_sdp_crypto struct and initializes its values
*
* \retval NULL on failure
* \retval a pointer to a new ast_sdp_crypto structure
* \return a pointer to a new ast_sdp_crypto structure
*/
typedef struct ast_sdp_crypto *(*sdp_crypto_alloc_cb)(void);
@ -98,10 +98,9 @@ typedef int (*sdp_crypto_build_offer_cb)(struct ast_sdp_crypto *crypto, int tagl
*
* The attribute line should already have "a=crypto:" removed.
*
* \param p A valid ast_sdp_crypto struct
* \param attr the a:crypto line from SDP
* \param rtp The rtp instance associated with the SDP being parsed
* \param srtp SRTP structure
* \param attr the a:crypto line from SDP
*
* \retval 0 success
* \retval nonzero failure
@ -119,7 +118,7 @@ typedef int (*sdp_crypto_parse_offer_cb)(struct ast_rtp_instance *rtp, struct as
* \param dtls_enabled Whether this connection is encrypted with datagram TLS
* \param default_taglen_32 Whether to default to a tag length of 32 instead of 80
*
* \retval An attribute line containing cryptographic information
* \return An attribute line containing cryptographic information
* \retval NULL if the srtp structure does not require an attribute line containing crypto information
*/
typedef const char *(*sdp_srtp_get_attr_cb)(struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32);
@ -153,8 +152,6 @@ int ast_sdp_crypto_register(struct ast_sdp_crypto_api *api);
* \since 14.0.0
*
* \param api Callbacks to unregister.
*
* \return Nothing
*/
void ast_sdp_crypto_unregister(struct ast_sdp_crypto_api *api);
@ -164,7 +161,7 @@ void ast_sdp_crypto_unregister(struct ast_sdp_crypto_api *api);
* This function allocates a new ast_sdp_crypto struct and initializes its values
*
* \retval NULL on failure
* \retval a pointer to a new ast_sdp_crypto structure
* \return a pointer to a new ast_sdp_crypto structure
*/
struct ast_sdp_crypto *ast_sdp_crypto_alloc(void);
@ -176,10 +173,9 @@ void ast_sdp_crypto_destroy(struct ast_sdp_crypto *crypto);
*
* The attribute line should already have "a=crypto:" removed.
*
* \param p A valid ast_sdp_crypto struct
* \param attr the a:crypto line from SDP
* \param rtp The rtp instance associated with the SDP being parsed
* \param srtp SRTP structure
* \param attr the a:crypto line from SDP
*
* \retval 0 success
* \retval nonzero failure
@ -208,7 +204,7 @@ int ast_sdp_crypto_build_offer(struct ast_sdp_crypto *p, int taglen);
* \param dtls_enabled Whether this connection is encrypted with datagram TLS
* \param default_taglen_32 Whether to default to a tag length of 32 instead of 80
*
* \retval An attribute line containing cryptographic information
* \return An attribute line containing cryptographic information
* \retval NULL if the srtp structure does not require an attribute line containing crypto information
*/
const char *ast_sdp_srtp_get_attrib(struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32);
@ -220,7 +216,7 @@ const char *ast_sdp_srtp_get_attrib(struct ast_sdp_srtp *srtp, int dtls_enabled,
* \param using_avpf Whether the media session is using early feedback (AVPF)
* \param force_avp Force SAVP or SAVPF profile when DTLS is in use
*
* \retval A non-allocated string describing the profile in use (does not need to be freed)
* \return A non-allocated string describing the profile in use (does not need to be freed)
*/
char *ast_sdp_get_rtp_profile(unsigned int sdes_active, struct ast_rtp_instance *instance, unsigned int using_avpf,
unsigned int force_avp);

4
include/asterisk/security_events.h
View File

@ -60,7 +60,7 @@ struct ast_security_event_ie_type {
* \brief A \ref stasis_topic which publishes messages for security related issues.
* \since 12
*
* \retval \ref stasis_topic for security related issues.
* \return \ref stasis_topic for security related issues.
* \retval NULL on error
*/
struct stasis_topic *ast_security_topic(void);
@ -70,7 +70,7 @@ struct stasis_topic *ast_security_topic(void);
* \since 12
*
* \retval NULL on error
* \retval \ref stasis_message_type for security events
* \return \ref stasis_message_type for security events
*
* \note Messages of this type should always be issued on and expected from
* the \ref ast_security_topic \ref stasis_topic

25
include/asterisk/sem.h
View File

@ -101,8 +101,8 @@ struct ast_sem {
* in case we need to add support in the future.
* \param value Initial value of the semaphore.
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_init(struct ast_sem *sem, int pshared, unsigned int value);
@ -114,8 +114,8 @@ int ast_sem_init(struct ast_sem *sem, int pshared, unsigned int value);
*
* \param sem Semaphore to destroy.
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_destroy(struct ast_sem *sem);
@ -124,8 +124,8 @@ int ast_sem_destroy(struct ast_sem *sem);
*
* \param sem Semaphore to increment.
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_post(struct ast_sem *sem);
@ -138,8 +138,8 @@ int ast_sem_post(struct ast_sem *sem);
*
* \param sem Semaphore to decrement.
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_wait(struct ast_sem *sem);
@ -151,9 +151,10 @@ int ast_sem_wait(struct ast_sem *sem);
* handler, which sets errno to EINTR).
*
* \param sem Semaphore to decrement.
* \param abs_timeout
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_timedwait(struct ast_sem *sem, const struct timespec *abs_timeout);
@ -168,8 +169,8 @@ int ast_sem_timedwait(struct ast_sem *sem, const struct timespec *abs_timeout);
* \param sem Semaphore to query.
* \param[out] sval Output value.
*
* \return 0 on success.
* \return -1 on error, errno set to indicate error.
* \retval 0 on success.
* \retval -1 on error, errno set to indicate error.
*/
int ast_sem_getvalue(struct ast_sem *sem, int *sval);

11
include/asterisk/serializer.h
View File

@ -50,7 +50,8 @@ int ast_serializer_pool_destroy(struct ast_serializer_pool *pool);
* \param threadpool The backing threadpool to use
* \param timeout The timeout used if using a shutdown group (-1 = disabled)
*
* \retval A newly allocated serializer pool object, or NULL on error
* \return A newly allocated serializer pool object
* \retval NULL on error
*/
struct ast_serializer_pool *ast_serializer_pool_create(const char *name,
unsigned int size, struct ast_threadpool *threadpool, int timeout);
@ -60,7 +61,7 @@ struct ast_serializer_pool *ast_serializer_pool_create(const char *name,
*
* \param pool The pool object
*
* \retval The base name given to the pool
* \return The base name given to the pool
*/
const char *ast_serializer_pool_name(const struct ast_serializer_pool *pool);
@ -69,7 +70,7 @@ const char *ast_serializer_pool_name(const struct ast_serializer_pool *pool);
*
* \param pool The pool object
*
* \retval A serializer/taskprocessor
* \return A serializer/taskprocessor
*/
struct ast_taskprocessor *ast_serializer_pool_get(struct ast_serializer_pool *pool);
@ -77,8 +78,10 @@ struct ast_taskprocessor *ast_serializer_pool_get(struct ast_serializer_pool *po
* \brief Set taskprocessor alert levels for the serializers in the pool.
*
* \param pool The pool to destroy
* \param high, low
*
* \retval 0 on success, or -1 on error.
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_serializer_pool_set_alerts(struct ast_serializer_pool *pool, long high, long low);

9
include/asterisk/slinfactory.h
View File

@ -47,8 +47,6 @@ struct ast_slinfactory {
* \brief Initialize a slinfactory
*
* \param sf The slinfactory to initialize
*
* \return Nothing
*/
void ast_slinfactory_init(struct ast_slinfactory *sf);
@ -58,7 +56,8 @@ void ast_slinfactory_init(struct ast_slinfactory *sf);
* \param sf The slinfactory to initialize
* \param slin_out the slinear output format desired.
*
* \return 0 on success, non-zero on failure
* \retval 0 on success
* \retval non-zero on failure
*/
int ast_slinfactory_init_with_format(struct ast_slinfactory *sf, struct ast_format *slin_out);
@ -70,8 +69,6 @@ int ast_slinfactory_init_with_format(struct ast_slinfactory *sf, struct ast_form
* This function will free any memory allocated for the contents of the
* slinfactory. It does not free the slinfactory itself. If the sf is
* malloc'd, then it must be explicitly free'd after calling this function.
*
* \return Nothing
*/
void ast_slinfactory_destroy(struct ast_slinfactory *sf);
@ -109,8 +106,6 @@ unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf);
* \brief Flush the contents of a slinfactory
*
* \param sf The slinfactory to flush
*
* \return Nothing
*/
void ast_slinfactory_flush(struct ast_slinfactory *sf);

2
include/asterisk/smoother.h
View File

@ -67,8 +67,6 @@ void ast_smoother_reset(struct ast_smoother *s, int bytes);
* \brief Reconfigure an existing smoother to output a different number of bytes per frame
* \param s the smoother to reconfigure
* \param bytes the desired number of bytes per output frame
* \return nothing
*
*/
void ast_smoother_reconfigure(struct ast_smoother *s, int bytes);

48
include/asterisk/sorcery.h
View File

@ -211,8 +211,8 @@ typedef int (*sorcery_copy_handler)(const void *src, void *dst);
* \param modified The modified object
* \param changes The changeset
*
* \param 0 success
* \param -1 failure
* \retval 0 success
* \retval -1 failure
*/
typedef int (*sorcery_diff_handler)(const void *original, const void *modified, struct ast_variable **changes);
@ -403,14 +403,13 @@ int ast_sorcery_wizard_unregister(const struct ast_sorcery_wizard *interface);
* \retval non-NULL success
* \retval NULL if allocation failed
*/
struct ast_sorcery *__ast_sorcery_open(const char *module, const char *file, int line, const char *func);
#define ast_sorcery_open() __ast_sorcery_open(AST_MODULE, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct ast_sorcery *__ast_sorcery_open(const char *module, const char *file, int line, const char *func);
/*!
* \brief Retrieves an existing sorcery instance by module name
*
* \param module The module name
* \param module_name The module name
*
* \retval non-NULL success
* \retval NULL if no instance was found
@ -419,7 +418,7 @@ struct ast_sorcery *__ast_sorcery_open(const char *module, const char *file, int
* must decrement the count when they're finished with it.
*
*/
struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module);
struct ast_sorcery *ast_sorcery_retrieve_by_module_name(const char *module_name);
enum ast_sorcery_apply_result {
/*! Sorcery wizard failed to apply. */
@ -500,9 +499,9 @@ enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorc
*
* \param sorcery Pointer to a sorcery structure
* \param type Type of object to apply to
* \param module The name of the module, typically AST_MODULE
* \param name Name of the wizard to use
* \param data Data to be passed to wizard
* \param caching Wizard should cache
*
* \return What occurred when applying the mapping
*
@ -550,9 +549,9 @@ enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sor
*
* \param sorcery Pointer to a sorcery structure
* \param type Type of object to apply to
* \param module The name of the module, typically AST_MODULE
* \param name Name of the wizard to use
* \param data Data to be passed to wizard
* \param caching Wizard should cache
* \param position One of ast_sorcery_wizard_position
*
* \return What occurred when applying the mapping
@ -607,9 +606,9 @@ enum ast_sorcery_wizard_apply_flags {
*
* \note This should be called *after* applying default mappings
*
* \note Although \ref wizard_args is an optional parameter it is highly
* \note Although \p wizard_args is an optional parameter it is highly
* recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
* flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
* flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
* to remove specific instances of a wizard type.
*/
enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast_sorcery *sorcery,
@ -639,9 +638,9 @@ enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast
*
* \note This should be called *after* applying default mappings
*
* \note Although \ref wizard_args is an optional parameter it is highly
* \note Although \p wizard_args is an optional parameter it is highly
* recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
* flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
* flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
* to remove specific instances.
*/
#define ast_sorcery_object_type_insert_wizard(sorcery, \
@ -671,9 +670,9 @@ enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast
*
* \note This should be called *after* applying default mappings
*
* \note Although \ref wizard_args is an optional parameter it is highly
* \note Although \p wizard_args is an optional parameter it is highly
* recommended to supply one. If you use the AST_SORCERY_WIZARD_APPLY_ALLOW_DUPLICATE
* flag, and you intend to ever remove a wizard mapping, you'll need wizard_args
* flag, and you intend to ever remove a wizard mapping, you'll need \p wizard_args
* to remove specific instances.
*/
#define ast_sorcery_object_type_apply_wizard(sorcery, \
@ -698,7 +697,7 @@ enum ast_sorcery_apply_result __ast_sorcery_object_type_insert_wizard(struct ast
* \retval -1 failure
*
* \note If there were multiple instances of the same wizard type
* added to this object type without using \ref wizard_args, then
* added to this object type without using \p wizard_args, then
* only the first wizard matching wizard_type will be removed.
*/
int __ast_sorcery_object_type_remove_wizard(struct ast_sorcery *sorcery,
@ -719,7 +718,7 @@ int __ast_sorcery_object_type_remove_wizard(struct ast_sorcery *sorcery,
* \retval -1 failure
*
* \note If there were multiple instances of the same wizard type
* added to this object type without using \ref wizard_args, then
* added to this object type without using \p wizard_args, then
* only the first wizard matching wizard_type will be removed.
*/
#define ast_sorcery_object_type_remove_wizard(sorcery, object_type_name, \
@ -929,6 +928,7 @@ int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *
* \param flags Option type specific flags
* \param no_doc Field should not be documented
* \param alias Interpret and apply field value only
* \param argc
*
* \retval 0 success
* \retval -1 failure
@ -1014,6 +1014,7 @@ int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char
* \param default_val Default value of the field
* \param config_handler Custom configuration handler
* \param sorcery_handler Custom sorcery handler
* \param multiple_handler Custom multiple handler
* \param flags Option type specific flags
*
* \retval 0 success
@ -1308,7 +1309,7 @@ void ast_sorcery_instance_observer_remove(struct ast_sorcery *sorcery,
/*!
* \brief Add an observer to a sorcery wizard
*
* \param sorcery Pointer to a previously registered wizard structure
* \param wizard Pointer to a previously registered wizard structure
* \param callbacks Implementation of the wizard observer interface
*
* A wizard observer is notified...
@ -1326,10 +1327,10 @@ int ast_sorcery_wizard_observer_add(struct ast_sorcery_wizard *wizard,
/*!
* \brief Remove an observer from a sorcery wizard.
*
* \param sorcery Pointer to a sorcery structure
* \param interface Pointer to a sorcery structure
* \param callbacks Implementation of the wizard observer interface
*/
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *wizard,
void ast_sorcery_wizard_observer_remove(struct ast_sorcery_wizard *interface,
const struct ast_sorcery_wizard_observer *callbacks);
/*!
@ -1352,9 +1353,6 @@ int ast_sorcery_observer_add(const struct ast_sorcery *sorcery, const char *type
* \param sorcery Pointer to a sorcery structure
* \param type Type of object that should no longer be observed
* \param callbacks Implementation of the observer interface
*
* \retval 0 success
* \retval -1 failure
*/
void ast_sorcery_observer_remove(const struct ast_sorcery *sorcery, const char *type, const struct ast_sorcery_observer *callbacks);
@ -1507,7 +1505,7 @@ int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
*
* \param object Pointer to a sorcery object
*
* \retval unique identifier
* \return unique identifier
*/
const char *ast_sorcery_object_get_id(const void *object);
@ -1517,7 +1515,7 @@ const char *ast_sorcery_object_get_id(const void *object);
*
* \param object Pointer to a sorcery object
*
* \retval The time when the object was created
* \return The time when the object was created
*/
const struct timeval ast_sorcery_object_get_created(const void *object);
@ -1526,7 +1524,7 @@ const struct timeval ast_sorcery_object_get_created(const void *object);
*
* \param object Pointer to a sorcery object
*
* \retval type of object
* \return type of object
*/
const char *ast_sorcery_object_get_type(const void *object);

64
include/asterisk/stream.h
View File

@ -110,7 +110,7 @@ extern const char *ast_stream_state_map[AST_STREAM_STATE_END];
* \since 18
*
* \param stream_state One of enum ast_stream_state
* \returns A constant string with the name of the state or an empty string
* \return A constant string with the name of the state or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_state_to_str(stream_state) _stream_maps_to_str(ast_stream_state_map, stream_state)
@ -238,7 +238,7 @@ extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_
* \since 18
*
* \param value One of enum \ref ast_stream_codec_negotiation_params
* \returns A constant string with the name of the preference or an empty string
* \return A constant string with the name of the preference or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_codec_param_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_params_map, value)
@ -247,8 +247,8 @@ extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_
* \brief Safely get the name of a "prefer" parameter value
* \since 18
*
* \param value One of enum \ref ast_stream_codec_negotiation_prefer_values
* \returns A constant string with the name of the value or an empty string
* \param value One of enum \ref ast_stream_codec_negotiation_prefs_prefer_values
* \return A constant string with the name of the value or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_codec_prefer_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_prefer_map, value)
@ -257,8 +257,8 @@ extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_
* \brief Safely get the name of an "operation" parameter value
* \since 18
*
* \param value One of enum \ref ast_stream_codec_negotiation_operation_values
* \returns A constant string with the name of the value or an empty string
* \param value One of enum \ref ast_stream_codec_negotiation_prefs_operation_values
* \return A constant string with the name of the value or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_codec_operation_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_operation_map, value)
@ -267,8 +267,8 @@ extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_
* \brief Safely get the name of a "keep" parameter value
* \since 18
*
* \param value One of enum \ref ast_stream_codec_negotiation_keep_values
* \returns A constant string with the name of the value or an empty string
* \param value One of enum \ref ast_stream_codec_negotiation_prefs_keep_values
* \return A constant string with the name of the value or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_codec_keep_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_keep_map, value)
@ -277,8 +277,8 @@ extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_
* \brief Safely get the name of a "transcode" parameter value
* \since 18
*
* \param value One of enum \ref ast_stream_codec_negotiation_transcode_values
* \returns A constant string with the name of the value or an empty string
* \param value One of enum \ref ast_stream_codec_negotiation_prefs_transcode_values
* \return A constant string with the name of the value or an empty string
* if an invalid value was passed in.
*/
#define ast_stream_codec_transcode_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_transcode_map, value)
@ -316,7 +316,7 @@ struct ast_stream_codec_negotiation_prefs {
* \param prefs A pointer to a ast_stream_codec_negotiation_prefs structure
* \param buf A pointer to an ast_str* used for the output. See note below.
*
* \returns the contents of the ast_str as a const char *.
* \return the contents of the ast_str as a const char *.
*
* \warning No attempt should ever be made to free the returned
* char * and it should be dup'd if needed after the ast_str is freed.
@ -389,7 +389,7 @@ void ast_stream_free(struct ast_stream *stream);
* \brief Create a deep clone of an existing stream
*
* \param stream The existing stream
* \param Optional name for cloned stream. If NULL, then existing stream's name is copied.
* \param name Optional for cloned stream. If NULL, then existing stream's name is copied.
*
* \retval non-NULL success
* \retval NULL failure
@ -457,7 +457,7 @@ const struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *str
*
* \retval "" (empty string) if either buf or *buf are NULL
* \retval "(null stream)" if *stream was NULL
* \retval <stream_representation> otherwise
* \return \<stream_representation\> otherwise
*
* \warning No attempt should ever be made to free the returned
* char * and it should be dup'd if needed after the ast_str is freed.
@ -465,10 +465,10 @@ const struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *str
* \details
*
* Return format:
* <name>:<media_type>:<stream_state> (formats)
* \verbatim <name>:<media_type>:<stream_state> (formats) \endverbatim
*
* Sample return:
* "audio:audio:sendrecv (ulaw,g722)"
* \verbatim "audio:audio:sendrecv (ulaw,g722)" \endverbatim
*
*/
const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf);
@ -476,9 +476,9 @@ const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **
/*!
* \brief Get a stack allocated string representing the stream for debugging/display purposes
*
* \param stream A stream
* \param __stream A stream
*
* \returns a stack allocated pointer to a string representing the stream.
* \return A stack allocated pointer to a string representing the stream.
*
* \warning No attempt should ever be made to free the returned
* char* as it is allocated from the stack.
@ -574,7 +574,7 @@ const char *ast_stream_get_metadata(const struct ast_stream *stream,
*
* \param stream The media stream
*
* \retval An ast_variable list of the metadata key/value pairs.
* \return An ast_variable list of the metadata key/value pairs.
* \retval NULL if error or no variables are set.
*
* When you're finished with the list, you must call
@ -650,7 +650,7 @@ void ast_stream_set_rtp_codecs(struct ast_stream *stream, struct ast_rtp_codecs
* some catastrophic allocation failure.
*
* \retval NULL if there was some allocation failure.
* \retval A new, resolved stream.
* \return A new, resolved stream.
*
*/
struct ast_stream *ast_stream_create_resolved(struct ast_stream *pending_stream,
@ -715,11 +715,11 @@ void ast_stream_topology_free(struct ast_stream_topology *topology);
* \param topology The topology of streams
* \param stream The stream to append
*
* \returns the position of the stream in the topology (-1 on error)
* \return The position of the stream in the topology (-1 on error)
*
* \since 15
*
* \note If the stream's name is empty, it'll be set to <stream_type>-<position>
* \note If the stream's name is empty, it'll be set to \<stream_type\>-\<position\>
*/
int ast_stream_topology_append_stream(struct ast_stream_topology *topology,
struct ast_stream *stream);
@ -729,7 +729,7 @@ int ast_stream_topology_append_stream(struct ast_stream_topology *topology,
*
* \param topology The topology of streams
*
* \return the number of streams (-1 on error)
* \return The number of streams (-1 on error)
*
* \since 15
*/
@ -778,7 +778,7 @@ struct ast_stream *ast_stream_topology_get_stream(
*
* \since 15
*
* \note If the stream's name is empty, it'll be set to <stream_type>-<position>
* \note If the stream's name is empty, it'll be set to \<stream_type\>-\<position\>
*/
int ast_stream_topology_set_stream(struct ast_stream_topology *topology,
unsigned int position, struct ast_stream *stream);
@ -796,8 +796,6 @@ int ast_stream_topology_set_stream(struct ast_stream_topology *topology,
*
* \retval 0 on success.
* \retval -1 on failure.
*
* \return Nothing
*/
int ast_stream_topology_del_stream(struct ast_stream_topology *topology,
unsigned int position);
@ -807,7 +805,7 @@ int ast_stream_topology_del_stream(struct ast_stream_topology *topology,
* creates a topology and separates the media types in format_cap into
* separate streams.
*
* \param caps The format capabilities structure (NULL creates an empty topology)
* \param cap The format capabilities structure (NULL creates an empty topology)
*
* \retval non-NULL success
* \retval NULL failure
@ -853,16 +851,16 @@ struct ast_format_cap *ast_stream_topology_get_formats(
*
* \retval "" (empty string) if either buf or *buf are NULL
* \retval "(null topology)" if *topology was NULL
* \retval <topology_representation> otherwise
* \return \<topology_representation\> otherwise
*
* \warning No attempt should ever be made to free the returned
* char * and it should be dup'd if needed after the ast_str is freed.
*
* Return format:
* <final>? <stream> ...
* \verbatim <final>? <stream> ... \endverbatim
*
* Sample return:
* "final <audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>"
* \verbatim "final <audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>" \endverbatim
*
*/
const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf);
@ -947,7 +945,7 @@ void ast_stream_set_group(struct ast_stream *stream, int group);
*
* \param pending_topology The "live" topology created from an SDP,
* passed through the core, or used to create an SDP.
* \param configured_topology The static topology used to validate the pending topology.
* \param validation_topology The static topology used to validate the pending topology.
* It MUST have only 1 stream per media type.
* \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
* \param error_message If supplied, error messages will be appended.
@ -964,7 +962,7 @@ void ast_stream_set_group(struct ast_stream *stream, int group);
* number of streams, in the same order, as the pending topology.
*
* \retval NULL if there was some allocation failure.
* \retval The joint topology.
* \return The joint topology.
*/
struct ast_stream_topology *ast_stream_topology_create_resolved(
struct ast_stream_topology *pending_topology, struct ast_stream_topology *validation_topology,
@ -974,9 +972,9 @@ struct ast_stream_topology *ast_stream_topology_create_resolved(
/*!
* \brief Get a stack allocated string representing the topology for debugging/display purposes
*
* \param topology A topology
* \param __topology A topology
*
* \returns a stack allocated pointer to a string representing the topology.
* \return A stack allocated pointer to a string representing the topology.
*
* \warning No attempt should ever be made to free the returned
* char* as it is allocated from the stack.

24
include/asterisk/stringfields.h
View File

@ -234,9 +234,11 @@ struct ast_string_field_mgr {
\internal
\brief Attempt to 'grow' an already allocated field to a larger size
\param mgr Pointer to the pool manager structure
\param pool_head Pointer to the current pool
\param needed Amount of space needed for this field
\param ptr Pointer to a field within the structure
\return 0 on success, non-zero on failure
\retval zero on success
\retval non-zero on failure
This function will attempt to increase the amount of space allocated to
an existing field to the amount requested; this is only possible if the
@ -252,9 +254,11 @@ int __ast_string_field_ptr_grow(struct ast_string_field_mgr *mgr,
\internal
\brief Allocate space for a field
\param mgr Pointer to the pool manager structure
\param pool_head Pointer to the current pool
\param needed Amount of space needed for this field
\param fields Pointer to the first entry of the field array
\return NULL on failure, an address for the field on success.
\param file, lineno, func
\retval NULL on failure
\return an address for the field on success.
This function will allocate the requested amount of space from
the field pool. If the requested amount of space is not available,
@ -271,7 +275,7 @@ ast_string_field __ast_string_field_alloc_space(struct ast_string_field_mgr *mgr
\param pool_head Pointer to the current pool
\param ptr Pointer to a field within the structure
\param format printf-style format string
\return nothing
\param file, lineno, func
*/
void __ast_string_field_ptr_build(const char *file, int lineno, const char *func,
struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head,
@ -284,8 +288,8 @@ void __ast_string_field_ptr_build(const char *file, int lineno, const char *func
\param pool_head Pointer to the current pool
\param ptr Pointer to a field within the structure
\param format printf-style format string
\param args va_list of the args for the format_string
\return nothing
\param ap va_list of the args for the format_string
\param file, lineno, func
*/
void __ast_string_field_ptr_build_va(struct ast_string_field_mgr *mgr,
struct ast_string_field_pool **pool_head,
@ -348,7 +352,8 @@ enum ast_stringfield_cleanup_type {
AST_STRINGFIELD_DESTROY (used internally) means free all pools which is
equivalent to calling ast_string_field_free_memory.
\return 0 on success, non-zero on failure
\retval zero on success
\retval non-zero on failure
*/
#define ast_string_field_init(x, size) \
({ \
@ -440,7 +445,6 @@ void *__ast_calloc_with_stringfields(unsigned int num_structs,
\brief Release a field's allocation from a pool
\param pool_head Pointer to the current pool
\param ptr Field to be released
\return nothing
This function will search the pool list to find the pool that contains
the allocation for the specified field, then remove the field's allocation
@ -526,7 +530,6 @@ void __ast_string_field_release_active(struct ast_string_field_pool *pool_head,
\param ptr Pointer to a field within the structure
\param fmt printf-style format string
\param args Arguments for format string
\return nothing
*/
#define ast_string_field_ptr_build(x, ptr, fmt, args...) \
({ \
@ -545,7 +548,6 @@ void __ast_string_field_release_active(struct ast_string_field_pool *pool_head,
\param field Name of the field to set
\param fmt printf-style format string
\param args Arguments for format string
\return nothing
*/
#define ast_string_field_build(x, field, fmt, args...) \
({ \
@ -564,7 +566,6 @@ void __ast_string_field_release_active(struct ast_string_field_pool *pool_head,
\param ptr Pointer to a field within the structure
\param fmt printf-style format string
\param args Arguments for format string in va_list format
\return nothing
*/
#define ast_string_field_ptr_build_va(x, ptr, fmt, args) \
({ \
@ -583,7 +584,6 @@ void __ast_string_field_release_active(struct ast_string_field_pool *pool_head,
\param field Name of the field to set
\param fmt printf-style format string
\param args Arguments for format string in va_list format
\return nothing
*/
#define ast_string_field_build_va(x, field, fmt, args) \
({ \

122
include/asterisk/strings.h
View File

@ -73,23 +73,26 @@ static force_inline int attribute_pure ast_strlen_zero(const char *s)
#define ast_strlen_imaginary(a) ast_random()
#endif
/*! \brief returns the equivalent of logic or for strings:
/*!
* \brief returns the equivalent of logic or for strings:
* first one if not empty, otherwise second one.
*/
#define S_OR(a, b) ({typeof(&((a)[0])) __x = (a); ast_strlen_zero(__x) ? (b) : __x;})
/*! \brief returns the equivalent of logic or for strings, with an additional boolean check:
/*!
* \brief returns the equivalent of logic or for strings, with an additional boolean check:
* second one if not empty and first one is true, otherwise third one.
* example: S_COR(usewidget, widget, "<no widget>")
*/
#define S_COR(a, b, c) ({typeof(&((b)[0])) __x = (b); (a) && !ast_strlen_zero(__x) ? (__x) : (c);})
/*
/*!
\brief Checks whether a string begins with another.
\since 12.0.0
\param str String to check.
\param prefix Prefix to look for.
\param 1 if \a str begins with \a prefix, 0 otherwise.
\retval 1 if \a str begins with \a prefix
\retval 0 otherwise.
*/
static int force_inline attribute_pure ast_begins_with(const char *str, const char *prefix)
{
@ -102,12 +105,13 @@ static int force_inline attribute_pure ast_begins_with(const char *str, const ch
return *prefix == '\0';
}
/*
/*!
\brief Checks whether a string ends with another.
\since 12.0.0
\param str String to check.
\param suffix Suffix to look for.
\param 1 if \a str ends with \a suffix, 0 otherwise.
\retval 1 if \a str ends with \a suffix
\retval 0 otherwise.
*/
static int force_inline attribute_pure ast_ends_with(const char *str, const char *suffix)
{
@ -133,8 +137,8 @@ static int force_inline attribute_pure ast_ends_with(const char *str, const char
* expected, and translations would cause problems.
*
* \param x Boolean value
* \return "Yes" if x is true (non-zero)
* \return "No" if x is false (zero)
* \retval "Yes" if x is true (non-zero)
* \retval "No" if x is false (zero)
*/
#define AST_YESNO(x) ((x) ? "Yes" : "No")
@ -377,7 +381,6 @@ char *ast_escape_c_alloc(const char *s);
\param dst The destination buffer.
\param src The source string
\param size The size of the destination buffer
\return Nothing.
This is similar to \a strncpy, with two important differences:
- the destination buffer will \b always be null-terminated
@ -409,7 +412,8 @@ void ast_copy_string(char *dst, const char *src, size_t size),
* \param haystack The string searched in
* \param delim The haystack delimiter
*
* \return True if an exact match for needle is in haystack, false otherwise
* \retval true If an exact match for needle is in haystack.
* \retval false otherwise
*/
int ast_in_delimited_string(const char *needle, const char *haystack, char delim);
@ -435,7 +439,8 @@ int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attri
This is a wrapper for snprintf, that properly handles the buffer pointer
and buffer space available.
\return 0 on success, non-zero on failure.
\retval zero on success.
\retval non-zero on failure.
\param buffer current position in buffer to place string into (will be updated on return)
\param space remaining space in buffer (will be updated on return)
\param fmt printf-style format string
@ -449,9 +454,8 @@ int ast_build_string_va(char **buffer, size_t *space, const char *fmt, va_list a
* This function checks to see whether a string passed to it is an indication of an "true" value.
* It checks to see if the string is "yes", "true", "y", "t", "on" or "1".
*
* \retval 0 if val is a NULL pointer.
* \retval -1 if "true".
* \retval 0 otherwise.
* \retval 0 otherwise, like NULL pointer.
*/
int attribute_pure ast_true(const char *val);
@ -461,13 +465,12 @@ int attribute_pure ast_true(const char *val);
* This function checks to see whether a string passed to it is an indication of an "false" value.
* It checks to see if the string is "no", "false", "n", "f", "off" or "0".
*
* \retval 0 if val is a NULL pointer.
* \retval -1 if "true".
* \retval 0 otherwise.
* \retval 0 otherwise, like NUL pointer.
*/
int attribute_pure ast_false(const char *val);
/*
/*!
* \brief Join an array of strings into a single string.
* \param s the resulting string buffer
* \param len the length of the result buffer, s
@ -483,7 +486,7 @@ int attribute_pure ast_false(const char *val);
void ast_join_delim(char *s, size_t len, const char * const w[],
unsigned int size, char delim);
/*
/*!
* \brief Join an array of strings into a single string.
* \param s the resulting string buffer
* \param len the length of the result buffer, s
@ -495,7 +498,7 @@ void ast_join_delim(char *s, size_t len, const char * const w[],
*/
#define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
/*
/*!
* \brief Attempts to convert the given string to camel case using
* the specified delimiter.
*
@ -504,12 +507,12 @@ void ast_join_delim(char *s, size_t len, const char * const w[],
* \param s the string to convert
* \param delim delimiter to parse out
*
* \retval The string converted to "CamelCase"
* \return The string converted to "CamelCase"
* \since 12
*/
char *ast_to_camel_case_delim(const char *s, const char *delim);
/*
/*!
* \brief Attempts to convert the given string to camel case using
* an underscore as the specified delimiter.
*
@ -517,33 +520,34 @@ char *ast_to_camel_case_delim(const char *s, const char *delim);
*
* \param s the string to convert
*
* \retval The string converted to "CamelCase"
* \return The string converted to "CamelCase"
*/
#define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
/*
/*!
\brief Parse a time (integer) string.
\param src String to parse
\param dst Destination
\param _default Value to use if the string does not contain a valid time
\param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
\retval 0 on success
\retval zero on success.
\retval non-zero on failure.
*/
int ast_get_time_t(const char *src, time_t *dst, time_t _default, int *consumed);
/*
/*!
\brief Parse a time (float) string.
\param src String to parse
\param dst Destination
\param _default Value to use if the string does not contain a valid time
\param consumed The number of characters 'consumed' in the string by the parse (see 'man sscanf' for details)
\return zero on success, non-zero on failure
\retval zero on success.
\retval non-zero on failure.
*/
int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default, int *consumed);
/*!
* Support for dynamic strings.
* \brief Support for dynamic strings.
*
* A dynamic string is just a C string prefixed by a few control fields
* that help setting/appending/extending it using a printf-like syntax.
@ -587,7 +591,8 @@ int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default
* to the ast_str.
*/
/*! \brief The descriptor of a dynamic string
/*!
* \brief The descriptor of a dynamic string
* XXX storage will be optimized later if needed
* We use the ts field to indicate the type of storage.
* Three special constants indicate malloc, ast_alloca() or static
@ -610,10 +615,10 @@ struct ast_str {
* This function will trim one leading / and one trailing / from a given input string
* ast_str regex_pattern must be preallocated before calling this function
*
* \return 0 on success, non-zero on failure.
* \return 1 if we only stripped a leading /
* \return 2 if we only stripped a trailing /
* \return 3 if we did not strip any / characters
* \retval 0 on success, non-zero on failure.
* \retval 1 if we only stripped a leading /
* \retval 2 if we only stripped a trailing /
* \retval 3 if we did not strip any / characters
* \param regex_string the string containing /regex/
* \param regex_pattern the destination ast_str which will contain "regex" after execution
*/
@ -650,7 +655,8 @@ struct ast_str * attribute_malloc _ast_str_create(size_t init_len,
}
)
/*! \brief Reset the content of a dynamic string.
/*!
* \brief Reset the content of a dynamic string.
* Useful before a series of ast_str_append.
*/
AST_INLINE_API(
@ -675,8 +681,9 @@ void ast_str_update(struct ast_str *buf),
}
)
/*! \brief Trims trailing whitespace characters from an ast_str string.
* \param buf A pointer to the ast_str string.
/*!
* \brief Trims trailing whitespace characters from an ast_str string.
* \param buf A pointer to the ast_str string.
*/
AST_INLINE_API(
void ast_str_trim_blanks(struct ast_str *buf),
@ -690,7 +697,8 @@ void ast_str_trim_blanks(struct ast_str *buf),
}
)
/*!\brief Returns the current length of the string stored within buf.
/*!
* \brief Returns the current length of the string stored within buf.
* \param buf A pointer to the ast_str structure.
*/
AST_INLINE_API(
@ -700,9 +708,10 @@ size_t attribute_pure ast_str_strlen(const struct ast_str *buf),
}
)
/*!\brief Returns the current maximum length (without reallocation) of the current buffer.
/*!
* \brief Returns the current maximum length (without reallocation) of the current buffer.
* \param buf A pointer to the ast_str structure.
* \retval Current maximum length of the buffer.
* \return Current maximum length of the buffer.
*/
AST_INLINE_API(
size_t attribute_pure ast_str_size(const struct ast_str *buf),
@ -711,9 +720,10 @@ size_t attribute_pure ast_str_size(const struct ast_str *buf),
}
)
/*!\brief Returns the string buffer within the ast_str buf.
/*!
* \brief Returns the string buffer within the ast_str buf.
* \param buf A pointer to the ast_str structure.
* \retval A pointer to the enclosed string.
* \return A pointer to the enclosed string.
*/
AST_INLINE_API(
char * attribute_pure ast_str_buffer(const struct ast_str *buf),
@ -726,12 +736,13 @@ char * attribute_pure ast_str_buffer(const struct ast_str *buf),
}
)
/*!\brief Truncates the enclosed string to the given length.
/*!
* \brief Truncates the enclosed string to the given length.
* \param buf A pointer to the ast_str structure.
* \param len Maximum length of the string. If len is larger than the
* current maximum length, things will explode. If it is negative
* at most -len characters will be trimmed off the end.
* \retval A pointer to the resulting string.
* \return A pointer to the resulting string.
*/
AST_INLINE_API(
char *ast_str_truncate(struct ast_str *buf, ssize_t len),
@ -1012,28 +1023,28 @@ AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struc
}
)
/*!\brief Set a dynamic string to a non-NULL terminated substring. */
/*! \brief Set a dynamic string to a non-NULL terminated substring. */
AST_INLINE_API(char *ast_str_set_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
{
return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 0);
}
)
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string. */
/*! \brief Append a non-NULL terminated substring to the end of a dynamic string. */
AST_INLINE_API(char *ast_str_append_substr(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
{
return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 0);
}
)
/*!\brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
/*! \brief Set a dynamic string to a non-NULL terminated substring, with escaping of commas. */
AST_INLINE_API(char *ast_str_set_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
{
return __ast_str_helper2(buf, maxlen, src, maxsrc, 0, 1);
}
)
/*!\brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
/*! \brief Append a non-NULL terminated substring to the end of a dynamic string, with escaping of commas. */
AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t maxlen, const char *src, size_t maxsrc),
{
return __ast_str_helper2(buf, maxlen, src, maxsrc, 1, 1);
@ -1112,7 +1123,7 @@ int __attribute__((format(printf, 3, 4))) ast_str_append(
* \param init_len The initial length of the temporary ast_str needed.
* \param __expr An expression that needs the temporary ast_str and returns a char *.
*
* \returns A copy of __expr's return buffer allocated on the stack.
* \return A copy of __expr's return buffer allocated on the stack.
*
* \details
* There are a few query functions scattered around that need an ast_str in which
@ -1183,7 +1194,7 @@ int ast_check_digits(const char *arg),
/*!
* \brief Convert the tech portion of a device string to upper case
*
* \retval dev_str Returns the char* passed in for convenience
* \retval dev_str the char* passed in for convenience
*/
AST_INLINE_API(
char *ast_tech_to_upper(char *dev_str),
@ -1281,7 +1292,7 @@ static force_inline int attribute_pure ast_str_case_hash(const char *str)
*
* \param str The string to be converted to lower case
*
* \retval str for convenience
* \retval str the char* passed in for convenience
*/
static force_inline char *ast_str_to_lower(char *str)
{
@ -1302,7 +1313,7 @@ static force_inline char *ast_str_to_lower(char *str)
*
* \param str The string to be converted to upper case
*
* \retval str for convenience
* \retval str the char* passed in for convenience
*/
static force_inline char *ast_str_to_upper(char *str)
{
@ -1324,7 +1335,7 @@ static force_inline char *ast_str_to_upper(char *str)
*
* \param buckets The number of buckets to use for the hash container
*
* \retval AO2 container for strings
* \return AO2 container for strings
* \retval NULL if allocation failed
*/
#define ast_str_container_alloc(buckets) ast_str_container_alloc_options(AO2_ALLOC_OPT_LOCK_MUTEX, buckets)
@ -1336,7 +1347,7 @@ static force_inline char *ast_str_to_upper(char *str)
* \param opts Options to be provided to the container
* \param buckets The number of buckets to use for the hash container
*
* \retval AO2 container for strings
* \return AO2 container for strings
* \retval NULL if allocation failed
*/
//struct ao2_container *ast_str_container_alloc_options(enum ao2_container_opts opts, int buckets);
@ -1391,7 +1402,8 @@ char *ast_generate_random_string(char *buf, size_t size);
* \param str1 The string to compare to str2
* \param str2 The string to compare to str1
*
* \return true if valid strings and equal, false otherwise.
* \retval true if valid strings and equal.
* \retval false otherwise.
*/
int ast_strings_equal(const char *str1, const char *str2);
@ -1428,18 +1440,18 @@ int ast_strings_match(const char *left, const char *op, const char *right);
* \brief Read lines from a string buffer
* \since 13.18.0
*
* \param buffer [IN/OUT] A pointer to a char * string with either Unix or Windows line endings
* \param[in,out] buffer A pointer to a char * string with either Unix or Windows line endings
*
* \return The "next" line
*
* \warning The original string and *buffer will be modified.
*
* \details
* Both '\n' and '\r\n' are treated as single delimiters but consecutive occurrences of
* Both '\\n' and '\\r\\n' are treated as single delimiters but consecutive occurrences of
* the delimiters are NOT considered to be a single delimiter. This preserves blank
* lines in the input.
*
* MacOS line endings ('\r') are not supported at this time.
* macOS line endings ('\\r') are not supported at this time.
*
*/
char *ast_read_line_from_buffer(char **buffer);

4
include/asterisk/taskprocessor.h
View File

@ -178,7 +178,7 @@ struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_o
* \param name The name of the taskprocessor to create
* \param listener The listener for operations on this taskprocessor
* \retval NULL Failure
* \reval non-NULL success
* \retval non-NULL success
*/
struct ast_taskprocessor *ast_taskprocessor_create_with_listener(const char *name, struct ast_taskprocessor_listener *listener);
@ -325,8 +325,6 @@ void ast_taskprocessor_name_append(char *buf, unsigned int size, const char *nam
* \note The user supplied part of the taskprocessor name is truncated
* to allow the full sequence number to be appended within the supplied
* buffer size.
*
* \return Nothing
*/
void __attribute__((format(printf, 3, 4))) ast_taskprocessor_build_name(char *buf, unsigned int size, const char *format, ...);

4
include/asterisk/tdd.h
View File

@ -75,8 +75,8 @@ int ast_tdd_gen_ecdisa(unsigned char *outbuf, int len);
/*! Generate hold tone
* \param outbuf This is the buffer to receive the tone data
* \param buf This is the buffer to receive the tone data
*/
int tdd_gen_holdtone(unsigned char* outbuf);
int tdd_gen_holdtone(unsigned char* buf);
#endif /* _ASTERISK_TDD_H */

1
include/asterisk/threadstorage.h
View File

@ -245,6 +245,7 @@ void *ast_threadstorage_get_ptr(struct ast_threadstorage *ts),
/*!
* \brief Set a raw pointer from threadstorage.
* \param ts Threadstorage object to operate on.
* \param ptr
*
* \retval 0 Success
* \retval non-zero Failure

1
include/asterisk/timing.h
View File

@ -124,7 +124,6 @@ struct ast_timer *ast_timer_open(void);
*
* \param handle timer handle returned from timer_open()
*
* \return nothing
* \since 1.6.1
*/
void ast_timer_close(struct ast_timer *handle);

28
include/asterisk/translate.h
View File

@ -249,7 +249,8 @@ struct ast_trans_pvt;
* This registers a codec translator with asterisk
* \param t populated ast_translator structure
* \param mod module handle to the module that owns this translator
* \return 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
@ -260,14 +261,14 @@ int __ast_register_translator(struct ast_translator *t, struct ast_module *modul
* \brief Unregister a translator
* Unregisters the given translator
* \param t translator to unregister
* \return 0 on success, -1 on failure
* \retval 0 on success
* \retval -1 on failure
*/
int ast_unregister_translator(struct ast_translator *t);
/*!
* \brief Activate a previously deactivated translator
* \param t translator to activate
* \return nothing
*
* Enables the specified translator for use.
*/
@ -276,7 +277,6 @@ void ast_translator_activate(struct ast_translator *t);
/*!
* \brief Deactivate a translator
* \param t translator to deactivate
* \return nothing
*
* Disables the specified translator from being used.
*/
@ -292,7 +292,8 @@ void ast_translator_deactivate(struct ast_translator *t);
* \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.
* \retval 0 on success
* \retval -1 if no path could be found.
*
* \note dst_cap and src_cap are not mondified.
*/
@ -306,7 +307,8 @@ int ast_translator_best_choice(struct ast_format_cap *dst_cap,
* Build a path (possibly NULL) from source to dest
* \param dst dest destination format
* \param src source source format
* \return ast_trans_pvt on success, NULL on failure
* \return ast_trans_pvt on success
* \retval NULL on failure
* */
struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
@ -326,7 +328,8 @@ void ast_translator_free_path(struct ast_trans_pvt *tr);
* \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
* \return an ast_frame of the new translation format on success
* \retval NULL on failure
*/
struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
@ -334,7 +337,8 @@ struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, i
* \brief Returns the number of steps required to convert from 'src' to 'dest'.
* \param dest destination format
* \param src source format
* \return the number of translation steps required, or -1 if no path is available
* \return the number of translation steps required
* \retval -1 if no path is available
*/
unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format *src);
@ -342,9 +346,8 @@ unsigned int ast_translate_path_steps(struct ast_format *dest, struct ast_format
* \brief Find available formats
* \param dest possible destination formats
* \param src source formats
* \param result capabilities structure to store available formats in
*
* \return the destination formats that are available in the source or translatable
* \param[out] result capabilities structure to store available formats in
* returns the destination formats that are available in the source or translatable
*
* The result will include all formats from 'dest' that are either present
* in 'src' or translatable from a format present in 'src'.
@ -358,7 +361,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 t translator structure containing the translation path
* \param str ast_str output buffer
* \retval on success pointer to beginning of outbuf. on failure "".
* \return on success pointer to beginning of outbuf
* \retval "" on failure
*/
const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);

6
include/asterisk/udptl.h
View File

@ -60,8 +60,6 @@ struct ast_udptl *ast_udptl_new_with_bindaddr(struct ast_sched_context *sched, s
* related to that session will include the tag and the reader of
* the messages will be able to identify which endpoint caused them
* to be generated.
*
* \retval none
*/
void __attribute__((format(printf, 2, 3))) ast_udptl_set_tag(struct ast_udptl *udptl, const char *format, ...);
@ -101,7 +99,7 @@ void ast_udptl_set_local_max_ifp(struct ast_udptl *udptl, unsigned int max_ifp);
/*!
* \brief retrieves local_max_datagram.
*
* \retval positive value representing max datagram size.
* \return positive value representing max datagram size.
* \retval 0 if no value is present
*/
unsigned int ast_udptl_get_local_max_datagram(struct ast_udptl *udptl);
@ -117,7 +115,7 @@ unsigned int ast_udptl_get_far_max_datagram(const struct ast_udptl *udptl);
/*!
* \brief retrieves far max ifp
*
* \retval positive value representing max ifp size
* \return positive value representing max ifp size
* \retval 0 if no value is present
*/
unsigned int ast_udptl_get_far_max_ifp(struct ast_udptl *udptl);

25
include/asterisk/uri.h
View File

@ -26,13 +26,13 @@ struct ast_uri;
* \brief Create a uri with the given parameters
*
* \param scheme the uri scheme (ex: http)
* \param user_info user credentials (ex: <name>@<pass>)
* \param user_info user credentials (ex: \<name\>\@\<pass\>)
* \param host host name or ip address
* \param port the port
* \param path the path
* \param query query parameters
* \return a structure containing parsed uri data.
* \return \c NULL on error
* \retval NULL on error
* \since 13
*/
struct ast_uri *ast_uri_create(const char *scheme, const char *user_info,
@ -45,13 +45,13 @@ struct ast_uri *ast_uri_create(const char *scheme, const char *user_info,
*
* \param uri the uri object to copy
* \param scheme the uri scheme (ex: http)
* \param user_info user credentials (ex: <name>@<pass>)
* \param user_info user credentials (ex: \<name\>\@\<pass\>)
* \param host host name or ip address
* \param port the port
* \param path the path
* \param query query parameters
* \return a copy of the given uri with specified values replaced.
* \return \c NULL on error
* \retval NULL on error
* \since 13
*/
struct ast_uri *ast_uri_copy_replace(const struct ast_uri *uri, const char *scheme,
@ -112,7 +112,8 @@ const char *ast_uri_query(const struct ast_uri *uri);
* \note Secure types are recognized by an 's' at the end
* of the scheme.
*
* \return True if secure, False otherwise.
* \retval True if secure.
* \retval False otherwise.
* \since 13
*/
int attribute_pure ast_uri_is_secure(const struct ast_uri *uri);
@ -121,11 +122,11 @@ int attribute_pure ast_uri_is_secure(const struct ast_uri *uri);
* \brief Parse the given uri into a structure.
*
* \note Expects the following form:
* <scheme>://[user:pass@]<host>[:port][/<path>]
* \verbatim <scheme>://[user:pass@]<host>[:port][/<path>] \endverbatim
*
* \param uri a string uri to parse
* \return a structure containing parsed uri data.
* \return \c NULL on error
* \retval NULL on error
* \since 13
*/
struct ast_uri *ast_uri_parse(const char *uri);
@ -134,7 +135,7 @@ struct ast_uri *ast_uri_parse(const char *uri);
* \brief Parse the given http uri into a structure.
*
* \note Expects the following form:
* [http[s]://][user:pass@]<host>[:port][/<path>]
* \verbatim [http[s]://][user:pass@]<host>[:port][/<path>] \endverbatim
*
* \note If no scheme is given it defaults to 'http' and if
* no port is specified it will default to 443 if marked
@ -142,7 +143,7 @@ struct ast_uri *ast_uri_parse(const char *uri);
*
* \param uri an http string uri to parse
* \return a structure containing parsed http uri data.
* \return \c NULL on error
* \retval NULL on error
* \since 13
*/
struct ast_uri *ast_uri_parse_http(const char *uri);
@ -159,7 +160,7 @@ struct ast_uri *ast_uri_parse_http(const char *uri);
*
* \param uri a websocket string uri to parse
* \return a structure containing parsed http uri data.
* \return \c NULL on error
* \retval NULL on error
* \since 13
*/
struct ast_uri *ast_uri_parse_websocket(const char *uri);
@ -167,8 +168,8 @@ struct ast_uri *ast_uri_parse_websocket(const char *uri);
/*!
* \brief Retrieve a string of the host and port.
*
* \detail Combine the host and port (<host>:<port>) if the port
* is available, otherwise just return the host.
* Combine the host and port (\<host\>:\<port\>) if the port
* is available, otherwise just return the host.
*
* \note Caller is responsible for release the returned string.
*

5
include/asterisk/utf8.h
View File

@ -54,7 +54,7 @@ int ast_utf8_is_validn(const char *str, size_t size);
* \brief Copy a string safely ensuring valid UTF-8
* \since 13.36.0, 16.13.0, 17.7.0, 18.0.0
*
* This is similar to \a ast_copy_string, but it will only copy valid UTF-8
* This is similar to \ref ast_copy_string, but it will only copy valid UTF-8
* sequences from the source string into the destination buffer. If an invalid
* UTF-8 sequence is encountered, or the available space in the destination
* buffer is exhausted in the middle of an otherwise valid UTF-8 sequence, the
@ -64,7 +64,6 @@ int ast_utf8_is_validn(const char *str, size_t size);
* \param dst The destination buffer.
* \param src The source string
* \param size The size of the destination buffer
* \return Nothing.
*/
void ast_utf8_copy_string(char *dst, const char *src, size_t size);
@ -181,7 +180,7 @@ void ast_utf8_validator_destroy(struct ast_utf8_validator *validator);
*
* Does nothing unless TEST_FRAMEWORK is defined.
*
* \return Always returns 0
* \retval 0 Always
*/
int ast_utf8_init(void);

81
include/asterisk/utils.h
View File

@ -248,7 +248,7 @@ int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
* \param src The source buffer
*
* \retval NULL on failure
* \retval Encoded string on success
* \return Encoded string on success
*/
char *ast_base64encode_string(const char *src);
@ -272,7 +272,7 @@ int ast_base64decode(unsigned char *dst, const char *src, int max);
* \param src The source buffer
*
* \retval NULL on failure
* \retval Decoded string on success
* \return Decoded string on success
*/
char *ast_base64decode_string(const char *src);
@ -320,7 +320,7 @@ int ast_base64url_encode(char *dst, const unsigned char *src, int srclen, int ma
* \param src The source buffer
*
* \retval NULL on failure
* \retval Decoded string on success
* \return Decoded string on success
*/
char *ast_base64url_decode_string(const char *src);
@ -332,7 +332,7 @@ char *ast_base64url_decode_string(const char *src);
* \param src The source data to be encoded
*
* \retval NULL on failure
* \retval Encoded string on success
* \return Encoded string on success
*/
char *ast_base64url_encode_string(const char *src);
@ -405,8 +405,8 @@ void ast_uri_decode(char *s, struct ast_flags spec);
\param string String to be converted
\param outbuf Resulting encoded string
\param buflen Size of output buffer
\return 0 for success
\return -1 if buflen is too short.
\retval 0 for success
\retval -1 if buflen is too short.
*/
int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
@ -621,7 +621,6 @@ long int ast_random(void);
/*!
* \brief Disable PMTU discovery on a socket
* \param sock The socket to manipulate
* \return Nothing
*
* On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
* bit set. This is supposedly done to allow the application to do PMTU
@ -637,7 +636,8 @@ void ast_enable_packet_fragmentation(int sock);
* \brief Recursively create directory path
* \param path The directory path to create
* \param mode The permissions with which to try to create the directory
* \return 0 on success or an error code otherwise
* \retval 0 on success
* \return error code otherwise
*
* Creates a directory path, creating parent directories as needed.
*/
@ -650,9 +650,11 @@ int ast_mkdir(const char *path, int mode);
* If \a base_path does not exist, it will not be created and this function
* returns \c EPERM.
*
* \param base_path
* \param path The directory path to create
* \param mode The permissions with which to try to create the directory
* \return 0 on success or an error code otherwise
* \retval 0 on success
* \return an error code otherwise
*/
int ast_safe_mkdir(const char *base_path, const char *path, int mode);
@ -664,7 +666,8 @@ int ast_safe_mkdir(const char *base_path, const char *path, int mode);
* \param v the value to check
* \param min minimum lower bound (inclusive)
* \param max maximum upper bound (inclusive)
* \return 0 if value out of bounds, otherwise true (non-zero)
* \retval 0 if value out of bounds
* \retval non-zero otherwise
*/
#define IN_BOUNDS(v, min, max) ((v) >= (min)) && ((v) <= (max))
@ -673,7 +676,8 @@ int ast_safe_mkdir(const char *base_path, const char *path, int mode);
*
* \param v the value to check
* \param a the array to bound check
* \return 0 if value out of bounds, otherwise true (non-zero)
* \retval 0 if value out of bounds
* \retval non-zero otherwise
*/
#define ARRAY_IN_BOUNDS(v, a) IN_BOUNDS((int) (v), 0, ARRAY_LEN(a) - 1)
@ -695,7 +699,7 @@ struct ast_http_digest {
/*!
* \brief Parse digest authorization header.
* \return Returns -1 if we have no auth or something wrong with digest.
* \return -1 if we have no auth or something wrong with digest.
* \note This function may be used for Digest request and responce header.
* request arg is set to nonzero, if we parse Digest Request.
* pedantic arg can be set to nonzero if we need to do addition Digest check.
@ -740,8 +744,6 @@ static void force_inline _ast_assert(int condition, const char *condition_str, c
* \brief Force a crash if DO_CRASH is defined.
*
* \note If DO_CRASH is not defined then the function returns.
*
* \return Nothing
*/
void DO_CRASH_NORETURN ast_do_crash(void);
@ -833,7 +835,8 @@ char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
* This function expects an EID in the format:
* 00:11:22:33:44:55
*
* \return 0 success, non-zero failure
* \retval 0 success
* \retval non-zero failure
* \since 1.6.1
*/
int ast_str_to_eid(struct ast_eid *eid, const char *s);
@ -841,7 +844,8 @@ int ast_str_to_eid(struct ast_eid *eid, const char *s);
/*!
* \brief Compare two EIDs
*
* \return 0 if the two are the same, non-zero otherwise
* \retval 0 if the two are the same
* \retval non-zero otherwise
* \since 1.6.1
*/
int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
@ -849,7 +853,8 @@ int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
/*!
* \brief Check if EID is empty
*
* \return 1 if the EID is empty, zero otherwise
* \retval 1 if the EID is empty
* \retval 0 otherwise
* \since 13.12.0
*/
int ast_eid_is_empty(const struct ast_eid *eid);
@ -949,7 +954,7 @@ static inline void _raii_cleanup_block(_raii_cleanup_block_t *b) { (*b)(); }
* \param key User's password to crypt.
* \param salt Salt to crypt with.
* \return Crypted password.
* \return \c NULL on error.
* \retval NULL on error.
*/
char *ast_crypt(const char *key, const char *salt);
@ -962,7 +967,7 @@ char *ast_crypt(const char *key, const char *salt);
*
* \param key User's password to crypt.
* \return Crypted password.
* \return \c NULL on error.
* \retval NULL on error.
*/
char *ast_crypt_encrypt(const char *key);
@ -971,8 +976,8 @@ char *ast_crypt_encrypt(const char *key);
*
* \param key User's password to validate.
* \param expected Expected result from crypt.
* \return True (non-zero) if \a key matches \a expected.
* \return False (zero) if \a key doesn't match.
* \retval True (non-zero) if \a key matches \a expected.
* \retval False (zero) if \a key doesn't match.
*/
int ast_crypt_validate(const char *key, const char *expected);
@ -981,8 +986,8 @@ int ast_crypt_validate(const char *key, const char *expected);
* \since 13.7.0
*
* \param filename File to test.
* \return True (non-zero) if the file exists and is readable.
* \return False (zero) if the file either doesn't exists or is not readable.
* \retval True (non-zero) if the file exists and is readable.
* \retval False (zero) if the file either doesn't exists or is not readable.
*/
int ast_file_is_readable(const char *filename);
@ -990,12 +995,12 @@ int ast_file_is_readable(const char *filename);
* \brief Compare 2 major.minor.patch.extra version strings.
* \since 13.7.0
*
* \param version1.
* \param version2.
* \param version1
* \param version2
*
* \return <0 if version 1 < version 2.
* \return =0 if version 1 = version 2.
* \return >0 if version 1 > version 2.
* \retval negative if version 1 < version 2.
* \retval 0 if version 1 = version 2.
* \retval positive if version 1 > version 2.
*/
int ast_compare_versions(const char *version1, const char *version2);
@ -1003,8 +1008,8 @@ int ast_compare_versions(const char *version1, const char *version2);
* \brief Test that an OS supports IPv6 Networking.
* \since 13.14.0
*
* \return True (non-zero) if the IPv6 supported.
* \return False (zero) if the OS doesn't support IPv6.
* \retval True (non-zero) if the IPv6 supported.
* \retval False (zero) if the OS doesn't support IPv6.
*/
int ast_check_ipv6(void);
@ -1023,8 +1028,8 @@ enum ast_fd_flag_operation {
* \param fd File descriptor to set flags on
* \param flags The flag(s) to set
*
* \return -1 on error
* \return 0 if successful
* \retval -1 on error
* \retval 0 if successful
*/
#define ast_fd_set_flags(fd, flags) \
__ast_fd_set_flags((fd), (flags), AST_FD_FLAG_SET, __FILE__, __LINE__, __PRETTY_FUNCTION__)
@ -1039,8 +1044,8 @@ enum ast_fd_flag_operation {
* \param fd File descriptor to clear flags on
* \param flags The flag(s) to clear
*
* \return -1 on error
* \return 0 if successful
* \retval -1 on error
* \retval 0 if successful
*/
#define ast_fd_clear_flags(fd, flags) \
__ast_fd_set_flags((fd), (flags), AST_FD_FLAG_CLEAR, __FILE__, __LINE__, __PRETTY_FUNCTION__)
@ -1087,16 +1092,16 @@ int ast_pipe_nonblock(int filedes[2]);
*
* \param is_user_interface Non-zero to mark the thread as a user interface.
*
* \return 0 if successfuly marked current thread.
* \return Non-zero if marking current thread failed.
* \retval True (non-zero) if marking current thread failed.
* \retval False (zero) if successfuly marked current thread.
*/
int ast_thread_user_interface_set(int is_user_interface);
/*!
* \brief Indicates whether the current thread is a user interface
*
* \return True (non-zero) if thread is a user interface.
* \return False (zero) if thread is not a user interface.
* \retval True (non-zero) if thread is a user interface.
* \retval False (zero) if thread is not a user interface.
*/
int ast_thread_is_user_interface(void);

91
include/asterisk/vector.h
View File

@ -69,7 +69,7 @@ enum ast_vector_string_split_flags {
* \param dest Pointer to an initialized vector.
* \param input String buffer to split.
* \param delim String delimeter passed to strsep.
* \param flags Processing options defined by \ref enum ast_vector_string_split_flags.
* \param flags Processing options defined by \ref ast_vector_string_split_flags.
* \param excludes_cmp NULL or a function like strcmp to exclude duplicate strings.
*
* \retval 0 Success
@ -107,8 +107,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param vec Vector to initialize.
* \param size Initial size of the vector.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*/
#define AST_VECTOR_INIT(vec, size) ({ \
size_t __size = (size); \
@ -152,8 +152,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param vec Vector to initialize.
* \param size Initial size of the vector.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*/
#define AST_VECTOR_RW_INIT(vec, size) ({ \
int res = -1; \
@ -250,8 +250,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param vec Vector to append to.
* \param elem Element to append.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*/
#define AST_VECTOR_APPEND(vec, elem) ({ \
int res = 0; \
@ -272,8 +272,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param idx Position to replace.
* \param elem Element to replace.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*
* \warning This macro will overwrite anything already present at the position provided.
*
@ -326,8 +326,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param idx Position to insert at.
* \param elem Element to insert.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*
* \warning This macro will shift existing elements right to make room for the new element.
*
@ -360,8 +360,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param elem Element to insert. Must not be an array type.
* \param cmp A strcmp compatible compare function.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*
* \warning Use of this macro on an unsorted vector will produce unpredictable results
* \warning 'elem' must not be an array type so passing 'x' where 'x' is defined as
@ -405,7 +405,7 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to remove from.
* \param idx Index of the element to remove.
* \param preserve_order Preserve the vector order.
* \param preserve_ordered Preserve the vector order.
*
* \return The element that was removed.
*/
@ -482,8 +482,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param cmp Comparator function/macros (called as \c cmp(elem, value))
* \param cleanup How to cleanup a removed element macro/function.
*
* \return 0 if element was removed.
* \return Non-zero if element was not in the vector.
* \retval 0 if element was removed.
* \retval Non-zero if element was not in the vector.
*/
#define AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup) ({ \
int res = -1; \
@ -534,8 +534,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param cmp Comparator function/macros (called as \c cmp(elem, value))
* \param cleanup How to cleanup a removed element macro/function.
*
* \return 0 if element was removed.
* \return Non-zero if element was not in the vector.
* \retval 0 if element was removed.
* \retval Non-zero if element was not in the vector.
*/
#define AST_VECTOR_REMOVE_CMP_ORDERED(vec, value, cmp, cleanup) ({ \
int res = -1; \
@ -558,8 +558,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param elem Element to compare against
* \param value Value to compare with the vector element.
*
* \return 0 if element does not match.
* \return Non-zero if element matches.
* \retval 0 if element does not match.
* \retval Non-zero if element matches.
*/
#define AST_VECTOR_ELEM_DEFAULT_CMP(elem, value) ((elem) == (value))
@ -567,8 +567,6 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \brief Vector element cleanup that does nothing.
*
* \param elem Element to cleanup
*
* \return Nothing
*/
#define AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
@ -579,8 +577,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param elem Element to remove
* \param cleanup How to cleanup a removed element macro/function.
*
* \return 0 if element was removed.
* \return Non-zero if element was not in the vector.
* \retval 0 if element was removed.
* \retval Non-zero if element was not in the vector.
*/
#define AST_VECTOR_REMOVE_ELEM_UNORDERED(vec, elem, cleanup) ({ \
AST_VECTOR_REMOVE_CMP_UNORDERED((vec), (elem), \
@ -594,8 +592,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \param elem Element to remove
* \param cleanup How to cleanup a removed element macro/function.
*
* \return 0 if element was removed.
* \return Non-zero if element was not in the vector.
* \retval 0 if element was removed.
* \retval Non-zero if element was not in the vector.
*/
#define AST_VECTOR_REMOVE_ELEM_ORDERED(vec, elem, cleanup) ({ \
AST_VECTOR_REMOVE_CMP_ORDERED((vec), (elem), \
@ -622,7 +620,7 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \brief Reset vector.
*
* \param vec Vector to reset.
* \param callback A cleanup callback or AST_VECTOR_ELEM_CLEANUP_NOOP.
* \param cleanup A cleanup callback or AST_VECTOR_ELEM_CLEANUP_NOOP.
*/
#define AST_VECTOR_RESET(vec, cleanup) ({ \
AST_VECTOR_CALLBACK_VOID(vec, cleanup); \
@ -634,8 +632,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to compact.
*
* \return 0 on success.
* \return Non-zero on failure.
* \retval 0 on success.
* \retval Non-zero on failure.
*/
#define AST_VECTOR_COMPACT(vec) ({ \
int res = 0; \
@ -746,10 +744,9 @@ int ast_vector_string_split(struct ast_vector_string *dest,
/*!
* \brief Default callback for AST_VECTOR_CALLBACK()
*
* \param elem Element to compare against
* \param value Value to compare with the vector element.
* \param element Element to compare against
*
* \return CMP_MATCH always.
* \retval CMP_MATCH always.
*/
#define AST_VECTOR_MATCH_ALL(element) (CMP_MATCH)
@ -874,8 +871,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to operate on.
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_RDLOCK(vec) ast_rwlock_rdlock(&(vec)->lock)
@ -884,8 +881,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to operate on.
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_WRLOCK(vec) ast_rwlock_wrlock(&(vec)->lock)
@ -894,8 +891,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to operate on.
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_UNLOCK(vec) ast_rwlock_unlock(&(vec)->lock)
@ -904,8 +901,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to operate on.
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_RDLOCK_TRY(vec) ast_rwlock_tryrdlock(&(vec)->lock)
@ -914,8 +911,8 @@ int ast_vector_string_split(struct ast_vector_string *dest,
*
* \param vec Vector to operate on.
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_WRLOCK_TRY(vec) ast_rwlock_trywrlock(&(vec)->lock)
@ -923,9 +920,10 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \brief Try to obtain read lock on vector failing after timeout if unable
*
* \param vec Vector to operate on.
* \param timespec
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_RDLOCK_TIMED(vec, timespec) ast_rwlock_timedrdlock(&(vec)->lock, timespec)
@ -933,9 +931,10 @@ int ast_vector_string_split(struct ast_vector_string *dest,
* \brief Try to obtain write lock on vector failing after timeout if unable
*
* \param vec Vector to operate on.
* \param timespec
*
* \return 0 if success
* \return Non-zero if error
* \retval 0 if success
* \retval Non-zero if error
*/
#define AST_VECTOR_RW_WRLOCK_TIMED(vec, timespec) ast_rwlock_timedwrlock(&(vec)->lock, timespec)

28
include/asterisk/xml.h
View File

@ -45,7 +45,7 @@ int ast_xml_finish(void);
* \brief Open an XML document.
* \param filename Document path.
* \retval NULL on error.
* \retval The ast_xml_doc reference to the open document.
* \return The ast_xml_doc reference to the open document.
*/
struct ast_xml_doc *ast_xml_open(char *filename);
@ -102,7 +102,7 @@ struct ast_xml_node *ast_xml_copy_node_list(struct ast_xml_node *list);
/*!
* \brief Close an already open document and free the used
* structure.
* \retval doc The document reference.
* \param doc XML Document to close
*/
void ast_xml_close(struct ast_xml_doc *doc);
@ -110,22 +110,22 @@ void ast_xml_close(struct ast_xml_doc *doc);
* \param buffer The address where the document is stored
* \param size The number of bytes in the document
* \retval NULL on error.
* \retval The ast_xml_doc reference to the open document.
* \return The ast_xml_doc reference to the open document.
*/
struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size);
/*!
* \brief Specify the root node of a XML document.
* \param doc The document pointer.
* \param doc XML Document reference
* \param node A pointer to the node we want to set as root node.
*/
void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node);
/*!
* \brief Get the document root node.
* \param doc Document reference
* \param doc XML Document reference
* \retval NULL on error
* \retval The root node on success.
* \return The root node on success.
*/
struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc);
@ -144,7 +144,7 @@ void ast_xml_free_attr(const char *attribute);
/*!
* \brief Get the document based on a node.
* \param node A node that is part of the dom.
* \returns The dom pointer where this node resides.
* \return The dom pointer where this node resides.
*/
struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node);
@ -159,7 +159,7 @@ void ast_xml_free_text(const char *text);
* \param node Node where to search the attribute.
* \param attrname Attribute name.
* \retval NULL on error
* \retval The attribute value on success.
* \return The attribute value on success.
*/
const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname);
@ -180,7 +180,7 @@ int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const cha
* \param attrname attribute name to match (if NULL it won't be matched).
* \param attrvalue attribute value to match (if NULL it won't be matched).
* \retval NULL if not found.
* \retval The node on success.
* \return The node on success.
*/
struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);
struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name);
@ -190,7 +190,7 @@ const char *ast_xml_get_ns_href(struct ast_xml_ns *ns);
* \brief Get an element content string.
* \param node Node from where to get the string.
* \retval NULL on error.
* \retval The text content of node.
* \return The text content of node.
*/
const char *ast_xml_get_text(struct ast_xml_node *node);
@ -236,7 +236,7 @@ void ast_xml_xpath_results_free(struct ast_xml_xpath_results *results);
/*!
* \brief Return the number of results from an XPath query
* \param results The XPath results object to count
* \retval The number of results in the XPath object
* \return The number of results in the XPath object
*
* \since 12
*/
@ -245,7 +245,7 @@ int ast_xml_xpath_num_results(struct ast_xml_xpath_results *results);
/*!
* \brief Return the first result node of an XPath query
* \param results The XPath results object to get the first result from
* \retval The first result in the XPath object on success
* \return The first result in the XPath object on success
* \retval NULL on error
*
* \since 12
@ -254,9 +254,9 @@ struct ast_xml_node *ast_xml_xpath_get_first_result(struct ast_xml_xpath_results
/*!
* \brief Execute an XPath query on an XML document
* \param doc The XML document to query
* \param doc XML document to query
* \param xpath_str The XPath query string to execute on the document
* \retval An object containing the results of the XPath query on success
* \return An object containing the results of the XPath query on success
* \retval NULL on failure
*
* \since 12

8
main/aoc.c
View File

@ -1389,8 +1389,6 @@ static char *aoc_cli_debug_enable(struct ast_cli_entry *e, int cmd, struct ast_c
* \param name Name of the time structure to convert.
* \param time Data to convert.
* \param scale Data to convert.
*
* \return Nothing
*/
static void aoc_time_str(struct ast_str **msg, const char *prefix, const char *name, unsigned long time, enum ast_aoc_time_scale scale)
{
@ -1407,9 +1405,7 @@ static void aoc_time_str(struct ast_str **msg, const char *prefix, const char *n
* \param msg Event message string being built.
* \param prefix Prefix to add to the amount lines.
* \param amount Data to convert.
* \param multiplier to convert
*
* \return Nothing
* \param mult to convert
*/
static void aoc_amount_str(struct ast_str **msg, const char *prefix, unsigned int amount, enum ast_aoc_currency_multiplier mult)
{
@ -1829,8 +1825,6 @@ static void aoc_event_blob_dtor(void *obj)
* \param chan Channel associated with the AOC event. (May be NULL if no channel)
* \param msg_type What kind of AOC event.
* \param blob AOC data blob to publish.
*
* \return Nothing
*/
static void aoc_publish_blob(struct ast_channel *chan, struct stasis_message_type *msg_type, struct ast_json *blob)
{

4
main/astobj2.c
View File

@ -65,7 +65,7 @@ struct __priv_data {
* \brief The ao2 object option flags.
*
* \note This field is constant after object creation. It shares
* a uint32_t with \ref lockused and \ref magic.
* a uint32_t with \p lockused and \p magic.
*/
uint32_t options:3;
/*!
@ -82,7 +82,7 @@ struct __priv_data {
* reference.
*
* \note This field is constant after object creation. It shares
* a uint32_t with \ref options and \ref lockused.
* a uint32_t with \p options and \p lockused.
*
* \warning Stealing bits for any additional writable fields would cause
* reentrancy issues if using bitfields. If any additional

27
main/astobj2_container_private.h
View File

@ -78,8 +78,6 @@ struct ao2_container_node {
* \brief Destroy this container.
*
* \param self Container to operate upon.
*
* \return Nothing
*/
typedef void (*ao2_container_destroy_fn)(struct ao2_container *self);
@ -92,7 +90,7 @@ typedef void (*ao2_container_destroy_fn)(struct ao2_container *self);
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval empty-container on success.
* \return empty-container on success.
* \retval NULL on error.
*/
typedef struct ao2_container *(*ao2_container_alloc_empty_clone_fn)(struct ao2_container *self, const char *tag, const char *file, int line, const char *func);
@ -107,7 +105,7 @@ typedef struct ao2_container *(*ao2_container_alloc_empty_clone_fn)(struct ao2_c
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval initialized-node on success.
* \return initialized-node on success.
* \retval NULL on error.
*/
typedef struct ao2_container_node *(*ao2_container_new_node_fn)(struct ao2_container *self, void *obj_new, const char *tag, const char *file, int line, const char *func);
@ -130,7 +128,7 @@ typedef enum ao2_container_insert (*ao2_container_insert_fn)(struct ao2_containe
* \param arg Comparison callback arg parameter.
* \param v_state Traversal state to restart container traversal.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
typedef struct ao2_container_node *(*ao2_container_find_first_fn)(struct ao2_container *self, enum search_flags flags, void *arg, void *v_state);
@ -143,7 +141,7 @@ typedef struct ao2_container_node *(*ao2_container_find_first_fn)(struct ao2_con
* \param prev Previous node returned by the traversal search functions.
* The ref ownership is passed back to this function.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
typedef struct ao2_container_node *(*ao2_container_find_next_fn)(struct ao2_container *self, void *v_state, struct ao2_container_node *prev);
@ -152,8 +150,6 @@ typedef struct ao2_container_node *(*ao2_container_find_next_fn)(struct ao2_cont
* \brief Cleanup the container traversal state.
*
* \param v_state Traversal state to cleanup.
*
* \return Nothing
*/
typedef void (*ao2_container_find_cleanup_fn)(void *v_state);
@ -167,7 +163,7 @@ typedef void (*ao2_container_find_cleanup_fn)(void *v_state);
*
* \note The container is already locked.
*
* \retval node on success.
* \return node on success.
* \retval NULL on error or no more nodes in the container.
*/
typedef struct ao2_container_node *(*ao2_iterator_next_fn)(struct ao2_container *self, struct ao2_container_node *prev, enum ao2_iterator_flags flags);
@ -179,8 +175,6 @@ typedef struct ao2_container_node *(*ao2_iterator_next_fn)(struct ao2_container
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
* \param prnt_obj Callback function to print the given object's key. (NULL if not available)
*
* \return Nothing
*/
typedef void (*ao2_container_display)(struct ao2_container *self, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj);
@ -192,8 +186,6 @@ typedef void (*ao2_container_display)(struct ao2_container *self, void *where, a
* \param prnt Print output callback function to use.
*
* \note The container is already locked for reading.
*
* \return Nothing
*/
typedef void (*ao2_container_statistics)(struct ao2_container *self, void *where, ao2_prnt_fn *prnt);
@ -216,8 +208,6 @@ typedef int (*ao2_container_integrity)(struct ao2_container *self);
*
* \param container Container to operate upon.
* \param node Container node linking object to.
*
* \return Nothing
*/
typedef void (*ao2_link_node_stat_fn)(struct ao2_container *container, struct ao2_container_node *node);
@ -228,8 +218,6 @@ typedef void (*ao2_link_node_stat_fn)(struct ao2_container *container, struct ao
*
* \param container Container to operate upon.
* \param node Container node unlinking object from.
*
* \return Nothing
*/
typedef void (*ao2_unlink_node_stat_fn)(struct ao2_container *container, struct ao2_container_node *node);
@ -319,11 +307,10 @@ struct ao2_container {
* \retval 0 on errors.
* \retval 1 on success.
*/
int __container_unlink_node_debug(struct ao2_container_node *node, uint32_t flags,
const char *tag, const char *file, int line, const char *func);
#define __container_unlink_node(node, flags) \
__container_unlink_node_debug(node, flags, NULL, __FILE__, __LINE__, __PRETTY_FUNCTION__)
int __container_unlink_node_debug(struct ao2_container_node *node, uint32_t flags,
const char *tag, const char *file, int line, const char *func);
void container_destruct(void *_c);
int container_init(void);

26
main/astobj2_hash.c
View File

@ -110,7 +110,7 @@ struct hash_traversal_state_check {
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval empty-clone-container on success.
* \return empty-clone-container on success.
* \retval NULL on error.
*/
static struct ao2_container *hash_ao2_alloc_empty_clone(struct ao2_container_hash *self,
@ -139,8 +139,6 @@ static struct ao2_container *hash_ao2_alloc_empty_clone(struct ao2_container_has
*
* \note The container must be locked when the node is
* unreferenced.
*
* \return Nothing
*/
static void hash_ao2_node_destructor(void *v_doomed)
{
@ -202,7 +200,7 @@ static void hash_ao2_node_destructor(void *v_doomed)
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval initialized-node on success.
* \return initialized-node on success.
* \retval NULL on error.
*/
static struct hash_bucket_node *hash_ao2_new_node(struct ao2_container_hash *self, void *obj_new, const char *tag, const char *file, int line, const char *func)
@ -234,7 +232,7 @@ static struct hash_bucket_node *hash_ao2_new_node(struct ao2_container_hash *sel
* \param self Container to operate upon.
* \param node Container node to insert into the container.
*
* \return enum ao2_container_insert value.
* \return \ref ao2_container_insert value.
*/
static enum ao2_container_insert hash_ao2_insert_node(struct ao2_container_hash *self,
struct hash_bucket_node *node)
@ -329,7 +327,7 @@ static enum ao2_container_insert hash_ao2_insert_node(struct ao2_container_hash
* \param arg Comparison callback arg parameter.
* \param state Traversal state to restart hash container traversal.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
static struct hash_bucket_node *hash_ao2_find_first(struct ao2_container_hash *self, enum search_flags flags, void *arg, struct hash_traversal_state *state)
@ -477,7 +475,7 @@ static struct hash_bucket_node *hash_ao2_find_first(struct ao2_container_hash *s
* \param prev Previous node returned by the traversal search functions.
* The ref ownership is passed back to this function.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
static struct hash_bucket_node *hash_ao2_find_next(struct ao2_container_hash *self, struct hash_traversal_state *state, struct hash_bucket_node *prev)
@ -607,7 +605,7 @@ hash_ascending_resume:;
*
* \note The container is already locked.
*
* \retval node on success.
* \return node on success.
* \retval NULL on error or no more nodes in the container.
*/
static struct hash_bucket_node *hash_ao2_iterator_next(struct ao2_container_hash *self, struct hash_bucket_node *node, enum ao2_iterator_flags flags)
@ -690,8 +688,6 @@ static struct hash_bucket_node *hash_ao2_iterator_next(struct ao2_container_hash
*
* \param hash Container to operate upon.
* \param hash_node Container node linking object to.
*
* \return Nothing
*/
static void hash_ao2_link_node_stat(struct ao2_container *hash, struct ao2_container_node *hash_node)
{
@ -714,8 +710,6 @@ static void hash_ao2_link_node_stat(struct ao2_container *hash, struct ao2_conta
*
* \param hash Container to operate upon.
* \param hash_node Container node unlinking object from.
*
* \return Nothing
*/
static void hash_ao2_unlink_node_stat(struct ao2_container *hash, struct ao2_container_node *hash_node)
{
@ -733,8 +727,6 @@ static void hash_ao2_unlink_node_stat(struct ao2_container *hash, struct ao2_con
* \since 12.0.0
*
* \param self Container to operate upon.
*
* \return Nothing
*/
static void hash_ao2_destroy(struct ao2_container_hash *self)
{
@ -760,8 +752,6 @@ static void hash_ao2_destroy(struct ao2_container_hash *self)
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
* \param prnt_obj Callback function to print the given object's key. (NULL if not available)
*
* \return Nothing
*/
static void hash_ao2_dump(struct ao2_container_hash *self, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj)
{
@ -815,8 +805,6 @@ static void hash_ao2_dump(struct ao2_container_hash *self, void *where, ao2_prnt
* \param prnt Print output callback function to use.
*
* \note The container is already locked for reading.
*
* \return Nothing
*/
static void hash_ao2_stats(struct ao2_container_hash *self, void *where, ao2_prnt_fn *prnt)
{
@ -1035,7 +1023,7 @@ static const struct ao2_container_methods v_table_hash = {
* This is basically used when we want to have a container that is
* a simple linked list.
*
* \returns 0
* \retval 0
*/
static int hash_zero(const void *user_obj, const int flags)
{

48
main/astobj2_rbtree.c
View File

@ -168,7 +168,7 @@ static struct rbtree_node *rb_node_most_right(struct rbtree_node *node)
*
* \param node Starting node to find the next node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_next(struct rbtree_node *node)
@ -195,7 +195,7 @@ static struct rbtree_node *rb_node_next(struct rbtree_node *node)
*
* \param node Starting node to find the previous node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_prev(struct rbtree_node *node)
@ -222,7 +222,7 @@ static struct rbtree_node *rb_node_prev(struct rbtree_node *node)
*
* \param node Starting node to find the next node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_pre(struct rbtree_node *node)
@ -258,7 +258,7 @@ static struct rbtree_node *rb_node_pre(struct rbtree_node *node)
*
* \param node Starting node to find the next node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_post(struct rbtree_node *node)
@ -303,7 +303,7 @@ static struct rbtree_node *rb_node_post(struct rbtree_node *node)
*
* \param node Starting node to find the next node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_next_full(struct rbtree_node *node)
@ -323,7 +323,7 @@ static struct rbtree_node *rb_node_next_full(struct rbtree_node *node)
*
* \param node Starting node to find the previous node.
*
* \retval node on success.
* \return node on success.
* \retval NULL if no node.
*/
static struct rbtree_node *rb_node_prev_full(struct rbtree_node *node)
@ -350,7 +350,7 @@ static struct rbtree_node *rb_node_prev_full(struct rbtree_node *node)
* OBJ_SEARCH_PARTIAL_KEY - if set, 'obj_right', is a partial search key item that is not an object.
* \param bias How to bias search direction for duplicates
*
* \return enum empty_node_direction to proceed.
* \return \ref empty_node_direction to proceed.
*/
static enum empty_node_direction rb_find_empty_direction(struct rbtree_node *empty, ao2_sort_fn *sort_fn, void *obj_right, enum search_flags flags, enum equal_node_bias bias)
{
@ -453,8 +453,6 @@ static enum empty_node_direction rb_find_empty_direction(struct rbtree_node *emp
* a,b,c = other nodes that are unaffected by the rotation.
*
* \note It is assumed that the node's right child exists.
*
* \return Nothing
*/
static void rb_rotate_left(struct ao2_container_rbtree *self, struct rbtree_node *node)
{
@ -508,8 +506,6 @@ static void rb_rotate_left(struct ao2_container_rbtree *self, struct rbtree_node
* a,b,c = other nodes that are unaffected by the rotation.
*
* \note It is assumed that the node's left child exists.
*
* \return Nothing
*/
static void rb_rotate_right(struct ao2_container_rbtree *self, struct rbtree_node *node)
{
@ -552,7 +548,7 @@ static void rb_rotate_right(struct ao2_container_rbtree *self, struct rbtree_nod
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval empty-clone-container on success.
* \return empty-clone-container on success.
* \retval NULL on error.
*/
static struct ao2_container *rb_ao2_alloc_empty_clone(struct ao2_container_rbtree *self,
@ -578,8 +574,6 @@ static struct ao2_container *rb_ao2_alloc_empty_clone(struct ao2_container_rbtre
* was no child of the deleted node. Otherwise, the caller must
* pass in the parent node and which child was deleted. In
* addition, the fixup routine would be more complicated.
*
* \return Nothing
*/
static void rb_delete_fixup(struct ao2_container_rbtree *self, struct rbtree_node *child)
{
@ -714,8 +708,6 @@ static void rb_delete_fixup(struct ao2_container_rbtree *self, struct rbtree_nod
*
* \param self Container to operate upon.
* \param doomed Container node to delete from the container.
*
* \return Nothing
*/
static void rb_delete_node(struct ao2_container_rbtree *self, struct rbtree_node *doomed)
{
@ -832,8 +824,6 @@ static void rb_delete_node(struct ao2_container_rbtree *self, struct rbtree_node
*
* \note The container must be locked when the node is
* unreferenced.
*
* \return Nothing
*/
static void rb_ao2_node_destructor(void *v_doomed)
{
@ -898,7 +888,7 @@ static void rb_ao2_node_destructor(void *v_doomed)
* \param line Debug line invoked from
* \param func Debug function name invoked from
*
* \retval initialized-node on success.
* \return initialized-node on success.
* \retval NULL on error.
*/
static struct rbtree_node *rb_ao2_new_node(struct ao2_container_rbtree *self, void *obj_new, const char *tag, const char *file, int line, const char *func)
@ -927,8 +917,6 @@ static struct rbtree_node *rb_ao2_new_node(struct ao2_container_rbtree *self, vo
* \param node Container node just inserted into the container.
*
* \note The just inserted node is red.
*
* \return Nothing
*/
static void rb_insert_fixup(struct ao2_container_rbtree *self, struct rbtree_node *node)
{
@ -1017,7 +1005,7 @@ static void rb_insert_fixup(struct ao2_container_rbtree *self, struct rbtree_nod
* \param self Container to operate upon.
* \param node Container node to insert into the container.
*
* \return enum ao2_container_insert value.
* \return \ref ao2_container_insert value.
*/
static enum ao2_container_insert rb_ao2_insert_node(struct ao2_container_rbtree *self, struct rbtree_node *node)
{
@ -1264,7 +1252,7 @@ static enum ao2_container_insert rb_ao2_insert_node(struct ao2_container_rbtree
* \param prev Previous node returned by the traversal search functions.
* The ref ownership is passed back to this function.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
static struct rbtree_node *rb_ao2_find_next(struct ao2_container_rbtree *self, struct rbtree_traversal_state *state, struct rbtree_node *prev)
@ -1347,7 +1335,7 @@ static struct rbtree_node *rb_ao2_find_next(struct ao2_container_rbtree *self, s
* OBJ_SEARCH_PARTIAL_KEY - if set, 'obj_right', is a partial search key item that is not an object.
* \param bias How to bias search direction for duplicates
*
* \retval node on success.
* \return node on success.
* \retval NULL if not found.
*/
static struct rbtree_node *rb_find_initial(struct ao2_container_rbtree *self, void *obj_right, enum search_flags flags, enum equal_node_bias bias)
@ -1465,7 +1453,7 @@ static struct rbtree_node *rb_find_initial(struct ao2_container_rbtree *self, vo
* \param arg Comparison callback arg parameter.
* \param state Traversal state to restart rbtree container traversal.
*
* \retval node-ptr of found node (Reffed).
* \return node-ptr of found node (Reffed).
* \retval NULL when no node found.
*/
static struct rbtree_node *rb_ao2_find_first(struct ao2_container_rbtree *self, enum search_flags flags, void *arg, struct rbtree_traversal_state *state)
@ -1629,7 +1617,7 @@ static struct rbtree_node *rb_ao2_find_first(struct ao2_container_rbtree *self,
*
* \note The container is already locked.
*
* \retval node on success.
* \return node on success.
* \retval NULL on error or no more nodes in the container.
*/
static struct rbtree_node *rb_ao2_iterator_next(struct ao2_container_rbtree *self, struct rbtree_node *node, enum ao2_iterator_flags flags)
@ -1674,8 +1662,6 @@ static struct rbtree_node *rb_ao2_iterator_next(struct ao2_container_rbtree *sel
* \since 12.0.0
*
* \param self Container to operate upon.
*
* \return Nothing
*/
static void rb_ao2_destroy(struct ao2_container_rbtree *self)
{
@ -1696,8 +1682,6 @@ static void rb_ao2_destroy(struct ao2_container_rbtree *self)
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
* \param prnt_obj Callback function to print the given object's key. (NULL if not available)
*
* \return Nothing
*/
static void rb_ao2_dump(struct ao2_container_rbtree *self, void *where, ao2_prnt_fn *prnt, ao2_prnt_obj_fn *prnt_obj)
{
@ -1737,8 +1721,6 @@ static void rb_ao2_dump(struct ao2_container_rbtree *self, void *where, ao2_prnt
* \param prnt Print output callback function to use.
*
* \note The container is already locked for reading.
*
* \return Nothing
*/
static void rb_ao2_stats(struct ao2_container_rbtree *self, void *where, ao2_prnt_fn *prnt)
{
@ -1776,7 +1758,7 @@ static void rb_ao2_stats(struct ao2_container_rbtree *self, void *where, ao2_prn
*
* \param node Node to check black height.
*
* \retval black-height of node on success.
* \return black-height of node on success.
* \retval -1 on error. Node black height did not balance.
*/
static int rb_check_black_height(struct rbtree_node *node)

93
main/bridge.c
View File

@ -182,8 +182,6 @@ struct ao2_container *ast_bridges(void)
* \since 12.0.0
*
* \param bridge Requesting service.
*
* \return Nothing
*/
static void bridge_manager_service_req(struct ast_bridge *bridge)
{
@ -290,8 +288,6 @@ int ast_bridge_technology_unregister(struct ast_bridge_technology *technology)
*
* \param bridge What to queue the action on.
* \param action What to do.
*
* \return Nothing
*/
static void bridge_queue_action_nodup(struct ast_bridge *bridge, struct ast_frame *action)
{
@ -355,8 +351,6 @@ void bridge_dissolve(struct ast_bridge *bridge, int cause)
* \param bridge_channel Stolen channel causing the check. It is not in the bridge to check and may be in another bridge.
*
* \note On entry, bridge and bridge_channel->bridge are already locked.
*
* \return Nothing
*/
static void bridge_dissolve_check_stolen(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
@ -387,8 +381,6 @@ static void bridge_dissolve_check_stolen(struct ast_bridge *bridge, struct ast_b
* \brief Update connected line information after a bridge has been reconfigured.
*
* \param bridge The bridge itself.
*
* \return Nothing
*/
static void bridge_reconfigured_connected_line_update(struct ast_bridge *bridge)
{
@ -437,8 +429,6 @@ static void bridge_reconfigured_connected_line_update(struct ast_bridge *bridge)
* \param bridge_channel What is joining the bridge technology.
*
* \note On entry, bridge is already locked.
*
* \return Nothing
*/
static void bridge_channel_complete_join(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel)
{
@ -480,8 +470,6 @@ static void bridge_channel_complete_join(struct ast_bridge *bridge, struct ast_b
* \param bridge Check for new channels on this bridge.
*
* \note On entry, bridge is already locked.
*
* \return Nothing
*/
static void bridge_complete_join(struct ast_bridge *bridge)
{
@ -568,8 +556,6 @@ struct tech_deferred_destroy {
* \param action Deferred bridge tech destruction.
*
* \note On entry, bridge must not be locked.
*
* \return Nothing
*/
static void bridge_tech_deferred_destroy(struct ast_bridge *bridge, struct ast_frame *action)
{
@ -597,9 +583,7 @@ static void bridge_tech_deferred_destroy(struct ast_bridge *bridge, struct ast_f
* \param action What to do.
*
* \note On entry, bridge is already locked.
* \note Can be called by the bridge destructor.
*
* \return Nothing
* \note Can be called by the bridge destructor
*/
static void bridge_action_bridge(struct ast_bridge *bridge, struct ast_frame *action)
{
@ -634,8 +618,6 @@ static void bridge_action_bridge(struct ast_bridge *bridge, struct ast_frame *ac
*
* \note On entry, bridge is already locked.
* \note Can be called by the bridge destructor.
*
* \return Nothing
*/
static void bridge_handle_actions(struct ast_bridge *bridge)
{
@ -835,8 +817,6 @@ struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabiliti
* \param self Bridge to operate upon.
*
* \note Stub because of nothing to do.
*
* \return Nothing
*/
static void bridge_base_destroy(struct ast_bridge *self)
{
@ -848,8 +828,6 @@ static void bridge_base_destroy(struct ast_bridge *self)
* \since 12.0.0
*
* \param self Bridge to operate upon.
*
* \return Nothing
*/
static void bridge_base_dissolving(struct ast_bridge *self)
{
@ -885,8 +863,6 @@ static int bridge_base_push(struct ast_bridge *self, struct ast_bridge_channel *
* \param bridge_channel Bridge channel to pull.
*
* \note On entry, self is already locked.
*
* \return Nothing
*/
static void bridge_base_pull(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel)
{
@ -902,8 +878,6 @@ static void bridge_base_pull(struct ast_bridge *self, struct ast_bridge_channel
* \param bridge_channel Bridge channel that was masqueraded.
*
* \note On entry, self is already locked.
*
* \return Nothing
*/
static void bridge_base_notify_masquerade(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel)
{
@ -1197,8 +1171,6 @@ static int smart_bridge_operation(struct ast_bridge *bridge)
* \since 12.0.0
*
* \param bridge_channel What to check.
*
* \return Nothing
*/
static void check_bridge_play_sound(struct ast_bridge_channel *bridge_channel)
{
@ -1227,8 +1199,6 @@ static void check_bridge_play_sound(struct ast_bridge_channel *bridge_channel)
* \param bridge What to operate on.
*
* \note On entry, the bridge is already locked.
*
* \return Nothing
*/
static void check_bridge_play_sounds(struct ast_bridge *bridge)
{
@ -1257,8 +1227,6 @@ void ast_bridge_vars_set(struct ast_channel *chan, const char *name, const char
*
* \note On entry, the bridge is already locked.
* \note The bridge is expected to have exactly two parties.
*
* \return Nothing
*/
static void set_bridge_peer_vars_2party(struct ast_channel *c0, struct ast_channel *c1)
{
@ -1297,8 +1265,6 @@ static void set_bridge_peer_vars_2party(struct ast_channel *c0, struct ast_chann
* \param cur_idx Which index into names[] to skip.
* \param names Channel names to put in the buffer.
* \param num_names Number of names in the array.
*
* \return Nothing
*/
static void fill_bridgepeer_buf(char *buf, unsigned int cur_idx, const char *names[], unsigned int num_names)
{
@ -1336,8 +1302,6 @@ static void fill_bridgepeer_buf(char *buf, unsigned int cur_idx, const char *nam
*
* \note On entry, the bridge is already locked.
* \note The bridge is expected to have more than two parties.
*
* \return Nothing
*/
static void set_bridge_peer_vars_multiparty(struct ast_bridge *bridge)
{
@ -1398,8 +1362,6 @@ static void set_bridge_peer_vars_multiparty(struct ast_bridge *bridge)
* \param bridge What to operate on.
*
* \note On entry, the bridge is already locked.
*
* \return Nothing
*/
static void set_bridge_peer_vars_holding(struct ast_bridge *bridge)
{
@ -1420,8 +1382,6 @@ static void set_bridge_peer_vars_holding(struct ast_bridge *bridge)
* \param bridge What to operate on.
*
* \note On entry, the bridge is already locked.
*
* \return Nothing
*/
static void set_bridge_peer_vars(struct ast_bridge *bridge)
{
@ -1530,8 +1490,6 @@ AST_LIST_HEAD_NOLOCK(bridge_channel_impart_ds_head, bridge_channel_impart_cond);
* \since 13.9.0
*
* \param ds_head List of imparting threads to wake up.
*
* \return Nothing
*/
static void bridge_channel_impart_ds_head_signal(struct bridge_channel_impart_ds_head *ds_head)
{
@ -1561,8 +1519,6 @@ static void bridge_channel_impart_ds_head_dtor(void *doomed)
* \param data Bridge impart datastore data to fixup from old_chan.
* \param old_chan The datastore is moving from this channel.
* \param new_chan The datastore is moving to this channel.
*
* \return Nothing
*/
static void bridge_channel_impart_ds_head_fixup(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan)
{
@ -1641,8 +1597,6 @@ void bridge_channel_impart_signal(struct ast_channel *chan)
* \since 13.9.0
*
* \param cond Imparting conditional to wait for.
*
* \return Nothing
*/
static void bridge_channel_impart_wait(struct bridge_channel_impart_cond *cond)
{
@ -2049,8 +2003,6 @@ int ast_bridge_kick(struct ast_bridge *bridge, struct ast_channel *chan)
*
* \param bridge_channel What is to point to a new bridge.
* \param new_bridge Where the bridge channel should point.
*
* \return Nothing
*/
static void bridge_channel_change_bridge(struct ast_bridge_channel *bridge_channel, struct ast_bridge *new_bridge)
{
@ -2621,7 +2573,7 @@ static int bridge_allows_optimization(struct ast_bridge *bridge)
*
* \note It is assumed that chan is already locked.
*
* \retval bridge on success with bridge and bridge_channel locked.
* \return bridge on success with bridge and bridge_channel locked.
* \retval NULL if cannot do optimization now.
*/
static struct ast_bridge *optimize_lock_chan_stack(struct ast_channel *chan)
@ -2666,7 +2618,7 @@ static struct ast_bridge *optimize_lock_chan_stack(struct ast_channel *chan)
*
* \param peer Other unreal channel in the pair.
*
* \retval bridge on success with bridge, bridge_channel, and peer locked.
* \return bridge on success with bridge, bridge_channel, and peer locked.
* \retval NULL if cannot do optimization now.
*/
static struct ast_bridge *optimize_lock_peer_stack(struct ast_channel *peer)
@ -3036,19 +2988,6 @@ enum ast_bridge_optimization ast_bridges_allow_optimization(struct ast_bridge *c
}
}
/*!
* \internal
* \brief Adjust the bridge merge inhibit request count.
* \since 12.0.0
*
* \param bridge What to operate on.
* \param request Inhibit request increment.
* (Positive to add requests. Negative to remove requests.)
*
* \note This function assumes bridge is locked.
*
* \return Nothing
*/
void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request)
{
int new_request;
@ -3196,8 +3135,6 @@ int ast_bridge_interval_unregister(enum ast_bridge_builtin_interval interval)
* \since 12.0.0
*
* \param vhook Object to destroy.
*
* \return Nothing
*/
static void bridge_hook_destroy(void *vhook)
{
@ -3219,7 +3156,7 @@ static void bridge_hook_destroy(void *vhook)
* \param destructor Optional destructor callback for hook_pvt data
* \param remove_flags Dictates what situations the hook should be removed.
*
* \retval hook on success.
* \return hook on success.
* \retval NULL on error.
*/
static struct ast_bridge_hook *bridge_hook_generic(size_t size,
@ -3524,8 +3461,6 @@ static int hook_remove_match(void *obj, void *arg, int flags)
*
* \param hooks Hooks container to work on.
* \param remove_flags Determinator for whether hook is removed
*
* \return Nothing
*/
static void hooks_remove_container(struct ao2_container *hooks, enum ast_bridge_hook_remove_flags remove_flags)
{
@ -3540,8 +3475,6 @@ static void hooks_remove_container(struct ao2_container *hooks, enum ast_bridge_
*
* \param hooks Hooks heap to work on.
* \param remove_flags Determinator for whether hook is removed
*
* \return Nothing
*/
static void hooks_remove_heap(struct ast_heap *hooks, enum ast_bridge_hook_remove_flags remove_flags)
{
@ -4273,7 +4206,7 @@ static struct ast_channel *get_transferee(struct ao2_container *channels, struct
* \param chan2 Other transferer channel. May or may not be bridged.
* \param bridge1 Bridge that chan1 is in. Guaranteed to be non-NULL.
* \param bridge2 Bridge that chan2 is in. If NULL, then chan2 is not bridged.
* \param publication Data to publish for a stasis attended transfer message.
* \param transfer_msg Data to publish for a stasis attended transfer message.
* \retval AST_BRIDGE_TRANSFER_FAIL Internal error occurred
* \retval AST_BRIDGE_TRANSFER_SUCCESS Succesfully transferred the bridge
*/
@ -4613,7 +4546,7 @@ publish:
* \note dest_bridge and source_bridge_channel's bridge MUST be locked before calling this function.
*
* \param dest_bridge The final bridge for the attended transfer
* \param source_channel Channel who is bridged to the channel that will move
* \param source_bridge_channel Channel who is bridged to the channel that will move
* \param swap_channel Channel to be swapped out of the dest_bridge
* \return The success or failure of the swap attempt
*/
@ -4657,7 +4590,7 @@ static enum ast_transfer_result bridge_swap_attended_transfer(struct ast_bridge
* \param to_target_bridge_channel to_transfer_target's bridge_channel
* \param to_transferee_bridge The bridge between to_transferee and the transferee
* \param to_target_bridge The bridge between to_transfer_target and the transfer_target
* \param publication Data to publish for a stasis attended transfer message
* \param transfer_msg Data to publish for a stasis attended transfer message
* \return The success or failure of the attended transfer
*/
static enum ast_transfer_result two_bridge_attended_transfer(struct ast_channel *to_transferee,
@ -4917,8 +4850,6 @@ end:
* \since 12.0.0
*
* \param bridge requesting service.
*
* \return Nothing
*/
static void bridge_manager_service(struct ast_bridge *bridge)
{
@ -4936,8 +4867,6 @@ static void bridge_manager_service(struct ast_bridge *bridge)
* \internal
* \brief Bridge manager service thread.
* \since 12.0.0
*
* \return Nothing
*/
static void *bridge_manager_thread(void *data)
{
@ -4971,8 +4900,6 @@ static void *bridge_manager_thread(void *data)
* \since 12.0.0
*
* \param obj Bridge manager to destroy.
*
* \return Nothing
*/
static void bridge_manager_destroy(void *obj)
{
@ -5003,7 +4930,7 @@ static void bridge_manager_destroy(void *obj)
* \brief Create the bridge manager controller.
* \since 12.0.0
*
* \retval manager on success.
* \return manager on success.
* \retval NULL on error.
*/
static struct bridge_manager_controller *bridge_manager_create(void)
@ -5567,8 +5494,6 @@ static int manager_bridge_tech_list(struct mansession *s, const struct message *
* \param v_obj A pointer to the object we want the key printed.
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
*
* \return Nothing
*/
static void bridge_prnt_obj(void *v_obj, void *where, ao2_prnt_fn *prnt)
{
@ -5585,8 +5510,6 @@ static void bridge_prnt_obj(void *v_obj, void *where, ao2_prnt_fn *prnt)
* \internal
* \brief Shutdown the bridging system. Stuff to do on graceful shutdown.
* \since 13.3.0
*
* \return Nothing
*/
static void bridge_cleanup(void)
{

20
main/bridge_after.c
View File

@ -61,8 +61,6 @@ struct after_bridge_cb_ds {
* \since 12.0.0
*
* \param node After bridge callback node.
*
* \return Nothing
*/
static void after_bridge_cb_failed(struct after_bridge_cb_node *node)
{
@ -79,8 +77,6 @@ static void after_bridge_cb_failed(struct after_bridge_cb_node *node)
*
* \param after_bridge After bridge callback container process.
* \param reason Why are we doing this.
*
* \return Nothing
*/
static void after_bridge_cb_run_discard(struct after_bridge_cb_ds *after_bridge, enum ast_bridge_after_cb_reason reason)
{
@ -107,8 +103,6 @@ static void after_bridge_cb_run_discard(struct after_bridge_cb_ds *after_bridge,
* \since 12.0.0
*
* \param data After bridge callback data to destroy.
*
* \return Nothing
*/
static void after_bridge_cb_destroy(void *data)
{
@ -130,8 +124,6 @@ static struct after_bridge_cb_ds *after_bridge_cb_find(struct ast_channel *chan)
* \param data After bridge callback data to fixup.
* \param old_chan The datastore is moving from this channel.
* \param new_chan The datastore is moving to this channel.
*
* \return Nothing
*/
static void after_bridge_cb_fixup(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan)
{
@ -164,7 +156,7 @@ static const struct ast_datastore_info after_bridge_cb_info = {
*
* \param chan Channel to find the after bridge callback container on.
*
* \retval after_bridge datastore container on success.
* \return after_bridge datastore container on success.
* \retval NULL on error.
*/
static struct after_bridge_cb_ds *after_bridge_cb_find(struct ast_channel *chan)
@ -186,7 +178,7 @@ static struct after_bridge_cb_ds *after_bridge_cb_find(struct ast_channel *chan)
*
* \param chan Channel to setup/create the after bridge callback container on.
*
* \retval after_bridge datastore container on success.
* \return after_bridge datastore container on success.
* \retval NULL on error.
*/
static struct after_bridge_cb_ds *after_bridge_cb_setup(struct ast_channel *chan)
@ -333,8 +325,6 @@ struct after_bridge_goto_ds {
* \since 12.0.0
*
* \param data After bridge goto data to destroy.
*
* \return Nothing
*/
static void after_bridge_goto_destroy(void *data)
{
@ -354,8 +344,6 @@ static void after_bridge_goto_destroy(void *data)
* \param data After bridge goto data to fixup.
* \param old_chan The datastore is moving from this channel.
* \param new_chan The datastore is moving to this channel.
*
* \return Nothing
*/
static void after_bridge_goto_fixup(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan)
{
@ -376,7 +364,7 @@ static const struct ast_datastore_info after_bridge_goto_info = {
*
* \param chan Channel to remove after bridge goto location.
*
* \retval datastore on success.
* \return datastore on success.
* \retval NULL on error or not found.
*/
static struct ast_datastore *after_bridge_goto_remove(struct ast_channel *chan)
@ -565,8 +553,6 @@ void ast_bridge_run_after_goto(struct ast_channel *chan)
* Else if parseable_goto then use the given context/exten/priority
* as the relative position for the parseable_goto.
* Else goto the given context/exten/priority+1.
*
* \return Nothing
*/
static void __after_bridge_set_goto(struct ast_channel *chan, int run_h_exten, int specific, const char *context, const char *exten, int priority, const char *parseable_goto)
{

6
main/bridge_basic.c
View File

@ -72,7 +72,7 @@ enum bridge_basic_personality_type {
*
* \param bridge The bridge
* \param type The personality to change the bridge to
* \user_data Private data to attach to the personality.
* \param user_data Private data to attach to the personality.
*/
static void bridge_basic_change_personality(struct ast_bridge *bridge,
enum bridge_basic_personality_type type, void *user_data);
@ -331,7 +331,7 @@ struct bridge_basic_personality {
struct personality_details details[BRIDGE_BASIC_PERSONALITY_END];
};
/*
/*!
* \internal
* \brief Get the extension for a given builtin feature.
*
@ -2427,8 +2427,6 @@ static void recall_callback(struct ast_dial *dial)
*
* \pre COLP and CLID on the recall channel are setup by the caller but not
* explicitly published yet.
*
* \return Nothing
*/
static void common_recall_channel_setup(struct ast_channel *recall, struct ast_channel *transferer)
{

16
main/bridge_channel.c
View File

@ -826,14 +826,6 @@ void bridge_channel_queue_deferred_frames(struct ast_bridge_channel *bridge_chan
ast_bridge_channel_unlock(bridge_channel);
}
/*!
* \internal
* \brief Suspend a channel from a bridge.
*
* \param bridge_channel Channel to suspend.
*
* \note This function assumes bridge_channel->bridge is locked.
*/
void bridge_channel_internal_suspend_nolock(struct ast_bridge_channel *bridge_channel)
{
bridge_channel->suspended = 1;
@ -860,14 +852,6 @@ static void bridge_channel_suspend(struct ast_bridge_channel *bridge_channel)
ast_bridge_unlock(bridge_channel->bridge);
}
/*!
* \internal
* \brief Unsuspend a channel from a bridge.
*
* \param bridge_channel Channel to unsuspend.
*
* \note This function assumes bridge_channel->bridge is locked.
*/
void bridge_channel_internal_unsuspend_nolock(struct ast_bridge_channel *bridge_channel)
{
bridge_channel->suspended = 0;

16
main/bridge_roles.c
View File

@ -65,8 +65,6 @@ struct bridge_roles_datastore {
* \since 12.0.0
*
* \param role bridge_role being destroyed
*
* \return Nothing
*/
static void bridge_role_destroy(struct bridge_role *role)
{
@ -84,8 +82,6 @@ static void bridge_role_destroy(struct bridge_role *role)
* \since 12.0.0
*
* \param data Pointer to the datastore being destroyed
*
* \return Nothing
*/
static void bridge_role_datastore_destroy(void *data)
{
@ -112,7 +108,7 @@ static const struct ast_datastore_info bridge_role_info = {
* \param chan Chan the datastore is being setup on
*
* \retval NULL if failed
* \retval pointer to the newly created datastore
* \return pointer to the newly created datastore
*/
static struct bridge_roles_datastore *setup_bridge_roles_datastore(struct ast_channel *chan)
{
@ -143,7 +139,7 @@ static struct bridge_roles_datastore *setup_bridge_roles_datastore(struct ast_ch
* \param chan Channel we want the bridge_roles_datastore from
*
* \retval NULL if we can't find the datastore
* \retval pointer to the bridge_roles_datastore
* \return pointer to the bridge_roles_datastore
*/
static struct bridge_roles_datastore *fetch_bridge_roles_datastore(struct ast_channel *chan)
{
@ -167,7 +163,7 @@ static struct bridge_roles_datastore *fetch_bridge_roles_datastore(struct ast_ch
* \param chan Channel we want the bridge_roles_datastore from
*
* \retval NULL If we can't find and can't create the datastore
* \retval pointer to the bridge_roles_datastore
* \return pointer to the bridge_roles_datastore
*/
static struct bridge_roles_datastore *fetch_or_create_bridge_roles_datastore(struct ast_channel *chan)
{
@ -192,7 +188,7 @@ static struct bridge_roles_datastore *fetch_or_create_bridge_roles_datastore(str
* \param role_name Name of the role being sought
*
* \retval NULL if the datastore does not have the requested role
* \retval pointer to the requested role
* \return pointer to the requested role
*/
static struct bridge_role *get_role_from_datastore(struct bridge_roles_datastore *roles_datastore, const char *role_name)
{
@ -216,7 +212,7 @@ static struct bridge_role *get_role_from_datastore(struct bridge_roles_datastore
* \param role_name Name of the role sought
*
* \retval NULL if the channel's datastore does not have the requested role
* \retval pointer to the requested role
* \return pointer to the requested role
*/
static struct bridge_role *get_role_from_channel(struct ast_channel *channel, const char *role_name)
{
@ -233,7 +229,7 @@ static struct bridge_role *get_role_from_channel(struct ast_channel *channel, co
* \param option Name of the option sought
*
* \retval NULL if the bridge role doesn't have the requested option
* \retval pointer to the requested option
* \return pointer to the requested option
*/
static struct bridge_role_option *get_role_option(struct bridge_role *role, const char *option)
{

10
main/ccss.c
View File

@ -372,6 +372,7 @@ static int __attribute__((format(printf, 3, 0))) cc_request_state_change(enum cc
* \param called_tree A reference to the tree of called devices. The agent
* will gain a reference to this tree as well
* \param core_id The core_id that this core_instance will assume
* \param cc_data
* \retval NULL Failed to create the core instance either due to memory allocation
* errors or due to the agent count for the caller being too high
* \retval non-NULL A reference to the newly created cc_core_instance
@ -1308,7 +1309,7 @@ static const struct ast_cc_agent_callbacks *find_agent_callbacks(struct ast_chan
*
* \param state Device state to test.
*
* \return TRUE if the given device state is considered available by generic CCSS.
* \retval TRUE if the given device state is considered available by generic CCSS.
*/
static int cc_generic_is_device_available(enum ast_device_state state)
{
@ -2210,8 +2211,6 @@ static int cc_interfaces_datastore_init(struct ast_channel *chan) {
* has been properly allocated and had its callbacks assigned to it. If one of these
* failures should occur, then we still need to let the channel driver know that it
* must destroy the data that it allocated.
*
* \return Nothing
*/
static void call_destructor_with_no_monitor(const char * const monitor_type, void *private_data)
{
@ -2243,7 +2242,8 @@ static void call_destructor_with_no_monitor(const char * const monitor_type, voi
*
* \param device_name The name of the device being added to the tree
* \param dialstring The dialstring used to dial the device being added
* \param parent_id The parent of this new tree node.
* \param core_id
* \param cc_data
* \retval NULL Memory allocation failure
* \retval non-NULL The new ast_cc_interface created.
*/
@ -3553,7 +3553,6 @@ struct ast_cc_monitor *ast_cc_get_monitor_by_recall_core_id(const int core_id, c
*
* \param str An ast_str holding what we will add to CC_INTERFACES
* \param dialstring A new dialstring to add
* \retval void
*/
static void cc_unique_append(struct ast_str **str, const char *dialstring)
{
@ -3583,7 +3582,6 @@ static void cc_unique_append(struct ast_str **str, const char *dialstring)
* \param starting_point The extension monitor that is the parent to all
* monitors whose dialstrings should be added to CC_INTERFACES
* \param str Where we will store CC_INTERFACES
* \retval void
*/
static void build_cc_interfaces_chanvar(struct ast_cc_monitor *starting_point, struct ast_str **str)
{

47
main/cdr.c
View File

@ -387,7 +387,7 @@ STASIS_MESSAGE_TYPE_DEFN_LOCAL(cdr_sync_message_type);
struct cdr_object;
/*! \brief Return types for \ref process_bridge_enter functions */
/*! \brief Return types for \p process_bridge_enter functions */
enum process_bridge_enter_results {
/*!
* The CDR was the only party in the bridge.
@ -497,7 +497,7 @@ struct cdr_object_fn_table {
* \param bridge The bridge that the Party A just entered into
* \param channel The \ref ast_channel_snapshot for this CDR's Party A
*
* \retval process_bridge_enter_results Defines whether or not this CDR was able
* \return process_bridge_enter_results Defines whether or not this CDR was able
* to fully handle the bridge enter message.
*/
enum process_bridge_enter_results (* const process_bridge_enter)(
@ -741,7 +741,7 @@ struct cdr_object {
* \brief Copy variables from one list to another
* \param to_list destination
* \param from_list source
* \retval The number of copied variables
* \return The number of copied variables
*/
static int copy_variables(struct varshead *to_list, struct varshead *from_list)
{
@ -800,6 +800,7 @@ static void cdr_object_snapshot_copy(struct cdr_object_snapshot *dst, struct cdr
* \brief Transition a \ref cdr_object to a new state with initiation flag
* \param cdr The \ref cdr_object to transition
* \param fn_table The \ref cdr_object_fn_table state to go to
* \param do_init
*/
static void cdr_object_transition_state_init(struct cdr_object *cdr, struct cdr_object_fn_table *fn_table, int do_init)
{
@ -943,8 +944,6 @@ static int cdr_all_cmp_fn(void *obj, void *arg, int flags)
* \internal
* \brief Relink the CDR because Party B's snapshot changed.
* \since 13.19.0
*
* \return Nothing
*/
static void cdr_all_relink(struct cdr_object *cdr)
{
@ -966,8 +965,6 @@ static void cdr_all_relink(struct cdr_object *cdr)
* \internal
* \brief Unlink the master CDR and chained records from the active_cdrs_all container.
* \since 13.19.0
*
* \return Nothing
*/
static void cdr_all_unlink(struct cdr_object *cdr)
{
@ -1032,6 +1029,7 @@ static void cdr_object_dtor(void *obj)
/*!
* \brief \ref cdr_object constructor
* \param chan The \ref ast_channel_snapshot that is the CDR's Party A
* \param event_time
*
* This implicitly sets the state of the newly created CDR to the Single state
* (\ref single_state_fn_table)
@ -1071,6 +1069,7 @@ static struct cdr_object *cdr_object_alloc(struct ast_channel_snapshot *chan, co
/*!
* \brief Create a new \ref cdr_object and append it to an existing chain
* \param cdr The \ref cdr_object to append to
* \param event_time
*/
static struct cdr_object *cdr_object_create_and_append(struct cdr_object *cdr, const struct timeval *event_time)
{
@ -1121,8 +1120,6 @@ static struct cdr_object *cdr_object_create_and_append(struct cdr_object *cdr, c
*
* \retval 0 if the CDR flag is not configured.
* \retval non-zero if the CDR flag is configured.
*
* \return Nothing
*/
static int is_cdr_flag_set(unsigned int cdr_flag)
{
@ -1187,7 +1184,7 @@ static int snapshot_is_dialed(struct ast_channel_snapshot *snapshot)
* resulting CDR
* \param left One of the snapshots
* \param right The other snapshot
* \retval The snapshot that won
* \return The snapshot that won
*/
static struct cdr_object_snapshot *cdr_object_pick_party_a(struct cdr_object_snapshot *left, struct cdr_object_snapshot *right)
{
@ -1281,7 +1278,7 @@ static void set_variable(struct varshead *headp, const char *name, const char *v
* \brief Create a chain of \ref ast_cdr objects from a chain of \ref cdr_object
* suitable for consumption by the registered CDR backends
* \param cdr The \ref cdr_object to convert to a public record
* \retval A chain of \ref ast_cdr objects on success
* \return A chain of \ref ast_cdr objects on success
* \retval NULL on failure
*/
static struct ast_cdr *cdr_object_create_public_records(struct cdr_object *cdr)
@ -1431,11 +1428,11 @@ static void cdr_object_set_disposition(struct cdr_object *cdr, int hangupcause)
*
* This function is safe to call multiple times. Note that you can call this
* explicitly before going to the finalized state if there's a chance the CDR
* will be re-activated, in which case the \ref cdr_object's end time should be
* will be re-activated, in which case the \p cdr's end time should be
* cleared. This function is implicitly called when a CDR transitions to the
* finalized state and right before it is dispatched
*
* \param cdr_object The CDR to finalize
* \param cdr The CDR to finalize
*/
static void cdr_object_finalize(struct cdr_object *cdr)
{
@ -1502,7 +1499,7 @@ static void cdr_object_check_party_a_answer(struct cdr_object *cdr)
}
}
/* \brief Set Caller ID information on a CDR */
/*! \brief Set Caller ID information on a CDR */
static void cdr_object_update_cid(struct cdr_object_snapshot *old_snapshot, struct ast_channel_snapshot *new_snapshot)
{
if (!old_snapshot->snapshot) {
@ -2099,7 +2096,6 @@ static int dial_status_end(const char *dialstatus)
* \brief Handler for Stasis-Core dial messages
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message The message
*/
static void handle_dial_message(void *data, struct stasis_subscription *sub, struct stasis_message *message)
@ -2272,7 +2268,6 @@ static int check_new_cdr_needed(struct ast_channel_snapshot *old_snapshot,
* \brief Handler for channel snapshot update messages
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message The message
*/
static void handle_channel_snapshot_update_message(void *data, struct stasis_subscription *sub, struct stasis_message *message)
@ -2398,7 +2393,6 @@ static int filter_bridge_messages(struct ast_bridge_snapshot *bridge)
* \brief Handler for when a channel leaves a bridge
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message The message - hopefully a bridge one!
*/
static void handle_bridge_leave_message(void *data, struct stasis_subscription *sub,
@ -2489,15 +2483,15 @@ static void bridge_candidate_add_to_cdr(struct cdr_object *cdr,
}
/*!
* \brief Process a single \ref bridge_candidate
* \brief Process a single \c bridge_candidate
*
* When a CDR enters a bridge, it needs to make pairings with everyone else
* that it is not currently paired with. This function determines, for the
* CDR for the channel that entered the bridge and the CDR for every other
* channel currently in the bridge, who is Party A and makes new CDRs.
*
* \param cdr The \ref cdr_obj being processed
* \param cand_cdr The \ref cdr_object that is a candidate
* \param cdr The \ref cdr_object being processed
* \param base_cand_cdr The \ref cdr_object that is a candidate
*
*/
static void bridge_candidate_process(struct cdr_object *cdr, struct cdr_object *base_cand_cdr)
@ -2582,6 +2576,7 @@ static void handle_bridge_pairings(struct cdr_object *cdr, struct ast_bridge_sna
* \param cdr The CDR to operate on
* \param bridge The bridge the channel just entered
* \param channel The channel snapshot
* \param event_time
*/
static void handle_parking_bridge_enter_message(struct cdr_object *cdr,
struct ast_bridge_snapshot *bridge,
@ -2623,6 +2618,7 @@ static void handle_parking_bridge_enter_message(struct cdr_object *cdr,
* \param cdr The CDR to operate on
* \param bridge The bridge the channel just entered
* \param channel The channel snapshot
* \param event_time
*/
static void handle_standard_bridge_enter_message(struct cdr_object *cdr,
struct ast_bridge_snapshot *bridge,
@ -2702,7 +2698,6 @@ try_again:
* \brief Handler for Stasis-Core bridge enter messages
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message The message - hopefully a bridge one!
*/
static void handle_bridge_enter_message(void *data, struct stasis_subscription *sub,
@ -2745,7 +2740,6 @@ static void handle_bridge_enter_message(void *data, struct stasis_subscription *
* \brief Handler for when a channel is parked
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message The message about who got parked
* */
static void handle_parked_call_message(void *data, struct stasis_subscription *sub,
@ -2814,7 +2808,6 @@ static void handle_parked_call_message(void *data, struct stasis_subscription *s
* \brief Handler for a synchronization message
* \param data Passed on
* \param sub The stasis subscription for this message callback
* \param topic The topic this message was published for
* \param message A blank ao2 object
* */
static void handle_cdr_sync_message(void *data, struct stasis_subscription *sub,
@ -3306,7 +3299,7 @@ static int cdr_object_format_property(struct cdr_object *cdr_obj, const char *na
* \brief Look up and retrieve a CDR object by channel name
* \param name The name of the channel
* \retval NULL on error
* \retval The \ref cdr_object for the channel on success, with the reference
* \return The \ref cdr_object for the channel on success, with the reference
* count bumped by one.
*/
static struct cdr_object *cdr_object_get_by_name(const char *name)
@ -4254,7 +4247,7 @@ static struct ast_cli_entry cli_commands[] = {
};
/*!
* \brief This dispatches *all* \ref cdr_objects. It should only be used during
* \brief This dispatches *all* \ref cdr_object. It should only be used during
* shutdown, so that we get billing records for everything that we can.
*/
static int cdr_object_dispatch_all_cb(void *obj, void *arg, int flags)
@ -4439,8 +4432,6 @@ static void cdr_enable_batch_mode(struct ast_cdr_config *config)
* \param v_obj A pointer to the object we want printed.
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
*
* \return Nothing
*/
static void cdr_master_print_fn(void *v_obj, void *where, ao2_prnt_fn *prnt)
{
@ -4466,8 +4457,6 @@ static void cdr_master_print_fn(void *v_obj, void *where, ao2_prnt_fn *prnt)
* \param v_obj A pointer to the object we want printed.
* \param where User data needed by prnt to determine where to put output.
* \param prnt Print output callback function to use.
*
* \return Nothing
*/
static void cdr_all_print_fn(void *v_obj, void *where, ao2_prnt_fn *prnt)
{

2
main/cel.c
View File

@ -972,7 +972,7 @@ static void cel_channel_app_change(
}
}
/* \brief Handlers for channel snapshot changes.
/*! \brief Handlers for channel snapshot changes.
* \note Order of the handlers matters. Application changes must come before state
* changes to ensure that hangup notifications occur after application changes.
* Linkedid checking should always come last.

4
main/channel_internal_api.c
View File

@ -1310,14 +1310,14 @@ void ast_channel_dialed_causes_clear(const struct ast_channel *chan)
ao2_callback(chan->dialed_causes, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, NULL, NULL);
}
/* \brief Hash function for pvt cause code frames */
/*! \brief Hash function for pvt cause code frames */
static int pvt_cause_hash_fn(const void *vpc, const int flags)
{
const struct ast_control_pvt_cause_code *pc = vpc;
return ast_str_hash(ast_tech_to_upper(ast_strdupa(pc->chan_name)));
}
/* \brief Comparison function for pvt cause code frames */
/*! \brief Comparison function for pvt cause code frames */
static int pvt_cause_cmp_fn(void *obj, void *vstr, int flags)
{
struct ast_control_pvt_cause_code *pc = obj;

28
main/config.c
View File

@ -318,8 +318,6 @@ struct ast_variable *_ast_variable_new(const char *name, const char *value, cons
*
* \param dst_var Destination variable node
* \param src_var Source variable node
*
* \return Nothing
*/
static void ast_variable_move(struct ast_variable *dst_var, struct ast_variable *src_var)
{
@ -588,13 +586,13 @@ struct ast_variable *ast_variables_reverse(struct ast_variable *var)
return var1;
}
void ast_variables_destroy(struct ast_variable *v)
void ast_variables_destroy(struct ast_variable *var)
{
struct ast_variable *vn;
while (v) {
vn = v;
v = v->next;
while (var) {
vn = var;
var = var->next;
ast_variable_destroy(vn);
}
}
@ -1286,14 +1284,14 @@ void ast_config_sort_categories(struct ast_config *config, int descending,
}
char *ast_category_browse(struct ast_config *config, const char *prev)
char *ast_category_browse(struct ast_config *config, const char *prev_name)
{
struct ast_category *cat;
if (!prev) {
if (!prev_name) {
/* First time browse. */
cat = config->root;
} else if (config->last_browse && (config->last_browse->name == prev)) {
} else if (config->last_browse && (config->last_browse->name == prev_name)) {
/* Simple last browse found. */
cat = config->last_browse->next;
} else {
@ -1304,7 +1302,7 @@ char *ast_category_browse(struct ast_config *config, const char *prev)
* previous category?)
*/
for (cat = config->root; cat; cat = cat->next) {
if (cat->name == prev) {
if (cat->name == prev_name) {
/* Found it. */
cat = cat->next;
break;
@ -1316,7 +1314,7 @@ char *ast_category_browse(struct ast_config *config, const char *prev)
* re-added?)
*/
for (cat = config->root; cat; cat = cat->next) {
if (!strcasecmp(cat->name, prev)) {
if (!strcasecmp(cat->name, prev_name)) {
/* Found it. */
cat = cat->next;
break;
@ -1588,8 +1586,6 @@ enum config_cache_attribute_enum {
*
* \param cfmtime Cached file modtime.
* \param statbuf Buffer filled in by stat().
*
* \return Nothing
*/
static void cfmstat_save(struct cache_file_mtime *cfmtime, struct stat *statbuf)
{
@ -1633,8 +1629,6 @@ static int cfmstat_cmp(struct cache_file_mtime *cfmtime, struct stat *statbuf)
* \param cfmtime Cached file modtime.
*
* \note cfmtime_head is assumed already locked.
*
* \return Nothing
*/
static void config_cache_flush_includes(struct cache_file_mtime *cfmtime)
{
@ -1652,8 +1646,6 @@ static void config_cache_flush_includes(struct cache_file_mtime *cfmtime)
* \param cfmtime Cached file modtime.
*
* \note cfmtime_head is assumed already locked.
*
* \return Nothing
*/
static void config_cache_destroy_entry(struct cache_file_mtime *cfmtime)
{
@ -1667,8 +1659,6 @@ static void config_cache_destroy_entry(struct cache_file_mtime *cfmtime)
*
* \param filename Config filename.
* \param who_asked Which module asked.
*
* \return Nothing
*/
static void config_cache_remove(const char *filename, const char *who_asked)
{

10
main/core_local.c
View File

@ -386,7 +386,7 @@ static struct ast_multi_channel_blob *local_channel_optimization_blob(struct loc
return payload;
}
/*! \brief Callback for \ref ast_unreal_pvt_callbacks \ref optimization_started_cb */
/*! \brief Callback for \ref ast_unreal_pvt_callbacks \p optimization_started */
static void local_optimization_started_cb(struct ast_unreal_pvt *base, struct ast_channel *source,
enum ast_unreal_channel_indicator dest, unsigned int id)
{
@ -429,7 +429,7 @@ static void local_optimization_started_cb(struct ast_unreal_pvt *base, struct as
stasis_publish(ast_channel_topic(p->base.owner), msg);
}
/*! \brief Callback for \ref ast_unreal_pvt_callbacks \ref optimization_finished_cb */
/*! \brief Callback for \ref ast_unreal_pvt_callbacks \p optimization_finished */
static void local_optimization_finished_cb(struct ast_unreal_pvt *base, int success, unsigned int id)
{
RAII_VAR(struct ast_json *, json_object, ast_json_null(), ast_json_unref);
@ -534,8 +534,6 @@ static struct ast_manager_event_blob *local_message_to_ami(struct stasis_message
* \since 12.0.0
*
* \param p local_pvt to raise the local bridge message
*
* \return Nothing
*/
static void publish_local_bridge_message(struct local_pvt *p)
{
@ -840,8 +838,6 @@ static int local_hangup(struct ast_channel *ast)
* \brief struct local_pvt destructor.
*
* \param vdoomed Object to destroy.
*
* \return Nothing
*/
static void local_pvt_destructor(void *vdoomed)
{
@ -1116,8 +1112,6 @@ static int locals_cmp_cb(void *obj, void *arg, int flags)
* \internal
* \brief Shutdown the local proxy channel.
* \since 12.0.0
*
* \return Nothing
*/
static void local_shutdown(void)
{

2
main/crypt.c
View File

@ -65,7 +65,7 @@ static char gen_salt_char(void)
* \param[out] current_salt Output string in which to generate the salt.
* This can be an empty string, or the results of a
* prior gen_salt call.
* \param max_len Length of \a current_salt.
* \param maxlen Length of \a current_salt.
* \return 0 on success.
* \return Non-zero on error.
*/

4
main/devicestate.c
View File

@ -99,7 +99,7 @@
* and reported back.
*
* - Extension states
* \arg \ref AstENUM ast_extension_states
* \arg \ref ast_extension_states "AstENUM"
* \arg \ref pbx.c
* \arg \ref pbx.h
* - Structures
@ -781,8 +781,6 @@ static const char *device_state_get_id(struct stasis_message *message)
*
* \param cache_topic Caching topic the aggregate message may be published over.
* \param aggregate The aggregate shapshot message to publish.
*
* \return Nothing
*/
static void device_state_aggregate_publish(struct stasis_topic *cache_topic, struct stasis_message *aggregate)
{

40
main/dial.c
View File

@ -1083,11 +1083,6 @@ void ast_dial_hangup(struct ast_dial *dial)
return;
}
/*! \brief Destroys a dialing structure
* \note Destroys (free's) the given ast_dial structure
* \param dial Dialing structure to free
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_destroy(struct ast_dial *dial)
{
int i = 0;
@ -1142,12 +1137,6 @@ int ast_dial_destroy(struct ast_dial *dial)
return 0;
}
/*! \brief Enables an option globally
* \param dial Dial structure to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data)
{
/* If the option is already enabled, return failure */
@ -1184,13 +1173,6 @@ static struct ast_dial_channel *find_dial_channel(struct ast_dial *dial, int num
return channel;
}
/*! \brief Enables an option per channel
* \param dial Dial structure
* \param num Channel number to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data)
{
struct ast_dial_channel *channel = NULL;
@ -1215,11 +1197,6 @@ int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option
return 0;
}
/*! \brief Disables an option globally
* \param dial Dial structure to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option)
{
/* If the option is not enabled, return failure */
@ -1237,12 +1214,6 @@ int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option o
return 0;
}
/*! \brief Disables an option per channel
* \param dial Dial structure
* \param num Channel number to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option)
{
struct ast_dial_channel *channel = NULL;
@ -1305,11 +1276,6 @@ void *ast_dial_get_user_data(struct ast_dial *dial)
return dial->user_data;
}
/*! \brief Set the maximum time (globally) allowed for trying to ring phones
* \param dial The dial structure to apply the time limit to
* \param timeout Maximum time allowed
* \return nothing
*/
void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout)
{
dial->timeout = timeout;
@ -1320,12 +1286,6 @@ void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout)
return;
}
/*! \brief Set the maximum time (per channel) allowed for trying to ring the phone
* \param dial The dial structure the channel belongs to
* \param num Channel number to set timeout on
* \param timeout Maximum time allowed
* \return nothing
*/
void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout)
{
struct ast_dial_channel *channel = NULL;

10
main/dns.c
View File

@ -173,7 +173,7 @@ struct dn_answer {
* \param s A char pointer to the current frame in the DNS response.
* \param len The remaining available length of the DNS response.
*
* \retval The position of the next field
* \return The position of the next field
* \retval -1 if there are no remaining fields
*/
static int skip_name(unsigned char *s, int len)
@ -217,7 +217,7 @@ static int skip_name(unsigned char *s, int len)
* \param field_size A positive value representing the size of the current field
pointed to by the dns_response parameter.
*
* \retval The remaining length in the DNS response
* \return The remaining length in the DNS response
* \retval -1 there are no frames remaining in the DNS response
*/
static int dns_advance_field(unsigned char **dns_response, int remaining_len, int field_size)
@ -244,7 +244,7 @@ static int dns_advance_field(unsigned char **dns_response, int remaining_len, in
* \param dns_response The full DNS response.
* \param dns_response_len The length of the full DNS response.
*
* \retval The length of the DNS response
* \return The length of the DNS response
* \retval -1 on search failure
*/
static int dns_search_res(const char *dname, int rr_class, int rr_type,
@ -281,7 +281,7 @@ static int dns_search_res(const char *dname, int rr_class, int rr_type,
* \param dns_response The full DNS response.
* \param dns_response_len The length of the full DNS response.
*
* \retval The length of the DNS response
* \return The length of the DNS response
* \retval -1 on search failure
*/
static int dns_search_res(const char *dname, int rr_class, int rr_type,
@ -316,7 +316,6 @@ static int dns_search_res(const char *dname, int rr_class, int rr_type,
* \internal
*
* \param context Void pointer containing data to use in the callback functions.
* \param dname Domain name to lookup (host, SRV domain, TXT record name).
* \param class Record Class (see "man res_search").
* \param type Record type (see "man res_search").
* \param answer The full DNS response.
@ -394,7 +393,6 @@ static int dns_parse_answer(void *context,
* \internal
*
* \param context Void pointer containing data to use in the callback functions.
* \param dname Domain name to lookup (host, SRV domain, TXT record name).
* \param rr_class Record Class (see "man res_search").
* \param rr_type Record type (see "man res_search").
* \param answer The full DNS response.

2
main/dns_naptr.c
View File

@ -60,7 +60,7 @@ enum flags_result {
* \note The flags string passed into this function is NOT NULL-terminated
*
* \param flags The flags string from a NAPTR record
* \flags_size The size of the flags string in bytes
* \param flags_size The size of the flags string in bytes
* \return flag result
*/
static enum flags_result interpret_flags(const char *flags, uint8_t flags_size)

9
main/dns_system_resolver.c
View File

@ -20,7 +20,7 @@
*
* \brief The default DNS resolver for Asterisk.
*
* \arg See also \ref res_resolver_unbound
* \arg See also \ref res_resolver_unbound.c
*
* \author Ashley Sanders <asanders@digium.com>
*/
@ -200,9 +200,10 @@ static int dns_system_resolver_resolve(struct ast_dns_query *query)
*
* \internal
*
* \param dns_response The full DNS response.
* \param dns_response The length of the full DNS response.
* \param rcode The DNS response code.
* \param context A void pointer to the ast_dns_query being processed.
* \param dns_response The full DNS response.
* \param dns_response_len The length of the full DNS response.
* \param rcode The DNS response code.
*
* \retval 0 on success
* \retval -1 on failure

Some files were not shown because too many files have changed in this diff Show More