c332159ecca6ef12651bd3148f6ee81077f789c8
[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 <netinet/in.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 #define MAX_RTP_PT                      256
52
53 enum ast_rtp_options {
54         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
55 };
56
57 enum ast_rtp_get_result {
58         /*! Failed to find the RTP structure */
59         AST_RTP_GET_FAILED = 0,
60         /*! RTP structure exists but true native bridge can not occur so try partial */
61         AST_RTP_TRY_PARTIAL,
62         /*! RTP structure exists and native bridge can occur */
63         AST_RTP_TRY_NATIVE,
64 };
65
66 struct ast_rtp;
67
68 struct ast_rtp_protocol {
69         /*! Get RTP struct, or NULL if unwilling to transfer */
70         enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
71         /*! Get RTP struct, or NULL if unwilling to transfer */
72         enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
73         /*! Set RTP peer */
74         int (* const set_rtp_peer)(struct ast_channel *chan, struct ast_rtp *peer, struct ast_rtp *vpeer, int codecs, int nat_active);
75         int (* const get_codec)(struct ast_channel *chan);
76         const char * const type;
77         AST_LIST_ENTRY(ast_rtp_protocol) list;
78 };
79
80
81 #define FLAG_3389_WARNING               (1 << 0)
82
83 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
84
85 /*!
86  * \brief Get the amount of space required to hold an RTP session
87  * \return number of bytes required
88  */
89 size_t ast_rtp_alloc_size(void);
90
91 /*!
92  * \brief Initializate a RTP session.
93  *
94  * \param sched
95  * \param io
96  * \param rtcpenable
97  * \param callbackmode
98  * \returns A representation (structure) of an RTP session.
99  */
100 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
101
102 /*!
103  * \brief Initializate a RTP session using an in_addr structure.
104  *
105  * This fuction gets called by ast_rtp_new().
106  *
107  * \param sched
108  * \param io
109  * \param rtcpenable
110  * \param callbackmode
111  * \param in
112  * \returns A representation (structure) of an RTP session.
113  */
114 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
115
116 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
117
118 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
119 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
120
121 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
122
123 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
124
125 void ast_rtp_destroy(struct ast_rtp *rtp);
126
127 void ast_rtp_reset(struct ast_rtp *rtp);
128
129 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
130
131 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
132
133 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
134
135 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
136
137 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
138
139 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
140
141 int ast_rtp_fd(struct ast_rtp *rtp);
142
143 int ast_rtcp_fd(struct ast_rtp *rtp);
144
145 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
146
147 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
148
149 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
150
151 int ast_rtp_settos(struct ast_rtp *rtp, int tos);
152
153 /*! \brief  Setting RTP payload types from lines in a SDP description: */
154 void ast_rtp_pt_clear(struct ast_rtp* rtp);
155 /*! \brief Set payload types to defaults */
156 void ast_rtp_pt_default(struct ast_rtp* rtp);
157
158 /*! \brief Copy payload types between RTP structures */
159 void ast_rtp_pt_copy(struct ast_rtp *dest, const struct ast_rtp *src);
160
161 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
162 void ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
163                              char *mimeType, char *mimeSubtype,
164                              enum ast_rtp_options options);
165
166 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
167 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
168 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
169
170 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
171                              int* astFormats, int* nonAstFormats);
172
173 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
174 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
175                                         enum ast_rtp_options options);
176
177 /*! \brief Build a string of MIME subtype names from a capability list */
178 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
179                                    const int isAstFormat, enum ast_rtp_options options);
180
181 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
182
183 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
184 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
185
186 /*! \brief Compensate for devices that send RFC2833 packets all at once */
187 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
188
189 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
190
191 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
192
193 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
194
195 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
196
197 /*! \brief If possible, create an early bridge directly between the devices without
198            having to send a re-invite later */
199 int ast_rtp_early_bridge(struct ast_channel *dest, struct ast_channel *src);
200
201 void ast_rtp_stop(struct ast_rtp *rtp);
202
203 /*! \brief Return RTCP quality string */
204 char *ast_rtp_get_quality(struct ast_rtp *rtp);
205
206 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
207 int ast_rtcp_send_h261fur(void *data);
208
209 void ast_rtp_init(void);
210
211 int ast_rtp_reload(void);
212
213 int ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
214
215 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
216
217 int ast_rtp_codec_getformat(int pt);
218
219 #if defined(__cplusplus) || defined(c_plusplus)
220 }
221 #endif
222
223 #endif /* _ASTERISK_RTP_H */