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