Add support for DTLS-SRTP to res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / include / asterisk / rtp_engine.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2009, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  * Joshua Colp <jcolp@digium.com>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19
20 /*! \file
21  * \brief Pluggable RTP Architecture
22  * \author Joshua Colp <jcolp@digium.com>
23  * \ref AstRTPEngine
24  */
25
26 /*!
27  * \page AstRTPEngine Asterisk RTP Engine API
28  *
29  * The purpose of this API is to provide a way for multiple RTP stacks to be
30  * used inside of Asterisk without any module that uses RTP knowing any
31  * different. To the module each RTP stack behaves the same.
32  *
33  * An RTP session is called an instance and is made up of a combination of codec
34  * information, RTP engine, RTP properties, and address information. An engine
35  * name may be passed in to explicitly choose an RTP stack to be used but a
36  * default one will be used if none is provided. An address to use for RTP may
37  * also be provided but the underlying RTP engine may choose a different address
38  * depending on it's configuration.
39  *
40  * An RTP engine is the layer between the RTP engine core and the RTP stack
41  * itself. The RTP engine core provides a set of callbacks to do various things
42  * (such as write audio out) that the RTP engine has to have implemented.
43  *
44  * Glue is what binds an RTP instance to a channel. It is used to retrieve RTP
45  * instance information when performing remote or local bridging and is used to
46  * have the channel driver tell the remote side to change destination of the RTP
47  * stream.
48  *
49  * Statistics from an RTP instance can be retrieved using the
50  * ast_rtp_instance_get_stats API call. This essentially asks the RTP engine in
51  * use to fill in a structure with the requested values. It is not required for
52  * an RTP engine to support all statistic values.
53  *
54  * Properties allow behavior of the RTP engine and RTP engine core to be
55  * changed. For example, there is a property named AST_RTP_PROPERTY_NAT which is
56  * used to tell the RTP engine to enable symmetric RTP if it supports it. It is
57  * not required for an RTP engine to support all properties.
58  *
59  * Codec information is stored using a separate data structure which has it's
60  * own set of API calls to add/remove/retrieve information. They are used by the
61  * module after an RTP instance is created so that payload information is
62  * available for the RTP engine.
63  */
64
65 #ifndef _ASTERISK_RTP_ENGINE_H
66 #define _ASTERISK_RTP_ENGINE_H
67
68 #if defined(__cplusplus) || defined(c_plusplus)
69 extern "C" {
70 #endif
71
72 #include "asterisk/astobj2.h"
73 #include "asterisk/frame.h"
74 #include "asterisk/netsock2.h"
75 #include "asterisk/sched.h"
76 #include "asterisk/res_srtp.h"
77
78 /* Maximum number of payloads supported */
79 #if defined(LOW_MEMORY)
80 #define AST_RTP_MAX_PT 128
81 #else
82 #define AST_RTP_MAX_PT 196
83 #endif
84
85 /* Maximum number of generations */
86 #define AST_RED_MAX_GENERATION 5
87
88 struct ast_rtp_instance;
89 struct ast_rtp_glue;
90
91 /*! RTP Properties that can be set on an RTP instance */
92 enum ast_rtp_property {
93         /*! Enable symmetric RTP support */
94         AST_RTP_PROPERTY_NAT = 0,
95         /*! RTP instance will be carrying DTMF (using RFC2833) */
96         AST_RTP_PROPERTY_DTMF,
97         /*! Expect unreliable DTMF from remote party */
98         AST_RTP_PROPERTY_DTMF_COMPENSATE,
99         /*! Enable STUN support */
100         AST_RTP_PROPERTY_STUN,
101         /*! Enable RTCP support */
102         AST_RTP_PROPERTY_RTCP,
103
104         /*!
105          * \brief Maximum number of RTP properties supported
106          *
107          * \note THIS MUST BE THE LAST ENTRY IN THIS ENUM.
108          */
109         AST_RTP_PROPERTY_MAX,
110 };
111
112 /*! Additional RTP options */
113 enum ast_rtp_options {
114         /*! Remote side is using non-standard G.726 */
115         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
116 };
117
118 /*! RTP DTMF Modes */
119 enum ast_rtp_dtmf_mode {
120         /*! No DTMF is being carried over the RTP stream */
121         AST_RTP_DTMF_MODE_NONE = 0,
122         /*! DTMF is being carried out of band using RFC2833 */
123         AST_RTP_DTMF_MODE_RFC2833,
124         /*! DTMF is being carried inband over the RTP stream */
125         AST_RTP_DTMF_MODE_INBAND,
126 };
127
128 /*! Result codes when RTP glue is queried for information */
129 enum ast_rtp_glue_result {
130         /*! No remote or local bridging is permitted */
131         AST_RTP_GLUE_RESULT_FORBID = 0,
132         /*! Move RTP stream to be remote between devices directly */
133         AST_RTP_GLUE_RESULT_REMOTE,
134         /*! Perform RTP engine level bridging if possible */
135         AST_RTP_GLUE_RESULT_LOCAL,
136 };
137
138 /*! Field statistics that can be retrieved from an RTP instance */
139 enum ast_rtp_instance_stat_field {
140         /*! Retrieve quality information */
141         AST_RTP_INSTANCE_STAT_FIELD_QUALITY = 0,
142         /*! Retrieve quality information about jitter */
143         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_JITTER,
144         /*! Retrieve quality information about packet loss */
145         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_LOSS,
146         /*! Retrieve quality information about round trip time */
147         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_RTT,
148 };
149
150 /*! Statistics that can be retrieved from an RTP instance */
151 enum ast_rtp_instance_stat {
152         /*! Retrieve all statistics */
153         AST_RTP_INSTANCE_STAT_ALL = 0,
154         /*! Retrieve number of packets transmitted */
155         AST_RTP_INSTANCE_STAT_TXCOUNT,
156         /*! Retrieve number of packets received */
157         AST_RTP_INSTANCE_STAT_RXCOUNT,
158         /*! Retrieve ALL statistics relating to packet loss */
159         AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
160         /*! Retrieve number of packets lost for transmitting */
161         AST_RTP_INSTANCE_STAT_TXPLOSS,
162         /*! Retrieve number of packets lost for receiving */
163         AST_RTP_INSTANCE_STAT_RXPLOSS,
164         /*! Retrieve maximum number of packets lost on remote side */
165         AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
166         /*! Retrieve minimum number of packets lost on remote side */
167         AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
168         /*! Retrieve average number of packets lost on remote side */
169         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
170         /*! Retrieve standard deviation of packets lost on remote side */
171         AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
172         /*! Retrieve maximum number of packets lost on local side */
173         AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
174         /*! Retrieve minimum number of packets lost on local side */
175         AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
176         /*! Retrieve average number of packets lost on local side */
177         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
178         /*! Retrieve standard deviation of packets lost on local side */
179         AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
180         /*! Retrieve ALL statistics relating to jitter */
181         AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
182         /*! Retrieve jitter on transmitted packets */
183         AST_RTP_INSTANCE_STAT_TXJITTER,
184         /*! Retrieve jitter on received packets */
185         AST_RTP_INSTANCE_STAT_RXJITTER,
186         /*! Retrieve maximum jitter on remote side */
187         AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
188         /*! Retrieve minimum jitter on remote side */
189         AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
190         /*! Retrieve average jitter on remote side */
191         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
192         /*! Retrieve standard deviation jitter on remote side */
193         AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
194         /*! Retrieve maximum jitter on local side */
195         AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
196         /*! Retrieve minimum jitter on local side */
197         AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
198         /*! Retrieve average jitter on local side */
199         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
200         /*! Retrieve standard deviation jitter on local side */
201         AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
202         /*! Retrieve ALL statistics relating to round trip time */
203         AST_RTP_INSTANCE_STAT_COMBINED_RTT,
204         /*! Retrieve round trip time */
205         AST_RTP_INSTANCE_STAT_RTT,
206         /*! Retrieve maximum round trip time */
207         AST_RTP_INSTANCE_STAT_MAX_RTT,
208         /*! Retrieve minimum round trip time */
209         AST_RTP_INSTANCE_STAT_MIN_RTT,
210         /*! Retrieve average round trip time */
211         AST_RTP_INSTANCE_STAT_NORMDEVRTT,
212         /*! Retrieve standard deviation round trip time */
213         AST_RTP_INSTANCE_STAT_STDEVRTT,
214         /*! Retrieve local SSRC */
215         AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
216         /*! Retrieve remote SSRC */
217         AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
218 };
219
220 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
221 /*! DTMF (RFC2833) */
222 #define AST_RTP_DTMF                    (1 << 0)
223 /*! 'Comfort Noise' (RFC3389) */
224 #define AST_RTP_CN                      (1 << 1)
225 /*! DTMF (Cisco Proprietary) */
226 #define AST_RTP_CISCO_DTMF              (1 << 2)
227 /*! Maximum RTP-specific code */
228 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
229
230 /*! Structure that represents a payload */
231 struct ast_rtp_payload_type {
232         /*! Is this an Asterisk value */
233         int asterisk_format;
234         /*! If asterisk_format is set, this is the internal
235          * asterisk format represented by the payload */
236         struct ast_format format;
237         /*! Actual internal RTP specific value of the payload */
238         int rtp_code;
239         /*! Actual payload number */
240         int payload;
241 };
242
243 /*! Structure that represents statistics from an RTP instance */
244 struct ast_rtp_instance_stats {
245         /*! Number of packets transmitted */
246         unsigned int txcount;
247         /*! Number of packets received */
248         unsigned int rxcount;
249         /*! Jitter on transmitted packets */
250         double txjitter;
251         /*! Jitter on received packets */
252         double rxjitter;
253         /*! Maximum jitter on remote side */
254         double remote_maxjitter;
255         /*! Minimum jitter on remote side */
256         double remote_minjitter;
257         /*! Average jitter on remote side */
258         double remote_normdevjitter;
259         /*! Standard deviation jitter on remote side */
260         double remote_stdevjitter;
261         /*! Maximum jitter on local side */
262         double local_maxjitter;
263         /*! Minimum jitter on local side */
264         double local_minjitter;
265         /*! Average jitter on local side */
266         double local_normdevjitter;
267         /*! Standard deviation jitter on local side */
268         double local_stdevjitter;
269         /*! Number of transmitted packets lost */
270         unsigned int txploss;
271         /*! Number of received packets lost */
272         unsigned int rxploss;
273         /*! Maximum number of packets lost on remote side */
274         double remote_maxrxploss;
275         /*! Minimum number of packets lost on remote side */
276         double remote_minrxploss;
277         /*! Average number of packets lost on remote side */
278         double remote_normdevrxploss;
279         /*! Standard deviation packets lost on remote side */
280         double remote_stdevrxploss;
281         /*! Maximum number of packets lost on local side */
282         double local_maxrxploss;
283         /*! Minimum number of packets lost on local side */
284         double local_minrxploss;
285         /*! Average number of packets lost on local side */
286         double local_normdevrxploss;
287         /*! Standard deviation packets lost on local side */
288         double local_stdevrxploss;
289         /*! Total round trip time */
290         double rtt;
291         /*! Maximum round trip time */
292         double maxrtt;
293         /*! Minimum round trip time */
294         double minrtt;
295         /*! Average round trip time */
296         double normdevrtt;
297         /*! Standard deviation round trip time */
298         double stdevrtt;
299         /*! Our SSRC */
300         unsigned int local_ssrc;
301         /*! Their SSRC */
302         unsigned int remote_ssrc;
303 };
304
305 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
306 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
307 placement = value; \
308 if (stat == current_stat) { \
309 return 0; \
310 } \
311 }
312
313 #define AST_RTP_STAT_TERMINATOR(combined) \
314 if (stat == combined) { \
315 return 0; \
316 }
317
318 /*! \brief ICE candidate types */
319 enum ast_rtp_ice_candidate_type {
320         AST_RTP_ICE_CANDIDATE_TYPE_HOST,    /*!< ICE host candidate. A host candidate represents the actual local transport address in the host. */
321         AST_RTP_ICE_CANDIDATE_TYPE_SRFLX,   /*!< ICE server reflexive candidate, which represents the public mapped address of the local address. */
322         AST_RTP_ICE_CANDIDATE_TYPE_RELAYED, /*!< ICE relayed candidate, which represents the address allocated in TURN server. */
323 };
324
325 /*! \brief Structure for an ICE candidate */
326 struct ast_rtp_engine_ice_candidate {
327         char *foundation;                     /*!< Foundation identifier */
328         unsigned int id;                      /*!< Component identifier */
329         char *transport;                      /*!< Transport for the media */
330         int priority;                         /*!< Priority which is used if multiple candidates can be used */
331         struct ast_sockaddr address;          /*!< Address of the candidate */
332         struct ast_sockaddr relay_address;    /*!< Relay address for the candidate */
333         enum ast_rtp_ice_candidate_type type; /*!< Type of candidate */
334 };
335
336 /*! \brief Structure that represents the optional ICE support within an RTP engine */
337 struct ast_rtp_engine_ice {
338         /*! Callback for setting received authentication information */
339         void (*set_authentication)(struct ast_rtp_instance *instance, const char *ufrag, const char *password);
340         /*! Callback for adding a remote candidate */
341         void (*add_remote_candidate)(struct ast_rtp_instance *instance, const struct ast_rtp_engine_ice_candidate *candidate);
342         /*! Callback for starting ICE negotiation */
343         void (*start)(struct ast_rtp_instance *instance);
344         /*! Callback for stopping ICE support */
345         void (*stop)(struct ast_rtp_instance *instance);
346         /*! Callback for getting local username */
347         const char *(*get_ufrag)(struct ast_rtp_instance *instance);
348         /*! Callback for getting local password */
349         const char *(*get_password)(struct ast_rtp_instance *instance);
350         /*! Callback for getting local candidates */
351         struct ao2_container *(*get_local_candidates)(struct ast_rtp_instance *instance);
352         /*! Callback for telling the ICE support that it is talking to an ice-lite implementation */
353         void (*ice_lite)(struct ast_rtp_instance *instance);
354 };
355
356 /*! \brief DTLS setup types */
357 enum ast_rtp_dtls_setup {
358         AST_RTP_DTLS_SETUP_ACTIVE,   /*!< Endpoint is willing to inititate connections */
359         AST_RTP_DTLS_SETUP_PASSIVE,  /*!< Endpoint is willing to accept connections */
360         AST_RTP_DTLS_SETUP_ACTPASS,  /*!< Endpoint is willing to both accept and initiate connections */
361         AST_RTP_DTLS_SETUP_HOLDCONN, /*!< Endpoint does not want the connection to be established right now */
362 };
363
364 /*! \brief DTLS connection states */
365 enum ast_rtp_dtls_connection {
366         AST_RTP_DTLS_CONNECTION_NEW,      /*!< Endpoint wants to use a new connection */
367         AST_RTP_DTLS_CONNECTION_EXISTING, /*!< Endpoint wishes to use existing connection */
368 };
369
370 /*! \brief DTLS fingerprint hashes */
371 enum ast_rtp_dtls_hash {
372         AST_RTP_DTLS_HASH_SHA1, /*!< SHA-1 fingerprint hash */
373 };
374
375 /*! \brief DTLS configuration structure */
376 struct ast_rtp_dtls_cfg {
377         unsigned int enabled:1;                /*!< Whether DTLS support is enabled or not */
378         unsigned int verify:1;                 /*!< Whether to request and verify a client certificate when acting as server */
379         unsigned int rekey;                    /*!< Interval at which to renegotiate and rekey - defaults to 0 (off) */
380         enum ast_rtp_dtls_setup default_setup; /*!< Default setup type to use for outgoing */
381         enum ast_srtp_suite suite;             /*!< Crypto suite in use */
382         char *certfile;                        /*!< Certificate file */
383         char *pvtfile;                         /*!< Private key file */
384         char *cipher;                          /*!< Cipher to use */
385         char *cafile;                          /*!< Certificate authority file */
386         char *capath;                          /*!< Path to certificate authority */
387 };
388
389 /*! \brief Structure that represents the optional DTLS SRTP support within an RTP engine */
390 struct ast_rtp_engine_dtls {
391         /*! Set the configuration of the DTLS support on the instance */
392         int (*set_configuration)(struct ast_rtp_instance *instance, const struct ast_rtp_dtls_cfg *dtls_cfg);
393         /*! Get if the DTLS SRTP support is active or not */
394         int (*active)(struct ast_rtp_instance *instance);
395         /*! Stop and terminate DTLS SRTP support */
396         void (*stop)(struct ast_rtp_instance *instance);
397         /*! Reset the connection and start fresh */
398         void (*reset)(struct ast_rtp_instance *instance);
399         /*! Get the current connection state */
400         enum ast_rtp_dtls_connection (*get_connection)(struct ast_rtp_instance *instance);
401         /*! Get the current setup state */
402         enum ast_rtp_dtls_setup (*get_setup)(struct ast_rtp_instance *instance);
403         /*! Set the remote setup state */
404         void (*set_setup)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_setup setup);
405         /*! Set the remote fingerprint */
406         void (*set_fingerprint)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_hash hash, const char *fingerprint);
407         /*! Get the local fingerprint */
408         const char *(*get_fingerprint)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_hash hash);
409 };
410
411 /*! Structure that represents an RTP stack (engine) */
412 struct ast_rtp_engine {
413         /*! Name of the RTP engine, used when explicitly requested */
414         const char *name;
415         /*! Module this RTP engine came from, used for reference counting */
416         struct ast_module *mod;
417         /*! Callback for setting up a new RTP instance */
418         int (*new)(struct ast_rtp_instance *instance, struct ast_sched_context *sched, struct ast_sockaddr *sa, void *data);
419         /*! Callback for destroying an RTP instance */
420         int (*destroy)(struct ast_rtp_instance *instance);
421         /*! Callback for writing out a frame */
422         int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
423         /*! Callback for stopping the RTP instance */
424         void (*stop)(struct ast_rtp_instance *instance);
425         /*! Callback for starting RFC2833 DTMF transmission */
426         int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
427         /*! Callback for stopping RFC2833 DTMF transmission */
428         int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
429         int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
430         /*! Callback to indicate that we should update the marker bit */
431         void (*update_source)(struct ast_rtp_instance *instance);
432         /*! Callback to indicate that we should update the marker bit and ssrc */
433         void (*change_source)(struct ast_rtp_instance *instance);
434         /*! Callback for setting an extended RTP property */
435         int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
436         /*! Callback for getting an extended RTP property */
437         void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
438         /*! Callback for setting an RTP property */
439         void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
440         /*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
441         void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
442         /*! Callback for setting packetization preferences */
443         void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
444         /*! Callback for setting the remote address that RTP is to be sent to */
445         void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
446         /*! Callback for setting an alternate remote address */
447         void (*alt_remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
448         /*! Callback for changing DTMF mode */
449         int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
450         /*! Callback for getting DTMF mode */
451         enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
452         /*! Callback for retrieving statistics */
453         int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
454         /*! Callback for setting QoS values */
455         int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
456         /*! Callback for retrieving a file descriptor to poll on, not always required */
457         int (*fd)(struct ast_rtp_instance *instance, int rtcp);
458         /*! Callback for initializing RED support */
459         int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
460         /*! Callback for buffering a frame using RED */
461         int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
462         /*! Callback for reading a frame from the RTP engine */
463         struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
464         /*! Callback to locally bridge two RTP instances */
465         int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
466         /*! Callback to set the read format */
467         int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
468         /*! Callback to set the write format */
469         int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
470         /*! Callback to make two instances compatible */
471         int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
472         /*! Callback to see if two instances are compatible with DTMF */
473         int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
474         /*! Callback to indicate that packets will now flow */
475         int (*activate)(struct ast_rtp_instance *instance);
476         /*! Callback to request that the RTP engine send a STUN BIND request */
477         void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
478         /*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
479         void (*available_formats)(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
480         /*! Callback to send CNG */
481         int (*sendcng)(struct ast_rtp_instance *instance, int level);
482         /*! Callback to pointer for optional ICE support */
483         struct ast_rtp_engine_ice *ice;
484         /*! Callback to pointer for optional DTLS SRTP support */
485         struct ast_rtp_engine_dtls *dtls;
486         /*! Linked list information */
487         AST_RWLIST_ENTRY(ast_rtp_engine) entry;
488 };
489
490 /*! Structure that represents codec and packetization information */
491 struct ast_rtp_codecs {
492         /*! Payloads present */
493         struct ao2_container *payloads;
494         /*! Codec packetization preferences */
495         struct ast_codec_pref pref;
496 };
497
498 /*! Structure that represents the glue that binds an RTP instance to a channel */
499 struct ast_rtp_glue {
500         /*! Name of the channel driver that this glue is responsible for */
501         const char *type;
502         /*! Module that the RTP glue came from */
503         struct ast_module *mod;
504         /*!
505          * \brief Callback for retrieving the RTP instance carrying audio
506          * \note This function increases the reference count on the returned RTP instance.
507          */
508         enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
509         /*!
510          * \brief Used to prevent two channels from remotely bridging audio rtp if the channel tech has a
511          *        reason for prohibiting it based on qualities that need to be compared from both channels.
512          * \note This function should only be called with two channels of the same technology
513          * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, function this is not used.
514          */
515         int (*allow_rtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
516         /*!
517          * \brief Callback for retrieving the RTP instance carrying video
518          * \note This function increases the reference count on the returned RTP instance.
519          */
520         enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
521         /*!
522          * \brief Used to prevent two channels from remotely bridging video rtp if the channel tech has a
523          *        reason for prohibiting it based on qualities that need to be compared from both channels.
524          * \note This function should only be called with two channels of the same technology
525          * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, this function is not used.
526          */
527         int (*allow_vrtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
528
529         /*!
530          * \brief Callback for retrieving the RTP instance carrying text
531          * \note This function increases the reference count on the returned RTP instance.
532          */
533         enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
534         /*! Callback for updating the destination that the remote side should send RTP to */
535         int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, const struct ast_format_cap *cap, int nat_active);
536         /*! Callback for retrieving codecs that the channel can do.  Result returned in result_cap*/
537         void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
538         /*! Linked list information */
539         AST_RWLIST_ENTRY(ast_rtp_glue) entry;
540 };
541
542 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
543
544 /*!
545  * \brief Register an RTP engine
546  *
547  * \param engine Structure of the RTP engine to register
548  * \param module Module that the RTP engine is part of
549  *
550  * \retval 0 success
551  * \retval -1 failure
552  *
553  * Example usage:
554  *
555  * \code
556  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
557  * \endcode
558  *
559  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
560  * associate a module with it.
561  *
562  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
563  *       associated with the RTP engine and use counting is performed.
564  *
565  * \since 1.8
566  */
567 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
568
569 /*!
570  * \brief Unregister an RTP engine
571  *
572  * \param engine Structure of the RTP engine to unregister
573  *
574  * \retval 0 success
575  * \retval -1 failure
576  *
577  * Example usage:
578  *
579  * \code
580  * ast_rtp_engine_unregister(&example_rtp_engine);
581  * \endcode
582  *
583  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
584  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
585  *
586  * \since 1.8
587  */
588 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
589
590 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
591
592 void ast_rtp_engine_unregister_srtp(void);
593 int ast_rtp_engine_srtp_is_registered(void);
594
595 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
596
597 /*!
598  * \brief Register RTP glue
599  *
600  * \param glue The glue to register
601  * \param module Module that the RTP glue is part of
602  *
603  * \retval 0 success
604  * \retval -1 failure
605  *
606  * Example usage:
607  *
608  * \code
609  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
610  * \endcode
611  *
612  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
613  * associate a module with it.
614  *
615  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
616  *       associated with the RTP glue and use counting is performed.
617  *
618  * \since 1.8
619  */
620 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
621
622 /*!
623  * \brief Unregister RTP glue
624  *
625  * \param glue The glue to unregister
626  *
627  * \retval 0 success
628  * \retval -1 failure
629  *
630  * Example usage:
631  *
632  * \code
633  * ast_rtp_glue_unregister(&example_rtp_glue);
634  * \endcode
635  *
636  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
637  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
638  *
639  * \since 1.8
640  */
641 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
642
643 /*!
644  * \brief Create a new RTP instance
645  *
646  * \param engine_name Name of the engine to use for the RTP instance
647  * \param sched Scheduler context that the RTP engine may want to use
648  * \param sa Address we want to bind to
649  * \param data Unique data for the engine
650  *
651  * \retval non-NULL success
652  * \retval NULL failure
653  *
654  * Example usage:
655  *
656  * \code
657  * struct ast_rtp_instance *instance = NULL;
658  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
659  * \endcode
660  *
661  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
662  * in the address structure.
663  *
664  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
665  *       another depending on it's own configuration.
666  *
667  * \since 1.8
668  */
669 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
670                 struct ast_sched_context *sched, const struct ast_sockaddr *sa,
671                 void *data);
672
673 /*!
674  * \brief Destroy an RTP instance
675  *
676  * \param instance The RTP instance to destroy
677  *
678  * \retval 0 success
679  * \retval -1 failure
680  *
681  * Example usage:
682  *
683  * \code
684  * ast_rtp_instance_destroy(instance);
685  * \endcode
686  *
687  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
688  * memory and may not be used again.
689  *
690  * \since 1.8
691  */
692 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
693
694 /*!
695  * \brief Set the data portion of an RTP instance
696  *
697  * \param instance The RTP instance to manipulate
698  * \param data Pointer to data
699  *
700  * Example usage:
701  *
702  * \code
703  * ast_rtp_instance_set_data(instance, blob);
704  * \endcode
705  *
706  * This sets the data pointer on the RTP instance pointed to by 'instance' to
707  * blob.
708  *
709  * \since 1.8
710  */
711 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
712
713 /*!
714  * \brief Get the data portion of an RTP instance
715  *
716  * \param instance The RTP instance we want the data portion from
717  *
718  * Example usage:
719  *
720  * \code
721  * struct *blob = ast_rtp_instance_get_data(instance);
722  ( \endcode
723  *
724  * This gets the data pointer on the RTP instance pointed to by 'instance'.
725  *
726  * \since 1.8
727  */
728 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
729
730 /*!
731  * \brief Send a frame out over RTP
732  *
733  * \param instance The RTP instance to send frame out on
734  * \param frame the frame to send out
735  *
736  * \retval 0 success
737  * \retval -1 failure
738  *
739  * Example usage:
740  *
741  * \code
742  * ast_rtp_instance_write(instance, frame);
743  * \endcode
744  *
745  * This gives the frame pointed to by frame to the RTP engine being used for the instance
746  * and asks that it be transmitted to the current remote address set on the RTP instance.
747  *
748  * \since 1.8
749  */
750 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
751
752 /*!
753  * \brief Receive a frame over RTP
754  *
755  * \param instance The RTP instance to receive frame on
756  * \param rtcp Whether to read in RTCP or not
757  *
758  * \retval non-NULL success
759  * \retval NULL failure
760  *
761  * Example usage:
762  *
763  * \code
764  * struct ast_frame *frame;
765  * frame = ast_rtp_instance_read(instance, 0);
766  * \endcode
767  *
768  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
769  *
770  * \since 1.8
771  */
772 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
773
774 /*!
775  * \brief Set the address of the remote endpoint that we are sending RTP to
776  *
777  * \param instance The RTP instance to change the address on
778  * \param address Address to set it to
779  *
780  * \retval 0 success
781  * \retval -1 failure
782  *
783  * Example usage:
784  *
785  * \code
786  * ast_rtp_instance_set_remote_address(instance, &sin);
787  * \endcode
788  *
789  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
790  * structure.
791  *
792  * \since 1.8
793  */
794 int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
795
796
797 /*!
798  * \brief Set the address of an an alternate RTP address to receive from
799  *
800  * \param instance The RTP instance to change the address on
801  * \param address Address to set it to
802  *
803  * \retval 0 success
804  * \retval -1 failure
805  *
806  * Example usage:
807  *
808  * \code
809  * ast_rtp_instance_set_alt_remote_address(instance, &address);
810  * \endcode
811  *
812  * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin
813  * structure.
814  *
815  * \since 1.8
816  */
817 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
818
819 /*!
820  * \brief Set the address that we are expecting to receive RTP on
821  *
822  * \param instance The RTP instance to change the address on
823  * \param address Address to set it to
824  *
825  * \retval 0 success
826  * \retval -1 failure
827  *
828  * Example usage:
829  *
830  * \code
831  * ast_rtp_instance_set_local_address(instance, &sin);
832  * \endcode
833  *
834  * This changes the local address that RTP is expected on to the address given in the sin
835  * structure.
836  *
837  * \since 1.8
838  */
839 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
840                 const struct ast_sockaddr *address);
841
842 /*!
843  * \brief Get the local address that we are expecting RTP on
844  *
845  * \param instance The RTP instance to get the address from
846  * \param address The variable to store the address in
847  *
848  * Example usage:
849  *
850  * \code
851  * struct ast_sockaddr address;
852  * ast_rtp_instance_get_local_address(instance, &address);
853  * \endcode
854  *
855  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
856  *
857  * \since 1.8
858  */
859 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
860
861 /*!
862  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
863  *
864  * \param instance The instance that we want to get the local address for
865  * \param address An initialized address that may be overwritten if the local address is different
866  *
867  * \retval 0 address was not changed
868  * \retval 1 address was changed
869  * Example usage:
870  *
871  * \code
872  * struct ast_sockaddr address;
873  * int ret;
874  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
875  * \endcode
876  *
877  * This retrieves the current local address set on the instance pointed to by instance and puts the value
878  * into the address structure.
879  *
880  * \since 1.8
881  */
882 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
883
884 /*!
885  * \brief Get the address of the remote endpoint that we are sending RTP to
886  *
887  * \param instance The instance that we want to get the remote address for
888  * \param address A structure to put the address into
889  *
890  * Example usage:
891  *
892  * \code
893  * struct ast_sockaddr address;
894  * ast_rtp_instance_get_remote_address(instance, &address);
895  * \endcode
896  *
897  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
898  * into the address structure.
899  *
900  * \since 1.8
901  */
902 void ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
903
904 /*!
905  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
906  *
907  * \param instance The instance that we want to get the remote address for
908  * \param address An initialized address that may be overwritten if the remote address is different
909  *
910  * \retval 0 address was not changed
911  * \retval 1 address was changed
912  * Example usage:
913  *
914  * \code
915  * struct ast_sockaddr address;
916  * int ret;
917  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
918  * \endcode
919  *
920  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
921  * into the address structure.
922  *
923  * \since 1.8
924  */
925
926 int ast_rtp_instance_get_and_cmp_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
927
928 /*!
929  * \brief Set the value of an RTP instance extended property
930  *
931  * \param instance The RTP instance to set the extended property on
932  * \param property The extended property to set
933  * \param value The value to set the extended property to
934  *
935  * \since 1.8
936  */
937 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
938
939 /*!
940  * \brief Get the value of an RTP instance extended property
941  *
942  * \param instance The RTP instance to get the extended property on
943  * \param property The extended property to get
944  *
945  * \since 1.8
946  */
947 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
948
949 /*!
950  * \brief Set the value of an RTP instance property
951  *
952  * \param instance The RTP instance to set the property on
953  * \param property The property to modify
954  * \param value The value to set the property to
955  *
956  * Example usage:
957  *
958  * \code
959  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
960  * \endcode
961  *
962  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
963  *
964  * \since 1.8
965  */
966 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
967
968 /*!
969  * \brief Get the value of an RTP instance property
970  *
971  * \param instance The RTP instance to get the property from
972  * \param property The property to get
973  *
974  * \retval Current value of the property
975  *
976  * Example usage:
977  *
978  * \code
979  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
980  * \endcode
981  *
982  * This returns the current value of the NAT property on the instance pointed to by instance.
983  *
984  * \since 1.8
985  */
986 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
987
988 /*!
989  * \brief Get the codecs structure of an RTP instance
990  *
991  * \param instance The RTP instance to get the codecs structure from
992  *
993  * Example usage:
994  *
995  * \code
996  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
997  * \endcode
998  *
999  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
1000  *
1001  * \since 1.8
1002  */
1003 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
1004
1005 /*!
1006  * \brief Initialize an RTP codecs structure
1007  *
1008  * \param codecs The codecs structure to initialize
1009  *
1010  * \retval 0 success
1011  * \retval -1 failure
1012  *
1013  * Example usage:
1014  *
1015  * \code
1016  * struct ast_rtp_codecs codecs;
1017  * ast_rtp_codecs_payloads_initialize(&codecs);
1018  * \endcode
1019  *
1020  * \since 11
1021  */
1022 int ast_rtp_codecs_payloads_initialize(struct ast_rtp_codecs *codecs);
1023
1024 /*!
1025  * \brief Destroy the contents of an RTP codecs structure (but not the structure itself)
1026  *
1027  * \param codecs The codecs structure to destroy the contents of
1028  *
1029  * Example usage:
1030  *
1031  * \code
1032  * struct ast_rtp_codecs codecs;
1033  * ast_rtp_codecs_payloads_destroy(&codecs);
1034  * \endcode
1035  *
1036  * \since 11
1037  */
1038 void ast_rtp_codecs_payloads_destroy(struct ast_rtp_codecs *codecs);
1039
1040 /*!
1041  * \brief Clear payload information from an RTP instance
1042  *
1043  * \param codecs The codecs structure that payloads will be cleared from
1044  * \param instance Optionally the instance that the codecs structure belongs to
1045  *
1046  * Example usage:
1047  *
1048  * \code
1049  * struct ast_rtp_codecs codecs;
1050  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
1051  * \endcode
1052  *
1053  * This clears the codecs structure and puts it into a pristine state.
1054  *
1055  * \since 1.8
1056  */
1057 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
1058
1059 /*!
1060  * \brief Set payload information on an RTP instance to the default
1061  *
1062  * \param codecs The codecs structure to set defaults on
1063  * \param instance Optionally the instance that the codecs structure belongs to
1064  *
1065  * Example usage:
1066  *
1067  * \code
1068  * struct ast_rtp_codecs codecs;
1069  * ast_rtp_codecs_payloads_default(&codecs, NULL);
1070  * \endcode
1071  *
1072  * This sets the default payloads on the codecs structure.
1073  *
1074  * \since 1.8
1075  */
1076 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
1077
1078 /*!
1079  * \brief Copy payload information from one RTP instance to another
1080  *
1081  * \param src The source codecs structure
1082  * \param dest The destination codecs structure that the values from src will be copied to
1083  * \param instance Optionally the instance that the dst codecs structure belongs to
1084  *
1085  * Example usage:
1086  *
1087  * \code
1088  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
1089  * \endcode
1090  *
1091  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
1092  *
1093  * \since 1.8
1094  */
1095 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
1096
1097 /*!
1098  * \brief Record payload information that was seen in an m= SDP line
1099  *
1100  * \param codecs The codecs structure to muck with
1101  * \param instance Optionally the instance that the codecs structure belongs to
1102  * \param payload Numerical payload that was seen in the m= SDP line
1103  *
1104  * Example usage:
1105  *
1106  * \code
1107  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
1108  * \endcode
1109  *
1110  * This records that the numerical payload '0' was seen in the codecs structure.
1111  *
1112  * \since 1.8
1113  */
1114 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1115
1116 /*!
1117  * \brief Record payload information that was seen in an a=rtpmap: SDP line
1118  *
1119  * \param codecs The codecs structure to muck with
1120  * \param instance Optionally the instance that the codecs structure belongs to
1121  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
1122  * \param mimetype The string mime type that was seen
1123  * \param mimesubtype The strin mime sub type that was seen
1124  * \param options Optional options that may change the behavior of this specific payload
1125  *
1126  * \retval 0 success
1127  * \retval -1 failure, invalid payload numbe
1128  * \retval -2 failure, unknown mimetype
1129  *
1130  * Example usage:
1131  *
1132  * \code
1133  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
1134  * \endcode
1135  *
1136  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
1137  *
1138  * \since 1.8
1139  */
1140 int ast_rtp_codecs_payloads_set_rtpmap_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload, char *mimetype, char *mimesubtype, enum ast_rtp_options options);
1141
1142 /*!
1143  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
1144  *
1145  * \param codecs RTP structure to modify
1146  * \param instance Optionally the instance that the codecs structure belongs to
1147  * \param pt Payload type entry to modify
1148  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
1149  * \param mimesubtype MIME subtype of media stream (typically a codec name)
1150  * \param options Zero or more flags from the ast_rtp_options enum
1151  * \param sample_rate The sample rate of the media stream
1152  *
1153  * This function 'fills in' an entry in the list of possible formats for
1154  * a media stream associated with an RTP structure.
1155  *
1156  * \retval 0 on success
1157  * \retval -1 if the payload type is out of range
1158  * \retval -2 if the mimeType/mimeSubtype combination was not found
1159  *
1160  * \since 1.8
1161  */
1162 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
1163                                   char *mimetype, char *mimesubtype,
1164                                   enum ast_rtp_options options,
1165                                   unsigned int sample_rate);
1166
1167 /*!
1168  * \brief Remove payload information
1169  *
1170  * \param codecs The codecs structure to muck with
1171  * \param instance Optionally the instance that the codecs structure belongs to
1172  * \param payload Numerical payload to unset
1173  *
1174  * Example usage:
1175  *
1176  * \code
1177  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
1178  * \endcode
1179  *
1180  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
1181  *
1182  * \since 1.8
1183  */
1184 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1185
1186 /*!
1187  * \brief Retrieve payload information by payload
1188  *
1189  * \param codecs Codecs structure to look in
1190  * \param payload Numerical payload to look up
1191  *
1192  * \retval Payload information
1193  *
1194  * Example usage:
1195  *
1196  * \code
1197  * struct ast_rtp_payload_type payload_type;
1198  * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
1199  * \endcode
1200  *
1201  * This looks up the information for payload '0' from the codecs structure.
1202  *
1203  * \since 1.8
1204  */
1205 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
1206
1207 /*!
1208  * \brief Retrieve the actual ast_format stored on the codecs structure for a specific payload
1209  *
1210  * \param codecs Codecs structure to look in
1211  * \param payload Numerical payload to look up
1212  *
1213  * \retval pointer to format structure on success
1214  * \retval NULL on failure
1215  *
1216  * \since 10.0
1217  */
1218 struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *codecs, int payload);
1219
1220 /*!
1221  * \brief Get the sample rate associated with known RTP payload types
1222  *
1223  * \param asterisk_format True if the value in format is to be used.
1224  * \param format An asterisk format
1225  * \param code from AST_RTP list
1226  *
1227  * \return the sample rate if the format was found, zero if it was not found
1228  *
1229  * \since 1.8
1230  */
1231 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, struct ast_format *format, int code);
1232
1233 /*!
1234  * \brief Retrieve all formats that were found
1235  *
1236  * \param codecs Codecs structure to look in
1237  * \param astformats A capabilities structure to put the Asterisk formats in.
1238  * \param nonastformats An integer to put the non-Asterisk formats in
1239  *
1240  * Example usage:
1241  *
1242  * \code
1243  * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
1244  * int nonastformats;
1245  * ast_rtp_codecs_payload_formats(&codecs, &astformats, &nonastformats);
1246  * \endcode
1247  *
1248  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
1249  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
1250  *
1251  * \since 1.8
1252  */
1253 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
1254
1255 /*!
1256  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
1257  *
1258  * \param codecs Codecs structure to look in
1259  * \param asterisk_format Non-zero if the given Asterisk format is present
1260  * \param format Asterisk format to look for
1261  * \param code The format to look for
1262  *
1263  * \retval Numerical payload
1264  *
1265  * Example usage:
1266  *
1267  * \code
1268  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
1269  * \endcode
1270  *
1271  * This looks for the numerical payload for ULAW in the codecs structure.
1272  *
1273  * \since 1.8
1274  */
1275 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
1276 /*!
1277  * \brief Search for a payload code in the ast_rtp_codecs structure
1278  *
1279  * \param codecs Codecs structure to look in
1280  * \param code The format to look for
1281  *
1282  * \retval Numerical payload or -1 if unable to find payload in codecs
1283  *
1284  * Example usage:
1285  *
1286  * \code
1287  * int payload = ast_rtp_codecs_payload_code(&codecs, 0);
1288  * \endcode
1289  *
1290  * This looks for the numerical payload for ULAW in the codecs structure.
1291  *
1292  */
1293 int ast_rtp_codecs_find_payload_code(struct ast_rtp_codecs *codecs, int code);
1294
1295 /*!
1296  * \brief Retrieve mime subtype information on a payload
1297  *
1298  * \param asterisk_format Non-zero to look up using Asterisk format
1299  * \param format Asterisk format to look up
1300  * \param code RTP code to look up
1301  * \param options Additional options that may change the result
1302  *
1303  * \retval Mime subtype success
1304  * \retval NULL failure
1305  *
1306  * Example usage:
1307  *
1308  * \code
1309  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
1310  * \endcode
1311  *
1312  * This looks up the mime subtype for the ULAW format.
1313  *
1314  * \since 1.8
1315  */
1316 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, struct ast_format *format, int code, enum ast_rtp_options options);
1317
1318 /*!
1319  * \brief Convert formats into a string and put them into a buffer
1320  *
1321  * \param buf Buffer to put the mime output into
1322  * \param ast_format_capability Asterisk Formats we are looking up.
1323  * \param rtp_capability RTP codes that we are looking up
1324  * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
1325  * \param options Additional options that may change the result
1326  *
1327  * \retval non-NULL success
1328  * \retval NULL failure
1329  *
1330  * Example usage:
1331  *
1332  * \code
1333  * char buf[256] = "";
1334  * struct ast_format tmp_fmt;
1335  * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
1336  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1337  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
1338  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
1339  * ast_format_cap_destroy(cap);
1340  * \endcode
1341  *
1342  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
1343  *
1344  * \since 1.8
1345  */
1346 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, struct ast_format_cap *ast_format_capability, int rtp_capability, const int asterisk_format, enum ast_rtp_options options);
1347
1348 /*!
1349  * \brief Set codec packetization preferences
1350  *
1351  * \param codecs Codecs structure to muck with
1352  * \param instance Optionally the instance that the codecs structure belongs to
1353  * \param prefs Codec packetization preferences
1354  *
1355  * Example usage:
1356  *
1357  * \code
1358  * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
1359  * \endcode
1360  *
1361  * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
1362  *
1363  * \since 1.8
1364  */
1365 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
1366
1367 /*!
1368  * \brief Begin sending a DTMF digit
1369  *
1370  * \param instance The RTP instance to send the DTMF on
1371  * \param digit What DTMF digit to send
1372  *
1373  * \retval 0 success
1374  * \retval -1 failure
1375  *
1376  * Example usage:
1377  *
1378  * \code
1379  * ast_rtp_instance_dtmf_begin(instance, '1');
1380  * \endcode
1381  *
1382  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
1383  * continue being sent until it is ended.
1384  *
1385  * \since 1.8
1386  */
1387 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
1388
1389 /*!
1390  * \brief Stop sending a DTMF digit
1391  *
1392  * \param instance The RTP instance to stop the DTMF on
1393  * \param digit What DTMF digit to stop
1394  *
1395  * \retval 0 success
1396  * \retval -1 failure
1397  *
1398  * Example usage:
1399  *
1400  * \code
1401  * ast_rtp_instance_dtmf_end(instance, '1');
1402  * \endcode
1403  *
1404  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
1405  *
1406  * \since 1.8
1407  */
1408 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
1409 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
1410
1411 /*!
1412  * \brief Set the DTMF mode that should be used
1413  *
1414  * \param instance the RTP instance to set DTMF mode on
1415  * \param dtmf_mode The DTMF mode that is in use
1416  *
1417  * \retval 0 success
1418  * \retval -1 failure
1419  *
1420  * Example usage:
1421  *
1422  * \code
1423  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
1424  * \endcode
1425  *
1426  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
1427  *
1428  * \since 1.8
1429  */
1430 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
1431
1432 /*!
1433  * \brief Get the DTMF mode of an RTP instance
1434  *
1435  * \param instance The RTP instance to get the DTMF mode of
1436  *
1437  * \retval DTMF mode
1438  *
1439  * Example usage:
1440  *
1441  * \code
1442  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
1443  * \endcode
1444  *
1445  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
1446  *
1447  * \since 1.8
1448  */
1449 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
1450
1451 /*!
1452  * \brief Indicate that the RTP marker bit should be set on an RTP stream
1453  *
1454  * \param instance Instance that the new media source is feeding into
1455  *
1456  * Example usage:
1457  *
1458  * \code
1459  * ast_rtp_instance_update_source(instance);
1460  * \endcode
1461  *
1462  * This indicates that the source of media that is feeding the instance pointed to by
1463  * instance has been updated and that the marker bit should be set.
1464  *
1465  * \since 1.8
1466  */
1467 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
1468
1469 /*!
1470  * \brief Indicate a new source of audio has dropped in and the ssrc should change
1471  *
1472  * \param instance Instance that the new media source is feeding into
1473  *
1474  * Example usage:
1475  *
1476  * \code
1477  * ast_rtp_instance_change_source(instance);
1478  * \endcode
1479  *
1480  * This indicates that the source of media that is feeding the instance pointed to by
1481  * instance has changed and that the marker bit should be set and the SSRC updated.
1482  *
1483  * \since 1.8
1484  */
1485 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
1486
1487 /*!
1488  * \brief Set QoS parameters on an RTP session
1489  *
1490  * \param instance Instance to set the QoS parameters on
1491  * \param tos Terms of service value
1492  * \param cos Class of service value
1493  * \param desc What is setting the QoS values
1494  *
1495  * \retval 0 success
1496  * \retval -1 failure
1497  *
1498  * Example usage:
1499  *
1500  * \code
1501  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
1502  * \endcode
1503  *
1504  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
1505  *
1506  * \since 1.8
1507  */
1508 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
1509
1510 /*!
1511  * \brief Stop an RTP instance
1512  *
1513  * \param instance Instance that media is no longer going to at this time
1514  *
1515  * Example usage:
1516  *
1517  * \code
1518  * ast_rtp_instance_stop(instance);
1519  * \endcode
1520  *
1521  * This tells the RTP engine being used for the instance pointed to by instance
1522  * that media is no longer going to it at this time, but may in the future.
1523  *
1524  * \since 1.8
1525  */
1526 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
1527
1528 /*!
1529  * \brief Get the file descriptor for an RTP session (or RTCP)
1530  *
1531  * \param instance Instance to get the file descriptor for
1532  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
1533  *
1534  * \retval fd success
1535  * \retval -1 failure
1536  *
1537  * Example usage:
1538  *
1539  * \code
1540  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
1541  * \endcode
1542  *
1543  * This retrieves the file descriptor for the socket carrying media on the instance
1544  * pointed to by instance.
1545  *
1546  * \since 1.8
1547  */
1548 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
1549
1550 /*!
1551  * \brief Get the RTP glue that binds a channel to the RTP engine
1552  *
1553  * \param type Name of the glue we want
1554  *
1555  * \retval non-NULL success
1556  * \retval NULL failure
1557  *
1558  * Example usage:
1559  *
1560  * \code
1561  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
1562  * \endcode
1563  *
1564  * This retrieves the RTP glue that has the name 'Example'.
1565  *
1566  * \since 1.8
1567  */
1568 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
1569
1570 /*!
1571  * \brief Bridge two channels that use RTP instances
1572  *
1573  * \param c0 First channel part of the bridge
1574  * \param c1 Second channel part of the bridge
1575  * \param flags Bridging flags
1576  * \param fo If a frame needs to be passed up it is stored here
1577  * \param rc Channel that passed the above frame up
1578  * \param timeoutms How long the channels should be bridged for
1579  *
1580  * \retval Bridge result
1581  *
1582  * \note This should only be used by channel drivers in their technology declaration.
1583  *
1584  * \since 1.8
1585  */
1586 enum ast_bridge_result ast_rtp_instance_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
1587
1588 /*!
1589  * \brief Get the other RTP instance that an instance is bridged to
1590  *
1591  * \param instance The RTP instance that we want
1592  *
1593  * \retval non-NULL success
1594  * \retval NULL failure
1595  *
1596  * Example usage:
1597  *
1598  * \code
1599  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
1600  * \endcode
1601  *
1602  * This gets the RTP instance that instance0 is bridged to.
1603  *
1604  * \since 1.8
1605  */
1606 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
1607
1608 /*!
1609  * \brief Make two channels compatible for early bridging
1610  *
1611  * \param c0 First channel part of the bridge
1612  * \param c1 Second channel part of the bridge
1613  *
1614  * \since 1.8
1615  */
1616 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1617
1618 /*!
1619  * \brief Early bridge two channels that use RTP instances
1620  *
1621  * \param c0 First channel part of the bridge
1622  * \param c1 Second channel part of the bridge
1623  *
1624  * \retval 0 success
1625  * \retval -1 failure
1626  *
1627  * \note This should only be used by channel drivers in their technology declaration.
1628  *
1629  * \since 1.8
1630  */
1631 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1632
1633 /*!
1634  * \brief Initialize RED support on an RTP instance
1635  *
1636  * \param instance The instance to initialize RED support on
1637  * \param buffer_time How long to buffer before sending
1638  * \param payloads Payload values
1639  * \param generations Number of generations
1640  *
1641  * \retval 0 success
1642  * \retval -1 failure
1643  *
1644  * \since 1.8
1645  */
1646 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
1647
1648 /*!
1649  * \brief Buffer a frame in an RTP instance for RED
1650  *
1651  * \param instance The instance to buffer the frame on
1652  * \param frame Frame that we want to buffer
1653  *
1654  * \retval 0 success
1655  * \retval -1 failure
1656  *
1657  * \since 1.8
1658  */
1659 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
1660
1661 /*!
1662  * \brief Retrieve statistics about an RTP instance
1663  *
1664  * \param instance Instance to get statistics on
1665  * \param stats Structure to put results into
1666  * \param stat What statistic(s) to retrieve
1667  *
1668  * \retval 0 success
1669  * \retval -1 failure
1670  *
1671  * Example usage:
1672  *
1673  * \code
1674  * struct ast_rtp_instance_stats stats;
1675  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
1676  * \endcode
1677  *
1678  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
1679  * stats structure.
1680  *
1681  * \since 1.8
1682  */
1683 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
1684
1685 /*!
1686  * \brief Set standard statistics from an RTP instance on a channel
1687  *
1688  * \param chan Channel to set the statistics on
1689  * \param instance The RTP instance that statistics will be retrieved from
1690  *
1691  * Example usage:
1692  *
1693  * \code
1694  * ast_rtp_instance_set_stats_vars(chan, rtp);
1695  * \endcode
1696  *
1697  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
1698  * by chan.
1699  *
1700  * \since 1.8
1701  */
1702 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
1703
1704 /*!
1705  * \brief Retrieve quality statistics about an RTP instance
1706  *
1707  * \param instance Instance to get statistics on
1708  * \param field What quality statistic to retrieve
1709  * \param buf What buffer to put the result into
1710  * \param size Size of the above buffer
1711  *
1712  * \retval non-NULL success
1713  * \retval NULL failure
1714  *
1715  * Example usage:
1716  *
1717  * \code
1718  * char quality[AST_MAX_USER_FIELD];
1719  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
1720  * \endcode
1721  *
1722  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
1723  *
1724  * \since 1.8
1725  */
1726 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
1727
1728 /*!
1729  * \brief Request that the underlying RTP engine provide audio frames in a specific format
1730  *
1731  * \param instance The RTP instance to change read format on
1732  * \param format Format that frames are wanted in
1733  *
1734  * \retval 0 success
1735  * \retval -1 failure
1736  *
1737  * Example usage:
1738  *
1739  * \code
1740  * struct ast_format tmp_fmt;
1741  * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1742  * \endcode
1743  *
1744  * This requests that the RTP engine provide audio frames in the ULAW format.
1745  *
1746  * \since 1.8
1747  */
1748 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
1749
1750 /*!
1751  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
1752  *
1753  * \param instance The RTP instance to change write format on
1754  * \param format Format that frames will be provided in
1755  *
1756  * \retval 0 success
1757  * \retval -1 failure
1758  *
1759  * Example usage:
1760  *
1761  * \code
1762  * struct ast_format tmp_fmt;
1763  * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1764  * \endcode
1765  *
1766  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
1767  *
1768  * \since 1.8
1769  */
1770 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
1771
1772 /*!
1773  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
1774  *
1775  * \param chan Our own Asterisk channel
1776  * \param instance The first RTP instance
1777  * \param peer The peer Asterisk channel
1778  *
1779  * \retval 0 success
1780  * \retval -1 failure
1781  *
1782  * Example usage:
1783  *
1784  * \code
1785  * ast_rtp_instance_make_compatible(instance, peer);
1786  * \endcode
1787  *
1788  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
1789  *
1790  * \since 1.8
1791  */
1792 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
1793
1794 /*! \brief Request the formats that can be transcoded
1795  *
1796  * \param instance The RTP instance
1797  * \param to_endpoint Formats being sent/received towards the endpoint
1798  * \param to_asterisk Formats being sent/received towards Asterisk
1799  * \param result capabilities structure to store and return supported formats in.
1800  *
1801  * Example usage:
1802  *
1803  * \code
1804  * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
1805  * \endcode
1806  *
1807  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
1808  *
1809  * \since 1.8
1810  */
1811 void ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
1812
1813 /*!
1814  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
1815  *
1816  * \param instance The RTP instance
1817  *
1818  * \retval 0 success
1819  * \retval -1 failure
1820  *
1821  * Example usage:
1822  *
1823  * \code
1824  * ast_rtp_instance_activate(instance);
1825  * \endcode
1826  *
1827  * This tells the underlying RTP engine of instance that packets will now flow.
1828  *
1829  * \since 1.8
1830  */
1831 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
1832
1833 /*!
1834  * \brief Request that the underlying RTP engine send a STUN BIND request
1835  *
1836  * \param instance The RTP instance
1837  * \param suggestion The suggested destination
1838  * \param username Optionally a username for the request
1839  *
1840  * Example usage:
1841  *
1842  * \code
1843  * ast_rtp_instance_stun_request(instance, NULL, NULL);
1844  * \endcode
1845  *
1846  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
1847  * 'instance'.
1848  *
1849  * \since 1.8
1850  */
1851 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
1852
1853 /*!
1854  * \brief Set the RTP timeout value
1855  *
1856  * \param instance The RTP instance
1857  * \param timeout Value to set the timeout to
1858  *
1859  * Example usage:
1860  *
1861  * \code
1862  * ast_rtp_instance_set_timeout(instance, 5000);
1863  * \endcode
1864  *
1865  * This sets the RTP timeout value on 'instance' to be 5000.
1866  *
1867  * \since 1.8
1868  */
1869 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
1870
1871 /*!
1872  * \brief Set the RTP timeout value for when the instance is on hold
1873  *
1874  * \param instance The RTP instance
1875  * \param timeout Value to set the timeout to
1876  *
1877  * Example usage:
1878  *
1879  * \code
1880  * ast_rtp_instance_set_hold_timeout(instance, 5000);
1881  * \endcode
1882  *
1883  * This sets the RTP hold timeout value on 'instance' to be 5000.
1884  *
1885  * \since 1.8
1886  */
1887 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
1888
1889 /*!
1890  * \brief Set the RTP keepalive interval
1891  *
1892  * \param instance The RTP instance
1893  * \param timeout Value to set the keepalive interval to
1894  *
1895  * Example usage:
1896  *
1897  * \code
1898  * ast_rtp_instance_set_keepalive(instance, 5000);
1899  * \endcode
1900  *
1901  * This sets the RTP keepalive interval on 'instance' to be 5000.
1902  *
1903  * \since 1.8
1904  */
1905 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
1906
1907 /*!
1908  * \brief Get the RTP timeout value
1909  *
1910  * \param instance The RTP instance
1911  *
1912  * \retval timeout value
1913  *
1914  * Example usage:
1915  *
1916  * \code
1917  * int timeout = ast_rtp_instance_get_timeout(instance);
1918  * \endcode
1919  *
1920  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
1921  *
1922  * \since 1.8
1923  */
1924 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
1925
1926 /*!
1927  * \brief Get the RTP timeout value for when an RTP instance is on hold
1928  *
1929  * \param instance The RTP instance
1930  *
1931  * \retval timeout value
1932  *
1933  * Example usage:
1934  *
1935  * \code
1936  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
1937  * \endcode
1938  *
1939  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
1940  *
1941  * \since 1.8
1942  */
1943 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
1944
1945 /*!
1946  * \brief Get the RTP keepalive interval
1947  *
1948  * \param instance The RTP instance
1949  *
1950  * \retval period Keepalive interval value
1951  *
1952  * Example usage:
1953  *
1954  * \code
1955  * int interval = ast_rtp_instance_get_keepalive(instance);
1956  * \endcode
1957  *
1958  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
1959  *
1960  * \since 1.8
1961  */
1962 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
1963
1964 /*!
1965  * \brief Get the RTP engine in use on an RTP instance
1966  *
1967  * \param instance The RTP instance
1968  *
1969  * \retval pointer to the engine
1970  *
1971  * Example usage:
1972  *
1973  * \code
1974  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
1975  * \endcode
1976  *
1977  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
1978  *
1979  * \since 1.8
1980  */
1981 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
1982
1983 /*!
1984  * \brief Get the RTP glue in use on an RTP instance
1985  *
1986  * \param instance The RTP instance
1987  *
1988  * \retval pointer to the glue
1989  *
1990  * Example:
1991  *
1992  * \code
1993  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
1994  * \endcode
1995  *
1996  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
1997  *
1998  * \since 1.8
1999  */
2000 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
2001
2002 /*!
2003  * \brief Get the channel that is associated with an RTP instance while in a bridge
2004  *
2005  * \param instance The RTP instance
2006  *
2007  * \retval pointer to the channel
2008  *
2009  * Example:
2010  *
2011  * \code
2012  * struct ast_channel *chan = ast_rtp_instance_get_chan(instance);
2013  * \endcode
2014  *
2015  * This gets the channel associated with the RTP instance pointed to by 'instance'.
2016  *
2017  * \note This will only return a channel while in a local or remote bridge.
2018  *
2019  * \since 1.8
2020  */
2021 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance);
2022
2023 /*!
2024  * \brief Send a comfort noise packet to the RTP instance
2025  *
2026  * \param instance The RTP instance
2027  * \param level Magnitude of the noise level
2028  *
2029  * \retval 0 Success
2030  * \retval non-zero Failure
2031  */
2032 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
2033
2034 /*!
2035  * \brief Add or replace the SRTP policies for the given RTP instance
2036  *
2037  * \param instance the RTP instance
2038  * \param remote_policy the remote endpoint's policy
2039  * \param local_policy our policy for this RTP instance's remote endpoint
2040  *
2041  * \retval 0 Success
2042  * \retval non-zero Failure
2043  */
2044 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy);
2045
2046 /*!
2047  * \brief Obtain the SRTP instance associated with an RTP instance
2048  *
2049  * \param instance the RTP instance
2050  * \retval the SRTP instance on success
2051  * \retval NULL if no SRTP instance exists
2052  */
2053 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance);
2054
2055 /*! \brief Custom formats declared in codecs.conf at startup must be communicated to the rtp_engine
2056  * so their mime type can payload number can be initialized. */
2057 int ast_rtp_engine_load_format(const struct ast_format *format);
2058
2059 /*! \brief Formats requiring the use of a format attribute interface must have that
2060  * interface registered in order for the rtp engine to handle it correctly.  If an
2061  * attribute interface is unloaded, this function must be called to notify the rtp_engine. */
2062 int ast_rtp_engine_unload_format(const struct ast_format *format);
2063
2064 /*!
2065  * \brief Obtain a pointer to the ICE support present on an RTP instance
2066  *
2067  * \param instance the RTP instance
2068  *
2069  * \retval ICE support if present
2070  * \retval NULL if no ICE support available
2071  */
2072 struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *instance);
2073
2074 /*!
2075  * \brief Obtain a pointer to the DTLS support present on an RTP instance
2076  *
2077  * \param instance the RTP instance
2078  *
2079  * \retval DTLS support if present
2080  * \retval NULL if no DTLS support available
2081  */
2082 struct ast_rtp_engine_dtls *ast_rtp_instance_get_dtls(struct ast_rtp_instance *instance);
2083
2084 /*!
2085  * \brief Parse DTLS related configuration options
2086  *
2087  * \param dtls_cfg a DTLS configuration structure
2088  * \param name name of the configuration option
2089  * \param value value of the configuration option
2090  *
2091  * \retval 0 if handled
2092  * \retval -1 if not handled
2093  */
2094 int ast_rtp_dtls_cfg_parse(struct ast_rtp_dtls_cfg *dtls_cfg, const char *name, const char *value);
2095
2096 /*!
2097  * \brief Copy contents of a DTLS configuration structure
2098  *
2099  * \param src_cfg source DTLS configuration structure
2100  * \param dst_cfg destination DTLS configuration structure
2101  */
2102 void ast_rtp_dtls_cfg_copy(const struct ast_rtp_dtls_cfg *src_cfg, struct ast_rtp_dtls_cfg *dst_cfg);
2103
2104 /*!
2105  * \brief Free contents of a DTLS configuration structure
2106  *
2107  * \param dtls_cfg a DTLS configuration structure
2108  */
2109 void ast_rtp_dtls_cfg_free(struct ast_rtp_dtls_cfg *dtls_cfg);
2110
2111 #if defined(__cplusplus) || defined(c_plusplus)
2112 }
2113 #endif
2114
2115 #endif /* _ASTERISK_RTP_ENGINE_H */