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