699e276264833a3de4fd7fce7ca8b56394981923
[asterisk/asterisk.git] / include / asterisk / stasis_bridges.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/bridge.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                 /*! Creator of the bridge */
46                 AST_STRING_FIELD(creator);
47                 /*! Name given to the bridge by its creator */
48                 AST_STRING_FIELD(name);
49         );
50         /*! AO2 container of bare channel uniqueid strings participating in the bridge.
51          * Allocated from ast_str_container_alloc() */
52         struct ao2_container *channels;
53         /*! Bridge flags to tweak behavior */
54         struct ast_flags feature_flags;
55         /*! Bridge capabilities */
56         uint32_t capabilities;
57         /*! Number of channels participating in the bridge */
58         unsigned int num_channels;
59         /*! Number of active channels in the bridge. */
60         unsigned int num_active;
61 };
62
63 /*!
64  * \since 12
65  * \brief Generate a snapshot of the bridge state. This is an ao2 object, so
66  * ao2_cleanup() to deallocate.
67  *
68  * \pre Bridge is locked
69  *
70  * \param bridge The bridge from which to generate a snapshot
71  *
72  * \retval AO2 refcounted snapshot on success
73  * \retval NULL on error
74  */
75 struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge);
76
77 /*!
78  * \since 12
79  * \brief Message type for \ref ast_bridge_snapshot.
80  *
81  * \retval Message type for \ref ast_bridge_snapshot.
82  */
83 struct stasis_message_type *ast_bridge_snapshot_type(void);
84
85 /*!
86  * \since 12
87  * \brief A topic which publishes the events for a particular bridge.
88  *
89  * If the given \a bridge is \c NULL, ast_bridge_topic_all() is returned.
90  *
91  * \param bridge Bridge for which to get a topic or \c NULL.
92  *
93  * \retval Topic for bridge's events.
94  * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
95  */
96 struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
97
98 /*!
99  * \since 12
100  * \brief A topic which publishes the events for a particular bridge.
101  *
102  * \ref ast_bridge_snapshot messages are replaced with stasis_cache_update
103  * messages.
104  *
105  * If the given \a bridge is \c NULL, ast_bridge_topic_all_cached() is returned.
106  *
107  * \param bridge Bridge for which to get a topic or \c NULL.
108  *
109  * \retval Topic for bridge's events.
110  * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
111  */
112 struct stasis_topic *ast_bridge_topic_cached(struct ast_bridge *bridge);
113
114 /*!
115  * \since 12
116  * \brief A topic which publishes the events for all bridges.
117  * \retval Topic for all bridge events.
118  */
119 struct stasis_topic *ast_bridge_topic_all(void);
120
121 /*!
122  * \since 12
123  * \brief A caching topic which caches \ref ast_bridge_snapshot messages from
124  * ast_bridge_events_all(void).
125  *
126  * \retval Caching topic for all bridge events.
127  */
128 struct stasis_topic *ast_bridge_topic_all_cached(void);
129
130 /*!
131  * \since 12
132  * \brief Backend cache for ast_bridge_topic_all_cached().
133  * \retval Cache of \ref ast_bridge_snapshot.
134  */
135 struct stasis_cache *ast_bridge_cache(void);
136
137 /*!
138  * \since 12
139  * \brief Publish the state of a bridge
140  *
141  * \pre Bridge is locked
142  *
143  * \param bridge The bridge for which to publish state
144  */
145 void ast_bridge_publish_state(struct ast_bridge *bridge);
146
147 /*! \brief Message representing the merge of two bridges */
148 struct ast_bridge_merge_message {
149         struct ast_bridge_snapshot *from;       /*!< Bridge from which channels will be removed during the merge */
150         struct ast_bridge_snapshot *to;         /*!< Bridge to which channels will be added during the merge */
151 };
152
153 /*!
154  * \since 12
155  * \brief Message type for \ref ast_bridge_merge_message.
156  *
157  * \retval Message type for \ref ast_bridge_merge_message.
158  */
159 struct stasis_message_type *ast_bridge_merge_message_type(void);
160
161 /*!
162  * \since 12
163  * \brief Publish a bridge merge
164  *
165  * \pre Bridges involved are locked
166  *
167  * \param to The bridge to which channels are being added
168  * \param from The bridge from which channels are being removed
169  */
170 void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from);
171
172 /*!
173  * \since 12
174  * \brief Blob of data associated with a bridge.
175  *
176  * The \c blob is actually a JSON object of structured data. It has a "type" field
177  * which contains the type string describing this blob.
178  */
179 struct ast_bridge_blob {
180         /*! Bridge blob is associated with (or NULL for global/all bridges) */
181         struct ast_bridge_snapshot *bridge;
182         /*! Channel blob is associated with (may be NULL for some messages) */
183         struct ast_channel_snapshot *channel;
184         /*! JSON blob of data */
185         struct ast_json *blob;
186 };
187
188 /*!
189  * \since 12
190  * \brief Message type for \ref channel enter bridge blob messages.
191  *
192  * \retval Message type for \ref channel enter bridge blob messages.
193  */
194 struct stasis_message_type *ast_channel_entered_bridge_type(void);
195
196 /*!
197  * \since 12
198  * \brief Message type for \ref channel leave bridge blob messages.
199  *
200  * \retval Message type for \ref channel leave bridge blob messages.
201  */
202 struct stasis_message_type *ast_channel_left_bridge_type(void);
203
204 /*!
205  * \since 12
206  * \brief Creates a \ref ast_bridge_blob message.
207  *
208  * The \a blob JSON object requires a \c "type" field describing the blob. It
209  * should also be treated as immutable and not modified after it is put into the
210  * message.
211  *
212  * \pre bridge is locked.
213  * \pre No channels are locked.
214  *
215  * \param bridge Channel blob is associated with, or NULL for global/all bridges.
216  * \param blob JSON object representing the data.
217  * \return \ref ast_bridge_blob message.
218  * \return \c NULL on error
219  */
220 struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
221         struct ast_bridge *bridge,
222         struct ast_channel *chan,
223         struct ast_json *blob);
224
225 /*!
226  * \since 12
227  * \brief Publish a bridge channel enter event
228  *
229  * \pre bridge is locked.
230  * \pre No channels are locked.
231  *
232  * \param bridge The bridge a channel entered
233  * \param chan The channel that entered the bridge
234  * \param swap The channel being swapped out of the bridge
235  */
236 void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan,
237                 struct ast_channel *swap);
238
239 /*!
240  * \since 12
241  * \brief Publish a bridge channel leave event
242  *
243  * \pre bridge is locked.
244  * \pre No channels are locked.
245  *
246  * \param bridge The bridge a channel left
247  * \param chan The channel that left the bridge
248  */
249 void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan);
250
251 /*!
252  * \brief Build a JSON object from a \ref ast_bridge_snapshot.
253  *
254  * \param snapshot The bridge snapshot to convert to JSON
255  * \param sanitize The message sanitizer to use on the snapshot
256  *
257  * \return JSON object representing bridge snapshot.
258  * \return \c NULL on error
259  */
260 struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot,
261         const struct stasis_message_sanitizer *sanitize);
262
263 /*!
264  * \brief Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge
265  */
266 struct ast_bridge_channel_snapshot_pair {
267         struct ast_bridge_snapshot *bridge_snapshot;
268         struct ast_channel_snapshot *channel_snapshot;
269 };
270
271 /*!
272  * \brief Pair showing a bridge and a specific channel belonging to the bridge
273  */
274 struct ast_bridge_channel_pair {
275         struct ast_bridge *bridge;
276         struct ast_channel *channel;
277 };
278
279 /*!
280  * \since 12
281  * \brief Message type for \ref ast_blind_transfer_message.
282  *
283  * \retval Message type for \ref ast_blind_transfer_message.
284  */
285 struct stasis_message_type *ast_blind_transfer_type(void);
286
287 /*!
288  * \brief Message published during a blind transfer
289  */
290 struct ast_blind_transfer_message {
291         /*! Result of the transfer */
292         enum ast_transfer_result result;
293         /*! True if the transfer was initiated by an external source (i.e. not DTMF-initiated) */
294         int is_external;
295         /*! Transferer and its bridge */
296         struct ast_bridge_channel_snapshot_pair to_transferee;
297         /*! Destination context */
298         char context[AST_MAX_CONTEXT];
299         /*! Destination extension */
300         char exten[AST_MAX_EXTENSION];
301         /*! Transferee channel. NULL if there were multiple transferee channels */
302         struct ast_channel_snapshot *transferee;
303         /*! The channel replacing the transferer when multiple parties are being transferred */
304         struct ast_channel_snapshot *replace_channel;
305 };
306
307 /*!
308  * \brief Publish a blind transfer event
309  *
310  * \pre Bridges involved are locked. Channels involved are not locked.
311  *
312  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
313  * \param result The success or failure of the transfer
314  * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
315  * \param context The destination context for the blind transfer
316  * \param exten The destination extension for the blind transfer
317  * \param transferee_channel If a single channel is being transferred, this is it. If
318  *                           multiple parties are being transferred, this is NULL.
319  * \param replace_channel If multiple parties are being transferred or the transfer
320  *                        cannot reach across the bridge due to bridge flags, this is
321  *                        the channel connecting their bridge to the destination.
322  */
323 void ast_bridge_publish_blind_transfer(int is_external, enum ast_transfer_result result,
324                 struct ast_bridge_channel_pair *to_transferee, const char *context, const char *exten,
325                 struct ast_channel *transferee_channel, struct ast_channel *replace_channel);
326
327 enum ast_attended_transfer_dest_type {
328         /*! The transfer failed, so there is no appropriate final state */
329         AST_ATTENDED_TRANSFER_DEST_FAIL,
330         /*! The transfer results in a single bridge remaining due to a merge or swap */
331         AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE,
332         /*! The transfer results in a channel or bridge running an application */
333         AST_ATTENDED_TRANSFER_DEST_APP,
334         /*! The transfer results in a channel or bridge running an application via a local channel */
335         AST_ATTENDED_TRANSFER_DEST_LOCAL_APP,
336         /*! The transfer results in both bridges remaining with a local channel linking them */
337         AST_ATTENDED_TRANSFER_DEST_LINK,
338         /*! The transfer results in a threeway call between transferer, transferee, and transfer target */
339         AST_ATTENDED_TRANSFER_DEST_THREEWAY,
340 };
341
342 /*!
343  * \brief Message representing attended transfer
344  */
345 struct ast_attended_transfer_message {
346         /*! Result of the attended transfer */
347         enum ast_transfer_result result;
348         /*! Indicates if the transfer was initiated externally*/
349         int is_external;
350         /*! Bridge between transferer <-> transferee and the transferer channel in that bridge. May be NULL */
351         struct ast_bridge_channel_snapshot_pair to_transferee;
352         /*! Bridge between transferer <-> transfer target and the transferer channel in that bridge. May be NULL */
353         struct ast_bridge_channel_snapshot_pair to_transfer_target;
354         /*! Local channel connecting transferee bridge to application */
355         struct ast_channel_snapshot *replace_channel;
356         /*! Transferee channel. Will be NULL if there were multiple channels transferred. */
357         struct ast_channel_snapshot *transferee;
358         /*! Transfer target channel. Will be NULL if there were multiple channels targeted. */
359         struct ast_channel_snapshot *target;
360         /*! Indicates the final state of the transfer */
361         enum ast_attended_transfer_dest_type dest_type;
362         union {
363                 /*! ID of the surviving bridge. Applicable for AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE */
364                 char bridge[AST_UUID_STR_LEN];
365                 /*! Destination application of transfer. Applicable for AST_ATTENDED_TRANSFER_DEST_APP */
366                 char app[AST_MAX_APP];
367                 /*! Pair of local channels linking the bridges. Applicable for AST_ATTENDED_TRANSFER_DEST_LINK */
368                 struct ast_channel_snapshot *links[2];
369                 /*! Transferer channel and bridge that survived the transition to a threeway call. Applicable for AST_ATTENDED_TRANSFER_DEST_THREEWAY */
370                 struct ast_bridge_channel_snapshot_pair threeway;
371         } dest;
372 };
373
374 /*!
375  * \since 12
376  * \brief Message type for \ref ast_attended_transfer_message.
377  *
378  * \retval Message type for \ref ast_attended_transfer_message.
379  */
380 struct stasis_message_type *ast_attended_transfer_type(void);
381
382 /*!
383  * \since 12
384  * \brief Publish an attended transfer failure
385  *
386  * Publish an \ref ast_attended_transfer_message with the dest_type set to
387  * \c AST_ATTENDED_TRANSFER_DEST_FAIL.
388  *
389  * \pre Bridges involved are locked. Channels involved are not locked.
390  *
391  * \param is_external Indicates if the transfer was initiated externally
392  * \param result The result of the transfer. Will always be a type of failure.
393  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
394  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
395  * \param transferee_channel If a single channel is being transferred, this is it. If multiple parties are being transferred, this is NULL.
396  * \param target_channel If a single channel is being transferred to, this is it. If multiple parties are being transferred to, this is NULL.
397  */
398 void ast_bridge_publish_attended_transfer_fail(int is_external, enum ast_transfer_result result,
399                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
400                 struct ast_channel *transferee_channel, struct ast_channel *target_channel);
401
402 /*!
403  * \since 12
404  * \brief Publish an attended transfer that results in two bridges becoming one.
405  *
406  * Publish an \ref ast_attended_transfer_message with the dest_type set to
407  * \c AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE. This type of attended transfer results from
408  * having two bridges involved and either
409  *
410  * \li Merging the two bridges together
411  * \li Moving a channel from one bridge to the other, thus emptying a bridge
412  *
413  * In either case, two bridges enter, one leaves.
414  *
415  * \pre Bridges involved are locked. Channels involved are not locked.
416  *
417  * \param is_external Indicates if the transfer was initiated externally
418  * \param result The result of the transfer.
419  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
420  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
421  * \param final_bridge The bridge that the parties end up in. Will be a bridge from the transferee or target pair.
422  * \param transferee_channel If a single channel is being transferred, this is it. If multiple parties are being transferred, this is NULL.
423  * \param target_channel If a single channel is being transferred to, this is it. If multiple parties are being transferred to, this is NULL.
424  */
425 void ast_bridge_publish_attended_transfer_bridge_merge(int is_external, enum ast_transfer_result result,
426                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
427                 struct ast_bridge *final_bridge, struct ast_channel *transferee_channel,
428                 struct ast_channel *target_channel);
429
430 /*!
431  * \since 12
432  * \brief Publish an attended transfer that results in a threeway call.
433  *
434  * Publish an \ref ast_attended_transfer_message with the dest_type set to
435  * \c AST_ATTENDED_TRANSFER_DEST_THREEWAY. Like with \ref ast_bridge_publish_attended_transfer_bridge_merge,
436  * this results from merging two bridges together. The difference is that a
437  * transferer channel survives the bridge merge
438  *
439  * \pre Bridges involved are locked. Channels involved are not locked.
440  *
441  * \param is_external Indicates if the transfer was initiated externally
442  * \param result The result of the transfer.
443  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
444  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
445  * \param final_pair The bridge that the parties end up in, and the transferer channel that is in this bridge.
446  * \param transferee_channel If a single channel is being transferred, this is it. If multiple parties are being transferred, this is NULL.
447  * \param target_channel If a single channel is being transferred to, this is it. If multiple parties are being transferred to, this is NULL.
448  */
449 void ast_bridge_publish_attended_transfer_threeway(int is_external, enum ast_transfer_result result,
450                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
451                 struct ast_bridge_channel_pair *final_pair, struct ast_channel *transferee_channel,
452                 struct ast_channel *target_channel);
453
454 /*!
455  * \since 12
456  * \brief Publish an attended transfer that results in an application being run
457  *
458  * Publish an \ref ast_attended_transfer_message with the dest_type set to
459  * \c AST_ATTENDED_TRANSFER_DEST_APP. This occurs when an attended transfer
460  * results in either:
461  *
462  * \li A transferee channel leaving a bridge to run an app
463  * \li A bridge of transferees running an app (via a local channel)
464  *
465  * \pre Bridges involved are locked. Channels involved are not locked.
466  *
467  * \param is_external Indicates if the transfer was initiated externally
468  * \param result The result of the transfer.
469  * \param transferee The bridge between the transferer and transferees as well as the
470  *        transferer channel from that bridge
471  * \param target The bridge between the transferer and transfer targets as well as the
472  *        transferer channel from that bridge
473  * \param replace_channel The channel that will be replacing the transferee bridge
474  *        transferer channel when a local channel is involved
475  * \param dest_app The application that the channel or bridge is running upon transfer
476  *        completion.
477  * \param transferee_channel If a single channel is being transferred, this is it.
478  *        If multiple parties are being transferred, this is NULL.
479  * \param target_channel If a single channel is being transferred to, this is it.
480  *        If multiple parties are being transferred to, this is NULL.
481  */
482 void ast_bridge_publish_attended_transfer_app(int is_external, enum ast_transfer_result result,
483                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
484                 struct ast_channel *replace_channel, const char *dest_app,
485                 struct ast_channel *transferee_channel, struct ast_channel *target_channel);
486
487 /*!
488  * \since 12
489  * \brief Publish an attended transfer that results in two bridges linked by a local channel
490  *
491  * Publish an \ref ast_attended_transfer_message with the dest_type set to
492  * \c AST_ATTENDED_TRANSFER_DEST_LINK. This occurs when two bridges are involved
493  * in an attended transfer, but their properties do not allow for the bridges to
494  * merge or to have channels moved off of the bridge. An example of this occurs when
495  * attempting to transfer a ConfBridge to another bridge.
496  *
497  * When this type of transfer occurs, the two bridges continue to exist after the
498  * transfer and a local channel is used to link the two bridges together.
499  *
500  * \pre Bridges involved are locked. Channels involved are not locked.
501  *
502  * \param is_external Indicates if the transfer was initiated externally
503  * \param result The result of the transfer.
504  * \param transferee The bridge between the transferer and transferees as well as the transferer channel from that bridge
505  * \param target The bridge between the transferer and transfer targets as well as the transferer channel from that bridge
506  * \param locals The local channels linking the bridges together.
507  * \param transferee_channel If a single channel is being transferred, this is it. If multiple parties are being transferred, this is NULL.
508  * \param target_channel If a single channel is being transferred to, this is it. If multiple parties are being transferred to, this is NULL.
509  */
510 void ast_bridge_publish_attended_transfer_link(int is_external, enum ast_transfer_result result,
511                 struct ast_bridge_channel_pair *transferee, struct ast_bridge_channel_pair *target,
512                 struct ast_channel *locals[2], struct ast_channel *transferee_channel,
513                 struct ast_channel *target_channel);
514
515 /*!
516  * \brief Returns the most recent snapshot for the bridge.
517  *
518  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
519  *
520  * \param bridge_id Uniqueid of the bridge for which to get the snapshot.
521  * \return Most recent snapshot. ao2_cleanup() when done.
522  * \return \c NULL if channel isn't in cache.
523  */
524 struct ast_bridge_snapshot *ast_bridge_snapshot_get_latest(
525         const char *bridge_id);
526
527 /*!
528  * \internal
529  * \brief Initialize the topics for a single bridge.
530  * \return 0 on success.
531  * \return Non-zero on error.
532  */
533 int bridge_topics_init(struct ast_bridge *bridge);
534
535 /*!
536  * \internal
537  * \brief Initialize the stasis bridging topic and message types
538  * \retval 0 on success
539  * \retval -1 on failure
540  */
541 int ast_stasis_bridging_init(void);
542
543 #if defined(__cplusplus) || defined(c_plusplus)
544 }
545 #endif
546
547 #endif  /* _STASIS_BRIDGING_H */