2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 1999 - 2006, Digium, Inc.
6 * Mark Spencer <markster@digium.com>
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.
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.
21 * \brief Supports RTP and RTCP with Symmetric RTP support for NAT traversal.
23 * RTP is defined in RFC 3550.
26 #ifndef _ASTERISK_RTP_H
27 #define _ASTERISK_RTP_H
29 #include "asterisk/network.h"
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"
37 #if defined(__cplusplus) || defined(c_plusplus)
41 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
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
51 /*! Maxmum number of payload defintions for a RTP session */
52 #define MAX_RTP_PT 256
54 /*! T.140 Redundancy Maxium number of generations */
55 #define RED_MAX_GENERATION 5
57 #define FLAG_3389_WARNING (1 << 0)
59 enum ast_rtp_options {
60 AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
63 enum ast_rtp_get_result {
64 /*! Failed to find the RTP structure */
65 AST_RTP_GET_FAILED = 0,
66 /*! RTP structure exists but true native bridge can not occur so try partial */
68 /*! RTP structure exists and native bridge can occur */
72 /*! \brief Variables used in ast_rtcp_get function */
73 enum ast_rtp_qos_vars {
84 /*! T.140 Redundancy structure*/
87 /*! \brief The value of each payload format mapping: */
88 struct rtpPayloadType {
89 int isAstFormat; /*!< whether the following code is an AST_FORMAT */
93 /*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem
95 struct ast_rtp_protocol {
96 /*! Get RTP struct, or NULL if unwilling to transfer */
97 enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
98 /*! Get RTP struct, or NULL if unwilling to transfer */
99 enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
100 /*! Get RTP struct, or NULL if unwilling to transfer */
101 enum ast_rtp_get_result (* const get_trtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
103 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);
104 int (* const get_codec)(struct ast_channel *chan);
105 const char * const type;
106 AST_LIST_ENTRY(ast_rtp_protocol) list;
109 enum ast_rtp_quality_type {
116 /*! \brief RTCP quality report storage */
117 struct ast_rtp_quality {
118 unsigned int local_ssrc; /*!< Our SSRC */
119 unsigned int local_lostpackets; /*!< Our lost packets */
120 double local_jitter; /*!< Our calculated jitter */
121 unsigned int local_count; /*!< Number of received packets */
122 unsigned int remote_ssrc; /*!< Their SSRC */
123 unsigned int remote_lostpackets; /*!< Their lost packets */
124 double remote_jitter; /*!< Their reported jitter */
125 unsigned int remote_count; /*!< Number of transmitted packets */
126 double rtt; /*!< Round trip time */
129 /*! RTP callback structure */
130 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
133 * \brief Get the amount of space required to hold an RTP session
134 * \return number of bytes required
136 size_t ast_rtp_alloc_size(void);
139 * \brief Initializate a RTP session.
144 * \param callbackmode
145 * \return A representation (structure) of an RTP session.
147 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
150 * \brief Initializate a RTP session using an in_addr structure.
152 * This fuction gets called by ast_rtp_new().
157 * \param callbackmode
159 * \return A representation (structure) of an RTP session.
161 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
163 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
165 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
166 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
168 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
170 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
172 /*! Destroy RTP session */
173 void ast_rtp_destroy(struct ast_rtp *rtp);
175 void ast_rtp_reset(struct ast_rtp *rtp);
177 /*! Stop RTP session, do not destroy structure */
178 void ast_rtp_stop(struct ast_rtp *rtp);
180 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
182 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
184 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
186 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
188 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
190 int ast_rtp_fd(struct ast_rtp *rtp);
192 int ast_rtcp_fd(struct ast_rtp *rtp);
194 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
196 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
198 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
200 int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int cos, char *desc);
202 void ast_rtp_new_source(struct ast_rtp *rtp);
204 /*! \brief Setting RTP payload types from lines in a SDP description: */
205 void ast_rtp_pt_clear(struct ast_rtp* rtp);
206 /*! \brief Set payload types to defaults */
207 void ast_rtp_pt_default(struct ast_rtp* rtp);
209 /*! \brief Copy payload types between RTP structures */
210 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
212 /*! \brief Activate payload type */
213 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
215 /*! \brief clear payload type */
216 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
218 /*! \brief Set payload type to a known MIME media type for a codec
220 * \param rtp RTP structure to modify
221 * \param pt Payload type entry to modify
222 * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
223 * \param mimeSubtype MIME subtype of media stream (typically a codec name)
224 * \param options Zero or more flags from the ast_rtp_options enum
226 * This function 'fills in' an entry in the list of possible formats for
227 * a media stream associated with an RTP structure.
229 * \retval 0 on success
230 * \retval -1 if the payload type is out of range
231 * \retval -2 if the mimeType/mimeSubtype combination was not found
233 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
234 char *mimeType, char *mimeSubtype,
235 enum ast_rtp_options options);
237 /*! \brief Set payload type to a known MIME media type for a codec with a specific sample rate
239 * \param rtp RTP structure to modify
240 * \param pt Payload type entry to modify
241 * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
242 * \param mimeSubtype MIME subtype of media stream (typically a codec name)
243 * \param options Zero or more flags from the ast_rtp_options enum
244 * \param sample_rate The sample rate of the media stream
246 * This function 'fills in' an entry in the list of possible formats for
247 * a media stream associated with an RTP structure.
249 * \retval 0 on success
250 * \retval -1 if the payload type is out of range
251 * \retval -2 if the mimeType/mimeSubtype combination was not found
253 int ast_rtp_set_rtpmap_type_rate(struct ast_rtp* rtp, int pt,
254 char *mimeType, char *mimeSubtype,
255 enum ast_rtp_options options,
256 unsigned int sample_rate);
258 /*! \brief Mapping between RTP payload format codes and Asterisk codes: */
259 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
260 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
262 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
263 int* astFormats, int* nonAstFormats);
265 /*! \brief Mapping an Asterisk code into a MIME subtype (string): */
266 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
267 enum ast_rtp_options options);
269 /*! \brief Get the sample rate associated with known RTP payload types
271 * \param isAstFormat True if the value in the 'code' parameter is an AST_FORMAT value
272 * \param code Format code, either from AST_FORMAT list or from AST_RTP list
274 * \return the sample rate if the format was found, zero if it was not found
276 unsigned int ast_rtp_lookup_sample_rate(int isAstFormat, int code);
278 /*! \brief Build a string of MIME subtype names from a capability list */
279 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
280 const int isAstFormat, enum ast_rtp_options options);
282 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
284 int ast_rtp_getnat(struct ast_rtp *rtp);
286 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
287 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
289 /*! \brief Compensate for devices that send RFC2833 packets all at once */
290 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
292 /*! \brief Enable STUN capability */
293 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
295 /*! \brief Generic STUN request
296 * send a generic stun request to the server specified.
297 * \param s the socket used to send the request
298 * \param dst the address of the STUN server
299 * \param username if non null, add the username in the request
300 * \param answer if non null, the function waits for a response and
301 * puts here the externally visible address.
302 * \return 0 on success, other values on error.
303 * The interface it may change in the future.
305 int ast_stun_request(int s, struct sockaddr_in *dst,
306 const char *username, struct sockaddr_in *answer);
308 /*! \brief Send STUN request for an RTP socket
309 * Deprecated, this is just a wrapper for ast_rtp_stun_request()
311 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
313 /*! \brief The RTP bridge.
314 \arg \ref AstRTPbridge
316 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
318 /*! \brief Register an RTP channel client */
319 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
321 /*! \brief Unregister an RTP channel client */
322 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
324 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
326 /*! \brief If possible, create an early bridge directly between the devices without
327 having to send a re-invite later */
328 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
330 /*! \brief Get QOS stats on a RTP channel
333 int ast_rtp_get_qos(struct ast_rtp *rtp, const char *qos, char *buf, unsigned int buflen);
335 /*! \brief Return RTP and RTCP QoS values
338 unsigned int ast_rtp_get_qosvalue(struct ast_rtp *rtp, enum ast_rtp_qos_vars value);
340 /*! \brief Set RTPAUDIOQOS(...) variables on a channel when it is being hung up
343 void ast_rtp_set_vars(struct ast_channel *chan, struct ast_rtp *rtp);
345 /*! \brief Return RTCP quality string
347 * \param rtp An rtp structure to get qos information about.
349 * \param qual An (optional) rtp quality structure that will be
350 * filled with the quality information described in
351 * the ast_rtp_quality structure. This structure is
352 * not dependent on any qtype, so a call for any
353 * type of information would yield the same results
354 * because ast_rtp_quality is not a data type
355 * specific to any qos type.
357 * \param qtype The quality type you'd like, default should be
358 * RTPQOS_SUMMARY which returns basic information
359 * about the call. The return from RTPQOS_SUMMARY
360 * is basically ast_rtp_quality in a string. The
361 * other types are RTPQOS_JITTER, RTPQOS_LOSS and
362 * RTPQOS_RTT which will return more specific
364 * \version 1.6.1 added qtype parameter
366 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual, enum ast_rtp_quality_type qtype);
367 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message in SIP */
368 int ast_rtcp_send_h261fur(void *data);
370 void ast_rtp_init(void); /*! Initialize RTP subsystem */
371 int ast_rtp_reload(void); /*! reload rtp configuration */
372 void ast_rtp_new_init(struct ast_rtp *rtp);
374 /*! \brief Set codec preference */
375 void ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
377 /*! \brief Get codec preference */
378 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
380 /*! \brief get format from predefined dynamic payload format */
381 int ast_rtp_codec_getformat(int pt);
383 /*! \brief Set rtp timeout */
384 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
385 /*! \brief Set rtp hold timeout */
386 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
387 /*! \brief set RTP keepalive interval */
388 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
389 /*! \brief Get RTP keepalive interval */
390 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
391 /*! \brief Get rtp hold timeout */
392 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
393 /*! \brief Get rtp timeout */
394 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
395 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
396 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
398 /*! \brief Initalize t.140 redudancy
399 * \param ti time between each t140red frame is sent
400 * \param red_pt payloadtype for RTP packet
401 * \param pt payloadtype numbers for each generation including primary data
402 * \param num_gen number of redundant generations, primary data excluded
405 int rtp_red_init(struct ast_rtp *rtp, int ti, int *pt, int num_gen);
407 /*! \brief Buffer t.140 data */
408 void red_buffer_t140(struct ast_rtp *rtp, struct ast_frame *f);
412 #if defined(__cplusplus) || defined(c_plusplus)
416 #endif /* _ASTERISK_RTP_H */