Asterisk
/
asterisk
mirror of https://github.com/asterisk/asterisk
1
0
Fork 0
Code Issues Releases Wiki Activity

stasis: Fix for Doxygen.

Browse Source 
ASTERISK-29750

Change-Id: Iea50173e785b2e9d49bc24c0af7111cfd96d44a9
18.9
Alexander Traud 3 years ago committed by Friendly Automation
parent e7d5db1471
commit 6988386234
24 changed files with 232 additions and 263 deletions
Show Stats Download Patch File Download Diff File

122
include/asterisk/stasis.h
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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
Unescape 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.
*/

Write Preview
Loading…
Cancel
Save