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  * \brief Message representing blind transfer
 232  */
 233 struct ast_blind_transfer_message {
 234         AST_DECLARE_STRING_FIELDS(
 235                 /*! The destination context for the blind transfer */
 236                 AST_STRING_FIELD(context);
 237                 /*! The destination extension for the blind transfer */
 238                 AST_STRING_FIELD(exten);
 239         );
 240         /*! Result of the blind transfer */
 241         enum ast_transfer_result result;
 242         /*! If 0, was core DTMF transfer, otherwise occurred externally*/
 243         int is_external;
 244         /*! The transferer and its bridge before starting the transfer*/
 245         struct ast_bridge_channel_snapshot_pair transferer;
 246 };
 247
 248 /*!
 249  * \since 12
 250  * \brief Message type for \ref ast_blind_transfer_message.
 251  *
 252  * \retval Message type for \ref ast_blind_transfer_message.
 253  */
 254 struct stasis_message_type *ast_blind_transfer_type(void);
 255
 256 /*!
 257  * \brief Publish a blind transfer event
 258  *
 259  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
 260  * \param result The success or failure of the transfer
 261  * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
 262  * \param context The destination context for the blind transfer
 263  * \param exten The destination extension for the blind transfer
 264  */
 265 void ast_bridge_publish_blind_transfer(int is_external, enum ast_transfer_result result,
 266                 struct ast_bridge_channel_pair *to_transferee, const char *context, const char *exten);
 267
 268 enum ast_attended_transfer_dest_type {
 269         /*! The transfer failed, so there is no appropriate final state */
 270         AST_ATTENDED_TRANSFER_DEST_FAIL,
 271         /*! The transfer results in a single bridge remaining due to a merge or swap */
 272         AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE,
 273         /*! The transfer results in a channel or bridge running an application */
 274         AST_ATTENDED_TRANSFER_DEST_APP,
 275         /*! The transfer results in both bridges remaining with a local channel linking them */
 276         AST_ATTENDED_TRANSFER_DEST_LINK,
 277 };
 278
 279 /*!
 280  * \brief Message representing attended transfer
 281  */
 282 struct ast_attended_transfer_message {
 283         /*! Result of the attended transfer */
 284         enum ast_transfer_result result;
 285         /*! Indicates if the transfer was initiated externally*/
 286         int is_external;
 287         /*! Bridge between transferer <-> transferee and the transferer channel in that bridge. May be NULL */
 288         struct ast_bridge_channel_snapshot_pair to_transferee;
 289         /*! Bridge between transferer <-> transfer target and the transferer channel in that bridge. May be NULL */
 290         struct ast_bridge_channel_snapshot_pair to_transfer_target;
 291         /*! Indicates the final state of the transfer */
 292         enum ast_attended_transfer_dest_type dest_type;
 293         union {
 294                 /*! ID of the surviving bridge. Applicable for AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE */
 295                 char bridge[AST_UUID_STR_LEN];
 296                 /*! Destination application of transfer. Applicable for AST_ATTENDED_TRANSFER_DEST_APP */
 297                 char app[AST_MAX_APP];
 298                 /*! Pair of local channels linking the bridges. Applicable for AST_ATTENDED_TRANSFER_DEST_LINK */
 299                 struct ast_channel_snapshot *links[2];
 300         } dest;
 301 };
 302
 303 /*!
 304  * \since 12
 305  * \brief Message type for \ref ast_attended_transfer_message.
 306  *
 307  * \retval Message type for \ref ast_attended_transfer_message.
 308  */
 309 struct stasis_message_type *ast_attended_transfer_type(void);
 310
 311 /*!
 312  * \since 12
 313  * \brief Publish an attended transfer failure
 314  *
 315  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 316  * \c AST_ATTENDED_TRANSFER_DEST_FAIL.
 317  *
 318  * \param is_external Indicates if the transfer was initiated externally
 319  * \param result The result of the transfer. Will always be a type of failure.
 320  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 321  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 322  */
 323 void ast_bridge_publish_attended_transfer_fail(int is_external, enum ast_transfer_result result,
 324                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target);
 325
 326 /*!
 327  * \since 12
 328  * \brief Publish an attended transfer that results in two bridges becoming one.
 329  *
 330  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 331  * \c AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE. This type of attended transfer results from
 332  * having two bridges involved and either
 333  *
 334  * \li Merging the two bridges together
 335  * \li Moving a channel from one bridge to the other, thus emptying a bridge
 336  *
 337  * In either case, two bridges enter, one leaves.
 338  *
 339  * \param is_external Indicates if the transfer was initiated externally
 340  * \param result The result of the transfer.
 341  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 342  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 343  * \param final_bridge The bridge that the parties end up in. Will be a bridge from the transferee or target pair.
 344  */
 345 void ast_bridge_publish_attended_transfer_bridge_merge(int is_external, enum ast_transfer_result result,
 346                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 347                 struct ast_bridge *final_bridge);
 348
 349 /*!
 350  * \since 12
 351  * \brief Publish an attended transfer that results in an application being run
 352  *
 353  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 354  * \c AST_ATTENDED_TRANSFER_DEST_APP. This occurs when an attended transfer
 355  * results in either:
 356  *
 357  * \li A transferee channel leaving a bridge to run an app
 358  * \li A bridge of transferees running an app (via a local channel)
 359  *
 360  * \param is_external Indicates if the transfer was initiated externally
 361  * \param result The result of the transfer.
 362  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 363  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 364  * \param dest_app The application that the channel or bridge is running upon transfer completion.
 365  */
 366 void ast_bridge_publish_attended_transfer_app(int is_external, enum ast_transfer_result result,
 367                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 368                 const char *dest_app);
 369
 370 /*!
 371  * \since 12
 372  * \brief Publish an attended transfer that results in two bridges linked by a local channel
 373  *
 374  * Publish an \ref ast_attended_transfer_message with the dest_type set to
 375  * \c AST_ATTENDED_TRANSFER_DEST_LINK. This occurs when two bridges are involved
 376  * in an attended transfer, but their properties do not allow for the bridges to
 377  * merge or to have channels moved off of the bridge. An example of this occurs when
 378  * attempting to transfer a ConfBridge to another bridge.
 379  *
 380  * When this type of transfer occurs, the two bridges continue to exist after the
 381  * transfer and a local channel is used to link the two bridges together.
 382  *
 383  * \param is_external Indicates if the transfer was initiated externally
 384  * \param result The result of the transfer.
 385  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
 386  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
 387  * \param locals The local channels linking the bridges together.
 388  */
 389 void ast_bridge_publish_attended_transfer_link(int is_external, enum ast_transfer_result result,
 390                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
 391                 struct ast_channel *locals[2]);
 392
 393 /*!
 394  * \brief Returns the most recent snapshot for the bridge.
 395  *
 396  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
 397  *
 398  * \param bridge_id Uniqueid of the bridge for which to get the snapshot.
 399  * \return Most recent snapshot. ao2_cleanup() when done.
 400  * \return \c NULL if channel isn't in cache.
 401  */
 402 struct ast_bridge_snapshot *ast_bridge_snapshot_get_latest(
 403         const char *bridge_id);
 404
 405 /*!
 406  * \brief Initialize the stasis bridging topic and message types
 407  * \retval 0 on success
 408  * \retval -1 on failure
 409  */
 410 int ast_stasis_bridging_init(void);
 411
 412 #if defined(__cplusplus) || defined(c_plusplus)
 413 }
 414 #endif
 415
 416 #endif  /* _STASIS_BRIDGING_H */