Add multi-channel Stasis messages; refactor Dial AMI events to Stasis
[asterisk/asterisk.git] / include / asterisk / stasis_channels.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Matt Jordan <mjordan@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
20 #ifndef STASIS_CHANNELS_H_
21 #define STASIS_CHANNELS_H_
22
23 #include "asterisk/stringfields.h"
24 #include "asterisk/stasis.h"
25 #include "asterisk/json.h"
26 #include "asterisk/channel.h"
27
28 /*! \addtogroup StasisTopicsAndMessages
29  * @{
30  */
31
32 /*!
33  * \since 12
34  * \brief Structure representing a snapshot of channel state.
35  *
36  * While not enforced programmatically, this object is shared across multiple
37  * threads, and should be threated as an immutable object.
38  */
39 struct ast_channel_snapshot {
40         AST_DECLARE_STRING_FIELDS(
41                 AST_STRING_FIELD(name);                 /*!< ASCII unique channel name */
42                 AST_STRING_FIELD(accountcode);          /*!< Account code for billing */
43                 AST_STRING_FIELD(peeraccount);          /*!< Peer account code for billing */
44                 AST_STRING_FIELD(userfield);            /*!< Userfield for CEL billing */
45                 AST_STRING_FIELD(uniqueid);             /*!< Unique Channel Identifier */
46                 AST_STRING_FIELD(linkedid);             /*!< Linked Channel Identifier -- gets propagated by linkage */
47                 AST_STRING_FIELD(parkinglot);           /*!< Default parking lot, if empty, default parking lot */
48                 AST_STRING_FIELD(hangupsource);         /*!< Who is responsible for hanging up this channel */
49                 AST_STRING_FIELD(appl);                 /*!< Current application */
50                 AST_STRING_FIELD(data);                 /*!< Data passed to current application */
51                 AST_STRING_FIELD(context);              /*!< Dialplan: Current extension context */
52                 AST_STRING_FIELD(exten);                /*!< Dialplan: Current extension number */
53                 AST_STRING_FIELD(caller_name);          /*!< Caller ID Name */
54                 AST_STRING_FIELD(caller_number);        /*!< Caller ID Number */
55                 AST_STRING_FIELD(connected_name);       /*!< Connected Line Name */
56                 AST_STRING_FIELD(connected_number);     /*!< Connected Line Number */
57         );
58
59         struct timeval creationtime;    /*!< The time of channel creation */
60         enum ast_channel_state state;   /*!< State of line */
61         int priority;                   /*!< Dialplan: Current extension priority */
62         int amaflags;                   /*!< AMA flags for billing */
63         int hangupcause;                /*!< Why is the channel hanged up. See causes.h */
64         int caller_pres;                /*!< Caller ID presentation. */
65         struct ast_flags flags;         /*!< channel flags of AST_FLAG_ type */
66         struct varshead *manager_vars;  /*!< Variables to be appended to manager events */
67 };
68
69 /*!
70  * \since 12
71  * \brief Blob of data associated with a channel.
72  *
73  * The \c blob is actually a JSON object of structured data. It has a "type" field
74  * which contains the type string describing this blob.
75  */
76 struct ast_channel_blob {
77         /*! Channel blob is associated with (or NULL for global/all channels) */
78         struct ast_channel_snapshot *snapshot;
79         /*! JSON blob of data */
80         struct ast_json *blob;
81 };
82
83 /*!
84  * \since 12
85  * \brief A set of channels with blob objects - see \ref ast_channel_blob
86  */
87 struct ast_multi_channel_blob;
88
89 /*!
90  * \since 12
91  * \brief A topic which publishes the events for all channels.
92  * \retval Topic for all channel events.
93  */
94 struct stasis_topic *ast_channel_topic_all(void);
95
96 /*!
97  * \since 12
98  * \brief A caching topic which caches \ref ast_channel_snapshot messages from
99  * ast_channel_events_all(void).
100  *
101  * \retval Topic for all channel events.
102  */
103 struct stasis_caching_topic *ast_channel_topic_all_cached(void);
104
105 /*!
106  * \since 12
107  * \brief Message type for \ref ast_channel_snapshot.
108  *
109  * \retval Message type for \ref ast_channel_snapshot.
110  */
111 struct stasis_message_type *ast_channel_snapshot_type(void);
112
113 /*!
114  * \since 12
115  * \brief Message type for \ref ast_channel_blob messages.
116  *
117  * \retval Message type for \ref ast_channel_blob messages.
118  */
119 struct stasis_message_type *ast_channel_blob_type(void);
120
121 /*!
122  * \since 12
123  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
124  * ao2_cleanup() to deallocate.
125  *
126  * \param chan The channel from which to generate a snapshot
127  *
128  * \retval pointer on success (must be ast_freed)
129  * \retval NULL on error
130  */
131 struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan);
132
133 /*!
134  * \since 12
135  * \brief Creates a \ref ast_channel_blob message.
136  *
137  * The \a blob JSON object requires a \c "type" field describing the blob. It
138  * should also be treated as immutable and not modified after it is put into the
139  * message.
140  *
141  * \param chan Channel blob is associated with, or NULL for global/all channels.
142  * \param blob JSON object representing the data.
143  * \return \ref ast_channel_blob message.
144  * \return \c NULL on error
145  */
146 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
147                                                struct ast_json *blob);
148
149 /*!
150  * \since 12
151  * \brief Extracts the type field from a \ref ast_channel_blob.
152  * Returned \c char* is still owned by \a obj
153  * \param obj Channel blob object.
154  * \return Type field value from the blob.
155  * \return \c NULL on error.
156  */
157 const char *ast_channel_blob_json_type(struct ast_channel_blob *obj);
158
159 /*!
160  * \since 12
161  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message
162  *
163  * \note Similar to a \ref ast_channel_blob, the \ref ast_multi_channel_blob requires
164  * a \a blob JSON object containing a \c "type" field describing the blob. It
165  * should also be treated as immutable and not modified after it is put into the
166  * message.
167  *
168  * \param blob The JSON blob that defines the type of this \ref ast_multi_channel_blob
169  *
170  * \return \ref ast_multi_channel_blob object
171  * \return \c NULL on error
172 */
173 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
174
175 /*!
176  * \since 12
177  * \brief Retrieve a channel snapshot associated with a specific role from a
178  * \ref ast_multi_channel_blob
179  *
180  * \note The reference count of the \ref ast_channel_snapshot returned from
181  * this function is not changed. The caller of this function does not own the
182  * reference to the snapshot.
183  *
184  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
185  * to retrieve
186  * \param role The role associated with the channel snapshot
187  *
188  * \retval \ref ast_channel_snapshot matching the role on success
189  * \retval NULL on error or not found for the role specified
190  */
191 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
192                                                struct ast_multi_channel_blob *obj,
193                                                const char *role);
194
195 /*!
196  * \since 12
197  * \brief Retrieve all channel snapshots associated with a specific role from
198  * a \ref ast_multi_channel_blob
199  *
200  * \note Because this function returns an ao2_container (hashed by channel name)
201  * of all channel snapshots that matched the passed in role, the reference of
202  * the snapshots is increased by this function. The caller of this function must
203  * release the reference to the snapshots by disposing of the container
204  * appropriately.
205  *
206  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
207  * retrieve
208  * \param role The role associated with the channel snapshots
209  *
210  * \retval A container containing all \ref ast_channel_snapshot objects matching
211  * the role on success.
212  * \retval NULL on error or not found for the role specified
213  */
214 struct ao2_container *ast_multi_channel_blob_get_channels(
215                                                struct ast_multi_channel_blob *obj,
216                                                const char *role);
217
218 /*!
219  * \since 12
220  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
221  * Returned \ref ast_json is still owned by \a obj
222  *
223  * \param obj Channel blob object.
224  * \return Type field value from the blob.
225  * \return \c NULL on error.
226  */
227 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
228
229 /*!
230  * \since 12
231  * \brief Extracts the type field from a \ref ast_multi_channel_blob.
232  * Returned \c char* is still owned by \a obj
233  *
234  * \param obj Channel blob object.
235  * \return Type field value from the blob.
236  * \return \c NULL on error.
237  */
238 const char *ast_multi_channel_blob_get_type(struct ast_multi_channel_blob *obj);
239
240 /*!
241  * \since 12
242  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
243  *
244  * \note This will increase the reference count by 1 for the channel snapshot. It is
245  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
246  *
247  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
248  * \param role A \a role that the snapshot has in the multi channel relationship
249  * \param snapshot The \ref ast_channel_snapshot being added to the
250  * \ref ast_multi_channel_blob object
251  */
252 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
253                                                const char *role,
254                                                struct ast_channel_snapshot *snapshot);
255
256 /*!
257  * \since 12
258  * \brief Publish a \ref ast_channel_varset for a channel.
259  *
260  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
261  * \param variable Name of the variable being set
262  * \param value Value.
263  */
264 void ast_channel_publish_varset(struct ast_channel *chan,
265                                 const char *variable, const char *value);
266
267 /*!
268  * \since 12
269  * \brief Message type for when a channel dials another channel
270  *
271  * \retval A stasis message type
272  */
273 struct stasis_message_type *ast_channel_dial_type(void);
274
275 /*!
276  * \since 12
277  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
278  * topics a stasis message for the channels involved in a dial operation.
279  *
280  * \param caller The channel performing the dial operation
281  * \param peer The channel being dialed
282  * \param dialstring When beginning a dial, the information passed to the
283  * dialing application
284  * \param dialstatus The current status of the dial operation (NULL if no
285  * status is known)
286  */
287 void ast_channel_publish_dial(struct ast_channel *caller,
288                 struct ast_channel *peer,
289                 const char *dialstring,
290                 const char *dialstatus);
291
292 /*! @} */
293
294 /*!
295  * \brief Dispose of the stasis channel topics and message types
296  */
297 void ast_stasis_channels_shutdown(void);
298
299 /*!
300  * \brief Initialize the stasis channel topic and message types
301  */
302 void ast_stasis_channels_init(void);
303
304 #endif /* STASIS_CHANNELS_H_ */