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

stasis: Fix for Doxygen. 

ASTERISK-29750

Change-Id: Iea50173e785b2e9d49bc24c0af7111cfd96d44a9
This commit is contained in:
Alexander Traud 2021-11-16 17:26:23 +01:00 committed by Kevin Harwell
parent 173bc6b4c3
commit acd1cd66b8
24 changed files with 232 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
include/asterisk/stasis.h
View File

@ -65,7 +65,7 @@
*
* \par stasis_topic
*
* A \ref stasis_topic is an object to which \ref stasis_subscriber's may be
* A \ref stasis_topic is an object to which stasis_topic_subscriber's may be
* subscribed, and \ref stasis_message's may be published. Any message published
* to the topic is dispatched to all of its subscribers. The topic itself may be
* named, which is useful in debugging.
@ -106,7 +106,7 @@
* cache may be shared amongst different message types, such a usage is probably
* not a good idea.
*
* The \ref stasis_cache can only be written to by \ref stasis_caching_topics.
* The \ref stasis_cache can only be written to by \ref stasis_caching_topic.
* It's a thread safe container, so freely use the stasis_cache_get() and
* stasis_cache_dump() to query the cache.
*
@ -125,7 +125,7 @@
* The \ref stasis_cache object is a normal AO2 managed object, which can be
* release with ao2_cleanup().
*
* \par stasis_subscriber
* \par stasis_topic_subscriber
*
* Any topic may be subscribed to by simply providing stasis_subscribe() the
* \ref stasis_topic to subscribe to, a handler function and \c void pointer to
@ -247,8 +247,7 @@ struct stasis_message_vtable {
* \param sanitize Snapshot sanitization callback.
*
* \return Newly allocated JSON message.
* \return \c NULL on error.
* \return \c NULL if JSON format is not supported.
* \retval NULL if JSON format is not supported.
*/
struct ast_json *(*to_json)(struct stasis_message *message, const struct stasis_message_sanitizer *sanitize);
@ -260,8 +259,7 @@ struct stasis_message_vtable {
*
* \param message Message to convert to AMI string.
* \return Newly allocated \ref ast_manager_event_blob.
* \return \c NULL on error.
* \return \c NULL if AMI format is not supported.
* \retval NULL if AMI format is not supported.
*/
struct ast_manager_event_blob *(*to_ami)(
struct stasis_message *message);
@ -275,8 +273,7 @@ struct stasis_message_vtable {
*
* \param message Message to convert to an \ref ast_event.
* \return Newly allocated \ref ast_event.
* \return \c NULL on error.
* \return \c NULL if AMI format is not supported.
* \retval NULL if AMI format is not supported.
*/
struct ast_event *(*to_event)(
struct stasis_message *message);
@ -337,7 +334,7 @@ enum stasis_message_type_result stasis_message_type_create(const char *name,
* \brief Gets the name of a given message type
* \param type The type to get.
* \return Name of the type.
* \return \c NULL if \a type is \c NULL.
* \retval NULL if \a type is \c NULL.
* \since 12
*/
const char *stasis_message_type_name(const struct stasis_message_type *type);
@ -379,7 +376,7 @@ int stasis_message_type_declined(const char *name);
* \param data Immutable data that is the actual contents of the message
*
* \return New message
* \return \c NULL on error
* \retval NULL on error
*
* \since 12
*/
@ -404,7 +401,7 @@ struct stasis_message *stasis_message_create(struct stasis_message_type *type, v
* any remote entities publishing to a mailbox.
*
* \retval New message
* \retval \c NULL on error
* \retval NULL on error
*
* \since 12.2.0
*/
@ -417,7 +414,7 @@ struct stasis_message *stasis_message_create_full(struct stasis_message_type *ty
* \param msg Message to get eid.
*
* \retval Entity id of \a msg
* \retval \c NULL if \a msg is an aggregate or \a msg is \c NULL.
* \retval NULL if \a msg is an aggregate or \a msg is \c NULL.
*/
const struct ast_eid *stasis_message_eid(const struct stasis_message *msg);
@ -425,7 +422,7 @@ const struct ast_eid *stasis_message_eid(const struct stasis_message *msg);
* \brief Get the message type for a \ref stasis_message.
* \param msg Message to type
* \return Type of \a msg
* \return \c NULL if \a msg is \c NULL.
* \retval NULL if \a msg is \c NULL.
* \since 12
*/
struct stasis_message_type *stasis_message_type(const struct stasis_message *msg);
@ -434,7 +431,7 @@ struct stasis_message_type *stasis_message_type(const struct stasis_message *msg
* \brief Get the data contained in a message.
* \param msg Message.
* \return Immutable data pointer
* \return \c NULL if msg is \c NULL.
* \retval NULL if msg is \c NULL.
* \since 12
*/
void *stasis_message_data(const struct stasis_message *msg);
@ -443,7 +440,7 @@ void *stasis_message_data(const struct stasis_message *msg);
* \brief Get the time when a message was created.
* \param msg Message.
* \return Pointer to the \a timeval when the message was created.
* \return \c NULL if msg is \c NULL.
* \retval NULL if msg is \c NULL.
* \since 12
*/
const struct timeval *stasis_message_timestamp(const struct stasis_message *msg);
@ -458,8 +455,7 @@ const struct timeval *stasis_message_timestamp(const struct stasis_message *msg)
* \param sanitize Snapshot sanitization callback.
*
* \return Newly allocated string with JSON message.
* \return \c NULL on error.
* \return \c NULL if JSON format is not supported.
* \retval NULL if JSON format is not supported.
*/
struct ast_json *stasis_message_to_json(struct stasis_message *msg, struct stasis_message_sanitizer *sanitize);
@ -470,8 +466,7 @@ struct ast_json *stasis_message_to_json(struct stasis_message *msg, struct stasi
* be ao2_cleanup()'ed.
*
* \param msg Message to convert to AMI.
* \return \c NULL on error.
* \return \c NULL if AMI format is not supported.
* \retval NULL if AMI format is not supported.
*/
struct ast_manager_event_blob *stasis_message_to_ami(struct stasis_message *msg);
@ -492,8 +487,7 @@ int stasis_message_can_be_ami(struct stasis_message *msg);
* be disposed of via \ref ast_event_destroy.
*
* \param msg Message to convert to AMI.
* \return \c NULL on error.
* \return \c NULL if AMI format is not supported.
* \retval NULL if AMI format is not supported.
*/
struct ast_event *stasis_message_to_event(struct stasis_message *msg);
@ -507,7 +501,7 @@ struct stasis_topic;
* \brief Create a new topic.
* \param name Name of the new topic.
* \return New topic instance.
* \return \c NULL on error.
* \retval NULL on error.
* \since 12
*
* \note There is no explicit ability to unsubscribe all subscribers
@ -515,7 +509,8 @@ struct stasis_topic;
* the last subscriber unsubscribes itself even if there is no
* publisher.
*
* \note Topic names should be in the form of <subsystem>:<functionality>[/<object>]
* \note Topic names should be in the form of
* \verbatim <subsystem>:<functionality>[/<object>] \endverbatim
*/
struct stasis_topic *stasis_topic_create(const char *name);
@ -524,7 +519,7 @@ struct stasis_topic *stasis_topic_create(const char *name);
* \param name Name of the new topic.
* \param detail Detail description of the new topic. i.e. "Queue main topic for subscribing every queue event"
* \return New topic instance.
* \return \c NULL on error.
* \retval NULL on error.
*
* \note There is no explicit ability to unsubscribe all subscribers
* from a topic and destroy it. As a result the topic can persist until
@ -538,7 +533,7 @@ struct stasis_topic *stasis_topic_create_with_detail(
* \brief Get a topic of the given name.
* \param name Topic's name.
* \return Name of the topic.
* \return \c NULL on error or not exist.
* \retval NULL on error or not exist.
*
* \note This SHOULD NOT be used in normal operation for publishing messages.
*/
@ -548,7 +543,7 @@ struct stasis_topic *stasis_topic_get(const char *name);
* \brief Return the uniqueid of a topic.
* \param topic Topic.
* \return Uniqueid of the topic.
* \return \c NULL if topic is \c NULL.
* \retval NULL if topic is \c NULL.
*/
const char *stasis_topic_uniqueid(const struct stasis_topic *topic);
@ -556,7 +551,7 @@ const char *stasis_topic_uniqueid(const struct stasis_topic *topic);
* \brief Return the name of a topic.
* \param topic Topic.
* \return Name of the topic.
* \return \c NULL if topic is \c NULL.
* \retval NULL if topic is \c NULL.
*/
const char *stasis_topic_name(const struct stasis_topic *topic);
@ -564,7 +559,7 @@ const char *stasis_topic_name(const struct stasis_topic *topic);
* \brief Return the detail of a topic.
* \param topic Topic.
* \return Detail of the topic.
* \return \c NULL if topic is \c NULL.
* \retval NULL if topic is \c NULL.
* \since 12
*/
const char *stasis_topic_detail(const struct stasis_topic *topic);
@ -598,7 +593,7 @@ void stasis_publish(struct stasis_topic *topic, struct stasis_message *message);
* The caller of stasis_publish_sync will block until the specified
* subscriber completes handling of the message.
*
* All other subscribers to the topic the \ref stasis_subpscription
* All other subscribers to the topic the \ref stasis_subscription
* is subscribed to are also delivered the message; this delivery however
* happens asynchronously.
*
@ -609,6 +604,7 @@ void stasis_publish_sync(struct stasis_subscription *sub, struct stasis_message
/*!
* \brief Callback function type for Stasis subscriptions.
* \param data Data field provided with subscription.
* \param sub Subscription published on.
* \param message Published message.
* \since 12
*/
@ -639,8 +635,9 @@ void stasis_subscription_cb_noop(void *data, struct stasis_subscription *sub, st
* \param topic Topic to subscribe to.
* \param callback Callback function for subscription messages.
* \param data Data to be passed to the callback, in addition to the message.
* \param file, lineno, func
* \return New \ref stasis_subscription object.
* \return \c NULL on error.
* \retval NULL on error.
* \since 12
*
* \note This callback will receive a callback with a message indicating it
@ -669,8 +666,9 @@ struct stasis_subscription *__stasis_subscribe(struct stasis_topic *topic,
* \param topic Topic to subscribe to.
* \param callback Callback function for subscription messages.
* \param data Data to be passed to the callback, in addition to the message.
* \param file, lineno, func
* \return New \ref stasis_subscription object.
* \return \c NULL on error.
* \retval NULL on error.
* \since 12.8.0
*
* \note This callback will receive a callback with a message indicating it
@ -768,7 +766,7 @@ enum stasis_subscription_message_formatters stasis_message_type_available_format
* delivery of the final message.
*
* \param subscription Subscription to cancel.
* \return \c NULL for convenience
* \retval NULL for convenience
* \since 12
*/
struct stasis_subscription *stasis_unsubscribe(
@ -823,7 +821,7 @@ int stasis_subscription_is_done(struct stasis_subscription *subscription);
* a function in a shared module that no longer exists).
*
* \param subscription Subscription to cancel.
* \return \c NULL for convenience
* \retval NULL for convenience
* \since 12
*/
struct stasis_subscription *stasis_unsubscribe_and_join(
@ -841,7 +839,7 @@ struct stasis_forward;
* \param from_topic Topic to forward.
* \param to_topic Destination topic of forwarded messages.
* \return New forwarding subscription.
* \return \c NULL on error.
* \retval NULL on error.
* \since 12
*/
struct stasis_forward *stasis_forward_all(struct stasis_topic *from_topic,
@ -913,7 +911,7 @@ struct stasis_topic_pool;
* \brief Create a topic pool that routes messages from dynamically generated topics to the given topic
* \param pooled_topic Topic to which messages will be routed
* \return the new stasis_topic_pool
* \return \c NULL on failure
* \retval NULL on failure
*/
struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_topic);
@ -922,7 +920,7 @@ struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_t
* \param pool Pool for which to get the topic
* \param topic_name Name of the topic to get
* \return The already stored or newly allocated topic
* \return \c NULL if the topic was not found and could not be allocated
* \retval NULL if the topic was not found and could not be allocated
*/
struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name);
@ -931,7 +929,7 @@ struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool,
*
* \param pool Pool from which to delete the topic
* \param topic_name Name of the topic to delete in the form of
* <pool_topic_name>/<topic_name> or just <topic_name>
* \verbatim [<pool_topic_name>/]<topic_name> \endverbatim
*
* \since 13.24
* \since 15.6
@ -1005,7 +1003,7 @@ struct stasis_caching_topic;
*
* \param message Message to extract id from.
* \return String representing the snapshot's id.
* \return \c NULL if the message_type of the message isn't a handled snapshot.
* \retval NULL if the message_type of the message isn't a handled snapshot.
* \since 12
*/
typedef const char *(*snapshot_get_id)(struct stasis_message *message);
@ -1115,8 +1113,8 @@ struct stasis_message *stasis_cache_entry_get_remote(struct stasis_cache_entry *
*
* \param id_fn Callback to extract the id from a snapshot message.
*
* \retval New cache indexed by \a id_fn.
* \retval \c NULL on error
* \return New cache indexed by \a id_fn.
* \retval NULL on error
*
* \since 12
*/
@ -1141,8 +1139,8 @@ struct stasis_cache *stasis_cache_create(snapshot_get_id id_fn);
* MWI message is the old/new MWI counts accumulated from the local and
* any remote entities publishing to a mailbox.
*
* \retval New cache indexed by \a id_fn.
* \retval \c NULL on error
* \return New cache indexed by \a id_fn.
* \retval NULL on error
*
* \since 12.2.0
*/
@ -1162,7 +1160,7 @@ struct stasis_cache *stasis_cache_create_full(snapshot_get_id id_fn, cache_aggre
* \param cache Backend cache in which to keep snapshots.
* \return New topic which changes snapshot messages to stasis_cache_update()
* messages, and forwards all other messages from the original topic.
* \return \c NULL on error
* \retval NULL on error
* \since 12
*/
struct stasis_caching_topic *stasis_caching_topic_create(
@ -1175,7 +1173,7 @@ struct stasis_caching_topic *stasis_caching_topic_create(
* stasis_subscription_final_message() is received.
*
* \param caching_topic Caching topic to unsubscribe
* \return \c NULL for convenience
* \retval NULL for convenience
* \since 12
*/
struct stasis_caching_topic *stasis_caching_unsubscribe(
@ -1189,7 +1187,7 @@ struct stasis_caching_topic *stasis_caching_unsubscribe(
* opposed to stasis_caching_unsubscribe().
*
* \param caching_topic Caching topic to unsubscribe
* \return \c NULL for convenience
* \retval NULL for convenience
* \since 12
*/
struct stasis_caching_topic *stasis_caching_unsubscribe_and_join(
@ -1200,7 +1198,7 @@ struct stasis_caching_topic *stasis_caching_unsubscribe_and_join(
* \param caching_topic The caching topic.
* \return The topic that publishes cache update events, along with passthrough
* events from the underlying topic.
* \return \c NULL if \a caching_topic is \c NULL.
* \retval NULL if \a caching_topic is \c NULL.
* \since 12
*/
struct stasis_topic *stasis_caching_get_topic(
@ -1251,7 +1249,7 @@ int stasis_caching_set_filter(struct stasis_caching_topic *caching_topic,
*
* \return Message which, when sent to a \ref stasis_caching_topic, will clear
* the item from the cache.
* \return \c NULL on error.
* \retval NULL on error.
* \since 12
*/
struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
@ -1265,8 +1263,8 @@ struct stasis_message *stasis_cache_clear_create(struct stasis_message *message)
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
*
* \retval Message from the cache.
* \retval \c NULL if message is not found.
* \return Message from the cache.
* \retval NULL if message is not found.
*
* \since 12
*/
@ -1289,8 +1287,8 @@ struct stasis_message *stasis_cache_get(struct stasis_cache *cache, struct stasi
* MWI message is the old/new MWI counts accumulated from the local and
* any remote entities publishing to a mailbox.
*
* \retval Message from the cache.
* \retval \c NULL if message is not found.
* \return Message from the cache.
* \retval NULL if message is not found.
*
* \since 12.2.0
*/
@ -1304,8 +1302,8 @@ struct stasis_message *stasis_cache_get_by_eid(struct stasis_cache *cache, struc
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
*
* \retval Container of matching items found.
* \retval \c NULL if error.
* \return Container of matching items found.
* \retval NULL if error.
*/
struct ao2_container *stasis_cache_get_all(struct stasis_cache *cache, struct stasis_message_type *type, const char *id);
@ -1315,8 +1313,8 @@ struct ao2_container *stasis_cache_get_all(struct stasis_cache *cache, struct st
* \param cache The cache to query.
* \param type Type of message to dump (any type if \c NULL).
*
* \retval ao2_container containing all matches (must be unreffed by caller)
* \retval \c NULL on allocation error
* \return ao2_container containing all matches (must be unreffed by caller)
* \retval NULL on allocation error
*
* \since 12
*/
@ -1330,8 +1328,8 @@ struct ao2_container *stasis_cache_dump(struct stasis_cache *cache, struct stasi
* \param type Type of message to dump (any type if \c NULL).
* \param eid Specific entity id to retrieve. NULL for aggregate.
*
* \retval ao2_container containing all matches (must be unreffed by caller)
* \retval \c NULL on allocation error
* \return ao2_container containing all matches (must be unreffed by caller)
* \retval NULL on allocation error
*/
struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struct stasis_message_type *type, const struct ast_eid *eid);
@ -1342,8 +1340,8 @@ struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struc
* \param cache The cache to query.
* \param type Type of message to dump (any type if \c NULL).
*
* \retval ao2_container containing all matches (must be unreffed by caller)
* \retval \c NULL on allocation error
* \return ao2_container containing all matches (must be unreffed by caller)
* \retval NULL on allocation error
*/
struct ao2_container *stasis_cache_dump_all(struct stasis_cache *cache, struct stasis_message_type *type);
@ -1399,8 +1397,6 @@ struct ast_multi_object_blob *ast_multi_object_blob_create(struct ast_json *blob
* \param multi The multi object blob previously created
* \param type Type code for the object such as channel, bridge, etc.
* \param object Snapshot object of the type supplied to typename
*
* \return Nothing
*/
void ast_multi_object_blob_add(struct ast_multi_object_blob *multi, enum stasis_user_multi_object_snapshot_type type, void *object);
@ -1416,8 +1412,6 @@ void ast_multi_object_blob_add(struct ast_multi_object_blob *multi, enum stasis_
* \param chan The channel to snapshot and publish event to
* \param type The message type
* \param blob A json blob to publish with the snapshot
*
* \return Nothing
*/
void ast_multi_object_blob_single_channel_publish(struct ast_channel *chan, struct stasis_message_type *type, struct ast_json *blob);

28
include/asterisk/stasis_app.h
View File

@ -71,7 +71,7 @@ typedef void (*stasis_app_cb)(void *data, const char *app_name,
* \brief Gets the names of all registered Stasis applications.
*
* \return \c ast_str_container of container names.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ao2_container *stasis_app_get_all(void);
@ -81,7 +81,7 @@ struct ao2_container *stasis_app_get_all(void);
* \param name The name of the registered Stasis application
*
* \return \c stasis_app on success.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app *stasis_app_get_by_name(const char *name);
@ -154,7 +154,7 @@ const char *stasis_app_name(const struct stasis_app *app);
* \param app The application.
*
* \return JSON representation of app with given name.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *stasis_app_object_to_json(struct stasis_app *app);
@ -164,7 +164,7 @@ struct ast_json *stasis_app_object_to_json(struct stasis_app *app);
* \param app_name Name of the application.
*
* \return JSON representation of app with given name.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *stasis_app_to_json(const char *app_name);
@ -452,8 +452,6 @@ int stasis_app_control_is_done(
* \since 13.9.0
*
* \param control Control object to flush command queue.
*
* \return Nothing
*/
void stasis_app_control_flush_queue(struct stasis_app_control *control);
@ -463,7 +461,7 @@ void stasis_app_control_flush_queue(struct stasis_app_control *control);
* \param control Control object.
*
* \return Uniqueid of the associate channel.
* \return \c NULL if \a control is \c NULL.
* \retval NULL if \a control is \c NULL.
*/
const char *stasis_app_control_get_channel_id(
const struct stasis_app_control *control);
@ -649,7 +647,7 @@ void stasis_app_control_silence_stop(struct stasis_app_control *control);
* \param control Control for \c res_stasis.
*
* \return Most recent snapshot. ao2_cleanup() when done.
* \return \c NULL if channel isn't in cache.
* \retval NULL if channel isn't in cache.
*/
struct ast_channel_snapshot *stasis_app_control_get_snapshot(
const struct stasis_app_control *control);
@ -690,7 +688,7 @@ int stasis_app_control_queue_control(struct stasis_app_control *control,
* \param id Optional Unique ID to give to the bridge
*
* \return New bridge.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
@ -702,7 +700,7 @@ struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name,
* \param id Optional Unique ID to give to the bridge
*
* \return New bridge.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
@ -754,6 +752,7 @@ struct ast_channel *stasis_app_bridge_playback_channel_find(
*
* \param bridge Bridge we are adding the playback channel for
* \param chan Channel being added as a playback channel (must be ;1)
* \param control The app control structure for the playback channel
*
* \retval -1 failed to add channel for any reason
* \retval 0 on success
@ -842,7 +841,7 @@ void stasis_app_control_mute_in_bridge(
* \brief Set whether COLP frames should be generated when joining the bridge
*
* \param control Control whose channel should have its COLP frames inhibited when bridged
* \param mute Whether COLP frames should be generated (0) or not (1).
* \param inhibit_colp Whether COLP frames should be generated (0) or not (1).
*/
void stasis_app_control_inhibit_colp_in_bridge(
struct stasis_app_control *control, int inhibit_colp);
@ -858,7 +857,7 @@ void stasis_app_control_inhibit_colp_in_bridge(
* \param control Control object for the channel to query.
*
* \return Associated \ref ast_bridge.
* \return \c NULL if not associated with a bridge.
* \retval NULL if not associated with a bridge.
*/
struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
@ -866,9 +865,6 @@ struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
* \brief Destroy the bridge.
*
* \param bridge_id Uniqueid of bridge to be destroyed
*
* \retval non-zero on failure
* \retval zero on success
*/
void stasis_app_bridge_destroy(const char *bridge_id);
@ -882,7 +878,7 @@ struct stasis_message_sanitizer *stasis_app_get_sanitizer(void);
/*!
* \brief Indicate that this channel has had a StasisEnd published for it
*
* \param The channel that is exiting Stasis.
* \param chan The channel that is exiting Stasis.
*/
void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan);

2
include/asterisk/stasis_app_device_state.h
View File

@ -85,7 +85,7 @@ enum stasis_device_state_result stasis_app_device_state_update(
*
* \param name the name of the ARI controlled device
*
* \returna stasis device state application result.
* \return stasis device state application result.
*/
enum stasis_device_state_result stasis_app_device_state_delete(
const char *name);

14
include/asterisk/stasis_app_playback.h
View File

@ -97,7 +97,7 @@ enum stasis_app_playback_target_type {
* \param offsetms Number of milliseconds to skip before playing.
* \param id ID to assign the new playback or NULL for default.
* \return Playback control object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app_playback *stasis_app_control_play_uri(
struct stasis_app_control *control, const char **media,
@ -119,7 +119,7 @@ enum stasis_app_playback_state stasis_app_playback_get_state(
*
* \param playback Playback control object.
* \return \a playback's id.
* \return \c NULL if \a playback ic \c NULL
* \retval NULL if \a playback ic \c NULL
*/
const char *stasis_app_playback_get_id(
struct stasis_app_playback *playback);
@ -129,7 +129,7 @@ const char *stasis_app_playback_get_id(
*
* \param id Id of the playback object to find.
* \return Associated \ref stasis_app_playback object.
* \return \c NULL if \a id not found.
* \retval NULL if \a id not found.
*/
struct stasis_app_playback *stasis_app_playback_find_by_id(const char *id);
@ -138,8 +138,8 @@ struct stasis_app_playback *stasis_app_playback_find_by_id(const char *id);
*
* \param playback The playback object to convert to JSON
*
* \retval \c NULL on error
* \retval A JSON object on success
* \retval NULL on error
* \return A JSON object on success
*/
struct ast_json *stasis_app_playback_to_json(
const struct stasis_app_playback *playback);
@ -153,8 +153,8 @@ enum stasis_playback_oper_results {
* \brief Controls the media for a given playback operation.
*
* \param playback Playback control object.
* \param control Media control operation.
* \return \c STASIS_PLAYBACK_OPER_OK on success.
* \param operation Media control operation.
* \retval STASIS_PLAYBACK_OPER_OK on success.
* \return \ref stasis_playback_oper_results indicating failure.
*/
enum stasis_playback_oper_results stasis_app_playback_operation(

32
include/asterisk/stasis_app_recording.h
View File

@ -43,7 +43,7 @@ struct stasis_app_stored_recording;
*
* \param recording Recording to query.
* \return Absolute path to the recording file, without the extension.
* \return \c NULL on error.
* \retval NULL on error.
*/
const char *stasis_app_stored_recording_get_file(
struct stasis_app_stored_recording *recording);
@ -55,7 +55,7 @@ const char *stasis_app_stored_recording_get_file(
* \param recording Recording to query.
*
* \return Absolute path to the recording file, with the extension.
* \return \c NULL on error
* \retval NULL on error
*/
const char *stasis_app_stored_recording_get_filename(
struct stasis_app_stored_recording *recording);
@ -67,7 +67,7 @@ const char *stasis_app_stored_recording_get_filename(
* \param recording Recording to query.
*
* \return The extension associated with this recording.
* \return \c NULL on error
* \retval NULL on error
*/
const char *stasis_app_stored_recording_get_extension(
struct stasis_app_stored_recording *recording);
@ -77,7 +77,7 @@ const char *stasis_app_stored_recording_get_extension(
*
* \param recording Recording to convert.
* \return JSON representation.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *stasis_app_stored_recording_to_json(
struct stasis_app_stored_recording *recording);
@ -86,7 +86,7 @@ struct ast_json *stasis_app_stored_recording_to_json(
* \brief Find all stored recordings on disk.
*
* \return Container of \ref stasis_app_stored_recording objects.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ao2_container *stasis_app_stored_recording_find_all(void);
@ -95,7 +95,7 @@ struct ao2_container *stasis_app_stored_recording_find_all(void);
*
* \param name Name of the recording.
* \return New recording object.
* \return \c NULL if recording is not found. \c errno is set to indicate why
* \retval NULL if recording is not found. \c errno is set to indicate why
* - \c ENOMEM - out of memeory
* - \c EACCES - file permissions (or recording is outside the config dir)
* - Any of the error codes for stat(), opendir(), readdir()
@ -202,7 +202,7 @@ struct stasis_app_recording_options {
* \param name Name of the recording.
* \param format Format to record in.
* \return Newly allocated options object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app_recording_options *stasis_app_recording_options_create(
const char *name, const char *format);
@ -212,9 +212,9 @@ struct stasis_app_recording_options *stasis_app_recording_options_create(
*
* \param str String to parse.
* \return DTMF value to terminate on.
* \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
* \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
* \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
* \retval STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
* \retval STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
* \retval STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
*/
char stasis_app_recording_termination_parse(const char *str);
@ -242,7 +242,7 @@ enum ast_record_if_exists stasis_app_recording_if_exists_parse(
* \param control Control for \c res_stasis.
* \param options Recording options.
* \return Recording control object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app_recording *stasis_app_control_record(
struct stasis_app_control *control,
@ -262,7 +262,7 @@ enum stasis_app_recording_state stasis_app_recording_get_state(
*
* \param recording Recording control object.
* \return \a recording's name.
* \return \c NULL if \a recording ic \c NULL
* \retval NULL if \a recording ic \c NULL
*/
const char *stasis_app_recording_get_name(
struct stasis_app_recording *recording);
@ -272,7 +272,7 @@ const char *stasis_app_recording_get_name(
*
* \param name Name of the recording object to find.
* \return Associated \ref stasis_app_recording object.
* \return \c NULL if \a name not found.
* \retval NULL if \a name not found.
*/
struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name);
@ -281,7 +281,7 @@ struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name)
*
* \param recording Recording to conver.
* \return JSON model.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *stasis_app_recording_to_json(
const struct stasis_app_recording *recording);
@ -302,8 +302,8 @@ enum stasis_app_recording_oper_results {
* \brief Controls the media for a given recording operation.
*
* \param recording Recording control object.
* \param control Media control operation.
* \return \c STASIS_APP_RECORDING_OPER_OK on success.
* \param operation Media control operation.
* \retval STASIS_APP_RECORDING_OPER_OK on success.
* \return \ref stasis_app_recording_oper_results indicating failure.
*/
enum stasis_app_recording_oper_results stasis_app_recording_operation(

5
include/asterisk/stasis_app_snoop.h
View File

@ -50,8 +50,9 @@ enum stasis_app_snoop_direction {
* \param whisper Direction of media that should be whispered into.
* \param app Stasis application to execute on the snoop channel.
* \param app_args Stasis application arguments.
* \return Snoop channel. ast_channel_unref() when done.
* \return \c NULL if snoop channel couldn't be created.
* \param snoop_id
* \return ast_channel ast_channel_unref() when done.
* \retval NULL if snoop channel couldn't be created.
*/
struct ast_channel *stasis_app_control_snoop(struct ast_channel *chan,
enum stasis_app_snoop_direction spy, enum stasis_app_snoop_direction whisper,

53
include/asterisk/stasis_bridges.h
View File

@ -45,7 +45,7 @@ struct ast_bridge_snapshot_update {
*
* \param bridge The bridge from which to generate a snapshot
*
* \retval AO2 refcounted snapshot on success
* \return AO2 refcounted snapshot on success
* \retval NULL on error
*/
struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge);
@ -54,7 +54,7 @@ struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge
* \since 12
* \brief Message type for \ref ast_bridge_snapshot.
*
* \retval Message type for \ref ast_bridge_snapshot.
* \return Message type for \ref ast_bridge_snapshot.
*/
struct stasis_message_type *ast_bridge_snapshot_type(void);
@ -66,7 +66,7 @@ struct stasis_message_type *ast_bridge_snapshot_type(void);
*
* \param bridge Bridge for which to get a topic or \c NULL.
*
* \retval Topic for bridge's events.
* \return Topic for bridge's events.
* \retval ast_bridge_topic_all() if \a bridge is \c NULL.
*/
struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
@ -74,7 +74,7 @@ struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
/*!
* \since 12
* \brief A topic which publishes the events for all bridges.
* \retval Topic for all bridge events.
* \return Topic for all bridge events.
*/
struct stasis_topic *ast_bridge_topic_all(void);
@ -98,7 +98,7 @@ struct ast_bridge_merge_message {
* \since 12
* \brief Message type for \ref ast_bridge_merge_message.
*
* \retval Message type for \ref ast_bridge_merge_message.
* \return Message type for \ref ast_bridge_merge_message.
*/
struct stasis_message_type *ast_bridge_merge_message_type(void);
@ -131,17 +131,17 @@ struct ast_bridge_blob {
/*!
* \since 12
* \brief Message type for \ref channel enter bridge blob messages.
* \brief Message type for \ref ast_channel enter bridge blob messages.
*
* \retval Message type for \ref channel enter bridge blob messages.
* \return Message type for \ref ast_channel enter bridge blob messages.
*/
struct stasis_message_type *ast_channel_entered_bridge_type(void);
/*!
* \since 12
* \brief Message type for \ref channel leave bridge blob messages.
* \brief Message type for \ref ast_channel leave bridge blob messages.
*
* \retval Message type for \ref channel leave bridge blob messages.
* \return Message type for \ref ast_channel leave bridge blob messages.
*/
struct stasis_message_type *ast_channel_left_bridge_type(void);
@ -156,10 +156,12 @@ struct stasis_message_type *ast_channel_left_bridge_type(void);
* \pre bridge is locked.
* \pre No channels are locked.
*
* \param type
* \param bridge Channel blob is associated with, or NULL for global/all bridges.
* \param chan The channel that started the bridge
* \param blob JSON object representing the data.
* \return \ref ast_bridge_blob message.
* \return \c NULL on error
* \retval NULL on error
*/
struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
struct ast_bridge *bridge,
@ -178,11 +180,12 @@ struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
* \pre bridge is locked.
* \pre No channels are locked.
*
* \param type
* \param bridge_snapshot Bridge snapshot
* \param channel_snapshot Channel snapshot
* \param chan_snapshot Channel snapshot
* \param blob JSON object representing the data.
* \return \ref ast_bridge_blob message.
* \return \c NULL on error
* \retval NULL on error
*/
struct stasis_message *ast_bridge_blob_create_from_snapshots(struct stasis_message_type *type,
struct ast_bridge_snapshot *bridge_snapshot,
@ -222,7 +225,7 @@ void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *cha
* \param sanitize The message sanitizer to use on the snapshot
*
* \return JSON object representing bridge snapshot.
* \return \c NULL on error
* \retval NULL on error
*/
struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot,
const struct stasis_message_sanitizer *sanitize);
@ -239,7 +242,7 @@ struct ast_bridge_channel_snapshot_pair {
* \since 12
* \brief Message type for \ref ast_blind_transfer_message.
*
* \retval Message type for \ref ast_blind_transfer_message.
* \return Message type for \ref ast_blind_transfer_message.
*/
struct stasis_message_type *ast_blind_transfer_type(void);
@ -270,9 +273,8 @@ struct ast_blind_transfer_message {
*
* \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
* \param transferer The transferer's channel that is bridged to the transferee
* \param bridge The bridge the transferer and transferee are in
* \param context The destination context for the blind transfer
* \param exten The destination extension for the blind transfer
* \param context The destination context for the blind transfer
*
* \retval NULL Failure to allocate or create snapshots
* \retval non-NULL The created blind transfer message
@ -285,16 +287,7 @@ struct ast_blind_transfer_message *ast_blind_transfer_message_create(int is_exte
*
* \pre Bridges involved are locked. Channels involved are not locked.
*
* \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
* \param result The success or failure of the transfer
* \param to_transferee The bridge between the transferer and transferee plus the transferer channel
* \param context The destination context for the blind transfer
* \param exten The destination extension for the blind transfer
* \param transferee_channel If a single channel is being transferred, this is it. If
* multiple parties are being transferred, this is NULL.
* \param replace_channel If multiple parties are being transferred or the transfer
* cannot reach across the bridge due to bridge flags, this is
* the channel connecting their bridge to the destination.
* \param transfer_message
*/
void ast_bridge_publish_blind_transfer(struct ast_blind_transfer_message *transfer_message);
@ -460,7 +453,7 @@ struct stasis_message_type *ast_attended_transfer_type(void);
*
* \param bridge_id Uniqueid of the bridge from which to get the snapshot.
* \return Most recent snapshot. ao2_cleanup() when done.
* \return \c NULL if bridge or snapshot doesn't exist.
* \retval NULL if bridge or snapshot doesn't exist.
*/
struct ast_bridge_snapshot *ast_bridge_get_snapshot_by_uniqueid(
const char *bridge_id);
@ -473,7 +466,7 @@ struct ast_bridge_snapshot *ast_bridge_get_snapshot_by_uniqueid(
*
* \param bridge The bridge from which to get the snapshot.
* \return Most recent snapshot. ao2_cleanup() when done.
* \return \c NULL if there isn't a snapshot.
* \retval NULL if there isn't a snapshot.
*/
struct ast_bridge_snapshot *ast_bridge_get_snapshot(
struct ast_bridge *bridge);
@ -481,8 +474,8 @@ struct ast_bridge_snapshot *ast_bridge_get_snapshot(
/*!
* \internal
* \brief Initialize the topics for a single bridge.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int bridge_topics_init(struct ast_bridge *bridge);

98
include/asterisk/stasis_channels.h
View File

@ -199,7 +199,7 @@ struct ao2_container *ast_channel_cache_all(void);
/*!
* \since 12
* \brief A topic which publishes the events for all channels.
* \retval Topic for all channel events.
* \return Topic for all channel events.
*/
struct stasis_topic *ast_channel_topic_all(void);
@ -207,7 +207,7 @@ struct stasis_topic *ast_channel_topic_all(void);
* \since 12
* \brief Secondary channel cache, indexed by name.
*
* \retval Cache of \ref ast_channel_snapshot.
* \return Cache of \ref ast_channel_snapshot.
*/
struct ao2_container *ast_channel_cache_by_name(void);
@ -215,7 +215,7 @@ struct ao2_container *ast_channel_cache_by_name(void);
* \since 12
* \brief Message type for \ref ast_channel_snapshot_update.
*
* \retval Message type for \ref ast_channel_snapshot_update.
* \return Message type for \ref ast_channel_snapshot_update.
*/
struct stasis_message_type *ast_channel_snapshot_type(void);
@ -228,7 +228,7 @@ struct stasis_message_type *ast_channel_snapshot_type(void);
*
* \param chan The channel from which to generate a snapshot
*
* \retval pointer on success (must be unreffed)
* \return pointer on success (must be unreffed)
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_create(
@ -239,9 +239,9 @@ struct ast_channel_snapshot *ast_channel_snapshot_create(
* \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
* an ao2 object, so use \ref ao2_cleanup() to deallocate.
*
* \param unique_id The channel's unique ID
* \param uniqueid The channel's unique ID
*
* \retval A \ref ast_channel_snapshot on success
* \return A \ref ast_channel_snapshot on success
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniqueid);
@ -253,7 +253,7 @@ struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniquei
*
* \param name The channel's name
*
* \retval A \ref ast_channel_snapshot on success
* \return A \ref ast_channel_snapshot on success
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_get_latest_by_name(const char *name);
@ -285,7 +285,7 @@ void ast_channel_publish_final_snapshot(struct ast_channel *chan);
* \c NULL, ast_json_null() is put into the object.
*
* \return \ref ast_channel_blob message.
* \return \c NULL on error
* \retval NULL on error
*/
struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
struct stasis_message_type *type, struct ast_json *blob);
@ -301,7 +301,7 @@ struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
* \c NULL, ast_json_null() is put into the object.
*
* \return \ref ast_channel_blob message.
* \return \c NULL on error
* \retval NULL on error
*/
struct stasis_message *ast_channel_blob_create_from_cache(
const char *uniqueid, struct stasis_message_type *type,
@ -317,7 +317,7 @@ struct stasis_message *ast_channel_blob_create_from_cache(
* \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
*
* \return \ref ast_multi_channel_blob object
* \return \c NULL on error
* \retval NULL on error
*/
struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
@ -334,7 +334,7 @@ struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *bl
* to retrieve
* \param role The role associated with the channel snapshot
*
* \retval \ref ast_channel_snapshot matching the role on success
* \return \ref ast_channel_snapshot matching the role on success
* \retval NULL on error or not found for the role specified
*/
struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
@ -355,7 +355,7 @@ struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
* retrieve
* \param role The role associated with the channel snapshots
*
* \retval A container containing all \ref ast_channel_snapshot objects matching
* \return A container containing all \ref ast_channel_snapshot objects matching
* the role on success.
* \retval NULL on error or not found for the role specified
*/
@ -369,7 +369,7 @@ struct ao2_container *ast_multi_channel_blob_get_channels(
*
* \param obj Channel blob object.
* \return Type field value from the blob.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
@ -399,8 +399,6 @@ void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
* \param blob The blob being published. (NULL if no blob)
*
* \note This will use the current snapshot on the channel and will not generate a new one.
*
* \return Nothing
*/
void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_type *type,
struct ast_json *blob);
@ -416,8 +414,6 @@ void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_ty
* \note As this only accesses the uniqueid and topic of the channel - neither of
* which should ever be changed on a channel anyhow - a channel does not have to
* be locked when calling this function.
*
* \return Nothing
*/
void ast_channel_publish_cached_blob(struct ast_channel *chan, struct stasis_message_type *type,
struct ast_json *blob);
@ -466,7 +462,7 @@ void ast_channel_publish_snapshot(struct ast_channel *chan);
/*!
* \since 12
* \brief Publish a \ref ast_channel_varset for a channel.
* \brief Publish a \ref ast_channel_publish_varset for a channel.
*
* \pre chan is locked
*
@ -481,7 +477,7 @@ void ast_channel_publish_varset(struct ast_channel *chan,
* \since 12
* \brief Message type for when a channel dials another channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_dial_type(void);
@ -489,7 +485,7 @@ struct stasis_message_type *ast_channel_dial_type(void);
* \since 12
* \brief Message type for when a variable is set on a channel.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_varset_type(void);
@ -497,7 +493,7 @@ struct stasis_message_type *ast_channel_varset_type(void);
* \since 12
* \brief Message type for when a hangup is requested on a channel.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_hangup_request_type(void);
@ -505,7 +501,7 @@ struct stasis_message_type *ast_channel_hangup_request_type(void);
* \since 16
* \brief Message type for when a channel is being masqueraded
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_masquerade_type(void);
@ -513,7 +509,7 @@ struct stasis_message_type *ast_channel_masquerade_type(void);
* \since 12
* \brief Message type for when DTMF begins on a channel.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_dtmf_begin_type(void);
@ -521,14 +517,14 @@ struct stasis_message_type *ast_channel_dtmf_begin_type(void);
* \since 12
* \brief Message type for when DTMF ends on a channel.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_dtmf_end_type(void);
/*!
* \brief Message type for when a hook flash occurs on a channel.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_flash_type(void);
@ -536,7 +532,7 @@ struct stasis_message_type *ast_channel_flash_type(void);
* \since 12
* \brief Message type for when a channel is placed on hold.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_hold_type(void);
@ -544,7 +540,7 @@ struct stasis_message_type *ast_channel_hold_type(void);
* \since 12
* \brief Message type for when a channel is removed from hold.
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_unhold_type(void);
@ -552,7 +548,7 @@ struct stasis_message_type *ast_channel_unhold_type(void);
* \since 12
* \brief Message type for when a channel starts spying on another channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_chanspy_start_type(void);
@ -560,7 +556,7 @@ struct stasis_message_type *ast_channel_chanspy_start_type(void);
* \since 12
* \brief Message type for when a channel stops spying on another channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_chanspy_stop_type(void);
@ -568,7 +564,7 @@ struct stasis_message_type *ast_channel_chanspy_stop_type(void);
* \since 12
* \brief Message type for a fax operation
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_fax_type(void);
@ -576,7 +572,7 @@ struct stasis_message_type *ast_channel_fax_type(void);
* \since 12
* \brief Message type for hangup handler related actions
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_hangup_handler_type(void);
@ -584,7 +580,7 @@ struct stasis_message_type *ast_channel_hangup_handler_type(void);
* \since 12
* \brief Message type for starting monitor on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_monitor_start_type(void);
@ -592,7 +588,7 @@ struct stasis_message_type *ast_channel_monitor_start_type(void);
* \since 12
* \brief Message type for stopping monitor on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_monitor_stop_type(void);
@ -600,7 +596,7 @@ struct stasis_message_type *ast_channel_monitor_stop_type(void);
* \since 18
* \brief Message type for starting mixmonitor on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_start_type(void);
@ -608,7 +604,7 @@ struct stasis_message_type *ast_channel_mixmonitor_start_type(void);
* \since 18
* \brief Message type for stopping mixmonitor on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_stop_type(void);
@ -616,7 +612,7 @@ struct stasis_message_type *ast_channel_mixmonitor_stop_type(void);
* \since 18
* \brief Message type for muting or unmuting mixmonitor on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_mute_type(void);
@ -624,7 +620,7 @@ struct stasis_message_type *ast_channel_mixmonitor_mute_type(void);
* \since 18.0.0
* \brief Message type for agent login on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_agent_login_type(void);
@ -632,7 +628,7 @@ struct stasis_message_type *ast_channel_agent_login_type(void);
* \since 12.0.0
* \brief Message type for agent logoff on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_agent_logoff_type(void);
@ -640,7 +636,7 @@ struct stasis_message_type *ast_channel_agent_logoff_type(void);
* \since 12
* \brief Message type for starting music on hold on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_moh_start_type(void);
@ -648,7 +644,7 @@ struct stasis_message_type *ast_channel_moh_start_type(void);
* \since 12
* \brief Message type for stopping music on hold on a channel
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_moh_stop_type(void);
@ -656,7 +652,7 @@ struct stasis_message_type *ast_channel_moh_stop_type(void);
* \since 12.4.0
* \brief Message type for a channel starting talking
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_talking_start(void);
@ -664,7 +660,7 @@ struct stasis_message_type *ast_channel_talking_start(void);
* \since 12.4.0
* \brief Message type for a channel stopping talking
*
* \retval A stasis message type
* \return A stasis message type
*/
struct stasis_message_type *ast_channel_talking_stop(void);
@ -714,7 +710,7 @@ void ast_channel_publish_dial_forward(struct ast_channel *caller,
* \param sanitize The message sanitizer to use on the snapshot
*
* \return JSON object representing channel snapshot.
* \return \c NULL on error
* \retval NULL on error
*/
struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot,
const struct stasis_message_sanitizer *sanitize);
@ -726,8 +722,8 @@ struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
* \return True (non-zero) if context, exten or priority are identical.
* \return False (zero) if context, exten and priority changed.
* \retval True (non-zero) if context, exten or priority are identical.
* \retval False (zero) if context, exten and priority changed.
*/
int ast_channel_snapshot_cep_equal(
const struct ast_channel_snapshot *old_snapshot,
@ -740,8 +736,8 @@ int ast_channel_snapshot_cep_equal(
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
* \return True (non-zero) if callerid are identical.
* \return False (zero) if callerid changed.
* \retval True (non-zero) if callerid are identical.
* \retval False (zero) if callerid changed.
*/
int ast_channel_snapshot_caller_id_equal(
const struct ast_channel_snapshot *old_snapshot,
@ -754,8 +750,8 @@ int ast_channel_snapshot_caller_id_equal(
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
* \return True (non-zero) if callerid are identical.
* \return False (zero) if callerid changed.
* \retval True (non-zero) if callerid are identical.
* \retval False (zero) if callerid changed.
*/
int ast_channel_snapshot_connected_line_equal(
const struct ast_channel_snapshot *old_snapshot,
@ -763,8 +759,8 @@ int ast_channel_snapshot_connected_line_equal(
/*!
* \brief Initialize the stasis channel topic and message types
* \return 0 on success
* \return Non-zero on error
* \retval 0 on success
* \retval Non-zero on error
*/
int ast_stasis_channels_init(void);

1
include/asterisk/stasis_internal.h
View File

@ -56,6 +56,7 @@
* subscriptions without mailboxes will be delivered on the publisher thread.
* \param use_thread_pool Use the thread pool for the subscription. This is only
* relevant if \c needs_mailbox is non-zero.
* \param file, lineno, func
* \return New \ref stasis_subscription object.
* \return \c NULL on error.
* \since 12

12
include/asterisk/stasis_message_router.h
View File

@ -51,13 +51,13 @@ struct stasis_message_router;
* \param topic Topic to subscribe route to.
*
* \return New \ref stasis_message_router.
* \return \c NULL on error.
* \retval NULL on error.
*
* \since 12
*/
#define stasis_message_router_create(topic) __stasis_message_router_create(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct stasis_message_router *__stasis_message_router_create(
struct stasis_topic *topic, const char *file, int lineno, const char *func);
#define stasis_message_router_create(topic) __stasis_message_router_create(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Create a new message router object.
@ -68,13 +68,13 @@ struct stasis_message_router *__stasis_message_router_create(
* \param topic Topic to subscribe route to.
*
* \return New \ref stasis_message_router.
* \return \c NULL on error.
* \retval NULL on error.
*
* \since 12.8.0
*/
#define stasis_message_router_create_pool(topic) __stasis_message_router_create_pool(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct stasis_message_router *__stasis_message_router_create_pool(
struct stasis_topic *topic, const char *file, int lineno, const char *func);
#define stasis_message_router_create_pool(topic) __stasis_message_router_create_pool(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Unsubscribe the router from the upstream topic.
@ -104,9 +104,9 @@ void stasis_message_router_unsubscribe_and_join(
*
* \param router Router.
*
* \return True (non-zero) if stasis_subscription_final_message() has been
* \retval True (non-zero) if stasis_subscription_final_message() has been
* received.
* \return False (zero) if waiting for the end.
* \retval False (zero) if waiting for the end.
*/
int stasis_message_router_is_done(struct stasis_message_router *router);

4
include/asterisk/stasis_system.h
View File

@ -37,7 +37,7 @@ void ast_system_publish_registry(const char *channeltype, const char *username,
* \since 12
* \brief A \ref stasis topic which publishes messages regarding system changes
*
* \retval \ref stasis_topic for system level changes
* \return \ref stasis_topic for system level changes
* \retval NULL on error
*/
struct stasis_topic *ast_system_topic(void);
@ -47,7 +47,7 @@ struct stasis_topic *ast_system_topic(void);
* \brief A \ref stasis_message_type for network changes
*
* \retval NULL on error
* \retval \ref stasis_message_type for network changes
* \return \ref stasis_message_type for network changes
*
* \note Messages of this type should always be issued on and expected from
* the \ref ast_system_topic \ref stasis topic

1
include/asterisk/stasis_test.h
View File

@ -101,6 +101,7 @@ typedef int (*stasis_wait_cb)(struct stasis_message *msg, const void *data);
* \param start Index of message to start with.
* \param cmp_cb comparison function. This returns true (non-zero) on match
* and false (zero) on match.
* \param data
* \param timeout_millis Number of milliseconds to wait.
* \return Index of the matching message.
* \return Negative for no match.

5
main/stasis.c
View File

@ -250,8 +250,8 @@
* The destructors of both have assertions regarding this to catch ref-counting
* problems where a subscription or topic has had an extra ao2_cleanup().
*
* The \ref dispatch object is a transient object, which is posted to a
* subscription's taskprocessor to send a message to the subscriber. They have
* The \ref dispatch_exec_sync object is a transient object, which is posted to
* a subscription's taskprocessor to send a message to the subscriber. They have
* short life cycles, allocated on one thread, destroyed on another.
*
* During shutdown, or the deletion of a domain object, there are a flurry of
@ -750,7 +750,6 @@ static void subscription_dtor(void *obj)
/*!
* \brief Invoke the subscription's callback.
* \param sub Subscription to invoke.
* \param topic Topic message was published to.
* \param message Message to send.
*/
static void subscription_invoke(struct stasis_subscription *sub,

2
main/stasis_bridges.c
View File

@ -752,7 +752,7 @@ struct ast_json *ast_bridge_snapshot_to_json(
* \internal
* \brief Allocate the fields of an \ref ast_bridge_channel_snapshot_pair.
*
* \param pair A bridge and channel to get snapshots of
* \param channel, bridge A bridge and channel to get snapshots of
* \param[out] snapshot_pair An allocated snapshot pair.
* \retval 0 Success
* \retval non-zero Failure

6
main/stasis_cache.c
View File

@ -390,7 +390,7 @@ struct stasis_message *stasis_cache_entry_get_remote(struct stasis_cache_entry *
*
* \note The entries container is already locked.
*
* \retval Cache-entry on success.
* \return Cache-entry on success.
* \retval NULL Not in cache.
*/
static struct stasis_cache_entry *cache_find(struct ao2_container *entries, struct stasis_message_type *type, const char *id)
@ -625,8 +625,8 @@ struct ao2_container *stasis_cache_get_all(struct stasis_cache *cache, struct st
*
* \note The returned snapshot has not had its reference bumped.
*
* \retval Snapshot from the cache.
* \retval \c NULL if snapshot is not found.
* \return Snapshot from the cache.
* \retval NULL if snapshot is not found.
*/
static struct stasis_message *cache_entry_by_eid(const struct stasis_cache_entry *entry, const struct ast_eid *eid)
{

7
main/stasis_state.c
View File

@ -157,9 +157,10 @@ static void state_proxy_sub_cb(void *obj, void *data)
* \param manager The owning manager
* \param state_topic A state topic to be managed
* \param id The unique id for the state
* \param file, line, func
*
* \return A stasis_state object or NULL
* \return NULL on error
* \retval NULL on error
*
* \pre manager->states must be locked.
* \pre manager->states does not contain an object matching key \a id.
@ -265,9 +266,9 @@ error_return:
* \param id The unique id for the state (if NULL state_topic is required)
*
* \return The added state object
* \return NULL on error
* \retval NULL on error
*/
#define state_find_or_add(mgr, top, id) __state_find_or_add(mgr, top, id, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define state_find_or_add(manager, state_topic, id) __state_find_or_add(manager, state_topic, id, __FILE__, __LINE__, __PRETTY_FUNCTION__)
static struct stasis_state *__state_find_or_add(struct stasis_state_manager *manager,
struct stasis_topic *state_topic, const char *id,
const char *file, int line, const char *func)

2
res/res_stasis_snoop.c
View File

@ -107,7 +107,7 @@ static void snoop_destroy(void *obj)
/*! \internal
* \brief Publish the chanspy message over Stasis-Core
* \param snoop The snoop structure
* \start start If non-zero, the spying is starting. Otherwise, the spyer is
* \param start If non-zero, the spying is starting. Otherwise, the spyer is
* finishing
*/
static void publish_chanspy_message(struct stasis_app_snoop *snoop, int start)

5
res/stasis/app.c
View File

@ -1030,11 +1030,6 @@ struct stasis_topic *ast_app_get_topic(struct stasis_app *app)
return app->topic;
}
/*!
* \brief Send a message to the given application.
* \param app App to send the message to.
* \param message Message to send.
*/
void app_send(struct stasis_app *app, struct ast_json *message)
{
stasis_app_cb handler;

71
res/stasis/app.h
View File

@ -55,8 +55,9 @@ enum stasis_app_subscription_model {
* \param name Name of the application.
* \param handler Callback for messages sent to the application.
* \param data Data pointer provided to the callback.
* \param subscription_model
* \return New \c res_stasis application.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app *app_create(const char *name, stasis_app_cb handler, void *data, enum stasis_app_subscription_model subscription_model);
@ -83,8 +84,8 @@ void app_deactivate(struct stasis_app *app);
* \brief Checks whether an app is active.
*
* \param app Application to check.
* \return True (non-zero) if app is active.
* \return False (zero) if app has been deactivated.
* \retval True (non-zero) if app is active.
* \retval False (zero) if app has been deactivated.
*/
int app_is_active(struct stasis_app *app);
@ -92,8 +93,8 @@ int app_is_active(struct stasis_app *app);
* \brief Checks whether a deactivated app has no channels.
*
* \param app Application to check.
* \param True (non-zero) if app is deactivated, and has no associated channels.
* \param False (zero) otherwise.
* \retval True (non-zero) if app is deactivated, and has no associated channels.
* \retval False (zero) otherwise.
*/
int app_is_finished(struct stasis_app *app);
@ -111,7 +112,7 @@ void app_update(struct stasis_app *app, stasis_app_cb handler, void *data);
/*!
* \brief Send a message to an application.
*
* \param app Application.
* \param app App to send the message to.
* \param message Message to send.
*/
void app_send(struct stasis_app *app, struct ast_json *message);
@ -123,8 +124,8 @@ struct app_forwards;
*
* \param app The application
*
* \return \c JSON blob on success
* \return \c NULL on error
* \return JSON blob on success
* \retval NULL on error
*/
struct ast_json *app_to_json(const struct stasis_app *app);
@ -133,8 +134,8 @@ struct ast_json *app_to_json(const struct stasis_app *app);
*
* \param app Application.
* \param chan Channel to subscribe to.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
@ -143,8 +144,8 @@ int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
*
* \param app Subscribing application.
* \param chan Channel to unsubscribe from.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
@ -153,8 +154,8 @@ int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
*
* \param app Subscribing application.
* \param channel_id Id of channel to unsubscribe from.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
@ -163,8 +164,8 @@ int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
*
* \param app Subscribing application.
* \param channel_id Id of channel to check.
* \return True (non-zero) if channel is subscribed to \a app.
* \return False (zero) if channel is not subscribed.
* \retval True (non-zero) if channel is subscribed to \a app.
* \retval False (zero) if channel is not subscribed.
*/
int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id);
@ -173,18 +174,18 @@ int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id)
*
* \param app Application.
* \param bridge Bridge to subscribe to.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
/*!
* \brief Cancel the bridge subscription for an application.
*
* \param forwards Return from app_subscribe_channel().
* \param app Subscribing application.
* \param bridge Bridge to subscribe to.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
@ -193,8 +194,8 @@ int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
*
* \param app Subscribing application.
* \param bridge_id Id of bridge to unsubscribe from.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
@ -203,8 +204,8 @@ int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
*
* \param app Subscribing application.
* \param bridge_id Id of bridge to check.
* \return True (non-zero) if bridge is subscribed to \a app.
* \return False (zero) if bridge is not subscribed.
* \retval True (non-zero) if bridge is subscribed to \a app.
* \retval False (zero) if bridge is not subscribed.
*/
int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
@ -212,9 +213,9 @@ int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
* \brief Subscribes an application to a endpoint.
*
* \param app Application.
* \param chan Endpoint to subscribe to.
* \return 0 on success.
* \return Non-zero on error.
* \param endpoint Endpoint to subscribe to.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint);
@ -223,8 +224,8 @@ int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint
*
* \param app Subscribing application.
* \param endpoint_id Id of endpoint to unsubscribe from.
* \return 0 on success.
* \return Non-zero on error.
* \retval 0 on success.
* \retval Non-zero on error.
*/
int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id);
@ -233,15 +234,15 @@ int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id)
*
* \param app Subscribing application.
* \param endpoint_id Id of endpoint to check.
* \return True (non-zero) if endpoint is subscribed to \a app.
* \return False (zero) if endpoint is not subscribed.
* \retval True (non-zero) if endpoint is subscribed to \a app.
* \retval False (zero) if endpoint is not subscribed.
*/
int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id);
/*!
* \brief Set the snapshot of the channel that this channel will replace
*
* \param channel The channel on which this will be set
* \param chan The channel on which this will be set
* \param replace_snapshot The snapshot of the channel that is being replaced
*
* \retval zero success
@ -252,7 +253,7 @@ int app_set_replace_channel_snapshot(struct ast_channel *chan, struct ast_channe
/*!
* \brief Set the app that the replacement channel will be controlled by
*
* \param channel The channel on which this will be set
* \param chan The channel on which this will be set
* \param replace_app The app that will be controlling this channel
*
* \retval zero success
@ -263,7 +264,7 @@ int app_set_replace_channel_app(struct ast_channel *chan, const char *replace_ap
/*!
* \brief Get the app that the replacement channel will be controlled by
*
* \param channel The channel on which this will be set
* \param chan The channel on which this will be set
*
* \retval NULL on error
* \return the name of the controlling app (must be ast_free()d)

14
res/stasis/control.h
View File

@ -36,7 +36,7 @@
* \param app stasis_app for which this control is being created.
*
* \return New control object.
* \return \c NULL on error.
* \retval NULL on error.
*/
struct stasis_app_control *control_create(struct ast_channel *channel, struct stasis_app *app);
@ -45,8 +45,6 @@ struct stasis_app_control *control_create(struct ast_channel *channel, struct st
* \since 13.9.0
*
* \param control Control object to flush command queue.
*
* \return Nothing
*/
void control_flush_queue(struct stasis_app_control *control);
@ -72,7 +70,7 @@ void control_wait(struct stasis_app_control *control);
*
* \param control Control to count commands on
*
* \retval number of commands in the command que
* \return number of commands in the command que
*/
int control_command_count(struct stasis_app_control *control);
@ -80,8 +78,8 @@ int control_command_count(struct stasis_app_control *control);
* \brief Returns true if control_continue() has been called on this \a control.
*
* \param control Control to query.
* \return True (non-zero) if control_continue() has been called.
* \return False (zero) otherwise.
* \retval True (non-zero) if control_continue() has been called.
* \retval False (zero) otherwise.
*/
int control_is_done(struct stasis_app_control *control);
@ -91,7 +89,7 @@ void control_mark_done(struct stasis_app_control *control);
* \brief Dispatch all queued prestart commands
*
* \param control The control for chan
* \param channel The channel on which commands should be executed
* \param chan The channel on which commands should be executed
*
* \return The number of commands executed
*/
@ -103,7 +101,7 @@ int control_prestart_dispatch_all(struct stasis_app_control *control,
*
* \param control Control to query.
*
* \returns A pointer to the associated stasis_app
* \return A pointer to the associated stasis_app
*/
struct stasis_app *control_app(struct stasis_app_control *control);

5
res/stasis/messaging.h
View File

@ -45,9 +45,6 @@ typedef int (* message_received_cb)(const char *endpoint_id, struct ast_json *js
*
* \param app_name Name of the stasis application to unsubscribe from messaging
* \param endpoint_id The ID of the endpoint we no longer care about
*
* \retval 0 success
* \retval -1 error
*/
void messaging_app_unsubscribe_endpoint(const char *app_name, const char *endpoint_id);
@ -56,7 +53,7 @@ void messaging_app_unsubscribe_endpoint(const char *app_name, const char *endpoi
*
* \param app_name The name of the \ref stasis application to subscribe to \c endpoint
* \param endpoint The endpoint object to subscribe to
* \param message_received_cb The callback to call when a message is received
* \param callback The callback to call when a message is received
* \param pvt An ao2 ref counted object that will be passed to the callback.
*
* \retval 0 subscription was successful

2
res/stasis/stasis_bridge.c
View File

@ -278,8 +278,6 @@ static int bridge_stasis_moving(struct ast_bridge_channel *bridge_channel, void
* \param bridge_channel Bridge channel to pull.
*
* \note On entry, self is already locked.
*
* \return Nothing
*/
static void bridge_stasis_pull(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel)
{

2
res/stasis/stasis_bridge.h
View File

@ -61,8 +61,6 @@ struct ast_bridge *bridge_stasis_new(uint32_t capabilities, unsigned int flags,
* \internal
* \brief Initialize the Stasis bridge subclass.
* \since 12.5.0
*
* \return Nothing
*/
void bridge_stasis_init(void);

2
res/stasis_recording/stored.c
View File

@ -85,7 +85,7 @@ const char *stasis_app_stored_recording_get_extension(
*
* \param path Path to split.
* \param[out] dir Output parameter for directory portion.
* \param[out] fail Output parameter for the file portion.
* \param[out] file Output parameter for the file portion.
* \return 0 on success.
* \return Non-zero on error.
*/