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                 AST_STRING_FIELD(language);             /*!< The default spoken language for the channel */
  58         );
  59
  60         struct timeval creationtime;    /*!< The time of channel creation */
  61         enum ast_channel_state state;   /*!< State of line */
  62         int priority;                   /*!< Dialplan: Current extension priority */
  63         int amaflags;                   /*!< AMA flags for billing */
  64         int hangupcause;                /*!< Why is the channel hanged up. See causes.h */
  65         int caller_pres;                /*!< Caller ID presentation. */
  66         struct ast_flags flags;         /*!< channel flags of AST_FLAG_ type */
  67         struct varshead *manager_vars;  /*!< Variables to be appended to manager events */
  68 };
  69
  70 /*!
  71  * \since 12
  72  * \brief Blob of data associated with a channel.
  73  *
  74  * This blob is actually shared amongst several \ref stasis_message_type's.
  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 Generate a snapshot of the channel state. This is an ao2 object, so
 116  * ao2_cleanup() to deallocate.
 117  *
 118  * \param chan The channel from which to generate a snapshot
 119  *
 120  * \retval pointer on success (must be ast_freed)
 121  * \retval NULL on error
 122  */
 123 struct ast_channel_snapshot *ast_channel_snapshot_create(
 124         struct ast_channel *chan);
 125
 126 /*!
 127  * \since 12
 128  * \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
 129  * an ao2 object, so use \ref ao2_cleanup() to deallocate.
 130  *
 131  * \param unique_id The channel's unique ID
 132  *
 133  * \retval A \ref ast_channel_snapshot on success
 134  * \retval NULL on error
 135  */
 136 struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniqueid);
 137
 138 /*!
 139  * \since 12
 140  * \brief Creates a \ref ast_channel_blob message.
 141  *
 142  * The given \a blob should be treated as immutable and not modified after it is
 143  * put into the message.
 144  *
 145  * \param chan Channel blob is associated with, or \c NULL for global/all channels.
 146  * \param type Message type for this blob.
 147  * \param blob JSON object representing the data, or \c NULL for no data. If
 148  *             \c NULL, ast_json_null() is put into the object.
 149  *
 150  * \return \ref ast_channel_blob message.
 151  * \return \c NULL on error
 152  */
 153 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
 154         struct stasis_message_type *type, struct ast_json *blob);
 155
 156 /*!
 157  * \since 12
 158  * \brief Creates a \ref ast_channel_blob message using the current cached
 159  * \ref ast_channel_snapshot for the passed in \ref ast_channel
 160  *
 161  * The given \a blob should be treated as immutable and not modified after it is
 162  * put into the message.
 163  *
 164  * \param chan Channel blob is associated with, or \c NULL for global/all channels.
 165  * \param type Message type for this blob.
 166  * \param blob JSON object representing the data, or \c NULL for no data. If
 167  *             \c NULL, ast_json_null() is put into the object.
 168  *
 169  * \param chan Channel blob is associated with
 170  * \param blob JSON object representing the data.
 171  * \return \ref ast_channel_blob message.
 172  * \return \c NULL on error
 173  */
 174 struct stasis_message *ast_channel_cached_blob_create(struct ast_channel *chan,
 175         struct stasis_message_type *type, struct ast_json *blob);
 176
 177 /*!
 178  * \since 12
 179  * \brief Create a \ref ast_channel_blob message, pulling channel state from
 180  *        the cache.
 181  *
 182  * \param uniqueid Uniqueid of the channel.
 183  * \param type Message type for this blob.
 184  * \param blob JSON object representing the data, or \c NULL for no data. If
 185  *             \c NULL, ast_json_null() is put into the object.
 186  *
 187  * \return \ref ast_channel_blob message.
 188  * \return \c NULL on error
 189  */
 190 struct stasis_message *ast_channel_blob_create_from_cache(
 191         const char *uniqueid, struct stasis_message_type *type,
 192         struct ast_json *blob);
 193
 194 /*!
 195  * \since 12
 196  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
 197  *
 198  * The given \a blob should be treated as immutable and not modified after it is
 199  * put into the message.
 200  *
 201  * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
 202  *
 203  * \return \ref ast_multi_channel_blob object
 204  * \return \c NULL on error
 205 */
 206 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
 207
 208 /*!
 209  * \since 12
 210  * \brief Retrieve a channel snapshot associated with a specific role from a
 211  * \ref ast_multi_channel_blob
 212  *
 213  * \note The reference count of the \ref ast_channel_snapshot returned from
 214  * this function is not changed. The caller of this function does not own the
 215  * reference to the snapshot.
 216  *
 217  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
 218  * to retrieve
 219  * \param role The role associated with the channel snapshot
 220  *
 221  * \retval \ref ast_channel_snapshot matching the role on success
 222  * \retval NULL on error or not found for the role specified
 223  */
 224 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
 225         struct ast_multi_channel_blob *obj, const char *role);
 226
 227 /*!
 228  * \since 12
 229  * \brief Retrieve all channel snapshots associated with a specific role from
 230  * a \ref ast_multi_channel_blob
 231  *
 232  * \note Because this function returns an ao2_container (hashed by channel name)
 233  * of all channel snapshots that matched the passed in role, the reference of
 234  * the snapshots is increased by this function. The caller of this function must
 235  * release the reference to the snapshots by disposing of the container
 236  * appropriately.
 237  *
 238  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
 239  * retrieve
 240  * \param role The role associated with the channel snapshots
 241  *
 242  * \retval A container containing all \ref ast_channel_snapshot objects matching
 243  * the role on success.
 244  * \retval NULL on error or not found for the role specified
 245  */
 246 struct ao2_container *ast_multi_channel_blob_get_channels(
 247         struct ast_multi_channel_blob *obj, const char *role);
 248
 249 /*!
 250  * \since 12
 251  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
 252  * Returned \ref ast_json is still owned by \a obj
 253  *
 254  * \param obj Channel blob object.
 255  * \return Type field value from the blob.
 256  * \return \c NULL on error.
 257  */
 258 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
 259
 260 /*!
 261  * \since 12
 262  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
 263  *
 264  * \note This will increase the reference count by 1 for the channel snapshot. It is
 265  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
 266  *
 267  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
 268  * \param role A \a role that the snapshot has in the multi channel relationship
 269  * \param snapshot The \ref ast_channel_snapshot being added to the
 270  * \ref ast_multi_channel_blob object
 271  */
 272 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
 273         const char *role, struct ast_channel_snapshot *snapshot);
 274
 275 /*!
 276  * \since 12
 277  * \brief Publish a \ref ast_channel_snapshot for a channel.
 278  *
 279  * \param chan Channel to publish.
 280  */
 281 void ast_channel_publish_snapshot(struct ast_channel *chan);
 282
 283 /*!
 284  * \since 12
 285  * \brief Publish a \ref ast_channel_varset for a channel.
 286  *
 287  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
 288  * \param variable Name of the variable being set
 289  * \param value Value.
 290  */
 291 void ast_channel_publish_varset(struct ast_channel *chan,
 292                                 const char *variable, const char *value);
 293
 294 /*!
 295  * \since 12
 296  * \brief Message type for when a channel dials another channel
 297  *
 298  * \retval A stasis message type
 299  */
 300 struct stasis_message_type *ast_channel_dial_type(void);
 301
 302 /*!
 303  * \since 12
 304  * \brief Message type for when a variable is set on a channel.
 305  *
 306  * \retval A stasis message type
 307  */
 308 struct stasis_message_type *ast_channel_varset_type(void);
 309
 310 /*!
 311  * \since 12
 312  * \brief Message type for when a custom user event is sent on a channel.
 313  *
 314  * \retval A stasis message type
 315  */
 316 struct stasis_message_type *ast_channel_user_event_type(void);
 317
 318 /*!
 319  * \since 12
 320  * \brief Message type for when a hangup is requested on a channel.
 321  *
 322  * \retval A stasis message type
 323  */
 324 struct stasis_message_type *ast_channel_hangup_request_type(void);
 325
 326 /*!
 327  * \since 12
 328  * \brief Message type for when DTMF begins on a channel.
 329  *
 330  * \retval A stasis message type
 331  */
 332 struct stasis_message_type *ast_channel_dtmf_begin_type(void);
 333
 334 /*!
 335  * \since 12
 336  * \brief Message type for when DTMF ends on a channel.
 337  *
 338  * \retval A stasis message type
 339  */
 340 struct stasis_message_type *ast_channel_dtmf_end_type(void);
 341
 342 /*!
 343  * \since 12
 344  * \brief Message type for when a channel is placed on hold.
 345  *
 346  * \retval A stasis message type
 347  */
 348 struct stasis_message_type *ast_channel_hold_type(void);
 349
 350 /*!
 351  * \since 12
 352  * \brief Message type for when a channel is removed from hold.
 353  *
 354  * \retval A stasis message type
 355  */
 356 struct stasis_message_type *ast_channel_unhold_type(void);
 357
 358 /*!
 359  * \since 12
 360  * \brief Message type for when a channel starts spying on another channel
 361  *
 362  * \retval A stasis message type
 363  */
 364 struct stasis_message_type *ast_channel_chanspy_start_type(void);
 365
 366 /*!
 367  * \since 12
 368  * \brief Message type for when a channel stops spying on another channel
 369  *
 370  * \retval A stasis message type
 371  */
 372 struct stasis_message_type *ast_channel_chanspy_stop_type(void);
 373
 374 /*!
 375  * \since 12
 376  * \brief Message type for a fax operation
 377  *
 378  * \retval A stasis message type
 379  */
 380 struct stasis_message_type *ast_channel_fax_type(void);
 381
 382 /*!
 383  * \since 12
 384  * \brief Message type for hangup handler related actions
 385  *
 386  * \retval A stasis message type
 387  */
 388 struct stasis_message_type *ast_channel_hangup_handler_type(void);
 389
 390 /*!
 391  * \since 12
 392  * \brief Message type for starting monitor on a channel
 393  *
 394  * \retval A stasis message type
 395  */
 396 struct stasis_message_type *ast_channel_monitor_start_type(void);
 397
 398 /*!
 399  * \since 12
 400  * \brief Message type for stopping monitor on a channel
 401  *
 402  * \retval A stasis message type
 403  */
 404 struct stasis_message_type *ast_channel_monitor_stop_type(void);
 405
 406 /*!
 407  * \since 12
 408  * \brief Message type for starting music on hold on a channel
 409  *
 410  * \retval A stasis message type
 411  */
 412 struct stasis_message_type *ast_channel_moh_start_type(void);
 413
 414 /*!
 415  * \since 12
 416  * \brief Message type for stopping music on hold on a channel
 417  *
 418  * \retval A stasis message type
 419  */
 420 struct stasis_message_type *ast_channel_moh_stop_type(void);
 421
 422 /*!
 423  * \since 12
 424  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
 425  * topics a stasis message for the channels involved in a dial operation.
 426  *
 427  * \param caller The channel performing the dial operation
 428  * \param peer The channel being dialed
 429  * \param dialstring When beginning a dial, the information passed to the
 430  * dialing application
 431  * \param dialstatus The current status of the dial operation (NULL if no
 432  * status is known)
 433  */
 434 void ast_channel_publish_dial(struct ast_channel *caller,
 435                 struct ast_channel *peer,
 436                 const char *dialstring,
 437                 const char *dialstatus);
 438
 439 /*!
 440  * \since 12
 441  * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
 442  * message indicating a change in channel state
 443  *
 444  * \param chan The channel whose state has changed
 445  */
 446 void ast_publish_channel_state(struct ast_channel *chan);
 447
 448 /*! @} */
 449
 450 /*!
 451  * \brief Build a JSON object from a \ref ast_channel_snapshot.
 452  * \return JSON object representing channel snapshot.
 453  * \return \c NULL on error
 454  */
 455 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
 456
 457 /*!
 458  * \brief Compares the context, exten and priority of two snapshots.
 459  * \since 12
 460  *
 461  * \param old_snapshot Old snapshot
 462  * \param new_snapshot New snapshot
 463  *
 464  * \return True (non-zero) if context, exten or priority are identical.
 465  * \return False (zero) if context, exten and priority changed.
 466  */
 467 int ast_channel_snapshot_cep_equal(
 468         const struct ast_channel_snapshot *old_snapshot,
 469         const struct ast_channel_snapshot *new_snapshot);
 470
 471 /*!
 472  * \brief Compares the callerid info of two snapshots.
 473  * \since 12
 474  *
 475  * \param old_snapshot Old snapshot
 476  * \param new_snapshot New snapshot
 477  *
 478  * \return True (non-zero) if callerid are identical.
 479  * \return False (zero) if callerid changed.
 480  */
 481 int ast_channel_snapshot_caller_id_equal(
 482         const struct ast_channel_snapshot *old_snapshot,
 483         const struct ast_channel_snapshot *new_snapshot);
 484
 485 /*!
 486  * \brief Dispose of the stasis channel topics and message types
 487  */
 488 void ast_stasis_channels_shutdown(void);
 489
 490 /*!
 491  * \brief Initialize the stasis channel topic and message types
 492  */
 493 void ast_stasis_channels_init(void);
 494
 495 #endif /* STASIS_CHANNELS_H_ */