d16b92dc2f067a5cc2825d10d1688acbbafd63e1
[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 treated 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                 AST_STRING_FIELD(language);             /*!< The default spoken language for the channel */
58         );
59
60         struct timeval creationtime;    /*!< The time of channel creation */
61         enum ast_channel_state state;   /*!< State of line */
62         int priority;                   /*!< Dialplan: Current extension priority */
63         int amaflags;                   /*!< AMA flags for billing */
64         int hangupcause;                /*!< Why is the channel hanged up. See causes.h */
65         int caller_pres;                /*!< Caller ID presentation. */
66         struct ast_flags flags;         /*!< channel flags of AST_FLAG_ type */
67         struct varshead *manager_vars;  /*!< Variables to be appended to manager events */
68 };
69
70 /*!
71  * \since 12
72  * \brief Blob of data associated with a channel.
73  *
74  * This blob is actually shared amongst several \ref stasis_message_type's.
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 A caching topic which caches \ref ast_channel_snapshot messages from
108  * ast_channel_events_all(void) and indexes them by name.
109  *
110  * \retval Topic for all channel events.
111  */
112 struct stasis_caching_topic *ast_channel_topic_all_cached_by_name(void);
113
114 /*!
115  * \since 12
116  * \brief Message type for \ref ast_channel_snapshot.
117  *
118  * \retval Message type for \ref ast_channel_snapshot.
119  */
120 struct stasis_message_type *ast_channel_snapshot_type(void);
121
122 /*!
123  * \since 12
124  * \brief Generate a snapshot of the channel state. This is an ao2 object, so
125  * ao2_cleanup() to deallocate.
126  *
127  * \param chan The channel from which to generate a snapshot
128  *
129  * \retval pointer on success (must be ast_freed)
130  * \retval NULL on error
131  */
132 struct ast_channel_snapshot *ast_channel_snapshot_create(
133         struct ast_channel *chan);
134
135 /*!
136  * \since 12
137  * \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
138  * an ao2 object, so use \ref ao2_cleanup() to deallocate.
139  *
140  * \param unique_id The channel's unique ID
141  *
142  * \retval A \ref ast_channel_snapshot on success
143  * \retval NULL on error
144  */
145 struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniqueid);
146
147 /*!
148  * \since 12
149  * \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
150  * an ao2 object, so use \ref ao2_cleanup() to deallocate.
151  *
152  * \param name The channel's name
153  *
154  * \retval A \ref ast_channel_snapshot on success
155  * \retval NULL on error
156  */
157 struct ast_channel_snapshot *ast_channel_snapshot_get_latest_by_name(const char *name);
158
159 /*!
160  * \since 12
161  * \brief Creates a \ref ast_channel_blob message.
162  *
163  * The given \a blob should be treated as immutable and not modified after it is
164  * put into the message.
165  *
166  * \param chan Channel blob is associated with, or \c NULL for global/all channels.
167  * \param type Message type for this blob.
168  * \param blob JSON object representing the data, or \c NULL for no data. If
169  *             \c NULL, ast_json_null() is put into the object.
170  *
171  * \return \ref ast_channel_blob message.
172  * \return \c NULL on error
173  */
174 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
175         struct stasis_message_type *type, struct ast_json *blob);
176
177 /*!
178  * \since 12
179  * \brief Create a \ref ast_channel_blob message, pulling channel state from
180  *        the cache.
181  *
182  * \param uniqueid Uniqueid of the channel.
183  * \param type Message type for this blob.
184  * \param blob JSON object representing the data, or \c NULL for no data. If
185  *             \c NULL, ast_json_null() is put into the object.
186  *
187  * \return \ref ast_channel_blob message.
188  * \return \c NULL on error
189  */
190 struct stasis_message *ast_channel_blob_create_from_cache(
191         const char *uniqueid, struct stasis_message_type *type,
192         struct ast_json *blob);
193
194 /*!
195  * \since 12
196  * \brief Create a \ref ast_multi_channel_blob suitable for a \ref stasis_message.
197  *
198  * The given \a blob should be treated as immutable and not modified after it is
199  * put into the message.
200  *
201  * \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
202  *
203  * \return \ref ast_multi_channel_blob object
204  * \return \c NULL on error
205 */
206 struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
207
208 /*!
209  * \since 12
210  * \brief Retrieve a channel snapshot associated with a specific role from a
211  * \ref ast_multi_channel_blob
212  *
213  * \note The reference count of the \ref ast_channel_snapshot returned from
214  * this function is not changed. The caller of this function does not own the
215  * reference to the snapshot.
216  *
217  * \param obj The \ref ast_multi_channel_blob containing the channel snapshot
218  * to retrieve
219  * \param role The role associated with the channel snapshot
220  *
221  * \retval \ref ast_channel_snapshot matching the role on success
222  * \retval NULL on error or not found for the role specified
223  */
224 struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
225         struct ast_multi_channel_blob *obj, const char *role);
226
227 /*!
228  * \since 12
229  * \brief Retrieve all channel snapshots associated with a specific role from
230  * a \ref ast_multi_channel_blob
231  *
232  * \note Because this function returns an ao2_container (hashed by channel name)
233  * of all channel snapshots that matched the passed in role, the reference of
234  * the snapshots is increased by this function. The caller of this function must
235  * release the reference to the snapshots by disposing of the container
236  * appropriately.
237  *
238  * \param obj The \ref ast_multi_channel_blob containing the channel snapshots to
239  * retrieve
240  * \param role The role associated with the channel snapshots
241  *
242  * \retval A container containing all \ref ast_channel_snapshot objects matching
243  * the role on success.
244  * \retval NULL on error or not found for the role specified
245  */
246 struct ao2_container *ast_multi_channel_blob_get_channels(
247         struct ast_multi_channel_blob *obj, const char *role);
248
249 /*!
250  * \since 12
251  * \brief Retrieve the JSON blob from a \ref ast_multi_channel_blob.
252  * Returned \ref ast_json is still owned by \a obj
253  *
254  * \param obj Channel blob object.
255  * \return Type field value from the blob.
256  * \return \c NULL on error.
257  */
258 struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
259
260 /*!
261  * \since 12
262  * \brief Add a \ref ast_channel_snapshot to a \ref ast_multi_channel_blob object
263  *
264  * \note This will increase the reference count by 1 for the channel snapshot. It is
265  * assumed that the \ref ast_multi_channel_blob will own a reference to the object.
266  *
267  * \param obj The \ref ast_multi_channel_blob object that will reference the snapshot
268  * \param role A \a role that the snapshot has in the multi channel relationship
269  * \param snapshot The \ref ast_channel_snapshot being added to the
270  * \ref ast_multi_channel_blob object
271  */
272 void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
273         const char *role, struct ast_channel_snapshot *snapshot);
274
275 /*!
276  * \brief Publish a channel blob message.
277  * \since 12.0.0
278  *
279  * \param chan Channel publishing the blob.
280  * \param type Type of stasis message.
281  * \param blob The blob being published. (NULL if no blob)
282  *
283  * \return Nothing
284  */
285 void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_type *type,
286         struct ast_json *blob);
287
288 /*!
289  * \since 12
290  * \brief Publish a \ref ast_channel_snapshot for a channel.
291  *
292  * \param chan Channel to publish.
293  */
294 void ast_channel_publish_snapshot(struct ast_channel *chan);
295
296 /*!
297  * \since 12
298  * \brief Publish a \ref ast_channel_varset for a channel.
299  *
300  * \param chan Channel to pulish the event for, or \c NULL for 'none'.
301  * \param variable Name of the variable being set
302  * \param value Value.
303  */
304 void ast_channel_publish_varset(struct ast_channel *chan,
305                                 const char *variable, const char *value);
306
307 /*!
308  * \since 12
309  * \brief Message type for when a channel dials another channel
310  *
311  * \retval A stasis message type
312  */
313 struct stasis_message_type *ast_channel_dial_type(void);
314
315 /*!
316  * \since 12
317  * \brief Message type for when a variable is set on a channel.
318  *
319  * \retval A stasis message type
320  */
321 struct stasis_message_type *ast_channel_varset_type(void);
322
323 /*!
324  * \since 12
325  * \brief Message type for when a custom user event is sent on a channel.
326  *
327  * \retval A stasis message type
328  */
329 struct stasis_message_type *ast_channel_user_event_type(void);
330
331 /*!
332  * \since 12
333  * \brief Message type for when a hangup is requested on a channel.
334  *
335  * \retval A stasis message type
336  */
337 struct stasis_message_type *ast_channel_hangup_request_type(void);
338
339 /*!
340  * \since 12
341  * \brief Message type for when DTMF begins on a channel.
342  *
343  * \retval A stasis message type
344  */
345 struct stasis_message_type *ast_channel_dtmf_begin_type(void);
346
347 /*!
348  * \since 12
349  * \brief Message type for when DTMF ends on a channel.
350  *
351  * \retval A stasis message type
352  */
353 struct stasis_message_type *ast_channel_dtmf_end_type(void);
354
355 /*!
356  * \since 12
357  * \brief Message type for when a channel is placed on hold.
358  *
359  * \retval A stasis message type
360  */
361 struct stasis_message_type *ast_channel_hold_type(void);
362
363 /*!
364  * \since 12
365  * \brief Message type for when a channel is removed from hold.
366  *
367  * \retval A stasis message type
368  */
369 struct stasis_message_type *ast_channel_unhold_type(void);
370
371 /*!
372  * \since 12
373  * \brief Message type for when a channel starts spying on another channel
374  *
375  * \retval A stasis message type
376  */
377 struct stasis_message_type *ast_channel_chanspy_start_type(void);
378
379 /*!
380  * \since 12
381  * \brief Message type for when a channel stops spying on another channel
382  *
383  * \retval A stasis message type
384  */
385 struct stasis_message_type *ast_channel_chanspy_stop_type(void);
386
387 /*!
388  * \since 12
389  * \brief Message type for a fax operation
390  *
391  * \retval A stasis message type
392  */
393 struct stasis_message_type *ast_channel_fax_type(void);
394
395 /*!
396  * \since 12
397  * \brief Message type for hangup handler related actions
398  *
399  * \retval A stasis message type
400  */
401 struct stasis_message_type *ast_channel_hangup_handler_type(void);
402
403 /*!
404  * \since 12
405  * \brief Message type for starting monitor on a channel
406  *
407  * \retval A stasis message type
408  */
409 struct stasis_message_type *ast_channel_monitor_start_type(void);
410
411 /*!
412  * \since 12
413  * \brief Message type for stopping monitor on a channel
414  *
415  * \retval A stasis message type
416  */
417 struct stasis_message_type *ast_channel_monitor_stop_type(void);
418
419 /*!
420  * \since 12
421  * \brief Message type for starting music on hold on a channel
422  *
423  * \retval A stasis message type
424  */
425 struct stasis_message_type *ast_channel_moh_start_type(void);
426
427 /*!
428  * \since 12
429  * \brief Message type for stopping music on hold on a channel
430  *
431  * \retval A stasis message type
432  */
433 struct stasis_message_type *ast_channel_moh_stop_type(void);
434
435 /*!
436  * \since 12
437  * \brief Publish in the \ref ast_channel_topic or \ref ast_channel_topic_all
438  * topics a stasis message for the channels involved in a dial operation.
439  *
440  * \param caller The channel performing the dial operation
441  * \param peer The channel being dialed
442  * \param dialstring When beginning a dial, the information passed to the
443  * dialing application
444  * \param dialstatus The current status of the dial operation (NULL if no
445  * status is known)
446  */
447 void ast_channel_publish_dial(struct ast_channel *caller,
448                 struct ast_channel *peer,
449                 const char *dialstring,
450                 const char *dialstatus);
451
452 /*!
453  * \since 12
454  * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
455  * message indicating a change in channel state
456  *
457  * \param chan The channel whose state has changed
458  */
459 void ast_publish_channel_state(struct ast_channel *chan);
460
461 /*! @} */
462
463 /*!
464  * \brief Build a JSON object from a \ref ast_channel_snapshot.
465  * \return JSON object representing channel snapshot.
466  * \return \c NULL on error
467  */
468 struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot);
469
470 /*!
471  * \brief Compares the context, exten and priority of two snapshots.
472  * \since 12
473  *
474  * \param old_snapshot Old snapshot
475  * \param new_snapshot New snapshot
476  *
477  * \return True (non-zero) if context, exten or priority are identical.
478  * \return False (zero) if context, exten and priority changed.
479  */
480 int ast_channel_snapshot_cep_equal(
481         const struct ast_channel_snapshot *old_snapshot,
482         const struct ast_channel_snapshot *new_snapshot);
483
484 /*!
485  * \brief Compares the callerid info of two snapshots.
486  * \since 12
487  *
488  * \param old_snapshot Old snapshot
489  * \param new_snapshot New snapshot
490  *
491  * \return True (non-zero) if callerid are identical.
492  * \return False (zero) if callerid changed.
493  */
494 int ast_channel_snapshot_caller_id_equal(
495         const struct ast_channel_snapshot *old_snapshot,
496         const struct ast_channel_snapshot *new_snapshot);
497
498 /*!
499  * \brief Initialize the stasis channel topic and message types
500  */
501 void ast_stasis_channels_init(void);
502
503 #endif /* STASIS_CHANNELS_H_ */