Fri Aug 17 00:17:11 2018

Asterisk developer's documentation


bridging_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 /*! \brief Preference for choosing the bridge technology */
00032 enum ast_bridge_preference {
00033    /*! Bridge technology should have high precedence over other bridge technologies */
00034    AST_BRIDGE_PREFERENCE_HIGH = 0,
00035    /*! Bridge technology is decent, not the best but should still be considered over low */
00036    AST_BRIDGE_PREFERENCE_MEDIUM,
00037    /*! Bridge technology is low, it should not be considered unless it is absolutely needed */
00038    AST_BRIDGE_PREFERENCE_LOW,
00039 };
00040 
00041 /*!
00042  * \brief Structure that is the essence of a bridge technology
00043  */
00044 struct ast_bridge_technology {
00045    /*! Unique name to this bridge technology */
00046    const char *name;
00047    /*! The capabilities that this bridge technology is capable of */
00048    int capabilities;
00049    /*! Preference level that should be used when determining whether to use this bridge technology or not */
00050    enum ast_bridge_preference preference;
00051    /*! Callback for when a bridge is being created */
00052    int (*create)(struct ast_bridge *bridge);
00053    /*! Callback for when a bridge is being destroyed */
00054    int (*destroy)(struct ast_bridge *bridge);
00055    /*! Callback for when a channel is being added to a bridge */
00056    int (*join)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00057    /*! Callback for when a channel is leaving a bridge */
00058    int (*leave)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00059    /*! Callback for when a channel is suspended from the bridge */
00060    void (*suspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00061    /*! Callback for when a channel is unsuspended from the bridge */
00062    void (*unsuspend)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00063    /*! Callback to see if a channel is compatible with the bridging technology */
00064    int (*compatible)(struct ast_bridge_channel *bridge_channel);
00065    /*! Callback for writing a frame into the bridging technology */
00066    enum ast_bridge_write_result (*write)(struct ast_bridge *bridge, struct ast_bridge_channel *bridged_channel, struct ast_frame *frame);
00067    /*! Callback for when a file descriptor trips */
00068    int (*fd)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int fd);
00069    /*! Callback for replacement thread function */
00070    int (*thread)(struct ast_bridge *bridge);
00071    /*! Callback for poking a bridge thread */
00072    int (*poke)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel);
00073    /*! Formats that the bridge technology supports */
00074    format_t formats;
00075    /*! Bit to indicate whether the bridge technology is currently suspended or not */
00076    unsigned int suspended:1;
00077    /*! Module this bridge technology belongs to. Is used for reference counting when creating/destroying a bridge. */
00078    struct ast_module *mod;
00079    /*! Linked list information */
00080    AST_RWLIST_ENTRY(ast_bridge_technology) entry;
00081 };
00082 
00083 /*! \brief Register a bridge technology for use
00084  *
00085  * \param technology The bridge technology to register
00086  * \param mod The module that is registering the bridge technology
00087  *
00088  * \retval 0 on success
00089  * \retval -1 on failure
00090  *
00091  * Example usage:
00092  *
00093  * \code
00094  * ast_bridge_technology_register(&simple_bridge_tech);
00095  * \endcode
00096  *
00097  * This registers a bridge technology declared as the structure
00098  * simple_bridge_tech with the bridging core and makes it available for
00099  * use when creating bridges.
00100  */
00101 int __ast_bridge_technology_register(struct ast_bridge_technology *technology, struct ast_module *mod);
00102 
00103 /*! \brief See \ref __ast_bridge_technology_register() */
00104 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
00105 
00106 /*! \brief Unregister a bridge technology from use
00107  *
00108  * \param technology The bridge technology to unregister
00109  *
00110  * \retval 0 on success
00111  * \retval -1 on failure
00112  *
00113  * Example usage:
00114  *
00115  * \code
00116  * ast_bridge_technology_unregister(&simple_bridge_tech);
00117  * \endcode
00118  *
00119  * This unregisters a bridge technlogy declared as the structure
00120  * simple_bridge_tech with the bridging core. It will no longer be
00121  * considered when creating a new bridge.
00122  */
00123 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
00124 
00125 /*! \brief Feed notification that a frame is waiting on a channel into the bridging core
00126  *
00127  * \param bridge The bridge that the notification should influence
00128  * \param bridge_channel Bridge channel the notification was received on (if known)
00129  * \param chan Channel the notification was received on (if known)
00130  * \param outfd File descriptor that the notification was received on (if known)
00131  *
00132  * Example usage:
00133  *
00134  * \code
00135  * ast_bridge_handle_trip(bridge, NULL, chan, -1);
00136  * \endcode
00137  *
00138  * This tells the bridging core that a frame has been received on
00139  * the channel pointed to by chan and that it should be read and handled.
00140  *
00141  * \note This should only be used by bridging technologies.
00142  */
00143 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd);
00144 
00145 /*! \brief Suspend a bridge technology from consideration
00146  *
00147  * \param technology The bridge technology to suspend
00148  *
00149  * Example usage:
00150  *
00151  * \code
00152  * ast_bridge_technology_suspend(&simple_bridge_tech);
00153  * \endcode
00154  *
00155  * This suspends the bridge technology simple_bridge_tech from being considered
00156  * when creating a new bridge. Existing bridges using the bridge technology
00157  * are not affected.
00158  */
00159 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
00160 
00161 /*! \brief Unsuspend a bridge technology
00162  *
00163  * \param technology The bridge technology to unsuspend
00164  *
00165  * Example usage:
00166  *
00167  * \code
00168  * ast_bridge_technology_unsuspend(&simple_bridge_tech);
00169  * \endcode
00170  *
00171  * This makes the bridge technology simple_bridge_tech considered when
00172  * creating a new bridge again.
00173  */
00174 void ast_bridge_technology_unsuspend(struct ast_bridge_technology *technology);
00175 
00176 #if defined(__cplusplus) || defined(c_plusplus)
00177 }
00178 #endif
00179 
00180 #endif /* _ASTERISK_BRIDGING_TECHNOLOGY_H */

Generated on 17 Aug 2018 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1