bridge_technology.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 /*! \file
00020  * \brief Channel Bridging API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H
00025 #define _ASTERISK_BRIDGING_TECHNOLOGY_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*!
00032  * \brief Base preference values for choosing a bridge technology.
00033  *
00034  * \note Higher is more preference.
00035  */
00036 enum ast_bridge_preference {
00037    AST_BRIDGE_PREFERENCE_BASE_HOLDING  = 50,
00038    AST_BRIDGE_PREFERENCE_BASE_EARLY    = 100,
00039    AST_BRIDGE_PREFERENCE_BASE_NATIVE   = 90,
00040    AST_BRIDGE_PREFERENCE_BASE_1TO1MIX  = 50,
00041    AST_BRIDGE_PREFERENCE_BASE_MULTIMIX = 10,
00042 };
00043 
00044 /*!
00045  * \brief Structure specific to bridge technologies capable of
00046  * performing talking optimizations.
00047  */
00048 struct ast_bridge_tech_optimizations {
00049    /*! The amount of time in ms that talking must be detected before
00050     *  the dsp determines that talking has occurred */
00051    unsigned int talking_threshold;
00052    /*! The amount of time in ms that silence must be detected before
00053     *  the dsp determines that talking has stopped */
00054    unsigned int silence_threshold;
00055    /*! Whether or not the bridging technology should drop audio
00056     *  detected as silence from the mix. */
00057    unsigned int drop_silence:1;
00058 };
00059 
00060 /*!
00061  * \brief Structure that is the essence of a bridge technology
00062  */
00063 struct ast_bridge_technology {
00064    /*! Unique name to this bridge technology */
00065    const char *name;
00066    /*! The capabilities that this bridge technology is capable of.  This has nothing to do with
00067     * format capabilities. */
00068    uint32_t capabilities;
00069    /*! Preference level that should be used when determining whether to use this bridge technology or not */
00070    enum ast_bridge_preference preference;
00071    /*!
00072     * \brief Create a bridge technology instance for a bridge.
00073     *
00074     * \retval 0 on success
00075     * \retval -1 on failure
00076     *
00077     * \note On entry, bridge may or may not already be locked.
00078     * However, it can be accessed as if it were locked.
00079     */
00080    int (*create)(struct ast_bridge *bridge);
00081    /*!
00082     * \brief Request a bridge technology instance start operations.
00083     *
00084     * \retval 0 on success
00085     * \retval -1 on failure
00086     *
00087     * \note On entry, bridge may or may not already be locked.
00088     * However, it can be accessed as if it were locked.
00089     */
00090    int (*start)(struct ast_bridge *bridge);
00091    /*!
00092     * \brief Request a bridge technology instance stop in preparation for being destroyed.
00093     *
00094     * \note On entry, bridge is already locked.
00095     */
00096    void (*stop)(struct ast_bridge *bridge);
00097    /*!
00098     * \brief Destroy a bridging technology instance for a bridge.
00099     *
00100     * \note On entry, bridge must NOT be locked.
00101     */
00102    void (*destroy)(struct ast_bridge *bridge);
00103    /*!
00104     * \brief Add a channel to a bridging technology instance for a bridge.
00105     *
00106     * \retval 0 on success
00107     * \retval -1 on failure
00108     *
00109     * \note On entry, bridge is already locked.
00110     */
00111    int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00112    /*!
00113     * \brief Remove a channel from a bridging technology instance for a bridge.
00114     *
00115     * \note On entry, bridge is already locked.
00116     * \note Do not make assumptions about the number of channels in the bridge when
00117     * this callback is called. When a channel is swapped into a bridge for another
00118     * channel, the leave callback is called after the new channel has been added to
00119     * the bridge.
00120     */
00121    void (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00122    /*!
00123     * \brief Suspend a channel on a bridging technology instance for a bridge.
00124     *
00125     * \note On entry, bridge is already locked.
00126     */
00127    void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00128    /*!
00129     * \brief Unsuspend a channel on a bridging technology instance for a bridge.
00130     *
00131     * \note On entry, bridge is already locked.
00132     */
00133    void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00134    /*!
00135     * \brief Check if a bridge is compatible with the bridging technology.
00136     *
00137     * \retval 0 if not compatible
00138     * \retval non-zero if compatible
00139     *
00140     * \note On entry, bridge may or may not already be locked.
00141     * However, it can be accessed as if it were locked.
00142     */
00143    int (*compatible)(struct ast_bridge *bridge);
00144    /*!
00145     * \brief Write a frame into the bridging technology instance for a bridge.
00146     *
00147     * \note The bridge must be tolerant of bridge_channel being NULL.
00148     *
00149     * \retval 0 Frame accepted into the bridge.
00150     * \retval -1 Frame needs to be deferred.
00151     *
00152     * \note On entry, bridge is already locked.
00153     */
00154    int (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
00155    /*! TRUE if the bridge technology is currently suspended. */
00156    unsigned int suspended:1;
00157    /*! Module this bridge technology belongs to. It is used for reference counting bridges using the technology. */
00158    struct ast_module *mod;
00159    /*! Linked list information */
00160    AST_RWLIST_ENTRY(ast_bridge_technology) entry;
00161 };
00162 
00163 /*!
00164  * \brief Register a bridge technology for use
00165  *
00166  * \param technology The bridge technology to register
00167  * \param mod The module that is registering the bridge technology
00168  *
00169  * \retval 0 on success
00170  * \retval -1 on failure
00171  *
00172  * Example usage:
00173  *
00174  * \code
00175  * ast_bridge_technology_register(&simple_bridge_tech);
00176  * \endcode
00177  *
00178  * This registers a bridge technology declared as the structure
00179  * simple_bridge_tech with the bridging core and makes it available for
00180  * use when creating bridges.
00181  */
00182 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
00183 
00184 /*! \brief See \ref __ast_bridge_technology_register() */
00185 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
00186 
00187 /*!
00188  * \brief Unregister a bridge technology from use
00189  *
00190  * \param technology The bridge technology to unregister
00191  *
00192  * \retval 0 on success
00193  * \retval -1 on failure
00194  *
00195  * Example usage:
00196  *
00197  * \code
00198  * ast_bridge_technology_unregister(&simple_bridge_tech);
00199  * \endcode
00200  *
00201  * This unregisters a bridge technlogy declared as the structure
00202  * simple_bridge_tech with the bridging core. It will no longer be
00203  * considered when creating a new bridge.
00204  */
00205 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
00206 
00207 /*!
00208  * \brief Suspend a bridge technology from consideration
00209  *
00210  * \param technology The bridge technology to suspend
00211  *
00212  * Example usage:
00213  *
00214  * \code
00215  * ast_bridge_technology_suspend(&simple_bridge_tech);
00216  * \endcode
00217  *
00218  * This suspends the bridge technology simple_bridge_tech from being considered
00219  * when creating a new bridge. Existing bridges using the bridge technology
00220  * are not affected.
00221  */
00222 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
00223 
00224 /*!
00225  * \brief Unsuspend a bridge technology
00226  *
00227  * \param technology The bridge technology to unsuspend
00228  *
00229  * Example usage:
00230  *
00231  * \code
00232  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
00233  * \endcode
00234  *
00235  * This makes the bridge technology simple_bridge_tech considered when
00236  * creating a new bridge again.
00237  */
00238 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
00239 
00240 #if defined(__cplusplus) || defined(c_plusplus)
00241 }
00242 #endif
00243 
00244 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */

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