bridge_features.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2009, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \brief Channel Bridging API
00022  * \author Joshua Colp <jcolp@digium.com>
00023  */
00024 
00025 #ifndef _ASTERISK_BRIDGING_FEATURES_H
00026 #define _ASTERISK_BRIDGING_FEATURES_H
00027 
00028 #include "asterisk/channel.h"
00029 
00030 #if defined(__cplusplus) || defined(c_plusplus)
00031 extern "C" {
00032 #endif
00033 
00034 /*! \brief Flags used for bridge features */
00035 enum ast_bridge_feature_flags {
00036    /*! Upon channel hangup all bridge participants should be kicked out. */
00037    AST_BRIDGE_FLAG_DISSOLVE_HANGUP = (1 << 0),
00038    /*! The last channel to leave the bridge dissolves it. */
00039    AST_BRIDGE_FLAG_DISSOLVE_EMPTY = (1 << 1),
00040    /*! Move between bridging technologies as needed. */
00041    AST_BRIDGE_FLAG_SMART = (1 << 2),
00042    /*! Bridge channels cannot be merged from this bridge. */
00043    AST_BRIDGE_FLAG_MERGE_INHIBIT_FROM = (1 << 3),
00044    /*! Bridge channels cannot be merged to this bridge. */
00045    AST_BRIDGE_FLAG_MERGE_INHIBIT_TO = (1 << 4),
00046    /*! Bridge channels cannot be local channel swap optimized from this bridge. */
00047    AST_BRIDGE_FLAG_SWAP_INHIBIT_FROM = (1 << 5),
00048    /*! Bridge channels cannot be local channel swap optimized to this bridge. */
00049    AST_BRIDGE_FLAG_SWAP_INHIBIT_TO = (1 << 6),
00050    /*! Bridge channels can be moved to another bridge only by masquerade (ConfBridge) */
00051    AST_BRIDGE_FLAG_MASQUERADE_ONLY = (1 << 7),
00052    /*! Bridge does not allow transfers of channels out */
00053    AST_BRIDGE_FLAG_TRANSFER_PROHIBITED = (1 << 8),
00054    /*! Bridge transfers require transfer of entire bridge rather than individual channels */
00055    AST_BRIDGE_FLAG_TRANSFER_BRIDGE_ONLY = (1 << 9),
00056 };
00057 
00058 /*! \brief Flags used for per bridge channel features */
00059 enum ast_bridge_channel_feature_flags {
00060    /*! Upon channel hangup all bridge participants should be kicked out. */
00061    AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP = (1 << 0),
00062    /*! This channel leaves the bridge if all participants have this flag set. */
00063    AST_BRIDGE_CHANNEL_FLAG_LONELY = (1 << 1),
00064    /*! This channel cannot be moved to another bridge. */
00065    AST_BRIDGE_CHANNEL_FLAG_IMMOVABLE = (1 << 2),
00066 };
00067 
00068 /*! \brief Built in DTMF features */
00069 enum ast_bridge_builtin_feature {
00070    /*! DTMF based Blind Transfer */
00071    AST_BRIDGE_BUILTIN_BLINDTRANSFER,
00072    /*! DTMF based Attended Transfer */
00073    AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
00074    /*!
00075     * DTMF based depart bridge feature
00076     *
00077     * \note Imparted channels are optionally hangup depending upon
00078     * how it was imparted.
00079     *
00080     * \note Joined channels exit the bridge with
00081     * BRIDGE_CHANNEL_STATE_END_WITH_DISSOLVE.
00082     */
00083    AST_BRIDGE_BUILTIN_HANGUP,
00084    /*!
00085     * DTMF based Park
00086     *
00087     * \details The bridge is parked and the channel hears the
00088     * parking slot to which it was parked.
00089     */
00090    AST_BRIDGE_BUILTIN_PARKCALL,
00091    /*!
00092     * DTMF one-touch-record toggle using Monitor app.
00093     *
00094     * \note Only valid on two party bridges.
00095     */
00096    AST_BRIDGE_BUILTIN_AUTOMON,
00097    /*!
00098     * DTMF one-touch-record toggle using MixMonitor app.
00099     *
00100     * \note Only valid on two party bridges.
00101     */
00102    AST_BRIDGE_BUILTIN_AUTOMIXMON,
00103 
00104    /*! End terminator for list of built in features. Must remain last. */
00105    AST_BRIDGE_BUILTIN_END
00106 };
00107 
00108 enum ast_bridge_builtin_interval {
00109    /*! Apply Call Duration Limits */
00110    AST_BRIDGE_BUILTIN_INTERVAL_LIMITS,
00111 
00112    /*! End terminator for list of built in interval features. Must remain last. */
00113    AST_BRIDGE_BUILTIN_INTERVAL_END
00114 };
00115 
00116 struct ast_bridge;
00117 struct ast_bridge_channel;
00118 
00119 /*!
00120  * \brief Hook callback type
00121  *
00122  * \param bridge_channel Channel executing the feature
00123  * \param hook_pvt Private data passed in when the hook was created
00124  *
00125  * For interval hooks:
00126  * \retval 0 Setup to fire again at the last interval.
00127  * \retval positive Setup to fire again at the new interval returned.
00128  * \retval -1 Remove the callback hook.
00129  *
00130  * For other hooks:
00131  * \retval 0 Keep the callback hook.
00132  * \retval -1 Remove the callback hook.
00133  */
00134 typedef int (*ast_bridge_hook_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt);
00135 
00136 /*!
00137  * \brief Hook pvt destructor callback
00138  *
00139  * \param hook_pvt Private data passed in when the hook was created to destroy
00140  */
00141 typedef void (*ast_bridge_hook_pvt_destructor)(void *hook_pvt);
00142 
00143 /*!
00144  * \brief Talking indicator callback
00145  *
00146  * \details
00147  * This callback can be registered with the bridge channel in
00148  * order to receive updates when the bridge_channel has started
00149  * and stopped talking.
00150  *
00151  * \param bridge_channel Channel executing the feature
00152  * \param hook_pvt Private data passed in when the hook was created
00153  * \param talking TRUE if the channel is now talking
00154  *
00155  * \retval 0 Keep the callback hook.
00156  * \retval -1 Remove the callback hook.
00157  */
00158 typedef int (*ast_bridge_talking_indicate_callback)(struct ast_bridge_channel *bridge_channel, void *hook_pvt, int talking);
00159 
00160 /*!
00161  * \brief Move indicator callback
00162  *
00163  * \details
00164  * This callback can be registered with the bridge channel in order
00165  * to be notified when the bridge channel is being moved from one
00166  * bridge to another.
00167  *
00168  * \param bridge_channel The channel executing the feature
00169  * \param hook_pvt Private data passed in when the hook was created
00170  * \param src The bridge from which the bridge channel is moving
00171  * \param dst The bridge into which the bridge channel is moving
00172  *
00173  * \retval 0 Keep the callback hook.
00174  * \retval -1 Remove the callback hook.
00175  */
00176 typedef int (*ast_bridge_move_indicate_callback)(struct ast_bridge_channel *bridge_channel,
00177       void *hook_pvt, struct ast_bridge *src, struct ast_bridge *dst);
00178 
00179 enum ast_bridge_hook_remove_flags {
00180    /*! The hook is removed when the channel is pulled from the bridge. */
00181    AST_BRIDGE_HOOK_REMOVE_ON_PULL = (1 << 0),
00182    /*! The hook is removed when the bridge's personality changes. */
00183    AST_BRIDGE_HOOK_REMOVE_ON_PERSONALITY_CHANGE = (1 << 1),
00184 };
00185 
00186 enum ast_bridge_hook_type {
00187    /*! The hook type has not been specified. */
00188    AST_BRIDGE_HOOK_TYPE_NONE,
00189    AST_BRIDGE_HOOK_TYPE_DTMF,
00190    AST_BRIDGE_HOOK_TYPE_TIMER,
00191    AST_BRIDGE_HOOK_TYPE_HANGUP,
00192    AST_BRIDGE_HOOK_TYPE_JOIN,
00193    AST_BRIDGE_HOOK_TYPE_LEAVE,
00194    AST_BRIDGE_HOOK_TYPE_TALK,
00195    AST_BRIDGE_HOOK_TYPE_MOVE,
00196 };
00197 
00198 /*! \brief Structure that is the essence of a feature hook. */
00199 struct ast_bridge_hook {
00200    /*! Callback that is called when hook is tripped */
00201    ast_bridge_hook_callback callback;
00202    /*! Callback to destroy hook_pvt data right before destruction. */
00203    ast_bridge_hook_pvt_destructor destructor;
00204    /*! Unique data that was passed into us */
00205    void *hook_pvt;
00206    /*! Flags determining when hooks should be removed from a bridge channel */
00207    struct ast_flags remove_flags;
00208    /*! What kind of hook this is. */
00209    enum ast_bridge_hook_type type;
00210 };
00211 
00212 /*!
00213  * \brief Maximum length of a DTMF feature string
00214  */
00215 #define MAXIMUM_DTMF_FEATURE_STRING (11 + 1)
00216 
00217 /*! Extra parameters for a DTMF feature hook. */
00218 struct ast_bridge_hook_dtmf_parms {
00219    /*! DTMF String that is examined during a feature hook lookup */
00220    char code[MAXIMUM_DTMF_FEATURE_STRING];
00221 };
00222 
00223 /*! DTMF specific hook. */
00224 struct ast_bridge_hook_dtmf {
00225    /*! Generic feature hook information. */
00226    struct ast_bridge_hook generic;
00227    /*! Extra parameters for a DTMF feature hook. */
00228    struct ast_bridge_hook_dtmf_parms dtmf;
00229 };
00230 
00231 enum ast_bridge_hook_timer_option {
00232    /*! The timer temporarily affects media. (Like a custom playfile.) */
00233    AST_BRIDGE_HOOK_TIMER_OPTION_MEDIA = (1 << 0),
00234 };
00235 
00236 /*! Extra parameters for an interval timer hook. */
00237 struct ast_bridge_hook_timer_parms {
00238    /*! Time at which the hook should actually trip */
00239    struct timeval trip_time;
00240    /*! Heap index for interval hook */
00241    ssize_t heap_index;
00242    /*! Interval that the hook should execute at in milliseconds */
00243    unsigned int interval;
00244    /*! Sequence number for the hook to ensure expiration ordering */
00245    unsigned int seqno;
00246    /*! Option flags determining how callback is called. */
00247    unsigned int flags;
00248 };
00249 
00250 /*! Timer specific hook. */
00251 struct ast_bridge_hook_timer {
00252    /*! Generic feature hook information. */
00253    struct ast_bridge_hook generic;
00254    /*! Extra parameters for an interval timer hook. */
00255    struct ast_bridge_hook_timer_parms timer;
00256 };
00257 
00258 /*!
00259  * \brief Structure that contains features information
00260  */
00261 struct ast_bridge_features {
00262    /*! Attached DTMF feature hooks */
00263    struct ao2_container *dtmf_hooks;
00264    /*! Attached miscellaneous other hooks. */
00265    struct ao2_container *other_hooks;
00266    /*! Attached interval hooks */
00267    struct ast_heap *interval_hooks;
00268    /*! Feature flags that are enabled */
00269    struct ast_flags feature_flags;
00270    /*! Used to assign the sequence number to the next interval hook added. */
00271    unsigned int interval_sequence;
00272    /*! TRUE if feature_flags is setup */
00273    unsigned int usable:1;
00274    /*! TRUE if the channel/bridge is muted. */
00275    unsigned int mute:1;
00276    /*! TRUE if DTMF should be passed into the bridge tech.  */
00277    unsigned int dtmf_passthrough:1;
00278 };
00279 
00280 /*!
00281  * \brief Structure that contains configuration information for the blind transfer built in feature
00282  */
00283 struct ast_bridge_features_blind_transfer {
00284    /*! Context to use for transfers (If not empty.) */
00285    char context[AST_MAX_CONTEXT];
00286 };
00287 
00288 /*!
00289  * \brief Structure that contains configuration information for the attended transfer built in feature
00290  */
00291 struct ast_bridge_features_attended_transfer {
00292    /*! Context to use for transfers (If not empty.) */
00293    char context[AST_MAX_CONTEXT];
00294    /*! DTMF string used to abort the transfer (If not empty.) */
00295    char abort[MAXIMUM_DTMF_FEATURE_STRING];
00296    /*! DTMF string used to turn the transfer into a three way conference (If not empty.) */
00297    char threeway[MAXIMUM_DTMF_FEATURE_STRING];
00298    /*! DTMF string used to complete the transfer (If not empty.) */
00299    char complete[MAXIMUM_DTMF_FEATURE_STRING];
00300    /*! DTMF string used to swap bridged targets (If not empty.) */
00301    char swap[MAXIMUM_DTMF_FEATURE_STRING];
00302 };
00303 
00304 enum ast_bridge_features_monitor {
00305    /*! Toggle start/stop of Monitor/MixMonitor. */
00306    AUTO_MONITOR_TOGGLE,
00307    /*! Start Monitor/MixMonitor if not already started. */
00308    AUTO_MONITOR_START,
00309    /*! Stop Monitor/MixMonitor if not already stopped. */
00310    AUTO_MONITOR_STOP,
00311 };
00312 
00313 struct ast_bridge_features_automonitor {
00314    /*! Start/Stop behavior. */
00315    enum ast_bridge_features_monitor start_stop;
00316 };
00317 
00318 struct ast_bridge_features_automixmonitor {
00319    /*! Start/Stop behavior. */
00320    enum ast_bridge_features_monitor start_stop;
00321 };
00322 
00323 /*!
00324  * \brief Structure that contains configuration information for the limits feature
00325  */
00326 struct ast_bridge_features_limits {
00327    AST_DECLARE_STRING_FIELDS(
00328       /*! Sound file to play when the maximum duration is reached (if empty, then nothing will be played) */
00329       AST_STRING_FIELD(duration_sound);
00330       /*! Sound file to play when the warning time is reached (if empty, then the remaining time will be played) */
00331       AST_STRING_FIELD(warning_sound);
00332       /*! Sound file to play when the call is first entered (if empty, then the remaining time will be played) */
00333       AST_STRING_FIELD(connect_sound);
00334    );
00335    /*! Time when the bridge will be terminated by the limits feature */
00336    struct timeval quitting_time;
00337    /*! Maximum duration that the channel is allowed to be in the bridge (specified in milliseconds) */
00338    unsigned int duration;
00339    /*! Duration into the call when warnings should begin (specified in milliseconds or 0 to disable) */
00340    unsigned int warning;
00341    /*! Interval between the warnings (specified in milliseconds or 0 to disable) */
00342    unsigned int frequency;
00343 };
00344 
00345 /*!
00346  * \brief Register a handler for a built in feature
00347  *
00348  * \param feature The feature that the handler will be responsible for
00349  * \param callback The callback function that will handle it
00350  * \param dtmf Default DTMF string used to activate the feature
00351  *
00352  * \retval 0 on success
00353  * \retval -1 on failure
00354  *
00355  * Example usage:
00356  *
00357  * \code
00358  * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
00359  * \endcode
00360  *
00361  * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
00362  * attended transfer feature.
00363  */
00364 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_hook_callback callback, const char *dtmf);
00365 
00366 /*!
00367  * \brief Unregister a handler for a built in feature
00368  *
00369  * \param feature The feature to unregister
00370  *
00371  * \retval 0 on success
00372  * \retval -1 on failure
00373  *
00374  * Example usage:
00375  *
00376  * \code
00377  * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
00378  * \endcode
00379  *
00380  * This unregisters the function that is handling the built in attended transfer feature.
00381  */
00382 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
00383 
00384 /*!
00385  * \brief Invoke a built in feature hook now.
00386  *
00387  * \param feature The feature to invoke
00388  * \param bridge_channel Channel executing the feature
00389  * \param hook_pvt Private data passed in when the hook was created
00390  *
00391  * \note This API call is only meant to be used by bridge
00392  * subclasses and hook callbacks to request a builtin feature
00393  * hook to be executed.
00394  *
00395  * \retval 0 on success
00396  * \retval -1 on failure
00397  *
00398  * Example usage:
00399  *
00400  * \code
00401  * ast_bridge_features_do(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_channel, hook_pvt);
00402  * \endcode
00403  */
00404 int ast_bridge_features_do(enum ast_bridge_builtin_feature feature, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
00405 
00406 /*!
00407  * \brief Attach interval hooks to a bridge features structure
00408  *
00409  * \param features Bridge features structure
00410  * \param limits Configured limits applicable to the channel
00411  * \param remove_flags Dictates what situations the hook should be removed.
00412  *
00413  * \retval 0 on success
00414  * \retval -1 on failure
00415  */
00416 typedef int (*ast_bridge_builtin_set_limits_fn)(struct ast_bridge_features *features,
00417       struct ast_bridge_features_limits *limits, enum ast_bridge_hook_remove_flags remove_flags);
00418 
00419 /*!
00420  * \brief Register a handler for a built in interval feature
00421  *
00422  * \param interval The interval feature that the handler will be responsible for
00423  * \param callback the Callback function that will handle it
00424  *
00425  * \retval 0 on success
00426  * \retval -1 on failure
00427  *
00428  * Example usage:
00429  *
00430  * \code
00431  * ast_bridge_interval_register(AST_BRIDGE_BUILTIN_INTERVAL_LIMITS, bridge_builtin_set_limits);
00432  * \endcode
00433  *
00434  * This registers the function bridge_builtin_set_limits as the function responsible for the built in
00435  * duration limit feature.
00436  */
00437 int ast_bridge_interval_register(enum ast_bridge_builtin_interval interval, ast_bridge_builtin_set_limits_fn callback);
00438 
00439 /*!
00440  * \brief Unregisters a handler for a built in interval feature
00441  *
00442  * \param interval the interval feature to unregister
00443  *
00444  * \retval 0 on success
00445  * \retval -1 on failure
00446  *
00447  * Example usage:
00448  *
00449  * \code
00450  * ast_bridge_interval_unregister(AST_BRIDGE_BULTIN_INTERVAL_LIMITS)
00451  * /endcode
00452  *
00453  * This unregisters the function that is handling the built in duration limit feature.
00454  */
00455 int ast_bridge_interval_unregister(enum ast_bridge_builtin_interval interval);
00456 
00457 /*!
00458  * \brief Attach a bridge channel join hook to a bridge features structure
00459  *
00460  * \param features Bridge features structure
00461  * \param callback Function to execute upon activation
00462  * \param hook_pvt Unique data
00463  * \param destructor Optional destructor callback for hook_pvt data
00464  * \param remove_flags Dictates what situations the hook should be removed.
00465  *
00466  * \retval 0 on success
00467  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00468  *
00469  * Example usage:
00470  *
00471  * \code
00472  * struct ast_bridge_features features;
00473  * ast_bridge_features_init(&features);
00474  * ast_bridge_join_hook(&features, join_callback, NULL, NULL, 0);
00475  * \endcode
00476  *
00477  * This makes the bridging core call join_callback when a
00478  * channel successfully joins the bridging system.  A pointer to
00479  * useful data may be provided to the hook_pvt parameter.
00480  */
00481 int ast_bridge_join_hook(struct ast_bridge_features *features,
00482    ast_bridge_hook_callback callback,
00483    void *hook_pvt,
00484    ast_bridge_hook_pvt_destructor destructor,
00485    enum ast_bridge_hook_remove_flags remove_flags);
00486 
00487 /*!
00488  * \brief Attach a bridge channel leave hook to a bridge features structure
00489  *
00490  * \param features Bridge features structure
00491  * \param callback Function to execute upon activation
00492  * \param hook_pvt Unique data
00493  * \param destructor Optional destructor callback for hook_pvt data
00494  * \param remove_flags Dictates what situations the hook should be removed.
00495  *
00496  * \retval 0 on success
00497  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00498  *
00499  * Example usage:
00500  *
00501  * \code
00502  * struct ast_bridge_features features;
00503  * ast_bridge_features_init(&features);
00504  * ast_bridge_leave_hook(&features, leave_callback, NULL, NULL, 0);
00505  * \endcode
00506  *
00507  * This makes the bridging core call leave_callback when a
00508  * channel successfully leaves the bridging system.  A pointer
00509  * to useful data may be provided to the hook_pvt parameter.
00510  */
00511 int ast_bridge_leave_hook(struct ast_bridge_features *features,
00512    ast_bridge_hook_callback callback,
00513    void *hook_pvt,
00514    ast_bridge_hook_pvt_destructor destructor,
00515    enum ast_bridge_hook_remove_flags remove_flags);
00516 
00517 /*!
00518  * \brief Attach a hangup hook to a bridge features structure
00519  *
00520  * \param features Bridge features structure
00521  * \param callback Function to execute upon activation
00522  * \param hook_pvt Unique data
00523  * \param destructor Optional destructor callback for hook_pvt data
00524  * \param remove_flags Dictates what situations the hook should be removed.
00525  *
00526  * \retval 0 on success
00527  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00528  *
00529  * Example usage:
00530  *
00531  * \code
00532  * struct ast_bridge_features features;
00533  * ast_bridge_features_init(&features);
00534  * ast_bridge_hangup_hook(&features, hangup_callback, NULL, NULL, 0);
00535  * \endcode
00536  *
00537  * This makes the bridging core call hangup_callback if a
00538  * channel that has this hook hangs up.  A pointer to useful
00539  * data may be provided to the hook_pvt parameter.
00540  */
00541 int ast_bridge_hangup_hook(struct ast_bridge_features *features,
00542    ast_bridge_hook_callback callback,
00543    void *hook_pvt,
00544    ast_bridge_hook_pvt_destructor destructor,
00545    enum ast_bridge_hook_remove_flags remove_flags);
00546 
00547 /*!
00548  * \brief Attach a DTMF hook to a bridge features structure
00549  *
00550  * \param features Bridge features structure
00551  * \param dtmf DTMF string to be activated upon
00552  * \param callback Function to execute upon activation
00553  * \param hook_pvt Unique data
00554  * \param destructor Optional destructor callback for hook_pvt data
00555  * \param remove_flags Dictates what situations the hook should be removed.
00556  *
00557  * \retval 0 on success
00558  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00559  *
00560  * Example usage:
00561  *
00562  * \code
00563  * struct ast_bridge_features features;
00564  * ast_bridge_features_init(&features);
00565  * ast_bridge_dtmf_hook(&features, "#", pound_callback, NULL, NULL, 0);
00566  * \endcode
00567  *
00568  * This makes the bridging core call pound_callback if a channel that has this
00569  * feature structure inputs the DTMF string '#'. A pointer to useful data may be
00570  * provided to the hook_pvt parameter.
00571  */
00572 int ast_bridge_dtmf_hook(struct ast_bridge_features *features,
00573    const char *dtmf,
00574    ast_bridge_hook_callback callback,
00575    void *hook_pvt,
00576    ast_bridge_hook_pvt_destructor destructor,
00577    enum ast_bridge_hook_remove_flags remove_flags);
00578 
00579 /*!
00580  * \brief Attach an interval hook to a bridge features structure
00581  *
00582  * \param features Bridge features structure
00583  * \param flags Interval timer callback option flags.
00584  * \param interval The interval that the hook should execute at in milliseconds
00585  * \param callback Function to execute upon activation
00586  * \param hook_pvt Unique data
00587  * \param destructor Optional destructor callback for hook_pvt data
00588  * \param remove_flags Dictates what situations the hook should be removed.
00589  *
00590  * \retval 0 on success
00591  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00592  *
00593  * \code
00594  * struct ast_bridge_features features;
00595  * ast_bridge_features_init(&features);
00596  * ast_bridge_interval_hook(&features, 1000, playback_callback, NULL, NULL, 0);
00597  * \endcode
00598  *
00599  * This makes the bridging core call playback_callback every second. A pointer to useful
00600  * data may be provided to the hook_pvt parameter.
00601  */
00602 int ast_bridge_interval_hook(struct ast_bridge_features *features,
00603    enum ast_bridge_hook_timer_option flags,
00604    unsigned int interval,
00605    ast_bridge_hook_callback callback,
00606    void *hook_pvt,
00607    ast_bridge_hook_pvt_destructor destructor,
00608    enum ast_bridge_hook_remove_flags remove_flags);
00609 
00610 /*!
00611  * \brief Attach a bridge channel talk detection hook to a bridge features structure
00612  *
00613  * \param features Bridge features structure
00614  * \param callback Function to execute upon activation
00615  * \param hook_pvt Unique data
00616  * \param destructor Optional destructor callback for hook_pvt data
00617  * \param remove_flags Dictates what situations the hook should be removed.
00618  *
00619  * \retval 0 on success
00620  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00621  *
00622  * Example usage:
00623  *
00624  * \code
00625  * struct ast_bridge_features features;
00626  * ast_bridge_features_init(&features);
00627  * ast_bridge_talk_hook(&features, talk_callback, NULL, NULL, 0);
00628  * \endcode
00629  *
00630  * This makes the bridging technology call talk_callback when a
00631  * channel is recognized as starting and stopping talking.  A
00632  * pointer to useful data may be provided to the hook_pvt
00633  * parameter.
00634  *
00635  * \note This hook is currently only supported by softmix.
00636  */
00637 int ast_bridge_talk_detector_hook(struct ast_bridge_features *features,
00638    ast_bridge_talking_indicate_callback callback,
00639    void *hook_pvt,
00640    ast_bridge_hook_pvt_destructor destructor,
00641    enum ast_bridge_hook_remove_flags remove_flags);
00642 
00643 /*!
00644  * \brief Attach a bridge channel move detection hook to a bridge features structure
00645  *
00646  * \param features Bridge features structure
00647  * \param callback Function to execute upon activation
00648  * \param hook_pvt Unique data
00649  * \param destructor Optional destructor callback for hook_pvt data
00650  * \param remove_flags Dictates what situations the hook should be removed.
00651  *
00652  * \retval 0 on success
00653  * \retval -1 on failure (The caller must cleanup any hook_pvt resources.)
00654  *
00655  * Example usage:
00656  *
00657  * \code
00658  * struct ast_bridge_features features;
00659  * ast_bridge_features_init(&features);
00660  * ast_bridge_move_hook(&features, move_callback, NULL, NULL, 0);
00661  * \endcode
00662  *
00663  * This makes the bridging core call \ref callback when a
00664  * channel is moved from one bridge to another.  A
00665  * pointer to useful data may be provided to the hook_pvt
00666  * parameter.
00667  */
00668 int ast_bridge_move_hook(struct ast_bridge_features *features,
00669    ast_bridge_move_indicate_callback callback,
00670    void *hook_pvt,
00671    ast_bridge_hook_pvt_destructor destructor,
00672    enum ast_bridge_hook_remove_flags remove_flags);
00673 
00674 /*!
00675  * \brief Enable a built in feature on a bridge features structure
00676  *
00677  * \param features Bridge features structure
00678  * \param feature Feature to enable
00679  * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
00680  * \param config Configuration structure unique to the built in type
00681  * \param destructor Optional destructor callback for config data
00682  * \param remove_flags Dictates what situations the hook should be removed.
00683  *
00684  * \retval 0 on success
00685  * \retval -1 on failure
00686  *
00687  * Example usage:
00688  *
00689  * \code
00690  * struct ast_bridge_features features;
00691  * ast_bridge_features_init(&features);
00692  * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL, NULL, 0);
00693  * \endcode
00694  *
00695  * This enables the attended transfer DTMF option using the default DTMF string. An alternate
00696  * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
00697  * to a built in feature callback function.
00698  */
00699 int ast_bridge_features_enable(struct ast_bridge_features *features,
00700    enum ast_bridge_builtin_feature feature,
00701    const char *dtmf,
00702    void *config,
00703    ast_bridge_hook_pvt_destructor destructor,
00704    enum ast_bridge_hook_remove_flags remove_flags);
00705 
00706 /*!
00707  * \brief Constructor function for ast_bridge_features_limits
00708  *
00709  * \param limits pointer to a ast_bridge_features_limits struct that has been allocted, but not initialized
00710  *
00711  * \retval 0 on success
00712  * \retval -1 on failure
00713  */
00714 int ast_bridge_features_limits_construct(struct ast_bridge_features_limits *limits);
00715 
00716 /*!
00717  * \brief Destructor function for ast_bridge_features_limits
00718  *
00719  * \param limits pointer to an ast_bridge_features_limits struct that needs to be destroyed
00720  *
00721  * This function does not free memory allocated to the ast_bridge_features_limits struct, it only frees elements within the struct.
00722  * You must still call ast_free on the the struct if you allocated it with malloc.
00723  */
00724 void ast_bridge_features_limits_destroy(struct ast_bridge_features_limits *limits);
00725 
00726 /*!
00727  * \brief Limit the amount of time a channel may stay in the bridge and optionally play warning messages as time runs out
00728  *
00729  * \param features Bridge features structure
00730  * \param limits Configured limits applicable to the channel
00731  * \param remove_flags Dictates what situations the hook should be removed.
00732  *
00733  * \retval 0 on success
00734  * \retval -1 on failure
00735  *
00736  * Example usage:
00737  *
00738  * \code
00739  * struct ast_bridge_features features;
00740  * struct ast_bridge_features_limits limits;
00741  * ast_bridge_features_init(&features);
00742  * ast_bridge_features_limits_construct(&limits);
00743  * ast_bridge_features_set_limits(&features, &limits, 0);
00744  * ast_bridge_features_limits_destroy(&limits);
00745  * \endcode
00746  *
00747  * This sets the maximum time the channel can be in the bridge to 10 seconds and does not play any warnings.
00748  *
00749  * \note This API call can only be used on a features structure that will be used in association with a bridge channel.
00750  * \note The ast_bridge_features_limits structure must remain accessible for the lifetime of the features structure.
00751  */
00752 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);
00753 
00754 /*!
00755  * \brief Set a flag on a bridge channel features structure
00756  *
00757  * \param features Bridge channel features structure
00758  * \param flag Flag to enable
00759  *
00760  * \return Nothing
00761  *
00762  * Example usage:
00763  *
00764  * \code
00765  * struct ast_bridge_features features;
00766  * ast_bridge_features_init(&features);
00767  * ast_bridge_features_set_flag(&features, AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP);
00768  * \endcode
00769  *
00770  * This sets the AST_BRIDGE_CHANNEL_FLAG_DISSOLVE_HANGUP feature
00771  * to be enabled on the features structure 'features'.
00772  */
00773 void ast_bridge_features_set_flag(struct ast_bridge_features *features, unsigned int flag);
00774 
00775 /*!
00776  * \brief Merge one ast_bridge_features into another
00777  *
00778  * \param into The ast_bridge_features that will be merged into
00779  * \param from The ast_bridge_features that will be merged from
00780  */
00781 void ast_bridge_features_merge(struct ast_bridge_features *into, const struct ast_bridge_features *from);
00782 
00783 /*!
00784  * \brief Initialize bridge features structure
00785  *
00786  * \param features Bridge featues structure
00787  *
00788  * \retval 0 on success
00789  * \retval -1 on failure
00790  *
00791  * Example usage:
00792  *
00793  * \code
00794  * struct ast_bridge_features features;
00795  * ast_bridge_features_init(&features);
00796  * \endcode
00797  *
00798  * This initializes the feature structure 'features' to have nothing enabled.
00799  *
00800  * \note This MUST be called before enabling features or flags. Failure to do so
00801  *       may result in a crash.
00802  */
00803 int ast_bridge_features_init(struct ast_bridge_features *features);
00804 
00805 /*!
00806  * \brief Clean up the contents of a bridge features structure
00807  *
00808  * \param features Bridge features structure
00809  *
00810  * \return Nothing
00811  *
00812  * Example usage:
00813  *
00814  * \code
00815  * struct ast_bridge_features features;
00816  * ast_bridge_features_init(&features);
00817  * ast_bridge_features_cleanup(&features);
00818  * \endcode
00819  *
00820  * This cleans up the feature structure 'features'.
00821  *
00822  * \note This MUST be called after the features structure is done being used
00823  *       or a memory leak may occur.
00824  */
00825 void ast_bridge_features_cleanup(struct ast_bridge_features *features);
00826 
00827 /*!
00828  * \brief Allocate a new bridge features struct.
00829  * \since 12.0.0
00830  *
00831  * Example usage:
00832  *
00833  * \code
00834  * struct ast_bridge_features *features;
00835  * features = ast_bridge_features_new();
00836  * ast_bridge_features_destroy(features);
00837  * \endcode
00838  *
00839  * \retval features New allocated features struct.
00840  * \retval NULL on error.
00841  */
00842 struct ast_bridge_features *ast_bridge_features_new(void);
00843 
00844 /*!
00845  * \brief Destroy an allocated bridge features struct.
00846  * \since 12.0.0
00847  *
00848  * \param features Bridge features structure
00849  *
00850  * Example usage:
00851  *
00852  * \code
00853  * struct ast_bridge_features *features;
00854  * features = ast_bridge_features_new();
00855  * ast_bridge_features_destroy(features);
00856  * \endcode
00857  *
00858  * \return Nothing
00859  */
00860 void ast_bridge_features_destroy(struct ast_bridge_features *features);
00861 
00862 #if defined(__cplusplus) || defined(c_plusplus)
00863 }
00864 #endif
00865 
00866 #endif /* _ASTERISK_BRIDGING_FEATURES_H */

Generated on Thu Apr 16 06:27:16 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6