Fix two more possible crashes in CEL
[asterisk/asterisk.git] / include / asterisk / stasis_bridging.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/bridging.h"
32
33 /*!
34  * \brief Structure that contains a snapshot of information about a bridge
35  */
36 struct ast_bridge_snapshot {
37         AST_DECLARE_STRING_FIELDS(
38                 /*! Immutable bridge UUID. */
39                 AST_STRING_FIELD(uniqueid);
40                 /*! Bridge technology that is handling the bridge */
41                 AST_STRING_FIELD(technology);
42                 /*! Bridge subclass that is handling the bridge */
43                 AST_STRING_FIELD(subclass);
44         );
45         /*! AO2 container of bare channel uniqueid strings participating in the bridge.
46          * Allocated from ast_str_container_alloc() */
47         struct ao2_container *channels;
48         /*! Bridge flags to tweak behavior */
49         struct ast_flags feature_flags;
50         /*! Bridge capabilities */
51         uint32_t capabilities;
52         /*! Number of channels participating in the bridge */
53         unsigned int num_channels;
54         /*! Number of active channels in the bridge. */
55         unsigned int num_active;
56 };
57
58 /*!
59  * \since 12
60  * \brief Generate a snapshot of the bridge state. This is an ao2 object, so
61  * ao2_cleanup() to deallocate.
62  *
63  * \param bridge The bridge from which to generate a snapshot
64  *
65  * \retval AO2 refcounted snapshot on success
66  * \retval NULL on error
67  */
68 struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge);
69
70 /*!
71  * \since 12
72  * \brief Message type for \ref ast_bridge_snapshot.
73  *
74  * \retval Message type for \ref ast_bridge_snapshot.
75  */
76 struct stasis_message_type *ast_bridge_snapshot_type(void);
77
78 /*!
79  * \since 12
80  * \brief A topic which publishes the events for a particular bridge.
81  *
82  * If the given \a bridge is \c NULL, ast_bridge_topic_all() is returned.
83  *
84  * \param bridge Bridge for which to get a topic or \c NULL.
85  *
86  * \retval Topic for bridge's events.
87  * \retval ast_bridge_topic_all() if \a bridge is \c NULL.
88  */
89 struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
90
91 /*!
92  * \since 12
93  * \brief A topic which publishes the events for all bridges.
94  * \retval Topic for all bridge events.
95  */
96 struct stasis_topic *ast_bridge_topic_all(void);
97
98 /*!
99  * \since 12
100  * \brief A caching topic which caches \ref ast_bridge_snapshot messages from
101  * ast_bridge_events_all(void).
102  *
103  * \retval Caching topic for all bridge events.
104  */
105 struct stasis_caching_topic *ast_bridge_topic_all_cached(void);
106
107 /*!
108  * \since 12
109  * \brief Publish the state of a bridge
110  *
111  * \param bridge The bridge for which to publish state
112  */
113 void ast_bridge_publish_state(struct ast_bridge *bridge);
114
115 /*! \brief Message representing the merge of two bridges */
116 struct ast_bridge_merge_message {
117         struct ast_bridge_snapshot *from;       /*!< Bridge from which channels will be removed during the merge */
118         struct ast_bridge_snapshot *to;         /*!< Bridge to which channels will be added during the merge */
119 };
120
121 /*!
122  * \since 12
123  * \brief Message type for \ref ast_bridge_merge_message.
124  *
125  * \retval Message type for \ref ast_bridge_merge_message.
126  */
127 struct stasis_message_type *ast_bridge_merge_message_type(void);
128
129 /*!
130  * \since 12
131  * \brief Publish a bridge merge
132  *
133  * \param to The bridge to which channels are being added
134  * \param from The bridge from which channels are being removed
135  */
136 void ast_bridge_publish_merge(struct ast_bridge *to, struct ast_bridge *from);
137
138 /*!
139  * \since 12
140  * \brief Blob of data associated with a bridge.
141  *
142  * The \c blob is actually a JSON object of structured data. It has a "type" field
143  * which contains the type string describing this blob.
144  */
145 struct ast_bridge_blob {
146         /*! Bridge blob is associated with (or NULL for global/all bridges) */
147         struct ast_bridge_snapshot *bridge;
148         /*! Channel blob is associated with (may be NULL for some messages) */
149         struct ast_channel_snapshot *channel;
150         /*! JSON blob of data */
151         struct ast_json *blob;
152 };
153
154 /*!
155  * \since 12
156  * \brief Message type for \ref channel enter bridge blob messages.
157  *
158  * \retval Message type for \ref channel enter bridge blob messages.
159  */
160 struct stasis_message_type *ast_channel_entered_bridge_type(void);
161
162 /*!
163  * \since 12
164  * \brief Message type for \ref channel leave bridge blob messages.
165  *
166  * \retval Message type for \ref channel leave bridge blob messages.
167  */
168 struct stasis_message_type *ast_channel_left_bridge_type(void);
169
170 /*!
171  * \since 12
172  * \brief Creates a \ref ast_bridge_blob message.
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  * \param bridge Channel blob is associated with, or NULL for global/all bridges.
179  * \param blob JSON object representing the data.
180  * \return \ref ast_bridge_blob message.
181  * \return \c NULL on error
182  */
183 struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
184         struct ast_bridge *bridge,
185         struct ast_channel *chan,
186         struct ast_json *blob);
187
188 /*!
189  * \since 12
190  * \brief Publish a bridge channel enter event
191  *
192  * \param bridge The bridge a channel entered
193  * \param chan The channel that entered the bridge
194  */
195 void ast_bridge_publish_enter(struct ast_bridge *bridge, struct ast_channel *chan);
196
197 /*!
198  * \since 12
199  * \brief Publish a bridge channel leave event
200  *
201  * \param bridge The bridge a channel left
202  * \param chan The channel that left the bridge
203  */
204 void ast_bridge_publish_leave(struct ast_bridge *bridge, struct ast_channel *chan);
205
206 /*!
207  * \brief Build a JSON object from a \ref ast_bridge_snapshot.
208  * \return JSON object representing bridge snapshot.
209  * \return \c NULL on error
210  */
211 struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot);
212
213 /*!
214  * \brief Returns the most recent snapshot for the bridge.
215  *
216  * The returned pointer is AO2 managed, so ao2_cleanup() when you're done.
217  *
218  * \param bridge_id Uniqueid of the bridge for which to get the snapshot.
219  * \return Most recent snapshot. ao2_cleanup() when done.
220  * \return \c NULL if channel isn't in cache.
221  */
222 struct ast_bridge_snapshot *ast_bridge_snapshot_get_latest(
223         const char *bridge_id);
224
225 /*!
226  * \brief Initialize the stasis bridging topic and message types
227  * \retval 0 on success
228  * \retval -1 on failure
229  */
230 int ast_stasis_bridging_init(void);
231
232 #if defined(__cplusplus) || defined(c_plusplus)
233 }
234 #endif
235
236 #endif  /* _STASIS_BRIDGING_H */