Add missing end-of-file line terminators.
[asterisk/asterisk.git] / include / asterisk / bridging_channel.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  * Richard Mudgett <rmudgett@digium.com>
8  * Matt Jordan <mjordan@digium.com>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20
21 /*!
22  * \file
23  * \brief Bridging Channel API
24  *
25  * An API that act on a channel in a bridge
26  *
27  * \author Joshua Colp <jcolp@digium.com>
28  * \author Richard Mudgett <rmudgett@digium.com>
29  * \author Matt Jordan <mjordan@digium.com>
30  *
31  * See Also:
32  * \ref bridging.h
33  * \arg \ref AstCREDITS
34  */
35
36 #ifndef _ASTERISK_BRIDGING_CHANNEL_H
37 #define _ASTERISK_BRIDGING_CHANNEL_H
38
39 #if defined(__cplusplus) || defined(c_plusplus)
40 extern "C" {
41 #endif
42
43 #include "asterisk/bridging_technology.h"
44
45 /*! \brief State information about a bridged channel */
46 enum ast_bridge_channel_state {
47         /*! Waiting for a signal (Channel in the bridge) */
48         AST_BRIDGE_CHANNEL_STATE_WAIT = 0,
49         /*! Bridged channel was forced out and should be hung up (Bridge may dissolve.) */
50         AST_BRIDGE_CHANNEL_STATE_END,
51         /*! Bridged channel was forced out and should be hung up */
52         AST_BRIDGE_CHANNEL_STATE_HANGUP,
53 };
54
55 enum ast_bridge_channel_thread_state {
56         /*! Bridge channel thread is idle/waiting. */
57         AST_BRIDGE_CHANNEL_THREAD_IDLE,
58         /*! Bridge channel thread is writing a normal/simple frame. */
59         AST_BRIDGE_CHANNEL_THREAD_SIMPLE,
60         /*! Bridge channel thread is processing a frame. */
61         AST_BRIDGE_CHANNEL_THREAD_FRAME,
62 };
63
64 /*! \brief Actions that can be taken on a channel in a bridge */
65 enum ast_bridge_action_type {
66         /*! Bridged channel is to detect a feature hook */
67         AST_BRIDGE_ACTION_FEATURE,
68         /*! Bridged channel is to act on an interval hook */
69         AST_BRIDGE_ACTION_INTERVAL,
70         /*! Bridged channel is to send a DTMF stream out */
71         AST_BRIDGE_ACTION_DTMF_STREAM,
72         /*! Bridged channel is to indicate talking start */
73         AST_BRIDGE_ACTION_TALKING_START,
74         /*! Bridged channel is to indicate talking stop */
75         AST_BRIDGE_ACTION_TALKING_STOP,
76         /*! Bridge channel is to play the indicated sound file. */
77         AST_BRIDGE_ACTION_PLAY_FILE,
78         /*! Bridge channel is to run the indicated application. */
79         AST_BRIDGE_ACTION_RUN_APP,
80         /*! Bridge channel is to run the custom callback routine. */
81         AST_BRIDGE_ACTION_CALLBACK,
82         /*! Bridge channel is to get parked. */
83         AST_BRIDGE_ACTION_PARK,
84         /*! Bridge channel is to execute a blind transfer. */
85         AST_BRIDGE_ACTION_BLIND_TRANSFER,
86         /*! Bridge channel is to execute an attended transfer */
87         AST_BRIDGE_ACTION_ATTENDED_TRANSFER,
88
89         /*
90          * Bridge actions put after this comment must never be put onto
91          * the bridge_channel wr_queue because they have other resources
92          * that must be freed.
93          */
94
95         /*! Bridge reconfiguration deferred technology destruction. */
96         AST_BRIDGE_ACTION_DEFERRED_TECH_DESTROY = 1000,
97         /*! Bridge deferred dissolving. */
98         AST_BRIDGE_ACTION_DEFERRED_DISSOLVING,
99 };
100
101 struct ast_bridge;
102 struct ast_bridge_tech_optimizations;
103
104  /*!
105  * \brief Structure that contains information regarding a channel in a bridge
106  */
107 struct ast_bridge_channel {
108 /* BUGBUG cond is only here because of external party suspend/unsuspend support. */
109         /*! Condition, used if we want to wake up a thread waiting on the bridged channel */
110         ast_cond_t cond;
111         /*! Current bridged channel state */
112         enum ast_bridge_channel_state state;
113         /*! Asterisk channel participating in the bridge */
114         struct ast_channel *chan;
115         /*! Asterisk channel we are swapping with (if swapping) */
116         struct ast_channel *swap;
117         /*!
118          * \brief Bridge this channel is participating in
119          *
120          * \note The bridge pointer cannot change while the bridge or
121          * bridge_channel is locked.
122          */
123         struct ast_bridge *bridge;
124         /*!
125          * \brief Bridge class private channel data.
126          *
127          * \note This information is added when the channel is pushed
128          * into the bridge and removed when it is pulled from the
129          * bridge.
130          */
131         void *bridge_pvt;
132         /*!
133          * \brief Private information unique to the bridge technology.
134          *
135          * \note This information is added when the channel joins the
136          * bridge's technology and removed when it leaves the bridge's
137          * technology.
138          */
139         void *tech_pvt;
140         /*! Thread handling the bridged channel (Needed by ast_bridge_depart) */
141         pthread_t thread;
142         /* v-- These flags change while the bridge is locked or before the channel is in the bridge. */
143         /*! TRUE if the channel is in a bridge. */
144         unsigned int in_bridge:1;
145         /*! TRUE if the channel just joined the bridge. */
146         unsigned int just_joined:1;
147         /*! TRUE if the channel is suspended from the bridge. */
148         unsigned int suspended:1;
149         /*! TRUE if the channel must wait for an ast_bridge_depart to reclaim the channel. */
150         unsigned int depart_wait:1;
151         /* ^-- These flags change while the bridge is locked or before the channel is in the bridge. */
152         /*! Features structure for features that are specific to this channel */
153         struct ast_bridge_features *features;
154         /*! Technology optimization parameters used by bridging technologies capable of
155          *  optimizing based upon talk detection. */
156         struct ast_bridge_tech_optimizations tech_args;
157         /*! Copy of read format used by chan before join */
158         struct ast_format read_format;
159         /*! Copy of write format used by chan before join */
160         struct ast_format write_format;
161         /*! Call ID associated with bridge channel */
162         struct ast_callid *callid;
163         /*! A clone of the roles living on chan when the bridge channel joins the bridge. This may require some opacification */
164         struct bridge_roles_datastore *bridge_roles;
165         /*! Linked list information */
166         AST_LIST_ENTRY(ast_bridge_channel) entry;
167         /*! Queue of outgoing frames to the channel. */
168         AST_LIST_HEAD_NOLOCK(, ast_frame) wr_queue;
169         /*! Pipe to alert thread when frames are put into the wr_queue. */
170         int alert_pipe[2];
171         /*! TRUE if the bridge channel thread is waiting on channels (needs to be atomically settable) */
172         int waiting;
173         /*!
174          * \brief The bridge channel thread activity.
175          *
176          * \details Used by local channel optimization to determine if
177          * the thread is in an acceptable state to optimize.
178          *
179          * \note Needs to be atomically settable.
180          */
181         enum ast_bridge_channel_thread_state activity;
182 };
183
184 /*!
185  * \brief Try locking the bridge_channel.
186  *
187  * \param bridge_channel What to try locking
188  *
189  * \retval 0 on success.
190  * \retval non-zero on error.
191  */
192 #define ast_bridge_channel_trylock(bridge_channel)      _ast_bridge_channel_trylock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
193 static inline int _ast_bridge_channel_trylock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
194 {
195         return __ao2_trylock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
196 }
197
198 /*!
199  * \brief Lock the bridge_channel.
200  *
201  * \param bridge_channel What to lock
202  *
203  * \return Nothing
204  */
205 #define ast_bridge_channel_lock(bridge_channel) _ast_bridge_channel_lock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
206 static inline void _ast_bridge_channel_lock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
207 {
208         __ao2_lock(bridge_channel, AO2_LOCK_REQ_MUTEX, file, function, line, var);
209 }
210
211 /*!
212  * \brief Unlock the bridge_channel.
213  *
214  * \param bridge_channel What to unlock
215  *
216  * \return Nothing
217  */
218 #define ast_bridge_channel_unlock(bridge_channel)       _ast_bridge_channel_unlock(bridge_channel, __FILE__, __PRETTY_FUNCTION__, __LINE__, #bridge_channel)
219 static inline void _ast_bridge_channel_unlock(struct ast_bridge_channel *bridge_channel, const char *file, const char *function, int line, const char *var)
220 {
221         __ao2_unlock(bridge_channel, file, function, line, var);
222 }
223
224 /*!
225  * \brief Lock the bridge associated with the bridge channel.
226  * \since 12.0.0
227  *
228  * \param bridge_channel Channel that wants to lock the bridge.
229  *
230  * \details
231  * This is an upstream lock operation.  The defined locking
232  * order is bridge then bridge_channel.
233  *
234  * \note On entry, neither the bridge nor bridge_channel is locked.
235  *
236  * \note The bridge_channel->bridge pointer changes because of a
237  * bridge-merge/channel-move operation between bridges.
238  *
239  * \return Nothing
240  */
241 void ast_bridge_channel_lock_bridge(struct ast_bridge_channel *bridge_channel);
242
243 /*!
244  * \brief Ask the bridged channel to leave the bridge it is currently in
245  *
246  * \param bridge_channel Channel to leave the bridge
247  */
248 void ast_bridge_channel_leave_bridge(struct ast_bridge_channel *bridge_channel);
249
250 /*!
251  * \brief Ask the bridged channel to leave the bridge it is currently in
252  *
253  * \param bridge_channel Channel to leave the bridge
254  *
255  * \note This function assumes the bridge_channel is locked.
256  */
257 void ast_bridge_channel_leave_bridge_nolock(struct ast_bridge_channel *bridge_channel);
258
259 /*!
260  * \brief Write a frame to the specified bridge_channel.
261  * \since 12.0.0
262  *
263  * \param bridge_channel Channel to queue the frame.
264  * \param fr Frame to write.
265  *
266  * \retval 0 on success.
267  * \retval -1 on error.
268  *
269  * \note This API call is meant for internal bridging operations.
270  * \note BUGBUG This may get moved.
271  */
272 int ast_bridge_channel_queue_frame(struct ast_bridge_channel *bridge_channel, struct ast_frame *fr);
273
274 /*!
275  * \brief Used to queue an action frame onto a bridge channel and write an action frame into a bridge.
276  * \since 12.0.0
277  *
278  * \param bridge_channel Which channel work with.
279  * \param action Type of bridge action frame.
280  * \param data Frame payload data to pass.
281  * \param datalen Frame payload data length to pass.
282  *
283  * \retval 0 on success.
284  * \retval -1 on error.
285  */
286 typedef int (*ast_bridge_channel_post_action_data)(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
287
288 /*!
289  * \brief Queue an action frame onto the bridge channel with data.
290  * \since 12.0.0
291  *
292  * \param bridge_channel Which channel to queue the frame onto.
293  * \param action Type of bridge action frame.
294  * \param data Frame payload data to pass.
295  * \param datalen Frame payload data length to pass.
296  *
297  * \retval 0 on success.
298  * \retval -1 on error.
299  */
300 int ast_bridge_channel_queue_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
301
302 /*!
303  * \brief Write an action frame into the bridge with data.
304  * \since 12.0.0
305  *
306  * \param bridge_channel Which channel is putting the frame into the bridge.
307  * \param action Type of bridge action frame.
308  * \param data Frame payload data to pass.
309  * \param datalen Frame payload data length to pass.
310  *
311  * \retval 0 on success.
312  * \retval -1 on error.
313  */
314 int ast_bridge_channel_write_action_data(struct ast_bridge_channel *bridge_channel, enum ast_bridge_action_type action, const void *data, size_t datalen);
315
316 /*!
317  * \brief Queue a control frame onto the bridge channel with data.
318  * \since 12.0.0
319  *
320  * \param bridge_channel Which channel to queue the frame onto.
321  * \param control Type of control frame.
322  * \param data Frame payload data to pass.
323  * \param datalen Frame payload data length to pass.
324  *
325  * \retval 0 on success.
326  * \retval -1 on error.
327  */
328 int ast_bridge_channel_queue_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
329
330 /*!
331  * \brief Write a control frame into the bridge with data.
332  * \since 12.0.0
333  *
334  * \param bridge_channel Which channel is putting the frame into the bridge.
335  * \param control Type of control frame.
336  * \param data Frame payload data to pass.
337  * \param datalen Frame payload data length to pass.
338  *
339  * \retval 0 on success.
340  * \retval -1 on error.
341  */
342 int ast_bridge_channel_write_control_data(struct ast_bridge_channel *bridge_channel, enum ast_control_frame_type control, const void *data, size_t datalen);
343
344 /*!
345  * \brief Write a hold frame into the bridge.
346  * \since 12.0.0
347  *
348  * \param bridge_channel Which channel is putting the hold into the bridge.
349  * \param moh_class The suggested music class for the other end to use.
350  *
351  * \retval 0 on success.
352  * \retval -1 on error.
353  */
354 int ast_bridge_channel_write_hold(struct ast_bridge_channel *bridge_channel, const char *moh_class);
355
356 /*!
357  * \brief Write an unhold frame into the bridge.
358  * \since 12.0.0
359  *
360  * \param bridge_channel Which channel is putting the hold into the bridge.
361  *
362  * \retval 0 on success.
363  * \retval -1 on error.
364  */
365 int ast_bridge_channel_write_unhold(struct ast_bridge_channel *bridge_channel);
366
367 /*!
368  * \brief Run an application on the bridge channel.
369  * \since 12.0.0
370  *
371  * \param bridge_channel Which channel to run the application on.
372  * \param app_name Dialplan application name.
373  * \param app_args Arguments for the application. (NULL tolerant)
374  * \param moh_class MOH class to request bridge peers to hear while application is running.
375  *     NULL if no MOH.
376  *     Empty if default MOH class.
377  *
378  * \note This is intended to be called by bridge hooks.
379  *
380  * \return Nothing
381  */
382 void ast_bridge_channel_run_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
383
384 /*!
385  * \brief Write a bridge action run application frame into the bridge.
386  * \since 12.0.0
387  *
388  * \param bridge_channel Which channel is putting the frame into the bridge
389  * \param app_name Dialplan application name.
390  * \param app_args Arguments for the application. (NULL or empty for no arguments)
391  * \param moh_class MOH class to request bridge peers to hear while application is running.
392  *     NULL if no MOH.
393  *     Empty if default MOH class.
394  *
395  * \note This is intended to be called by bridge hooks.
396  *
397  * \retval 0 on success.
398  * \retval -1 on error.
399  */
400 int ast_bridge_channel_write_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
401
402 /*!
403  * \brief Queue a bridge action run application frame onto the bridge channel.
404  * \since 12.0.0
405  *
406  * \param bridge_channel Which channel to put the frame onto
407  * \param app_name Dialplan application name.
408  * \param app_args Arguments for the application. (NULL or empty for no arguments)
409  * \param moh_class MOH class to request bridge peers to hear while application is running.
410  *     NULL if no MOH.
411  *     Empty if default MOH class.
412  *
413  * \note This is intended to be called by bridge hooks.
414  *
415  * \retval 0 on success.
416  * \retval -1 on error.
417  */
418 int ast_bridge_channel_queue_app(struct ast_bridge_channel *bridge_channel, const char *app_name, const char *app_args, const char *moh_class);
419
420 /*!
421  * \brief Custom interpretation of the playfile name.
422  *
423  * \param bridge_channel Which channel to play the file on
424  * \param playfile Sound filename to play.
425  *
426  * \return Nothing
427  */
428 typedef void (*ast_bridge_custom_play_fn)(struct ast_bridge_channel *bridge_channel, const char *playfile);
429
430 /*!
431  * \brief Play a file on the bridge channel.
432  * \since 12.0.0
433  *
434  * \param bridge_channel Which channel to play the file on
435  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
436  * \param playfile Sound filename to play.
437  * \param moh_class MOH class to request bridge peers to hear while file is played.
438  *     NULL if no MOH.
439  *     Empty if default MOH class.
440  *
441  * \note This is intended to be called by bridge hooks.
442  *
443  * \return Nothing
444  */
445 void ast_bridge_channel_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
446
447 /*!
448  * \brief Write a bridge action play file frame into the bridge.
449  * \since 12.0.0
450  *
451  * \param bridge_channel Which channel is putting the frame into the bridge
452  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
453  * \param playfile Sound filename to play.
454  * \param moh_class MOH class to request bridge peers to hear while file is played.
455  *     NULL if no MOH.
456  *     Empty if default MOH class.
457  *
458  * \note This is intended to be called by bridge hooks.
459  *
460  * \retval 0 on success.
461  * \retval -1 on error.
462  */
463 int ast_bridge_channel_write_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
464
465 /*!
466  * \brief Queue a bridge action play file frame onto the bridge channel.
467  * \since 12.0.0
468  *
469  * \param bridge_channel Which channel to put the frame onto.
470  * \param custom_play Call this function to play the playfile. (NULL if normal sound file to play)
471  * \param playfile Sound filename to play.
472  * \param moh_class MOH class to request bridge peers to hear while file is played.
473  *     NULL if no MOH.
474  *     Empty if default MOH class.
475  *
476  * \note This is intended to be called by bridge hooks.
477  *
478  * \retval 0 on success.
479  * \retval -1 on error.
480  */
481 int ast_bridge_channel_queue_playfile(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_play_fn custom_play, const char *playfile, const char *moh_class);
482
483 /*!
484  * \brief Custom callback run on a bridge channel.
485  *
486  * \param bridge_channel Which channel to operate on.
487  * \param payload Data to pass to the callback. (NULL if none).
488  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
489  *
490  * \note The payload MUST NOT have any resources that need to be freed.
491  *
492  * \return Nothing
493  */
494 typedef void (*ast_bridge_custom_callback_fn)(struct ast_bridge_channel *bridge_channel, const void *payload, size_t payload_size);
495
496 /*!
497  * \brief Write a bridge action custom callback frame into the bridge.
498  * \since 12.0.0
499  *
500  * \param bridge_channel Which channel is putting the frame into the bridge
501  * \param callback Custom callback run on a bridge channel.
502  * \param payload Data to pass to the callback. (NULL if none).
503  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
504  *
505  * \note The payload MUST NOT have any resources that need to be freed.
506  *
507  * \note This is intended to be called by bridge hooks.
508  *
509  * \retval 0 on success.
510  * \retval -1 on error.
511  */
512 int ast_bridge_channel_write_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
513
514 /*!
515  * \brief Queue a bridge action custom callback frame onto the bridge channel.
516  * \since 12.0.0
517  *
518  * \param bridge_channel Which channel to put the frame onto.
519  * \param callback Custom callback run on a bridge channel.
520  * \param payload Data to pass to the callback. (NULL if none).
521  * \param payload_size Size of the payload if payload is non-NULL.  A number otherwise.
522  *
523  * \note The payload MUST NOT have any resources that need to be freed.
524  *
525  * \note This is intended to be called by bridge hooks.
526  *
527  * \retval 0 on success.
528  * \retval -1 on error.
529  */
530 int ast_bridge_channel_queue_callback(struct ast_bridge_channel *bridge_channel, ast_bridge_custom_callback_fn callback, const void *payload, size_t payload_size);
531
532 /*!
533  * \brief Have a bridge channel park a channel in the bridge
534  * \since 12.0.0
535  *
536  * \param bridge_channel Bridge channel performing the parking
537  * \param parkee_uuid Unique id of the channel we want to park
538  * \param parker_uuid Unique id of the channel parking the call
539  * \param app_data string indicating data used for park application (NULL allowed)
540  *
541  * \note This is intended to be called by bridge hooks.
542  *
543  * \retval 0 on success.
544  * \retval -1 on error.
545  */
546 int ast_bridge_channel_write_park(struct ast_bridge_channel *bridge_channel, const char *parkee_uuid,
547         const char *parker_uuid, const char *app_data);
548
549 /*!
550  * \brief Restore the formats of a bridge channel's channel to how they were before bridge_channel_join
551  * \since 12.0.0
552  *
553  * \param bridge_channel Channel to restore
554  */
555 void ast_bridge_channel_restore_formats(struct ast_bridge_channel *bridge_channel);
556
557 /*!
558  * \brief Get the peer bridge channel of a two party bridge.
559  * \since 12.0.0
560  *
561  * \param bridge_channel What to get the peer of.
562  *
563  * \note On entry, bridge_channel->bridge is already locked.
564  *
565  * \note This is an internal bridge function.
566  *
567  * \retval peer on success.
568  * \retval NULL no peer channel.
569  */
570 struct ast_bridge_channel *ast_bridge_channel_peer(struct ast_bridge_channel *bridge_channel);
571
572 #if defined(__cplusplus) || defined(c_plusplus)
573 }
574 #endif
575
576 #endif  /* _ASTERISK_BRIDGING_CHANNEL_H */