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