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