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