Merge phase 1 support for the new bridging architecture.
[asterisk/asterisk.git] / include / asterisk / bridging_features.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@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 /*! \file
20  * \brief Channel Bridging API
21  * \author Joshua Colp <jcolp@digium.com>
22  */
23
24 #ifndef _ASTERISK_BRIDGING_FEATURES_H
25 #define _ASTERISK_BRIDGING_FEATURES_H
26
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30
31 /*! \brief Flags used for bridge features */
32 enum ast_bridge_feature_flags {
33         /*! Upon hangup the bridge should be discontinued */
34         AST_BRIDGE_FLAG_DISSOLVE = (1 << 0),
35         /*! Move between bridging technologies as needed. */
36         AST_BRIDGE_FLAG_SMART = (1 << 1),
37 };
38
39 /*! \brief Built in features */
40 enum ast_bridge_builtin_feature {
41         /*! DTMF Based Blind Transfer */
42         AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0,
43         /*! DTMF Based Attended Transfer */
44         AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
45         /*! DTMF Based Hangup Feature */
46         AST_BRIDGE_BUILTIN_HANGUP,
47         /*! End terminator for list of built in features. Must remain last. */
48         AST_BRIDGE_BUILTIN_END,
49 };
50
51 struct ast_bridge;
52 struct ast_bridge_channel;
53
54 /*!
55  * \brief Features hook callback type
56  *
57  * \param bridge The bridge that the channel is part of
58  * \param bridge_channel Channel executing the feature
59  * \param hook_pvt Private data passed in when the hook was created
60  *
61  * \retval 0 success
62  * \retval -1 failure
63  */
64 typedef int (*ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt);
65
66 /*!
67  * \brief Maximum length of a DTMF feature string
68  */
69 #define MAXIMUM_DTMF_FEATURE_STRING 8
70
71 /*!
72  * \brief Structure that is the essence of a features hook
73  */
74 struct ast_bridge_features_hook {
75         /*! DTMF String that is examined during a feature hook lookup */
76         char dtmf[MAXIMUM_DTMF_FEATURE_STRING];
77         /*! Callback that is called when DTMF string is matched */
78         ast_bridge_features_hook_callback callback;
79         /*! Unique data that was passed into us */
80         void *hook_pvt;
81         /*! Linked list information */
82         AST_LIST_ENTRY(ast_bridge_features_hook) entry;
83 };
84
85 /*!
86  * \brief Structure that contains features information
87  */
88 struct ast_bridge_features {
89         /*! Attached DTMF based feature hooks */
90         AST_LIST_HEAD_NOLOCK(, ast_bridge_features_hook) hooks;
91         /*! Feature flags that are enabled */
92         struct ast_flags feature_flags;
93         /*! Bit to indicate that this structure is useful and should be considered when looking for features */
94         unsigned int usable:1;
95         /*! Bit to indicate whether the channel/bridge is muted or not */
96         unsigned int mute:1;
97 };
98
99 /*!
100  * \brief Structure that contains configuration information for the blind transfer built in feature
101  */
102 struct ast_bridge_features_blind_transfer {
103         /*! Context to use for transfers */
104         char context[AST_MAX_CONTEXT];
105 };
106
107 /*!
108  * \brief Structure that contains configuration information for the attended transfer built in feature
109  */
110 struct ast_bridge_features_attended_transfer {
111         /*! DTMF string used to abort the transfer */
112         char abort[MAXIMUM_DTMF_FEATURE_STRING];
113         /*! DTMF string used to turn the transfer into a three way conference */
114         char threeway[MAXIMUM_DTMF_FEATURE_STRING];
115         /*! DTMF string used to complete the transfer */
116         char complete[MAXIMUM_DTMF_FEATURE_STRING];
117         /*! Context to use for transfers */
118         char context[AST_MAX_CONTEXT];
119 };
120
121 /*! \brief Register a handler for a built in feature
122  *
123  * \param feature The feature that the handler will be responsible for
124  * \param callback The callback function that will handle it
125  * \param dtmf Default DTMF string used to activate the feature
126  *
127  * \retval 0 on success
128  * \retval -1 on failure
129  *
130  * Example usage:
131  *
132  * \code
133  * ast_bridge_features_register(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER, bridge_builtin_attended_transfer, "*1");
134  * \endcode
135  *
136  * This registers the function bridge_builtin_attended_transfer as the function responsible for the built in
137  * attended transfer feature.
138  */
139 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf);
140
141 /*! \brief Unregister a handler for a built in feature
142  *
143  * \param feature The feature to unregister
144  *
145  * \retval 0 on success
146  * \retval -1 on failure
147  *
148  * Example usage:
149  *
150  * \code
151  * ast_bridge_features_unregister(AST_BRIDGE_BUILTIN_ATTENDED_TRANSFER);
152  * \endcode
153  *
154  * This unregisters the function that is handling the built in attended transfer feature.
155  */
156 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
157
158 /*! \brief Attach a custom hook to a bridge features structure
159  *
160  * \param features Bridge features structure
161  * \param dtmf DTMF string to be activated upon
162  * \param callback Function to execute upon activation
163  * \param hook_pvt Unique data
164  *
165  * \retval 0 on success
166  * \retval -1 on failure
167  *
168  * Example usage:
169  *
170  * \code
171  * struct ast_bridge_features features;
172  * ast_bridge_features_init(&features);
173  * ast_bridge_features_hook(&features, "#", pound_callback, NULL);
174  * \endcode
175  *
176  * This makes the bridging core call pound_callback if a channel that has this
177  * feature structure inputs the DTMF string '#'. A pointer to useful data may be
178  * provided to the hook_pvt parameter.
179  *
180  * \note It is important that the callback set the bridge channel state back to
181  *       AST_BRIDGE_CHANNEL_STATE_WAIT or the bridge thread will not service the channel.
182  */
183 int ast_bridge_features_hook(struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt);
184
185 /*! \brief Enable a built in feature on a bridge features structure
186  *
187  * \param features Bridge features structure
188  * \param feature Feature to enable
189  * \param dtmf Optionally the DTMF stream to trigger the feature, if not specified it will be the default
190  * \param config Configuration structure unique to the built in type
191  *
192  * \retval 0 on success
193  * \retval -1 on failure
194  *
195  * Example usage:
196  *
197  * \code
198  * struct ast_bridge_features features;
199  * ast_bridge_features_init(&features);
200  * ast_bridge_features_enable(&features, AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER, NULL);
201  * \endcode
202  *
203  * This enables the attended transfer DTMF option using the default DTMF string. An alternate
204  * string may be provided using the dtmf parameter. Internally this is simply setting up a hook
205  * to a built in feature callback function.
206  */
207 int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config);
208
209 /*! \brief Set a flag on a bridge features structure
210  *
211  * \param features Bridge features structure
212  * \param flag Flag to enable
213  *
214  * \retval 0 on success
215  * \retval -1 on failure
216  *
217  * Example usage:
218  *
219  * \code
220  * struct ast_bridge_features features;
221  * ast_bridge_features_init(&features);
222  * ast_bridge_features_set_flag(&features, AST_BRIDGE_FLAG_DISSOLVE);
223  * \endcode
224  *
225  * This sets the AST_BRIDGE_FLAG_DISSOLVE feature to be enabled on the features structure
226  * 'features'.
227  */
228 int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag);
229
230 /*! \brief Initialize bridge features structure
231  *
232  * \param features Bridge featues structure
233  *
234  * \retval 0 on success
235  * \retval -1 on failure
236  *
237  * Example usage:
238  *
239  * \code
240  * struct ast_bridge_features features;
241  * ast_bridge_features_init(&features);
242  * \endcode
243  *
244  * This initializes the feature structure 'features' to have nothing enabled.
245  *
246  * \note This MUST be called before enabling features or flags. Failure to do so
247  *       may result in a crash.
248  */
249 int ast_bridge_features_init(struct ast_bridge_features *features);
250
251 /*! \brief Clean up the contents of a bridge features structure
252  *
253  * \param features Bridge features structure
254  *
255  * \retval 0 on success
256  * \retval -1 on failure
257  *
258  * Example usage:
259  *
260  * \code
261  * struct ast_bridge_features features;
262  * ast_bridge_features_init(&features);
263  * ast_bridge_features_cleanup(&features);
264  * \endcode
265  *
266  * This cleans up the feature structure 'features'.
267  *
268  * \note This MUST be called after the features structure is done being used
269  *       or a memory leak may occur.
270  */
271 int ast_bridge_features_cleanup(struct ast_bridge_features *features);
272
273 /*! \brief Play a DTMF stream into a bridge, optionally not to a given channel
274  *
275  * \param bridge Bridge to play stream into
276  * \param dtmf DTMF to play
277  * \param chan Channel to optionally not play to
278  *
279  * \retval 0 on success
280  * \retval -1 on failure
281  *
282  * Example usage:
283  *
284  * \code
285  * ast_bridge_dtmf_stream(bridge, "0123456789", NULL);
286  * \endcode
287  *
288  * This sends the DTMF digits '0123456789' to all channels in the bridge pointed to
289  * by the bridge pointer. Optionally a channel may be excluded by passing it's channel pointer
290  * using the chan parameter.
291  */
292 int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan);
293
294 #if defined(__cplusplus) || defined(c_plusplus)
295 }
296 #endif
297
298 #endif /* _ASTERISK_BRIDGING_FEATURES_H */