9a8d2e1f54a1d97add7fb266b3b895ad866cb8a3
[asterisk/asterisk.git] / include / asterisk / core_unreal.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 Unreal channel derivative framework.
22  *
23  * \author Richard Mudgett <rmudgett@digium.com>
24  *
25  * See Also:
26  * \arg \ref AstCREDITS
27  */
28
29 #ifndef _ASTERISK_CORE_UNREAL_H
30 #define _ASTERISK_CORE_UNREAL_H
31
32 #include "asterisk/astobj2.h"
33 #include "asterisk/channel.h"
34 #include "asterisk/bridge.h"
35 #include "asterisk/abstract_jb.h"
36
37 #if defined(__cplusplus) || defined(c_plusplus)
38 extern "C" {
39 #endif
40
41 /* Forward declare some struct names */
42 struct ast_format_cap;
43 struct ast_callid;
44
45 /* ------------------------------------------------------------------- */
46
47 struct ast_unreal_pvt;
48
49 /*!
50  * \brief Callbacks that can be provided by concrete implementations of the unreal
51  * channel driver that will be called when events occur in the unreal layer
52  */
53 struct ast_unreal_pvt_callbacks {
54         /*!
55          * \brief Called when an optimization attempt has started
56          * \note p is locked when this callback is called
57          * \param p The \ref ast_unreal_pvt object
58          */
59         void (* const optimization_started)(struct ast_unreal_pvt *p);
60
61         /*!
62          * \brief Called when an optimization attempt completed successfully
63          * \note p is locked when this callback is called
64          * \param p The \ref ast_unreal_pvt object
65          * \param success Non-zero if the optimization succeeded, zero if the optimization
66          * met with fatal and permanent error
67          */
68         void (* const optimization_finished)(struct ast_unreal_pvt *p);
69 };
70
71 /*!
72  * \brief The base pvt structure for local channel derivatives.
73  *
74  * The unreal pvt has two ast_chan objects - the "owner" and the "next channel", the outbound channel
75  *
76  * ast_chan owner -> ast_unreal_pvt -> ast_chan chan
77  */
78 struct ast_unreal_pvt {
79         struct ast_unreal_pvt_callbacks *callbacks; /*!< Event callbacks */
80         struct ast_channel *owner;                  /*!< Master Channel - ;1 side */
81         struct ast_channel *chan;                   /*!< Outbound channel - ;2 side */
82         struct ast_format_cap *reqcap;              /*!< Requested format capabilities */
83         struct ast_jb_conf jb_conf;                 /*!< jitterbuffer configuration */
84         unsigned int flags;                         /*!< Private option flags */
85         /*! Base name of the unreal channels.  exten@context or other name. */
86         char name[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
87 };
88
89 #define AST_UNREAL_IS_OUTBOUND(a, b) ((a) == (b)->chan ? 1 : 0)
90
91 #define AST_UNREAL_CARETAKER_THREAD (1 << 0) /*!< The ;2 side launched a PBX, was pushed into a bridge, or was masqueraded into an application. */
92 #define AST_UNREAL_NO_OPTIMIZATION  (1 << 1) /*!< Do not optimize out the unreal channels */
93 #define AST_UNREAL_MOH_INTERCEPT    (1 << 2) /*!< Intercept and act on hold/unhold control frames */
94 #define AST_UNREAL_OPTIMIZE_BEGUN   (1 << 3) /*!< Indicates that an optimization attempt has been started */
95
96 /*!
97  * \brief Send an unreal pvt in with no locks held and get all locks
98  *
99  * \note NO locks should be held prior to calling this function
100  * \note The pvt must have a ref held before calling this function
101  * \note if outchan or outowner is set != NULL after calling this function
102  *       those channels are locked and reffed.
103  * \note Batman.
104  */
105 void ast_unreal_lock_all(struct ast_unreal_pvt *p, struct ast_channel **outchan, struct ast_channel **outowner);
106
107 /*!
108  * \brief Hangup one end (maybe both ends) of an unreal channel derivative.
109  * \since 12.0.0
110  *
111  * \param p Private channel struct (reffed)
112  * \param ast Channel being hung up.  (locked)
113  *
114  * \note Common hangup code for unreal channels.  Derived
115  * channels will need to deal with any additional resources.
116  *
117  * \retval 0 on success.
118  * \retval -1 on error.
119  */
120 int ast_unreal_hangup(struct ast_unreal_pvt *p, struct ast_channel *ast);
121
122 /*! Unreal channel framework struct ast_channel_tech.send_digit_begin callback */
123 int ast_unreal_digit_begin(struct ast_channel *ast, char digit);
124
125 /*! Unreal channel framework struct ast_channel_tech.send_digit_end callback */
126 int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration);
127
128 /*! Unreal channel framework struct ast_channel_tech.answer callback */
129 int ast_unreal_answer(struct ast_channel *ast);
130
131 /*! Unreal channel framework struct ast_channel_tech.read and struct ast_channel_tech.exception callback */
132 struct ast_frame *ast_unreal_read(struct ast_channel *ast);
133
134 /*! Unreal channel framework struct ast_channel_tech.write callback */
135 int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f);
136
137 /*! Unreal channel framework struct ast_channel_tech.indicate callback */
138 int ast_unreal_indicate(struct ast_channel *ast, int condition, const void *data, size_t datalen);
139
140 /*! Unreal channel framework struct ast_channel_tech.fixup callback */
141 int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan);
142
143 /*! Unreal channel framework struct ast_channel_tech.send_html callback */
144 int ast_unreal_sendhtml(struct ast_channel *ast, int subclass, const char *data, int datalen);
145
146 /*! Unreal channel framework struct ast_channel_tech.send_text callback */
147 int ast_unreal_sendtext(struct ast_channel *ast, const char *text);
148
149 /*! Unreal channel framework struct ast_channel_tech.queryoption callback */
150 int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen);
151
152 /*! Unreal channel framework struct ast_channel_tech.setoption callback */
153 int ast_unreal_setoption(struct ast_channel *chan, int option, void *data, int datalen);
154
155 /*!
156  * \brief struct ast_unreal_pvt destructor.
157  * \since 12.0.0
158  *
159  * \param vdoomed Object to destroy.
160  *
161  * \return Nothing
162  */
163 void ast_unreal_destructor(void *vdoomed);
164
165 /*!
166  * \brief Allocate the base unreal struct for a derivative.
167  * \since 12.0.0
168  *
169  * \param size Size of the unreal struct to allocate.
170  * \param destructor Destructor callback.
171  * \param cap Format capabilities to give the unreal private struct.
172  *
173  * \retval pvt on success.
174  * \retval NULL on error.
175  */
176 struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructor, struct ast_format_cap *cap);
177
178 /*!
179  * \brief Create the semi1 and semi2 unreal channels.
180  * \since 12.0.0
181  *
182  * \param p Unreal channel private struct.
183  * \param tech Channel technology to use.
184  * \param semi1_state State to start the semi1(owner) channel in.
185  * \param semi2_state State to start the semi2(outgoing chan) channel in.
186  * \param exten Exten to start the chennels in. (NULL if s)
187  * \param context Context to start the channels in. (NULL if default)
188  * \param requestor Channel requesting creation. (NULL if none)
189  * \param callid Thread callid to use.
190  *
191  * \retval semi1_channel on success.
192  * \retval NULL on error.
193  */
194 struct ast_channel *ast_unreal_new_channels(struct ast_unreal_pvt *p,
195         const struct ast_channel_tech *tech, int semi1_state, int semi2_state,
196         const char *exten, const char *context, const struct ast_channel *requestor,
197         struct ast_callid *callid);
198
199 /*!
200  * \brief Setup unreal owner and chan channels before initiating call.
201  * \since 12.0.0
202  *
203  * \param semi1 Owner channel of unreal channel pair.
204  * \param semi2 Outgoing channel of unreal channel pair.
205  *
206  * \note On entry, the semi1 and semi2 channels are already locked.
207  *
208  * \return Nothing
209  */
210 void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2);
211
212 /*!
213  * \brief Push the semi2 unreal channel into a bridge from either member of the unreal pair
214  * \since 12.0.0
215  *
216  * \param ast A member of the unreal channel being pushed
217  * \param bridge Which bridge we want to push the channel to
218  * \param flags Feature flags to be set on the bridge channel.
219  *
220  * \retval 0 if the channel is successfully imparted onto the bridge
221  * \retval -1 on failure
222  *
223  * \note This is equivalent to ast_call() on unreal based channel drivers that are designed to use it instead.
224  */
225 int ast_unreal_channel_push_to_bridge(struct ast_channel *ast, struct ast_bridge *bridge, unsigned int flags);
226
227 /* ------------------------------------------------------------------- */
228
229 #if defined(__cplusplus) || defined(c_plusplus)
230 }
231 #endif
232
233 #endif  /* _ASTERISK_CORE_UNREAL_H */