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