Mon Mar 19 11:30:27 2012

Asterisk developer's documentation


features.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Call Parking and Pickup API 
00021  * Includes code and algorithms from the Zapata library.
00022  */
00023 
00024 #ifndef _AST_FEATURES_H
00025 #define _AST_FEATURES_H
00026 
00027 #include "asterisk/pbx.h"
00028 #include "asterisk/linkedlists.h"
00029 
00030 #define FEATURE_MAX_LEN    11
00031 #define FEATURE_APP_LEN    64
00032 #define FEATURE_APP_ARGS_LEN  256
00033 #define FEATURE_SNAME_LEN  32
00034 #define FEATURE_EXTEN_LEN  32
00035 #define FEATURE_MOH_LEN    80  /* same as MAX_MUSICCLASS from channel.h */
00036 
00037 #define DEFAULT_PARKINGLOT "default"   /*!< Default parking lot */
00038 
00039 #define AST_FEATURE_RETURN_HANGUP           -1
00040 #define AST_FEATURE_RETURN_SUCCESSBREAK     0
00041 #define AST_FEATURE_RETURN_PBX_KEEPALIVE    AST_PBX_KEEPALIVE
00042 #define AST_FEATURE_RETURN_NO_HANGUP_PEER   AST_PBX_NO_HANGUP_PEER
00043 #define AST_FEATURE_RETURN_PASSDIGITS       21
00044 #define AST_FEATURE_RETURN_STOREDIGITS      22
00045 #define AST_FEATURE_RETURN_SUCCESS          23
00046 #define AST_FEATURE_RETURN_KEEPTRYING       24
00047 #define AST_FEATURE_RETURN_PARKFAILED       25
00048 
00049 #define FEATURE_SENSE_CHAN (1 << 0)
00050 #define FEATURE_SENSE_PEER (1 << 1)
00051 
00052 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);
00053 
00054 /*! \brief main call feature structure */
00055 
00056 enum {
00057    AST_FEATURE_FLAG_NEEDSDTMF = (1 << 0),
00058    AST_FEATURE_FLAG_ONPEER =    (1 << 1),
00059    AST_FEATURE_FLAG_ONSELF =    (1 << 2),
00060    AST_FEATURE_FLAG_BYCALLEE =  (1 << 3),
00061    AST_FEATURE_FLAG_BYCALLER =  (1 << 4),
00062    AST_FEATURE_FLAG_BYBOTH  =   (3 << 3),
00063 };
00064 
00065 struct ast_call_feature {
00066    int feature_mask;
00067    char *fname;
00068    char sname[FEATURE_SNAME_LEN];
00069    char exten[FEATURE_MAX_LEN];
00070    char default_exten[FEATURE_MAX_LEN];
00071    ast_feature_operation operation;
00072    unsigned int flags;
00073    char app[FEATURE_APP_LEN];    
00074    char app_args[FEATURE_APP_ARGS_LEN];
00075    char moh_class[FEATURE_MOH_LEN];
00076    AST_LIST_ENTRY(ast_call_feature) feature_entry;
00077 };
00078 
00079 /*!
00080  * \brief Park a call and read back parked location
00081  *
00082  * \param park_me Channel to be parked.
00083  * \param parker Channel parking the call.
00084  * \param timeout is a timeout in milliseconds
00085  * \param park_exten Parking lot access extension (Not used)
00086  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
00087  *
00088  * \details
00089  * Park the park_me channel, and read back the parked location
00090  * to the parker channel.  If the call is not picked up within a
00091  * specified period of time, then the call will return to the
00092  * last step that it was in (in terms of exten, priority and
00093  * context).
00094  *
00095  * \note Use ast_park_call_exten() instead.
00096  *
00097  * \retval 0 on success.
00098  * \retval -1 on failure.
00099  */
00100 int ast_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, const char *park_exten, int *extout);
00101 
00102 /*!
00103  * \brief Park a call and read back parked location
00104  * \since 1.8.9
00105  *
00106  * \param park_me Channel to be parked.
00107  * \param parker Channel parking the call.
00108  * \param park_exten Parking lot access extension
00109  * \param park_context Parking lot context
00110  * \param timeout is a timeout in milliseconds
00111  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
00112  *
00113  * \details
00114  * Park the park_me channel, and read back the parked location
00115  * to the parker channel.  If the call is not picked up within a
00116  * specified period of time, then the call will return to the
00117  * last step that it was in (in terms of exten, priority and
00118  * context).
00119  *
00120  * \retval 0 on success.
00121  * \retval -1 on failure.
00122  */
00123 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);
00124 
00125 /*!
00126  * \brief Park a call via a masqueraded channel
00127  *
00128  * \param park_me Channel to be parked.
00129  * \param parker Channel parking the call.
00130  * \param timeout is a timeout in milliseconds
00131  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
00132  *
00133  * \details
00134  * Masquerade the park_me channel into a new, empty channel which is then parked.
00135  *
00136  * \note Use ast_masq_park_call_exten() instead.
00137  *
00138  * \retval 0 on success.
00139  * \retval -1 on failure.
00140  */
00141 int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
00142 
00143 /*!
00144  * \brief Park a call via a masqueraded channel
00145  * \since 1.8.9
00146  *
00147  * \param park_me Channel to be parked.
00148  * \param parker Channel parking the call.
00149  * \param park_exten Parking lot access extension
00150  * \param park_context Parking lot context
00151  * \param timeout is a timeout in milliseconds
00152  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
00153  *
00154  * \details
00155  * Masquerade the park_me channel into a new, empty channel which is then parked.
00156  *
00157  * \retval 0 on success.
00158  * \retval -1 on failure.
00159  */
00160 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);
00161 
00162 /*! 
00163  * \brief Determine if parking extension exists in a given context
00164  * \retval 0 if extension does not exist
00165  * \retval 1 if extension does exist
00166 */
00167 int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
00168 
00169 /*! \brief Determine system call pickup extension */
00170 const char *ast_pickup_ext(void);
00171 
00172 /*! \brief Bridge a call, optionally allowing redirection */
00173 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
00174 
00175 /*!
00176  * \brief Test if a channel can be picked up.
00177  *
00178  * \param chan Channel to test if can be picked up.
00179  *
00180  * \note This function assumes that chan is locked.
00181  *
00182  * \return TRUE if channel can be picked up.
00183  */
00184 int ast_can_pickup(struct ast_channel *chan);
00185 
00186 /*! \brief Pickup a call */
00187 int ast_pickup_call(struct ast_channel *chan);
00188 
00189 /*!
00190  * \brief Pickup a call target.
00191  *
00192  * \param chan channel that initiated pickup.
00193  * \param target channel to be picked up.
00194  *
00195  * \note This function assumes that target is locked.
00196  *
00197  * \retval 0 on success.
00198  * \retval -1 on failure.
00199  */
00200 int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target);
00201 
00202 /*! 
00203  * \brief register new feature into feature_set 
00204  * \param feature an ast_call_feature object which contains a keysequence
00205  * and a callback function which is called when this keysequence is pressed
00206  * during a call. 
00207 */
00208 void ast_register_feature(struct ast_call_feature *feature);
00209 
00210 /*! 
00211  * \brief unregister feature from feature_set
00212  * \param feature the ast_call_feature object which was registered before
00213 */
00214 void ast_unregister_feature(struct ast_call_feature *feature);
00215 
00216 /*! 
00217  * \brief detect a feature before bridging 
00218  * \param chan
00219  * \param features an ast_flags ptr
00220  * \param code ptr of input code
00221  * \param feature
00222  * \retval ast_call_feature ptr to be set if found 
00223 */
00224 int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
00225 
00226 /*! 
00227  * \brief look for a call feature entry by its sname
00228  * \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. 
00229 */
00230 struct ast_call_feature *ast_find_call_feature(const char *name);
00231 
00232 void ast_rdlock_call_features(void);
00233 void ast_unlock_call_features(void);
00234 
00235 /*! \brief Reload call features from features.conf */
00236 int ast_features_reload(void);
00237 
00238 /*!
00239  * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
00240  * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
00241 */
00242 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
00243 
00244 #endif /* _AST_FEATURES_H */

Generated on Mon Mar 19 11:30:27 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7