Asterisk - The Open Source Telephony Project  18.5.0
stasis_bridges.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Kinsey Moore <[email protected]>
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 
37 };
38 
39 /*!
40  * \since 12
41  * \brief Generate a snapshot of the bridge state. This is an ao2 object, so
42  * ao2_cleanup() to deallocate.
43  *
44  * \pre Bridge is locked
45  *
46  * \param bridge The bridge from which to generate a snapshot
47  *
48  * \retval AO2 refcounted snapshot on success
49  * \retval NULL on error
50  */
52 
53 /*!
54  * \since 12
55  * \brief Message type for \ref ast_bridge_snapshot.
56  *
57  * \retval Message type for \ref ast_bridge_snapshot.
58  */
60 
61 /*!
62  * \since 12
63  * \brief A topic which publishes the events for a particular bridge.
64  *
65  * If the given \a bridge is \c NULL, ast_bridge_topic_all() is returned.
66  *
67  * \param bridge Bridge for which to get a topic or \c NULL.
68  *
69  * \retval Topic for bridge's events.
70  * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
71  */
72 struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
73 
74 /*!
75  * \since 12
76  * \brief A topic which publishes the events for all bridges.
77  * \retval Topic for all bridge events.
78  */
80 
81 /*!
82  * \since 12
83  * \brief Publish the state of a bridge
84  *
85  * \pre Bridge is locked
86  *
87  * \param bridge The bridge for which to publish state
88  */
89 void ast_bridge_publish_state(struct ast_bridge *bridge);
90 
91 /*! \brief Message representing the merge of two bridges */
93  struct ast_bridge_snapshot *from; /*!< Bridge from which channels will be removed during the merge */
94  struct ast_bridge_snapshot *to; /*!< Bridge to which channels will be added during the merge */
95 };
96 
97 /*!
98  * \since 12
99  * \brief Message type for \ref ast_bridge_merge_message.
100  *
101  * \retval Message type for \ref ast_bridge_merge_message.
102  */
104 
105 /*!
106  * \since 12
107  * \brief Publish a bridge merge
108  *
109  * \pre Bridges involved are locked
110  *
111  * \param to The bridge to which channels are being added
112  * \param from The bridge from which channels are being removed
113  */
114 void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from);
115 
116 /*!
117  * \since 12
118  * \brief Blob of data associated with a bridge.
119  *
120  * The \c blob is actually a JSON object of structured data. It has a "type" field
121  * which contains the type string describing this blob.
122  */
124  /*! Bridge blob is associated with (or NULL for global/all bridges) */
126  /*! Channel blob is associated with (may be NULL for some messages) */
128  /*! JSON blob of data */
129  struct ast_json *blob;
130 };
131 
132 /*!
133  * \since 12
134  * \brief Message type for \ref channel enter bridge blob messages.
135  *
136  * \retval Message type for \ref channel enter bridge blob messages.
137  */
139 
140 /*!
141  * \since 12
142  * \brief Message type for \ref channel leave bridge blob messages.
143  *
144  * \retval Message type for \ref channel leave bridge blob messages.
145  */
147 
148 /*!
149  * \since 12
150  * \brief Creates a \ref ast_bridge_blob message.
151  *
152  * The \a blob JSON object requires a \c "type" field describing the blob. It
153  * should also be treated as immutable and not modified after it is put into the
154  * message.
155  *
156  * \pre bridge is locked.
157  * \pre No channels are locked.
158  *
159  * \param bridge Channel blob is associated with, or NULL for global/all bridges.
160  * \param blob JSON object representing the data.
161  * \return \ref ast_bridge_blob message.
162  * \return \c NULL on error
163  */
165  struct ast_bridge *bridge,
166  struct ast_channel *chan,
167  struct ast_json *blob);
168 
169 /*!
170  * \since 13.28
171  * \since 16.5
172  * \brief Creates a \ref ast_bridge_blob message from snapshots.
173  *
174  * The \a blob JSON object requires a \c "type" field describing the blob. It
175  * should also be treated as immutable and not modified after it is put into the
176  * message.
177  *
178  * \pre bridge is locked.
179  * \pre No channels are locked.
180  *
181  * \param bridge_snapshot Bridge snapshot
182  * \param channel_snapshot Channel snapshot
183  * \param blob JSON object representing the data.
184  * \return \ref ast_bridge_blob message.
185  * \return \c NULL on error
186  */
188  struct ast_bridge_snapshot *bridge_snapshot,
189  struct ast_channel_snapshot *chan_snapshot,
190  struct ast_json *blob);
191 
192 /*!
193  * \since 12
194  * \brief Publish a bridge channel enter event
195  *
196  * \pre bridge is locked.
197  * \pre No channels are locked.
198  *
199  * \param bridge The bridge a channel entered
200  * \param chan The channel that entered the bridge
201  * \param swap The channel being swapped out of the bridge
202  */
203 void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan,
204  struct ast_channel *swap);
205 
206 /*!
207  * \since 12
208  * \brief Publish a bridge channel leave event
209  *
210  * \pre bridge is locked.
211  * \pre No channels are locked.
212  *
213  * \param bridge The bridge a channel left
214  * \param chan The channel that left the bridge
215  */
216 void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan);
217 
218 /*!
219  * \brief Build a JSON object from a \ref ast_bridge_snapshot.
220  *
221  * \param snapshot The bridge snapshot to convert to JSON
222  * \param sanitize The message sanitizer to use on the snapshot
223  *
224  * \return JSON object representing bridge snapshot.
225  * \return \c NULL on error
226  */
227 struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot,
228  const struct stasis_message_sanitizer *sanitize);
229 
230 /*!
231  * \brief Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge
232  */
236 };
237 
238 /*!
239  * \since 12
240  * \brief Message type for \ref ast_blind_transfer_message.
241  *
242  * \retval Message type for \ref ast_blind_transfer_message.
243  */
245 
246 /*!
247  * \brief Message published during a blind transfer
248  */
250  /*! Result of the transfer */
252  /*! True if the transfer was initiated by an external source (i.e. not DTMF-initiated) */
254  /*! The transferring channel */
256  /*! The bridge between the transferer and the transferee */
258  /*! Destination context */
260  /*! Destination extension */
262  /*! Transferee channel. NULL if there were multiple transferee channels */
264  /*! The channel replacing the transferer when multiple parties are being transferred */
266 };
267 
268 /*!
269  * \brief Create a blind transfer message to be published
270  *
271  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
272  * \param transferer The transferer's channel that is bridged to the transferee
273  * \param bridge The bridge the transferer and transferee are in
274  * \param context The destination context for the blind transfer
275  * \param exten The destination extension for the blind transfer
276  *
277  * \retval NULL Failure to allocate or create snapshots
278  * \retval non-NULL The created blind transfer message
279  */
281  struct ast_channel *transferer, const char *exten, const char *context);
282 
283 /*!
284  * \brief Publish a blind transfer event
285  *
286  * \pre Bridges involved are locked. Channels involved are not locked.
287  *
288  * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
289  * \param result The success or failure of the transfer
290  * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
291  * \param context The destination context for the blind transfer
292  * \param exten The destination extension for the blind transfer
293  * \param transferee_channel If a single channel is being transferred, this is it. If
294  * multiple parties are being transferred, this is NULL.
295  * \param replace_channel If multiple parties are being transferred or the transfer
296  * cannot reach across the bridge due to bridge flags, this is
297  * the channel connecting their bridge to the destination.
298  */
300 
302  /*! The transfer failed, so there is no appropriate final state */
304  /*! The transfer results in a single bridge remaining due to a merge or swap */
306  /*! The transfer results in a channel or bridge running an application */
308  /*! The transfer results in a channel or bridge running an application via a local channel */
310  /*! The transfer results in both bridges remaining with a local channel linking them */
312  /*! The transfer results in a threeway call between transferer, transferee, and transfer target */
314 };
315 
316 /*!
317  * \brief Message representing attended transfer
318  */
320  /*! Result of the attended transfer */
322  /*! Indicates if the transfer was initiated externally*/
324  /*! Bridge between transferer <-> transferee and the transferer channel in that bridge. May be NULL */
325  struct ast_bridge_channel_snapshot_pair to_transferee;
326  /*! Bridge between transferer <-> transfer target and the transferer channel in that bridge. May be NULL */
327  struct ast_bridge_channel_snapshot_pair to_transfer_target;
328  /*! Local channel connecting transferee bridge to application */
330  /*! Transferee channel. Will be NULL if there were multiple channels transferred. */
332  /*! Transfer target channel. Will be NULL if there were multiple channels targeted. */
334  /*! Indicates the final state of the transfer */
336  union {
337  /*! ID of the surviving bridge. Applicable for AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE */
338  char bridge[AST_UUID_STR_LEN];
339  /*! Destination application of transfer. Applicable for AST_ATTENDED_TRANSFER_DEST_APP */
341  /*! Pair of local channels linking the bridges. Applicable for AST_ATTENDED_TRANSFER_DEST_LINK */
342  struct ast_channel_snapshot *links[2];
343  /*! Transferer channel and bridge that survived the transition to a threeway call. Applicable for AST_ATTENDED_TRANSFER_DEST_THREEWAY */
345  } dest;
346 };
347 
348 /*!
349  * \brief Create an Attended transfer message to be published.
350  *
351  * The parameters to this function are the basic necessities in order to create the
352  * initial attended transfer message.
353  *
354  * The transferee and transfer_target parameters are optional. If not provided, then this
355  * function will attempt to determine who the transferee and transfer target are based on
356  * the input transferer channels and bridges. You typically will not need to provide an
357  * explicit transferee and transfer target channel unless your attended transfer is implemented
358  * in a strange way.
359  *
360  * \param is_external Non-zero if the transfer was initiated by a native channel driver protocol.
361  * \param to_transferee The transferer channel that is bridged to the transferee channel.
362  * \param transferee_bridge The bridge between the transferer and transferee. May be NULL.
363  * \param to_transfer_target The transferer channel that is bridged to the transfer target.
364  * \param target_bridge The bridge between the transferer and transfer target. May be NULL.
365  * \param transferee The channel that is being transferred. Optional.
366  * \param transfer_target The channel that is being transferred to. Optional.
367  *
368  * \retval NULL Failure to allocate or create snapshots
369  * \retval non-NULL The created attended transfer message
370  */
372  int is_external, struct ast_channel *to_transferee, struct ast_bridge *transferee_bridge,
373  struct ast_channel *to_transfer_target, struct ast_bridge *target_bridge,
374  struct ast_channel *transferee, struct ast_channel *transfer_target);
375 
376 /*!
377  * \brief Add details for a bridge merge to an attended transfer message.
378  *
379  * If the transfer is accomplished by a bridge merge (or swap optimization), then this should
380  * be called on the created attended transfer message to have the appropriate details added on.
381  *
382  * \param transfer_msg The transfer message to add details to
383  * \param final_bridge The bridge where the surviving parties reside
384  *
385  * \retval 0 Success
386  * \retval -1 Failure
387  */
389  struct ast_bridge *final_bridge);
390 
391 /*!
392  * \brief Add details for an attended transfer that was resolved as a three-way call
393  *
394  * If the transfer results in a three-way call between the transferer, the transferee, and the
395  * transfer target, then this should be called in order to add appropriate details to the
396  * transfer message to be published.
397  *
398  * \param transfer_msg The message to add details to
399  * \param survivor_channel The transferer channel that exists in the three-way call
400  * \param survivor_bridge The bridge where the three-way call takes place.
401  *
402  * \retval 0 Success
403  * \retval -1 Failure
404  */
406  struct ast_channel *survivor_channel, struct ast_bridge *survivor_bridge);
407 
408 /*!
409  * \brief Add details for an attended transfer to an application
410  *
411  * If the transfer is sending one or more parties into an application, then this should be called
412  * to add appropriate details to the transfer message being published.
413  *
414  * \param transfer_msg The message to add details to
415  * \param app The name of the application that the parties are being transferred to
416  * \param replace_channel The local channel that is in the bridge and running the application
417  *
418  * \retval 0 Success
419  * \retval -1 Failure
420  */
422  const char *app, struct ast_channel *replace_channel);
423 
424 /*!
425  * \brief Add details for an attended transfer that has a link between bridges.
426  *
427  * An attended transfer may be accomplished by linking two bridges together with local channels.
428  * If this is how the transfer is to be completed, call this function in order to fill in details
429  * about the transfer.
430  *
431  * \param transfer_msg The message to add details to.
432  * \param locals An array of local channel halves that each are in one of the involved bridges.
433  *
434  * \retval 0 Success
435  * \retval -1 Failure
436  */
438  struct ast_channel *locals[2]);
439 
440 /*!
441  * \brief Publish an attended transfer
442  *
443  * \param transfer_msg The transfer message to publish
444  */
446 
447 /*!
448  * \since 12
449  * \brief Message type for \ref ast_attended_transfer_message.
450  *
451  * \retval Message type for \ref ast_attended_transfer_message.
452  */
454 
455 /*!
456  * \brief Returns the current snapshot for the bridge.
457  * \since 17.0
458  *
459  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
460  *
461  * \param bridge_id Uniqueid of the bridge from which to get the snapshot.
462  * \return Most recent snapshot. ao2_cleanup() when done.
463  * \return \c NULL if bridge or snapshot doesn't exist.
464  */
466  const char *bridge_id);
467 
468 /*!
469  * \brief Returns the current snapshot for the bridge.
470  * \since 17.0
471  *
472  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
473  *
474  * \param bridge The bridge from which to get the snapshot.
475  * \return Most recent snapshot. ao2_cleanup() when done.
476  * \return \c NULL if there isn't a snapshot.
477  */
479  struct ast_bridge *bridge);
480 
481 /*!
482  * \internal
483  * \brief Initialize the topics for a single bridge.
484  * \return 0 on success.
485  * \return Non-zero on error.
486  */
487 int bridge_topics_init(struct ast_bridge *bridge);
488 
489 /*!
490  * \internal
491  * \since 17.0
492  * \brief Publish destroy then cleanup topics.
493  *
494  * \param bridge The bridge to clean up
495  */
496 void bridge_topics_destroy(struct ast_bridge *bridge);
497 
498 /*!
499  * \internal
500  * \brief Initialize the stasis bridging topic and message types
501  * \retval 0 on success
502  * \retval -1 on failure
503  */
504 int ast_stasis_bridging_init(void);
505 
506 #if defined(__cplusplus) || defined(c_plusplus)
507 }
508 #endif
509 
510 #endif /* _STASIS_BRIDGING_H */
void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan)
Publish a bridge channel leave event.
struct stasis_message_type * ast_bridge_snapshot_type(void)
Message type for ast_bridge_snapshot.
struct stasis_message_type * ast_blind_transfer_type(void)
Message type for ast_blind_transfer_message.
static const char type[]
Definition: chan_ooh323.c:109
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
Main Channel structure associated with a channel.
Asterisk locking-related definitions:
struct ast_blind_transfer_message * ast_blind_transfer_message_create(int is_external, struct ast_channel *transferer, const char *exten, const char *context)
Create a blind transfer message to be published.
ast_attended_transfer_dest_type
struct stasis_message_type * ast_channel_entered_bridge_type(void)
Message type for channel enter bridge blob messages.
#define AST_UUID_STR_LEN
Definition: uuid.h:27
Message representing attended transfer.
struct ast_channel_snapshot * channel
void ast_bridge_publish_attended_transfer(struct ast_attended_transfer_message *transfer_msg)
Publish an attended transfer.
Message published during a blind transfer.
int ast_attended_transfer_message_add_app(struct ast_attended_transfer_message *transfer_msg, const char *app, struct ast_channel *replace_channel)
Add details for an attended transfer to an application.
struct stasis_message_type * ast_channel_left_bridge_type(void)
Message type for channel leave bridge blob messages.
Structure that contains a snapshot of information about a bridge.
Definition: bridge.h:322
int bridge_topics_init(struct ast_bridge *bridge)
Structure representing a snapshot of channel state.
int ast_attended_transfer_message_add_threeway(struct ast_attended_transfer_message *transfer_msg, struct ast_channel *survivor_channel, struct ast_bridge *survivor_bridge)
Add details for an attended transfer that was resolved as a three-way call.
struct ast_json * blob
struct ast_channel_snapshot * target
ast_transfer_result
Definition: bridge.h:1115
struct ast_bridge_channel_snapshot_pair to_transferee
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200
Utility functions.
void bridge_topics_destroy(struct ast_bridge *bridge)
struct ast_bridge_channel_snapshot_pair to_transfer_target
struct ast_bridge_snapshot * bridge
struct stasis_message_type * ast_bridge_merge_message_type(void)
Message type for ast_bridge_merge_message.
int ast_stasis_bridging_init(void)
struct ast_bridge_snapshot * ast_bridge_get_snapshot(struct ast_bridge *bridge)
Returns the current snapshot for the bridge.
General Asterisk PBX channel definitions.
struct ast_channel_snapshot * transferee
int ast_attended_transfer_message_add_merge(struct ast_attended_transfer_message *transfer_msg, struct ast_bridge *final_bridge)
Add details for a bridge merge to an attended transfer message.
#define AST_MAX_EXTENSION
Definition: channel.h:135
struct ast_channel_snapshot * replace_channel
void ast_bridge_publish_state(struct ast_bridge *bridge)
Publish the state of a bridge.
A set of macros to manage forward-linked lists.
struct ast_bridge_snapshot * bridge
struct ast_bridge_snapshot * old_snapshot
Blob of data associated with a bridge.
Core PBX routines and definitions.
Structure that contains information about a bridge.
Definition: bridge.h:357
struct ast_channel_snapshot * transferer
struct ast_channel_snapshot * channel_snapshot
#define AST_MAX_APP
Definition: pbx.h:40
struct ast_bridge_snapshot * ast_bridge_snapshot_create(struct ast_bridge *bridge)
Generate a snapshot of the bridge state. This is an ao2 object, so ao2_cleanup() to deallocate...
void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap)
Publish a bridge channel enter event.
struct stasis_message_type * ast_attended_transfer_type(void)
Message type for ast_attended_transfer_message.
struct ast_bridge_snapshot * bridge_snapshot
#define AST_MAX_CONTEXT
Definition: channel.h:136
void ast_bridge_publish_blind_transfer(struct ast_blind_transfer_message *transfer_message)
Publish a blind transfer event.
struct ast_bridge_snapshot * new_snapshot
struct ast_bridge_snapshot * from
struct stasis_topic * ast_bridge_topic_all(void)
A topic which publishes the events for all bridges.
Message representing the merge of two bridges.
struct ast_json * ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot, const struct stasis_message_sanitizer *sanitize)
Build a JSON object from a ast_bridge_snapshot.
static PGresult * result
Definition: cel_pgsql.c:88
struct stasis_message * ast_bridge_blob_create(struct stasis_message_type *type, struct ast_bridge *bridge, struct ast_channel *chan, struct ast_json *blob)
Creates a ast_bridge_blob message.
Abstract JSON element (object, array, string, int, ...).
struct stasis_topic * ast_bridge_topic(struct ast_bridge *bridge)
A topic which publishes the events for a particular bridge.
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116
struct ast_channel_snapshot * transferee
static struct ao2_container * locals
Definition: core_local.c:138
int ast_attended_transfer_message_add_link(struct ast_attended_transfer_message *transfer_msg, struct ast_channel *locals[2])
Add details for an attended transfer that has a link between bridges.
struct ast_attended_transfer_message * ast_attended_transfer_message_create(int is_external, struct ast_channel *to_transferee, struct ast_bridge *transferee_bridge, struct ast_channel *to_transfer_target, struct ast_bridge *target_bridge, struct ast_channel *transferee, struct ast_channel *transfer_target)
Create an Attended transfer message to be published.
Bridging API.
static const char app[]
Definition: app_mysql.c:62
void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from)
Publish a bridge merge.
struct stasis_message * ast_bridge_blob_create_from_snapshots(struct stasis_message_type *type, struct ast_bridge_snapshot *bridge_snapshot, struct ast_channel_snapshot *chan_snapshot, struct ast_json *blob)
Creates a ast_bridge_blob message from snapshots.
struct ast_bridge_snapshot * ast_bridge_get_snapshot_by_uniqueid(const char *bridge_id)
Returns the current snapshot for the bridge.
struct ast_channel_snapshot * replace_channel
struct ast_bridge_snapshot * to
Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge.