2aeefe077643c55d38c181478e0ba98fecd92275
[asterisk/asterisk.git] / include / asterisk / rtp.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, 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 /*!
20  * \file rtp.h
21  * \brief Supports RTP and RTCP with Symmetric RTP support for NAT traversal.
22  *
23  * RTP is defined in RFC 3550.
24  */
25
26 #ifndef _ASTERISK_RTP_H
27 #define _ASTERISK_RTP_H
28
29 #include "asterisk/network.h"
30
31 #include "asterisk/frame.h"
32 #include "asterisk/io.h"
33 #include "asterisk/sched.h"
34 #include "asterisk/channel.h"
35 #include "asterisk/linkedlists.h"
36
37 #if defined(__cplusplus) || defined(c_plusplus)
38 extern "C" {
39 #endif
40
41 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
42 /*! DTMF (RFC2833) */
43 #define AST_RTP_DTMF                    (1 << 0)
44 /*! 'Comfort Noise' (RFC3389) */
45 #define AST_RTP_CN                      (1 << 1)
46 /*! DTMF (Cisco Proprietary) */
47 #define AST_RTP_CISCO_DTMF              (1 << 2)
48 /*! Maximum RTP-specific code */
49 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
50
51 /*! Maxmum number of payload defintions for a RTP session */
52 #define MAX_RTP_PT                      256
53
54 #define FLAG_3389_WARNING               (1 << 0)
55
56 enum ast_rtp_options {
57         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
58 };
59
60 enum ast_rtp_get_result {
61         /*! Failed to find the RTP structure */
62         AST_RTP_GET_FAILED = 0,
63         /*! RTP structure exists but true native bridge can not occur so try partial */
64         AST_RTP_TRY_PARTIAL,
65         /*! RTP structure exists and native bridge can occur */
66         AST_RTP_TRY_NATIVE,
67 };
68
69 struct ast_rtp;
70
71 /*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem 
72 */
73 struct ast_rtp_protocol {
74         /*! Get RTP struct, or NULL if unwilling to transfer */
75         enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
76         /*! Get RTP struct, or NULL if unwilling to transfer */
77         enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
78         /*! Get RTP struct, or NULL if unwilling to transfer */
79         enum ast_rtp_get_result (* const get_trtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
80         /*! Set RTP peer */
81         int (* const set_rtp_peer)(struct ast_channel *chan, struct ast_rtp *peer, struct ast_rtp *vpeer, struct ast_rtp *tpeer, int codecs, int nat_active);
82         int (* const get_codec)(struct ast_channel *chan);
83         const char * const type;
84         AST_LIST_ENTRY(ast_rtp_protocol) list;
85 };
86
87 /*! \brief RTCP quality report storage */
88 struct ast_rtp_quality {
89         unsigned int local_ssrc;          /*!< Our SSRC */
90         unsigned int local_lostpackets;   /*!< Our lost packets */
91         double       local_jitter;        /*!< Our calculated jitter */
92         unsigned int local_count;         /*!< Number of received packets */
93         unsigned int remote_ssrc;         /*!< Their SSRC */
94         unsigned int remote_lostpackets;  /*!< Their lost packets */
95         double       remote_jitter;       /*!< Their reported jitter */
96         unsigned int remote_count;        /*!< Number of transmitted packets */
97         double       rtt;                 /*!< Round trip time */
98 };
99
100 /*! RTP callback structure */
101 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
102
103 /*!
104  * \brief Get the amount of space required to hold an RTP session
105  * \return number of bytes required
106  */
107 size_t ast_rtp_alloc_size(void);
108
109 /*!
110  * \brief Initializate a RTP session.
111  *
112  * \param sched
113  * \param io
114  * \param rtcpenable
115  * \param callbackmode
116  * \returns A representation (structure) of an RTP session.
117  */
118 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
119
120 /*!
121  * \brief Initializate a RTP session using an in_addr structure.
122  *
123  * This fuction gets called by ast_rtp_new().
124  *
125  * \param sched
126  * \param io
127  * \param rtcpenable
128  * \param callbackmode
129  * \param in
130  * \returns A representation (structure) of an RTP session.
131  */
132 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
133
134 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
135
136 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
137 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
138
139 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
140
141 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
142
143 /*! Destroy RTP session */
144 void ast_rtp_destroy(struct ast_rtp *rtp);
145
146 void ast_rtp_reset(struct ast_rtp *rtp);
147
148 /*! Stop RTP session, do not destroy structure */
149 void ast_rtp_stop(struct ast_rtp *rtp);
150
151 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
152
153 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
154
155 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
156
157 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
158
159 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
160
161 int ast_rtp_fd(struct ast_rtp *rtp);
162
163 int ast_rtcp_fd(struct ast_rtp *rtp);
164
165 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
166
167 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
168
169 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
170
171 int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int cos);
172
173 /*! \brief  Setting RTP payload types from lines in a SDP description: */
174 void ast_rtp_pt_clear(struct ast_rtp* rtp);
175 /*! \brief Set payload types to defaults */
176 void ast_rtp_pt_default(struct ast_rtp* rtp);
177
178 /*! \brief Copy payload types between RTP structures */
179 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
180
181 /*! \brief Activate payload type */
182 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
183
184 /*! \brief clear payload type */
185 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
186
187 /*! \brief Initiate payload type to a known MIME media type for a codec */
188 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
189                              char *mimeType, char *mimeSubtype,
190                              enum ast_rtp_options options);
191
192 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
193 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
194 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
195
196 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
197                              int* astFormats, int* nonAstFormats);
198
199 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
200 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
201                                         enum ast_rtp_options options);
202
203 /*! \brief Build a string of MIME subtype names from a capability list */
204 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
205                                    const int isAstFormat, enum ast_rtp_options options);
206
207 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
208
209 int ast_rtp_getnat(struct ast_rtp *rtp);
210
211 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
212 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
213
214 /*! \brief Compensate for devices that send RFC2833 packets all at once */
215 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
216
217 /*! \brief Enable STUN capability */
218 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
219
220 /*! \brief Generic STUN request
221  * send a generic stun request to the server specified.
222  * \param s the socket used to send the request
223  * \param dst the address of the STUN server
224  * \param username if non null, add the username in the request
225  * \param answer if non null, the function waits for a response and
226  *    puts here the externally visible address.
227  * \return 0 on success, other values on error.
228  * The interface it may change in the future.
229  */
230 int ast_stun_request(int s, struct sockaddr_in *dst,
231         const char *username, struct sockaddr_in *answer);
232
233 /*! \brief Send STUN request for an RTP socket
234  * Deprecated, this is just a wrapper for ast_rtp_stun_request()
235  */
236 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
237
238 /*! \brief The RTP bridge.
239         \arg \ref AstRTPbridge
240 */
241 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
242
243 /*! \brief Register an RTP channel client */
244 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
245
246 /*! \brief Unregister an RTP channel client */
247 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
248
249 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
250
251 /*! \brief If possible, create an early bridge directly between the devices without
252            having to send a re-invite later */
253 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
254
255 /*! \brief Return RTCP quality string */
256 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual);
257
258 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
259 int ast_rtcp_send_h261fur(void *data);
260
261 void ast_rtp_init(void);                                      /*! Initialize RTP subsystem */
262 int ast_rtp_reload(void);                                     /*! reload rtp configuration */
263 void ast_rtp_new_init(struct ast_rtp *rtp);
264
265 /*! Set codec preference */
266 int ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
267
268 /*! Get codec preference */
269 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
270
271 /*! get format from predefined dynamic payload format */
272 int ast_rtp_codec_getformat(int pt);
273
274 /*! \brief Set rtp timeout */
275 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
276 /*! \brief Set rtp hold timeout */
277 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
278 /*! \brief set RTP keepalive interval */
279 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
280 /*! \brief Get RTP keepalive interval */
281 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
282 /*! \brief Get rtp hold timeout */
283 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
284 /*! \brief Get rtp timeout */
285 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
286 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
287 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
288
289 #if defined(__cplusplus) || defined(c_plusplus)
290 }
291 #endif
292
293 #endif /* _ASTERISK_RTP_H */