Perform the initial renaming of the Bridging API
[asterisk/asterisk.git] / include / asterisk / features.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@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 Call Parking and Pickup API
21  * Includes code and algorithms from the Zapata library.
22  */
23
24 #ifndef _AST_FEATURES_H
25 #define _AST_FEATURES_H
26
27 #include "asterisk/pbx.h"
28 #include "asterisk/linkedlists.h"
29 #include "asterisk/bridging.h"
30
31 #define FEATURE_MAX_LEN         11
32 #define FEATURE_APP_LEN         64
33 #define FEATURE_APP_ARGS_LEN    256
34 #define FEATURE_SNAME_LEN       32
35 #define FEATURE_EXTEN_LEN       32
36 #define FEATURE_MOH_LEN         80  /* same as MAX_MUSICCLASS from channel.h */
37
38 #define DEFAULT_PARKINGLOT "default"    /*!< Default parking lot */
39
40 #define AST_FEATURE_RETURN_HANGUP           -1
41 #define AST_FEATURE_RETURN_SUCCESSBREAK     0
42 #define AST_FEATURE_RETURN_PBX_KEEPALIVE    AST_PBX_KEEPALIVE
43 #define AST_FEATURE_RETURN_NO_HANGUP_PEER   AST_PBX_NO_HANGUP_PEER
44 #define AST_FEATURE_RETURN_PASSDIGITS       21
45 #define AST_FEATURE_RETURN_STOREDIGITS      22
46 #define AST_FEATURE_RETURN_SUCCESS          23
47 #define AST_FEATURE_RETURN_KEEPTRYING       24
48 #define AST_FEATURE_RETURN_PARKFAILED       25
49
50 #define FEATURE_SENSE_CHAN      (1 << 0)
51 #define FEATURE_SENSE_PEER      (1 << 1)
52
53 typedef int (*ast_feature_operation)(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, const char *code, int sense, void *data);
54
55 /*! \brief main call feature structure */
56
57 enum {
58         AST_FEATURE_FLAG_NEEDSDTMF = (1 << 0),
59         AST_FEATURE_FLAG_ONPEER =    (1 << 1),
60         AST_FEATURE_FLAG_ONSELF =    (1 << 2),
61         AST_FEATURE_FLAG_BYCALLEE =  (1 << 3),
62         AST_FEATURE_FLAG_BYCALLER =  (1 << 4),
63         AST_FEATURE_FLAG_BYBOTH  =   (3 << 3),
64 };
65
66 /*!
67  * \brief Park a call and read back parked location
68  *
69  * \param park_me Channel to be parked.
70  * \param parker Channel parking the call.
71  * \param timeout is a timeout in milliseconds
72  * \param park_exten Parking lot access extension (Not used)
73  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
74  *
75  * \details
76  * Park the park_me channel, and read back the parked location
77  * to the parker channel.  If the call is not picked up within a
78  * specified period of time, then the call will return to the
79  * last step that it was in (in terms of exten, priority and
80  * context).
81  *
82  * \note Use ast_park_call_exten() instead.
83  *
84  * \retval 0 on success.
85  * \retval -1 on failure.
86  */
87 int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout);
88
89 /*!
90  * \brief Park a call and read back parked location
91  * \since 1.8.9
92  *
93  * \param park_me Channel to be parked.
94  * \param parker Channel parking the call.
95  * \param park_exten Parking lot access extension
96  * \param park_context Parking lot context
97  * \param timeout is a timeout in milliseconds
98  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
99  *
100  * \details
101  * Park the park_me channel, and read back the parked location
102  * to the parker channel.  If the call is not picked up within a
103  * specified period of time, then the call will return to the
104  * last step that it was in (in terms of exten, priority and
105  * context).
106  *
107  * \retval 0 on success.
108  * \retval -1 on failure.
109  */
110 int ast_park_call_exten(struct ast_channel *park_me, struct ast_channel *parker, const char *park_exten, const char *park_context, int timeout, int *extout);
111
112 /*!
113  * \brief Park a call via a masqueraded channel
114  *
115  * \param park_me Channel to be parked.
116  * \param parker Channel parking the call.
117  * \param timeout is a timeout in milliseconds
118  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
119  *
120  * \details
121  * Masquerade the park_me channel into a new, empty channel which is then parked.
122  *
123  * \note Use ast_masq_park_call_exten() instead.
124  *
125  * \retval 0 on success.
126  * \retval -1 on failure.
127  */
128 int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
129
130 /*!
131  * \brief Park a call via a masqueraded channel
132  * \since 1.8.9
133  *
134  * \param park_me Channel to be parked.
135  * \param parker Channel parking the call.
136  * \param park_exten Parking lot access extension
137  * \param park_context Parking lot context
138  * \param timeout is a timeout in milliseconds
139  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
140  *
141  * \details
142  * Masquerade the park_me channel into a new, empty channel which is then parked.
143  *
144  * \retval 0 on success.
145  * \retval -1 on failure.
146  */
147 int ast_masq_park_call_exten(struct ast_channel *park_me, struct ast_channel *parker, const char *park_exten, const char *park_context, int timeout, int *extout);
148
149 /*!
150  * \brief Determine if parking extension exists in a given context
151  * \retval 0 if extension does not exist
152  * \retval 1 if extension does exist
153 */
154 int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
155
156 /*! \brief Bridge a call, optionally allowing redirection */
157 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
158
159 /*!
160  * \brief Add an arbitrary channel to a bridge
161  * \since 12.0.0
162  *
163  * The channel that is being added to the bridge can be in any state: unbridged,
164  * bridged, answered, unanswered, etc. The channel will be added asynchronously,
165  * meaning that when this function returns once the channel has been added to
166  * the bridge, not once the channel has been removed from the bridge.
167  *
168  * In addition, a tone can optionally be played to the channel once the
169  * channel is placed into the bridge.
170  *
171  * \note When this function returns, there is no guarantee that the channel that
172  * was passed in is valid any longer. Do not attempt to operate on the channel
173  * after this function returns.
174  *
175  * \param bridge Bridge to which the channel should be added
176  * \param chan The channel to add to the bridge
177  * \param features Features for this channel in the bridge
178  * \param play_tone Indicates if a tone should be played to the channel
179  * \param xfersound Sound that should be used to indicate transfer with play_tone
180  * \retval 0 Success
181  * \retval -1 Failure
182  */
183 int ast_bridge_add_channel(struct ast_bridge *bridge, struct ast_channel *chan,
184                 struct ast_bridge_features *features, int play_tone, const char *xfersound);
185
186 /*!
187  * \brief Test if a channel can be picked up.
188  *
189  * \param chan Channel to test if can be picked up.
190  *
191  * \note This function assumes that chan is locked.
192  *
193  * \return TRUE if channel can be picked up.
194  */
195 int ast_can_pickup(struct ast_channel *chan);
196
197 /*!
198  * \brief Find a pickup channel target by group.
199  *
200  * \param chan channel that initiated pickup.
201  *
202  * \retval target on success.  The returned channel is locked and reffed.
203  * \retval NULL on error.
204  */
205 struct ast_channel *ast_pickup_find_by_group(struct ast_channel *chan);
206
207 /*! \brief Pickup a call */
208 int ast_pickup_call(struct ast_channel *chan);
209
210 /*!
211  * \brief Pickup a call target.
212  *
213  * \param chan channel that initiated pickup.
214  * \param target channel to be picked up.
215  *
216  * \note This function assumes that target is locked.
217  *
218  * \retval 0 on success.
219  * \retval -1 on failure.
220  */
221 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
222
223 /*!
224  * \brief accessor for call pickup message type
225  * \since 12.0.0
226  *
227  * \retval pointer to the stasis message type
228  * \retval NULL if not initialized
229  */
230 struct stasis_message_type *ast_call_pickup_type(void);
231
232 /*! \brief Reload call features from features.conf */
233 int ast_features_reload(void);
234
235 /*!
236  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
237  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
238 */
239 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
240
241 #endif /* _AST_FEATURES_H */