bridge_technology.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2009, Digium, Inc.
 *
 * Joshua Colp <jcolp@digium.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */
 
/*! \file
 * \brief Channel Bridging API
 * \author Joshua Colp <jcolp@digium.com>
 */
 
#ifndef _ASTERISK_BRIDGING_TECHNOLOGY_H
#define _ASTERISK_BRIDGING_TECHNOLOGY_H
 
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
 
/*!
 * \brief Base preference values for choosing a bridge technology.
 *
 * \note Higher is more preference.
 */
enum ast_bridge_preference {
    AST_BRIDGE_PREFERENCE_BASE_HOLDING  = 50,
    AST_BRIDGE_PREFERENCE_BASE_EARLY    = 100,
    AST_BRIDGE_PREFERENCE_BASE_NATIVE   = 90,
    AST_BRIDGE_PREFERENCE_BASE_1TO1MIX  = 50,
    AST_BRIDGE_PREFERENCE_BASE_MULTIMIX = 10,
};
 
/*!
 * \brief Structure specific to bridge technologies capable of
 * performing talking optimizations.
 */
struct ast_bridge_tech_optimizations {
    /*! Minimum average magnitude threshold to determine talking by the DSP. */
    unsigned int talking_threshold;
    /*! Time in ms of silence necessary to declare talking stopped by the bridge. */
    unsigned int silence_threshold;
    /*! Whether or not the bridging technology should drop audio
     *  detected as silence from the mix. */
    unsigned int drop_silence:1;
};
 
/*!
 * \brief Structure that is the essence of a bridge technology
 */
struct ast_bridge_technology {
    /*! Unique name to this bridge technology */
    const char *name;
    /*! The capabilities that this bridge technology is capable of.  This has nothing to do with
     * format capabilities. */
    uint32_t capabilities;
    /*! Preference level that should be used when determining whether to use this bridge technology or not */
    enum ast_bridge_preference preference;
    /*!
     * \brief Create a bridge technology instance for a bridge.
     *
     * \retval 0 on success
     * \retval -1 on failure
     *
     * \note On entry, bridge may or may not already be locked.
     * However, it can be accessed as if it were locked.
     */
    int (*create)(struct ast_bridge *bridge);
    /*!
     * \brief Request a bridge technology instance start operations.
     *
     * \retval 0 on success
     * \retval -1 on failure
     *
     * \note On entry, bridge may or may not already be locked.
     * However, it can be accessed as if it were locked.
     */
    int (*start)(struct ast_bridge *bridge);
    /*!
     * \brief Request a bridge technology instance stop in preparation for being destroyed.
     *
     * \note On entry, bridge is already locked.
     */
    void (*stop)(struct ast_bridge *bridge);
    /*!
     * \brief Destroy a bridging technology instance for a bridge.
     *
     * \note On entry, bridge must NOT be locked.
     */
    void (*destroy)(struct ast_bridge *bridge);
    /*!
     * \brief Add a channel to a bridging technology instance for a bridge.
     *
     * \retval 0 on success
     * \retval -1 on failure
     *
     * \note On entry, bridge is already locked.
     *
     * \note The bridge technology must tolerate a failed to join channel
     * until it can be kicked from the bridge.
     *
     * \note A channel may be in a suspended state already when joining a bridge
     * technology. The technology must handle this case.
     *
     * \note A channel may not be answered when joining a bridge technology.
     */
    int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*!
     * \brief Remove a channel from a bridging technology instance for a bridge.
     *
     * \note On entry, bridge is already locked.
     * \note Do not make assumptions about the number of channels in the bridge when
     * this callback is called. When a channel is swapped into a bridge for another
     * channel, the leave callback is called after the new channel has been added to
     * the bridge.
     */
    void (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*!
     * \brief Suspend a channel on a bridging technology instance for a bridge.
     *
     * \note On entry, bridge is already locked.
     */
    void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*!
     * \brief Unsuspend a channel on a bridging technology instance for a bridge.
     *
     * \note On entry, bridge is already locked.
     */
    void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*!
     * \brief Check if a bridge is compatible with the bridging technology.
     *
     * \retval 0 if not compatible
     * \retval non-zero if compatible
     *
     * \note On entry, bridge may or may not already be locked.
     * However, it can be accessed as if it were locked.
     */
    int (*compatible)(struct ast_bridge *bridge);
    /*!
     * \brief Write a frame into the bridging technology instance for a bridge.
     *
     * \note The bridge must be tolerant of bridge_channel being NULL.
     *
     * \retval 0 Frame accepted into the bridge.
     * \retval -1 Frame needs to be deferred.
     *
     * \note On entry, bridge is already locked.
     *
     * \note Deferred frames will be automatically queued onto the channel when another
     * channel joins the bridge.
     */
    int (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_frame *frame);
    /*!
     * \brief Callback for when a request has been made to change a stream topology on a channel
     *
     * \details
     * This is called when a bridge receives a request to change the
     * topology on the channel.  A bridge technology should define a
     * handler for this callback if it needs to update internals or
     * intercept the request and not pass it on to other channels.
     * This can be done by returning a nonzero value.
     *
     * \retval 0 Frame can pass to the bridge technology.
     * \retval non-zero Frame intercepted by the bridge technology.
     *
     * \note On entry, bridge is already locked.
     */
    int (*stream_topology_request_change)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*!
     * \brief Callback for when a stream topology changes on the channel
     *
     * \details
     * This is called when a bridge receives an indication that a
     * topology has been changed on a channel and the new topology has
     * been mapped to the bridge.  A bridge technology should define a
     * handler for this callback if it needs to update internals due
     * to a channel's topology changing.
     *
     * \note On entry, bridge is already locked.
     */
    void (*stream_topology_changed)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
    /*! TRUE if the bridge technology is currently suspended. */
    unsigned int suspended:1;
    /*! Module this bridge technology belongs to. It is used for reference counting bridges using the technology. */
    struct ast_module *mod;
    /*! Linked list information */
    AST_RWLIST_ENTRY(ast_bridge_technology) entry;
};
 
/*!
 * \brief Register a bridge technology for use
 *
 * \param technology The bridge technology to register
 * \param mod The module that is registering the bridge technology
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_technology_register(&simple_bridge_tech);
 * \endcode
 *
 * This registers a bridge technology declared as the structure
 * simple_bridge_tech with the bridging core and makes it available for
 * use when creating bridges.
 */
int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
 
/*! \brief See \ref __ast_bridge_technology_register() */
#define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, AST_MODULE_SELF)
 
/*!
 * \brief Unregister a bridge technology from use
 *
 * \param technology The bridge technology to unregister
 *
 * \retval 0 on success
 * \retval -1 on failure
 *
 * Example usage:
 *
 * \code
 * ast_bridge_technology_unregister(&simple_bridge_tech);
 * \endcode
 *
 * This unregisters a bridge technlogy declared as the structure
 * simple_bridge_tech with the bridging core. It will no longer be
 * considered when creating a new bridge.
 */
int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
 
/*!
 * \brief Suspend a bridge technology from consideration
 *
 * \param technology The bridge technology to suspend
 *
 * Example usage:
 *
 * \code
 * ast_bridge_technology_suspend(&simple_bridge_tech);
 * \endcode
 *
 * This suspends the bridge technology simple_bridge_tech from being considered
 * when creating a new bridge. Existing bridges using the bridge technology
 * are not affected.
 */
void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
 
/*!
 * \brief Unsuspend a bridge technology
 *
 * \param technology The bridge technology to unsuspend
 *
 * Example usage:
 *
 * \code
 * ast_bridge_technology_unsuspend(&simple_bridge_tech);
 * \endcode
 *
 * This makes the bridge technology simple_bridge_tech considered when
 * creating a new bridge again.
 */
void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
 
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
 
#endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */