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 Create a \ref ast_channel_blob message, pulling channel state from
 159  *        the cache.
 160  *
 161  * \param uniqueid Uniqueid of the channel.
 162  * \param type Message type for this blob.
 163  * \param blob JSON object representing the data, or \c NULL for no data. If
 164  *             \c NULL, ast_json_null() is put into the object.
 165  *
 166  * \return \ref ast_channel_blob message.
 167  * \return \c NULL on error
 168  */
 169 struct stasis_message *ast_channel_blob_create_from_cache(
 170         const char *uniqueid, struct stasis_message_type *type,
 171         struct ast_json *blob);
 172
 173 /*!
 174  * \since 12
 175  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
 176  *
 177  * The given \a blob should be treated as immutable and not modified after it is
 178  * put into the message.
 179  *
 180  * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
 181  *
 182  * \return \ref ast_multi_channel_blob object
 183  * \return \c NULL on error
 184 */
 185 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
 186
 187 /*!
 188  * \since 12
 189  * \brief Retrieve a channel snapshot associated with a specific role from a
 190  * \ref ast_multi_channel_blob
 191  *
 192  * \note The reference count of the \ref ast_channel_snapshot returned from
 193  * this function is not changed. The caller of this function does not own the
 194  * reference to the snapshot.
 195  *
 196  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
 197  * to retrieve
 198  * \param role The role associated with the channel snapshot
 199  *
 200  * \retval \ref ast_channel_snapshot matching the role on success
 201  * \retval NULL on error or not found for the role specified
 202  */
 203 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
 204         struct ast_multi_channel_blob *obj, const char *role);
 205
 206 /*!
 207  * \since 12
 208  * \brief Retrieve all channel snapshots associated with a specific role from
 209  * a \ref ast_multi_channel_blob
 210  *
 211  * \note Because this function returns an ao2_container (hashed by channel name)
 212  * of all channel snapshots that matched the passed in role, the reference of
 213  * the snapshots is increased by this function. The caller of this function must
 214  * release the reference to the snapshots by disposing of the container
 215  * appropriately.
 216  *
 217  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
 218  * retrieve
 219  * \param role The role associated with the channel snapshots
 220  *
 221  * \retval A container containing all \ref ast_channel_snapshot objects matching
 222  * the role on success.
 223  * \retval NULL on error or not found for the role specified
 224  */
 225 struct ao2_container *ast_multi_channel_blob_get_channels(
 226         struct ast_multi_channel_blob *obj, const char *role);
 227
 228 /*!
 229  * \since 12
 230  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
 231  * Returned \ref ast_json is still owned by \a obj
 232  *
 233  * \param obj Channel blob object.
 234  * \return Type field value from the blob.
 235  * \return \c NULL on error.
 236  */
 237 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
 238
 239 /*!
 240  * \since 12
 241  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
 242  *
 243  * \note This will increase the reference count by 1 for the channel snapshot. It is
 244  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
 245  *
 246  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
 247  * \param role A \a role that the snapshot has in the multi channel relationship
 248  * \param snapshot The \ref ast_channel_snapshot being added to the
 249  * \ref ast_multi_channel_blob object
 250  */
 251 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
 252         const char *role, struct ast_channel_snapshot *snapshot);
 253
 254 /*!
 255  * \since 12
 256  * \brief Publish a \ref ast_channel_snapshot for a channel.
 257  *
 258  * \param chan Channel to publish.
 259  */
 260 void ast_channel_publish_snapshot(struct ast_channel *chan);
 261
 262 /*!
 263  * \since 12
 264  * \brief Publish a \ref ast_channel_varset for a channel.
 265  *
 266  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
 267  * \param variable Name of the variable being set
 268  * \param value Value.
 269  */
 270 void ast_channel_publish_varset(struct ast_channel *chan,
 271                                 const char *variable, const char *value);
 272
 273 /*!
 274  * \since 12
 275  * \brief Message type for when a channel dials another channel
 276  *
 277  * \retval A stasis message type
 278  */
 279 struct stasis_message_type *ast_channel_dial_type(void);
 280
 281 /*!
 282  * \since 12
 283  * \brief Message type for when a variable is set on a channel.
 284  *
 285  * \retval A stasis message type
 286  */
 287 struct stasis_message_type *ast_channel_varset_type(void);
 288
 289 /*!
 290  * \since 12
 291  * \brief Message type for when a custom user event is sent on a channel.
 292  *
 293  * \retval A stasis message type
 294  */
 295 struct stasis_message_type *ast_channel_user_event_type(void);
 296
 297 /*!
 298  * \since 12
 299  * \brief Message type for when a hangup is requested on a channel.
 300  *
 301  * \retval A stasis message type
 302  */
 303 struct stasis_message_type *ast_channel_hangup_request_type(void);
 304
 305 /*!
 306  * \since 12
 307  * \brief Message type for when DTMF begins on a channel.
 308  *
 309  * \retval A stasis message type
 310  */
 311 struct stasis_message_type *ast_channel_dtmf_begin_type(void);
 312
 313 /*!
 314  * \since 12
 315  * \brief Message type for when DTMF ends on a channel.
 316  *
 317  * \retval A stasis message type
 318  */
 319 struct stasis_message_type *ast_channel_dtmf_end_type(void);
 320
 321 /*!
 322  * \since 12
 323  * \brief Message type for when a channel is placed on hold.
 324  *
 325  * \retval A stasis message type
 326  */
 327 struct stasis_message_type *ast_channel_hold_type(void);
 328
 329 /*!
 330  * \since 12
 331  * \brief Message type for when a channel is removed from hold.
 332  *
 333  * \retval A stasis message type
 334  */
 335 struct stasis_message_type *ast_channel_unhold_type(void);
 336
 337 /*!
 338  * \since 12
 339  * \brief Message type for when a channel starts spying on another channel
 340  *
 341  * \retval A stasis message type
 342  */
 343 struct stasis_message_type *ast_channel_chanspy_start_type(void);
 344
 345 /*!
 346  * \since 12
 347  * \brief Message type for when a channel stops spying on another channel
 348  *
 349  * \retval A stasis message type
 350  */
 351 struct stasis_message_type *ast_channel_chanspy_stop_type(void);
 352
 353 /*!
 354  * \since 12
 355  * \brief Message type for a fax operation
 356  *
 357  * \retval A stasis message type
 358  */
 359 struct stasis_message_type *ast_channel_fax_type(void);
 360
 361 /*!
 362  * \since 12
 363  * \brief Message type for hangup handler related actions
 364  *
 365  * \retval A stasis message type
 366  */
 367 struct stasis_message_type *ast_channel_hangup_handler_type(void);
 368
 369 /*!
 370  * \since 12
 371  * \brief Message type for starting monitor on a channel
 372  *
 373  * \retval A stasis message type
 374  */
 375 struct stasis_message_type *ast_channel_monitor_start_type(void);
 376
 377 /*!
 378  * \since 12
 379  * \brief Message type for stopping monitor on a channel
 380  *
 381  * \retval A stasis message type
 382  */
 383 struct stasis_message_type *ast_channel_monitor_stop_type(void);
 384
 385 /*!
 386  * \since 12
 387  * \brief Message type for starting music on hold on a channel
 388  *
 389  * \retval A stasis message type
 390  */
 391 struct stasis_message_type *ast_channel_moh_start_type(void);
 392
 393 /*!
 394  * \since 12
 395  * \brief Message type for stopping music on hold on a channel
 396  *
 397  * \retval A stasis message type
 398  */
 399 struct stasis_message_type *ast_channel_moh_stop_type(void);
 400
 401 /*!
 402  * \since 12
 403  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
 404  * topics a stasis message for the channels involved in a dial operation.
 405  *
 406  * \param caller The channel performing the dial operation
 407  * \param peer The channel being dialed
 408  * \param dialstring When beginning a dial, the information passed to the
 409  * dialing application
 410  * \param dialstatus The current status of the dial operation (NULL if no
 411  * status is known)
 412  */
 413 void ast_channel_publish_dial(struct ast_channel *caller,
 414                 struct ast_channel *peer,
 415                 const char *dialstring,
 416                 const char *dialstatus);
 417
 418 /*!
 419  * \since 12
 420  * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
 421  * message indicating a change in channel state
 422  *
 423  * \param chan The channel whose state has changed
 424  */
 425 void ast_publish_channel_state(struct ast_channel *chan);
 426
 427 /*! @} */
 428
 429 /*!
 430  * \brief Build a JSON object from a \ref ast_channel_snapshot.
 431  * \return JSON object representing channel snapshot.
 432  * \return \c NULL on error
 433  */
 434 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
 435
 436 /*!
 437  * \brief Compares the context, exten and priority of two snapshots.
 438  * \since 12
 439  *
 440  * \param old_snapshot Old snapshot
 441  * \param new_snapshot New snapshot
 442  *
 443  * \return True (non-zero) if context, exten or priority are identical.
 444  * \return False (zero) if context, exten and priority changed.
 445  */
 446 int ast_channel_snapshot_cep_equal(
 447         const struct ast_channel_snapshot *old_snapshot,
 448         const struct ast_channel_snapshot *new_snapshot);
 449
 450 /*!
 451  * \brief Compares the callerid info of two snapshots.
 452  * \since 12
 453  *
 454  * \param old_snapshot Old snapshot
 455  * \param new_snapshot New snapshot
 456  *
 457  * \return True (non-zero) if callerid are identical.
 458  * \return False (zero) if callerid changed.
 459  */
 460 int ast_channel_snapshot_caller_id_equal(
 461         const struct ast_channel_snapshot *old_snapshot,
 462         const struct ast_channel_snapshot *new_snapshot);
 463
 464 /*!
 465  * \brief Dispose of the stasis channel topics and message types
 466  */
 467 void ast_stasis_channels_shutdown(void);
 468
 469 /*!
 470  * \brief Initialize the stasis channel topic and message types
 471  */
 472 void ast_stasis_channels_init(void);
 473
 474 #endif /* STASIS_CHANNELS_H_ */