diff options
author | Matthew Jordan <mjordan@digium.com> | 2013-04-08 14:26:37 +0000 |
---|---|---|
committer | Matthew Jordan <mjordan@digium.com> | 2013-04-08 14:26:37 +0000 |
commit | b8d4e573f1292688d07063542d263490536c2bc9 (patch) | |
tree | 938b0732a2311aa3c424597283aff95c85f9a98e /include/asterisk | |
parent | a2a53cc306ea5fec65daf3630716a7c6ee13adad (diff) |
Add multi-channel Stasis messages; refactor Dial AMI events to Stasis
This patch does the following:
* A new Stasis payload has been defined for multi-channel messages. This
payload can store multiple ast_channel_snapshot objects along with a single
JSON blob. The payload object itself is opaque; the snapshots are stored
in a container keyed by roles. APIs have been provided to query for and
retrieve the snapshots from the payload object.
* The Dial AMI events have been refactored onto Stasis. This includes dial
messages in app_dial, as well as the core dialing framework. The AMI events
have been modified to send out a DialBegin/DialEnd events, as opposed to
the subevent type that was previously used.
* Stasis messages, types, and other objects related to channels have been
placed in their own file, stasis_channels. Unit tests for some of these
objects/messages have also been written.
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@384910 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk')
-rw-r--r-- | include/asterisk/app_stasis.h | 2 | ||||
-rw-r--r-- | include/asterisk/channel.h | 146 | ||||
-rw-r--r-- | include/asterisk/stasis_channels.h | 304 |
3 files changed, 309 insertions, 143 deletions
diff --git a/include/asterisk/app_stasis.h b/include/asterisk/app_stasis.h index 921a35ee8..3001992d2 100644 --- a/include/asterisk/app_stasis.h +++ b/include/asterisk/app_stasis.h @@ -49,6 +49,8 @@ #include "asterisk/channel.h" #include "asterisk/json.h" +struct ast_channel_snapshot; + /*! @{ */ /*! diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 91d2f803c..939c8db51 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -365,7 +365,7 @@ struct ast_party_dialed { * PSTN gateway). * * \todo Implement settings for transliteration between UTF8 Caller ID names in - * to ASCII Caller ID's (DAHDI). Östen Åsklund might be transliterated into + * to ASCII Caller ID's (DAHDI). Östen Ã…sklund might be transliterated into * Osten Asklund or Oesten Aasklund depending upon language and person... * We need automatic routines for incoming calls and static settings for * our own accounts. @@ -3015,7 +3015,7 @@ void ast_party_id_reset(struct ast_party_id *id); * * \details * This function will generate an effective party id. - * + * * Each party id component of the party id 'base' is overwritten * by components of the party id 'overlay' if the overlay * component is marked as valid. However the component 'tag' of @@ -3788,7 +3788,7 @@ int ast_channel_get_cc_agent_type(struct ast_channel *chan, char *agent_type, si void ast_channel_unlink(struct ast_channel *chan); /*! - * \brief Sets the HANGUPCAUSE hash and optionally the SIP_CAUSE hash + * \brief Sets the HANGUPCAUSE hash and optionally the SIP_CAUSE hash * on the given channel * * \param chan channel on which to set the cause information @@ -4125,69 +4125,6 @@ void ast_channel_set_manager_vars(size_t varc, char **vars); */ struct varshead *ast_channel_get_manager_vars(struct ast_channel *chan); -/*! \addtogroup StasisTopicsAndMessages - * @{ - */ - -/*! - * \since 12 - * \brief Structure representing a snapshot of channel state. - * - * While not enforced programmatically, this object is shared across multiple - * threads, and should be threated as an immutable object. - */ -struct ast_channel_snapshot { - AST_DECLARE_STRING_FIELDS( - AST_STRING_FIELD(name); /*!< ASCII unique channel name */ - AST_STRING_FIELD(accountcode); /*!< Account code for billing */ - AST_STRING_FIELD(peeraccount); /*!< Peer account code for billing */ - AST_STRING_FIELD(userfield); /*!< Userfield for CEL billing */ - AST_STRING_FIELD(uniqueid); /*!< Unique Channel Identifier */ - AST_STRING_FIELD(linkedid); /*!< Linked Channel Identifier -- gets propagated by linkage */ - AST_STRING_FIELD(parkinglot); /*!< Default parking lot, if empty, default parking lot */ - AST_STRING_FIELD(hangupsource); /*!< Who is responsible for hanging up this channel */ - AST_STRING_FIELD(appl); /*!< Current application */ - AST_STRING_FIELD(data); /*!< Data passed to current application */ - AST_STRING_FIELD(context); /*!< Dialplan: Current extension context */ - AST_STRING_FIELD(exten); /*!< Dialplan: Current extension number */ - AST_STRING_FIELD(caller_name); /*!< Caller ID Name */ - AST_STRING_FIELD(caller_number); /*!< Caller ID Number */ - AST_STRING_FIELD(connected_name); /*!< Connected Line Name */ - AST_STRING_FIELD(connected_number); /*!< Connected Line Number */ - ); - - struct timeval creationtime; /*!< The time of channel creation */ - enum ast_channel_state state; /*!< State of line */ - int priority; /*!< Dialplan: Current extension priority */ - int amaflags; /*!< AMA flags for billing */ - int hangupcause; /*!< Why is the channel hanged up. See causes.h */ - int caller_pres; /*!< Caller ID presentation. */ - - struct ast_flags flags; /*!< channel flags of AST_FLAG_ type */ - - struct varshead *manager_vars; /*!< Variables to be appended to manager events */ -}; - -/*! - * \since 12 - * \brief Generate a snapshot of the channel state. This is an ao2 object, so - * ao2_cleanup() to deallocate. - * - * \param chan The channel from which to generate a snapshot - * - * \retval pointer on success (must be ast_freed) - * \retval NULL on error - */ -struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan); - -/*! - * \since 12 - * \brief Message type for \ref ast_channel_snapshot. - * - * \retval Message type for \ref ast_channel_snapshot. - */ -struct stasis_message_type *ast_channel_snapshot_type(void); - /*! * \since 12 * \brief A topic which publishes the events for a particular channel. @@ -4201,81 +4138,4 @@ struct stasis_message_type *ast_channel_snapshot_type(void); */ struct stasis_topic *ast_channel_topic(struct ast_channel *chan); -/*! - * \since 12 - * \brief A topic which publishes the events for all channels. - * \retval Topic for all channel events. - */ -struct stasis_topic *ast_channel_topic_all(void); - -/*! - * \since 12 - * \brief A caching topic which caches \ref ast_channel_snapshot messages from - * ast_channel_events_all(void). - * - * \retval Topic for all channel events. - */ -struct stasis_caching_topic *ast_channel_topic_all_cached(void); - -/*! - * \since 12 - * \brief Blob of data associated with a channel. - * - * The \c blob is actually a JSON object of structured data. It has a "type" field - * which contains the type string describing this blob. - */ -struct ast_channel_blob { - /*! Channel blob is associated with (or NULL for global/all channels) */ - struct ast_channel_snapshot *snapshot; - /*! JSON blob of data */ - struct ast_json *blob; -}; - -/*! - * \since 12 - * \brief Message type for \ref ast_channel_blob messages. - * - * \retval Message type for \ref ast_channel_blob messages. - */ -struct stasis_message_type *ast_channel_blob_type(void); - -/*! - * \since 12 - * \brief Extracts the type field from a \ref ast_channel_blob. - * Returned \c char* is still owned by \a obj - * \param obj Channel blob object. - * \return Type field value from the blob. - * \return \c NULL on error. - */ -const char *ast_channel_blob_json_type(struct ast_channel_blob *obj); - -/*! - * \since 12 - * \brief Creates a \ref ast_channel_blob message. - * - * The \a blob JSON object requires a \c "type" field describing the blob. It - * should also be treated as immutable and not modified after it is put into the - * message. - * - * \param chan Channel blob is associated with, or NULL for global/all channels. - * \param blob JSON object representing the data. - * \return \ref ast_channel_blob message. - * \return \c NULL on error - */ -struct stasis_message *ast_channel_blob_create(struct ast_channel *chan, - struct ast_json *blob); - -/*! @} */ - -/*! - * \since 12 - * \brief Publish a \ref ast_channel_varset for a channel. - * - * \param chan Channel to pulish the event for, or \c NULL for 'none'. - * \param variable Name of the variable being set - * \param value Value. - */ -void ast_channel_publish_varset(struct ast_channel *chan, - const char *variable, const char *value); - #endif /* _ASTERISK_CHANNEL_H */ diff --git a/include/asterisk/stasis_channels.h b/include/asterisk/stasis_channels.h new file mode 100644 index 000000000..c5464ba03 --- /dev/null +++ b/include/asterisk/stasis_channels.h @@ -0,0 +1,304 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2013, Digium, Inc. + * + * Matt Jordan <mjordan@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + + +#ifndef STASIS_CHANNELS_H_ +#define STASIS_CHANNELS_H_ + +#include "asterisk/stringfields.h" +#include "asterisk/stasis.h" +#include "asterisk/json.h" +#include "asterisk/channel.h" + +/*! \addtogroup StasisTopicsAndMessages + * @{ + */ + +/*! + * \since 12 + * \brief Structure representing a snapshot of channel state. + * + * While not enforced programmatically, this object is shared across multiple + * threads, and should be threated as an immutable object. + */ +struct ast_channel_snapshot { + AST_DECLARE_STRING_FIELDS( + AST_STRING_FIELD(name); /*!< ASCII unique channel name */ + AST_STRING_FIELD(accountcode); /*!< Account code for billing */ + AST_STRING_FIELD(peeraccount); /*!< Peer account code for billing */ + AST_STRING_FIELD(userfield); /*!< Userfield for CEL billing */ + AST_STRING_FIELD(uniqueid); /*!< Unique Channel Identifier */ + AST_STRING_FIELD(linkedid); /*!< Linked Channel Identifier -- gets propagated by linkage */ + AST_STRING_FIELD(parkinglot); /*!< Default parking lot, if empty, default parking lot */ + AST_STRING_FIELD(hangupsource); /*!< Who is responsible for hanging up this channel */ + AST_STRING_FIELD(appl); /*!< Current application */ + AST_STRING_FIELD(data); /*!< Data passed to current application */ + AST_STRING_FIELD(context); /*!< Dialplan: Current extension context */ + AST_STRING_FIELD(exten); /*!< Dialplan: Current extension number */ + AST_STRING_FIELD(caller_name); /*!< Caller ID Name */ + AST_STRING_FIELD(caller_number); /*!< Caller ID Number */ + AST_STRING_FIELD(connected_name); /*!< Connected Line Name */ + AST_STRING_FIELD(connected_number); /*!< Connected Line Number */ + ); + + struct timeval creationtime; /*!< The time of channel creation */ + enum ast_channel_state state; /*!< State of line */ + int priority; /*!< Dialplan: Current extension priority */ + int amaflags; /*!< AMA flags for billing */ + int hangupcause; /*!< Why is the channel hanged up. See causes.h */ + int caller_pres; /*!< Caller ID presentation. */ + struct ast_flags flags; /*!< channel flags of AST_FLAG_ type */ + struct varshead *manager_vars; /*!< Variables to be appended to manager events */ +}; + +/*! + * \since 12 + * \brief Blob of data associated with a channel. + * + * The \c blob is actually a JSON object of structured data. It has a "type" field + * which contains the type string describing this blob. + */ +struct ast_channel_blob { + /*! Channel blob is associated with (or NULL for global/all channels) */ + struct ast_channel_snapshot *snapshot; + /*! JSON blob of data */ + struct ast_json *blob; +}; + +/*! + * \since 12 + * \brief A set of channels with blob objects - see \ref ast_channel_blob + */ +struct ast_multi_channel_blob; + +/*! + * \since 12 + * \brief A topic which publishes the events for all channels. + * \retval Topic for all channel events. + */ +struct stasis_topic *ast_channel_topic_all(void); + +/*! + * \since 12 + * \brief A caching topic which caches \ref ast_channel_snapshot messages from + * ast_channel_events_all(void). + * + * \retval Topic for all channel events. + */ +struct stasis_caching_topic *ast_channel_topic_all_cached(void); + +/*! + * \since 12 + * \brief Message type for \ref ast_channel_snapshot. + * + * \retval Message type for \ref ast_channel_snapshot. + */ +struct stasis_message_type *ast_channel_snapshot_type(void); + +/*! + * \since 12 + * \brief Message type for \ref ast_channel_blob messages. + * + * \retval Message type for \ref ast_channel_blob messages. + */ +struct stasis_message_type *ast_channel_blob_type(void); + +/*! + * \since 12 + * \brief Generate a snapshot of the channel state. This is an ao2 object, so + * ao2_cleanup() to deallocate. + * + * \param chan The channel from which to generate a snapshot + * + * \retval pointer on success (must be ast_freed) + * \retval NULL on error + */ +struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan); + +/*! + * \since 12 + * \brief Creates a \ref ast_channel_blob message. + * + * The \a blob JSON object requires a \c "type" field describing the blob. It + * should also be treated as immutable and not modified after it is put into the + * message. + * + * \param chan Channel blob is associated with, or NULL for global/all channels. + * \param blob JSON object representing the data. + * \return \ref ast_channel_blob message. + * \return \c NULL on error + */ +struct stasis_message *ast_channel_blob_create(struct ast_channel *chan, + struct ast_json *blob); + +/*! + * \since 12 + * \brief Extracts the type field from a \ref ast_channel_blob. + * Returned \c char* is still owned by \a obj + * \param obj Channel blob object. + * \return Type field value from the blob. + * \return \c NULL on error. + */ +const char *ast_channel_blob_json_type(struct ast_channel_blob *obj); + +/*! + * \since 12 + * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message + * + * \note Similar to a \ref ast_channel_blob, the \ref ast_multi_channel_blob requires + * a \a blob JSON object containing a \c "type" field describing the blob. It + * should also be treated as immutable and not modified after it is put into the + * message. + * + * \param blob The JSON blob that defines the type of this \ref ast_multi_channel_blob + * + * \return \ref ast_multi_channel_blob object + * \return \c NULL on error +*/ +struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob); + +/*! + * \since 12 + * \brief Retrieve a channel snapshot associated with a specific role from a + * \ref ast_multi_channel_blob + * + * \note The reference count of the \ref ast_channel_snapshot returned from + * this function is not changed. The caller of this function does not own the + * reference to the snapshot. + * + * \param obj The \ref ast_multi_channel_blob containing the channel snapshot + * to retrieve + * \param role The role associated with the channel snapshot + * + * \retval \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( + struct ast_multi_channel_blob *obj, + const char *role); + +/*! + * \since 12 + * \brief Retrieve all channel snapshots associated with a specific role from + * a \ref ast_multi_channel_blob + * + * \note Because this function returns an ao2_container (hashed by channel name) + * of all channel snapshots that matched the passed in role, the reference of + * the snapshots is increased by this function. The caller of this function must + * release the reference to the snapshots by disposing of the container + * appropriately. + * + * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to + * retrieve + * \param role The role associated with the channel snapshots + * + * \retval 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 + */ +struct ao2_container *ast_multi_channel_blob_get_channels( + struct ast_multi_channel_blob *obj, + const char *role); + +/*! + * \since 12 + * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob. + * Returned \ref ast_json is still owned by \a obj + * + * \param obj Channel blob object. + * \return Type field value from the blob. + * \return \c NULL on error. + */ +struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj); + +/*! + * \since 12 + * \brief Extracts the type field from a \ref ast_multi_channel_blob. + * Returned \c char* is still owned by \a obj + * + * \param obj Channel blob object. + * \return Type field value from the blob. + * \return \c NULL on error. + */ +const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj); + +/*! + * \since 12 + * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object + * + * \note This will increase the reference count by 1 for the channel snapshot. It is + * assumed that the \ref ast_multi_channel_blob will own a reference to the object. + * + * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot + * \param role A \a role that the snapshot has in the multi channel relationship + * \param snapshot The \ref ast_channel_snapshot being added to the + * \ref ast_multi_channel_blob object + */ +void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj, + const char *role, + struct ast_channel_snapshot *snapshot); + +/*! + * \since 12 + * \brief Publish a \ref ast_channel_varset for a channel. + * + * \param chan Channel to pulish the event for, or \c NULL for 'none'. + * \param variable Name of the variable being set + * \param value Value. + */ +void ast_channel_publish_varset(struct ast_channel *chan, + const char *variable, const char *value); + +/*! + * \since 12 + * \brief Message type for when a channel dials another channel + * + * \retval A stasis message type + */ +struct stasis_message_type *ast_channel_dial_type(void); + +/*! + * \since 12 + * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all + * topics a stasis message for the channels involved in a dial operation. + * + * \param caller The channel performing the dial operation + * \param peer The channel being dialed + * \param dialstring When beginning a dial, the information passed to the + * dialing application + * \param dialstatus The current status of the dial operation (NULL if no + * status is known) + */ +void ast_channel_publish_dial(struct ast_channel *caller, + struct ast_channel *peer, + const char *dialstring, + const char *dialstatus); + +/*! @} */ + +/*! + * \brief Dispose of the stasis channel topics and message types + */ +void ast_stasis_channels_shutdown(void); + +/*! + * \brief Initialize the stasis channel topic and message types + */ +void ast_stasis_channels_init(void); + +#endif /* STASIS_CHANNELS_H_ */ |