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 #include "asterisk/bridge.h"
  30
  31 #define FEATURE_MAX_LEN         11
  32 #define FEATURE_APP_LEN         64
  33 #define FEATURE_APP_ARGS_LEN    256
  34 #define FEATURE_SNAME_LEN       32
  35 #define FEATURE_EXTEN_LEN       32
  36 #define FEATURE_MOH_LEN         80  /* same as MAX_MUSICCLASS from channel.h */
  37
  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 /*!
  67  * \brief Park a call and read back parked location
  68  *
  69  * \param park_me Channel to be parked.
  70  * \param parker Channel parking the call.
  71  * \param timeout is a timeout in milliseconds
  72  * \param park_exten Parking lot access extension (Not used)
  73  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
  74  *
  75  * \details
  76  * Park the park_me channel, and read back the parked location
  77  * to the parker channel.  If the call is not picked up within a
  78  * specified period of time, then the call will return to the
  79  * last step that it was in (in terms of exten, priority and
  80  * context).
  81  *
  82  * \note Use ast_park_call_exten() instead.
  83  *
  84  * \retval 0 on success.
  85  * \retval -1 on failure.
  86  */
  87 int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout);
  88
  89 /*!
  90  * \brief Park a call and read back parked location
  91  * \since 1.8.9
  92  *
  93  * \param park_me Channel to be parked.
  94  * \param parker Channel parking the call.
  95  * \param park_exten Parking lot access extension
  96  * \param park_context Parking lot context
  97  * \param timeout is a timeout in milliseconds
  98  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
  99  *
 100  * \details
 101  * Park the park_me channel, and read back the parked location
 102  * to the parker channel.  If the call is not picked up within a
 103  * specified period of time, then the call will return to the
 104  * last step that it was in (in terms of exten, priority and
 105  * context).
 106  *
 107  * \retval 0 on success.
 108  * \retval -1 on failure.
 109  */
 110 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);
 111
 112 /*!
 113  * \brief Park a call via a masqueraded channel
 114  *
 115  * \param park_me Channel to be parked.
 116  * \param parker Channel parking the call.
 117  * \param timeout is a timeout in milliseconds
 118  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
 119  *
 120  * \details
 121  * Masquerade the park_me channel into a new, empty channel which is then parked.
 122  *
 123  * \note Use ast_masq_park_call_exten() instead.
 124  *
 125  * \retval 0 on success.
 126  * \retval -1 on failure.
 127  */
 128 int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
 129
 130 /*!
 131  * \brief Park a call via a masqueraded channel
 132  * \since 1.8.9
 133  *
 134  * \param park_me Channel to be parked.
 135  * \param parker Channel parking the call.
 136  * \param park_exten Parking lot access extension
 137  * \param park_context Parking lot context
 138  * \param timeout is a timeout in milliseconds
 139  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
 140  *
 141  * \details
 142  * Masquerade the park_me channel into a new, empty channel which is then parked.
 143  *
 144  * \retval 0 on success.
 145  * \retval -1 on failure.
 146  */
 147 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);
 148
 149 /*!
 150  * \brief Determine if parking extension exists in a given context
 151  * \retval 0 if extension does not exist
 152  * \retval 1 if extension does exist
 153 */
 154 int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
 155
 156 /*! \brief Bridge a call, optionally allowing redirection */
 157 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
 158
 159 /*!
 160  * \brief Add an arbitrary channel to a bridge
 161  * \since 12.0.0
 162  *
 163  * The channel that is being added to the bridge can be in any state: unbridged,
 164  * bridged, answered, unanswered, etc. The channel will be added asynchronously,
 165  * meaning that when this function returns once the channel has been added to
 166  * the bridge, not once the channel has been removed from the bridge.
 167  *
 168  * In addition, a tone can optionally be played to the channel once the
 169  * channel is placed into the bridge.
 170  *
 171  * \note When this function returns, there is no guarantee that the channel that
 172  * was passed in is valid any longer. Do not attempt to operate on the channel
 173  * after this function returns.
 174  *
 175  * \param bridge Bridge to which the channel should be added
 176  * \param chan The channel to add to the bridge
 177  * \param features Features for this channel in the bridge
 178  * \param play_tone Indicates if a tone should be played to the channel
 179  * \param xfersound Sound that should be used to indicate transfer with play_tone
 180  * \retval 0 Success
 181  * \retval -1 Failure
 182  */
 183 int ast_bridge_add_channel(struct ast_bridge *bridge, struct ast_channel *chan,
 184                 struct ast_bridge_features *features, int play_tone, const char *xfersound);
 185
 186 /*!
 187  * \brief Test if a channel can be picked up.
 188  *
 189  * \param chan Channel to test if can be picked up.
 190  *
 191  * \note This function assumes that chan is locked.
 192  *
 193  * \return TRUE if channel can be picked up.
 194  */
 195 int ast_can_pickup(struct ast_channel *chan);
 196
 197 /*!
 198  * \brief Find a pickup channel target by group.
 199  *
 200  * \param chan channel that initiated pickup.
 201  *
 202  * \retval target on success.  The returned channel is locked and reffed.
 203  * \retval NULL on error.
 204  */
 205 struct ast_channel *ast_pickup_find_by_group(struct ast_channel *chan);
 206
 207 /*! \brief Pickup a call */
 208 int ast_pickup_call(struct ast_channel *chan);
 209
 210 /*!
 211  * \brief Pickup a call target.
 212  *
 213  * \param chan channel that initiated pickup.
 214  * \param target channel to be picked up.
 215  *
 216  * \note This function assumes that target is locked.
 217  *
 218  * \retval 0 on success.
 219  * \retval -1 on failure.
 220  */
 221 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
 222
 223 /*!
 224  * \brief accessor for call pickup message type
 225  * \since 12.0.0
 226  *
 227  * \retval pointer to the stasis message type
 228  * \retval NULL if not initialized
 229  */
 230 struct stasis_message_type *ast_call_pickup_type(void);
 231
 232 /*! \brief Reload call features from features.conf */
 233 int ast_features_reload(void);
 234
 235 /*!
 236  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
 237  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
 238 */
 239 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
 240
 241 #endif /* _AST_FEATURES_H */