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