include/asterisk/bridge_internal.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2013 Digium, Inc.
   5  *
   6  * Mark Michelson <mmichelson@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*!
  20  * \file
  21  * \brief Private Bridging API
  22  *
  23  * Functions in this file are intended to be used by the Bridging API,
  24  * bridge mixing technologies, and bridge sub-classes. Users of bridges
  25  * that do not fit those three categories should *not* use the API
  26  * defined in this file.
  27  *
  28  * \author Mark Michelson <mmichelson@digium.com>
  29  *
  30  * See Also:
  31  * \arg \ref AstCREDITS
  32  */
  33
  34 #ifndef _ASTERISK_PRIVATE_BRIDGING_H
  35 #define _ASTERISK_PRIVATE_BRIDGING_H
  36
  37 struct ast_bridge;
  38 struct ast_bridge_channel;
  39 struct ast_bridge_methods;
  40
  41 /*!
  42  * \brief Register the new bridge with the system.
  43  * \since 12.0.0
  44  *
  45  * \param bridge What to register. (Tolerates a NULL pointer)
  46  *
  47  * \code
  48  * struct ast_bridge *ast_bridge_basic_new(uint32_t capabilities, int flags, uint32 dtmf_features)
  49  * {
  50  *     void *bridge;
  51  *
  52  *     bridge = bridge_alloc(sizeof(struct ast_bridge_basic), &ast_bridge_basic_v_table);
  53  *     bridge = bridge_base_init(bridge, capabilities, flags);
  54  *     bridge = ast_bridge_basic_init(bridge, dtmf_features);
  55  *     bridge = bridge_register(bridge);
  56  *     return bridge;
  57  * }
  58  * \endcode
  59  *
  60  * \note This must be done after a bridge constructor has
  61  * completed setting up the new bridge but before it returns.
  62  *
  63  * \note After a bridge is registered, ast_bridge_destroy() must
  64  * eventually be called to get rid of the bridge.
  65  *
  66  * \retval bridge on success.
  67  * \retval NULL on error.
  68  */
  69 struct ast_bridge *bridge_register(struct ast_bridge *bridge);
  70
  71 /*!
  72  * \internal
  73  * \brief Allocate the bridge class object memory.
  74  * \since 12.0.0
  75  *
  76  * \param size Size of the bridge class structure to allocate.
  77  * \param v_table Bridge class virtual method table.
  78  *
  79  * \retval bridge on success.
  80  * \retval NULL on error.
  81  */
  82 struct ast_bridge *bridge_alloc(size_t size, const struct ast_bridge_methods *v_table);
  83
  84 /*!
  85  * \brief Initialize the base class of the bridge.
  86  *
  87  * \param self Bridge to operate upon. (Tolerates a NULL pointer)
  88  * \param capabilities The capabilities that we require to be used on the bridge
  89  * \param flags Flags that will alter the behavior of the bridge
  90  *
  91  * \retval self on success
  92  * \retval NULL on failure, self is already destroyed
  93  *
  94  * Example usage:
  95  *
  96  * \code
  97  * struct ast_bridge *bridge;
  98  * bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
  99  * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP);
 100  * \endcode
 101  *
 102  * This creates a no frills two party bridge that will be
 103  * destroyed once one of the channels hangs up.
 104  */
 105 struct ast_bridge *bridge_base_init(struct ast_bridge *self, uint32_t capabilities, unsigned int flags);
 106
 107 /*!
 108  * \internal
 109  * \brief Move a bridge channel from one bridge to another.
 110  * \since 12.0.0
 111  *
 112  * \param dst_bridge Destination bridge of bridge channel move.
 113  * \param bridge_channel Channel moving from one bridge to another.
 114  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
 115  * \param optimized Indicates whether the move is part of an unreal channel optimization.
 116  *
 117  * \note The dst_bridge and bridge_channel->bridge are assumed already locked.
 118  *
 119  * \retval 0 on success.
 120  * \retval -1 on failure.
 121  */
 122 int bridge_do_move(struct ast_bridge *dst_bridge, struct ast_bridge_channel *bridge_channel,
 123                 int attempt_recovery, unsigned int optimized);
 124
 125 /*!
 126  * \internal
 127  * \brief Do the merge of two bridges.
 128  * \since 12.0.0
 129  *
 130  * \param dst_bridge Destination bridge of merge.
 131  * \param src_bridge Source bridge of merge.
 132  * \param kick_me Array of channels to kick from the bridges.
 133  * \param num_kick Number of channels in the kick_me array.
 134  * \param optimized Indicates whether the merge is part of an unreal channel optimization.
 135  *
 136  * \return Nothing
 137  *
 138  * \note The two bridges are assumed already locked.
 139  *
 140  * This moves the channels in src_bridge into the bridge pointed
 141  * to by dst_bridge.
 142  */
 143 void bridge_do_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge,
 144                 struct ast_bridge_channel **kick_me, unsigned int num_kick, unsigned int optimized);
 145
 146 /*!
 147  * \internal
 148  * \brief Helper function to find a bridge channel given a channel.
 149  *
 150  * \param bridge What to search
 151  * \param chan What to search for.
 152  *
 153  * \note On entry, bridge is already locked.
 154  *
 155  * \retval bridge_channel if channel is in the bridge.
 156  * \retval NULL if not in bridge.
 157  */
 158 struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct ast_channel *chan);
 159
 160 /*!
 161  * \internal
 162  * \brief Adjust the bridge merge inhibit request count.
 163  * \since 12.0.0
 164  *
 165  * \param bridge What to operate on.
 166  * \param request Inhibit request increment.
 167  *     (Positive to add requests.  Negative to remove requests.)
 168  *
 169  * \note This function assumes bridge is locked.
 170  *
 171  * \return Nothing
 172  */
 173 void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
 174
 175 /*!
 176  * \internal
 177  * \brief Notify the bridge that it has been reconfigured.
 178  * \since 12.0.0
 179  *
 180  * \param bridge Reconfigured bridge.
 181  * \param colp_update Whether to perform COLP updates.
 182  *
 183  * \details
 184  * After a series of bridge_channel_internal_push and
 185  * bridge_channel_internal_pull calls, you need to call this function
 186  * to cause the bridge to complete restructuring for the change
 187  * in the channel makeup of the bridge.
 188  *
 189  * \note On entry, the bridge is already locked.
 190  *
 191  * \return Nothing
 192  */
 193 void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
 194
 195 /*!
 196  * \internal
 197  * \brief Dissolve the bridge.
 198  * \since 12.0.0
 199  *
 200  * \param bridge Bridge to eject all channels
 201  * \param cause Cause of bridge being dissolved.  (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
 202  *
 203  * \details
 204  * Force out all channels that are not already going out of the
 205  * bridge.  Any new channels joining will leave immediately.
 206  *
 207  * \note On entry, bridge is already locked.
 208  *
 209  * \return Nothing
 210  */
 211 void bridge_dissolve(struct ast_bridge *bridge, int cause);
 212
 213 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */