Asterisk - The Open Source Telephony Project GIT-master-2de1a68
core_unreal.h
Go to the documentation of this file.
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"
36
37#if defined(__cplusplus) || defined(c_plusplus)
38extern "C" {
39#endif
40
41/* Forward declare some struct names */
42struct ast_format_cap;
44
45/* ------------------------------------------------------------------- */
46
47struct ast_unreal_pvt;
48
52};
53
54/*!
55 * \brief Callbacks that can be provided by concrete implementations of the unreal
56 * channel driver that will be called when events occur in the unreal layer
57 */
59 /*!
60 * \brief Called when an optimization attempt has started
61 * \note p is locked when this callback is called
62 * \param p The \ref ast_unreal_pvt object
63 * \param source The channel that is optimizing into an unreal_pvt channel's bridge.
64 * If NULL, the optimization is being accomplished via a bridge merge.
65 * \param dest Indicator of which channel's bridge in the unreal_pvt will survive the
66 * optimization
67 * \param id Unique identifier for this optimization operation.
68 */
69 void (* const optimization_started)(struct ast_unreal_pvt *p, struct ast_channel *source,
70 enum ast_unreal_channel_indicator dest, unsigned int id);
71
72 /*!
73 * \brief Called when an optimization attempt completed successfully
74 * \note p is locked when this callback is called
75 * \param p The \ref ast_unreal_pvt object
76 * \param success Non-zero if the optimization succeeded, zero if the optimization
77 * met with fatal and permanent error
78 * \param id Unique identifier for this optimization. Same as the one from the optimization_started
79 * call
80 */
81 void (* const optimization_finished)(struct ast_unreal_pvt *p, int success, unsigned int id);
82};
83
84/*!
85 * \brief The base pvt structure for local channel derivatives.
86 *
87 * The unreal pvt has two ast_chan objects - the "owner" and the "next channel", the outbound channel
88 *
89 * ast_chan owner -> ast_unreal_pvt -> ast_chan chan
90 */
92 struct ast_unreal_pvt_callbacks *callbacks; /*!< Event callbacks */
93 struct ast_channel *owner; /*!< Master Channel - ;1 side */
94 struct ast_channel *chan; /*!< Outbound channel - ;2 side */
95 struct ast_format_cap *reqcap; /*!< Requested format capabilities */
96 struct ast_jb_conf jb_conf; /*!< jitterbuffer configuration */
97 unsigned int flags; /*!< Private option flags */
98 /*! Base name of the unreal channels. exten\@context or other name. */
100 struct ast_stream_topology *reqtopology; /*!< Requested stream topology */
101 struct ast_stream_topology *owner_old_topology; /*!< Stored topology for owner side when we need to restore later (faxing) */
102 struct ast_stream_topology *chan_old_topology; /*!< Stored topology for chan side when we need to restore later (faxing) */
103};
104
105#define AST_UNREAL_IS_OUTBOUND(a, b) ((a) == (b)->chan ? 1 : 0)
106
107#define AST_UNREAL_CARETAKER_THREAD (1 << 0) /*!< The ;2 side launched a PBX, was pushed into a bridge, or was masqueraded into an application. */
108#define AST_UNREAL_NO_OPTIMIZATION (1 << 1) /*!< Do not optimize out the unreal channels */
109#define AST_UNREAL_MOH_INTERCEPT (1 << 2) /*!< Intercept and act on hold/unhold control frames */
110#define AST_UNREAL_OPTIMIZE_BEGUN (1 << 3) /*!< Indicates that an optimization attempt has been started */
111
112/*!
113 * \brief Send an unreal pvt in with no locks held and get all locks
114 *
115 * \note NO locks should be held prior to calling this function
116 * \note The pvt must have a ref held before calling this function
117 * \note if outchan or outowner is set != NULL after calling this function
118 * those channels are locked and reffed.
119 * \note Batman.
120 */
121void ast_unreal_lock_all(struct ast_unreal_pvt *p, struct ast_channel **outchan, struct ast_channel **outowner);
122
123/*!
124 * \brief Hangup one end (maybe both ends) of an unreal channel derivative.
125 * \since 12.0.0
126 *
127 * \param p Private channel struct (reffed)
128 * \param ast Channel being hung up. (locked)
129 *
130 * \note Common hangup code for unreal channels. Derived
131 * channels will need to deal with any additional resources.
132 *
133 * \retval 0 on success.
134 * \retval -1 on error.
135 */
136int ast_unreal_hangup(struct ast_unreal_pvt *p, struct ast_channel *ast);
137
138/*! Unreal channel framework struct ast_channel_tech.send_digit_begin callback */
139int ast_unreal_digit_begin(struct ast_channel *ast, char digit);
140
141/*! Unreal channel framework struct ast_channel_tech.send_digit_end callback */
142int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration);
143
144/*! Unreal channel framework struct ast_channel_tech.answer callback */
145int ast_unreal_answer(struct ast_channel *ast);
146
147/*! Unreal channel framework struct ast_channel_tech.read and struct ast_channel_tech.exception callback */
148struct ast_frame *ast_unreal_read(struct ast_channel *ast);
149
150/*! Unreal channel framework struct ast_channel_tech.write callback */
151int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f);
152
153/*! Unreal channel framework struct ast_channel_tech.write_stream callback */
154int ast_unreal_write_stream(struct ast_channel *ast, int stream_num, struct ast_frame *f);
155
156/*! Unreal channel framework struct ast_channel_tech.indicate callback */
157int ast_unreal_indicate(struct ast_channel *ast, int condition, const void *data, size_t datalen);
158
159/*! Unreal channel framework struct ast_channel_tech.fixup callback */
160int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan);
161
162/*! Unreal channel framework struct ast_channel_tech.send_html callback */
163int ast_unreal_sendhtml(struct ast_channel *ast, int subclass, const char *data, int datalen);
164
165/*! Unreal channel framework struct ast_channel_tech.send_text callback */
166int ast_unreal_sendtext(struct ast_channel *ast, const char *text);
167
168/*! Unreal channel framework struct ast_channel_tech.queryoption callback */
169int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen);
170
171/*! Unreal channel framework struct ast_channel_tech.setoption callback */
172int ast_unreal_setoption(struct ast_channel *chan, int option, void *data, int datalen);
173
174/*!
175 * \brief struct ast_unreal_pvt destructor.
176 * \since 12.0.0
177 *
178 * \param vdoomed Object to destroy.
179 */
180void ast_unreal_destructor(void *vdoomed);
181
182/*!
183 * \brief Allocate the base unreal struct for a derivative.
184 * \since 12.0.0
185 *
186 * \param size Size of the unreal struct to allocate.
187 * \param destructor Destructor callback.
188 * \param cap Format capabilities to give the unreal private struct.
189 *
190 * \return pvt on success.
191 * \retval NULL on error.
192 */
193struct ast_unreal_pvt *ast_unreal_alloc(size_t size, ao2_destructor_fn destructor, struct ast_format_cap *cap);
194
195/*!
196 * \brief Allocate the base unreal struct for a derivative.
197 * \since 16.12.0
198 * \since 17.6.0
199 *
200 * \param size Size of the unreal struct to allocate.
201 * \param destructor Destructor callback.
202 * \param topology
203 *
204 * \return pvt on success.
205 * \retval NULL on error.
206 */
207struct ast_unreal_pvt *ast_unreal_alloc_stream_topology(size_t size, ao2_destructor_fn destructor, struct ast_stream_topology *topology);
208
209/*!
210 * \brief Create the semi1 and semi2 unreal channels.
211 * \since 12.0.0
212 *
213 * \param p Unreal channel private struct.
214 * \param tech Channel technology to use.
215 * \param semi1_state State to start the semi1(owner) channel in.
216 * \param semi2_state State to start the semi2(outgoing chan) channel in.
217 * \param exten Exten to start the chennels in. (NULL if s)
218 * \param context Context to start the channels in. (NULL if default)
219 * \param assignedids
220 * \param requestor Channel requesting creation. (NULL if none)
221 * \param callid Thread callid to use.
222 *
223 * \return semi1_channel on success.
224 * \retval NULL on error.
225 */
227 const struct ast_channel_tech *tech, int semi1_state, int semi2_state,
228 const char *exten, const char *context, const struct ast_assigned_ids *assignedids,
229 const struct ast_channel *requestor, ast_callid callid);
230
231/*!
232 * \brief Setup unreal owner and chan channels before initiating call.
233 * \since 12.0.0
234 *
235 * \param semi1 Owner channel of unreal channel pair.
236 * \param semi2 Outgoing channel of unreal channel pair.
237 *
238 * \note On entry, the semi1 and semi2 channels are already locked.
239 */
240void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2);
241
242/*!
243 * \brief Push the semi2 unreal channel into a bridge from either member of the unreal pair
244 * \since 12.0.0
245 *
246 * \param ast A member of the unreal channel being pushed
247 * \param bridge Which bridge we want to push the channel to
248 * \param flags Feature flags to be set on the bridge channel.
249 *
250 * \retval 0 if the channel is successfully imparted onto the bridge
251 * \retval -1 on failure
252 *
253 * \note This is equivalent to ast_call() on unreal based channel drivers that are designed to use it instead.
254 */
255int ast_unreal_channel_push_to_bridge(struct ast_channel *ast, struct ast_bridge *bridge, unsigned int flags);
256
257/* ------------------------------------------------------------------- */
258
259#if defined(__cplusplus) || defined(c_plusplus)
260}
261#endif
262
263#endif /* _ASTERISK_CORE_UNREAL_H */
Common implementation-independent jitterbuffer stuff.
char digit
char * text
Definition: app_queue.c:1639
enum queue_result id
Definition: app_queue.c:1638
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
Definition: astobj2.h:358
Bridging API.
General Asterisk PBX channel definitions.
#define AST_MAX_CONTEXT
Definition: channel.h:135
#define AST_MAX_EXTENSION
Definition: channel.h:134
int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration)
Definition: core_unreal.c:801
int ast_unreal_setoption(struct ast_channel *chan, int option, void *data, int datalen)
Definition: core_unreal.c:97
int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen)
Definition: core_unreal.c:166
int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan)
Definition: core_unreal.c:369
int ast_unreal_digit_begin(struct ast_channel *ast, char digit)
Definition: core_unreal.c:779
int ast_unreal_sendhtml(struct ast_channel *ast, int subclass, const char *data, int datalen)
Definition: core_unreal.c:846
void ast_unreal_call_setup(struct ast_channel *semi1, struct ast_channel *semi2)
Setup unreal owner and chan channels before initiating call.
Definition: core_unreal.c:870
void ast_unreal_destructor(void *vdoomed)
struct ast_unreal_pvt destructor.
Definition: core_unreal.c:1097
int ast_unreal_hangup(struct ast_unreal_pvt *p, struct ast_channel *ast)
Hangup one end (maybe both ends) of an unreal channel derivative.
Definition: core_unreal.c:1018
int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f)
Definition: core_unreal.c:318
struct ast_unreal_pvt * ast_unreal_alloc(size_t size, ao2_destructor_fn destructor, struct ast_format_cap *cap)
Allocate the base unreal struct for a derivative.
Definition: core_unreal.c:1109
struct ast_unreal_pvt * ast_unreal_alloc_stream_topology(size_t size, ao2_destructor_fn destructor, struct ast_stream_topology *topology)
Allocate the base unreal struct for a derivative.
Definition: core_unreal.c:1126
int ast_unreal_indicate(struct ast_channel *ast, int condition, const void *data, size_t datalen)
Definition: core_unreal.c:622
int ast_unreal_channel_push_to_bridge(struct ast_channel *ast, struct ast_bridge *bridge, unsigned int flags)
Push the semi2 unreal channel into a bridge from either member of the unreal pair.
Definition: core_unreal.c:928
int ast_unreal_sendtext(struct ast_channel *ast, const char *text)
Definition: core_unreal.c:824
ast_unreal_channel_indicator
Definition: core_unreal.h:49
@ AST_UNREAL_CHAN
Definition: core_unreal.h:51
@ AST_UNREAL_OWNER
Definition: core_unreal.h:50
int ast_unreal_answer(struct ast_channel *ast)
Definition: core_unreal.c:254
int ast_unreal_write_stream(struct ast_channel *ast, int stream_num, struct ast_frame *f)
Definition: core_unreal.c:323
void ast_unreal_lock_all(struct ast_unreal_pvt *p, struct ast_channel **outchan, struct ast_channel **outowner)
Send an unreal pvt in with no locks held and get all locks.
Definition: core_unreal.c:47
struct ast_channel * ast_unreal_new_channels(struct ast_unreal_pvt *p, const struct ast_channel_tech *tech, int semi1_state, int semi2_state, const char *exten, const char *context, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, ast_callid callid)
Create the semi1 and semi2 unreal channels.
Definition: core_unreal.c:1160
struct ast_frame * ast_unreal_read(struct ast_channel *ast)
Definition: core_unreal.c:313
unsigned int ast_callid
Structure to pass both assignedid values to channel drivers.
Definition: channel.h:604
Structure that contains information about a bridge.
Definition: bridge.h:349
Structure to describe a channel "technology", ie a channel driver See for examples:
Definition: channel.h:628
Main Channel structure associated with a channel.
struct ast_bridge * bridge
char exten[AST_MAX_EXTENSION]
const struct ast_channel_tech * tech
struct ast_flags flags
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Data structure associated with a single frame of data.
struct ast_frame_subclass subclass
union ast_frame::@226 data
General jitterbuffer configuration.
Definition: abstract_jb.h:70
Callbacks that can be provided by concrete implementations of the unreal channel driver that will be ...
Definition: core_unreal.h:58
void(*const optimization_started)(struct ast_unreal_pvt *p, struct ast_channel *source, enum ast_unreal_channel_indicator dest, unsigned int id)
Called when an optimization attempt has started.
Definition: core_unreal.h:69
void(*const optimization_finished)(struct ast_unreal_pvt *p, int success, unsigned int id)
Called when an optimization attempt completed successfully.
Definition: core_unreal.h:81
The base pvt structure for local channel derivatives.
Definition: core_unreal.h:91
struct ast_stream_topology * chan_old_topology
Definition: core_unreal.h:102
struct ast_format_cap * reqcap
Definition: core_unreal.h:95
struct ast_channel * chan
Definition: core_unreal.h:94
char name[AST_MAX_EXTENSION+AST_MAX_CONTEXT+2]
Definition: core_unreal.h:99
struct ast_unreal_pvt_callbacks * callbacks
Definition: core_unreal.h:92
struct ast_channel * owner
Definition: core_unreal.h:93
unsigned int flags
Definition: core_unreal.h:97
struct ast_stream_topology * owner_old_topology
Definition: core_unreal.h:101
struct ast_stream_topology * reqtopology
Definition: core_unreal.h:100