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
  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 {
  57         AST_FEATURE_FLAG_NEEDSDTMF = (1 << 0),
  58         AST_FEATURE_FLAG_ONPEER =    (1 << 1),
  59         AST_FEATURE_FLAG_ONSELF =    (1 << 2),
  60         AST_FEATURE_FLAG_BYCALLEE =  (1 << 3),
  61         AST_FEATURE_FLAG_BYCALLER =  (1 << 4),
  62         AST_FEATURE_FLAG_BYBOTH  =   (3 << 3),
  63 };
  64
  65 struct ast_call_feature {
  66         int feature_mask;
  67         char *fname;
  68         char sname[FEATURE_SNAME_LEN];
  69         char exten[FEATURE_MAX_LEN];
  70         char default_exten[FEATURE_MAX_LEN];
  71         ast_feature_operation operation;
  72         unsigned int flags;
  73         char app[FEATURE_APP_LEN];
  74         char app_args[FEATURE_APP_ARGS_LEN];
  75         char moh_class[FEATURE_MOH_LEN];
  76         AST_LIST_ENTRY(ast_call_feature) feature_entry;
  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 /*!
 199  * \brief Find a pickup channel target by group.
 200  *
 201  * \param chan channel that initiated pickup.
 202  *
 203  * \retval target on success.  The returned channel is locked and reffed.
 204  * \retval NULL on error.
 205  */
 206 struct ast_channel *ast_pickup_find_by_group(struct ast_channel *chan);
 207
 208 /*! \brief Pickup a call */
 209 int ast_pickup_call(struct ast_channel *chan);
 210
 211 /*!
 212  * \brief Pickup a call target.
 213  *
 214  * \param chan channel that initiated pickup.
 215  * \param target channel to be picked up.
 216  *
 217  * \note This function assumes that target is locked.
 218  *
 219  * \retval 0 on success.
 220  * \retval -1 on failure.
 221  */
 222 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
 223
 224 /*!
 225  * \brief register new feature into feature_set
 226  * \param feature an ast_call_feature object which contains a keysequence
 227  * and a callback function which is called when this keysequence is pressed
 228  * during a call.
 229 */
 230 void ast_register_feature(struct ast_call_feature *feature);
 231
 232 /*!
 233  * \brief unregister feature from feature_set
 234  * \param feature the ast_call_feature object which was registered before
 235 */
 236 void ast_unregister_feature(struct ast_call_feature *feature);
 237
 238 /*!
 239  * \brief detect a feature before bridging
 240  * \param chan
 241  * \param features an ast_flags ptr
 242  * \param code ptr of input code
 243  * \param feature
 244  * \retval ast_call_feature ptr to be set if found
 245 */
 246 int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
 247
 248 /*!
 249  * \brief look for a call feature entry by its sname
 250  * \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc.
 251 */
 252 struct ast_call_feature *ast_find_call_feature(const char *name);
 253
 254 void ast_rdlock_call_features(void);
 255 void ast_unlock_call_features(void);
 256
 257 /*! \brief Reload call features from features.conf */
 258 int ast_features_reload(void);
 259
 260 /*!
 261  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
 262  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
 263 */
 264 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
 265
 266 #endif /* _AST_FEATURES_H */