Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


features.h
Go to the documentation of this file.
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 DEFAULT_PARKINGLOT "default" /*!< Default parking lot */
38 
39 #define AST_FEATURE_RETURN_HANGUP -1
40 #define AST_FEATURE_RETURN_SUCCESSBREAK 0
41 #define AST_FEATURE_RETURN_PBX_KEEPALIVE AST_PBX_KEEPALIVE
42 #define AST_FEATURE_RETURN_NO_HANGUP_PEER AST_PBX_NO_HANGUP_PEER
43 #define AST_FEATURE_RETURN_PASSDIGITS 21
44 #define AST_FEATURE_RETURN_STOREDIGITS 22
45 #define AST_FEATURE_RETURN_SUCCESS 23
46 #define AST_FEATURE_RETURN_KEEPTRYING 24
47 #define AST_FEATURE_RETURN_PARKFAILED 25
48 
49 #define FEATURE_SENSE_CHAN (1 << 0)
50 #define FEATURE_SENSE_PEER (1 << 1)
51 
52 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);
53 
54 /*! \brief main call feature structure */
55 
56 enum {
63 };
64 
67  char *fname;
72  unsigned int flags;
77 };
78 
79 /*!
80  * \brief Park a call and read back parked location
81  *
82  * \param park_me Channel to be parked.
83  * \param parker Channel parking the call.
84  * \param timeout is a timeout in milliseconds
85  * \param park_exten Parking lot access extension (Not used)
86  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
87  *
88  * \details
89  * Park the park_me channel, and read back the parked location
90  * to the parker channel. If the call is not picked up within a
91  * specified period of time, then the call will return to the
92  * last step that it was in (in terms of exten, priority and
93  * context).
94  *
95  * \note Use ast_park_call_exten() instead.
96  *
97  * \retval 0 on success.
98  * \retval -1 on failure.
99  */
100 int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout);
101 
102 /*!
103  * \brief Park a call and read back parked location
104  * \since 1.8.9
105  *
106  * \param park_me Channel to be parked.
107  * \param parker Channel parking the call.
108  * \param park_exten Parking lot access extension
109  * \param park_context Parking lot context
110  * \param timeout is a timeout in milliseconds
111  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
112  *
113  * \details
114  * Park the park_me channel, and read back the parked location
115  * to the parker channel. If the call is not picked up within a
116  * specified period of time, then the call will return to the
117  * last step that it was in (in terms of exten, priority and
118  * context).
119  *
120  * \retval 0 on success.
121  * \retval -1 on failure.
122  */
123 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);
124 
125 /*!
126  * \brief Park a call via a masqueraded channel
127  *
128  * \param park_me Channel to be parked.
129  * \param parker Channel parking the call.
130  * \param timeout is a timeout in milliseconds
131  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
132  *
133  * \details
134  * Masquerade the park_me channel into a new, empty channel which is then parked.
135  *
136  * \note Use ast_masq_park_call_exten() instead.
137  *
138  * \retval 0 on success.
139  * \retval -1 on failure.
140  */
141 int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
142 
143 /*!
144  * \brief Park a call via a masqueraded channel
145  * \since 1.8.9
146  *
147  * \param park_me Channel to be parked.
148  * \param parker Channel parking the call.
149  * \param park_exten Parking lot access extension
150  * \param park_context Parking lot context
151  * \param timeout is a timeout in milliseconds
152  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
153  *
154  * \details
155  * Masquerade the park_me channel into a new, empty channel which is then parked.
156  *
157  * \retval 0 on success.
158  * \retval -1 on failure.
159  */
160 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);
161 
162 /*!
163  * \brief Determine if parking extension exists in a given context
164  * \retval 0 if extension does not exist
165  * \retval 1 if extension does exist
166 */
167 int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
168 
169 /*! \brief Determine system call pickup extension */
170 const char *ast_pickup_ext(void);
171 
172 /*!
173  * \brief Simulate a DTMF end on a broken bridge channel.
174  *
175  * \param chan Channel sending DTMF that has not ended.
176  * \param digit DTMF digit to stop.
177  * \param start DTMF digit start time.
178  * \param why Reason bridge broken.
179  *
180  * \return Nothing
181  */
182 void ast_bridge_end_dtmf(struct ast_channel *chan, char digit, struct timeval start, const char *why);
183 
184 /*! \brief Bridge a call, optionally allowing redirection */
185 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
186 
187 /*!
188  * \brief Test if a channel can be picked up.
189  *
190  * \param chan Channel to test if can be picked up.
191  *
192  * \note This function assumes that chan is locked.
193  *
194  * \return TRUE if channel can be picked up.
195  */
196 int ast_can_pickup(struct ast_channel *chan);
197 
198 /*! \brief Pickup a call */
199 int ast_pickup_call(struct ast_channel *chan);
200 
201 /*!
202  * \brief Pickup a call target.
203  *
204  * \param chan channel that initiated pickup.
205  * \param target channel to be picked up.
206  *
207  * \note This function assumes that target is locked.
208  *
209  * \retval 0 on success.
210  * \retval -1 on failure.
211  */
212 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
213 
214 /*!
215  * \brief register new feature into feature_set
216  * \param feature an ast_call_feature object which contains a keysequence
217  * and a callback function which is called when this keysequence is pressed
218  * during a call.
219 */
220 void ast_register_feature(struct ast_call_feature *feature);
221 
222 /*!
223  * \brief unregister feature from feature_set
224  * \param feature the ast_call_feature object which was registered before
225 */
226 void ast_unregister_feature(struct ast_call_feature *feature);
227 
228 /*!
229  * \brief detect a feature before bridging
230  * \param chan
231  * \param features an ast_flags ptr
232  * \param code ptr of input code
233  * \param feature
234  * \retval ast_call_feature ptr to be set if found
235 */
236 int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
237 
238 /*!
239  * \brief look for a call feature entry by its sname
240  * \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc.
241 */
242 struct ast_call_feature *ast_find_call_feature(const char *name);
243 
244 void ast_rdlock_call_features(void);
245 void ast_unlock_call_features(void);
246 
247 /*! \brief Reload call features from features.conf */
248 int ast_features_reload(void);
249 
250 /*!
251  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
252  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
253 */
254 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
255 
256 #endif /* _AST_FEATURES_H */
char exten[FEATURE_MAX_LEN]
Definition: features.h:69
void ast_bridge_end_dtmf(struct ast_channel *chan, char digit, struct timeval start, const char *why)
Simulate a DTMF end on a broken bridge channel.
Definition: features.c:3927
Main Channel structure associated with a channel.
Definition: channel.h:742
static const char config[]
Definition: cdr_csv.c:57
int(* ast_feature_operation)(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, const char *code, int sense, void *data)
Definition: features.h:52
void ast_unregister_feature(struct ast_call_feature *feature)
unregister feature from feature_set
Definition: features.c:3074
#define FEATURE_APP_LEN
Definition: features.h:31
int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config)
Bridge a call, optionally allowing redirection.
Definition: features.c:3960
#define FEATURE_MAX_LEN
Definition: features.h:30
int ast_pickup_call(struct ast_channel *chan)
Pickup a call.
Definition: features.c:7380
int ast_features_reload(void)
Reload call features from features.conf.
Definition: features.c:6879
int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout)
Park a call via a masqueraded channel.
Definition: features.c:1857
void ast_register_feature(struct ast_call_feature *feature)
register new feature into feature_set
Definition: features.c:2994
char app[FEATURE_APP_LEN]
Definition: features.h:73
void ast_rdlock_call_features(void)
Definition: features.c:3150
char app_args[FEATURE_APP_ARGS_LEN]
Definition: features.h:74
bridge configuration
Definition: channel.h:974
char * fname
Definition: features.h:67
A set of macros to manage forward-linked lists.
unsigned int flags
Definition: features.h:72
Core PBX routines and definitions.
char moh_class[FEATURE_MOH_LEN]
Definition: features.h:75
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
char default_exten[FEATURE_MAX_LEN]
Definition: features.h:70
static void parse(struct mgcp_request *req)
Definition: chan_mgcp.c:1858
static const char name[]
int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target)
Pickup a call target.
Definition: features.c:7414
char sname[FEATURE_SNAME_LEN]
Definition: features.h:68
#define FEATURE_SNAME_LEN
Definition: features.h:33
Structure used to handle boolean flags.
Definition: utils.h:200
#define FEATURE_MOH_LEN
Definition: features.h:35
ast_feature_operation operation
Definition: features.h:71
#define FEATURE_APP_ARGS_LEN
Definition: features.h:32
int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout)
Park a call and read back parked location.
Definition: features.c:1706
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)
Park a call via a masqueraded channel.
Definition: features.c:1803
int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context)
Determine if parking extension exists in a given context.
Definition: features.c:844
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:107
void ast_unlock_call_features(void)
Definition: features.c:3155
struct ast_call_feature::@170 feature_entry
const char * ast_pickup_ext(void)
Determine system call pickup extension.
Definition: features.c:849
struct ast_call_feature * ast_find_call_feature(const char *name)
look for a call feature entry by its sname
Definition: features.c:3160
int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature)
detect a feature before bridging
Definition: features.c:3434
int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit)
parse L option and read associated channel variables to set warning, warning frequency, and timelimit
Definition: features.c:7532
int ast_can_pickup(struct ast_channel *chan)
Test if a channel can be picked up.
Definition: features.c:7338
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)
Park a call and read back parked location.
Definition: features.c:1655