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