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