include/asterisk/stasis_bridging.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2013 Digium, Inc.
   5  *
   6  * Kinsey Moore <kmoore@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 #ifndef _STASIS_BRIDGING_H
  20 #define _STASIS_BRIDGING_H
  21
  22 #if defined(__cplusplus) || defined(c_plusplus)
  23 extern "C" {
  24 #endif
  25
  26 #include "asterisk/stringfields.h"
  27 #include "asterisk/utils.h"
  28 #include "asterisk/lock.h"
  29 #include "asterisk/linkedlists.h"
  30 #include "asterisk/channel.h"
  31 #include "asterisk/bridging.h"
  32 #include "asterisk/pbx.h"
  33
  34 /*!
  35  * \brief Structure that contains a snapshot of information about a bridge
  36  */
  37 struct ast_bridge_snapshot {
  38         AST_DECLARE_STRING_FIELDS(
  39                 /*! Immutable bridge UUID. */
  40                 AST_STRING_FIELD(uniqueid);
  41                 /*! Bridge technology that is handling the bridge */
  42                 AST_STRING_FIELD(technology);
  43                 /*! Bridge subclass that is handling the bridge */
  44                 AST_STRING_FIELD(subclass);
  45         );
  46         /*! AO2 container of bare channel uniqueid strings participating in the bridge.
  47          * Allocated from ast_str_container_alloc() */
  48         struct ao2_container *channels;
  49         /*! Bridge flags to tweak behavior */
  50         struct ast_flags feature_flags;
  51         /*! Bridge capabilities */
  52         uint32_t capabilities;
  53         /*! Number of channels participating in the bridge */
  54         unsigned int num_channels;
  55         /*! Number of active channels in the bridge. */
  56         unsigned int num_active;
  57 };
  58
  59 /*!
  60  * \since 12
  61  * \brief Generate a snapshot of the bridge state. This is an ao2 object, so
  62  * ao2_cleanup() to deallocate.
  63  *
  64  * \param bridge The bridge from which to generate a snapshot
  65  *
  66  * \retval AO2 refcounted snapshot on success
  67  * \retval NULL on error
  68  */
  69 struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge);
  70
  71 /*!
  72  * \since 12
  73  * \brief Message type for \ref ast_bridge_snapshot.
  74  *
  75  * \retval Message type for \ref ast_bridge_snapshot.
  76  */
  77 struct stasis_message_type *ast_bridge_snapshot_type(void);
  78
  79 /*!
  80  * \since 12
  81  * \brief A topic which publishes the events for a particular bridge.
  82  *
  83  * If the given \a bridge is \c NULL, ast_bridge_topic_all() is returned.
  84  *
  85  * \param bridge Bridge for which to get a topic or \c NULL.
  86  *
  87  * \retval Topic for bridge's events.
  88  * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
  89  */
  90 struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
  91
  92 /*!
  93  * \since 12
  94  * \brief A topic which publishes the events for all bridges.
  95  * \retval Topic for all bridge events.
  96  */
  97 struct stasis_topic *ast_bridge_topic_all(void);
  98
  99 /*!
 100  * \since 12
 101  * \brief A caching topic which caches \ref ast_bridge_snapshot messages from
 102  * ast_bridge_events_all(void).
 103  *
 104  * \retval Caching topic for all bridge events.
 105  */
 106 struct stasis_caching_topic *ast_bridge_topic_all_cached(void);
 107
 108 /*!
 109  * \since 12
 110  * \brief Publish the state of a bridge
 111  *
 112  * \param bridge The bridge for which to publish state
 113  */
 114 void ast_bridge_publish_state(struct ast_bridge *bridge);
 115
 116 /*! \brief Message representing the merge of two bridges */
 117 struct ast_bridge_merge_message {
 118         struct ast_bridge_snapshot *from;       /*!< Bridge from which channels will be removed during the merge */
 119         struct ast_bridge_snapshot *to;         /*!< Bridge to which channels will be added during the merge */
 120 };
 121
 122 /*!
 123  * \since 12
 124  * \brief Message type for \ref ast_bridge_merge_message.
 125  *
 126  * \retval Message type for \ref ast_bridge_merge_message.
 127  */
 128 struct stasis_message_type *ast_bridge_merge_message_type(void);
 129
 130 /*!
 131  * \since 12
 132  * \brief Publish a bridge merge
 133  *
 134  * \param to The bridge to which channels are being added
 135  * \param from The bridge from which channels are being removed
 136  */
 137 void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from);
 138
 139 /*!
 140  * \since 12
 141  * \brief Blob of data associated with a bridge.
 142  *
 143  * The \c blob is actually a JSON object of structured data. It has a "type" field
 144  * which contains the type string describing this blob.
 145  */
 146 struct ast_bridge_blob {
 147         /*! Bridge blob is associated with (or NULL for global/all bridges) */
 148         struct ast_bridge_snapshot *bridge;
 149         /*! Channel blob is associated with (may be NULL for some messages) */
 150         struct ast_channel_snapshot *channel;
 151         /*! JSON blob of data */
 152         struct ast_json *blob;
 153 };
 154
 155 /*!
 156  * \since 12
 157  * \brief Message type for \ref channel enter bridge blob messages.
 158  *
 159  * \retval Message type for \ref channel enter bridge blob messages.
 160  */
 161 struct stasis_message_type *ast_channel_entered_bridge_type(void);
 162
 163 /*!
 164  * \since 12
 165  * \brief Message type for \ref channel leave bridge blob messages.
 166  *
 167  * \retval Message type for \ref channel leave bridge blob messages.
 168  */
 169 struct stasis_message_type *ast_channel_left_bridge_type(void);
 170
 171 /*!
 172  * \since 12
 173  * \brief Creates a \ref ast_bridge_blob message.
 174  *
 175  * The \a blob JSON object requires a \c "type" field describing the blob. It
 176  * should also be treated as immutable and not modified after it is put into the
 177  * message.
 178  *
 179  * \param bridge Channel blob is associated with, or NULL for global/all bridges.
 180  * \param blob JSON object representing the data.
 181  * \return \ref ast_bridge_blob message.
 182  * \return \c NULL on error
 183  */
 184 struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
 185         struct ast_bridge *bridge,
 186         struct ast_channel *chan,
 187         struct ast_json *blob);
 188
 189 /*!
 190  * \since 12
 191  * \brief Publish a bridge channel enter event
 192  *
 193  * \param bridge The bridge a channel entered
 194  * \param chan The channel that entered the bridge
 195  */
 196 void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan);
 197
 198 /*!
 199  * \since 12
 200  * \brief Publish a bridge channel leave event
 201  *
 202  * \param bridge The bridge a channel left
 203  * \param chan The channel that left the bridge
 204  */
 205 void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan);
 206
 207 /*!
 208  * \brief Build a JSON object from a \ref ast_bridge_snapshot.
 209  * \return JSON object representing bridge snapshot.
 210  * \return \c NULL on error
 211  */
 212 struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot);
 213
 214 /*!
 215  * \brief Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge
 216  */
 217 struct ast_bridge_channel_snapshot_pair {
 218         struct ast_bridge_snapshot *bridge_snapshot;
 219         struct ast_channel_snapshot *channel_snapshot;
 220 };
 221
 222 /*!
 223  * \brief Pair showing a bridge and a specific channel belonging to the bridge
 224  */
 225 struct ast_bridge_channel_pair {
 226         struct ast_bridge *bridge;
 227         struct ast_channel *channel;
 228 };
 229
 230 /*!
 231  * \since 12
 232  * \brief Message type for \ref ast_blind_transfer_message.
 233  *
 234  * \retval Message type for \ref ast_blind_transfer_message.
 235  */
 236 struct stasis_message_type *ast_blind_transfer_type(void);
 237
 238 /*!
 239  * \brief Publish a blind transfer event
 240  *
 241  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
 242  * \param result The success or failure of the transfer
 243  * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
 244  * \param context The destination context for the blind transfer
 245  * \param exten The destination extension for the blind transfer
 246  */
 247 void ast_bridge_publish_blind_transfer(int is_external, enum ast_transfer_result result,
 248                 struct ast_bridge_channel_pair *to_transferee, const char *context, const char *exten);
 249
 250 enum ast_attended_transfer_dest_type {
 251         /*! The transfer failed, so there is no appropriate final state */
 252         AST_ATTENDED_TRANSFER_DEST_FAIL,
 253         /*! The transfer results in a single bridge remaining due to a merge or swap */
 254         AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE,
 255         /*! The transfer results in a channel or bridge running an application */
 256         AST_ATTENDED_TRANSFER_DEST_APP,
 257         /*! The transfer results in both bridges remaining with a local channel linking them */
 258         AST_ATTENDED_TRANSFER_DEST_LINK,
 259 };
 260
 261 /*!
 262  * \brief Message representing attended transfer
 263  */
 264 struct ast_attended_transfer_message {
 265         /*! Result of the attended transfer */
 266         enum ast_transfer_result result;
 267         /*! Indicates if the transfer was initiated externally*/
 268         int is_external;
 269         /*! Bridge between transferer <-> transferee and the transferer channel in that bridge. May be NULL */
 270         struct ast_bridge_channel_snapshot_pair to_transferee;
 271         /*! Bridge between transferer <-> transfer target and the transferer channel in that bridge. May be NULL */
 272         struct ast_bridge_channel_snapshot_pair to_transfer_target;
 273         /*! Indicates the final state of the transfer */
 274         enum ast_attended_transfer_dest_type dest_type;
 275         union {
 276                 /*! ID of the surviving bridge. Applicable for AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE */
 277                 char bridge[AST_UUID_STR_LEN];
 278                 /*! Destination application of transfer. Applicable for AST_ATTENDED_TRANSFER_DEST_APP */
 279                 char app[AST_MAX_APP];
 280                 /*! Pair of local channels linking the bridges. Applicable for AST_ATTENDED_TRANSFER_DEST_LINK */
 281                 struct ast_channel_snapshot *links[2];
 282         } dest;
 283 };
 284
 285 /*!
 286  * \since 12
 287  * \brief Message type for \ref ast_attended_transfer_message.
 288  *
 289  * \retval Message type for \ref ast_attended_transfer_message.
 290  */
 291 struct stasis_message_type *ast_attended_transfer_type(void);
 292
 293 /*!
 294  * \since 12
 295  * \brief Publish an attended transfer failure
 296  *
 297  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 298  * \c AST_ATTENDED_TRANSFER_DEST_FAIL.
 299  *
 300  * \param is_external Indicates if the transfer was initiated externally
 301  * \param result The result of the transfer. Will always be a type of failure.
 302  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 303  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 304  */
 305 void ast_bridge_publish_attended_transfer_fail(int is_external, enum ast_transfer_result result,
 306                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target);
 307
 308 /*!
 309  * \since 12
 310  * \brief Publish an attended transfer that results in two bridges becoming one.
 311  *
 312  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 313  * \c AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE. This type of attended transfer results from
 314  * having two bridges involved and either
 315  *
 316  * \li Merging the two bridges together
 317  * \li Moving a channel from one bridge to the other, thus emptying a bridge
 318  *
 319  * In either case, two bridges enter, one leaves.
 320  *
 321  * \param is_external Indicates if the transfer was initiated externally
 322  * \param result The result of the transfer.
 323  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 324  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 325  * \param final_bridge The bridge that the parties end up in. Will be a bridge from the transferee or target pair.
 326  */
 327 void ast_bridge_publish_attended_transfer_bridge_merge(int is_external, enum ast_transfer_result result,
 328                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 329                 struct ast_bridge *final_bridge);
 330
 331 /*!
 332  * \since 12
 333  * \brief Publish an attended transfer that results in an application being run
 334  *
 335  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 336  * \c AST_ATTENDED_TRANSFER_DEST_APP. This occurs when an attended transfer
 337  * results in either:
 338  *
 339  * \li A transferee channel leaving a bridge to run an app
 340  * \li A bridge of transferees running an app (via a local channel)
 341  *
 342  * \param is_external Indicates if the transfer was initiated externally
 343  * \param result The result of the transfer.
 344  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 345  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 346  * \param dest_app The application that the channel or bridge is running upon transfer completion.
 347  */
 348 void ast_bridge_publish_attended_transfer_app(int is_external, enum ast_transfer_result result,
 349                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 350                 const char *dest_app);
 351
 352 /*!
 353  * \since 12
 354  * \brief Publish an attended transfer that results in two bridges linked by a local channel
 355  *
 356  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 357  * \c AST_ATTENDED_TRANSFER_DEST_LINK. This occurs when two bridges are involved
 358  * in an attended transfer, but their properties do not allow for the bridges to
 359  * merge or to have channels moved off of the bridge. An example of this occurs when
 360  * attempting to transfer a ConfBridge to another bridge.
 361  *
 362  * When this type of transfer occurs, the two bridges continue to exist after the
 363  * transfer and a local channel is used to link the two bridges together.
 364  *
 365  * \param is_external Indicates if the transfer was initiated externally
 366  * \param result The result of the transfer.
 367  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 368  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 369  * \param locals The local channels linking the bridges together.
 370  */
 371 void ast_bridge_publish_attended_transfer_link(int is_external, enum ast_transfer_result result,
 372                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 373                 struct ast_channel *locals[2]);
 374
 375 /*!
 376  * \brief Returns the most recent snapshot for the bridge.
 377  *
 378  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
 379  *
 380  * \param bridge_id Uniqueid of the bridge for which to get the snapshot.
 381  * \return Most recent snapshot. ao2_cleanup() when done.
 382  * \return \c NULL if channel isn't in cache.
 383  */
 384 struct ast_bridge_snapshot *ast_bridge_snapshot_get_latest(
 385         const char *bridge_id);
 386
 387 /*!
 388  * \brief Initialize the stasis bridging topic and message types
 389  * \retval 0 on success
 390  * \retval -1 on failure
 391  */
 392 int ast_stasis_bridging_init(void);
 393
 394 #if defined(__cplusplus) || defined(c_plusplus)
 395 }
 396 #endif
 397
 398 #endif  /* _STASIS_BRIDGING_H */