mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-05 20:55:26 +00:00
Add Doxygen documentation for API changes from 1.6.0 to 1.6.1
Copied from my review board description: This is a continuation of the API changes documentation started for describing changes between releases. Most of the API changes were pretty simple needing only to be brought to attention via the new "Asterisk API Changes" list. However, if you see anything that needs further explanation feel free to supplement what is there. The current method of documenting is to add (in the header file): \version <ver number> <description of changes> and then to add the function to the change list in doxyref.h on the AstAPIChanges page. I also made sure all the functions that were newly added were tagged with \since 1.6.1. I think this is a good habit to start both for the historical aspect as well as for the future ability to easily add a "New Asterisk API" page. Review: http://reviewboard.digium.com/r/190/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@180719 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Jeff Peeler
@@ -63,7 +63,7 @@ extern "C" {
|
||||
|
||||
#include "asterisk/event_defs.h"
|
||||
|
||||
/*!
|
||||
/*!
|
||||
* \brief Subscriber event callback type
|
||||
*
|
||||
* \param event the event being passed to the subscriber
|
||||
@@ -73,7 +73,7 @@ extern "C" {
|
||||
*/
|
||||
typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
|
||||
|
||||
/*!
|
||||
/*!
|
||||
* \brief Subscribe to events
|
||||
*
|
||||
* \param event_type The type of events to subscribe to
|
||||
@@ -110,45 +110,48 @@ typedef void (*ast_event_cb_t)(const struct ast_event *event, void *userdata);
|
||||
* contained in peer->mailbox. Also, the event callback will be passed a
|
||||
* pointer to the peer.
|
||||
*/
|
||||
struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
|
||||
struct ast_event_sub *ast_event_subscribe(enum ast_event_type event_type,
|
||||
ast_event_cb_t cb, void *userdata, ...);
|
||||
|
||||
/*!
|
||||
* \brief Allocate a subscription, but do not activate it
|
||||
*
|
||||
* \arg type the event type to subscribe to
|
||||
* \arg cb the function to call when an event matches this subscription
|
||||
* \arg userdata data to pass to the provided callback
|
||||
* \param type the event type to subscribe to
|
||||
* \param cb the function to call when an event matches this subscription
|
||||
* \param userdata data to pass to the provided callback
|
||||
*
|
||||
* This function should be used when you want to dynamically build a
|
||||
* subscription.
|
||||
*
|
||||
* \return the allocated subscription, or NULL on failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
|
||||
struct ast_event_sub *ast_event_subscribe_new(enum ast_event_type type,
|
||||
ast_event_cb_t cb, void *userdata);
|
||||
|
||||
/*!
|
||||
* \brief Destroy an allocated subscription
|
||||
*
|
||||
* \arg sub the subscription to destroy
|
||||
* \param sub the subscription to destroy
|
||||
*
|
||||
* This function should be used when a subscription is allocated with
|
||||
* ast_event_subscribe_new(), but for some reason, you want to destroy it
|
||||
* instead of activating it. This could be because of an error when
|
||||
* reading in the configuration for the dynamically built subscription.
|
||||
* \since 1.6.1
|
||||
*/
|
||||
void ast_event_sub_destroy(struct ast_event_sub *sub);
|
||||
|
||||
/*!
|
||||
* \brief Append a uint parameter to a subscription
|
||||
*
|
||||
* \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \arg ie_type the information element type for the parameter
|
||||
* \arg uint the value that must be present in the event to match this subscription
|
||||
* \param sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \param ie_type the information element type for the parameter
|
||||
* \param uint the value that must be present in the event to match this subscription
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
|
||||
enum ast_event_ie_type ie_type, uint32_t uint);
|
||||
@@ -156,53 +159,57 @@ int ast_event_sub_append_ie_uint(struct ast_event_sub *sub,
|
||||
/*!
|
||||
* \brief Append a string parameter to a subscription
|
||||
*
|
||||
* \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \arg ie_type the information element type for the parameter
|
||||
* \arg str the string that must be present in the event to match this subscription
|
||||
* \param sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \param ie_type the information element type for the parameter
|
||||
* \param str the string that must be present in the event to match this subscription
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
|
||||
int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
|
||||
enum ast_event_ie_type ie_type, const char *str);
|
||||
|
||||
/*!
|
||||
* \brief Append a raw parameter to a subscription
|
||||
*
|
||||
* \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \arg ie_type the information element type for the parameter
|
||||
* \arg raw the data that must be present in the event to match this subscription
|
||||
* \param sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \param ie_type the information element type for the parameter
|
||||
* \param raw the data that must be present in the event to match this subscription
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
|
||||
int ast_event_sub_append_ie_raw(struct ast_event_sub *sub,
|
||||
enum ast_event_ie_type ie_type, void *data, size_t raw_datalen);
|
||||
|
||||
/*!
|
||||
* \brief Append an 'exists' parameter to a subscription
|
||||
*
|
||||
* \arg sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \arg ie_type the information element type that must be present in the event
|
||||
* \param sub the dynamic subscription allocated with ast_event_subscribe_new()
|
||||
* \param ie_type the information element type that must be present in the event
|
||||
* for it to match this subscription.
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
|
||||
int ast_event_sub_append_ie_exists(struct ast_event_sub *sub,
|
||||
enum ast_event_ie_type ie_type);
|
||||
|
||||
/*!
|
||||
* \brief Activate a dynamically built subscription
|
||||
*
|
||||
* \arg sub the subscription to activate that was allocated using
|
||||
* \param sub the subscription to activate that was allocated using
|
||||
* ast_event_subscribe_new()
|
||||
*
|
||||
* Once a dynamically built subscription has had all of the parameters added
|
||||
* Once a dynamically built subscription has had all of the parameters added
|
||||
* to it, it should be activated using this function.
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_sub_activate(struct ast_event_sub *sub);
|
||||
|
||||
@@ -216,6 +223,7 @@ int ast_event_sub_activate(struct ast_event_sub *sub);
|
||||
* structures.
|
||||
*
|
||||
* \return NULL for convenience.
|
||||
* \version 1.6.1 return changed to NULL
|
||||
*/
|
||||
struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
|
||||
|
||||
@@ -252,7 +260,7 @@ struct ast_event_sub *ast_event_unsubscribe(struct ast_event_sub *event_sub);
|
||||
* }
|
||||
* \endcode
|
||||
*
|
||||
* This example will check if there are any subscribers to MWI events for the
|
||||
* This example will check if there are any subscribers to MWI events for the
|
||||
* mailbox defined in the "mailbox" variable.
|
||||
*/
|
||||
enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type event_type, ...);
|
||||
@@ -274,7 +282,10 @@ enum ast_event_subscriber_res ast_event_check_subscriber(enum ast_event_type eve
|
||||
*/
|
||||
void ast_event_report_subs(const struct ast_event_sub *sub);
|
||||
|
||||
/*! \brief Dump the event cache for the subscriber */
|
||||
/*!
|
||||
* \brief Dump the event cache for the subscriber
|
||||
* \since 1.6.1
|
||||
*/
|
||||
void ast_event_dump_cache(const struct ast_event_sub *event_sub);
|
||||
|
||||
/*!
|
||||
@@ -337,7 +348,7 @@ void ast_event_destroy(struct ast_event *event);
|
||||
*
|
||||
* This function queues an event to be dispatched to all of the appropriate
|
||||
* subscribers. This function will not block while the event is being
|
||||
* dispatched because a pool of event dispatching threads handle the event
|
||||
* dispatched because a pool of event dispatching threads handle the event
|
||||
* queue.
|
||||
*/
|
||||
int ast_event_queue(struct ast_event *event);
|
||||
@@ -350,7 +361,7 @@ int ast_event_queue(struct ast_event *event);
|
||||
* The rest of the arguments to this function specify information elements to
|
||||
* use for determining which events in the cache that this event should replace.
|
||||
* All events in the cache that match the specified criteria will be removed from
|
||||
* the cache and then this one will be added. The arguments are specified in
|
||||
* the cache and then this one will be added. The arguments are specified in
|
||||
* the form:
|
||||
*
|
||||
* \code
|
||||
@@ -481,7 +492,7 @@ int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_
|
||||
*
|
||||
* \param event The event to get the IE from
|
||||
* \param ie_type the type of information element to retrieve
|
||||
*
|
||||
*
|
||||
* \return This returns the payload of the information element with the given type.
|
||||
* However, an IE with a payload of 0, and the case where no IE is found
|
||||
* yield the same return value.
|
||||
@@ -493,7 +504,7 @@ uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_
|
||||
*
|
||||
* \param event The event to get the IE from
|
||||
* \param ie_type the type of information element to retrieve
|
||||
*
|
||||
*
|
||||
* \return This returns the payload of the information element with the given type.
|
||||
* If the information element isn't found, NULL will be returned.
|
||||
*/
|
||||
@@ -504,7 +515,7 @@ const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_i
|
||||
*
|
||||
* \param event The event to get the IE from
|
||||
* \param ie_type the type of information element to retrieve
|
||||
*
|
||||
*
|
||||
* \return This returns the payload of the information element with the given type.
|
||||
* If the information element isn't found, NULL will be returned.
|
||||
*/
|
||||
@@ -513,18 +524,20 @@ const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_i
|
||||
/*!
|
||||
* \brief Get the string representation of an information element type
|
||||
*
|
||||
* \arg ie_type the information element type to get the string representation of
|
||||
* \param ie_type the information element type to get the string representation of
|
||||
*
|
||||
* \return the string representation of the information element type
|
||||
* \since 1.6.1
|
||||
*/
|
||||
const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
|
||||
|
||||
/*!
|
||||
* \brief Get the payload type for a given information element type
|
||||
*
|
||||
* \arg ie_type the information element type to get the payload type of
|
||||
* \param ie_type the information element type to get the payload type of
|
||||
*
|
||||
* \return the payload type for the provided IE type
|
||||
* \since 1.6.1
|
||||
*/
|
||||
enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
|
||||
|
||||
@@ -544,28 +557,31 @@ enum ast_event_type ast_event_get_type(const struct ast_event *event);
|
||||
* \arg event the event to get the type of
|
||||
*
|
||||
* \return the string representation of the event type of the provided event
|
||||
* \since 1.6.1
|
||||
*/
|
||||
const char *ast_event_get_type_name(const struct ast_event *event);
|
||||
|
||||
/*!
|
||||
* \brief Convert a string into an event type
|
||||
*
|
||||
* \arg str the string to convert
|
||||
* \arg event_type an output parameter for the event type
|
||||
* \param str the string to convert
|
||||
* \param event_type an output parameter for the event type
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_str_to_event_type(const char *str, enum ast_event_type *event_type);
|
||||
|
||||
/*!
|
||||
* \brief Convert a string to an IE type
|
||||
*
|
||||
* \arg str the string to convert
|
||||
* \arg ie_type an output parameter for the IE type
|
||||
* \param str the string to convert
|
||||
* \param ie_type an output parameter for the IE type
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval non-zero failure
|
||||
* \since 1.6.1
|
||||
*/
|
||||
int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
|
||||
|
||||
@@ -575,6 +591,7 @@ int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
|
||||
* \param event the event to get the size of
|
||||
*
|
||||
* \return the number of bytes contained in the event
|
||||
* \since 1.6.1
|
||||
*/
|
||||
size_t ast_event_get_size(const struct ast_event *event);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user