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