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