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