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