More parking issues.
[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
30 #define FEATURE_MAX_LEN         11
31 #define FEATURE_APP_LEN         64
32 #define FEATURE_APP_ARGS_LEN    256
33 #define FEATURE_SNAME_LEN       32
34 #define FEATURE_EXTEN_LEN       32
35 #define FEATURE_MOH_LEN         80  /* same as MAX_MUSICCLASS from channel.h */
36
37 #define PARK_APP_NAME "Park"
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 struct ast_call_feature {
67         int feature_mask;
68         char *fname;
69         char sname[FEATURE_SNAME_LEN];
70         char exten[FEATURE_MAX_LEN];
71         char default_exten[FEATURE_MAX_LEN];
72         ast_feature_operation operation;
73         unsigned int flags;
74         char app[FEATURE_APP_LEN];              
75         char app_args[FEATURE_APP_ARGS_LEN];
76         char moh_class[FEATURE_MOH_LEN];
77         AST_LIST_ENTRY(ast_call_feature) feature_entry;
78 };
79
80 /*!
81  * \brief Park a call and read back parked location
82  *
83  * \param park_me Channel to be parked.
84  * \param parker Channel parking the call.
85  * \param timeout is a timeout in milliseconds
86  * \param park_exten Parking lot access extension (Not used)
87  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
88  *
89  * \details
90  * Park the park_me channel, and read back the parked location
91  * to the parker channel.  If the call is not picked up within a
92  * specified period of time, then the call will return to the
93  * last step that it was in (in terms of exten, priority and
94  * context).
95  *
96  * \note Use ast_park_call_exten() instead.
97  *
98  * \retval 0 on success.
99  * \retval -1 on failure.
100  */
101 int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout);
102
103 /*!
104  * \brief Park a call and read back parked location
105  * \since 1.8.9
106  *
107  * \param park_me Channel to be parked.
108  * \param parker Channel parking the call.
109  * \param park_exten Parking lot access extension
110  * \param park_context Parking lot context
111  * \param timeout is a timeout in milliseconds
112  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
113  *
114  * \details
115  * Park the park_me channel, and read back the parked location
116  * to the parker channel.  If the call is not picked up within a
117  * specified period of time, then the call will return to the
118  * last step that it was in (in terms of exten, priority and
119  * context).
120  *
121  * \retval 0 on success.
122  * \retval -1 on failure.
123  */
124 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);
125
126 /*!
127  * \brief Park a call via a masqueraded channel
128  *
129  * \param park_me Channel to be parked.
130  * \param parker Channel parking the call.
131  * \param timeout is a timeout in milliseconds
132  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
133  *
134  * \details
135  * Masquerade the park_me channel into a new, empty channel which is then parked.
136  *
137  * \note Use ast_masq_park_call_exten() instead.
138  *
139  * \retval 0 on success.
140  * \retval -1 on failure.
141  */
142 int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
143
144 /*!
145  * \brief Park a call via a masqueraded channel
146  * \since 1.8.9
147  *
148  * \param park_me Channel to be parked.
149  * \param parker Channel parking the call.
150  * \param park_exten Parking lot access extension
151  * \param park_context Parking lot context
152  * \param timeout is a timeout in milliseconds
153  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
154  *
155  * \details
156  * Masquerade the park_me channel into a new, empty channel which is then parked.
157  *
158  * \retval 0 on success.
159  * \retval -1 on failure.
160  */
161 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);
162
163 /*! 
164  * \brief Determine if parking extension exists in a given context
165  * \retval 0 if extension does not exist
166  * \retval 1 if extension does exist
167 */
168 int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
169
170 /*! \brief Determine system call pickup extension */
171 const char *ast_pickup_ext(void);
172
173 /*! \brief Bridge a call, optionally allowing redirection */
174 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
175
176 /*!
177  * \brief Test if a channel can be picked up.
178  *
179  * \param chan Channel to test if can be picked up.
180  *
181  * \note This function assumes that chan is locked.
182  *
183  * \return TRUE if channel can be picked up.
184  */
185 int ast_can_pickup(struct ast_channel *chan);
186
187 /*! \brief Pickup a call */
188 int ast_pickup_call(struct ast_channel *chan);
189
190 /*!
191  * \brief Pickup a call target.
192  *
193  * \param chan channel that initiated pickup.
194  * \param target channel to be picked up.
195  *
196  * \note This function assumes that target is locked.
197  *
198  * \retval 0 on success.
199  * \retval -1 on failure.
200  */
201 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
202
203 /*! 
204  * \brief register new feature into feature_set 
205  * \param feature an ast_call_feature object which contains a keysequence
206  * and a callback function which is called when this keysequence is pressed
207  * during a call. 
208 */
209 void ast_register_feature(struct ast_call_feature *feature);
210
211 /*! 
212  * \brief unregister feature from feature_set
213  * \param feature the ast_call_feature object which was registered before
214 */
215 void ast_unregister_feature(struct ast_call_feature *feature);
216
217 /*! 
218  * \brief detect a feature before bridging 
219  * \param chan
220  * \param features an ast_flags ptr
221  * \param code ptr of input code
222  * \param feature
223  * \retval ast_call_feature ptr to be set if found 
224 */
225 int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
226
227 /*! 
228  * \brief look for a call feature entry by its sname
229  * \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. 
230 */
231 struct ast_call_feature *ast_find_call_feature(const char *name);
232
233 void ast_rdlock_call_features(void);
234 void ast_unlock_call_features(void);
235
236 /*! \brief Reload call features from features.conf */
237 int ast_features_reload(void);
238
239 /*!
240  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
241  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
242 */
243 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
244
245 #endif /* _AST_FEATURES_H */