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