Asterisk - The Open Source Telephony Project GIT-master-67613d1
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 <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)
23extern "C" {
24#endif
25
27#include "asterisk/utils.h"
28#include "asterisk/lock.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 * \return 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 * \return 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 * \return Topic for bridge's events.
70 * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
71 */
72struct 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 * \return 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 */
89void 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 * \return 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 */
114void 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 ast_channel enter bridge blob messages.
135 *
136 * \return Message type for \ref ast_channel enter bridge blob messages.
137 */
139
140/*!
141 * \since 12
142 * \brief Message type for \ref ast_channel leave bridge blob messages.
143 *
144 * \return Message type for \ref ast_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 type
160 * \param bridge Channel blob is associated with, or NULL for global/all bridges.
161 * \param chan The channel that started the bridge
162 * \param blob JSON object representing the data.
163 * \return \ref ast_bridge_blob message.
164 * \retval NULL on error
165 */
167 struct ast_bridge *bridge,
168 struct ast_channel *chan,
169 struct ast_json *blob);
170
171/*!
172 * \since 13.28
173 * \since 16.5
174 * \brief Creates a \ref ast_bridge_blob message from snapshots.
175 *
176 * The \a blob JSON object requires a \c "type" field describing the blob. It
177 * should also be treated as immutable and not modified after it is put into the
178 * message.
179 *
180 * \pre bridge is locked.
181 * \pre No channels are locked.
182 *
183 * \param type
184 * \param bridge_snapshot Bridge snapshot
185 * \param chan_snapshot Channel snapshot
186 * \param blob JSON object representing the data.
187 * \return \ref ast_bridge_blob message.
188 * \retval NULL on error
189 */
191 struct ast_bridge_snapshot *bridge_snapshot,
192 struct ast_channel_snapshot *chan_snapshot,
193 struct ast_json *blob);
194
195/*!
196 * \since 12
197 * \brief Publish a bridge channel enter event
198 *
199 * \pre bridge is locked.
200 * \pre No channels are locked.
201 *
202 * \param bridge The bridge a channel entered
203 * \param chan The channel that entered the bridge
204 * \param swap The channel being swapped out of the bridge
205 */
206void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan,
207 struct ast_channel *swap);
208
209/*!
210 * \since 12
211 * \brief Publish a bridge channel leave event
212 *
213 * \pre bridge is locked.
214 * \pre No channels are locked.
215 *
216 * \param bridge The bridge a channel left
217 * \param chan The channel that left the bridge
218 */
219void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan);
220
221/*!
222 * \brief Build a JSON object from a \ref ast_bridge_snapshot.
223 *
224 * \param snapshot The bridge snapshot to convert to JSON
225 * \param sanitize The message sanitizer to use on the snapshot
226 *
227 * \return JSON object representing bridge snapshot.
228 * \retval NULL on error
229 */
230struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot,
231 const struct stasis_message_sanitizer *sanitize);
232
233/*!
234 * \brief Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge
235 */
239};
240
241/*!
242 * \since 12
243 * \brief Message type for \ref ast_blind_transfer_message.
244 *
245 * \return Message type for \ref ast_blind_transfer_message.
246 */
248
249/*!
250 * \brief Message published during a blind transfer
251 */
253 /*! Result of the transfer */
255 /*! True if the transfer was initiated by an external source (i.e. not DTMF-initiated) */
257 /*! The transferring channel */
259 /*! The bridge between the transferer and the transferee */
261 /*! Destination context */
263 /*! Destination extension */
265 /*! Transferee channel. NULL if there were multiple transferee channels */
267 /*! The channel replacing the transferer when multiple parties are being transferred */
269};
270
271/*!
272 * \brief Create a blind transfer message to be published
273 *
274 * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
275 * \param transferer The transferer's channel that is bridged to the transferee
276 * \param exten The destination extension for the blind transfer
277 * \param context The destination context for the blind transfer
278 *
279 * \retval NULL Failure to allocate or create snapshots
280 * \retval non-NULL The created blind transfer message
281 */
283 struct ast_channel *transferer, const char *exten, const char *context);
284
285/*!
286 * \brief Publish a blind transfer event
287 *
288 * \pre Bridges involved are locked. Channels involved are not locked.
289 *
290 * \param transfer_message
291 */
293
295 /*! The transfer failed, so there is no appropriate final state */
297 /*! The transfer results in a single bridge remaining due to a merge or swap */
299 /*! The transfer results in a channel or bridge running an application */
301 /*! The transfer results in a channel or bridge running an application via a local channel */
303 /*! The transfer results in both bridges remaining with a local channel linking them */
305 /*! The transfer results in a threeway call between transferer, transferee, and transfer target */
307};
308
309/*!
310 * \brief Message representing attended transfer
311 */
313 /*! Result of the attended transfer */
315 /*! Indicates if the transfer was initiated externally*/
317 /*! Bridge between transferer <-> transferee and the transferer channel in that bridge. May be NULL */
319 /*! Bridge between transferer <-> transfer target and the transferer channel in that bridge. May be NULL */
321 /*! Local channel connecting transferee bridge to application */
323 /*! Transferee channel. Will be NULL if there were multiple channels transferred. */
325 /*! Transfer target channel. Will be NULL if there were multiple channels targeted. */
327 /*! Indicates the final state of the transfer */
329 union {
330 /*! ID of the surviving bridge. Applicable for AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE */
332 /*! Destination application of transfer. Applicable for AST_ATTENDED_TRANSFER_DEST_APP */
334 /*! Pair of local channels linking the bridges. Applicable for AST_ATTENDED_TRANSFER_DEST_LINK */
336 /*! Transferer channel and bridge that survived the transition to a threeway call. Applicable for AST_ATTENDED_TRANSFER_DEST_THREEWAY */
339};
340
341/*!
342 * \brief Create an Attended transfer message to be published.
343 *
344 * The parameters to this function are the basic necessities in order to create the
345 * initial attended transfer message.
346 *
347 * The transferee and transfer_target parameters are optional. If not provided, then this
348 * function will attempt to determine who the transferee and transfer target are based on
349 * the input transferer channels and bridges. You typically will not need to provide an
350 * explicit transferee and transfer target channel unless your attended transfer is implemented
351 * in a strange way.
352 *
353 * \param is_external Non-zero if the transfer was initiated by a native channel driver protocol.
354 * \param to_transferee The transferer channel that is bridged to the transferee channel.
355 * \param transferee_bridge The bridge between the transferer and transferee. May be NULL.
356 * \param to_transfer_target The transferer channel that is bridged to the transfer target.
357 * \param target_bridge The bridge between the transferer and transfer target. May be NULL.
358 * \param transferee The channel that is being transferred. Optional.
359 * \param transfer_target The channel that is being transferred to. Optional.
360 *
361 * \retval NULL Failure to allocate or create snapshots
362 * \retval non-NULL The created attended transfer message
363 */
365 int is_external, struct ast_channel *to_transferee, struct ast_bridge *transferee_bridge,
366 struct ast_channel *to_transfer_target, struct ast_bridge *target_bridge,
367 struct ast_channel *transferee, struct ast_channel *transfer_target);
368
369/*!
370 * \brief Add details for a bridge merge to an attended transfer message.
371 *
372 * If the transfer is accomplished by a bridge merge (or swap optimization), then this should
373 * be called on the created attended transfer message to have the appropriate details added on.
374 *
375 * \param transfer_msg The transfer message to add details to
376 * \param final_bridge The bridge where the surviving parties reside
377 *
378 * \retval 0 Success
379 * \retval -1 Failure
380 */
382 struct ast_bridge *final_bridge);
383
384/*!
385 * \brief Add details for an attended transfer that was resolved as a three-way call
386 *
387 * If the transfer results in a three-way call between the transferer, the transferee, and the
388 * transfer target, then this should be called in order to add appropriate details to the
389 * transfer message to be published.
390 *
391 * \param transfer_msg The message to add details to
392 * \param survivor_channel The transferer channel that exists in the three-way call
393 * \param survivor_bridge The bridge where the three-way call takes place.
394 *
395 * \retval 0 Success
396 * \retval -1 Failure
397 */
399 struct ast_channel *survivor_channel, struct ast_bridge *survivor_bridge);
400
401/*!
402 * \brief Add details for an attended transfer to an application
403 *
404 * If the transfer is sending one or more parties into an application, then this should be called
405 * to add appropriate details to the transfer message being published.
406 *
407 * \param transfer_msg The message to add details to
408 * \param app The name of the application that the parties are being transferred to
409 * \param replace_channel The local channel that is in the bridge and running the application
410 *
411 * \retval 0 Success
412 * \retval -1 Failure
413 */
415 const char *app, struct ast_channel *replace_channel);
416
417/*!
418 * \brief Add details for an attended transfer that has a link between bridges.
419 *
420 * An attended transfer may be accomplished by linking two bridges together with local channels.
421 * If this is how the transfer is to be completed, call this function in order to fill in details
422 * about the transfer.
423 *
424 * \param transfer_msg The message to add details to.
425 * \param locals An array of local channel halves that each are in one of the involved bridges.
426 *
427 * \retval 0 Success
428 * \retval -1 Failure
429 */
431 struct ast_channel *locals[2]);
432
433/*!
434 * \brief Publish an attended transfer
435 *
436 * \param transfer_msg The transfer message to publish
437 */
439
440/*!
441 * \since 12
442 * \brief Message type for \ref ast_attended_transfer_message.
443 *
444 * \retval Message type for \ref ast_attended_transfer_message.
445 */
447
448/*!
449 * \brief Returns the current snapshot for the bridge.
450 * \since 17.0
451 *
452 * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
453 *
454 * \param bridge_id Uniqueid of the bridge from which to get the snapshot.
455 * \return Most recent snapshot. ao2_cleanup() when done.
456 * \retval NULL if bridge or snapshot doesn't exist.
457 */
459 const char *bridge_id);
460
461/*!
462 * \brief Returns the current snapshot for the bridge.
463 * \since 17.0
464 *
465 * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
466 *
467 * \param bridge The bridge from which to get the snapshot.
468 * \return Most recent snapshot. ao2_cleanup() when done.
469 * \retval NULL if there isn't a snapshot.
470 */
472 struct ast_bridge *bridge);
473
474/*!
475 * \internal
476 * \brief Initialize the topics for a single bridge.
477 * \retval 0 on success.
478 * \retval Non-zero on error.
479 */
480int bridge_topics_init(struct ast_bridge *bridge);
481
482/*!
483 * \internal
484 * \since 17.0
485 * \brief Publish destroy then cleanup topics.
486 *
487 * \param bridge The bridge to clean up
488 */
489void bridge_topics_destroy(struct ast_bridge *bridge);
490
491/*!
492 * \internal
493 * \brief Initialize the stasis bridging topic and message types
494 * \retval 0 on success
495 * \retval -1 on failure
496 */
498
499#if defined(__cplusplus) || defined(c_plusplus)
500}
501#endif
502
503#endif /* _STASIS_BRIDGING_H */
static const char app[]
Definition: app_adsiprog.c:56
Bridging API.
ast_transfer_result
Definition: bridge.h:1098
static const char type[]
Definition: chan_ooh323.c:109
General Asterisk PBX channel definitions.
#define AST_MAX_CONTEXT
Definition: channel.h:135
#define AST_MAX_EXTENSION
Definition: channel.h:134
static struct ao2_container * locals
Definition: core_local.c:138
A set of macros to manage forward-linked lists.
Asterisk locking-related definitions:
Core PBX routines and definitions.
#define AST_MAX_APP
Definition: pbx.h:40
void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from)
Publish a bridge merge.
void ast_bridge_publish_attended_transfer(struct ast_attended_transfer_message *transfer_msg)
Publish an attended transfer.
void ast_bridge_publish_blind_transfer(struct ast_blind_transfer_message *transfer_message)
Publish a blind transfer event.
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 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.
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_bridge_snapshot * ast_bridge_get_snapshot(struct ast_bridge *bridge)
Returns the current snapshot for the bridge.
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.
int bridge_topics_init(struct ast_bridge *bridge)
void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan)
Publish a bridge channel leave event.
struct ast_bridge_snapshot * ast_bridge_get_snapshot_by_uniqueid(const char *bridge_id)
Returns the current snapshot for the bridge.
struct stasis_message_type * ast_bridge_snapshot_type(void)
Message type for ast_bridge_snapshot.
struct stasis_message_type * ast_channel_entered_bridge_type(void)
Message type for ast_channel enter bridge blob messages.
struct stasis_message_type * ast_blind_transfer_type(void)
Message type for ast_blind_transfer_message.
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_state(struct ast_bridge *bridge)
Publish the state of a bridge.
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.
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.
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 stasis_topic * ast_bridge_topic(struct ast_bridge *bridge)
A topic which publishes the events for a particular bridge.
struct stasis_message_type * ast_attended_transfer_type(void)
Message type for ast_attended_transfer_message.
struct stasis_message_type * ast_bridge_merge_message_type(void)
Message type for ast_bridge_merge_message.
struct stasis_topic * ast_bridge_topic_all(void)
A topic which publishes the events for all bridges.
int ast_stasis_bridging_init(void)
void bridge_topics_destroy(struct ast_bridge *bridge)
void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap)
Publish a bridge channel enter event.
ast_attended_transfer_dest_type
@ AST_ATTENDED_TRANSFER_DEST_FAIL
@ AST_ATTENDED_TRANSFER_DEST_BRIDGE_MERGE
@ AST_ATTENDED_TRANSFER_DEST_LOCAL_APP
@ AST_ATTENDED_TRANSFER_DEST_LINK
@ AST_ATTENDED_TRANSFER_DEST_APP
@ AST_ATTENDED_TRANSFER_DEST_THREEWAY
struct stasis_message_type * ast_channel_left_bridge_type(void)
Message type for ast_channel leave bridge blob messages.
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.
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.
Message representing attended transfer.
union ast_attended_transfer_message::@284 dest
enum ast_attended_transfer_dest_type dest_type
struct ast_channel_snapshot * replace_channel
struct ast_channel_snapshot * links[2]
struct ast_bridge_channel_snapshot_pair to_transfer_target
struct ast_channel_snapshot * transferee
struct ast_bridge_channel_snapshot_pair threeway
enum ast_transfer_result result
struct ast_bridge_channel_snapshot_pair to_transferee
char bridge[AST_UUID_STR_LEN]
struct ast_channel_snapshot * target
Message published during a blind transfer.
struct ast_channel_snapshot * replace_channel
char exten[AST_MAX_EXTENSION]
struct ast_bridge_snapshot * bridge
struct ast_channel_snapshot * transferer
struct ast_channel_snapshot * transferee
enum ast_transfer_result result
char context[AST_MAX_CONTEXT]
Blob of data associated with a bridge.
struct ast_bridge_snapshot * bridge
struct ast_channel_snapshot * channel
struct ast_json * blob
Pair showing a bridge snapshot and a specific channel snapshot belonging to the bridge.
struct ast_bridge_snapshot * bridge_snapshot
struct ast_channel_snapshot * channel_snapshot
Message representing the merge of two bridges.
struct ast_bridge_snapshot * from
struct ast_bridge_snapshot * to
struct ast_bridge_snapshot * new_snapshot
struct ast_bridge_snapshot * old_snapshot
Structure that contains a snapshot of information about a bridge.
Definition: bridge.h:314
Structure that contains information about a bridge.
Definition: bridge.h:349
Structure representing a snapshot of channel state.
Main Channel structure associated with a channel.
Abstract JSON element (object, array, string, int, ...).
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200
Utility functions.
#define AST_UUID_STR_LEN
Definition: uuid.h:27