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