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