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