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