Allow for transferer to retry when dialing an invalid extension.
[asterisk/asterisk.git] / include / asterisk / features_config.h
1 /*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2013, Digium, Inc.
5 *
6 * Mark Michelson <mmichelson@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 #ifndef _FEATURES_CONFIG_H
20 #define _FEATURES_CONFIG_H
21
22 #include "asterisk/stringfields.h"
23
24 struct ast_channel;
25
26 /*!
27  * \brief General features configuration items
28  */
29 struct ast_features_general_config {
30         AST_DECLARE_STRING_FIELDS(
31                 /*! Sound played when automon or automixmon features are used */
32                 AST_STRING_FIELD(courtesytone);
33                 /*! Sound played when automon or automixmon features fail when used */
34                 AST_STRING_FIELD(recordingfailsound);
35         );
36         /*! Milliseconds allowed between digit presses when entering feature code */
37         unsigned int featuredigittimeout;
38 };
39
40 /*!
41  * \brief Get the general configuration options for a channel
42  *
43  * \note The channel should be locked before calling this function.
44  * \note The returned value has its reference count incremented.
45  *
46  * If no channel is provided, then the global features configuration is returned.
47  *
48  * \param chan The channel to get configuration options for
49  * \retval NULL Failed to get configuration
50  * \retval non-NULL The general features configuration
51  */
52 struct ast_features_general_config *ast_get_chan_features_general_config(struct ast_channel *chan);
53
54 /*!
55  * \brief Feature configuration relating to transfers
56  */
57 struct ast_features_xfer_config {
58         AST_DECLARE_STRING_FIELDS (
59                 /*! Sound to play when transfer succeeds */
60                 AST_STRING_FIELD(xfersound);
61                 /*! Sound to play when transfer fails */
62                 AST_STRING_FIELD(xferfailsound);
63                 /*! DTMF sequence used to abort an attempted atxfer */
64                 AST_STRING_FIELD(atxferabort);
65                 /*! DTMF sequence used to complete an attempted atxfer */
66                 AST_STRING_FIELD(atxfercomplete);
67                 /*! DTMF sequence used to turn an attempted atxfer into a three-way call */
68                 AST_STRING_FIELD(atxferthreeway);
69                 /*! DTMF sequence used to swap which party the transferer is talking to */
70                 AST_STRING_FIELD(atxferswap);
71                 /*! Sound played when an invalid extension is dialed, and the transferer should retry. */
72                 AST_STRING_FIELD(transferretrysound);
73                 /*! Sound played when an invalid extension is dialed, and the transferer is being returned to the call. */
74                 AST_STRING_FIELD(transferinvalidsound);
75         );
76         /*! Seconds allowed between digit presses when dialing transfer destination */
77         unsigned int transferdigittimeout;
78         /*! Seconds to wait for the transfer target to answer a transferred call */
79         unsigned int atxfernoanswertimeout;
80         /*! Seconds to wait before attempting to re-dial the transfer target */
81         unsigned int atxferloopdelay;
82         /*! Number of times to re-attempt dialing the transfer target */
83         unsigned int atxfercallbackretries;
84         /*! Determines if the call is dropped on attended transfer failure */
85         unsigned int atxferdropcall;
86         /*! Number of dial attempts allowed for blind/attended transfers */
87         unsigned int transferdialattempts;
88 };
89
90 /*!
91  * \brief Get the transfer configuration options for a channel
92  *
93  * \note The channel should be locked before calling this function.
94  * \note The returned value has its reference count incremented.
95  *
96  * If no channel is provided, then the global transfer configuration is returned.
97  *
98  * \param chan The channel to get configuration options for
99  * \retval NULL Failed to get configuration
100  * \retval non-NULL The transfer features configuration
101  */
102 struct ast_features_xfer_config *ast_get_chan_features_xfer_config(struct ast_channel *chan);
103
104 /*!
105  * \brief Configuration relating to call pickup
106  */
107 struct ast_features_pickup_config {
108         AST_DECLARE_STRING_FIELDS (
109                 /*! Digit sequence to press to pick up a ringing call */
110                 AST_STRING_FIELD(pickupexten);
111                 /*! Sound to play to picker when pickup succeeds */
112                 AST_STRING_FIELD(pickupsound);
113                 /*! Sound to play to picker when pickup fails */
114                 AST_STRING_FIELD(pickupfailsound);
115         );
116 };
117
118 /*!
119  * \brief Get the pickup configuration options for a channel
120  *
121  * \note The channel should be locked before calling this function.
122  * \note The returned value has its reference count incremented.
123  *
124  * If no channel is provided, then the global pickup configuration is returned.
125  *
126  * \param chan The channel to get configuration options for
127  * \retval NULL Failed to get configuration
128  * \retval non-NULL The pickup features configuration
129  */
130 struct ast_features_pickup_config *ast_get_chan_features_pickup_config(struct ast_channel *chan);
131
132 /*!
133  * \brief Configuration for the builtin features
134  */
135 struct ast_featuremap_config {
136         AST_DECLARE_STRING_FIELDS (
137                 /*! Blind transfer DTMF code */
138                 AST_STRING_FIELD(blindxfer);
139                 /*! Disconnect DTMF code */
140                 AST_STRING_FIELD(disconnect);
141                 /*! Automon DTMF code */
142                 AST_STRING_FIELD(automon);
143                 /*! Attended Transfer DTMF code */
144                 AST_STRING_FIELD(atxfer);
145                 /*! One-touch parking DTMF code */
146                 AST_STRING_FIELD(parkcall);
147                 /*! Automixmon DTMF code */
148                 AST_STRING_FIELD(automixmon);
149         );
150 };
151
152 /*!
153  * \brief Get the featuremap configuration options for a channel
154  *
155  * \note The channel should be locked before calling this function.
156  * \note The returned value has its reference count incremented.
157  *
158  * If no channel is provided, then the global featuremap configuration is returned.
159  *
160  * \param chan The channel to get configuration options for
161  * \retval NULL Failed to get configuration
162  * \retval non-NULL The pickup features configuration
163  */
164 struct ast_featuremap_config *ast_get_chan_featuremap_config(struct ast_channel *chan);
165
166 /*!
167  * \brief Get the DTMF code for a builtin feature
168  *
169  * \note The channel should be locked before calling this function
170  *
171  * If no channel is provided, then the global setting for the option is returned.
172  *
173  * \param chan The channel to get the option from
174  * \param feature The short name of the feature (as it appears in features.conf)
175  * \param[out] buf The buffer to write the DTMF value into
176  * \param size The size of the buffer in bytes
177  * \retval 0 Success
178  * \retval non-zero Unrecognized builtin feature name
179  */
180 int ast_get_builtin_feature(struct ast_channel *chan, const char *feature, char *buf, size_t len);
181
182 /*!
183  * \brief Get the DTMF code for a call feature
184  *
185  * \note The channel should be locked before calling this function
186  *
187  * If no channel is provided, then the global setting for the option is returned.
188  *
189  * This function is like \ref ast_get_builtin_feature except that it will
190  * also check the applicationmap in addition to the builtin features.
191  *
192  * \param chan The channel to get the option from
193  * \param feature The short name of the feature
194  * \param[out] buf The buffer to write the DTMF value into
195  * \param size The size of the buffer in bytes
196  * \retval 0 Success
197  * \retval non-zero Unrecognized feature name
198  */
199 int ast_get_feature(struct ast_channel *chan, const char *feature, char *buf, size_t len);
200
201 #define AST_FEATURE_MAX_LEN 11
202
203 /*!
204  * \brief An applicationmap configuration item
205  */
206 struct ast_applicationmap_item {
207         AST_DECLARE_STRING_FIELDS (
208                 /* Name of the item */
209                 AST_STRING_FIELD(name);
210                 /* Name Dialplan application that is invoked by the feature */
211                 AST_STRING_FIELD(app);
212                 /* Data to pass to the application */
213                 AST_STRING_FIELD(app_data);
214                 /* Music-on-hold class to play to party on which feature is not activated */
215                 AST_STRING_FIELD(moh_class);
216         );
217         /* DTMF key sequence used to activate the feature */
218         char dtmf[AST_FEATURE_MAX_LEN];
219         /* If true, activate on party that input the sequence, otherwise activate on the other party */
220         unsigned int activate_on_self;
221 };
222
223 /*!
224  * \brief Get the applicationmap for a given channel.
225  *
226  * \note The channel should be locked before calling this function.
227  *
228  * This uses the value of the DYNAMIC_FEATURES channel variable to build a
229  * custom applicationmap for this channel. The returned container has
230  * applicationmap_items inside.
231  *
232  * \param chan The channel for which applicationmap is being retrieved.
233  * \retval NULL An error occurred or the channel has no dynamic features.
234  * \retval non-NULL A container of applicationmap_items pertaining to the channel.
235  */
236 struct ao2_container *ast_get_chan_applicationmap(struct ast_channel *chan);
237
238 void ast_features_config_shutdown(void);
239
240 int ast_features_config_reload(void);
241
242 int ast_features_config_init(void);
243
244 #endif /* _FEATURES_CONFIG_H */