Doxygen cleanups/fixes.
[asterisk/asterisk.git] / 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 #define FEATURE_MAX_LEN         11
28 #define FEATURE_APP_LEN         64
29 #define FEATURE_APP_ARGS_LEN    256
30 #define FEATURE_SNAME_LEN       32
31 #define FEATURE_EXTEN_LEN       32
32 #define FEATURE_MOH_LEN         80  /* same as MAX_MUSICCLASS from channel.h */
33
34 /*! \brief main call feature structure */
35 struct ast_call_feature {
36         int feature_mask;
37         char *fname;
38         char sname[FEATURE_SNAME_LEN];
39         char exten[FEATURE_MAX_LEN];
40         char default_exten[FEATURE_MAX_LEN];
41         int (*operation)(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense, void *data);
42         unsigned int flags;
43         char app[FEATURE_APP_LEN];              
44         char app_args[FEATURE_APP_ARGS_LEN];
45         char moh_class[FEATURE_MOH_LEN];
46         AST_LIST_ENTRY(ast_call_feature) feature_entry;
47 };
48
49
50
51 /*!
52  * \brief Park a call and read back parked location 
53  * \param chan the channel to actually be parked
54  * \param host the channel which will have the parked location read to.
55  * \param timeout is a timeout in milliseconds
56  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
57  * 
58  * Park the channel chan, and read back the parked location to the host. 
59  * If the call is not picked up within a specified period of time, 
60  * then the call will return to the last step that it was in 
61  * (in terms of exten, priority and context)
62  * \retval 0 on success.
63  * \retval -1 on failure.
64 */
65 int ast_park_call(struct ast_channel *chan, struct ast_channel *host, int timeout, int *extout);
66
67 /*! 
68  * \brief Park a call via a masqueraded channel
69  * \param rchan the real channel to be parked
70  * \param host the channel to have the parking read to.
71  * \param timeout is a timeout in milliseconds
72  * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
73  * 
74  * Masquerade the channel rchan into a new, empty channel which is then parked with ast_park_call
75  * \retval 0 on success.
76  * \retval -1 on failure.
77 */
78 int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *host, int timeout, int *extout);
79
80 /*! 
81  * \brief Determine system parking extension
82  * \returns the call parking extension for drivers that provide special call parking help 
83 */
84 const char *ast_parking_ext(void);
85
86 /*! \brief Determine system call pickup extension */
87 const char *ast_pickup_ext(void);
88
89 /*! \brief Bridge a call, optionally allowing redirection */
90 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
91
92 /*! \brief Pickup a call */
93 int ast_pickup_call(struct ast_channel *chan);
94
95 /*! \brief register new feature into feature_set 
96    \param feature an ast_call_feature object which contains a keysequence
97    and a callback function which is called when this keysequence is pressed
98    during a call. */
99 void ast_register_feature(struct ast_call_feature *feature);
100
101 /*! \brief unregister feature from feature_set
102     \param feature the ast_call_feature object which was registered before*/
103 void ast_unregister_feature(struct ast_call_feature *feature);
104
105 /*! \brief look for a call feature entry by its sname
106         \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. */
107 struct ast_call_feature *ast_find_call_feature(const char *name);
108
109 void ast_rdlock_call_features(void);
110 void ast_unlock_call_features(void);
111
112 #endif /* _AST_FEATURES_H */