Asterisk - The Open Source Telephony Project  21.4.1
bridge_internal.h
Go to the documentation of this file.
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  * \return 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  * \return 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  * \param creator Entity that created the bridge (optional)
91  * \param name Name given to the bridge by its creator (optional, requires named creator)
92  * \param id Unique ID given to the bridge by its creator (optional)
93  *
94  * \return self on success
95  * \retval NULL on failure, self is already destroyed
96  *
97  * Example usage:
98  *
99  * \code
100  * struct ast_bridge *bridge;
101  * bridge = bridge_alloc(sizeof(*bridge), &ast_bridge_base_v_table);
102  * bridge = bridge_base_init(bridge, AST_BRIDGE_CAPABILITY_1TO1MIX, AST_BRIDGE_FLAG_DISSOLVE_HANGUP, NULL, NULL, NULL);
103  * \endcode
104  *
105  * This creates a no frills two party bridge that will be
106  * destroyed once one of the channels hangs up.
107  */
108 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);
109 
110 /*!
111  * \internal
112  * \brief Move a bridge channel from one bridge to another.
113  * \since 12.0.0
114  *
115  * \param dst_bridge Destination bridge of bridge channel move.
116  * \param bridge_channel Channel moving from one bridge to another.
117  * \param attempt_recovery TRUE if failure attempts to push channel back into original bridge.
118  * \param optimized Indicates whether the move is part of an unreal channel optimization.
119  *
120  * \note A ref is not held by bridge_channel->swap when calling because the
121  * move with swap happens immediately.
122  *
123  * \note The dst_bridge and bridge_channel->bridge are assumed already locked.
124  *
125  * \retval 0 on success.
126  * \retval -1 on failure.
127  */
128 int bridge_do_move(struct ast_bridge *dst_bridge, struct ast_bridge_channel *bridge_channel,
129  int attempt_recovery, unsigned int optimized);
130 
131 /*!
132  * \internal
133  * \brief Do the merge of two bridges.
134  * \since 12.0.0
135  *
136  * \param dst_bridge Destination bridge of merge.
137  * \param src_bridge Source bridge of merge.
138  * \param kick_me Array of channels to kick from the bridges.
139  * \param num_kick Number of channels in the kick_me array.
140  * \param optimized Indicates whether the merge is part of an unreal channel optimization.
141  *
142  * \note The two bridges are assumed already locked.
143  *
144  * This moves the channels in src_bridge into the bridge pointed
145  * to by dst_bridge.
146  */
147 void bridge_do_merge(struct ast_bridge *dst_bridge, struct ast_bridge *src_bridge,
148  struct ast_bridge_channel **kick_me, unsigned int num_kick, unsigned int optimized);
149 
150 /*!
151  * \internal
152  * \brief Helper function to find a bridge channel given a channel.
153  *
154  * \param bridge What to search
155  * \param chan What to search for.
156  *
157  * \note On entry, bridge is already locked.
158  *
159  * \return bridge_channel if channel is in the bridge.
160  * \retval NULL if not in bridge.
161  */
162 struct ast_bridge_channel *bridge_find_channel(struct ast_bridge *bridge, struct ast_channel *chan);
163 
164 /*!
165  * \internal
166  * \brief Adjust the bridge merge inhibit request count.
167  * \since 12.0.0
168  *
169  * \param bridge What to operate on.
170  * \param request Inhibit request increment.
171  * (Positive to add requests. Negative to remove requests.)
172  *
173  * \note This function assumes bridge is locked.
174  */
175 void bridge_merge_inhibit_nolock(struct ast_bridge *bridge, int request);
176 
177 /*!
178  * \internal
179  * \brief Notify the bridge that it has been reconfigured.
180  * \since 12.0.0
181  *
182  * \param bridge Reconfigured bridge.
183  * \param colp_update Whether to perform COLP updates.
184  *
185  * After a series of bridge_channel_internal_push and
186  * bridge_channel_internal_pull calls, you need to call this function
187  * to cause the bridge to complete restructuring for the change
188  * in the channel makeup of the bridge.
189  *
190  * \note On entry, the bridge is already locked.
191  */
192 void bridge_reconfigured(struct ast_bridge *bridge, unsigned int colp_update);
193 
194 /*!
195  * \internal
196  * \brief Dissolve the bridge.
197  * \since 12.0.0
198  *
199  * \param bridge Bridge to eject all channels
200  * \param cause Cause of bridge being dissolved. (If cause <= 0 then use AST_CAUSE_NORMAL_CLEARING)
201  *
202  * \details
203  * Force out all channels that are not already going out of the
204  * bridge. Any new channels joining will leave immediately.
205  *
206  * \note On entry, bridge is already locked.
207  */
208 void bridge_dissolve(struct ast_bridge *bridge, int cause);
209 
210 #endif /* _ASTERISK_PRIVATE_BRIDGING_H */
Main Channel structure associated with a channel.
struct ast_bridge * bridge_register(struct ast_bridge *bridge)
Register the new bridge with the system.
Definition: bridge.c:691
const ast_string_field name
Definition: bridge.h:401
struct ast_bridge * bridge
Bridge this channel is participating in.
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)
Initialize the base class of the bridge.
Definition: bridge.c:742
const struct ast_bridge_methods * v_table
Definition: bridge.h:351
Structure that contains information about a bridge.
Definition: bridge.h:349
Bridge virtual methods table definition.
Definition: bridge.h:257
struct ast_channel * chan
Structure that contains information regarding a channel in a bridge.
const ast_string_field creator
Definition: bridge.h:401