98d77734fa18c345d66ea4b4a5e81e21dc6d4c4a
[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/format_cap.h"
75 #include "asterisk/netsock2.h"
76 #include "asterisk/sched.h"
77 #include "asterisk/res_srtp.h"
78 #include "asterisk/stasis.h"
79 #include "asterisk/vector.h"
80
81 /*! Maximum number of payload types RTP can support. */
82 #define AST_RTP_MAX_PT 128
83
84 /*!
85  * Last RTP payload type statically assigned, see
86  * http://www.iana.org/assignments/rtp-parameters
87  */
88 #define AST_RTP_PT_LAST_STATIC 34
89
90 /*! First dynamic RTP payload type */
91 #define AST_RTP_PT_FIRST_DYNAMIC 96
92
93 /*! Last reassignable RTP payload type */
94 #define AST_RTP_PT_LAST_REASSIGN 63
95
96 /*! Maximum number of generations */
97 #define AST_RED_MAX_GENERATION 5
98
99 /*!
100  * Maximum size of an internal Asterisk channel unique ID.
101  *
102  * \note Must match the AST_MAX_UNIQUEID(AST_MAX_PUBLIC_UNIQUEID) value.
103  * We don't use that defined value directly here to avoid a hard
104  * dependency on channel.h.
105  */
106 #define MAX_CHANNEL_ID 152
107
108 struct ast_rtp_instance;
109 struct ast_rtp_glue;
110
111 /*! RTP Properties that can be set on an RTP instance */
112 enum ast_rtp_property {
113         /*! Enable symmetric RTP support */
114         AST_RTP_PROPERTY_NAT = 0,
115         /*! RTP instance will be carrying DTMF (using RFC2833) */
116         AST_RTP_PROPERTY_DTMF,
117         /*! Expect unreliable DTMF from remote party */
118         AST_RTP_PROPERTY_DTMF_COMPENSATE,
119         /*! Enable STUN support */
120         AST_RTP_PROPERTY_STUN,
121         /*! Enable RTCP support */
122         AST_RTP_PROPERTY_RTCP,
123         /*! Enable Asymmetric RTP Codecs */
124         AST_RTP_PROPERTY_ASYMMETRIC_CODEC,
125         /*! Enable packet retransmission for received packets */
126         AST_RTP_PROPERTY_RETRANS_RECV,
127         /*! Enable packet retransmission for sent packets */
128         AST_RTP_PROPERTY_RETRANS_SEND,
129         /*! Enable REMB sending and receiving passthrough support */
130         AST_RTP_PROPERTY_REMB,
131
132         /*!
133          * \brief Maximum number of RTP properties supported
134          *
135          * \note THIS MUST BE THE LAST ENTRY IN THIS ENUM.
136          */
137         AST_RTP_PROPERTY_MAX,
138 };
139
140 /*! Additional RTP options */
141 enum ast_rtp_options {
142         /*! Remote side is using non-standard G.726 */
143         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
144 };
145
146 /*! RTP DTMF Modes */
147 enum ast_rtp_dtmf_mode {
148         /*! No DTMF is being carried over the RTP stream */
149         AST_RTP_DTMF_MODE_NONE = 0,
150         /*! DTMF is being carried out of band using RFC2833 */
151         AST_RTP_DTMF_MODE_RFC2833,
152         /*! DTMF is being carried inband over the RTP stream */
153         AST_RTP_DTMF_MODE_INBAND,
154 };
155
156 /*! Result codes when RTP glue is queried for information */
157 enum ast_rtp_glue_result {
158         /*! No remote or local bridging is permitted */
159         AST_RTP_GLUE_RESULT_FORBID = 0,
160         /*! Move RTP stream to be remote between devices directly */
161         AST_RTP_GLUE_RESULT_REMOTE,
162         /*! Perform RTP engine level bridging if possible */
163         AST_RTP_GLUE_RESULT_LOCAL,
164 };
165
166 /*! Field statistics that can be retrieved from an RTP instance */
167 enum ast_rtp_instance_stat_field {
168         /*! Retrieve quality information */
169         AST_RTP_INSTANCE_STAT_FIELD_QUALITY = 0,
170         /*! Retrieve quality information about jitter */
171         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_JITTER,
172         /*! Retrieve quality information about packet loss */
173         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_LOSS,
174         /*! Retrieve quality information about round trip time */
175         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_RTT,
176 };
177
178 /*! Statistics that can be retrieved from an RTP instance */
179 enum ast_rtp_instance_stat {
180         /*! Retrieve all statistics */
181         AST_RTP_INSTANCE_STAT_ALL = 0,
182         /*! Retrieve number of packets transmitted */
183         AST_RTP_INSTANCE_STAT_TXCOUNT,
184         /*! Retrieve number of packets received */
185         AST_RTP_INSTANCE_STAT_RXCOUNT,
186         /*! Retrieve ALL statistics relating to packet loss */
187         AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
188         /*! Retrieve number of packets lost for transmitting */
189         AST_RTP_INSTANCE_STAT_TXPLOSS,
190         /*! Retrieve number of packets lost for receiving */
191         AST_RTP_INSTANCE_STAT_RXPLOSS,
192         /*! Retrieve maximum number of packets lost on remote side */
193         AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
194         /*! Retrieve minimum number of packets lost on remote side */
195         AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
196         /*! Retrieve average number of packets lost on remote side */
197         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
198         /*! Retrieve standard deviation of packets lost on remote side */
199         AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
200         /*! Retrieve maximum number of packets lost on local side */
201         AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
202         /*! Retrieve minimum number of packets lost on local side */
203         AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
204         /*! Retrieve average number of packets lost on local side */
205         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
206         /*! Retrieve standard deviation of packets lost on local side */
207         AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
208         /*! Retrieve ALL statistics relating to jitter */
209         AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
210         /*! Retrieve jitter on transmitted packets */
211         AST_RTP_INSTANCE_STAT_TXJITTER,
212         /*! Retrieve jitter on received packets */
213         AST_RTP_INSTANCE_STAT_RXJITTER,
214         /*! Retrieve maximum jitter on remote side */
215         AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
216         /*! Retrieve minimum jitter on remote side */
217         AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
218         /*! Retrieve average jitter on remote side */
219         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
220         /*! Retrieve standard deviation jitter on remote side */
221         AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
222         /*! Retrieve maximum jitter on local side */
223         AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
224         /*! Retrieve minimum jitter on local side */
225         AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
226         /*! Retrieve average jitter on local side */
227         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
228         /*! Retrieve standard deviation jitter on local side */
229         AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
230         /*! Retrieve ALL statistics relating to round trip time */
231         AST_RTP_INSTANCE_STAT_COMBINED_RTT,
232         /*! Retrieve round trip time */
233         AST_RTP_INSTANCE_STAT_RTT,
234         /*! Retrieve maximum round trip time */
235         AST_RTP_INSTANCE_STAT_MAX_RTT,
236         /*! Retrieve minimum round trip time */
237         AST_RTP_INSTANCE_STAT_MIN_RTT,
238         /*! Retrieve average round trip time */
239         AST_RTP_INSTANCE_STAT_NORMDEVRTT,
240         /*! Retrieve standard deviation round trip time */
241         AST_RTP_INSTANCE_STAT_STDEVRTT,
242         /*! Retrieve local SSRC */
243         AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
244         /*! Retrieve remote SSRC */
245         AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
246         /*! Retrieve channel unique ID */
247         AST_RTP_INSTANCE_STAT_CHANNEL_UNIQUEID,
248         /*! Retrieve number of octets transmitted */
249         AST_RTP_INSTANCE_STAT_TXOCTETCOUNT,
250         /*! Retrieve number of octets received */
251         AST_RTP_INSTANCE_STAT_RXOCTETCOUNT,
252 };
253
254 enum ast_rtp_instance_rtcp {
255         /*! RTCP should not be sent/received */
256         AST_RTP_INSTANCE_RTCP_DISABLED = 0,
257         /*! RTCP should be sent/received based on standard port rules */
258         AST_RTP_INSTANCE_RTCP_STANDARD,
259         /*! RTCP should be sent/received on the same port as RTP */
260         AST_RTP_INSTANCE_RTCP_MUX,
261 };
262
263 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
264 /*! DTMF (RFC2833) */
265 #define AST_RTP_DTMF                    (1 << 0)
266 /*! 'Comfort Noise' (RFC3389) */
267 #define AST_RTP_CN                      (1 << 1)
268 /*! DTMF (Cisco Proprietary) */
269 #define AST_RTP_CISCO_DTMF              (1 << 2)
270 /*! Maximum RTP-specific code */
271 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
272
273 /*! Structure that represents a payload */
274 struct ast_rtp_payload_type {
275         /*! If asterisk_format is set, this is the internal
276          * asterisk format represented by the payload */
277         struct ast_format *format;
278         /*! Is this an Asterisk value */
279         int asterisk_format;
280         /*! Actual internal RTP specific value of the payload */
281         int rtp_code;
282         /*! Actual payload number */
283         int payload;
284         /*! TRUE if this is the primary mapping to the format. */
285         unsigned int primary_mapping:1;
286         /*! When the payload type became non-primary. */
287         struct timeval when_retired;
288 };
289
290 /* Common RTCP report types */
291 /*! Sender Report */
292 #define AST_RTP_RTCP_SR 200
293 /*! Receiver Report */
294 #define AST_RTP_RTCP_RR 201
295 /*! Transport Layer Feed Back (From RFC4585 also RFC5104) */
296 #define AST_RTP_RTCP_RTPFB      205
297 /*! Payload Specific Feed Back (From RFC4585 also RFC5104) */
298 #define AST_RTP_RTCP_PSFB       206
299
300 /* Common RTCP feedback message types */
301 /*! Generic NACK (From RFC4585 also RFC5104) */
302 #define AST_RTP_RTCP_FMT_NACK   1
303 /*! Picture loss indication (From RFC4585) */
304 #define AST_RTP_RTCP_FMT_PLI    1
305 /*! Full INTRA-frame Request (From RFC5104) */
306 #define AST_RTP_RTCP_FMT_FIR    4
307 /*! REMB Information (From draft-alvestrand-rmcat-remb-03) */
308 #define AST_RTP_RTCP_FMT_REMB   15
309
310 /*!
311  * \since 12
312  * \brief A report block within a SR/RR report */
313 struct ast_rtp_rtcp_report_block {
314         unsigned int source_ssrc;         /*< The SSRC of the source for this report block */
315         struct {
316                 unsigned short fraction;      /*< The fraction of packets lost since last SR/RR */
317                 unsigned int packets;         /*< The cumulative packets since the beginning */
318         } lost_count;                     /*< Statistics regarding missed packets */
319         unsigned int highest_seq_no;      /*< Extended highest sequence number received */
320         unsigned int ia_jitter;           /*< Calculated interarrival jitter */
321         unsigned int lsr;                 /*< The time the last SR report was received */
322         unsigned int dlsr;                /*< Delay in sending this report */
323 };
324
325 /*!
326  * \since 12
327  * \brief An object that represents data sent during a SR/RR RTCP report */
328 struct ast_rtp_rtcp_report {
329         unsigned short reception_report_count;     /*< The number of report blocks */
330         unsigned int ssrc;                         /*< Our SSRC */
331         unsigned int type;                         /*< The type of report. 200=SR; 201=RR */
332         struct {
333                 struct timeval ntp_timestamp;          /*< Our NTP timestamp */
334                 unsigned int rtp_timestamp;            /*< Our last RTP timestamp */
335                 unsigned int packet_count;             /*< Number of packets sent */
336                 unsigned int octet_count;              /*< Number of bytes sent */
337         } sender_information;                      /*< Sender information for SR */
338         /*! A dynamic array of report blocks. The number of elements is given by
339          * \c reception_report_count.
340          */
341         struct ast_rtp_rtcp_report_block *report_block[0];
342 };
343
344 /*!
345  * \since 15.4.0
346  * \brief A REMB feedback message (see draft-alvestrand-rmcat-remb-03 for details) */
347 struct ast_rtp_rtcp_feedback_remb {
348         unsigned int br_exp;            /*!< Exponential scaling of the mantissa for the maximum total media bit rate value */
349         unsigned int br_mantissa;       /*!< The mantissa of the maximum total media bit rate */
350 };
351
352 /*!
353  * \since 15.4.0
354  * \brief An object that represents data received in a feedback report */
355 struct ast_rtp_rtcp_feedback {
356         unsigned int fmt; /*!< The feedback message type */
357         union {
358                 struct ast_rtp_rtcp_feedback_remb remb; /*!< REMB feedback information */
359         };
360 };
361
362 /*! Structure that represents statistics from an RTP instance */
363 struct ast_rtp_instance_stats {
364         /*! Number of packets transmitted */
365         unsigned int txcount;
366         /*! Number of packets received */
367         unsigned int rxcount;
368         /*! Jitter on transmitted packets */
369         double txjitter;
370         /*! Jitter on received packets */
371         double rxjitter;
372         /*! Maximum jitter on remote side */
373         double remote_maxjitter;
374         /*! Minimum jitter on remote side */
375         double remote_minjitter;
376         /*! Average jitter on remote side */
377         double remote_normdevjitter;
378         /*! Standard deviation jitter on remote side */
379         double remote_stdevjitter;
380         /*! Maximum jitter on local side */
381         double local_maxjitter;
382         /*! Minimum jitter on local side */
383         double local_minjitter;
384         /*! Average jitter on local side */
385         double local_normdevjitter;
386         /*! Standard deviation jitter on local side */
387         double local_stdevjitter;
388         /*! Number of transmitted packets lost */
389         unsigned int txploss;
390         /*! Number of received packets lost */
391         unsigned int rxploss;
392         /*! Maximum number of packets lost on remote side */
393         double remote_maxrxploss;
394         /*! Minimum number of packets lost on remote side */
395         double remote_minrxploss;
396         /*! Average number of packets lost on remote side */
397         double remote_normdevrxploss;
398         /*! Standard deviation packets lost on remote side */
399         double remote_stdevrxploss;
400         /*! Maximum number of packets lost on local side */
401         double local_maxrxploss;
402         /*! Minimum number of packets lost on local side */
403         double local_minrxploss;
404         /*! Average number of packets lost on local side */
405         double local_normdevrxploss;
406         /*! Standard deviation packets lost on local side */
407         double local_stdevrxploss;
408         /*! Total round trip time */
409         double rtt;
410         /*! Maximum round trip time */
411         double maxrtt;
412         /*! Minimum round trip time */
413         double minrtt;
414         /*! Average round trip time */
415         double normdevrtt;
416         /*! Standard deviation round trip time */
417         double stdevrtt;
418         /*! Our SSRC */
419         unsigned int local_ssrc;
420         /*! Their SSRC */
421         unsigned int remote_ssrc;
422         /*! The Asterisk channel's unique ID that owns this instance */
423         char channel_uniqueid[MAX_CHANNEL_ID];
424         /*! Number of octets transmitted */
425         unsigned int txoctetcount;
426         /*! Number of octets received */
427         unsigned int rxoctetcount;
428 };
429
430 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
431 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == stat)) { \
432 placement = value; \
433 if (stat == current_stat) { \
434 return 0; \
435 } \
436 }
437
438 #define AST_RTP_STAT_STRCPY(current_stat, combined, placement, value) \
439 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == stat)) { \
440         ast_copy_string(placement, value, sizeof(placement)); \
441         if (stat == current_stat) { \
442                 return 0; \
443         } \
444 }
445
446 #define AST_RTP_STAT_TERMINATOR(combined) \
447 if (stat == combined) { \
448 return 0; \
449 }
450
451 /*! \brief ICE candidate types */
452 enum ast_rtp_ice_candidate_type {
453         AST_RTP_ICE_CANDIDATE_TYPE_HOST,    /*!< ICE host candidate. A host candidate represents the actual local transport address in the host. */
454         AST_RTP_ICE_CANDIDATE_TYPE_SRFLX,   /*!< ICE server reflexive candidate, which represents the public mapped address of the local address. */
455         AST_RTP_ICE_CANDIDATE_TYPE_RELAYED, /*!< ICE relayed candidate, which represents the address allocated in TURN server. */
456 };
457
458 /*! \brief ICE component types */
459 enum ast_rtp_ice_component_type {
460         AST_RTP_ICE_COMPONENT_RTP = 1,
461         AST_RTP_ICE_COMPONENT_RTCP = 2,
462 };
463
464 /*! \brief ICE role during negotiation */
465 enum ast_rtp_ice_role {
466         AST_RTP_ICE_ROLE_CONTROLLED,
467         AST_RTP_ICE_ROLE_CONTROLLING,
468 };
469
470 /*! \brief Structure for an ICE candidate */
471 struct ast_rtp_engine_ice_candidate {
472         char *foundation;                     /*!< Foundation identifier */
473         enum ast_rtp_ice_component_type id;   /*!< Component identifier */
474         char *transport;                      /*!< Transport for the media */
475         int priority;                         /*!< Priority which is used if multiple candidates can be used */
476         struct ast_sockaddr address;          /*!< Address of the candidate */
477         struct ast_sockaddr relay_address;    /*!< Relay address for the candidate */
478         enum ast_rtp_ice_candidate_type type; /*!< Type of candidate */
479 };
480
481 /*! \brief Structure that represents the optional ICE support within an RTP engine */
482 struct ast_rtp_engine_ice {
483         /*! Callback for setting received authentication information */
484         void (*set_authentication)(struct ast_rtp_instance *instance, const char *ufrag, const char *password);
485         /*! Callback for adding a remote candidate */
486         void (*add_remote_candidate)(struct ast_rtp_instance *instance, const struct ast_rtp_engine_ice_candidate *candidate);
487         /*! Callback for starting ICE negotiation */
488         void (*start)(struct ast_rtp_instance *instance);
489         /*! Callback for stopping ICE support */
490         void (*stop)(struct ast_rtp_instance *instance);
491         /*! Callback for getting local username */
492         const char *(*get_ufrag)(struct ast_rtp_instance *instance);
493         /*! Callback for getting local password */
494         const char *(*get_password)(struct ast_rtp_instance *instance);
495         /*! Callback for getting local candidates */
496         struct ao2_container *(*get_local_candidates)(struct ast_rtp_instance *instance);
497         /*! Callback for telling the ICE support that it is talking to an ice-lite implementation */
498         void (*ice_lite)(struct ast_rtp_instance *instance);
499         /*! Callback for changing our role in negotiation */
500         void (*set_role)(struct ast_rtp_instance *instance, enum ast_rtp_ice_role role);
501         /*! Callback for requesting a TURN session */
502         void (*turn_request)(struct ast_rtp_instance *instance, enum ast_rtp_ice_component_type component,
503                 enum ast_transport transport, const char *server, unsigned int port,
504                 const char *username, const char *password);
505         /*! Callback to alter the number of ICE components on a session */
506         void (*change_components)(struct ast_rtp_instance *instance, int num_components);
507 };
508
509 /*! \brief DTLS setup types */
510 enum ast_rtp_dtls_setup {
511         AST_RTP_DTLS_SETUP_ACTIVE,   /*!< Endpoint is willing to inititate connections */
512         AST_RTP_DTLS_SETUP_PASSIVE,  /*!< Endpoint is willing to accept connections */
513         AST_RTP_DTLS_SETUP_ACTPASS,  /*!< Endpoint is willing to both accept and initiate connections */
514         AST_RTP_DTLS_SETUP_HOLDCONN, /*!< Endpoint does not want the connection to be established right now */
515 };
516
517 /*! \brief DTLS connection states */
518 enum ast_rtp_dtls_connection {
519         AST_RTP_DTLS_CONNECTION_NEW,      /*!< Endpoint wants to use a new connection */
520         AST_RTP_DTLS_CONNECTION_EXISTING, /*!< Endpoint wishes to use existing connection */
521 };
522
523 /*! \brief DTLS fingerprint hashes */
524 enum ast_rtp_dtls_hash {
525         AST_RTP_DTLS_HASH_SHA256, /*!< SHA-256 fingerprint hash */
526         AST_RTP_DTLS_HASH_SHA1,   /*!< SHA-1 fingerprint hash */
527 };
528
529 /*! \brief DTLS verification settings */
530 enum ast_rtp_dtls_verify {
531         AST_RTP_DTLS_VERIFY_NONE = 0,               /*!< Don't verify anything */
532         AST_RTP_DTLS_VERIFY_FINGERPRINT = (1 << 0), /*!< Verify the fingerprint */
533         AST_RTP_DTLS_VERIFY_CERTIFICATE = (1 << 1), /*!< Verify the certificate */
534 };
535
536 /*!
537  * \brief Known RTP extensions
538  */
539 enum ast_rtp_extension {
540         /*! Per the RFC 0 should not be used, so we treat it as an unsupported extension placeholder */
541         AST_RTP_EXTENSION_UNSUPPORTED = 0,
542         /*! abs-send-time from https://tools.ietf.org/html/draft-alvestrand-rmcat-remb-03 */
543         AST_RTP_EXTENSION_ABS_SEND_TIME,
544         /*! The maximum number of known RTP extensions */
545         AST_RTP_EXTENSION_MAX,
546 };
547
548 /*! \brief DTLS configuration structure */
549 struct ast_rtp_dtls_cfg {
550         unsigned int enabled:1;                /*!< Whether DTLS support is enabled or not */
551         unsigned int rekey;                    /*!< Interval at which to renegotiate and rekey - defaults to 0 (off) */
552         enum ast_rtp_dtls_setup default_setup; /*!< Default setup type to use for outgoing */
553         enum ast_srtp_suite suite;             /*!< Crypto suite in use */
554         enum ast_rtp_dtls_hash hash;               /*!< Hash to use for fingerprint */
555         enum ast_rtp_dtls_verify verify;           /*!< What should be verified */
556         char *certfile;                        /*!< Certificate file */
557         char *pvtfile;                         /*!< Private key file */
558         char *cipher;                          /*!< Cipher to use */
559         char *cafile;                          /*!< Certificate authority file */
560         char *capath;                          /*!< Path to certificate authority */
561         unsigned int ephemeral_cert:1;         /*!< Whether to not to generate an ephemeral certificate - defaults to 0 (off) */
562 };
563
564 /*! \brief Structure that represents the optional DTLS SRTP support within an RTP engine */
565 struct ast_rtp_engine_dtls {
566         /*! Set the configuration of the DTLS support on the instance */
567         int (*set_configuration)(struct ast_rtp_instance *instance, const struct ast_rtp_dtls_cfg *dtls_cfg);
568         /*! Get if the DTLS SRTP support is active or not */
569         int (*active)(struct ast_rtp_instance *instance);
570         /*! Stop and terminate DTLS SRTP support */
571         void (*stop)(struct ast_rtp_instance *instance);
572         /*! Reset the connection and start fresh */
573         void (*reset)(struct ast_rtp_instance *instance);
574         /*! Get the current connection state */
575         enum ast_rtp_dtls_connection (*get_connection)(struct ast_rtp_instance *instance);
576         /*! Get the current setup state */
577         enum ast_rtp_dtls_setup (*get_setup)(struct ast_rtp_instance *instance);
578         /*! Set the remote setup state */
579         void (*set_setup)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_setup setup);
580         /*! Set the remote fingerprint */
581         void (*set_fingerprint)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_hash hash, const char *fingerprint);
582         /*! Get the local fingerprint hash type */
583         enum ast_rtp_dtls_hash (*get_fingerprint_hash)(struct ast_rtp_instance *instance);
584         /*! Get the local fingerprint */
585         const char *(*get_fingerprint)(struct ast_rtp_instance *instance);
586 };
587
588 /*! Structure that represents an RTP stack (engine) */
589 struct ast_rtp_engine {
590         /*! Name of the RTP engine, used when explicitly requested */
591         const char *name;
592         /*! Module this RTP engine came from, used for reference counting */
593         struct ast_module *mod;
594         /*! Callback for setting up a new RTP instance */
595         int (*new)(struct ast_rtp_instance *instance, struct ast_sched_context *sched, struct ast_sockaddr *sa, void *data);
596         /*! Callback for destroying an RTP instance */
597         int (*destroy)(struct ast_rtp_instance *instance);
598         /*! Callback for writing out a frame */
599         int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
600         /*! Callback for stopping the RTP instance */
601         void (*stop)(struct ast_rtp_instance *instance);
602         /*! Callback for starting RFC2833 DTMF transmission */
603         int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
604         /*! Callback for stopping RFC2833 DTMF transmission */
605         int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
606         int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
607         /*! Callback to indicate that we should update the marker bit */
608         void (*update_source)(struct ast_rtp_instance *instance);
609         /*! Callback to indicate that we should update the marker bit and ssrc */
610         void (*change_source)(struct ast_rtp_instance *instance);
611         /*! Callback for setting an extended RTP property */
612         int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
613         /*! Callback for getting an extended RTP property */
614         void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
615         /*! Callback for setting an RTP property */
616         void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
617         /*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
618         void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
619         /*! Callback for setting the remote address that RTP is to be sent to */
620         void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
621         /*! Callback for changing DTMF mode */
622         int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
623         /*! Callback for getting DTMF mode */
624         enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
625         /*! Callback for retrieving statistics */
626         int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
627         /*! Callback for setting QoS values */
628         int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
629         /*! Callback for retrieving a file descriptor to poll on, not always required */
630         int (*fd)(struct ast_rtp_instance *instance, int rtcp);
631         /*! Callback for initializing RED support */
632         int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
633         /*! Callback for buffering a frame using RED */
634         int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
635         /*! Callback for reading a frame from the RTP engine */
636         struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
637         /*! Callback to locally bridge two RTP instances */
638         int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
639         /*! Callback to set the read format */
640         int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
641         /*! Callback to set the write format */
642         int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
643         /*! Callback to make two instances compatible */
644         int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
645         /*! Callback to see if two instances are compatible with DTMF */
646         int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
647         /*! Callback to indicate that packets will now flow */
648         int (*activate)(struct ast_rtp_instance *instance);
649         /*! Callback to request that the RTP engine send a STUN BIND request */
650         void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
651         /*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
652         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);
653         /*! Callback to send CNG */
654         int (*sendcng)(struct ast_rtp_instance *instance, int level);
655         /*! Callback to retrieve local SSRC */
656         unsigned int (*ssrc_get)(struct ast_rtp_instance *instance);
657         /*! Callback to retrieve RTCP SDES CNAME */
658         const char *(*cname_get)(struct ast_rtp_instance *instance);
659         /*! Callback to bundle an RTP instance to another */
660         int (*bundle)(struct ast_rtp_instance *child, struct ast_rtp_instance *parent);
661         /*! Callback to set remote SSRC information */
662         void (*set_remote_ssrc)(struct ast_rtp_instance *instance, unsigned int ssrc);
663         /*! Callback to set the stream identifier */
664         void (*set_stream_num)(struct ast_rtp_instance *instance, int stream_num);
665         /*! Callback to pointer for optional ICE support */
666         struct ast_rtp_engine_ice *ice;
667         /*! Callback to pointer for optional DTLS SRTP support */
668         struct ast_rtp_engine_dtls *dtls;
669         /*! Callback to enable an RTP extension (returns non-zero if supported) */
670         int (*extension_enable)(struct ast_rtp_instance *instance, enum ast_rtp_extension extension);
671         /*! Linked list information */
672         AST_RWLIST_ENTRY(ast_rtp_engine) entry;
673 };
674
675 /*! Structure that represents codec and packetization information */
676 struct ast_rtp_codecs {
677         /*! RW lock that protects elements in this structure */
678         ast_rwlock_t codecs_lock;
679         /*! Rx payload type mapping exceptions */
680         AST_VECTOR(, struct ast_rtp_payload_type *) payload_mapping_rx;
681         /*! Tx payload type mapping */
682         AST_VECTOR(, struct ast_rtp_payload_type *) payload_mapping_tx;
683         /*! The framing for this media session */
684         unsigned int framing;
685 };
686
687 #define AST_RTP_CODECS_NULL_INIT \
688     { .codecs_lock = AST_RWLOCK_INIT_VALUE, .payload_mapping_rx = { 0, }, .payload_mapping_tx = { 0, }, .framing = 0, }
689
690 /*! Structure that represents the glue that binds an RTP instance to a channel */
691 struct ast_rtp_glue {
692         /*! Name of the channel driver that this glue is responsible for */
693         const char *type;
694         /*! Module that the RTP glue came from */
695         struct ast_module *mod;
696         /*!
697          * \brief Callback for retrieving the RTP instance carrying audio
698          * \note This function increases the reference count on the returned RTP instance.
699          */
700         enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
701         /*!
702          * \brief Used to prevent two channels from remotely bridging audio rtp if the channel tech has a
703          *        reason for prohibiting it based on qualities that need to be compared from both channels.
704          * \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.
705          */
706         int (*allow_rtp_remote)(struct ast_channel *chan1, struct ast_rtp_instance *instance);
707         /*!
708          * \brief Callback for retrieving the RTP instance carrying video
709          * \note This function increases the reference count on the returned RTP instance.
710          * \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.
711          */
712         enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
713         /*!
714          * \brief Used to prevent two channels from remotely bridging video rtp if the channel tech has a
715          *        reason for prohibiting it based on qualities that need to be compared from both channels.
716          * \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.
717          */
718         int (*allow_vrtp_remote)(struct ast_channel *chan1, struct ast_rtp_instance *instance);
719
720         /*!
721          * \brief Callback for retrieving the RTP instance carrying text
722          * \note This function increases the reference count on the returned RTP instance.
723          * \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.
724          */
725         enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
726         /*! Callback for updating the destination that the remote side should send RTP to */
727         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);
728         /*!
729          * \brief Callback for retrieving codecs that the channel can do.  Result returned in result_cap.
730          * \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.
731          */
732         void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
733         /*! Linked list information */
734         AST_RWLIST_ENTRY(ast_rtp_glue) entry;
735 };
736
737 /*!
738  * \brief Directions for RTP extensions
739  */
740 enum ast_rtp_extension_direction {
741         /*! The extension is not negotiated and is not flowing */
742         AST_RTP_EXTENSION_DIRECTION_NONE,
743         /*! Send and receive */
744         AST_RTP_EXTENSION_DIRECTION_SENDRECV,
745         /*! Send only */
746         AST_RTP_EXTENSION_DIRECTION_SENDONLY,
747         /*! Receive only */
748         AST_RTP_EXTENSION_DIRECTION_RECVONLY,
749         /*! Negotiated but not sending or receiving */
750         AST_RTP_EXTENSION_DIRECTION_INACTIVE,
751 };
752
753 /*!
754  * \brief Allocation routine for \ref ast_rtp_payload_type
755  *
756  * \retval NULL on error
757  * \retval An ao2 ref counted \c ast_rtp_payload_type on success.
758  *
759  * \note The \c ast_rtp_payload_type returned by this function is an
760  *       ao2 ref counted object.
761  *
762  */
763 struct ast_rtp_payload_type *ast_rtp_engine_alloc_payload_type(void);
764
765 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, AST_MODULE_SELF)
766
767 /*!
768  * \brief Register an RTP engine
769  *
770  * \param engine Structure of the RTP engine to register
771  * \param module Module that the RTP engine is part of
772  *
773  * \retval 0 success
774  * \retval -1 failure
775  *
776  * Example usage:
777  *
778  * \code
779  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
780  * \endcode
781  *
782  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
783  * associate a module with it.
784  *
785  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
786  *       associated with the RTP engine and use counting is performed.
787  *
788  * \since 1.8
789  */
790 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
791
792 /*!
793  * \brief Unregister an RTP engine
794  *
795  * \param engine Structure of the RTP engine to unregister
796  *
797  * \retval 0 success
798  * \retval -1 failure
799  *
800  * Example usage:
801  *
802  * \code
803  * ast_rtp_engine_unregister(&example_rtp_engine);
804  * \endcode
805  *
806  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
807  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
808  *
809  * \since 1.8
810  */
811 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
812
813 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
814
815 void ast_rtp_engine_unregister_srtp(void);
816 int ast_rtp_engine_srtp_is_registered(void);
817
818 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, AST_MODULE_SELF)
819
820 /*!
821  * \brief Register RTP glue
822  *
823  * \param glue The glue to register
824  * \param module Module that the RTP glue is part of
825  *
826  * \retval 0 success
827  * \retval -1 failure
828  *
829  * Example usage:
830  *
831  * \code
832  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
833  * \endcode
834  *
835  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
836  * associate a module with it.
837  *
838  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
839  *       associated with the RTP glue and use counting is performed.
840  *
841  * \since 1.8
842  */
843 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
844
845 /*!
846  * \brief Unregister RTP glue
847  *
848  * \param glue The glue to unregister
849  *
850  * \retval 0 success
851  * \retval -1 failure
852  *
853  * Example usage:
854  *
855  * \code
856  * ast_rtp_glue_unregister(&example_rtp_glue);
857  * \endcode
858  *
859  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
860  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
861  *
862  * \since 1.8
863  */
864 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
865
866 /*!
867  * \brief Create a new RTP instance
868  *
869  * \param engine_name Name of the engine to use for the RTP instance
870  * \param sched Scheduler context that the RTP engine may want to use
871  * \param sa Address we want to bind to
872  * \param data Unique data for the engine
873  *
874  * \retval non-NULL success
875  * \retval NULL failure
876  *
877  * Example usage:
878  *
879  * \code
880  * struct ast_rtp_instance *instance = NULL;
881  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
882  * \endcode
883  *
884  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
885  * in the address structure.
886  *
887  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
888  *       another depending on it's own configuration.
889  *
890  * \since 1.8
891  */
892 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
893                 struct ast_sched_context *sched, const struct ast_sockaddr *sa,
894                 void *data);
895
896 /*!
897  * \brief Destroy an RTP instance
898  *
899  * \param instance The RTP instance to destroy
900  *
901  * \retval 0 success
902  * \retval -1 failure
903  *
904  * Example usage:
905  *
906  * \code
907  * ast_rtp_instance_destroy(instance);
908  * \endcode
909  *
910  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
911  * memory and may not be used again.
912  *
913  * \since 1.8
914  */
915 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
916
917 /*!
918  * \brief Set the data portion of an RTP instance
919  *
920  * \param instance The RTP instance to manipulate
921  * \param data Pointer to data
922  *
923  * Example usage:
924  *
925  * \code
926  * ast_rtp_instance_set_data(instance, blob);
927  * \endcode
928  *
929  * This sets the data pointer on the RTP instance pointed to by 'instance' to
930  * blob.
931  *
932  * \since 1.8
933  */
934 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
935
936 /*!
937  * \brief Get the data portion of an RTP instance
938  *
939  * \param instance The RTP instance we want the data portion from
940  *
941  * Example usage:
942  *
943  * \code
944  * struct *blob = ast_rtp_instance_get_data(instance);
945  ( \endcode
946  *
947  * This gets the data pointer on the RTP instance pointed to by 'instance'.
948  *
949  * \since 1.8
950  */
951 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
952
953 /*!
954  * \brief Send a frame out over RTP
955  *
956  * \param instance The RTP instance to send frame out on
957  * \param frame the frame to send out
958  *
959  * \retval 0 success
960  * \retval -1 failure
961  *
962  * Example usage:
963  *
964  * \code
965  * ast_rtp_instance_write(instance, frame);
966  * \endcode
967  *
968  * This gives the frame pointed to by frame to the RTP engine being used for the instance
969  * and asks that it be transmitted to the current remote address set on the RTP instance.
970  *
971  * \since 1.8
972  */
973 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
974
975 /*!
976  * \brief Receive a frame over RTP
977  *
978  * \param instance The RTP instance to receive frame on
979  * \param rtcp Whether to read in RTCP or not
980  *
981  * \retval non-NULL success
982  * \retval NULL failure
983  *
984  * Example usage:
985  *
986  * \code
987  * struct ast_frame *frame;
988  * frame = ast_rtp_instance_read(instance, 0);
989  * \endcode
990  *
991  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
992  *
993  * \since 1.8
994  */
995 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
996
997 /*!
998  * \brief Set the incoming source address of the remote endpoint that we are sending RTP to
999  *
1000  * This sets the incoming source address the engine is sending RTP to. Usually this
1001  * will be the same as the requested target address, however in the case where
1002  * the engine "learns" the address (for instance, symmetric RTP enabled) this
1003  * will then contain the learned address.
1004  *
1005  * \param instance The RTP instance to change the address on
1006  * \param address Address to set it to
1007  *
1008  * \retval 0 success
1009  * \retval -1 failure
1010  */
1011 int ast_rtp_instance_set_incoming_source_address(struct ast_rtp_instance *instance,
1012                                                  const struct ast_sockaddr *address);
1013
1014 /*!
1015  * \brief Set the requested target address of the remote endpoint
1016  *
1017  * This should always be the address of the remote endpoint. Consequently, this can differ
1018  * from the address the engine is sending RTP to.  However, usually they will be the same
1019  * except in some circumstances (for instance when the engine "learns" the address if
1020  * symmetric RTP is enabled).
1021  *
1022  * \param instance The RTP instance to change the address on
1023  * \param address Address to set it to
1024  *
1025  * \retval 0 success
1026  * \retval -1 failure
1027  */
1028 int ast_rtp_instance_set_requested_target_address(struct ast_rtp_instance *instance,
1029                                                   const struct ast_sockaddr *address);
1030
1031 /*!
1032  * \brief Set the address of the remote endpoint that we are sending RTP to
1033  *
1034  * \param instance The RTP instance to change the address on
1035  * \param address Address to set it to
1036  *
1037  * \retval 0 success
1038  * \retval -1 failure
1039  *
1040  * Example usage:
1041  *
1042  * \code
1043  * ast_rtp_instance_set_remote_address(instance, &sin);
1044  * \endcode
1045  *
1046  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
1047  * structure.
1048  *
1049  * \since 1.8
1050  */
1051 #define ast_rtp_instance_set_remote_address(instance, address) \
1052         ast_rtp_instance_set_requested_target_address((instance), (address))
1053
1054 /*!
1055  * \brief Set the address that we are expecting to receive RTP on
1056  *
1057  * \param instance The RTP instance to change the address on
1058  * \param address Address to set it to
1059  *
1060  * \retval 0 success
1061  * \retval -1 failure
1062  *
1063  * Example usage:
1064  *
1065  * \code
1066  * ast_rtp_instance_set_local_address(instance, &sin);
1067  * \endcode
1068  *
1069  * This changes the local address that RTP is expected on to the address given in the sin
1070  * structure.
1071  *
1072  * \since 1.8
1073  */
1074 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
1075                 const struct ast_sockaddr *address);
1076
1077 /*!
1078  * \brief Get the local address that we are expecting RTP on
1079  *
1080  * \param instance The RTP instance to get the address from
1081  * \param address The variable to store the address in
1082  *
1083  * Example usage:
1084  *
1085  * \code
1086  * struct ast_sockaddr address;
1087  * ast_rtp_instance_get_local_address(instance, &address);
1088  * \endcode
1089  *
1090  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
1091  *
1092  * \since 1.8
1093  */
1094 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
1095
1096 /*!
1097  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
1098  *
1099  * \param instance The instance that we want to get the local address for
1100  * \param address An initialized address that may be overwritten if the local address is different
1101  *
1102  * \retval 0 address was not changed
1103  * \retval 1 address was changed
1104  * Example usage:
1105  *
1106  * \code
1107  * struct ast_sockaddr address;
1108  * int ret;
1109  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
1110  * \endcode
1111  *
1112  * This retrieves the current local address set on the instance pointed to by instance and puts the value
1113  * into the address structure.
1114  *
1115  * \since 1.8
1116  */
1117 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
1118
1119 /*!
1120  * \brief Get the incoming source address of the remote endpoint
1121  *
1122  * This returns the remote address the engine is sending RTP to. Usually this
1123  * will be the same as the requested target address, however in the case where
1124  * the engine "learns" the address (for instance, symmetric RTP enabled) this
1125  * will then contain the learned address.
1126  *
1127  * \param instance The instance that we want to get the incoming source address for
1128  * \param address A structure to put the address into
1129  */
1130 void ast_rtp_instance_get_incoming_source_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
1131
1132 /*!
1133  * \brief Get the requested target address of the remote endpoint
1134  *
1135  * This returns the explicitly set address of a remote endpoint. Meaning this won't change unless
1136  * specifically told to change. In most cases this should be the same as the incoming source
1137  * address, except in cases where the engine "learns" the address in which case this and the
1138  * incoming source address might differ.
1139  *
1140  * \param instance The instance that we want to get the requested target address for
1141  * \param address A structure to put the address into
1142  */
1143 void ast_rtp_instance_get_requested_target_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
1144
1145 /*!
1146  * \brief Get the address of the remote endpoint that we are sending RTP to
1147  *
1148  * \param instance The instance that we want to get the remote address for
1149  * \param address A structure to put the address into
1150  *
1151  * Example usage:
1152  *
1153  * \code
1154  * struct ast_sockaddr address;
1155  * ast_rtp_instance_get_remote_address(instance, &address);
1156  * \endcode
1157  *
1158  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
1159  * into the address structure.
1160  *
1161  * \since 1.8
1162  */
1163 #define ast_rtp_instance_get_remote_address(instance, address) \
1164         ast_rtp_instance_get_incoming_source_address((instance), (address))
1165
1166 /*!
1167  * \brief Get the requested target address of the remote endpoint and
1168  *        compare it to the given address
1169  *
1170  * \param instance The instance that we want to get the remote address for
1171  * \param address An initialized address that may be overwritten addresses differ
1172  *
1173  * \retval 0 address was not changed
1174  * \retval 1 address was changed
1175  */
1176 int ast_rtp_instance_get_and_cmp_requested_target_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
1177
1178 /*!
1179  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
1180  *
1181  * \param instance The instance that we want to get the remote address for
1182  * \param address An initialized address that may be overwritten if the remote address is different
1183  *
1184  * \retval 0 address was not changed
1185  * \retval 1 address was changed
1186  * Example usage:
1187  *
1188  * \code
1189  * struct ast_sockaddr address;
1190  * int ret;
1191  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
1192  * \endcode
1193  *
1194  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
1195  * into the address structure.
1196  *
1197  * \since 1.8
1198  */
1199 #define ast_rtp_instance_get_and_cmp_remote_address(instance, address) \
1200         ast_rtp_instance_get_and_cmp_requested_target_address((instance), (address))
1201
1202 /*!
1203  * \brief Set the value of an RTP instance extended property
1204  *
1205  * \param instance The RTP instance to set the extended property on
1206  * \param property The extended property to set
1207  * \param value The value to set the extended property to
1208  *
1209  * \since 1.8
1210  */
1211 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
1212
1213 /*!
1214  * \brief Get the value of an RTP instance extended property
1215  *
1216  * \param instance The RTP instance to get the extended property on
1217  * \param property The extended property to get
1218  *
1219  * \since 1.8
1220  */
1221 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
1222
1223 /*!
1224  * \brief Set the value of an RTP instance property
1225  *
1226  * \param instance The RTP instance to set the property on
1227  * \param property The property to modify
1228  * \param value The value to set the property to
1229  *
1230  * Example usage:
1231  *
1232  * \code
1233  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
1234  * \endcode
1235  *
1236  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
1237  *
1238  * \since 1.8
1239  */
1240 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
1241
1242 /*!
1243  * \brief Get the value of an RTP instance property
1244  *
1245  * \param instance The RTP instance to get the property from
1246  * \param property The property to get
1247  *
1248  * \retval Current value of the property
1249  *
1250  * Example usage:
1251  *
1252  * \code
1253  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
1254  * \endcode
1255  *
1256  * This returns the current value of the NAT property on the instance pointed to by instance.
1257  *
1258  * \since 1.8
1259  */
1260 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
1261
1262 /*!
1263  * \brief Get the codecs structure of an RTP instance
1264  *
1265  * \param instance The RTP instance to get the codecs structure from
1266  *
1267  * Example usage:
1268  *
1269  * \code
1270  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
1271  * \endcode
1272  *
1273  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
1274  *
1275  * \since 1.8
1276  */
1277 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
1278
1279 /*!
1280  * \brief Enable support for an RTP extension on an instance
1281  *
1282  * \param instance The RTP instance to enable the extension on
1283  * \param id The unique local identifier to use for this extension (-1 to have one auto selected)
1284  * \param extension The RTP extension
1285  * \param direction The initial direction that the RTP extension should be used in
1286  *
1287  * \retval 0 success
1288  * \retval -1 failure
1289  *
1290  * \since 15.5.0
1291  */
1292 int ast_rtp_instance_extmap_enable(struct ast_rtp_instance *instance, int id, enum ast_rtp_extension extension,
1293         enum ast_rtp_extension_direction direction);
1294
1295 /*!
1296  * \brief Negotiate received RTP extension information
1297  *
1298  * \param instance The RTP instance to set the extension on
1299  * \param id The local identifier for the extension
1300  * \param direction The direction that the extension should be used in
1301  * \param uri The unique URI for the extension
1302  * \param attributes Attributes specific to this extension (if NULL or empty then no attributes)
1303  *
1304  * \retval 0 success
1305  * \retval -1 failure
1306  *
1307  * \since 15.5.0
1308  */
1309 int ast_rtp_instance_extmap_negotiate(struct ast_rtp_instance *instance, int id, enum ast_rtp_extension_direction direction,
1310         const char *uri, const char *attributes);
1311
1312 /*!
1313  * \brief Clear negotiated RTP extension information
1314  *
1315  * \param instance The RTP instance to clear negotiated extension information on
1316  */
1317 void ast_rtp_instance_extmap_clear(struct ast_rtp_instance *instance);
1318
1319 /*!
1320  * \brief Retrieve the id for an RTP extension
1321  *
1322  * \param instance The RTP instance to retrieve the id from
1323  * \param extension The RTP extension
1324  *
1325  * \retval -1 not negotiated
1326  * \retval id if negotiated
1327  *
1328  * \since 15.5.0
1329  */
1330 int ast_rtp_instance_extmap_get_id(struct ast_rtp_instance *instance, enum ast_rtp_extension extension);
1331
1332 /*!
1333  * \brief Get the number of known unique identifiers
1334  *
1335  * \param instance The RTP instance to retrieve the count from
1336  *
1337  * \return the number of known unique identifiers
1338  *
1339  * \since 15.5.0
1340  */
1341 size_t ast_rtp_instance_extmap_count(struct ast_rtp_instance *instance);
1342
1343 /*!
1344  * \brief Retrieve the extension for an RTP extension id
1345  *
1346  * \param instance The RTP instance to retrieve the extension from
1347  * \param id The negotiated RTP extension id
1348  *
1349  * \retval extension the extension that maps to the id
1350  *
1351  * \since 15.5.0
1352  *
1353  * \note This will return AST_RTP_EXTENSION_UNSUPPORTED if an extension was proposed for this unique identifier
1354  * but it is not supported or if the unique identifier is unused.
1355  */
1356 enum ast_rtp_extension ast_rtp_instance_extmap_get_extension(struct ast_rtp_instance *instance, int id);
1357
1358 /*!
1359  * \brief Retrieve the negotiated direction for an RTP extension id
1360  *
1361  * \param instance The RTP instance to retrieve the direction from
1362  * \param id The negotiated RTP extension id
1363  *
1364  * \retval direction the direction that has been negotiated
1365  *
1366  * \since 15.5.0
1367  */
1368 enum ast_rtp_extension_direction ast_rtp_instance_extmap_get_direction(struct ast_rtp_instance *instance, int id);
1369
1370 /*!
1371  * \brief Retrieve the URI for an RTP extension id
1372  *
1373  * \param instance The RTP instance to retrieve the direction from
1374  * \param id The negotiated RTP extension id
1375  *
1376  * \retval uri The URI for the RTP extension
1377  *
1378  * \since 15.5.0
1379  */
1380 const char *ast_rtp_instance_extmap_get_uri(struct ast_rtp_instance *instance, int id);
1381
1382 /*!
1383  * \brief Initialize an RTP codecs structure
1384  *
1385  * \param codecs The codecs structure to initialize
1386  *
1387  * \retval 0 success
1388  * \retval -1 failure
1389  *
1390  * Example usage:
1391  *
1392  * \code
1393  * struct ast_rtp_codecs codecs;
1394  * ast_rtp_codecs_payloads_initialize(&codecs);
1395  * \endcode
1396  *
1397  * \since 11
1398  */
1399 int ast_rtp_codecs_payloads_initialize(struct ast_rtp_codecs *codecs);
1400
1401 /*!
1402  * \brief Destroy the contents of an RTP codecs structure (but not the structure itself)
1403  *
1404  * \param codecs The codecs structure to destroy the contents of
1405  *
1406  * Example usage:
1407  *
1408  * \code
1409  * struct ast_rtp_codecs codecs;
1410  * ast_rtp_codecs_payloads_destroy(&codecs);
1411  * \endcode
1412  *
1413  * \since 11
1414  */
1415 void ast_rtp_codecs_payloads_destroy(struct ast_rtp_codecs *codecs);
1416
1417 /*!
1418  * \brief Clear rx and tx payload mapping information from an RTP instance
1419  *
1420  * \param codecs The codecs structure that payloads will be cleared from
1421  * \param instance Optionally the instance that the codecs structure belongs to
1422  *
1423  * Example usage:
1424  *
1425  * \code
1426  * struct ast_rtp_codecs codecs;
1427  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
1428  * \endcode
1429  *
1430  * This clears the codecs structure and puts it into a pristine state.
1431  *
1432  * \since 1.8
1433  */
1434 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
1435
1436 /*!
1437  * \brief Copy payload information from one RTP instance to another
1438  *
1439  * \param src The source codecs structure
1440  * \param dest The destination codecs structure that the values from src will be copied to
1441  * \param instance Optionally the instance that the dst codecs structure belongs to
1442  *
1443  * Example usage:
1444  *
1445  * \code
1446  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
1447  * \endcode
1448  *
1449  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
1450  *
1451  * \since 1.8
1452  */
1453 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
1454
1455 /*!
1456  * \brief Crossover copy the tx payload mapping of src to the rx payload mapping of dest.
1457  * \since 14.0.0
1458  *
1459  * \param src The source codecs structure
1460  * \param dest The destination codecs structure that the values from src will be copied to
1461  * \param instance Optionally the instance that the dst codecs structure belongs to
1462  *
1463  * \return Nothing
1464  */
1465 void ast_rtp_codecs_payloads_xover(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
1466
1467 /*!
1468  * \brief Record tx payload type information that was seen in an m= SDP line
1469  *
1470  * \param codecs The codecs structure to muck with
1471  * \param instance Optionally the instance that the codecs structure belongs to
1472  * \param payload Numerical payload that was seen in the m= SDP line
1473  *
1474  * Example usage:
1475  *
1476  * \code
1477  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
1478  * \endcode
1479  *
1480  * This records that the numerical payload '0' was seen in the codecs structure.
1481  *
1482  * \since 1.8
1483  */
1484 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1485
1486 /*!
1487  * \brief Record tx payload type information that was seen in an a=rtpmap: SDP line
1488  *
1489  * \param codecs The codecs structure to muck with
1490  * \param instance Optionally the instance that the codecs structure belongs to
1491  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
1492  * \param mimetype The string mime type that was seen
1493  * \param mimesubtype The strin mime sub type that was seen
1494  * \param options Optional options that may change the behavior of this specific payload
1495  *
1496  * \retval 0 success
1497  * \retval -1 failure, invalid payload numbe
1498  * \retval -2 failure, unknown mimetype
1499  *
1500  * Example usage:
1501  *
1502  * \code
1503  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
1504  * \endcode
1505  *
1506  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
1507  *
1508  * \since 1.8
1509  */
1510 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);
1511
1512 /*!
1513  * \brief Set tx payload type to a known MIME media type for a codec with a specific sample rate
1514  *
1515  * \param codecs RTP structure to modify
1516  * \param instance Optionally the instance that the codecs structure belongs to
1517  * \param pt Payload type entry to modify
1518  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
1519  * \param mimesubtype MIME subtype of media stream (typically a codec name)
1520  * \param options Zero or more flags from the ast_rtp_options enum
1521  * \param sample_rate The sample rate of the media stream
1522  *
1523  * This function 'fills in' an entry in the list of possible formats for
1524  * a media stream associated with an RTP structure.
1525  *
1526  * \retval 0 on success
1527  * \retval -1 if the payload type is out of range
1528  * \retval -2 if the mimeType/mimeSubtype combination was not found
1529  *
1530  * \since 1.8
1531  */
1532 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
1533                                   char *mimetype, char *mimesubtype,
1534                                   enum ast_rtp_options options,
1535                                   unsigned int sample_rate);
1536
1537 /*!
1538  * \brief Remove tx payload type mapped information
1539  *
1540  * \param codecs The codecs structure to muck with
1541  * \param instance Optionally the instance that the codecs structure belongs to
1542  * \param payload Numerical payload to unset
1543  *
1544  * Example usage:
1545  *
1546  * \code
1547  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
1548  * \endcode
1549  *
1550  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
1551  *
1552  * \since 1.8
1553  */
1554 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1555
1556 /*!
1557  * \brief Determine the type of RTP stream media from the codecs mapped.
1558  * \since 13.19.0
1559  *
1560  * \param codecs Codecs structure to look in
1561  *
1562  * \return Media type or AST_MEDIA_TYPE_UNKNOWN if no codecs mapped.
1563  */
1564 enum ast_media_type ast_rtp_codecs_get_stream_type(struct ast_rtp_codecs *codecs);
1565
1566 /*!
1567  * \brief Retrieve rx payload mapped information by payload type
1568  *
1569  * \param codecs Codecs structure to look in
1570  * \param payload Numerical payload to look up
1571  *
1572  * \retval Payload information.
1573  * \retval NULL if payload does not exist.
1574  *
1575  * \note The payload returned by this function has its reference count increased.
1576  *       Callers are responsible for decrementing the reference count.
1577  *
1578  * Example usage:
1579  *
1580  * \code
1581  * struct ast_rtp_payload_type *payload_type;
1582  * payload_type = ast_rtp_codecs_get_payload(&codecs, 0);
1583  * \endcode
1584  *
1585  * This looks up the information for payload '0' from the codecs structure.
1586  */
1587 struct ast_rtp_payload_type *ast_rtp_codecs_get_payload(struct ast_rtp_codecs *codecs, int payload);
1588
1589 /*!
1590  * \brief Update the format associated with a tx payload type in a codecs structure
1591  *
1592  * \param codecs Codecs structure to operate on
1593  * \param payload Numerical payload type to look up
1594  * \param format The format to replace the existing one
1595  *
1596  * \retval 0 success
1597  * \retval -1 failure
1598  *
1599  * \since 13
1600  */
1601 int ast_rtp_codecs_payload_replace_format(struct ast_rtp_codecs *codecs, int payload, struct ast_format *format);
1602
1603 /*!
1604  * \brief Retrieve the actual ast_format stored on the codecs structure for a specific tx payload type
1605  *
1606  * \param codecs Codecs structure to look in
1607  * \param payload Numerical payload type to look up
1608  *
1609  * \retval pointer to format structure on success
1610  * \retval NULL on failure
1611  *
1612  * \note The format returned by this function has its reference count increased.
1613  *       Callers are responsible for decrementing the reference count.
1614  *
1615  * \since 10.0
1616  */
1617 struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *codecs, int payload);
1618
1619 /*!
1620  * \brief Set the framing used for a set of codecs
1621  *
1622  * \param codecs Codecs structure to set framing on
1623  * \param framing The framing value to set on the codecs
1624  *
1625  * \since 13.0.0
1626  */
1627 void ast_rtp_codecs_set_framing(struct ast_rtp_codecs *codecs, unsigned int framing);
1628
1629 /*!
1630  * \brief Get the framing used for a set of codecs
1631  *
1632  * \param codecs Codecs structure to get the framing from
1633  *
1634  * \retval The framing to be used for the media stream associated with these codecs
1635  *
1636  * \since 13.0.0
1637  */
1638 unsigned int ast_rtp_codecs_get_framing(struct ast_rtp_codecs *codecs);
1639
1640 /*!
1641  * \brief Get the sample rate associated with known RTP payload types
1642  *
1643  * \param asterisk_format True if the value in format is to be used.
1644  * \param format An asterisk format
1645  * \param code from AST_RTP list
1646  *
1647  * \return the sample rate if the format was found, zero if it was not found
1648  *
1649  * \since 1.8
1650  */
1651 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format,
1652         const struct ast_format *format, int code);
1653
1654 /*!
1655  * \brief Retrieve all formats that were found
1656  *
1657  * \param codecs Codecs structure to look in
1658  * \param astformats A capabilities structure to put the Asterisk formats in.
1659  * \param nonastformats An integer to put the non-Asterisk formats in
1660  *
1661  * Example usage:
1662  *
1663  * \code
1664  * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
1665  * int nonastformats;
1666  * ast_rtp_codecs_payload_formats(&codecs, astformats, &nonastformats);
1667  * \endcode
1668  *
1669  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
1670  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
1671  *
1672  * \since 1.8
1673  */
1674 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
1675
1676 /*!
1677  * \brief Retrieve a rx mapped payload type based on whether it is an Asterisk format and the code
1678  *
1679  * \param codecs Codecs structure to look in
1680  * \param asterisk_format Non-zero if the given Asterisk format is present
1681  * \param format Asterisk format to look for
1682  * \param code The format to look for
1683  *
1684  * \details
1685  * Find the currently assigned rx mapped payload type based on whether it
1686  * is an Asterisk format or non-format code.  If one is currently not
1687  * assigned then create a rx payload type mapping.
1688  *
1689  * \retval Numerical payload type
1690  * \retval -1 if could not assign.
1691  *
1692  * Example usage:
1693  *
1694  * \code
1695  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
1696  * \endcode
1697  *
1698  * This looks for the numerical payload for ULAW in the codecs structure.
1699  *
1700  * \since 1.8
1701  */
1702 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, struct ast_format *format, int code);
1703
1704 /*!
1705  * \brief Set a payload code for use with a specific Asterisk format
1706  *
1707  * \param codecs Codecs structure to manipulate
1708  * \param code The payload code
1709  * \param format Asterisk format
1710  *
1711  * \retval 0 Payload was set to the given format
1712  * \retval -1 Payload was in use or could not be set
1713  *
1714  * \since 15.0.0
1715  */
1716 int ast_rtp_codecs_payload_set_rx(struct ast_rtp_codecs *codecs, int code, struct ast_format *format);
1717
1718 /*!
1719  * \brief Retrieve a tx mapped payload type based on whether it is an Asterisk format and the code
1720  * \since 14.0.0
1721  *
1722  * \param codecs Codecs structure to look in
1723  * \param asterisk_format Non-zero if the given Asterisk format is present
1724  * \param format Asterisk format to look for
1725  * \param code The format to look for
1726  *
1727  * \retval Numerical payload type
1728  * \retval -1 if not found.
1729  */
1730 int ast_rtp_codecs_payload_code_tx(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
1731
1732 /*!
1733  * \brief Search for the tx payload type in the ast_rtp_codecs structure
1734  *
1735  * \param codecs Codecs structure to look in
1736  * \param payload The payload type format to look for
1737  *
1738  * \retval Numerical payload type or -1 if unable to find payload in codecs
1739  *
1740  * Example usage:
1741  *
1742  * \code
1743  * int payload = ast_rtp_codecs_find_payload_code(&codecs, 0);
1744  * \endcode
1745  *
1746  * This looks for the numerical payload for ULAW in the codecs structure.
1747  */
1748 int ast_rtp_codecs_find_payload_code(struct ast_rtp_codecs *codecs, int payload);
1749
1750 /*!
1751  * \brief Retrieve mime subtype information on a payload
1752  *
1753  * \param asterisk_format Non-zero to look up using Asterisk format
1754  * \param format Asterisk format to look up
1755  * \param code RTP code to look up
1756  * \param options Additional options that may change the result
1757  *
1758  * \retval Mime subtype success
1759  * \retval NULL failure
1760  *
1761  * Example usage:
1762  *
1763  * \code
1764  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
1765  * \endcode
1766  *
1767  * This looks up the mime subtype for the ULAW format.
1768  *
1769  * \since 1.8
1770  */
1771 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format,
1772         const struct ast_format *format, int code, enum ast_rtp_options options);
1773
1774 /*!
1775  * \brief Convert formats into a string and put them into a buffer
1776  *
1777  * \param buf Buffer to put the mime output into
1778  * \param ast_format_capability Asterisk Formats we are looking up.
1779  * \param rtp_capability RTP codes that we are looking up
1780  * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
1781  * \param options Additional options that may change the result
1782  *
1783  * \retval non-NULL success
1784  * \retval NULL failure
1785  *
1786  * Example usage:
1787  *
1788  * \code
1789  * char buf[256] = "";
1790  * struct ast_format tmp_fmt;
1791  * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
1792  * ast_format_cap_append(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1793  * ast_format_cap_append(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
1794  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
1795  * ast_format_cap_destroy(cap);
1796  * \endcode
1797  *
1798  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
1799  *
1800  * \since 1.8
1801  */
1802 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);
1803
1804 /*!
1805  * \brief Begin sending a DTMF digit
1806  *
1807  * \param instance The RTP instance to send the DTMF on
1808  * \param digit What DTMF digit to send
1809  *
1810  * \retval 0 success
1811  * \retval -1 failure
1812  *
1813  * Example usage:
1814  *
1815  * \code
1816  * ast_rtp_instance_dtmf_begin(instance, '1');
1817  * \endcode
1818  *
1819  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
1820  * continue being sent until it is ended.
1821  *
1822  * \since 1.8
1823  */
1824 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
1825
1826 /*!
1827  * \brief Stop sending a DTMF digit
1828  *
1829  * \param instance The RTP instance to stop the DTMF on
1830  * \param digit What DTMF digit to stop
1831  *
1832  * \retval 0 success
1833  * \retval -1 failure
1834  *
1835  * Example usage:
1836  *
1837  * \code
1838  * ast_rtp_instance_dtmf_end(instance, '1');
1839  * \endcode
1840  *
1841  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
1842  *
1843  * \since 1.8
1844  */
1845 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
1846 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
1847
1848 /*!
1849  * \brief Set the DTMF mode that should be used
1850  *
1851  * \param instance the RTP instance to set DTMF mode on
1852  * \param dtmf_mode The DTMF mode that is in use
1853  *
1854  * \retval 0 success
1855  * \retval -1 failure
1856  *
1857  * Example usage:
1858  *
1859  * \code
1860  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
1861  * \endcode
1862  *
1863  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
1864  *
1865  * \since 1.8
1866  */
1867 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
1868
1869 /*!
1870  * \brief Get the DTMF mode of an RTP instance
1871  *
1872  * \param instance The RTP instance to get the DTMF mode of
1873  *
1874  * \retval DTMF mode
1875  *
1876  * Example usage:
1877  *
1878  * \code
1879  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
1880  * \endcode
1881  *
1882  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
1883  *
1884  * \since 1.8
1885  */
1886 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
1887
1888 /*!
1889  * \brief Indicate that the RTP marker bit should be set on an RTP stream
1890  *
1891  * \param instance Instance that the new media source is feeding into
1892  *
1893  * Example usage:
1894  *
1895  * \code
1896  * ast_rtp_instance_update_source(instance);
1897  * \endcode
1898  *
1899  * This indicates that the source of media that is feeding the instance pointed to by
1900  * instance has been updated and that the marker bit should be set.
1901  *
1902  * \since 1.8
1903  */
1904 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
1905
1906 /*!
1907  * \brief Indicate a new source of audio has dropped in and the ssrc should change
1908  *
1909  * \param instance Instance that the new media source is feeding into
1910  *
1911  * Example usage:
1912  *
1913  * \code
1914  * ast_rtp_instance_change_source(instance);
1915  * \endcode
1916  *
1917  * This indicates that the source of media that is feeding the instance pointed to by
1918  * instance has changed and that the marker bit should be set and the SSRC updated.
1919  *
1920  * \since 1.8
1921  */
1922 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
1923
1924 /*!
1925  * \brief Set QoS parameters on an RTP session
1926  *
1927  * \param instance Instance to set the QoS parameters on
1928  * \param tos Terms of service value
1929  * \param cos Class of service value
1930  * \param desc What is setting the QoS values
1931  *
1932  * \retval 0 success
1933  * \retval -1 failure
1934  *
1935  * Example usage:
1936  *
1937  * \code
1938  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
1939  * \endcode
1940  *
1941  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
1942  *
1943  * \since 1.8
1944  */
1945 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
1946
1947 /*!
1948  * \brief Stop an RTP instance
1949  *
1950  * \param instance Instance that media is no longer going to at this time
1951  *
1952  * Example usage:
1953  *
1954  * \code
1955  * ast_rtp_instance_stop(instance);
1956  * \endcode
1957  *
1958  * This tells the RTP engine being used for the instance pointed to by instance
1959  * that media is no longer going to it at this time, but may in the future.
1960  *
1961  * \since 1.8
1962  */
1963 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
1964
1965 /*!
1966  * \brief Get the file descriptor for an RTP session (or RTCP)
1967  *
1968  * \param instance Instance to get the file descriptor for
1969  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
1970  *
1971  * \retval fd success
1972  * \retval -1 failure
1973  *
1974  * Example usage:
1975  *
1976  * \code
1977  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
1978  * \endcode
1979  *
1980  * This retrieves the file descriptor for the socket carrying media on the instance
1981  * pointed to by instance.
1982  *
1983  * \since 1.8
1984  */
1985 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
1986
1987 /*!
1988  * \brief Get the RTP glue that binds a channel to the RTP engine
1989  *
1990  * \param type Name of the glue we want
1991  *
1992  * \retval non-NULL success
1993  * \retval NULL failure
1994  *
1995  * Example usage:
1996  *
1997  * \code
1998  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
1999  * \endcode
2000  *
2001  * This retrieves the RTP glue that has the name 'Example'.
2002  *
2003  * \since 1.8
2004  */
2005 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
2006
2007 /*!
2008  * \brief Get the unique ID of the channel that owns this RTP instance
2009  *
2010  * Note that this should remain valid for the lifetime of the RTP instance.
2011  *
2012  * \param instance The RTP instance
2013  *
2014  * \retval The unique ID of the channel
2015  * \retval Empty string if no channel owns this RTP instance
2016  *
2017  * \since 12
2018  */
2019 const char *ast_rtp_instance_get_channel_id(struct ast_rtp_instance *instance);
2020
2021 /*!
2022  * \brief Set the channel that owns this RTP instance
2023  *
2024  * \param instance The RTP instance
2025  * \param uniqueid The uniqueid of the channel
2026  *
2027  * \since 12
2028  */
2029 void ast_rtp_instance_set_channel_id(struct ast_rtp_instance *instance, const char *uniqueid);
2030
2031 /*!
2032  * \brief Get the other RTP instance that an instance is bridged to
2033  *
2034  * \param instance The RTP instance that we want
2035  *
2036  * \retval non-NULL success
2037  * \retval NULL failure
2038  *
2039  * Example usage:
2040  *
2041  * \code
2042  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
2043  * \endcode
2044  *
2045  * This gets the RTP instance that instance0 is bridged to.
2046  *
2047  * \since 1.8
2048  */
2049 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
2050
2051 /*!
2052  * \brief Set the other RTP instance that an instance is bridged to
2053  *
2054  * \param instance The RTP instance that we want to set the bridged value on
2055  * \param bridged The RTP instance they are bridged to
2056  *
2057  * \since 12
2058  */
2059 void ast_rtp_instance_set_bridged(struct ast_rtp_instance *instance, struct ast_rtp_instance *bridged);
2060
2061 /*!
2062  * \brief Make two channels compatible for early bridging
2063  *
2064  * \param c_dst Destination channel to copy to
2065  * \param c_src Source channel to copy from
2066  *
2067  * \since 1.8
2068  */
2069 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c_dst, struct ast_channel *c_src);
2070
2071 /*!
2072  * \brief Early bridge two channels that use RTP instances
2073  *
2074  * \param c0 First channel part of the bridge
2075  * \param c1 Second channel part of the bridge
2076  *
2077  * \retval 0 success
2078  * \retval -1 failure
2079  *
2080  * \note This should only be used by channel drivers in their technology declaration.
2081  *
2082  * \since 1.8
2083  */
2084 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
2085
2086 /*!
2087  * \brief Initialize RED support on an RTP instance
2088  *
2089  * \param instance The instance to initialize RED support on
2090  * \param buffer_time How long to buffer before sending
2091  * \param payloads Payload values
2092  * \param generations Number of generations
2093  *
2094  * \retval 0 success
2095  * \retval -1 failure
2096  *
2097  * \since 1.8
2098  */
2099 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
2100
2101 /*!
2102  * \brief Buffer a frame in an RTP instance for RED
2103  *
2104  * \param instance The instance to buffer the frame on
2105  * \param frame Frame that we want to buffer
2106  *
2107  * \retval 0 success
2108  * \retval -1 failure
2109  *
2110  * \since 1.8
2111  */
2112 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
2113
2114 /*!
2115  * \brief Retrieve statistics about an RTP instance
2116  *
2117  * \param instance Instance to get statistics on
2118  * \param stats Structure to put results into
2119  * \param stat What statistic(s) to retrieve
2120  *
2121  * \retval 0 success
2122  * \retval -1 failure
2123  *
2124  * Example usage:
2125  *
2126  * \code
2127  * struct ast_rtp_instance_stats stats;
2128  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
2129  * \endcode
2130  *
2131  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
2132  * stats structure.
2133  *
2134  * \since 1.8
2135  */
2136 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
2137
2138 /*!
2139  * \brief Set standard statistics from an RTP instance on a channel
2140  *
2141  * \param chan Channel to set the statistics on
2142  * \param instance The RTP instance that statistics will be retrieved from
2143  *
2144  * \note Absolutely _NO_ channel locks should be held before calling this function.
2145  *
2146  * Example usage:
2147  *
2148  * \code
2149  * ast_rtp_instance_set_stats_vars(chan, rtp);
2150  * \endcode
2151  *
2152  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
2153  * by chan.
2154  *
2155  * \since 1.8
2156  */
2157 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
2158
2159 /*!
2160  * \brief Retrieve quality statistics about an RTP instance
2161  *
2162  * \param instance Instance to get statistics on
2163  * \param field What quality statistic to retrieve
2164  * \param buf What buffer to put the result into
2165  * \param size Size of the above buffer
2166  *
2167  * \retval non-NULL success
2168  * \retval NULL failure
2169  *
2170  * Example usage:
2171  *
2172  * \code
2173  * char quality[AST_MAX_USER_FIELD];
2174  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
2175  * \endcode
2176  *
2177  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
2178  *
2179  * \since 1.8
2180  */
2181 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
2182
2183 /*!
2184  * \brief Request that the underlying RTP engine provide audio frames in a specific format
2185  *
2186  * \param instance The RTP instance to change read format on
2187  * \param format Format that frames are wanted in
2188  *
2189  * \retval 0 success
2190  * \retval -1 failure
2191  *
2192  * Example usage:
2193  *
2194  * \code
2195  * struct ast_format tmp_fmt;
2196  * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
2197  * \endcode
2198  *
2199  * This requests that the RTP engine provide audio frames in the ULAW format.
2200  *
2201  * \since 1.8
2202  */
2203 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
2204
2205 /*!
2206  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
2207  *
2208  * \param instance The RTP instance to change write format on
2209  * \param format Format that frames will be provided in
2210  *
2211  * \retval 0 success
2212  * \retval -1 failure
2213  *
2214  * Example usage:
2215  *
2216  * \code
2217  * struct ast_format tmp_fmt;
2218  * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
2219  * \endcode
2220  *
2221  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
2222  *
2223  * \since 1.8
2224  */
2225 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
2226
2227 /*!
2228  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
2229  *
2230  * \param chan Our own Asterisk channel
2231  * \param instance The first RTP instance
2232  * \param peer The peer Asterisk channel
2233  *
2234  * \retval 0 success
2235  * \retval -1 failure
2236  *
2237  * Example usage:
2238  *
2239  * \code
2240  * ast_rtp_instance_make_compatible(instance, peer);
2241  * \endcode
2242  *
2243  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
2244  *
2245  * \since 1.8
2246  */
2247 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
2248
2249 /*! \brief Request the formats that can be transcoded
2250  *
2251  * \param instance The RTP instance
2252  * \param to_endpoint Formats being sent/received towards the endpoint
2253  * \param to_asterisk Formats being sent/received towards Asterisk
2254  * \param result capabilities structure to store and return supported formats in.
2255  *
2256  * Example usage:
2257  *
2258  * \code
2259  * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
2260  * \endcode
2261  *
2262  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
2263  *
2264  * \since 1.8
2265  */
2266 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);
2267
2268 /*!
2269  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
2270  *
2271  * \param instance The RTP instance
2272  *
2273  * \retval 0 success
2274  * \retval -1 failure
2275  *
2276  * Example usage:
2277  *
2278  * \code
2279  * ast_rtp_instance_activate(instance);
2280  * \endcode
2281  *
2282  * This tells the underlying RTP engine of instance that packets will now flow.
2283  *
2284  * \since 1.8
2285  */
2286 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
2287
2288 /*!
2289  * \brief Request that the underlying RTP engine send a STUN BIND request
2290  *
2291  * \param instance The RTP instance
2292  * \param suggestion The suggested destination
2293  * \param username Optionally a username for the request
2294  *
2295  * Example usage:
2296  *
2297  * \code
2298  * ast_rtp_instance_stun_request(instance, NULL, NULL);
2299  * \endcode
2300  *
2301  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
2302  * 'instance'.
2303  *
2304  * \since 1.8
2305  */
2306 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
2307
2308 /*!
2309  * \brief Set the RTP timeout value
2310  *
2311  * \param instance The RTP instance
2312  * \param timeout Value to set the timeout to
2313  *
2314  * Example usage:
2315  *
2316  * \code
2317  * ast_rtp_instance_set_timeout(instance, 5000);
2318  * \endcode
2319  *
2320  * This sets the RTP timeout value on 'instance' to be 5000.
2321  *
2322  * \since 1.8
2323  */
2324 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
2325
2326 /*!
2327  * \brief Set the RTP timeout value for when the instance is on hold
2328  *
2329  * \param instance The RTP instance
2330  * \param timeout Value to set the timeout to
2331  *
2332  * Example usage:
2333  *
2334  * \code
2335  * ast_rtp_instance_set_hold_timeout(instance, 5000);
2336  * \endcode
2337  *
2338  * This sets the RTP hold timeout value on 'instance' to be 5000.
2339  *
2340  * \since 1.8
2341  */
2342 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
2343
2344 /*!
2345  * \brief Set the RTP keepalive interval
2346  *
2347  * \param instance The RTP instance
2348  * \param timeout Value to set the keepalive interval to
2349  *
2350  * Example usage:
2351  *
2352  * \code
2353  * ast_rtp_instance_set_keepalive(instance, 5000);
2354  * \endcode
2355  *
2356  * This sets the RTP keepalive interval on 'instance' to be 5000.
2357  *
2358  * \since 1.8
2359  */
2360 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
2361
2362 /*!
2363  * \brief Get the RTP timeout value
2364  *
2365  * \param instance The RTP instance
2366  *
2367  * \retval timeout value
2368  *
2369  * Example usage:
2370  *
2371  * \code
2372  * int timeout = ast_rtp_instance_get_timeout(instance);
2373  * \endcode
2374  *
2375  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
2376  *
2377  * \since 1.8
2378  */
2379 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
2380
2381 /*!
2382  * \brief Get the RTP timeout value for when an RTP instance is on hold
2383  *
2384  * \param instance The RTP instance
2385  *
2386  * \retval timeout value
2387  *
2388  * Example usage:
2389  *
2390  * \code
2391  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
2392  * \endcode
2393  *
2394  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
2395  *
2396  * \since 1.8
2397  */
2398 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
2399
2400 /*!
2401  * \brief Get the RTP keepalive interval
2402  *
2403  * \param instance The RTP instance
2404  *
2405  * \retval period Keepalive interval value
2406  *
2407  * Example usage:
2408  *
2409  * \code
2410  * int interval = ast_rtp_instance_get_keepalive(instance);
2411  * \endcode
2412  *
2413  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
2414  *
2415  * \since 1.8
2416  */
2417 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
2418
2419 /*!
2420  * \brief Get the RTP engine in use on an RTP instance
2421  *
2422  * \param instance The RTP instance
2423  *
2424  * \retval pointer to the engine
2425  *
2426  * Example usage:
2427  *
2428  * \code
2429  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
2430  * \endcode
2431  *
2432  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
2433  *
2434  * \since 1.8
2435  */
2436 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
2437
2438 /*!
2439  * \brief Get the RTP glue in use on an RTP instance
2440  *
2441  * \param instance The RTP instance
2442  *
2443  * \retval pointer to the glue
2444  *
2445  * Example:
2446  *
2447  * \code
2448  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
2449  * \endcode
2450  *
2451  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
2452  *
2453  * \since 1.8
2454  */
2455 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
2456
2457 /*!
2458  * \brief Send a comfort noise packet to the RTP instance
2459  *
2460  * \param instance The RTP instance
2461  * \param level Magnitude of the noise level
2462  *
2463  * \retval 0 Success
2464  * \retval non-zero Failure
2465  */
2466 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
2467
2468 /*!
2469  * \brief Add or replace the SRTP policies for the given RTP instance
2470  *
2471  * \param instance the RTP instance
2472  * \param remote_policy the remote endpoint's policy
2473  * \param local_policy our policy for this RTP instance's remote endpoint
2474  * \param rtcp 1 for dedicated RTCP policies
2475  *
2476  * \retval 0 Success
2477  * \retval non-zero Failure
2478  *
2479  * \note If no remote policy is provided any existing SRTP policies are left and the new local policy is added
2480  */
2481 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy, int rtcp);
2482
2483 /*!
2484  * \brief Obtain the SRTP instance associated with an RTP instance
2485  *
2486  * \param instance the RTP instance
2487  * \param rtcp 1 to request instance for RTCP
2488  * \retval the SRTP instance on success
2489  * \retval NULL if no SRTP instance exists
2490  */
2491 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance, int rtcp);
2492
2493 /*! \brief Custom formats declared in codecs.conf at startup must be communicated to the rtp_engine
2494  * so their mime type can payload number can be initialized. */
2495 int ast_rtp_engine_load_format(struct ast_format *format);
2496
2497 /*! \brief Formats requiring the use of a format attribute interface must have that
2498  * interface registered in order for the rtp engine to handle it correctly.  If an
2499  * attribute interface is unloaded, this function must be called to notify the rtp_engine. */
2500 int ast_rtp_engine_unload_format(struct ast_format *format);
2501
2502 /*!
2503  * \brief Obtain a pointer to the ICE support present on an RTP instance
2504  *
2505  * \param instance the RTP instance
2506  *
2507  * \retval ICE support if present
2508  * \retval NULL if no ICE support available
2509  */
2510 struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *instance);
2511
2512 /*!
2513  * \brief Obtain a pointer to the DTLS support present on an RTP instance
2514  *
2515  * \param instance the RTP instance
2516  *
2517  * \retval DTLS support if present
2518  * \retval NULL if no DTLS support available
2519  */
2520 struct ast_rtp_engine_dtls *ast_rtp_instance_get_dtls(struct ast_rtp_instance *instance);
2521
2522 /*!
2523  * \brief Parse DTLS related configuration options
2524  *
2525  * \param dtls_cfg a DTLS configuration structure
2526  * \param name name of the configuration option
2527  * \param value value of the configuration option
2528  *
2529  * \retval 0 if handled
2530  * \retval -1 if not handled
2531  */
2532 int ast_rtp_dtls_cfg_parse(struct ast_rtp_dtls_cfg *dtls_cfg, const char *name, const char *value);
2533
2534 /*!
2535  * \brief Validates DTLS related configuration options
2536  *
2537  * \param dtls_cfg a DTLS configuration structure
2538  *
2539  * \retval 0 if valid
2540  * \retval -1 if invalid
2541  */
2542 int ast_rtp_dtls_cfg_validate(struct ast_rtp_dtls_cfg *dtls_cfg);
2543
2544 /*!
2545  * \brief Copy contents of a DTLS configuration structure
2546  *
2547  * \param src_cfg source DTLS configuration structure
2548  * \param dst_cfg destination DTLS configuration structure
2549  */
2550 void ast_rtp_dtls_cfg_copy(const struct ast_rtp_dtls_cfg *src_cfg, struct ast_rtp_dtls_cfg *dst_cfg);
2551
2552 /*!
2553  * \brief Free contents of a DTLS configuration structure
2554  *
2555  * \param dtls_cfg a DTLS configuration structure
2556  */
2557 void ast_rtp_dtls_cfg_free(struct ast_rtp_dtls_cfg *dtls_cfg);
2558
2559 struct ast_json;
2560
2561 /*!
2562  * \brief Allocate an ao2 ref counted instance of \ref ast_rtp_rtcp_report
2563  *
2564  * \param report_blocks The number of report blocks to allocate
2565  * \retval An ao2 ref counted \ref ast_rtp_rtcp_report object on success
2566  * \retval NULL on error
2567  */
2568 struct ast_rtp_rtcp_report *ast_rtp_rtcp_report_alloc(unsigned int report_blocks);
2569
2570 /*!
2571  * \since 12
2572  * \brief Publish an RTCP message to \ref stasis
2573  *
2574  * \param rtp The rtp instance object
2575  * \param message_type The RTP message type to publish
2576  * \param report The RTCP report object to publish. This should be an ao2 ref counted
2577  *  object. This routine will increase the reference count of the object.
2578  * \param blob Additional JSON objects to publish along with the RTCP information
2579  */
2580 void ast_rtp_publish_rtcp_message(struct ast_rtp_instance *rtp,
2581                 struct stasis_message_type *message_type,
2582                 struct ast_rtp_rtcp_report *report,
2583                 struct ast_json *blob);
2584
2585 /*!
2586  * \brief Get the last RTP transmission time
2587  *
2588  * \param rtp The instance from which to get the last transmission time
2589  * \return The last RTP transmission time
2590  */
2591 time_t ast_rtp_instance_get_last_tx(const struct ast_rtp_instance *rtp);
2592
2593 /*!
2594  * \brief Set the last RTP transmission time
2595  *
2596  * \param rtp The instance on which to set the last transmission time
2597  * \param time The last transmission time
2598  */
2599 void ast_rtp_instance_set_last_tx(struct ast_rtp_instance *rtp, time_t time);
2600
2601 /*
2602  * \brief Get the last RTP reception time
2603  *
2604  * \param rtp The instance from which to get the last reception time
2605  * \return The last RTP reception time
2606  */
2607 time_t ast_rtp_instance_get_last_rx(const struct ast_rtp_instance *rtp);
2608
2609 /*!
2610  * \brief Set the last RTP reception time
2611  *
2612  * \param rtp The instance on which to set the last reception time
2613  * \param time The last reception time
2614  */
2615 void ast_rtp_instance_set_last_rx(struct ast_rtp_instance *rtp, time_t time);
2616
2617 /*!
2618  * \brief Retrieve the local SSRC value that we will be using
2619  *
2620  * \param rtp The RTP instance
2621  * \return The SSRC value
2622  */
2623 unsigned int ast_rtp_instance_get_ssrc(struct ast_rtp_instance *rtp);
2624
2625 /*!
2626  * \brief Retrieve the CNAME used in RTCP SDES items
2627  *
2628  * This is a pointer directly into the RTP struct, not a copy.
2629  *
2630  * \param rtp The RTP instance
2631  * \return the CNAME
2632  */
2633 const char *ast_rtp_instance_get_cname(struct ast_rtp_instance *rtp);
2634
2635 /*!
2636  * \brief Request that an RTP instance be bundled with another
2637  * \since 15.0.0
2638  *
2639  * \param child The child RTP instance
2640  * \param parent The parent RTP instance the child should be bundled with
2641  *
2642  * \retval 0 success
2643  * \retval -1 failure
2644  */
2645 int ast_rtp_instance_bundle(struct ast_rtp_instance *child, struct ast_rtp_instance *parent);
2646
2647 /*!
2648  * \brief Set the remote SSRC for an RTP instance
2649  * \since 15.0.0
2650  *
2651  * \param rtp The RTP instance
2652  * \param ssrc The remote SSRC
2653  */
2654 void ast_rtp_instance_set_remote_ssrc(struct ast_rtp_instance *rtp, unsigned int ssrc);
2655
2656 /*!
2657  * \brief Set the stream number for an RTP instance
2658  * \since 15.0.0
2659  *
2660  * \param rtp The RTP instance
2661  * \param stream_num The stream identifier number
2662  */
2663 void ast_rtp_instance_set_stream_num(struct ast_rtp_instance *instance, int stream_num);
2664
2665 /*! \addtogroup StasisTopicsAndMessages
2666  * @{
2667  */
2668
2669 /*!
2670  * \since 12
2671  * \brief Message type for an RTCP message sent from this Asterisk instance
2672  *
2673  * \retval A stasis message type
2674  */
2675 struct stasis_message_type *ast_rtp_rtcp_sent_type(void);
2676
2677 /*!
2678  * \since 12
2679  * \brief Message type for an RTCP message received from some external source
2680  *
2681  * \retval A stasis message type
2682  */
2683 struct stasis_message_type *ast_rtp_rtcp_received_type(void);
2684
2685 /*!
2686  * \since 12
2687  * \brief \ref stasis topic for RTP and RTCP related messages
2688  *
2689  * \retval A \ref stasis topic
2690  */
2691 struct stasis_topic *ast_rtp_topic(void);
2692
2693 /* @} */
2694
2695 #if defined(__cplusplus) || defined(c_plusplus)
2696 }
2697 #endif
2698
2699 #endif /* _ASTERISK_RTP_ENGINE_H */