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