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 treated 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  * This blob is actually shared amongst several \ref stasis_message_type's.
  74  */
  75 struct ast_channel_blob {
  76         /*! Channel blob is associated with (or NULL for global/all channels) */
  77         struct ast_channel_snapshot *snapshot;
  78         /*! JSON blob of data */
  79         struct ast_json *blob;
  80 };
  81
  82 /*!
  83  * \since 12
  84  * \brief A set of channels with blob objects - see \ref ast_channel_blob
  85  */
  86 struct ast_multi_channel_blob;
  87
  88 /*!
  89  * \since 12
  90  * \brief A topic which publishes the events for all channels.
  91  * \retval Topic for all channel events.
  92  */
  93 struct stasis_topic *ast_channel_topic_all(void);
  94
  95 /*!
  96  * \since 12
  97  * \brief A caching topic which caches \ref ast_channel_snapshot messages from
  98  * ast_channel_events_all(void).
  99  *
 100  * \retval Topic for all channel events.
 101  */
 102 struct stasis_caching_topic *ast_channel_topic_all_cached(void);
 103
 104 /*!
 105  * \since 12
 106  * \brief Message type for \ref ast_channel_snapshot.
 107  *
 108  * \retval Message type for \ref ast_channel_snapshot.
 109  */
 110 struct stasis_message_type *ast_channel_snapshot_type(void);
 111
 112 /*!
 113  * \since 12
 114  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
 115  * ao2_cleanup() to deallocate.
 116  *
 117  * \param chan The channel from which to generate a snapshot
 118  *
 119  * \retval pointer on success (must be ast_freed)
 120  * \retval NULL on error
 121  */
 122 struct ast_channel_snapshot *ast_channel_snapshot_create(
 123         struct ast_channel *chan);
 124
 125 /*!
 126  * \since 12
 127  * \brief Creates a \ref ast_channel_blob message.
 128  *
 129  * The given \a blob should be treated as immutable and not modified after it is
 130  * put into the message.
 131  *
 132  * \param chan Channel blob is associated with, or \c NULL for global/all channels.
 133  * \param type Message type for this blob.
 134  * \param blob JSON object representing the data, or \c NULL for no data. If
 135  *             \c NULL, ast_json_null() is put into the object.
 136  *
 137  * \return \ref ast_channel_blob message.
 138  * \return \c NULL on error
 139  */
 140 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
 141         struct stasis_message_type *type, struct ast_json *blob);
 142
 143 /*!
 144  * \since 12
 145  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
 146  *
 147  * The given \a blob should be treated as immutable and not modified after it is
 148  * put into the message.
 149  *
 150  * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
 151  *
 152  * \return \ref ast_multi_channel_blob object
 153  * \return \c NULL on error
 154 */
 155 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
 156
 157 /*!
 158  * \since 12
 159  * \brief Retrieve a channel snapshot associated with a specific role from a
 160  * \ref ast_multi_channel_blob
 161  *
 162  * \note The reference count of the \ref ast_channel_snapshot returned from
 163  * this function is not changed. The caller of this function does not own the
 164  * reference to the snapshot.
 165  *
 166  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
 167  * to retrieve
 168  * \param role The role associated with the channel snapshot
 169  *
 170  * \retval \ref ast_channel_snapshot matching the role on success
 171  * \retval NULL on error or not found for the role specified
 172  */
 173 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
 174         struct ast_multi_channel_blob *obj, const char *role);
 175
 176 /*!
 177  * \since 12
 178  * \brief Retrieve all channel snapshots associated with a specific role from
 179  * a \ref ast_multi_channel_blob
 180  *
 181  * \note Because this function returns an ao2_container (hashed by channel name)
 182  * of all channel snapshots that matched the passed in role, the reference of
 183  * the snapshots is increased by this function. The caller of this function must
 184  * release the reference to the snapshots by disposing of the container
 185  * appropriately.
 186  *
 187  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
 188  * retrieve
 189  * \param role The role associated with the channel snapshots
 190  *
 191  * \retval A container containing all \ref ast_channel_snapshot objects matching
 192  * the role on success.
 193  * \retval NULL on error or not found for the role specified
 194  */
 195 struct ao2_container *ast_multi_channel_blob_get_channels(
 196         struct ast_multi_channel_blob *obj, const char *role);
 197
 198 /*!
 199  * \since 12
 200  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
 201  * Returned \ref ast_json is still owned by \a obj
 202  *
 203  * \param obj Channel blob object.
 204  * \return Type field value from the blob.
 205  * \return \c NULL on error.
 206  */
 207 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
 208
 209 /*!
 210  * \since 12
 211  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
 212  *
 213  * \note This will increase the reference count by 1 for the channel snapshot. It is
 214  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
 215  *
 216  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
 217  * \param role A \a role that the snapshot has in the multi channel relationship
 218  * \param snapshot The \ref ast_channel_snapshot being added to the
 219  * \ref ast_multi_channel_blob object
 220  */
 221 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
 222         const char *role, struct ast_channel_snapshot *snapshot);
 223
 224 /*!
 225  * \since 12
 226  * \brief Publish a \ref ast_channel_varset for a channel.
 227  *
 228  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
 229  * \param variable Name of the variable being set
 230  * \param value Value.
 231  */
 232 void ast_channel_publish_varset(struct ast_channel *chan,
 233                                 const char *variable, const char *value);
 234
 235 /*!
 236  * \since 12
 237  * \brief Message type for when a channel dials another channel
 238  *
 239  * \retval A stasis message type
 240  */
 241 struct stasis_message_type *ast_channel_dial_type(void);
 242
 243 /*!
 244  * \since 12
 245  * \brief Message type for when a variable is set on a channel.
 246  *
 247  * \retval A stasis message type
 248  */
 249 struct stasis_message_type *ast_channel_varset_type(void);
 250
 251 /*!
 252  * \since 12
 253  * \brief Message type for when a custom user event is sent on a channel.
 254  *
 255  * \retval A stasis message type
 256  */
 257 struct stasis_message_type *ast_channel_user_event_type(void);
 258
 259 /*!
 260  * \since 12
 261  * \brief Message type for when a hangup is requested on a channel.
 262  *
 263  * \retval A stasis message type
 264  */
 265 struct stasis_message_type *ast_channel_hangup_request_type(void);
 266
 267 /*!
 268  * \since 12
 269  * \brief Message type for when DTMF begins on a channel.
 270  *
 271  * \retval A stasis message type
 272  */
 273 struct stasis_message_type *ast_channel_dtmf_begin_type(void);
 274
 275 /*!
 276  * \since 12
 277  * \brief Message type for when DTMF ends on a channel.
 278  *
 279  * \retval A stasis message type
 280  */
 281 struct stasis_message_type *ast_channel_dtmf_end_type(void);
 282
 283 /*!
 284  * \since 12
 285  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
 286  * topics a stasis message for the channels involved in a dial operation.
 287  *
 288  * \param caller The channel performing the dial operation
 289  * \param peer The channel being dialed
 290  * \param dialstring When beginning a dial, the information passed to the
 291  * dialing application
 292  * \param dialstatus The current status of the dial operation (NULL if no
 293  * status is known)
 294  */
 295 void ast_channel_publish_dial(struct ast_channel *caller,
 296                 struct ast_channel *peer,
 297                 const char *dialstring,
 298                 const char *dialstatus);
 299
 300 /*! @} */
 301
 302 /*!
 303  * \brief Build a JSON object from a \ref ast_channel_snapshot.
 304  * \return JSON object representing channel snapshot.
 305  * \return \c NULL on error
 306  */
 307 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
 308
 309 /*!
 310  * \brief Dispose of the stasis channel topics and message types
 311  */
 312 void ast_stasis_channels_shutdown(void);
 313
 314 /*!
 315  * \brief Initialize the stasis channel topic and message types
 316  */
 317 void ast_stasis_channels_init(void);
 318
 319 #endif /* STASIS_CHANNELS_H_ */