Asterisk - The Open Source Telephony Project  21.4.1
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"
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_stream_topology;
44 
45 /* ------------------------------------------------------------------- */
46 
47 struct ast_unreal_pvt;
48 
49 enum ast_unreal_channel_indicator {
50  AST_UNREAL_OWNER,
51  AST_UNREAL_CHAN,
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  */
121 void 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  */
136 int 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 */
139 int ast_unreal_digit_begin(struct ast_channel *ast, char digit);
140 
141 /*! Unreal channel framework struct ast_channel_tech.send_digit_end callback */
142 int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration);
143 
144 /*! Unreal channel framework struct ast_channel_tech.answer callback */
145 int ast_unreal_answer(struct ast_channel *ast);
146 
147 /*! Unreal channel framework struct ast_channel_tech.read and struct ast_channel_tech.exception callback */
148 struct ast_frame *ast_unreal_read(struct ast_channel *ast);
149 
150 /*! Unreal channel framework struct ast_channel_tech.write callback */
151 int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f);
152 
153 /*! Unreal channel framework struct ast_channel_tech.write_stream callback */
154 int 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 */
157 int 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 */
160 int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan);
161 
162 /*! Unreal channel framework struct ast_channel_tech.send_html callback */
163 int 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 */
166 int ast_unreal_sendtext(struct ast_channel *ast, const char *text);
167 
168 /*! Unreal channel framework struct ast_channel_tech.queryoption callback */
169 int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen);
170 
171 /*! Unreal channel framework struct ast_channel_tech.setoption callback */
172 int 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  */
180 void 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  */
193 struct 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  */
207 struct 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  */
240 void 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  */
255 int 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 */
Main Channel structure associated with a channel.
struct ast_flags flags
struct ast_unreal_pvt_callbacks * callbacks
Definition: core_unreal.h:92
char context[AST_MAX_CONTEXT]
struct ast_channel * owner
Definition: core_unreal.h:93
int ast_unreal_sendhtml(struct ast_channel *ast, int subclass, const char *data, int datalen)
Definition: core_unreal.c:846
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
Structure to pass both assignedid values to channel drivers.
Definition: channel.h:604
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
int ast_unreal_indicate(struct ast_channel *ast, int condition, const void *data, size_t datalen)
Definition: core_unreal.c:622
Common implementation-independent jitterbuffer stuff.
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
struct ast_frame_subclass subclass
int ast_unreal_fixup(struct ast_channel *oldchan, struct ast_channel *newchan)
Definition: core_unreal.c:369
const struct ast_channel_tech * tech
struct ast_stream_topology * chan_old_topology
Definition: core_unreal.h:102
General Asterisk PBX channel definitions.
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 ast_unreal_destructor(void *vdoomed)
struct ast_unreal_pvt destructor.
Definition: core_unreal.c:1097
#define AST_MAX_EXTENSION
Definition: channel.h:134
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_setoption(struct ast_channel *chan, int option, void *data, int datalen)
Definition: core_unreal.c:97
Structure to describe a channel "technology", ie a channel driver See for examples: ...
Definition: channel.h:628
struct ast_stream_topology * owner_old_topology
Definition: core_unreal.h:101
struct ast_channel * chan
Definition: core_unreal.h:94
struct ast_format_cap * reqcap
Definition: core_unreal.h:95
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
Structure that contains information about a bridge.
Definition: bridge.h:349
int ast_unreal_write(struct ast_channel *ast, struct ast_frame *f)
Definition: core_unreal.c:318
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
int ast_unreal_digit_begin(struct ast_channel *ast, char digit)
Definition: core_unreal.c:779
char name[AST_MAX_EXTENSION+AST_MAX_CONTEXT+2]
Definition: core_unreal.h:99
void(* ao2_destructor_fn)(void *vdoomed)
Typedef for an object destructor.
Definition: astobj2.h:358
The base pvt structure for local channel derivatives.
Definition: core_unreal.h:91
int ast_unreal_write_stream(struct ast_channel *ast, int stream_num, struct ast_frame *f)
Definition: core_unreal.c:323
struct ast_bridge * bridge
int ast_unreal_digit_end(struct ast_channel *ast, char digit, unsigned int duration)
Definition: core_unreal.c:801
#define AST_MAX_CONTEXT
Definition: channel.h:135
union ast_frame::@224 data
struct ast_frame * ast_unreal_read(struct ast_channel *ast)
Definition: core_unreal.c:313
unsigned int flags
Definition: core_unreal.h:97
int ast_unreal_queryoption(struct ast_channel *ast, int option, void *data, int *datalen)
Definition: core_unreal.c:166
int ast_unreal_answer(struct ast_channel *ast)
Definition: core_unreal.c:254
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
Data structure associated with a single frame of data.
Bridging API.
Callbacks that can be provided by concrete implementations of the unreal channel driver that will be ...
Definition: core_unreal.h:58
struct ast_stream_topology * reqtopology
Definition: core_unreal.h:100
General jitterbuffer configuration.
Definition: abstract_jb.h:69
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
char exten[AST_MAX_EXTENSION]
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
int ast_unreal_sendtext(struct ast_channel *ast, const char *text)
Definition: core_unreal.c:824