Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


bridging_features.h
Go to the documentation of this file.
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 */
33  /*! Upon hangup the bridge should be discontinued */
35  /*! Move between bridging technologies as needed. */
37 };
38 
39 /*! \brief Built in features */
41  /*! DTMF Based Blind Transfer */
43  /*! DTMF Based Attended Transfer */
45  /*! DTMF Based Hangup Feature */
47  /*! End terminator for list of built in features. Must remain last. */
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  */
75  /*! DTMF String that is examined during a feature hook lookup */
77  /*! Callback that is called when DTMF string is matched */
79  /*! Unique data that was passed into us */
80  void *hook_pvt;
81  /*! Linked list information */
83 };
84 
85 /*!
86  * \brief Structure that contains features information
87  */
89  /*! Attached DTMF based feature 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  */
103  /*! Context to use for transfers */
105 };
106 
107 /*!
108  * \brief Structure that contains configuration information for the attended transfer built in feature
109  */
111  /*! DTMF string used to abort the transfer */
113  /*! DTMF string used to turn the transfer into a three way conference */
115  /*! DTMF string used to complete the transfer */
117  /*! Context to use for transfers */
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  */
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  */
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  */
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  */
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  */
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 */
int(* ast_bridge_features_hook_callback)(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt)
Features hook callback type.
Main Channel structure associated with a channel.
Definition: channel.h:742
static const char config[]
Definition: cdr_csv.c:57
Structure that contains features information.
int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config)
Enable a built in feature on a bridge features structure.
Definition: bridging.c:1295
int ast_bridge_features_init(struct ast_bridge_features *features)
Initialize bridge features structure.
Definition: bridging.c:1322
int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature)
Unregister a handler for a built in feature.
Definition: bridging.c:1263
static int mute
Definition: chan_alsa.c:135
char dtmf[MAXIMUM_DTMF_FEATURE_STRING]
int ast_bridge_features_hook(struct ast_bridge_features *features, const char *dtmf, ast_bridge_features_hook_callback callback, void *hook_pvt)
Attach a custom hook to a bridge features structure.
Definition: bridging.c:1274
#define MAXIMUM_DTMF_FEATURE_STRING
Maximum length of a DTMF feature string.
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:224
Structure that contains information about a bridge.
Definition: bridging.h:149
#define AST_MAX_CONTEXT
Definition: channel.h:136
Structure used to handle boolean flags.
Definition: utils.h:200
Structure that contains configuration information for the attended transfer built in feature...
Structure that contains information regarding a channel in a bridge.
Definition: bridging.h:117
AST_LIST_ENTRY(ast_bridge_features_hook) entry
ast_bridge_feature_flags
Flags used for bridge features.
ast_bridge_features_hook_callback callback
Structure that is the essence of a features hook.
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:107
int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf)
Register a handler for a built in feature.
Definition: bridging.c:1248
Structure that contains configuration information for the blind transfer built in feature...
int ast_bridge_dtmf_stream(struct ast_bridge *bridge, const char *dtmf, struct ast_channel *chan)
Play a DTMF stream into a bridge, optionally not to a given channel.
Definition: bridging.c:1345
int ast_bridge_features_cleanup(struct ast_bridge_features *features)
Clean up the contents of a bridge features structure.
Definition: bridging.c:1333
ast_bridge_builtin_feature
Built in features.
int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag)
Set a flag on a bridge features structure.
Definition: bridging.c:1315