560e94d5fc321b86ec4ead71016b063823deca7d
[asterisk/asterisk.git] / include / asterisk / bridge_basic.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013 Digium, Inc.
5  *
6  * Richard Mudgett <rmudgett@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 /*!
20  * \file
21  * \brief Basic bridge subclass API.
22  *
23  * \author Richard Mudgett <rmudgett@digium.com>
24  *
25  * See Also:
26  * \arg \ref AstCREDITS
27  */
28
29 #ifndef _ASTERISK_BRIDGING_BASIC_H
30 #define _ASTERISK_BRIDGING_BASIC_H
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 /* ------------------------------------------------------------------- */
37
38 /*!
39  * \brief Sets the features a channel will use upon being bridged.
40  * \since 12.0.0
41  *
42  * \param chan Which channel to set features for
43  * \param features Which feature codes to set for the channel
44  *
45  * \retval 0 on success
46  * \retval -1 on failure
47  */
48 int ast_bridge_features_ds_set_string(struct ast_channel *chan, const char *features);
49
50 /*!
51  * \brief writes a channel's DTMF features to a buffer string
52  * \since 12.0.0
53  *
54  * \param chan channel whose feature flags should be checked
55  * \param buffer pointer string buffer where the output should be stored
56  * \param buf_size size of the provided buffer (ideally enough for all features, 6+)
57  *
58  * \retval 0 on successful write
59  * \retval -1 on failure
60  */
61 int ast_bridge_features_ds_get_string(struct ast_channel *chan, char *buffer, size_t buf_size);
62
63 /*!
64  * \brief Get DTMF feature flags from the channel.
65  * \since 12.0.0
66  *
67  * \param chan Channel to get DTMF features datastore.
68  *
69  * \note The channel should be locked before calling this function.
70  * \note The channel must remain locked until the flags returned have been consumed.
71  *
72  * \retval flags on success.
73  * \retval NULL if the datastore does not exist.
74  */
75 struct ast_flags *ast_bridge_features_ds_get(struct ast_channel *chan);
76
77 /*!
78  * \brief Set basic bridge DTMF feature flags datastore on the channel.
79  * \since 12.0.0
80  *
81  * \param chan Channel to set DTMF features datastore.
82  * \param flags Builtin DTMF feature flags. (ast_bridge_config flags)
83  *
84  * \note The channel must be locked before calling this function.
85  *
86  * \retval 0 on success.
87  * \retval -1 on error.
88  */
89 int ast_bridge_features_ds_set(struct ast_channel *chan, struct ast_flags *flags);
90
91 /*!
92  * \brief Append basic bridge DTMF feature flags on the channel.
93  * \since 12.0.0
94  *
95  * \param chan Channel to append DTMF features datastore.
96  * \param flags Builtin DTMF feature flags. (ast_bridge_config flags)
97  *
98  * \note The channel must be locked before calling this function.
99  * \note This function differs from ast_bridge_features_ds_set only in that it won't
100  *       remove features already set on the channel.
101  *
102  * \retval 0 on success.
103  * \retval -1 on error.
104  */
105 int ast_bridge_features_ds_append(struct ast_channel *chan, struct ast_flags *flags);
106
107 /*! \brief Bridge basic class virtual method table. */
108 extern struct ast_bridge_methods ast_bridge_basic_v_table;
109
110 /*!
111  * \brief Create a new basic class bridge
112  *
113  * \retval a pointer to a new bridge on success
114  * \retval NULL on failure
115  *
116  * Example usage:
117  *
118  * \code
119  * struct ast_bridge *bridge;
120  * bridge = ast_bridge_basic_new();
121  * \endcode
122  *
123  * This creates a basic two party bridge with any configured
124  * DTMF features enabled that will be destroyed once one of the
125  * channels hangs up.
126  */
127 struct ast_bridge *ast_bridge_basic_new(void);
128
129 /*! Initialize the basic bridge class for use by the system. */
130 void ast_bridging_init_basic(void);
131
132 /* ------------------------------------------------------------------- */
133
134 #if defined(__cplusplus) || defined(c_plusplus)
135 }
136 #endif
137
138 #endif  /* _ASTERISK_BRIDGING_BASIC_H */