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