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