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