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