include/asterisk/stasis_channels.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2013, Digium, Inc.
   5  *
   6  * Matt Jordan <mjordan@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19
  20 #ifndef STASIS_CHANNELS_H_
  21 #define STASIS_CHANNELS_H_
  22
  23 #include "asterisk/stringfields.h"
  24 #include "asterisk/stasis.h"
  25 #include "asterisk/json.h"
  26 #include "asterisk/channel.h"
  27
  28 /*! \addtogroup StasisTopicsAndMessages
  29  * @{
  30  */
  31
  32 /*!
  33  * \since 12
  34  * \brief Structure representing a snapshot of channel state.
  35  *
  36  * While not enforced programmatically, this object is shared across multiple
  37  * threads, and should be threated as an immutable object.
  38  */
  39 struct ast_channel_snapshot {
  40         AST_DECLARE_STRING_FIELDS(
  41                 AST_STRING_FIELD(name);                 /*!< ASCII unique channel name */
  42                 AST_STRING_FIELD(accountcode);          /*!< Account code for billing */
  43                 AST_STRING_FIELD(peeraccount);          /*!< Peer account code for billing */
  44                 AST_STRING_FIELD(userfield);            /*!< Userfield for CEL billing */
  45                 AST_STRING_FIELD(uniqueid);             /*!< Unique Channel Identifier */
  46                 AST_STRING_FIELD(linkedid);             /*!< Linked Channel Identifier -- gets propagated by linkage */
  47                 AST_STRING_FIELD(parkinglot);           /*!< Default parking lot, if empty, default parking lot */
  48                 AST_STRING_FIELD(hangupsource);         /*!< Who is responsible for hanging up this channel */
  49                 AST_STRING_FIELD(appl);                 /*!< Current application */
  50                 AST_STRING_FIELD(data);                 /*!< Data passed to current application */
  51                 AST_STRING_FIELD(context);              /*!< Dialplan: Current extension context */
  52                 AST_STRING_FIELD(exten);                /*!< Dialplan: Current extension number */
  53                 AST_STRING_FIELD(caller_name);          /*!< Caller ID Name */
  54                 AST_STRING_FIELD(caller_number);        /*!< Caller ID Number */
  55                 AST_STRING_FIELD(connected_name);       /*!< Connected Line Name */
  56                 AST_STRING_FIELD(connected_number);     /*!< Connected Line Number */
  57         );
  58
  59         struct timeval creationtime;    /*!< The time of channel creation */
  60         enum ast_channel_state state;   /*!< State of line */
  61         int priority;                   /*!< Dialplan: Current extension priority */
  62         int amaflags;                   /*!< AMA flags for billing */
  63         int hangupcause;                /*!< Why is the channel hanged up. See causes.h */
  64         int caller_pres;                /*!< Caller ID presentation. */
  65         struct ast_flags flags;         /*!< channel flags of AST_FLAG_ type */
  66         struct varshead *manager_vars;  /*!< Variables to be appended to manager events */
  67 };
  68
  69 /*!
  70  * \since 12
  71  * \brief Blob of data associated with a channel.
  72  *
  73  * The \c blob is actually a JSON object of structured data. It has a "type" field
  74  * which contains the type string describing this blob.
  75  */
  76 struct ast_channel_blob {
  77         /*! Channel blob is associated with (or NULL for global/all channels) */
  78         struct ast_channel_snapshot *snapshot;
  79         /*! JSON blob of data */
  80         struct ast_json *blob;
  81 };
  82
  83 /*!
  84  * \since 12
  85  * \brief A set of channels with blob objects - see \ref ast_channel_blob
  86  */
  87 struct ast_multi_channel_blob;
  88
  89 /*!
  90  * \since 12
  91  * \brief A topic which publishes the events for all channels.
  92  * \retval Topic for all channel events.
  93  */
  94 struct stasis_topic *ast_channel_topic_all(void);
  95
  96 /*!
  97  * \since 12
  98  * \brief A caching topic which caches \ref ast_channel_snapshot messages from
  99  * ast_channel_events_all(void).
 100  *
 101  * \retval Topic for all channel events.
 102  */
 103 struct stasis_caching_topic *ast_channel_topic_all_cached(void);
 104
 105 /*!
 106  * \since 12
 107  * \brief Message type for \ref ast_channel_snapshot.
 108  *
 109  * \retval Message type for \ref ast_channel_snapshot.
 110  */
 111 struct stasis_message_type *ast_channel_snapshot_type(void);
 112
 113 /*!
 114  * \since 12
 115  * \brief Message type for \ref ast_channel_blob messages.
 116  *
 117  * \retval Message type for \ref ast_channel_blob messages.
 118  */
 119 struct stasis_message_type *ast_channel_blob_type(void);
 120
 121 /*!
 122  * \since 12
 123  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
 124  * ao2_cleanup() to deallocate.
 125  *
 126  * \param chan The channel from which to generate a snapshot
 127  *
 128  * \retval pointer on success (must be ast_freed)
 129  * \retval NULL on error
 130  */
 131 struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan);
 132
 133 /*!
 134  * \since 12
 135  * \brief Creates a \ref ast_channel_blob message.
 136  *
 137  * The \a blob JSON object requires a \c "type" field describing the blob. It
 138  * should also be treated as immutable and not modified after it is put into the
 139  * message.
 140  *
 141  * \param chan Channel blob is associated with, or NULL for global/all channels.
 142  * \param blob JSON object representing the data.
 143  * \return \ref ast_channel_blob message.
 144  * \return \c NULL on error
 145  */
 146 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
 147                                                struct ast_json *blob);
 148
 149 /*!
 150  * \since 12
 151  * \brief Extracts the type field from a \ref ast_channel_blob.
 152  * Returned \c char* is still owned by \a obj
 153  * \param obj Channel blob object.
 154  * \return Type field value from the blob.
 155  * \return \c NULL on error.
 156  */
 157 const char *ast_channel_blob_json_type(struct ast_channel_blob *obj);
 158
 159 /*!
 160  * \since 12
 161  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message
 162  *
 163  * \note Similar to a \ref ast_channel_blob, the \ref ast_multi_channel_blob requires
 164  * a \a blob JSON object containing a \c "type" field describing the blob. It
 165  * should also be treated as immutable and not modified after it is put into the
 166  * message.
 167  *
 168  * \param blob The JSON blob that defines the type of this \ref ast_multi_channel_blob
 169  *
 170  * \return \ref ast_multi_channel_blob object
 171  * \return \c NULL on error
 172 */
 173 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
 174
 175 /*!
 176  * \since 12
 177  * \brief Retrieve a channel snapshot associated with a specific role from a
 178  * \ref ast_multi_channel_blob
 179  *
 180  * \note The reference count of the \ref ast_channel_snapshot returned from
 181  * this function is not changed. The caller of this function does not own the
 182  * reference to the snapshot.
 183  *
 184  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
 185  * to retrieve
 186  * \param role The role associated with the channel snapshot
 187  *
 188  * \retval \ref ast_channel_snapshot matching the role on success
 189  * \retval NULL on error or not found for the role specified
 190  */
 191 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
 192                                                struct ast_multi_channel_blob *obj,
 193                                                const char *role);
 194
 195 /*!
 196  * \since 12
 197  * \brief Retrieve all channel snapshots associated with a specific role from
 198  * a \ref ast_multi_channel_blob
 199  *
 200  * \note Because this function returns an ao2_container (hashed by channel name)
 201  * of all channel snapshots that matched the passed in role, the reference of
 202  * the snapshots is increased by this function. The caller of this function must
 203  * release the reference to the snapshots by disposing of the container
 204  * appropriately.
 205  *
 206  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
 207  * retrieve
 208  * \param role The role associated with the channel snapshots
 209  *
 210  * \retval A container containing all \ref ast_channel_snapshot objects matching
 211  * the role on success.
 212  * \retval NULL on error or not found for the role specified
 213  */
 214 struct ao2_container *ast_multi_channel_blob_get_channels(
 215                                                struct ast_multi_channel_blob *obj,
 216                                                const char *role);
 217
 218 /*!
 219  * \since 12
 220  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
 221  * Returned \ref ast_json is still owned by \a obj
 222  *
 223  * \param obj Channel blob object.
 224  * \return Type field value from the blob.
 225  * \return \c NULL on error.
 226  */
 227 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
 228
 229 /*!
 230  * \since 12
 231  * \brief Extracts the type field from a \ref ast_multi_channel_blob.
 232  * Returned \c char* is still owned by \a obj
 233  *
 234  * \param obj Channel blob object.
 235  * \return Type field value from the blob.
 236  * \return \c NULL on error.
 237  */
 238 const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
 239
 240 /*!
 241  * \since 12
 242  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
 243  *
 244  * \note This will increase the reference count by 1 for the channel snapshot. It is
 245  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
 246  *
 247  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
 248  * \param role A \a role that the snapshot has in the multi channel relationship
 249  * \param snapshot The \ref ast_channel_snapshot being added to the
 250  * \ref ast_multi_channel_blob object
 251  */
 252 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
 253                                                const char *role,
 254                                                struct ast_channel_snapshot *snapshot);
 255
 256 /*!
 257  * \since 12
 258  * \brief Publish a \ref ast_channel_varset for a channel.
 259  *
 260  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
 261  * \param variable Name of the variable being set
 262  * \param value Value.
 263  */
 264 void ast_channel_publish_varset(struct ast_channel *chan,
 265                                 const char *variable, const char *value);
 266
 267 /*!
 268  * \since 12
 269  * \brief Message type for when a channel dials another channel
 270  *
 271  * \retval A stasis message type
 272  */
 273 struct stasis_message_type *ast_channel_dial_type(void);
 274
 275 /*!
 276  * \since 12
 277  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
 278  * topics a stasis message for the channels involved in a dial operation.
 279  *
 280  * \param caller The channel performing the dial operation
 281  * \param peer The channel being dialed
 282  * \param dialstring When beginning a dial, the information passed to the
 283  * dialing application
 284  * \param dialstatus The current status of the dial operation (NULL if no
 285  * status is known)
 286  */
 287 void ast_channel_publish_dial(struct ast_channel *caller,
 288                 struct ast_channel *peer,
 289                 const char *dialstring,
 290                 const char *dialstatus);
 291
 292 /*! @} */
 293
 294 /*!
 295  * \brief Build a JSON object from a \ref ast_channel_snapshot.
 296  * \return JSON object representing channel snapshot.
 297  * \return \c NULL on error
 298  */
 299 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
 300
 301 /*!
 302  * \brief Dispose of the stasis channel topics and message types
 303  */
 304 void ast_stasis_channels_shutdown(void);
 305
 306 /*!
 307  * \brief Initialize the stasis channel topic and message types
 308  */
 309 void ast_stasis_channels_init(void);
 310
 311 #endif /* STASIS_CHANNELS_H_ */