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