confbridge: Add support for disabling text messaging.
[asterisk/asterisk.git] / include / asterisk / bridge_features.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@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  * \file
21  * \brief Channel Bridging API
22  * \author Joshua Colp <jcolp@digium.com>
23  */
24
25 #ifndef _ASTERISK_BRIDGING_FEATURES_H
26 #define _ASTERISK_BRIDGING_FEATURES_H
27
28 #include "asterisk/channel.h"
29
30 #if defined(__cplusplus) || defined(c_plusplus)
31 extern "C" {
32 #endif
33
34 /*! \brief Flags used for bridge features */
35 enum ast_bridge_feature_flags {
36         /*! Upon channel hangup all bridge participants should be kicked out. */
37         AST_BRIDGE_FLAG_DISSOLVE_HANGUP = (1 << 0),
38         /*! The last channel to leave the bridge dissolves it. */
39         AST_BRIDGE_FLAG_DISSOLVE_EMPTY = (1 << 1),
40         /*! Move between bridging technologies as needed. */
41         AST_BRIDGE_FLAG_SMART = (1 << 2),
42         /*! Bridge channels cannot be merged from this bridge. */
43         AST_BRIDGE_FLAG_MERGE_INHIBIT_FROM = (1 << 3),
44         /*! Bridge channels cannot be merged to this bridge. */
45         AST_BRIDGE_FLAG_MERGE_INHIBIT_TO = (1 << 4),
46         /*! Bridge channels cannot be local channel swap optimized from this bridge. */
47         AST_BRIDGE_FLAG_SWAP_INHIBIT_FROM = (1 << 5),
48         /*! Bridge channels cannot be local channel swap optimized to this bridge. */
49         AST_BRIDGE_FLAG_SWAP_INHIBIT_TO = (1 << 6),
50         /*! Bridge channels can be moved to another bridge only by masquerade (ConfBridge) */
51         AST_BRIDGE_FLAG_MASQUERADE_ONLY = (1 << 7),
52         /*! Bridge does not allow transfers of channels out */
53         AST_BRIDGE_FLAG_TRANSFER_PROHIBITED = (1 << 8),
54         /*! Bridge transfers require transfer of entire bridge rather than individual channels */
55         AST_BRIDGE_FLAG_TRANSFER_BRIDGE_ONLY = (1 << 9),
56         /*! Bridge is invisible to AMI/CLI/ARI/etc. */
57         AST_BRIDGE_FLAG_INVISIBLE = (1 << 10),
58 };
59
60 /*! \brief Flags used for per bridge channel features */
61 enum ast_bridge_channel_feature_flags {
62         /*! Upon channel hangup all bridge participants should be kicked out. */
63         AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP = (1 << 0),
64         /*! This channel leaves the bridge if all participants have this flag set. */
65         AST_BRIDGE_CHANNEL_FLAG_LONELY = (1 << 1),
66         /*! This channel cannot be moved to another bridge. */
67         AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE = (1 << 2),
68 };
69
70 /*! \brief Built in DTMF features */
71 enum ast_bridge_builtin_feature {
72         /*! DTMF based Blind Transfer */
73         AST_BRIDGE_BUILTIN_BLINDTRANSFER,
74         /*! DTMF based Attended Transfer */
75         AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
76         /*!
77          * DTMF based depart bridge feature
78          *
79          * \note Imparted channels are optionally hangup depending upon
80          * how it was imparted.
81          *
82          * \note Joined channels exit the bridge with
83          * BRIDGE_CHANNEL_STATE_END_WITH_DISSOLVE.
84          */
85         AST_BRIDGE_BUILTIN_HANGUP,
86         /*!
87          * DTMF based Park
88          *
89          * \details The bridge is parked and the channel hears the
90          * parking slot to which it was parked.
91          */
92         AST_BRIDGE_BUILTIN_PARKCALL,
93         /*!
94          * DTMF one-touch-record toggle using Monitor app.
95          *
96          * \note Only valid on two party bridges.
97          */
98         AST_BRIDGE_BUILTIN_AUTOMON,
99         /*!
100          * DTMF one-touch-record toggle using MixMonitor app.
101          *
102          * \note Only valid on two party bridges.
103          */
104         AST_BRIDGE_BUILTIN_AUTOMIXMON,
105
106         /*! End terminator for list of built in features. Must remain last. */
107         AST_BRIDGE_BUILTIN_END
108 };
109
110 enum ast_bridge_builtin_interval {
111         /*! Apply Call Duration Limits */
112         AST_BRIDGE_BUILTIN_INTERVAL_LIMITS,
113
114         /*! End terminator for list of built in interval features. Must remain last. */
115         AST_BRIDGE_BUILTIN_INTERVAL_END
116 };
117
118 struct ast_bridge;
119 struct ast_bridge_channel;
120
121 /*!
122  * \brief Hook callback type
123  *
124  * \param bridge_channel Channel executing the feature
125  * \param hook_pvt Private data passed in when the hook was created
126  *
127  * For interval hooks:
128  * \retval 0 Setup to fire again at the last interval.
129  * \retval positive Setup to fire again at the new interval returned.
130  * \retval -1 Remove the callback hook.
131  *
132  * For other hooks:
133  * \retval 0 Keep the callback hook.
134  * \retval -1 Remove the callback hook.
135  */
136 typedef int (*ast_bridge_hook_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt);
137
138 /*!
139  * \brief Hook pvt destructor callback
140  *
141  * \param hook_pvt Private data passed in when the hook was created to destroy
142  */
143 typedef void (*ast_bridge_hook_pvt_destructor)(void *hook_pvt);
144
145 /*!
146  * \brief Talking indicator callback
147  *
148  * \details
149  * This callback can be registered with the bridge channel in
150  * order to receive updates when the bridge_channel has started
151  * and stopped talking.
152  *
153  * \param bridge_channel Channel executing the feature
154  * \param hook_pvt Private data passed in when the hook was created
155  * \param talking TRUE if the channel is now talking
156  *
157  * \retval 0 Keep the callback hook.
158  * \retval -1 Remove the callback hook.
159  */
160 typedef int (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt, int talking);
161
162 /*!
163  * \brief Move indicator callback
164  *
165  * \details
166  * This callback can be registered with the bridge channel in order
167  * to be notified when the bridge channel is being moved from one
168  * bridge to another.
169  *
170  * \param bridge_channel The channel executing the feature
171  * \param hook_pvt Private data passed in when the hook was created
172  * \param src The bridge from which the bridge channel is moving
173  * \param dst The bridge into which the bridge channel is moving
174  *
175  * \retval 0 Keep the callback hook.
176  * \retval -1 Remove the callback hook.
177  */
178 typedef int (*ast_bridge_move_indicate_callback)(struct ast_bridge_channel *bridge_channel,
179                 void *hook_pvt, struct ast_bridge *src, struct ast_bridge *dst);
180
181 enum ast_bridge_hook_remove_flags {
182         /*! The hook is removed when the channel is pulled from the bridge. */
183         AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0),
184         /*! The hook is removed when the bridge's personality changes. */
185         AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE = (1 << 1),
186 };
187
188 enum ast_bridge_hook_type {
189         /*! The hook type has not been specified. */
190         AST_BRIDGE_HOOK_TYPE_NONE,
191         AST_BRIDGE_HOOK_TYPE_DTMF,
192         AST_BRIDGE_HOOK_TYPE_TIMER,
193         AST_BRIDGE_HOOK_TYPE_HANGUP,
194         AST_BRIDGE_HOOK_TYPE_JOIN,
195         AST_BRIDGE_HOOK_TYPE_LEAVE,
196         AST_BRIDGE_HOOK_TYPE_TALK,
197         AST_BRIDGE_HOOK_TYPE_MOVE,
198 };
199
200 /*! \brief Structure that is the essence of a feature hook. */
201 struct ast_bridge_hook {
202         /*! Callback that is called when hook is tripped */
203         ast_bridge_hook_callback callback;
204         /*! Callback to destroy hook_pvt data right before destruction. */
205         ast_bridge_hook_pvt_destructor destructor;
206         /*! Unique data that was passed into us */
207         void *hook_pvt;
208         /*! Flags determining when hooks should be removed from a bridge channel */
209         struct ast_flags remove_flags;
210         /*! What kind of hook this is. */
211         enum ast_bridge_hook_type type;
212 };
213
214 /*!
215  * \brief Maximum length of a DTMF feature string
216  */
217 #define MAXIMUM_DTMF_FEATURE_STRING (11 + 1)
218
219 /*! Extra parameters for a DTMF feature hook. */
220 struct ast_bridge_hook_dtmf_parms {
221         /*! DTMF String that is examined during a feature hook lookup */
222         char code[MAXIMUM_DTMF_FEATURE_STRING];
223 };
224
225 /*! DTMF specific hook. */
226 struct ast_bridge_hook_dtmf {
227         /*! Generic feature hook information. */
228         struct ast_bridge_hook generic;
229         /*! Extra parameters for a DTMF feature hook. */
230         struct ast_bridge_hook_dtmf_parms dtmf;
231 };
232
233 enum ast_bridge_hook_timer_option {
234         /*! The timer temporarily affects media. (Like a custom playfile.) */
235         AST_BRIDGE_HOOK_TIMER_OPTION_MEDIA = (1 << 0),
236 };
237
238 /*! Extra parameters for an interval timer hook. */
239 struct ast_bridge_hook_timer_parms {
240         /*! Time at which the hook should actually trip */
241         struct timeval trip_time;
242         /*! Heap index for interval hook */
243         ssize_t heap_index;
244         /*! Interval that the hook should execute at in milliseconds */
245         unsigned int interval;
246         /*! Sequence number for the hook to ensure expiration ordering */
247         unsigned int seqno;
248         /*! Option flags determining how callback is called. */
249         unsigned int flags;
250 };
251
252 /*! Timer specific hook. */
253 struct ast_bridge_hook_timer {
254         /*! Generic feature hook information. */
255         struct ast_bridge_hook generic;
256         /*! Extra parameters for an interval timer hook. */
257         struct ast_bridge_hook_timer_parms timer;
258 };
259
260 /*!
261  * \brief Structure that contains features information
262  */
263 struct ast_bridge_features {
264         /*! Attached DTMF feature hooks */
265         struct ao2_container *dtmf_hooks;
266         /*! Attached miscellaneous other hooks. */
267         struct ao2_container *other_hooks;
268         /*! Attached interval hooks */
269         struct ast_heap *interval_hooks;
270         /*! Feature flags that are enabled */
271         struct ast_flags feature_flags;
272         /*! Used to assign the sequence number to the next interval hook added. */
273         unsigned int interval_sequence;
274         /*! TRUE if feature_flags is setup */
275         unsigned int usable:1;
276         /*! TRUE if the channel/bridge is muted. */
277         unsigned int mute:1;
278         /*! TRUE if DTMF should be passed into the bridge tech.  */
279         unsigned int dtmf_passthrough:1;
280         /*! TRUE to avoid generating COLP frames when joining the bridge */
281         unsigned int inhibit_colp:1;
282         /*! TRUE if text messaging is permitted. */
283         unsigned int text_messaging:1;
284 };
285
286 /*!
287  * \brief Structure that contains configuration information for the blind transfer built in feature
288  */
289 struct ast_bridge_features_blind_transfer {
290         /*! Context to use for transfers (If not empty.) */
291         char context[AST_MAX_CONTEXT];
292 };
293
294 /*!
295  * \brief Structure that contains configuration information for the attended transfer built in feature
296  */
297 struct ast_bridge_features_attended_transfer {
298         /*! Context to use for transfers (If not empty.) */
299         char context[AST_MAX_CONTEXT];
300         /*! DTMF string used to abort the transfer (If not empty.) */
301         char abort[MAXIMUM_DTMF_FEATURE_STRING];
302         /*! DTMF string used to turn the transfer into a three way conference (If not empty.) */
303         char threeway[MAXIMUM_DTMF_FEATURE_STRING];
304         /*! DTMF string used to complete the transfer (If not empty.) */
305         char complete[MAXIMUM_DTMF_FEATURE_STRING];
306         /*! DTMF string used to swap bridged targets (If not empty.) */
307         char swap[MAXIMUM_DTMF_FEATURE_STRING];
308 };
309
310 enum ast_bridge_features_monitor {
311         /*! Toggle start/stop of Monitor/MixMonitor. */
312         AUTO_MONITOR_TOGGLE,
313         /*! Start Monitor/MixMonitor if not already started. */
314         AUTO_MONITOR_START,
315         /*! Stop Monitor/MixMonitor if not already stopped. */
316         AUTO_MONITOR_STOP,
317 };
318
319 struct ast_bridge_features_automonitor {
320         /*! Start/Stop behavior. */
321         enum ast_bridge_features_monitor start_stop;
322 };
323
324 struct ast_bridge_features_automixmonitor {
325         /*! Start/Stop behavior. */
326         enum ast_bridge_features_monitor start_stop;
327 };
328
329 /*!
330  * \brief Structure that contains configuration information for the limits feature
331  */
332 struct ast_bridge_features_limits {
333         AST_DECLARE_STRING_FIELDS(
334                 /*! Sound file to play when the maximum duration is reached (if empty, then nothing will be played) */
335                 AST_STRING_FIELD(duration_sound);
336                 /*! Sound file to play when the warning time is reached (if empty, then the remaining time will be played) */
337                 AST_STRING_FIELD(warning_sound);
338                 /*! Sound file to play when the call is first entered (if empty, then the remaining time will be played) */
339                 AST_STRING_FIELD(connect_sound);
340         );
341         /*! Time when the bridge will be terminated by the limits feature */
342         struct timeval quitting_time;
343         /*! Maximum duration that the channel is allowed to be in the bridge (specified in milliseconds) */
344         unsigned int duration;
345         /*! Duration into the call when warnings should begin (specified in milliseconds or 0 to disable) */
346         unsigned int warning;
347         /*! Interval between the warnings (specified in milliseconds or 0 to disable) */
348         unsigned int frequency;
349 };
350
351 /*!
352  * \brief Register a handler for a built in feature
353  *
354  * \param feature The feature that the handler will be responsible for
355  * \param callback The callback function that will handle it
356  * \param dtmf Default DTMF string used to activate the feature
357  *
358  * \retval 0 on success
359  * \retval -1 on failure
360  *
361  * Example usage:
362  *
363  * \code
364  * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
365  * \endcode
366  *
367  * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
368  * attended transfer feature.
369  */
370 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_hook_callback callback, const char *dtmf);
371
372 /*!
373  * \brief Unregister a handler for a built in feature
374  *
375  * \param feature The feature to unregister
376  *
377  * \retval 0 on success
378  * \retval -1 on failure
379  *
380  * Example usage:
381  *
382  * \code
383  * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
384  * \endcode
385  *
386  * This unregisters the function that is handling the built in attended transfer feature.
387  */
388 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
389
390 /*!
391  * \brief Invoke a built in feature hook now.
392  *
393  * \param feature The feature to invoke
394  * \param bridge_channel Channel executing the feature
395  * \param hook_pvt Private data passed in when the hook was created
396  *
397  * \note This API call is only meant to be used by bridge
398  * subclasses and hook callbacks to request a builtin feature
399  * hook to be executed.
400  *
401  * \retval 0 on success
402  * \retval -1 on failure
403  *
404  * Example usage:
405  *
406  * \code
407  * ast_bridge_features_do(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_channel, hook_pvt);
408  * \endcode
409  */
410 int ast_bridge_features_do(enum ast_bridge_builtin_feature feature, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
411
412 /*!
413  * \brief Attach interval hooks to a bridge features structure
414  *
415  * \param features Bridge features structure
416  * \param limits Configured limits applicable to the channel
417  * \param remove_flags Dictates what situations the hook should be removed.
418  *
419  * \retval 0 on success
420  * \retval -1 on failure
421  */
422 typedef int (*ast_bridge_builtin_set_limits_fn)(struct ast_bridge_features *features,
423                 struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);
424
425 /*!
426  * \brief Register a handler for a built in interval feature
427  *
428  * \param interval The interval feature that the handler will be responsible for
429  * \param callback the Callback function that will handle it
430  *
431  * \retval 0 on success
432  * \retval -1 on failure
433  *
434  * Example usage:
435  *
436  * \code
437  * ast_bridge_interval_register(AST_BRIDGE_BUILTIN_INTERVAL_LIMITS, bridge_builtin_set_limits);
438  * \endcode
439  *
440  * This registers the function bridge_builtin_set_limits as the function responsible for the built in
441  * duration limit feature.
442  */
443 int ast_bridge_interval_register(enum ast_bridge_builtin_interval interval, ast_bridge_builtin_set_limits_fn callback);
444
445 /*!
446  * \brief Unregisters a handler for a built in interval feature
447  *
448  * \param interval the interval feature to unregister
449  *
450  * \retval 0 on success
451  * \retval -1 on failure
452  *
453  * Example usage:
454  *
455  * \code
456  * ast_bridge_interval_unregister(AST_BRIDGE_BULTIN_INTERVAL_LIMITS)
457  * /endcode
458  *
459  * This unregisters the function that is handling the built in duration limit feature.
460  */
461 int ast_bridge_interval_unregister(enum ast_bridge_builtin_interval interval);
462
463 /*!
464  * \brief Attach a bridge channel join hook to a bridge features structure
465  *
466  * \param features Bridge features structure
467  * \param callback Function to execute upon activation
468  * \param hook_pvt Unique data
469  * \param destructor Optional destructor callback for hook_pvt data
470  * \param remove_flags Dictates what situations the hook should be removed.
471  *
472  * \retval 0 on success
473  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
474  *
475  * Example usage:
476  *
477  * \code
478  * struct ast_bridge_features features;
479  * ast_bridge_features_init(&features);
480  * ast_bridge_join_hook(&features, join_callback, NULL, NULL, 0);
481  * \endcode
482  *
483  * This makes the bridging core call join_callback when a
484  * channel successfully joins the bridging system.  A pointer to
485  * useful data may be provided to the hook_pvt parameter.
486  */
487 int ast_bridge_join_hook(struct ast_bridge_features *features,
488         ast_bridge_hook_callback callback,
489         void *hook_pvt,
490         ast_bridge_hook_pvt_destructor destructor,
491         enum ast_bridge_hook_remove_flags remove_flags);
492
493 /*!
494  * \brief Attach a bridge channel leave hook to a bridge features structure
495  *
496  * \param features Bridge features structure
497  * \param callback Function to execute upon activation
498  * \param hook_pvt Unique data
499  * \param destructor Optional destructor callback for hook_pvt data
500  * \param remove_flags Dictates what situations the hook should be removed.
501  *
502  * \retval 0 on success
503  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
504  *
505  * Example usage:
506  *
507  * \code
508  * struct ast_bridge_features features;
509  * ast_bridge_features_init(&features);
510  * ast_bridge_leave_hook(&features, leave_callback, NULL, NULL, 0);
511  * \endcode
512  *
513  * This makes the bridging core call leave_callback when a
514  * channel successfully leaves the bridging system.  A pointer
515  * to useful data may be provided to the hook_pvt parameter.
516  */
517 int ast_bridge_leave_hook(struct ast_bridge_features *features,
518         ast_bridge_hook_callback callback,
519         void *hook_pvt,
520         ast_bridge_hook_pvt_destructor destructor,
521         enum ast_bridge_hook_remove_flags remove_flags);
522
523 /*!
524  * \brief Attach a hangup hook to a bridge features structure
525  *
526  * \param features Bridge features structure
527  * \param callback Function to execute upon activation
528  * \param hook_pvt Unique data
529  * \param destructor Optional destructor callback for hook_pvt data
530  * \param remove_flags Dictates what situations the hook should be removed.
531  *
532  * \retval 0 on success
533  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
534  *
535  * Example usage:
536  *
537  * \code
538  * struct ast_bridge_features features;
539  * ast_bridge_features_init(&features);
540  * ast_bridge_hangup_hook(&features, hangup_callback, NULL, NULL, 0);
541  * \endcode
542  *
543  * This makes the bridging core call hangup_callback if a
544  * channel that has this hook hangs up.  A pointer to useful
545  * data may be provided to the hook_pvt parameter.
546  */
547 int ast_bridge_hangup_hook(struct ast_bridge_features *features,
548         ast_bridge_hook_callback callback,
549         void *hook_pvt,
550         ast_bridge_hook_pvt_destructor destructor,
551         enum ast_bridge_hook_remove_flags remove_flags);
552
553 /*!
554  * \brief Attach a DTMF hook to a bridge features structure
555  *
556  * \param features Bridge features structure
557  * \param dtmf DTMF string to be activated upon
558  * \param callback Function to execute upon activation
559  * \param hook_pvt Unique data
560  * \param destructor Optional destructor callback for hook_pvt data
561  * \param remove_flags Dictates what situations the hook should be removed.
562  *
563  * \retval 0 on success
564  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
565  *
566  * Example usage:
567  *
568  * \code
569  * struct ast_bridge_features features;
570  * ast_bridge_features_init(&features);
571  * ast_bridge_dtmf_hook(&features, "#", pound_callback, NULL, NULL, 0);
572  * \endcode
573  *
574  * This makes the bridging core call pound_callback if a channel that has this
575  * feature structure inputs the DTMF string '#'. A pointer to useful data may be
576  * provided to the hook_pvt parameter.
577  */
578 int ast_bridge_dtmf_hook(struct ast_bridge_features *features,
579         const char *dtmf,
580         ast_bridge_hook_callback callback,
581         void *hook_pvt,
582         ast_bridge_hook_pvt_destructor destructor,
583         enum ast_bridge_hook_remove_flags remove_flags);
584
585 /*!
586  * \brief Attach an interval hook to a bridge features structure
587  *
588  * \param features Bridge features structure
589  * \param flags Interval timer callback option flags.
590  * \param interval The interval that the hook should execute at in milliseconds
591  * \param callback Function to execute upon activation
592  * \param hook_pvt Unique data
593  * \param destructor Optional destructor callback for hook_pvt data
594  * \param remove_flags Dictates what situations the hook should be removed.
595  *
596  * \retval 0 on success
597  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
598  *
599  * \code
600  * struct ast_bridge_features features;
601  * ast_bridge_features_init(&features);
602  * ast_bridge_interval_hook(&features, 1000, playback_callback, NULL, NULL, 0);
603  * \endcode
604  *
605  * This makes the bridging core call playback_callback every second. A pointer to useful
606  * data may be provided to the hook_pvt parameter.
607  */
608 int ast_bridge_interval_hook(struct ast_bridge_features *features,
609         enum ast_bridge_hook_timer_option flags,
610         unsigned int interval,
611         ast_bridge_hook_callback callback,
612         void *hook_pvt,
613         ast_bridge_hook_pvt_destructor destructor,
614         enum ast_bridge_hook_remove_flags remove_flags);
615
616 /*!
617  * \brief Attach a bridge channel talk detection hook to a bridge features structure
618  *
619  * \param features Bridge features structure
620  * \param callback Function to execute upon activation
621  * \param hook_pvt Unique data
622  * \param destructor Optional destructor callback for hook_pvt data
623  * \param remove_flags Dictates what situations the hook should be removed.
624  *
625  * \retval 0 on success
626  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
627  *
628  * Example usage:
629  *
630  * \code
631  * struct ast_bridge_features features;
632  * ast_bridge_features_init(&features);
633  * ast_bridge_talk_hook(&features, talk_callback, NULL, NULL, 0);
634  * \endcode
635  *
636  * This makes the bridging technology call talk_callback when a
637  * channel is recognized as starting and stopping talking.  A
638  * pointer to useful data may be provided to the hook_pvt
639  * parameter.
640  *
641  * \note This hook is currently only supported by softmix.
642  */
643 int ast_bridge_talk_detector_hook(struct ast_bridge_features *features,
644         ast_bridge_talking_indicate_callback callback,
645         void *hook_pvt,
646         ast_bridge_hook_pvt_destructor destructor,
647         enum ast_bridge_hook_remove_flags remove_flags);
648
649 /*!
650  * \brief Attach a bridge channel move detection hook to a bridge features structure
651  *
652  * \param features Bridge features structure
653  * \param callback Function to execute upon activation
654  * \param hook_pvt Unique data
655  * \param destructor Optional destructor callback for hook_pvt data
656  * \param remove_flags Dictates what situations the hook should be removed.
657  *
658  * \retval 0 on success
659  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
660  *
661  * Example usage:
662  *
663  * \code
664  * struct ast_bridge_features features;
665  * ast_bridge_features_init(&features);
666  * ast_bridge_move_hook(&features, move_callback, NULL, NULL, 0);
667  * \endcode
668  *
669  * This makes the bridging core call \ref callback when a
670  * channel is moved from one bridge to another.  A
671  * pointer to useful data may be provided to the hook_pvt
672  * parameter.
673  */
674 int ast_bridge_move_hook(struct ast_bridge_features *features,
675         ast_bridge_move_indicate_callback callback,
676         void *hook_pvt,
677         ast_bridge_hook_pvt_destructor destructor,
678         enum ast_bridge_hook_remove_flags remove_flags);
679
680 /*!
681  * \brief Enable a built in feature on a bridge features structure
682  *
683  * \param features Bridge features structure
684  * \param feature Feature to enable
685  * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
686  * \param config Configuration structure unique to the built in type
687  * \param destructor Optional destructor callback for config data
688  * \param remove_flags Dictates what situations the hook should be removed.
689  *
690  * \retval 0 on success
691  * \retval -1 on failure
692  *
693  * Example usage:
694  *
695  * \code
696  * struct ast_bridge_features features;
697  * ast_bridge_features_init(&features);
698  * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL, NULL, 0);
699  * \endcode
700  *
701  * This enables the attended transfer DTMF option using the default DTMF string. An alternate
702  * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
703  * to a built in feature callback function.
704  */
705 int ast_bridge_features_enable(struct ast_bridge_features *features,
706         enum ast_bridge_builtin_feature feature,
707         const char *dtmf,
708         void *config,
709         ast_bridge_hook_pvt_destructor destructor,
710         enum ast_bridge_hook_remove_flags remove_flags);
711
712 /*!
713  * \brief Constructor function for ast_bridge_features_limits
714  *
715  * \param limits pointer to a ast_bridge_features_limits struct that has been allocted, but not initialized
716  *
717  * \retval 0 on success
718  * \retval -1 on failure
719  */
720 int ast_bridge_features_limits_construct(struct ast_bridge_features_limits *limits);
721
722 /*!
723  * \brief Destructor function for ast_bridge_features_limits
724  *
725  * \param limits pointer to an ast_bridge_features_limits struct that needs to be destroyed
726  *
727  * This function does not free memory allocated to the ast_bridge_features_limits struct, it only frees elements within the struct.
728  * You must still call ast_free on the struct if you allocated it with malloc.
729  */
730 void ast_bridge_features_limits_destroy(struct ast_bridge_features_limits *limits);
731
732 /*!
733  * \brief Limit the amount of time a channel may stay in the bridge and optionally play warning messages as time runs out
734  *
735  * \param features Bridge features structure
736  * \param limits Configured limits applicable to the channel
737  * \param remove_flags Dictates what situations the hook should be removed.
738  *
739  * \retval 0 on success
740  * \retval -1 on failure
741  *
742  * Example usage:
743  *
744  * \code
745  * struct ast_bridge_features features;
746  * struct ast_bridge_features_limits limits;
747  * ast_bridge_features_init(&features);
748  * ast_bridge_features_limits_construct(&limits);
749  * ast_bridge_features_set_limits(&features, &limits, 0);
750  * ast_bridge_features_limits_destroy(&limits);
751  * \endcode
752  *
753  * This sets the maximum time the channel can be in the bridge to 10 seconds and does not play any warnings.
754  *
755  * \note This API call can only be used on a features structure that will be used in association with a bridge channel.
756  * \note The ast_bridge_features_limits structure must remain accessible for the lifetime of the features structure.
757  */
758 int ast_bridge_features_set_limits(struct ast_bridge_features *features, struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);
759
760 /*!
761  * \brief Set a flag on a bridge channel features structure
762  *
763  * \param features Bridge channel features structure
764  * \param flag Flag to enable
765  *
766  * \return Nothing
767  *
768  * Example usage:
769  *
770  * \code
771  * struct ast_bridge_features features;
772  * ast_bridge_features_init(&features);
773  * ast_bridge_features_set_flag(&features, AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP);
774  * \endcode
775  *
776  * This sets the AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP feature
777  * to be enabled on the features structure 'features'.
778  */
779 void ast_bridge_features_set_flag(struct ast_bridge_features *features, unsigned int flag);
780
781 /*!
782  * \brief Merge one ast_bridge_features into another
783  *
784  * \param into The ast_bridge_features that will be merged into
785  * \param from The ast_bridge_features that will be merged from
786  */
787 void ast_bridge_features_merge(struct ast_bridge_features *into, const struct ast_bridge_features *from);
788
789 /*!
790  * \brief Initialize bridge features structure
791  *
792  * \param features Bridge featues structure
793  *
794  * \retval 0 on success
795  * \retval -1 on failure
796  *
797  * Example usage:
798  *
799  * \code
800  * struct ast_bridge_features features;
801  * ast_bridge_features_init(&features);
802  * \endcode
803  *
804  * This initializes the feature structure 'features' to have nothing enabled.
805  *
806  * \note This MUST be called before enabling features or flags. Failure to do so
807  *       may result in a crash.
808  */
809 int ast_bridge_features_init(struct ast_bridge_features *features);
810
811 /*!
812  * \brief Clean up the contents of a bridge features structure
813  *
814  * \param features Bridge features structure
815  *
816  * \return Nothing
817  *
818  * Example usage:
819  *
820  * \code
821  * struct ast_bridge_features features;
822  * ast_bridge_features_init(&features);
823  * ast_bridge_features_cleanup(&features);
824  * \endcode
825  *
826  * This cleans up the feature structure 'features'.
827  *
828  * \note This MUST be called after the features structure is done being used
829  *       or a memory leak may occur.
830  */
831 void ast_bridge_features_cleanup(struct ast_bridge_features *features);
832
833 /*!
834  * \brief Allocate a new bridge features struct.
835  * \since 12.0.0
836  *
837  * Example usage:
838  *
839  * \code
840  * struct ast_bridge_features *features;
841  * features = ast_bridge_features_new();
842  * ast_bridge_features_destroy(features);
843  * \endcode
844  *
845  * \retval features New allocated features struct.
846  * \retval NULL on error.
847  */
848 struct ast_bridge_features *ast_bridge_features_new(void);
849
850 /*!
851  * \brief Destroy an allocated bridge features struct.
852  * \since 12.0.0
853  *
854  * \param features Bridge features structure
855  *
856  * Example usage:
857  *
858  * \code
859  * struct ast_bridge_features *features;
860  * features = ast_bridge_features_new();
861  * ast_bridge_features_destroy(features);
862  * \endcode
863  *
864  * \return Nothing
865  */
866 void ast_bridge_features_destroy(struct ast_bridge_features *features);
867
868 #if defined(__cplusplus) || defined(c_plusplus)
869 }
870 #endif
871
872 #endif /* _ASTERISK_BRIDGING_FEATURES_H */