bridge_internal.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2013 Digium, Inc.
00005  *
00006  * Mark Michelson <mmichelson@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 Private Bridging API
00022  *
00023  * Functions in this file are intended to be used by the Bridging API,
00024  * bridge mixing technologies, and bridge sub-classes. Users of bridges
00025  * that do not fit those three categories should *not* use the API
00026  * defined in this file.
00027  *
00028  * \author Mark Michelson <mmichelson@digium.com>
00029  *
00030  * See Also:
00031  * \arg \ref AstCREDITS
00032  */
00033 
00034 #ifndef _ASTERISK_PRIVATE_BRIDGING_H
00035 #define _ASTERISK_PRIVATE_BRIDGING_H
00036 
00037 struct ast_bridge;
00038 struct ast_bridge_channel;
00039 struct ast_bridge_methods;
00040 
00041 /*!
00042  * \brief Register the new bridge with the system.
00043  * \since 12.0.0
00044  *
00045  * \param bridge What to register. (Tolerates a NULL pointer)
00046  *
00047  * \code
00048  * struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
00049  * {
00050  *     void *bridge;
00051  *
00052  *     bridge = bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
00053  *     bridge = bridge_base_init(bridge, capabilities, flags);
00054  *     bridge = ast_bridge_basic_init(bridge, dtmf_features);
00055  *     bridge = bridge_register(bridge);
00056  *     return bridge;
00057  * }
00058  * \endcode
00059  *
00060  * \note This must be done after a bridge constructor has
00061  * completed setting up the new bridge but before it returns.
00062  *
00063  * \note After a bridge is registered, ast_bridge_destroy() must
00064  * eventually be called to get rid of the bridge.
00065  *
00066  * \retval bridge on success.
00067  * \retval NULL on error.
00068  */
00069 struct ast_bridge *bridge_register(struct ast_bridge *bridge);
00070 
00071 /*!
00072  * \internal
00073  * \brief Allocate the bridge class object memory.
00074  * \since 12.0.0
00075  *
00076  * \param size Size of the bridge class structure to allocate.
00077  * \param v_table Bridge class virtual method table.
00078  *
00079  * \retval bridge on success.
00080  * \retval NULL on error.
00081  */
00082 struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
00083 
00084 /*!
00085  * \brief Initialize the base class of the bridge.
00086  *
00087  * \param self Bridge to operate upon. (Tolerates a NULL pointer)
00088  * \param capabilities The capabilities that we require to be used on the bridge
00089  * \param flags Flags that will alter the behavior of the bridge
00090  * \param creator Entity that created the bridge (optional)
00091  * \param name Name given to the bridge by its creator (optional, requires named creator)
00092  * \param id Unique ID given to the bridge by its creator (optional)
00093  *
00094  * \retval self on success
00095  * \retval NULL on failure, self is already destroyed
00096  *
00097  * Example usage:
00098  *
00099  * \code
00100  * struct ast_bridge *bridge;
00101  * bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
00102  * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP, NULL, NULL, NULL);
00103  * \endcode
00104  *
00105  * This creates a no frills two party bridge that will be
00106  * destroyed once one of the channels hangs up.
00107  */
00108 struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags, const char *creator, const char *name, const char *id);
00109 
00110 /*!
00111  * \internal
00112  * \brief Move a bridge channel from one bridge to another.
00113  * \since 12.0.0
00114  *
00115  * \param dst_bridge Destination bridge of bridge channel move.
00116  * \param bridge_channel Channel moving from one bridge to another.
00117  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
00118  * \param optimized Indicates whether the move is part of an unreal channel optimization.
00119  *
00120  * \note A ref is not held by bridge_channel->swap when calling because the
00121  * move with swap happens immediately.
00122  *
00123  * \note The dst_bridge and bridge_channel->bridge are assumed already locked.
00124  *
00125  * \retval 0 on success.
00126  * \retval -1 on failure.
00127  */
00128 int bridge_do_move(struct ast_bridge *dst_bridge, struct ast_bridge_channel *bridge_channel,
00129       int attempt_recovery, unsigned int optimized);
00130 
00131 /*!
00132  * \internal
00133  * \brief Do the merge of two bridges.
00134  * \since 12.0.0
00135  *
00136  * \param dst_bridge Destination bridge of merge.
00137  * \param src_bridge Source bridge of merge.
00138  * \param kick_me Array of channels to kick from the bridges.
00139  * \param num_kick Number of channels in the kick_me array.
00140  * \param optimized Indicates whether the merge is part of an unreal channel optimization.
00141  *
00142  * \return Nothing
00143  *
00144  * \note The two bridges are assumed already locked.
00145  *
00146  * This moves the channels in src_bridge into the bridge pointed
00147  * to by dst_bridge.
00148  */
00149 void bridge_do_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge,
00150       struct ast_bridge_channel **kick_me, unsigned int num_kick, unsigned int optimized);
00151 
00152 /*!
00153  * \internal
00154  * \brief Helper function to find a bridge channel given a channel.
00155  *
00156  * \param bridge What to search
00157  * \param chan What to search for.
00158  *
00159  * \note On entry, bridge is already locked.
00160  *
00161  * \retval bridge_channel if channel is in the bridge.
00162  * \retval NULL if not in bridge.
00163  */
00164 struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct ast_channel *chan);
00165 
00166 /*!
00167  * \internal
00168  * \brief Adjust the bridge merge inhibit request count.
00169  * \since 12.0.0
00170  *
00171  * \param bridge What to operate on.
00172  * \param request Inhibit request increment.
00173  *     (Positive to add requests.  Negative to remove requests.)
00174  *
00175  * \note This function assumes bridge is locked.
00176  *
00177  * \return Nothing
00178  */
00179 void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
00180 
00181 /*!
00182  * \internal
00183  * \brief Notify the bridge that it has been reconfigured.
00184  * \since 12.0.0
00185  *
00186  * \param bridge Reconfigured bridge.
00187  * \param colp_update Whether to perform COLP updates.
00188  *
00189  * \details
00190  * After a series of bridge_channel_internal_push and
00191  * bridge_channel_internal_pull calls, you need to call this function
00192  * to cause the bridge to complete restructuring for the change
00193  * in the channel makeup of the bridge.
00194  *
00195  * \note On entry, the bridge is already locked.
00196  *
00197  * \return Nothing
00198  */
00199 void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
00200 
00201 /*!
00202  * \internal
00203  * \brief Dissolve the bridge.
00204  * \since 12.0.0
00205  *
00206  * \param bridge Bridge to eject all channels
00207  * \param cause Cause of bridge being dissolved.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
00208  *
00209  * \details
00210  * Force out all channels that are not already going out of the
00211  * bridge.  Any new channels joining will leave immediately.
00212  *
00213  * \note On entry, bridge is already locked.
00214  *
00215  * \return Nothing
00216  */
00217 void bridge_dissolve(struct ast_bridge *bridge, int cause);
00218 
00219 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */

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