Asterisk - The Open Source Telephony Project  21.4.1
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  */
31  /*! Sound played when automixmon features are used */
33  /*! Sound played when automixmon features fail when used */
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  */
59  /*! Sound to play when transfer succeeds */
61  /*! Sound to play when transfer fails */
63  /*! DTMF sequence used to abort an attempted atxfer */
65  /*! DTMF sequence used to complete an attempted atxfer */
67  /*! DTMF sequence used to turn an attempted atxfer into a three-way call */
69  /*! DTMF sequence used to swap which party the transferer is talking to */
71  /*! Sound played when an invalid extension is dialed, and the transferer should retry. */
73  /*! Sound played when an invalid extension is dialed, and the transferer is being returned to the call. */
75  /*! Sound to play to announce the transfer process has started. */
77  );
78  /*! Seconds allowed between digit presses when dialing transfer destination */
79  unsigned int transferdigittimeout;
80  /*! Seconds to wait for the transfer target to answer a transferred call */
81  unsigned int atxfernoanswertimeout;
82  /*! Seconds to wait before attempting to re-dial the transfer target */
83  unsigned int atxferloopdelay;
84  /*! Number of times to re-attempt dialing the transfer target */
85  unsigned int atxfercallbackretries;
86  /*! Determines if the call is dropped on attended transfer failure */
87  unsigned int atxferdropcall;
88  /*! Number of dial attempts allowed for blind/attended transfers */
89  unsigned int transferdialattempts;
90 };
91 
92 /*!
93  * \brief Get the transfer configuration options for a channel
94  *
95  * \note The channel should be locked before calling this function.
96  * \note The returned value has its reference count incremented.
97  *
98  * If no channel is provided, then the global transfer configuration is returned.
99  *
100  * \param chan The channel to get configuration options for
101  * \retval NULL Failed to get configuration
102  * \retval non-NULL The transfer features configuration
103  */
104 struct ast_features_xfer_config *ast_get_chan_features_xfer_config(struct ast_channel *chan);
105 
106 /*!
107  * \brief Get the transfer configuration option xferfailsound
108  *
109  * \note The channel should be locked before calling this function.
110  * \note The returned value has to be freed.
111  *
112  * If no channel is provided, then option is pulled from the global
113  * transfer configuration.
114  *
115  * \param chan The channel to get configuration options for
116  * \retval NULL Failed to get configuration
117  * \retval non-NULL The xferfailsound
118  */
119 char *ast_get_chan_features_xferfailsound(struct ast_channel *chan);
120 
121 /*!
122  * \brief Get the transfer configuration option atxferabort
123  *
124  * \note The channel should be locked before calling this function.
125  * \note The returned value has to be freed.
126  *
127  * If no channel is provided, then option is pulled from the global
128  * transfer configuration.
129  *
130  * \param chan The channel to get configuration options for
131  * \retval NULL Failed to get configuration
132  * \retval non-NULL The atxferabort
133  */
134 char *ast_get_chan_features_atxferabort(struct ast_channel *chan);
135 
136 /*!
137  * \brief Configuration relating to call pickup
138  */
141  /*! Digit sequence to press to pick up a ringing call */
143  /*! Sound to play to picker when pickup succeeds */
145  /*! Sound to play to picker when pickup fails */
147  );
148 };
149 
150 /*!
151  * \brief Get the pickup configuration options for a channel
152  *
153  * \note The channel should be locked before calling this function.
154  * \note The returned value has its reference count incremented.
155  *
156  * If no channel is provided, then the global pickup configuration is returned.
157  *
158  * \param chan The channel to get configuration options for
159  * \retval NULL Failed to get configuration
160  * \retval non-NULL The pickup features configuration
161  */
162 struct ast_features_pickup_config *ast_get_chan_features_pickup_config(struct ast_channel *chan);
163 
164 /*!
165  * \brief Configuration for the builtin features
166  */
169  /*! Blind transfer DTMF code */
171  /*! Disconnect DTMF code */
173  /*! Attended Transfer DTMF code */
175  /*! One-touch parking DTMF code */
177  /*! Automixmon DTMF code */
179  );
180 };
181 
182 /*!
183  * \brief Get the featuremap configuration options for a channel
184  *
185  * \note The channel should be locked before calling this function.
186  * \note The returned value has its reference count incremented.
187  *
188  * If no channel is provided, then the global featuremap configuration is returned.
189  *
190  * \param chan The channel to get configuration options for
191  * \retval NULL Failed to get configuration
192  * \retval non-NULL The pickup features configuration
193  */
194 struct ast_featuremap_config *ast_get_chan_featuremap_config(struct ast_channel *chan);
195 
196 /*!
197  * \brief Get the DTMF code for a builtin feature
198  *
199  * \note The channel should be locked before calling this function
200  *
201  * If no channel is provided, then the global setting for the option is returned.
202  *
203  * \param chan The channel to get the option from
204  * \param feature The short name of the feature (as it appears in features.conf)
205  * \param[out] buf The buffer to write the DTMF value into
206  * \param len The size of the buffer in bytes
207  * \retval 0 Success
208  * \retval non-zero Unrecognized builtin feature name
209  */
210 int ast_get_builtin_feature(struct ast_channel *chan, const char *feature, char *buf, size_t len);
211 
212 /*!
213  * \brief Get the DTMF code for a call feature
214  *
215  * \note The channel should be locked before calling this function
216  *
217  * If no channel is provided, then the global setting for the option is returned.
218  *
219  * This function is like \ref ast_get_builtin_feature except that it will
220  * also check the applicationmap in addition to the builtin features.
221  *
222  * \param chan The channel to get the option from
223  * \param feature The short name of the feature
224  * \param[out] buf The buffer to write the DTMF value into
225  * \param len The size of the buffer in bytes
226  * \retval 0 Success
227  * \retval non-zero Unrecognized feature name
228  */
229 int ast_get_feature(struct ast_channel *chan, const char *feature, char *buf, size_t len);
230 
231 #define AST_FEATURE_MAX_LEN 11
232 
233 /*!
234  * \brief An applicationmap configuration item
235  */
238  /* Name of the item */
239  AST_STRING_FIELD(name);
240  /* Name Dialplan application that is invoked by the feature */
241  AST_STRING_FIELD(app);
242  /* Data to pass to the application */
244  /* Music-on-hold class to play to party on which feature is not activated */
245  AST_STRING_FIELD(moh_class);
246  );
247  /* DTMF key sequence used to activate the feature */
248  char dtmf[AST_FEATURE_MAX_LEN];
249  /* If true, activate on party that input the sequence, otherwise activate on the other party */
250  unsigned int activate_on_self;
251 };
252 
253 /*!
254  * \brief Get the applicationmap for a given channel.
255  *
256  * \note The channel should be locked before calling this function.
257  *
258  * This uses the value of the DYNAMIC_FEATURES channel variable to build a
259  * custom applicationmap for this channel. The returned container has
260  * applicationmap_items inside.
261  *
262  * \param chan The channel for which applicationmap is being retrieved.
263  * \retval NULL An error occurred or the channel has no dynamic features.
264  * \retval non-NULL A container of applicationmap_items pertaining to the channel.
265  */
266 struct ao2_container *ast_get_chan_applicationmap(struct ast_channel *chan);
267 
268 #endif /* _FEATURES_CONFIG_H */
Main Channel structure associated with a channel.
Feature configuration relating to transfers.
Configuration for the builtin features.
An applicationmap configuration item.
const ast_string_field transferannouncesound
General features configuration items.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Generic container type.
Configuration relating to call pickup.