Fix a crash occurring as a result of excess stack usage.
[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
240 };
241
242 /*! Structure that represents statistics from an RTP instance */
243 struct ast_rtp_instance_stats {
244         /*! Number of packets transmitted */
245         unsigned int txcount;
246         /*! Number of packets received */
247         unsigned int rxcount;
248         /*! Jitter on transmitted packets */
249         double txjitter;
250         /*! Jitter on received packets */
251         double rxjitter;
252         /*! Maximum jitter on remote side */
253         double remote_maxjitter;
254         /*! Minimum jitter on remote side */
255         double remote_minjitter;
256         /*! Average jitter on remote side */
257         double remote_normdevjitter;
258         /*! Standard deviation jitter on remote side */
259         double remote_stdevjitter;
260         /*! Maximum jitter on local side */
261         double local_maxjitter;
262         /*! Minimum jitter on local side */
263         double local_minjitter;
264         /*! Average jitter on local side */
265         double local_normdevjitter;
266         /*! Standard deviation jitter on local side */
267         double local_stdevjitter;
268         /*! Number of transmitted packets lost */
269         unsigned int txploss;
270         /*! Number of received packets lost */
271         unsigned int rxploss;
272         /*! Maximum number of packets lost on remote side */
273         double remote_maxrxploss;
274         /*! Minimum number of packets lost on remote side */
275         double remote_minrxploss;
276         /*! Average number of packets lost on remote side */
277         double remote_normdevrxploss;
278         /*! Standard deviation packets lost on remote side */
279         double remote_stdevrxploss;
280         /*! Maximum number of packets lost on local side */
281         double local_maxrxploss;
282         /*! Minimum number of packets lost on local side */
283         double local_minrxploss;
284         /*! Average number of packets lost on local side */
285         double local_normdevrxploss;
286         /*! Standard deviation packets lost on local side */
287         double local_stdevrxploss;
288         /*! Total round trip time */
289         double rtt;
290         /*! Maximum round trip time */
291         double maxrtt;
292         /*! Minimum round trip time */
293         double minrtt;
294         /*! Average round trip time */
295         double normdevrtt;
296         /*! Standard deviation round trip time */
297         double stdevrtt;
298         /*! Our SSRC */
299         unsigned int local_ssrc;
300         /*! Their SSRC */
301         unsigned int remote_ssrc;
302 };
303
304 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
305 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
306 placement = value; \
307 if (stat == current_stat) { \
308 return 0; \
309 } \
310 }
311
312 #define AST_RTP_STAT_TERMINATOR(combined) \
313 if (stat == combined) { \
314 return 0; \
315 }
316
317 /*! \brief ICE candidate types */
318 enum ast_rtp_ice_candidate_type {
319         AST_RTP_ICE_CANDIDATE_TYPE_HOST,    /*!< ICE host candidate. A host candidate represents the actual local transport address in the host. */
320         AST_RTP_ICE_CANDIDATE_TYPE_SRFLX,   /*!< ICE server reflexive candidate, which represents the public mapped address of the local address. */
321         AST_RTP_ICE_CANDIDATE_TYPE_RELAYED, /*!< ICE relayed candidate, which represents the address allocated in TURN server. */
322 };
323
324 /*! \brief Structure for an ICE candidate */
325 struct ast_rtp_engine_ice_candidate {
326         char *foundation;                     /*!< Foundation identifier */
327         unsigned int id;                      /*!< Component identifier */
328         char *transport;                      /*!< Transport for the media */
329         int priority;                         /*!< Priority which is used if multiple candidates can be used */
330         struct ast_sockaddr address;          /*!< Address of the candidate */
331         struct ast_sockaddr relay_address;    /*!< Relay address for the candidate */
332         enum ast_rtp_ice_candidate_type type; /*!< Type of candidate */
333 };
334
335 /*! \brief Structure that represents the optional ICE support within an RTP engine */
336 struct ast_rtp_engine_ice {
337         /*! Callback for setting received authentication information */
338         void (*set_authentication)(struct ast_rtp_instance *instance, const char *ufrag, const char *password);
339         /*! Callback for adding a remote candidate */
340         void (*add_remote_candidate)(struct ast_rtp_instance *instance, const struct ast_rtp_engine_ice_candidate *candidate);
341         /*! Callback for starting ICE negotiation */
342         void (*start)(struct ast_rtp_instance *instance);
343         /*! Callback for stopping ICE support */
344         void (*stop)(struct ast_rtp_instance *instance);
345         /*! Callback for getting local username */
346         const char *(*get_ufrag)(struct ast_rtp_instance *instance);
347         /*! Callback for getting local password */
348         const char *(*get_password)(struct ast_rtp_instance *instance);
349         /*! Callback for getting local candidates */
350         struct ao2_container *(*get_local_candidates)(struct ast_rtp_instance *instance);
351         /*! Callback for telling the ICE support that it is talking to an ice-lite implementation */
352         void (*ice_lite)(struct ast_rtp_instance *instance);
353 };
354
355 /*! Structure that represents an RTP stack (engine) */
356 struct ast_rtp_engine {
357         /*! Name of the RTP engine, used when explicitly requested */
358         const char *name;
359         /*! Module this RTP engine came from, used for reference counting */
360         struct ast_module *mod;
361         /*! Callback for setting up a new RTP instance */
362         int (*new)(struct ast_rtp_instance *instance, struct ast_sched_context *sched, struct ast_sockaddr *sa, void *data);
363         /*! Callback for destroying an RTP instance */
364         int (*destroy)(struct ast_rtp_instance *instance);
365         /*! Callback for writing out a frame */
366         int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
367         /*! Callback for stopping the RTP instance */
368         void (*stop)(struct ast_rtp_instance *instance);
369         /*! Callback for starting RFC2833 DTMF transmission */
370         int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
371         /*! Callback for stopping RFC2833 DTMF transmission */
372         int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
373         int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
374         /*! Callback to indicate that we should update the marker bit */
375         void (*update_source)(struct ast_rtp_instance *instance);
376         /*! Callback to indicate that we should update the marker bit and ssrc */
377         void (*change_source)(struct ast_rtp_instance *instance);
378         /*! Callback for setting an extended RTP property */
379         int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
380         /*! Callback for getting an extended RTP property */
381         void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
382         /*! Callback for setting an RTP property */
383         void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
384         /*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
385         void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
386         /*! Callback for setting packetization preferences */
387         void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
388         /*! Callback for setting the remote address that RTP is to be sent to */
389         void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
390         /*! Callback for setting an alternate remote address */
391         void (*alt_remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
392         /*! Callback for changing DTMF mode */
393         int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
394         /*! Callback for getting DTMF mode */
395         enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
396         /*! Callback for retrieving statistics */
397         int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
398         /*! Callback for setting QoS values */
399         int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
400         /*! Callback for retrieving a file descriptor to poll on, not always required */
401         int (*fd)(struct ast_rtp_instance *instance, int rtcp);
402         /*! Callback for initializing RED support */
403         int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
404         /*! Callback for buffering a frame using RED */
405         int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
406         /*! Callback for reading a frame from the RTP engine */
407         struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
408         /*! Callback to locally bridge two RTP instances */
409         int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
410         /*! Callback to set the read format */
411         int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
412         /*! Callback to set the write format */
413         int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
414         /*! Callback to make two instances compatible */
415         int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
416         /*! Callback to see if two instances are compatible with DTMF */
417         int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
418         /*! Callback to indicate that packets will now flow */
419         int (*activate)(struct ast_rtp_instance *instance);
420         /*! Callback to request that the RTP engine send a STUN BIND request */
421         void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
422         /*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
423         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);
424         /*! Callback to send CNG */
425         int (*sendcng)(struct ast_rtp_instance *instance, int level);
426         /*! Callback to pointer for optional ICE support */
427         struct ast_rtp_engine_ice *ice;
428         /*! Linked list information */
429         AST_RWLIST_ENTRY(ast_rtp_engine) entry;
430 };
431
432 /*! Structure that represents codec and packetization information */
433 struct ast_rtp_codecs {
434         /*! Codec packetization preferences */
435         struct ast_codec_pref pref;
436         /*! Payloads present */
437         struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT];
438 };
439
440 /*! Structure that represents the glue that binds an RTP instance to a channel */
441 struct ast_rtp_glue {
442         /*! Name of the channel driver that this glue is responsible for */
443         const char *type;
444         /*! Module that the RTP glue came from */
445         struct ast_module *mod;
446         /*!
447          * \brief Callback for retrieving the RTP instance carrying audio
448          * \note This function increases the reference count on the returned RTP instance.
449          */
450         enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
451         /*!
452          * \brief Used to prevent two channels from remotely bridging audio rtp if the channel tech has a
453          *        reason for prohibiting it based on qualities that need to be compared from both channels.
454          * \note This function should only be called with two channels of the same technology
455          * \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.
456          */
457         int (*allow_rtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
458         /*!
459          * \brief Callback for retrieving the RTP instance carrying video
460          * \note This function increases the reference count on the returned RTP instance.
461          */
462         enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
463         /*!
464          * \brief Used to prevent two channels from remotely bridging video rtp if the channel tech has a
465          *        reason for prohibiting it based on qualities that need to be compared from both channels.
466          * \note This function should only be called with two channels of the same technology
467          * \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.
468          */
469         int (*allow_vrtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
470
471         /*!
472          * \brief Callback for retrieving the RTP instance carrying text
473          * \note This function increases the reference count on the returned RTP instance.
474          */
475         enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
476         /*! Callback for updating the destination that the remote side should send RTP to */
477         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);
478         /*! Callback for retrieving codecs that the channel can do.  Result returned in result_cap*/
479         void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
480         /*! Linked list information */
481         AST_RWLIST_ENTRY(ast_rtp_glue) entry;
482 };
483
484 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
485
486 /*!
487  * \brief Register an RTP engine
488  *
489  * \param engine Structure of the RTP engine to register
490  * \param module Module that the RTP engine is part of
491  *
492  * \retval 0 success
493  * \retval -1 failure
494  *
495  * Example usage:
496  *
497  * \code
498  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
499  * \endcode
500  *
501  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
502  * associate a module with it.
503  *
504  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
505  *       associated with the RTP engine and use counting is performed.
506  *
507  * \since 1.8
508  */
509 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
510
511 /*!
512  * \brief Unregister an RTP engine
513  *
514  * \param engine Structure of the RTP engine to unregister
515  *
516  * \retval 0 success
517  * \retval -1 failure
518  *
519  * Example usage:
520  *
521  * \code
522  * ast_rtp_engine_unregister(&example_rtp_engine);
523  * \endcode
524  *
525  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
526  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
527  *
528  * \since 1.8
529  */
530 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
531
532 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
533
534 void ast_rtp_engine_unregister_srtp(void);
535 int ast_rtp_engine_srtp_is_registered(void);
536
537 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
538
539 /*!
540  * \brief Register RTP glue
541  *
542  * \param glue The glue to register
543  * \param module Module that the RTP glue is part of
544  *
545  * \retval 0 success
546  * \retval -1 failure
547  *
548  * Example usage:
549  *
550  * \code
551  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
552  * \endcode
553  *
554  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
555  * associate a module with it.
556  *
557  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
558  *       associated with the RTP glue and use counting is performed.
559  *
560  * \since 1.8
561  */
562 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
563
564 /*!
565  * \brief Unregister RTP glue
566  *
567  * \param glue The glue to unregister
568  *
569  * \retval 0 success
570  * \retval -1 failure
571  *
572  * Example usage:
573  *
574  * \code
575  * ast_rtp_glue_unregister(&example_rtp_glue);
576  * \endcode
577  *
578  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
579  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
580  *
581  * \since 1.8
582  */
583 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
584
585 /*!
586  * \brief Create a new RTP instance
587  *
588  * \param engine_name Name of the engine to use for the RTP instance
589  * \param sched Scheduler context that the RTP engine may want to use
590  * \param sa Address we want to bind to
591  * \param data Unique data for the engine
592  *
593  * \retval non-NULL success
594  * \retval NULL failure
595  *
596  * Example usage:
597  *
598  * \code
599  * struct ast_rtp_instance *instance = NULL;
600  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
601  * \endcode
602  *
603  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
604  * in the address structure.
605  *
606  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
607  *       another depending on it's own configuration.
608  *
609  * \since 1.8
610  */
611 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
612                 struct ast_sched_context *sched, const struct ast_sockaddr *sa,
613                 void *data);
614
615 /*!
616  * \brief Destroy an RTP instance
617  *
618  * \param instance The RTP instance to destroy
619  *
620  * \retval 0 success
621  * \retval -1 failure
622  *
623  * Example usage:
624  *
625  * \code
626  * ast_rtp_instance_destroy(instance);
627  * \endcode
628  *
629  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
630  * memory and may not be used again.
631  *
632  * \since 1.8
633  */
634 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
635
636 /*!
637  * \brief Set the data portion of an RTP instance
638  *
639  * \param instance The RTP instance to manipulate
640  * \param data Pointer to data
641  *
642  * Example usage:
643  *
644  * \code
645  * ast_rtp_instance_set_data(instance, blob);
646  * \endcode
647  *
648  * This sets the data pointer on the RTP instance pointed to by 'instance' to
649  * blob.
650  *
651  * \since 1.8
652  */
653 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
654
655 /*!
656  * \brief Get the data portion of an RTP instance
657  *
658  * \param instance The RTP instance we want the data portion from
659  *
660  * Example usage:
661  *
662  * \code
663  * struct *blob = ast_rtp_instance_get_data(instance);
664  ( \endcode
665  *
666  * This gets the data pointer on the RTP instance pointed to by 'instance'.
667  *
668  * \since 1.8
669  */
670 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
671
672 /*!
673  * \brief Send a frame out over RTP
674  *
675  * \param instance The RTP instance to send frame out on
676  * \param frame the frame to send out
677  *
678  * \retval 0 success
679  * \retval -1 failure
680  *
681  * Example usage:
682  *
683  * \code
684  * ast_rtp_instance_write(instance, frame);
685  * \endcode
686  *
687  * This gives the frame pointed to by frame to the RTP engine being used for the instance
688  * and asks that it be transmitted to the current remote address set on the RTP instance.
689  *
690  * \since 1.8
691  */
692 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
693
694 /*!
695  * \brief Receive a frame over RTP
696  *
697  * \param instance The RTP instance to receive frame on
698  * \param rtcp Whether to read in RTCP or not
699  *
700  * \retval non-NULL success
701  * \retval NULL failure
702  *
703  * Example usage:
704  *
705  * \code
706  * struct ast_frame *frame;
707  * frame = ast_rtp_instance_read(instance, 0);
708  * \endcode
709  *
710  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
711  *
712  * \since 1.8
713  */
714 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
715
716 /*!
717  * \brief Set the address of the remote endpoint that we are sending RTP to
718  *
719  * \param instance The RTP instance to change the address on
720  * \param address Address to set it to
721  *
722  * \retval 0 success
723  * \retval -1 failure
724  *
725  * Example usage:
726  *
727  * \code
728  * ast_rtp_instance_set_remote_address(instance, &sin);
729  * \endcode
730  *
731  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
732  * structure.
733  *
734  * \since 1.8
735  */
736 int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
737
738
739 /*!
740  * \brief Set the address of an an alternate RTP address to receive from
741  *
742  * \param instance The RTP instance to change the address on
743  * \param address Address to set it to
744  *
745  * \retval 0 success
746  * \retval -1 failure
747  *
748  * Example usage:
749  *
750  * \code
751  * ast_rtp_instance_set_alt_remote_address(instance, &address);
752  * \endcode
753  *
754  * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin
755  * structure.
756  *
757  * \since 1.8
758  */
759 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
760
761 /*!
762  * \brief Set the address that we are expecting to receive RTP on
763  *
764  * \param instance The RTP instance to change the address on
765  * \param address Address to set it to
766  *
767  * \retval 0 success
768  * \retval -1 failure
769  *
770  * Example usage:
771  *
772  * \code
773  * ast_rtp_instance_set_local_address(instance, &sin);
774  * \endcode
775  *
776  * This changes the local address that RTP is expected on to the address given in the sin
777  * structure.
778  *
779  * \since 1.8
780  */
781 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
782                 const struct ast_sockaddr *address);
783
784 /*!
785  * \brief Get the local address that we are expecting RTP on
786  *
787  * \param instance The RTP instance to get the address from
788  * \param address The variable to store the address in
789  *
790  * Example usage:
791  *
792  * \code
793  * struct ast_sockaddr address;
794  * ast_rtp_instance_get_local_address(instance, &address);
795  * \endcode
796  *
797  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
798  *
799  * \since 1.8
800  */
801 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
802
803 /*!
804  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
805  *
806  * \param instance The instance that we want to get the local address for
807  * \param address An initialized address that may be overwritten if the local address is different
808  *
809  * \retval 0 address was not changed
810  * \retval 1 address was changed
811  * Example usage:
812  *
813  * \code
814  * struct ast_sockaddr address;
815  * int ret;
816  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
817  * \endcode
818  *
819  * This retrieves the current local address set on the instance pointed to by instance and puts the value
820  * into the address structure.
821  *
822  * \since 1.8
823  */
824 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
825
826 /*!
827  * \brief Get the address of the remote endpoint that we are sending RTP to
828  *
829  * \param instance The instance that we want to get the remote address for
830  * \param address A structure to put the address into
831  *
832  * Example usage:
833  *
834  * \code
835  * struct ast_sockaddr address;
836  * ast_rtp_instance_get_remote_address(instance, &address);
837  * \endcode
838  *
839  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
840  * into the address structure.
841  *
842  * \since 1.8
843  */
844 void ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
845
846 /*!
847  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
848  *
849  * \param instance The instance that we want to get the remote address for
850  * \param address An initialized address that may be overwritten if the remote address is different
851  *
852  * \retval 0 address was not changed
853  * \retval 1 address was changed
854  * Example usage:
855  *
856  * \code
857  * struct ast_sockaddr address;
858  * int ret;
859  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
860  * \endcode
861  *
862  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
863  * into the address structure.
864  *
865  * \since 1.8
866  */
867
868 int ast_rtp_instance_get_and_cmp_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
869
870 /*!
871  * \brief Set the value of an RTP instance extended property
872  *
873  * \param instance The RTP instance to set the extended property on
874  * \param property The extended property to set
875  * \param value The value to set the extended property to
876  *
877  * \since 1.8
878  */
879 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
880
881 /*!
882  * \brief Get the value of an RTP instance extended property
883  *
884  * \param instance The RTP instance to get the extended property on
885  * \param property The extended property to get
886  *
887  * \since 1.8
888  */
889 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
890
891 /*!
892  * \brief Set the value of an RTP instance property
893  *
894  * \param instance The RTP instance to set the property on
895  * \param property The property to modify
896  * \param value The value to set the property to
897  *
898  * Example usage:
899  *
900  * \code
901  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
902  * \endcode
903  *
904  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
905  *
906  * \since 1.8
907  */
908 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
909
910 /*!
911  * \brief Get the value of an RTP instance property
912  *
913  * \param instance The RTP instance to get the property from
914  * \param property The property to get
915  *
916  * \retval Current value of the property
917  *
918  * Example usage:
919  *
920  * \code
921  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
922  * \endcode
923  *
924  * This returns the current value of the NAT property on the instance pointed to by instance.
925  *
926  * \since 1.8
927  */
928 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
929
930 /*!
931  * \brief Get the codecs structure of an RTP instance
932  *
933  * \param instance The RTP instance to get the codecs structure from
934  *
935  * Example usage:
936  *
937  * \code
938  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
939  * \endcode
940  *
941  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
942  *
943  * \since 1.8
944  */
945 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
946
947 /*!
948  * \brief Clear payload information from an RTP instance
949  *
950  * \param codecs The codecs structure that payloads will be cleared from
951  * \param instance Optionally the instance that the codecs structure belongs to
952  *
953  * Example usage:
954  *
955  * \code
956  * struct ast_rtp_codecs codecs;
957  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
958  * \endcode
959  *
960  * This clears the codecs structure and puts it into a pristine state.
961  *
962  * \since 1.8
963  */
964 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
965
966 /*!
967  * \brief Set payload information on an RTP instance to the default
968  *
969  * \param codecs The codecs structure to set defaults on
970  * \param instance Optionally the instance that the codecs structure belongs to
971  *
972  * Example usage:
973  *
974  * \code
975  * struct ast_rtp_codecs codecs;
976  * ast_rtp_codecs_payloads_default(&codecs, NULL);
977  * \endcode
978  *
979  * This sets the default payloads on the codecs structure.
980  *
981  * \since 1.8
982  */
983 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
984
985 /*!
986  * \brief Copy payload information from one RTP instance to another
987  *
988  * \param src The source codecs structure
989  * \param dest The destination codecs structure that the values from src will be copied to
990  * \param instance Optionally the instance that the dst codecs structure belongs to
991  *
992  * Example usage:
993  *
994  * \code
995  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
996  * \endcode
997  *
998  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
999  *
1000  * \since 1.8
1001  */
1002 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
1003
1004 /*!
1005  * \brief Record payload information that was seen in an m= SDP line
1006  *
1007  * \param codecs The codecs structure to muck with
1008  * \param instance Optionally the instance that the codecs structure belongs to
1009  * \param payload Numerical payload that was seen in the m= SDP line
1010  *
1011  * Example usage:
1012  *
1013  * \code
1014  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
1015  * \endcode
1016  *
1017  * This records that the numerical payload '0' was seen in the codecs structure.
1018  *
1019  * \since 1.8
1020  */
1021 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1022
1023 /*!
1024  * \brief Record payload information that was seen in an a=rtpmap: SDP line
1025  *
1026  * \param codecs The codecs structure to muck with
1027  * \param instance Optionally the instance that the codecs structure belongs to
1028  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
1029  * \param mimetype The string mime type that was seen
1030  * \param mimesubtype The strin mime sub type that was seen
1031  * \param options Optional options that may change the behavior of this specific payload
1032  *
1033  * \retval 0 success
1034  * \retval -1 failure, invalid payload numbe
1035  * \retval -2 failure, unknown mimetype
1036  *
1037  * Example usage:
1038  *
1039  * \code
1040  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
1041  * \endcode
1042  *
1043  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
1044  *
1045  * \since 1.8
1046  */
1047 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);
1048
1049 /*!
1050  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
1051  *
1052  * \param codecs RTP structure to modify
1053  * \param instance Optionally the instance that the codecs structure belongs to
1054  * \param pt Payload type entry to modify
1055  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
1056  * \param mimesubtype MIME subtype of media stream (typically a codec name)
1057  * \param options Zero or more flags from the ast_rtp_options enum
1058  * \param sample_rate The sample rate of the media stream
1059  *
1060  * This function 'fills in' an entry in the list of possible formats for
1061  * a media stream associated with an RTP structure.
1062  *
1063  * \retval 0 on success
1064  * \retval -1 if the payload type is out of range
1065  * \retval -2 if the mimeType/mimeSubtype combination was not found
1066  *
1067  * \since 1.8
1068  */
1069 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
1070                                   char *mimetype, char *mimesubtype,
1071                                   enum ast_rtp_options options,
1072                                   unsigned int sample_rate);
1073
1074 /*!
1075  * \brief Remove payload information
1076  *
1077  * \param codecs The codecs structure to muck with
1078  * \param instance Optionally the instance that the codecs structure belongs to
1079  * \param payload Numerical payload to unset
1080  *
1081  * Example usage:
1082  *
1083  * \code
1084  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
1085  * \endcode
1086  *
1087  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
1088  *
1089  * \since 1.8
1090  */
1091 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1092
1093 /*!
1094  * \brief Retrieve payload information by payload
1095  *
1096  * \param codecs Codecs structure to look in
1097  * \param payload Numerical payload to look up
1098  *
1099  * \retval Payload information
1100  *
1101  * Example usage:
1102  *
1103  * \code
1104  * struct ast_rtp_payload_type payload_type;
1105  * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
1106  * \endcode
1107  *
1108  * This looks up the information for payload '0' from the codecs structure.
1109  *
1110  * \since 1.8
1111  */
1112 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
1113
1114 /*!
1115  * \brief Retrieve the actual ast_format stored on the codecs structure for a specific payload
1116  *
1117  * \param codecs Codecs structure to look in
1118  * \param payload Numerical payload to look up
1119  *
1120  * \retval pointer to format structure on success
1121  * \retval NULL on failure
1122  *
1123  * \since 10.0
1124  */
1125 struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *codecs, int payload);
1126
1127 /*!
1128  * \brief Get the sample rate associated with known RTP payload types
1129  *
1130  * \param asterisk_format True if the value in format is to be used.
1131  * \param An asterisk format
1132  * \param code from AST_RTP list
1133  *
1134  * \return the sample rate if the format was found, zero if it was not found
1135  *
1136  * \since 1.8
1137  */
1138 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, struct ast_format *format, int code);
1139
1140 /*!
1141  * \brief Retrieve all formats that were found
1142  *
1143  * \param codecs Codecs structure to look in
1144  * \param astformats A capabilities structure to put the Asterisk formats in.
1145  * \param nonastformats An integer to put the non-Asterisk formats in
1146  *
1147  * Example usage:
1148  *
1149  * \code
1150  * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
1151  * int nonastformats;
1152  * ast_rtp_codecs_payload_formats(&codecs, &astformats, &nonastformats);
1153  * \endcode
1154  *
1155  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
1156  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
1157  *
1158  * \since 1.8
1159  */
1160 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
1161
1162 /*!
1163  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
1164  *
1165  * \param codecs Codecs structure to look in
1166  * \param asterisk_format Non-zero if the given Asterisk format is present
1167  * \param format Asterisk format to look for
1168  * \param code The format to look for
1169  *
1170  * \retval Numerical payload
1171  *
1172  * Example usage:
1173  *
1174  * \code
1175  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
1176  * \endcode
1177  *
1178  * This looks for the numerical payload for ULAW in the codecs structure.
1179  *
1180  * \since 1.8
1181  */
1182 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
1183
1184 /*!
1185  * \brief Retrieve mime subtype information on a payload
1186  *
1187  * \param asterisk_format Non-zero to look up using Asterisk format
1188  * \param format Asterisk format to look up
1189  * \param code RTP code to look up
1190  * \param options Additional options that may change the result
1191  *
1192  * \retval Mime subtype success
1193  * \retval NULL failure
1194  *
1195  * Example usage:
1196  *
1197  * \code
1198  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
1199  * \endcode
1200  *
1201  * This looks up the mime subtype for the ULAW format.
1202  *
1203  * \since 1.8
1204  */
1205 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, struct ast_format *format, int code, enum ast_rtp_options options);
1206
1207 /*!
1208  * \brief Convert formats into a string and put them into a buffer
1209  *
1210  * \param buf Buffer to put the mime output into
1211  * \param ast_format_capability Asterisk Formats we are looking up.
1212  * \param rtp_capability RTP codes that we are looking up
1213  * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
1214  * \param options Additional options that may change the result
1215  *
1216  * \retval non-NULL success
1217  * \retval NULL failure
1218  *
1219  * Example usage:
1220  *
1221  * \code
1222  * char buf[256] = "";
1223  * struct ast_format tmp_fmt;
1224  * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
1225  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1226  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
1227  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
1228  * ast_format_cap_destroy(cap);
1229  * \endcode
1230  *
1231  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
1232  *
1233  * \since 1.8
1234  */
1235 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);
1236
1237 /*!
1238  * \brief Set codec packetization preferences
1239  *
1240  * \param codecs Codecs structure to muck with
1241  * \param instance Optionally the instance that the codecs structure belongs to
1242  * \param prefs Codec packetization preferences
1243  *
1244  * Example usage:
1245  *
1246  * \code
1247  * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
1248  * \endcode
1249  *
1250  * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
1251  *
1252  * \since 1.8
1253  */
1254 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
1255
1256 /*!
1257  * \brief Begin sending a DTMF digit
1258  *
1259  * \param instance The RTP instance to send the DTMF on
1260  * \param digit What DTMF digit to send
1261  *
1262  * \retval 0 success
1263  * \retval -1 failure
1264  *
1265  * Example usage:
1266  *
1267  * \code
1268  * ast_rtp_instance_dtmf_begin(instance, '1');
1269  * \endcode
1270  *
1271  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
1272  * continue being sent until it is ended.
1273  *
1274  * \since 1.8
1275  */
1276 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
1277
1278 /*!
1279  * \brief Stop sending a DTMF digit
1280  *
1281  * \param instance The RTP instance to stop the DTMF on
1282  * \param digit What DTMF digit to stop
1283  *
1284  * \retval 0 success
1285  * \retval -1 failure
1286  *
1287  * Example usage:
1288  *
1289  * \code
1290  * ast_rtp_instance_dtmf_end(instance, '1');
1291  * \endcode
1292  *
1293  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
1294  *
1295  * \since 1.8
1296  */
1297 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
1298 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
1299
1300 /*!
1301  * \brief Set the DTMF mode that should be used
1302  *
1303  * \param instance the RTP instance to set DTMF mode on
1304  * \param dtmf_mode The DTMF mode that is in use
1305  *
1306  * \retval 0 success
1307  * \retval -1 failure
1308  *
1309  * Example usage:
1310  *
1311  * \code
1312  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
1313  * \endcode
1314  *
1315  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
1316  *
1317  * \since 1.8
1318  */
1319 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
1320
1321 /*!
1322  * \brief Get the DTMF mode of an RTP instance
1323  *
1324  * \param instance The RTP instance to get the DTMF mode of
1325  *
1326  * \retval DTMF mode
1327  *
1328  * Example usage:
1329  *
1330  * \code
1331  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
1332  * \endcode
1333  *
1334  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
1335  *
1336  * \since 1.8
1337  */
1338 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
1339
1340 /*!
1341  * \brief Indicate that the RTP marker bit should be set on an RTP stream
1342  *
1343  * \param instance Instance that the new media source is feeding into
1344  *
1345  * Example usage:
1346  *
1347  * \code
1348  * ast_rtp_instance_update_source(instance);
1349  * \endcode
1350  *
1351  * This indicates that the source of media that is feeding the instance pointed to by
1352  * instance has been updated and that the marker bit should be set.
1353  *
1354  * \since 1.8
1355  */
1356 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
1357
1358 /*!
1359  * \brief Indicate a new source of audio has dropped in and the ssrc should change
1360  *
1361  * \param instance Instance that the new media source is feeding into
1362  *
1363  * Example usage:
1364  *
1365  * \code
1366  * ast_rtp_instance_change_source(instance);
1367  * \endcode
1368  *
1369  * This indicates that the source of media that is feeding the instance pointed to by
1370  * instance has changed and that the marker bit should be set and the SSRC updated.
1371  *
1372  * \since 1.8
1373  */
1374 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
1375
1376 /*!
1377  * \brief Set QoS parameters on an RTP session
1378  *
1379  * \param instance Instance to set the QoS parameters on
1380  * \param tos Terms of service value
1381  * \param cos Class of service value
1382  * \param desc What is setting the QoS values
1383  *
1384  * \retval 0 success
1385  * \retval -1 failure
1386  *
1387  * Example usage:
1388  *
1389  * \code
1390  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
1391  * \endcode
1392  *
1393  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
1394  *
1395  * \since 1.8
1396  */
1397 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
1398
1399 /*!
1400  * \brief Stop an RTP instance
1401  *
1402  * \param instance Instance that media is no longer going to at this time
1403  *
1404  * Example usage:
1405  *
1406  * \code
1407  * ast_rtp_instance_stop(instance);
1408  * \endcode
1409  *
1410  * This tells the RTP engine being used for the instance pointed to by instance
1411  * that media is no longer going to it at this time, but may in the future.
1412  *
1413  * \since 1.8
1414  */
1415 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
1416
1417 /*!
1418  * \brief Get the file descriptor for an RTP session (or RTCP)
1419  *
1420  * \param instance Instance to get the file descriptor for
1421  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
1422  *
1423  * \retval fd success
1424  * \retval -1 failure
1425  *
1426  * Example usage:
1427  *
1428  * \code
1429  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
1430  * \endcode
1431  *
1432  * This retrieves the file descriptor for the socket carrying media on the instance
1433  * pointed to by instance.
1434  *
1435  * \since 1.8
1436  */
1437 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
1438
1439 /*!
1440  * \brief Get the RTP glue that binds a channel to the RTP engine
1441  *
1442  * \param type Name of the glue we want
1443  *
1444  * \retval non-NULL success
1445  * \retval NULL failure
1446  *
1447  * Example usage:
1448  *
1449  * \code
1450  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
1451  * \endcode
1452  *
1453  * This retrieves the RTP glue that has the name 'Example'.
1454  *
1455  * \since 1.8
1456  */
1457 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
1458
1459 /*!
1460  * \brief Bridge two channels that use RTP instances
1461  *
1462  * \param c0 First channel part of the bridge
1463  * \param c1 Second channel part of the bridge
1464  * \param flags Bridging flags
1465  * \param fo If a frame needs to be passed up it is stored here
1466  * \param rc Channel that passed the above frame up
1467  * \param timeoutms How long the channels should be bridged for
1468  *
1469  * \retval Bridge result
1470  *
1471  * \note This should only be used by channel drivers in their technology declaration.
1472  *
1473  * \since 1.8
1474  */
1475 enum ast_bridge_result ast_rtp_instance_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
1476
1477 /*!
1478  * \brief Get the other RTP instance that an instance is bridged to
1479  *
1480  * \param instance The RTP instance that we want
1481  *
1482  * \retval non-NULL success
1483  * \retval NULL failure
1484  *
1485  * Example usage:
1486  *
1487  * \code
1488  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
1489  * \endcode
1490  *
1491  * This gets the RTP instance that instance0 is bridged to.
1492  *
1493  * \since 1.8
1494  */
1495 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
1496
1497 /*!
1498  * \brief Make two channels compatible for early bridging
1499  *
1500  * \param c0 First channel part of the bridge
1501  * \param c1 Second channel part of the bridge
1502  *
1503  * \since 1.8
1504  */
1505 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1506
1507 /*!
1508  * \brief Early bridge two channels that use RTP instances
1509  *
1510  * \param c0 First channel part of the bridge
1511  * \param c1 Second channel part of the bridge
1512  *
1513  * \retval 0 success
1514  * \retval -1 failure
1515  *
1516  * \note This should only be used by channel drivers in their technology declaration.
1517  *
1518  * \since 1.8
1519  */
1520 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1521
1522 /*!
1523  * \brief Initialize RED support on an RTP instance
1524  *
1525  * \param instance The instance to initialize RED support on
1526  * \param buffer_time How long to buffer before sending
1527  * \param payloads Payload values
1528  * \param generations Number of generations
1529  *
1530  * \retval 0 success
1531  * \retval -1 failure
1532  *
1533  * \since 1.8
1534  */
1535 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
1536
1537 /*!
1538  * \brief Buffer a frame in an RTP instance for RED
1539  *
1540  * \param instance The instance to buffer the frame on
1541  * \param frame Frame that we want to buffer
1542  *
1543  * \retval 0 success
1544  * \retval -1 failure
1545  *
1546  * \since 1.8
1547  */
1548 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
1549
1550 /*!
1551  * \brief Retrieve statistics about an RTP instance
1552  *
1553  * \param instance Instance to get statistics on
1554  * \param stats Structure to put results into
1555  * \param stat What statistic(s) to retrieve
1556  *
1557  * \retval 0 success
1558  * \retval -1 failure
1559  *
1560  * Example usage:
1561  *
1562  * \code
1563  * struct ast_rtp_instance_stats stats;
1564  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
1565  * \endcode
1566  *
1567  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
1568  * stats structure.
1569  *
1570  * \since 1.8
1571  */
1572 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
1573
1574 /*!
1575  * \brief Set standard statistics from an RTP instance on a channel
1576  *
1577  * \param chan Channel to set the statistics on
1578  * \param instance The RTP instance that statistics will be retrieved from
1579  *
1580  * Example usage:
1581  *
1582  * \code
1583  * ast_rtp_instance_set_stats_vars(chan, rtp);
1584  * \endcode
1585  *
1586  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
1587  * by chan.
1588  *
1589  * \since 1.8
1590  */
1591 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
1592
1593 /*!
1594  * \brief Retrieve quality statistics about an RTP instance
1595  *
1596  * \param instance Instance to get statistics on
1597  * \param field What quality statistic to retrieve
1598  * \param buf What buffer to put the result into
1599  * \param size Size of the above buffer
1600  *
1601  * \retval non-NULL success
1602  * \retval NULL failure
1603  *
1604  * Example usage:
1605  *
1606  * \code
1607  * char quality[AST_MAX_USER_FIELD];
1608  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
1609  * \endcode
1610  *
1611  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
1612  *
1613  * \since 1.8
1614  */
1615 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
1616
1617 /*!
1618  * \brief Request that the underlying RTP engine provide audio frames in a specific format
1619  *
1620  * \param instance The RTP instance to change read format on
1621  * \param format Format that frames are wanted in
1622  *
1623  * \retval 0 success
1624  * \retval -1 failure
1625  *
1626  * Example usage:
1627  *
1628  * \code
1629  * struct ast_format tmp_fmt;
1630  * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1631  * \endcode
1632  *
1633  * This requests that the RTP engine provide audio frames in the ULAW format.
1634  *
1635  * \since 1.8
1636  */
1637 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
1638
1639 /*!
1640  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
1641  *
1642  * \param instance The RTP instance to change write format on
1643  * \param format Format that frames will be provided in
1644  *
1645  * \retval 0 success
1646  * \retval -1 failure
1647  *
1648  * Example usage:
1649  *
1650  * \code
1651  * struct ast_format tmp_fmt;
1652  * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1653  * \endcode
1654  *
1655  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
1656  *
1657  * \since 1.8
1658  */
1659 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
1660
1661 /*!
1662  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
1663  *
1664  * \param chan Our own Asterisk channel
1665  * \param instance The first RTP instance
1666  * \param peer The peer Asterisk channel
1667  *
1668  * \retval 0 success
1669  * \retval -1 failure
1670  *
1671  * Example usage:
1672  *
1673  * \code
1674  * ast_rtp_instance_make_compatible(instance, peer);
1675  * \endcode
1676  *
1677  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
1678  *
1679  * \since 1.8
1680  */
1681 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
1682
1683 /*! \brief Request the formats that can be transcoded
1684  *
1685  * \param instance The RTP instance
1686  * \param to_endpoint Formats being sent/received towards the endpoint
1687  * \param to_asterisk Formats being sent/received towards Asterisk
1688  * \param result capabilities structure to store and return supported formats in.
1689  *
1690  * Example usage:
1691  *
1692  * \code
1693  * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
1694  * \endcode
1695  *
1696  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
1697  *
1698  * \since 1.8
1699  */
1700 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);
1701
1702 /*!
1703  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
1704  *
1705  * \param instance The RTP instance
1706  *
1707  * \retval 0 success
1708  * \retval -1 failure
1709  *
1710  * Example usage:
1711  *
1712  * \code
1713  * ast_rtp_instance_activate(instance);
1714  * \endcode
1715  *
1716  * This tells the underlying RTP engine of instance that packets will now flow.
1717  *
1718  * \since 1.8
1719  */
1720 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
1721
1722 /*!
1723  * \brief Request that the underlying RTP engine send a STUN BIND request
1724  *
1725  * \param instance The RTP instance
1726  * \param suggestion The suggested destination
1727  * \param username Optionally a username for the request
1728  *
1729  * Example usage:
1730  *
1731  * \code
1732  * ast_rtp_instance_stun_request(instance, NULL, NULL);
1733  * \endcode
1734  *
1735  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
1736  * 'instance'.
1737  *
1738  * \since 1.8
1739  */
1740 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
1741
1742 /*!
1743  * \brief Set the RTP timeout value
1744  *
1745  * \param instance The RTP instance
1746  * \param timeout Value to set the timeout to
1747  *
1748  * Example usage:
1749  *
1750  * \code
1751  * ast_rtp_instance_set_timeout(instance, 5000);
1752  * \endcode
1753  *
1754  * This sets the RTP timeout value on 'instance' to be 5000.
1755  *
1756  * \since 1.8
1757  */
1758 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
1759
1760 /*!
1761  * \brief Set the RTP timeout value for when the instance is on hold
1762  *
1763  * \param instance The RTP instance
1764  * \param timeout Value to set the timeout to
1765  *
1766  * Example usage:
1767  *
1768  * \code
1769  * ast_rtp_instance_set_hold_timeout(instance, 5000);
1770  * \endcode
1771  *
1772  * This sets the RTP hold timeout value on 'instance' to be 5000.
1773  *
1774  * \since 1.8
1775  */
1776 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
1777
1778 /*!
1779  * \brief Set the RTP keepalive interval
1780  *
1781  * \param instance The RTP instance
1782  * \param period Value to set the keepalive interval to
1783  *
1784  * Example usage:
1785  *
1786  * \code
1787  * ast_rtp_instance_set_keepalive(instance, 5000);
1788  * \endcode
1789  *
1790  * This sets the RTP keepalive interval on 'instance' to be 5000.
1791  *
1792  * \since 1.8
1793  */
1794 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
1795
1796 /*!
1797  * \brief Get the RTP timeout value
1798  *
1799  * \param instance The RTP instance
1800  *
1801  * \retval timeout value
1802  *
1803  * Example usage:
1804  *
1805  * \code
1806  * int timeout = ast_rtp_instance_get_timeout(instance);
1807  * \endcode
1808  *
1809  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
1810  *
1811  * \since 1.8
1812  */
1813 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
1814
1815 /*!
1816  * \brief Get the RTP timeout value for when an RTP instance is on hold
1817  *
1818  * \param instance The RTP instance
1819  *
1820  * \retval timeout value
1821  *
1822  * Example usage:
1823  *
1824  * \code
1825  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
1826  * \endcode
1827  *
1828  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
1829  *
1830  * \since 1.8
1831  */
1832 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
1833
1834 /*!
1835  * \brief Get the RTP keepalive interval
1836  *
1837  * \param instance The RTP instance
1838  *
1839  * \retval period Keepalive interval value
1840  *
1841  * Example usage:
1842  *
1843  * \code
1844  * int interval = ast_rtp_instance_get_keepalive(instance);
1845  * \endcode
1846  *
1847  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
1848  *
1849  * \since 1.8
1850  */
1851 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
1852
1853 /*!
1854  * \brief Get the RTP engine in use on an RTP instance
1855  *
1856  * \param instance The RTP instance
1857  *
1858  * \retval pointer to the engine
1859  *
1860  * Example usage:
1861  *
1862  * \code
1863  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
1864  * \endcode
1865  *
1866  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
1867  *
1868  * \since 1.8
1869  */
1870 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
1871
1872 /*!
1873  * \brief Get the RTP glue in use on an RTP instance
1874  *
1875  * \param instance The RTP instance
1876  *
1877  * \retval pointer to the glue
1878  *
1879  * Example:
1880  *
1881  * \code
1882  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
1883  * \endcode
1884  *
1885  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
1886  *
1887  * \since 1.8
1888  */
1889 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
1890
1891 /*!
1892  * \brief Get the channel that is associated with an RTP instance while in a bridge
1893  *
1894  * \param instance The RTP instance
1895  *
1896  * \retval pointer to the channel
1897  *
1898  * Example:
1899  *
1900  * \code
1901  * struct ast_channel *chan = ast_rtp_instance_get_chan(instance);
1902  * \endcode
1903  *
1904  * This gets the channel associated with the RTP instance pointed to by 'instance'.
1905  *
1906  * \note This will only return a channel while in a local or remote bridge.
1907  *
1908  * \since 1.8
1909  */
1910 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance);
1911
1912 /*!
1913  * \brief Send a comfort noise packet to the RTP instance
1914  *
1915  * \param instance The RTP instance
1916  * \param level Magnitude of the noise level
1917  *
1918  * \retval 0 Success
1919  * \retval non-zero Failure
1920  */
1921 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
1922
1923 /*!
1924  * \brief Add or replace the SRTP policies for the given RTP instance
1925  *
1926  * \param instance the RTP instance
1927  * \param remote_policy the remote endpoint's policy
1928  * \param local_policy our policy for this RTP instance's remote endpoint
1929  *
1930  * \retval 0 Success
1931  * \retval non-zero Failure
1932  */
1933 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy);
1934
1935 /*!
1936  * \brief Obtain the SRTP instance associated with an RTP instance
1937  *
1938  * \param instance the RTP instance
1939  * \retval the SRTP instance on success
1940  * \retval NULL if no SRTP instance exists
1941  */
1942 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance);
1943
1944 /*! \brief Custom formats declared in codecs.conf at startup must be communicated to the rtp_engine
1945  * so their mime type can payload number can be initialized. */
1946 int ast_rtp_engine_load_format(const struct ast_format *format);
1947
1948 /*! \brief Formats requiring the use of a format attribute interface must have that
1949  * interface registered in order for the rtp engine to handle it correctly.  If an
1950  * attribute interface is unloaded, this function must be called to notify the rtp_engine. */
1951 int ast_rtp_engine_unload_format(const struct ast_format *format);
1952
1953 /*!
1954  * \brief Obtain a pointer to the ICE support present on an RTP instance
1955  *
1956  * \param instance the RTP instance
1957  *
1958  * \retval ICE support if present
1959  * \retval NULL if no ICE support available
1960  */
1961 struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *instance);
1962
1963 #if defined(__cplusplus) || defined(c_plusplus)
1964 }
1965 #endif
1966
1967 #endif /* _ASTERISK_RTP_ENGINE_H */