Merged revisions 221086 via svnmerge from
[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
74 /* Maximum number of payloads supported */
75 #define AST_RTP_MAX_PT 256
76
77 /* Maximum number of generations */
78 #define AST_RED_MAX_GENERATION 5
79
80 struct ast_rtp_instance;
81 struct ast_rtp_glue;
82
83 /*! RTP Properties that can be set on an RTP instance */
84 enum ast_rtp_property {
85         /*! Enable symmetric RTP support */
86         AST_RTP_PROPERTY_NAT = 0,
87         /*! RTP instance will be carrying DTMF (using RFC2833) */
88         AST_RTP_PROPERTY_DTMF,
89         /*! Expect unreliable DTMF from remote party */
90         AST_RTP_PROPERTY_DTMF_COMPENSATE,
91         /*! Enable STUN support */
92         AST_RTP_PROPERTY_STUN,
93         /*! Enable RTCP support */
94         AST_RTP_PROPERTY_RTCP,
95         /*! Maximum number of RTP properties supported */
96         AST_RTP_PROPERTY_MAX,
97 };
98
99 /*! Additional RTP options */
100 enum ast_rtp_options {
101         /*! Remote side is using non-standard G.726 */
102         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
103 };
104
105 /*! RTP DTMF Modes */
106 enum ast_rtp_dtmf_mode {
107         /*! No DTMF is being carried over the RTP stream */
108         AST_RTP_DTMF_MODE_NONE = 0,
109         /*! DTMF is being carried out of band using RFC2833 */
110         AST_RTP_DTMF_MODE_RFC2833,
111         /*! DTMF is being carried inband over the RTP stream */
112         AST_RTP_DTMF_MODE_INBAND,
113 };
114
115 /*! Result codes when RTP glue is queried for information */
116 enum ast_rtp_glue_result {
117         /*! No remote or local bridging is permitted */
118         AST_RTP_GLUE_RESULT_FORBID = 0,
119         /*! Move RTP stream to be remote between devices directly */
120         AST_RTP_GLUE_RESULT_REMOTE,
121         /*! Perform RTP engine level bridging if possible */
122         AST_RTP_GLUE_RESULT_LOCAL,
123 };
124
125 /*! Field statistics that can be retrieved from an RTP instance */
126 enum ast_rtp_instance_stat_field {
127         /*! Retrieve quality information */
128         AST_RTP_INSTANCE_STAT_FIELD_QUALITY = 0,
129         /*! Retrieve quality information about jitter */
130         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_JITTER,
131         /*! Retrieve quality information about packet loss */
132         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_LOSS,
133         /*! Retrieve quality information about round trip time */
134         AST_RTP_INSTANCE_STAT_FIELD_QUALITY_RTT,
135 };
136
137 /*! Statistics that can be retrieved from an RTP instance */
138 enum ast_rtp_instance_stat {
139         /*! Retrieve all statistics */
140         AST_RTP_INSTANCE_STAT_ALL = 0,
141         /*! Retrieve number of packets transmitted */
142         AST_RTP_INSTANCE_STAT_TXCOUNT,
143         /*! Retrieve number of packets received */
144         AST_RTP_INSTANCE_STAT_RXCOUNT,
145         /*! Retrieve ALL statistics relating to packet loss */
146         AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
147         /*! Retrieve number of packets lost for transmitting */
148         AST_RTP_INSTANCE_STAT_TXPLOSS,
149         /*! Retrieve number of packets lost for receiving */
150         AST_RTP_INSTANCE_STAT_RXPLOSS,
151         /*! Retrieve maximum number of packets lost on remote side */
152         AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
153         /*! Retrieve minimum number of packets lost on remote side */
154         AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
155         /*! Retrieve average number of packets lost on remote side */
156         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
157         /*! Retrieve standard deviation of packets lost on remote side */
158         AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
159         /*! Retrieve maximum number of packets lost on local side */
160         AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
161         /*! Retrieve minimum number of packets lost on local side */
162         AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
163         /*! Retrieve average number of packets lost on local side */
164         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
165         /*! Retrieve standard deviation of packets lost on local side */
166         AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
167         /*! Retrieve ALL statistics relating to jitter */
168         AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
169         /*! Retrieve jitter on transmitted packets */
170         AST_RTP_INSTANCE_STAT_TXJITTER,
171         /*! Retrieve jitter on received packets */
172         AST_RTP_INSTANCE_STAT_RXJITTER,
173         /*! Retrieve maximum jitter on remote side */
174         AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
175         /*! Retrieve minimum jitter on remote side */
176         AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
177         /*! Retrieve average jitter on remote side */
178         AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
179         /*! Retrieve standard deviation jitter on remote side */
180         AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
181         /*! Retrieve maximum jitter on local side */
182         AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
183         /*! Retrieve minimum jitter on local side */
184         AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
185         /*! Retrieve average jitter on local side */
186         AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
187         /*! Retrieve standard deviation jitter on local side */
188         AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
189         /*! Retrieve ALL statistics relating to round trip time */
190         AST_RTP_INSTANCE_STAT_COMBINED_RTT,
191         /*! Retrieve round trip time */
192         AST_RTP_INSTANCE_STAT_RTT,
193         /*! Retrieve maximum round trip time */
194         AST_RTP_INSTANCE_STAT_MAX_RTT,
195         /*! Retrieve minimum round trip time */
196         AST_RTP_INSTANCE_STAT_MIN_RTT,
197         /*! Retrieve average round trip time */
198         AST_RTP_INSTANCE_STAT_NORMDEVRTT,
199         /*! Retrieve standard deviation round trip time */
200         AST_RTP_INSTANCE_STAT_STDEVRTT,
201         /*! Retrieve local SSRC */
202         AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
203         /*! Retrieve remote SSRC */
204         AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
205 };
206
207 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
208 /*! DTMF (RFC2833) */
209 #define AST_RTP_DTMF                    (1 << 0)
210 /*! 'Comfort Noise' (RFC3389) */
211 #define AST_RTP_CN                      (1 << 1)
212 /*! DTMF (Cisco Proprietary) */
213 #define AST_RTP_CISCO_DTMF              (1 << 2)
214 /*! Maximum RTP-specific code */
215 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
216
217 /*! Structure that represents a payload */
218 struct ast_rtp_payload_type {
219         /*! Is this an Asterisk value */
220         int asterisk_format;
221         /*! Actual internal value of the payload */
222         int code;
223 };
224
225 /*! Structure that represents statistics from an RTP instance */
226 struct ast_rtp_instance_stats {
227         /*! Number of packets transmitted */
228         unsigned int txcount;
229         /*! Number of packets received */
230         unsigned int rxcount;
231         /*! Jitter on transmitted packets */
232         unsigned int txjitter;
233         /*! Jitter on received packets */
234         unsigned int rxjitter;
235         /*! Maximum jitter on remote side */
236         double remote_maxjitter;
237         /*! Minimum jitter on remote side */
238         double remote_minjitter;
239         /*! Average jitter on remote side */
240         double remote_normdevjitter;
241         /*! Standard deviation jitter on remote side */
242         double remote_stdevjitter;
243         /*! Maximum jitter on local side */
244         double local_maxjitter;
245         /*! Minimum jitter on local side */
246         double local_minjitter;
247         /*! Average jitter on local side */
248         double local_normdevjitter;
249         /*! Standard deviation jitter on local side */
250         double local_stdevjitter;
251         /*! Number of transmitted packets lost */
252         unsigned int txploss;
253         /*! Number of received packets lost */
254         unsigned int rxploss;
255         /*! Maximum number of packets lost on remote side */
256         double remote_maxrxploss;
257         /*! Minimum number of packets lost on remote side */
258         double remote_minrxploss;
259         /*! Average number of packets lost on remote side */
260         double remote_normdevrxploss;
261         /*! Standard deviation packets lost on remote side */
262         double remote_stdevrxploss;
263         /*! Maximum number of packets lost on local side */
264         double local_maxrxploss;
265         /*! Minimum number of packets lost on local side */
266         double local_minrxploss;
267         /*! Average number of packets lost on local side */
268         double local_normdevrxploss;
269         /*! Standard deviation packets lost on local side */
270         double local_stdevrxploss;
271         /*! Total round trip time */
272         unsigned int rtt;
273         /*! Maximum round trip time */
274         double maxrtt;
275         /*! Minimum round trip time */
276         double minrtt;
277         /*! Average round trip time */
278         double normdevrtt;
279         /*! Standard deviation round trip time */
280         double stdevrtt;
281         /*! Our SSRC */
282         unsigned int local_ssrc;
283         /*! Their SSRC */
284         unsigned int remote_ssrc;
285 };
286
287 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
288 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
289 placement = value; \
290 if (stat == current_stat) { \
291 return 0; \
292 } \
293 }
294
295 #define AST_RTP_STAT_TERMINATOR(combined) \
296 if (stat == combined) { \
297 return 0; \
298 }
299
300 /*! Structure that represents an RTP stack (engine) */
301 struct ast_rtp_engine {
302         /*! Name of the RTP engine, used when explicitly requested */
303         const char *name;
304         /*! Module this RTP engine came from, used for reference counting */
305         struct ast_module *mod;
306         /*! Callback for setting up a new RTP instance */
307         int (*new)(struct ast_rtp_instance *instance, struct sched_context *sched, struct sockaddr_in *sin, void *data);
308         /*! Callback for destroying an RTP instance */
309         int (*destroy)(struct ast_rtp_instance *instance);
310         /*! Callback for writing out a frame */
311         int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
312         /*! Callback for stopping the RTP instance */
313         void (*stop)(struct ast_rtp_instance *instance);
314         /*! Callback for starting RFC2833 DTMF transmission */
315         int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
316         /*! Callback for stopping RFC2833 DTMF transmission */
317         int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
318         /*! Callback to indicate that a new source of media has come in */
319         void (*new_source)(struct ast_rtp_instance *instance);
320         /*! Callback to tell new_source not to change SSRC */
321         void (*constant_ssrc_set)(struct ast_rtp_instance *instance);
322         /*! Callback for setting an extended RTP property */
323         int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
324         /*! Callback for getting an extended RTP property */
325         void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
326         /*! Callback for setting an RTP property */
327         void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
328         /*! Callback for setting a payload */
329         void (*payload_set)(struct ast_rtp_instance *instance, int payload, int astformat, int format);
330         /*! Callback for setting packetization preferences */
331         void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
332         /*! Callback for setting the remote address that RTP is to be sent to */
333         void (*remote_address_set)(struct ast_rtp_instance *instance, struct sockaddr_in *sin);
334         /*! Callback for setting an alternate remote address */
335         void (*alt_remote_address_set)(struct ast_rtp_instance *instance, struct sockaddr_in *sin);
336         /*! Callback for changing DTMF mode */
337         int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
338         /*! Callback for retrieving statistics */
339         int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
340         /*! Callback for setting QoS values */
341         int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
342         /*! Callback for retrieving a file descriptor to poll on, not always required */
343         int (*fd)(struct ast_rtp_instance *instance, int rtcp);
344         /*! Callback for initializing RED support */
345         int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
346         /*! Callback for buffering a frame using RED */
347         int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
348         /*! Callback for reading a frame from the RTP engine */
349         struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
350         /*! Callback to locally bridge two RTP instances */
351         int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
352         /*! Callback to set the read format */
353         int (*set_read_format)(struct ast_rtp_instance *instance, int format);
354         /*! Callback to set the write format */
355         int (*set_write_format)(struct ast_rtp_instance *instance, int format);
356         /*! Callback to make two instances compatible */
357         int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
358         /*! Callback to see if two instances are compatible with DTMF */
359         int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
360         /*! Callback to indicate that packets will now flow */
361         int (*activate)(struct ast_rtp_instance *instance);
362         /*! Callback to request that the RTP engine send a STUN BIND request */
363         void (*stun_request)(struct ast_rtp_instance *instance, struct sockaddr_in *suggestion, const char *username);
364         /*! Callback to get the transcodeable formats supported */
365         int (*available_formats)(struct ast_rtp_instance *instance, int to_endpoint, int to_asterisk);
366         /*! Linked list information */
367         AST_RWLIST_ENTRY(ast_rtp_engine) entry;
368 };
369
370 /*! Structure that represents codec and packetization information */
371 struct ast_rtp_codecs {
372         /*! Codec packetization preferences */
373         struct ast_codec_pref pref;
374         /*! Payloads present */
375         struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT];
376 };
377
378 /*! Structure that represents the glue that binds an RTP instance to a channel */
379 struct ast_rtp_glue {
380         /*! Name of the channel driver that this glue is responsible for */
381         const char *type;
382         /*! Module that the RTP glue came from */
383         struct ast_module *mod;
384         /*!
385          * \brief Callback for retrieving the RTP instance carrying audio
386          * \note This function increases the reference count on the returned RTP instance.
387          */
388         enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
389         /*!
390          * \brief Callback for retrieving the RTP instance carrying video
391          * \note This function increases the reference count on the returned RTP instance.
392          */
393         enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
394         /*!
395          * \brief Callback for retrieving the RTP instance carrying text
396          * \note This function increases the reference count on the returned RTP instance.
397          */
398         enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
399         /*! Callback for updating the destination that the remote side should send RTP to */
400         int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, int codecs, int nat_active);
401         /*! Callback for retrieving codecs that the channel can do */
402         int (*get_codec)(struct ast_channel *chan);
403         /*! Linked list information */
404         AST_RWLIST_ENTRY(ast_rtp_glue) entry;
405 };
406
407 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
408
409 /*!
410  * \brief Register an RTP engine
411  *
412  * \param engine Structure of the RTP engine to register
413  * \param module Module that the RTP engine is part of
414  *
415  * \retval 0 success
416  * \retval -1 failure
417  *
418  * Example usage:
419  *
420  * \code
421  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
422  * \endcode
423  *
424  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
425  * associate a module with it.
426  *
427  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
428  *       associated with the RTP engine and use counting is performed.
429  *
430  * \since 1.6.3
431  */
432 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
433
434 /*!
435  * \brief Unregister an RTP engine
436  *
437  * \param engine Structure of the RTP engine to unregister
438  *
439  * \retval 0 success
440  * \retval -1 failure
441  *
442  * Example usage:
443  *
444  * \code
445  * ast_rtp_engine_unregister(&example_rtp_engine);
446  * \endcode
447  *
448  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
449  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
450  *
451  * \since 1.6.3
452  */
453 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
454
455 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
456
457 /*!
458  * \brief Register RTP glue
459  *
460  * \param glue The glue to register
461  * \param module Module that the RTP glue is part of
462  *
463  * \retval 0 success
464  * \retval -1 failure
465  *
466  * Example usage:
467  *
468  * \code
469  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
470  * \endcode
471  *
472  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
473  * associate a module with it.
474  *
475  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
476  *       associated with the RTP glue and use counting is performed.
477  *
478  * \since 1.6.3
479  */
480 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
481
482 /*!
483  * \brief Unregister RTP glue
484  *
485  * \param glue The glue to unregister
486  *
487  * \retval 0 success
488  * \retval -1 failure
489  *
490  * Example usage:
491  *
492  * \code
493  * ast_rtp_glue_unregister(&example_rtp_glue);
494  * \endcode
495  *
496  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
497  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
498  *
499  * \since 1.6.3
500  */
501 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
502
503 /*!
504  * \brief Create a new RTP instance
505  *
506  * \param engine_name Name of the engine to use for the RTP instance
507  * \param sched Scheduler context that the RTP engine may want to use
508  * \param sin Address we want to bind to
509  * \param data Unique data for the engine
510  *
511  * \retval non-NULL success
512  * \retval NULL failure
513  *
514  * Example usage:
515  *
516  * \code
517  * struct ast_rtp_instance *instance = NULL;
518  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
519  * \endcode
520  *
521  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
522  * in the sin structure.
523  *
524  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
525  *       another depending on it's own configuration.
526  *
527  * \since 1.6.3
528  */
529 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name, struct sched_context *sched, struct sockaddr_in *sin, void *data);
530
531 /*!
532  * \brief Destroy an RTP instance
533  *
534  * \param instance The RTP instance to destroy
535  *
536  * \retval 0 success
537  * \retval -1 failure
538  *
539  * Example usage:
540  *
541  * \code
542  * ast_rtp_instance_destroy(instance);
543  * \endcode
544  *
545  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
546  * memory and may not be used again.
547  *
548  * \since 1.6.3
549  */
550 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
551
552 /*!
553  * \brief Set the data portion of an RTP instance
554  *
555  * \param instance The RTP instance to manipulate
556  * \param data Pointer to data
557  *
558  * Example usage:
559  *
560  * \code
561  * ast_rtp_instance_set_data(instance, blob);
562  * \endcode
563  *
564  * This sets the data pointer on the RTP instance pointed to by 'instance' to
565  * blob.
566  *
567  * \since 1.6.3
568  */
569 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
570
571 /*!
572  * \brief Get the data portion of an RTP instance
573  *
574  * \param instance The RTP instance we want the data portion from
575  *
576  * Example usage:
577  *
578  * \code
579  * struct *blob = ast_rtp_instance_get_data(instance);
580  ( \endcode
581  *
582  * This gets the data pointer on the RTP instance pointed to by 'instance'.
583  *
584  * \since 1.6.3
585  */
586 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
587
588 /*!
589  * \brief Send a frame out over RTP
590  *
591  * \param instance The RTP instance to send frame out on
592  *
593  * \retval 0 success
594  * \retval -1 failure
595  *
596  * Example usage:
597  *
598  * \code
599  * ast_rtp_instance_write(instance, frame);
600  * \endcode
601  *
602  * This gives the frame pointed to by frame to the RTP engine being used for the instance
603  * and asks that it be transmitted to the current remote address set on the RTP instance.
604  *
605  * \since 1.6.3
606  */
607 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
608
609 /*!
610  * \brief Receive a frame over RTP
611  *
612  * \param instance The RTP instance to receive frame on
613  * \param rtcp Whether to read in RTCP or not
614  *
615  * \retval non-NULL success
616  * \retval NULL failure
617  *
618  * Example usage:
619  *
620  * \code
621  * struct ast_frame *frame;
622  * frame = ast_rtp_instance_read(instance, 0);
623  * \endcode
624  *
625  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
626  *
627  * \since 1.6.3
628  */
629 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
630
631 /*!
632  * \brief Set the address of the remote endpoint that we are sending RTP to
633  *
634  * \param instance The RTP instance to change the address on
635  * \param address Address to set it to
636  *
637  * \retval 0 success
638  * \retval -1 failure
639  *
640  * Example usage:
641  *
642  * \code
643  * ast_rtp_instance_set_remote_address(instance, &sin);
644  * \endcode
645  *
646  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
647  * structure.
648  *
649  * \since 1.6.3
650  */
651 int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
652
653 /*!
654  * \brief Set the address of an an alternate RTP address to receive from
655  *
656  * \param instance The RTP instance to change the address on
657  * \param address Address to set it to
658  *
659  * \retval 0 success
660  * \retval -1 failure
661  *
662  * Example usage:
663  *
664  * \code
665  * ast_rtp_instance_set_alt_remote_address(instance, &sin);
666  * \endcode
667  *
668  * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin
669  * structure.
670  *
671  * \since 1.6.3
672  */
673 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
674
675 /*!
676  * \brief Set the address that we are expecting to receive RTP on
677  *
678  * \param instance The RTP instance to change the address on
679  * \param address Address to set it to
680  *
681  * \retval 0 success
682  * \retval -1 failure
683  *
684  * Example usage:
685  *
686  * \code
687  * ast_rtp_instance_set_local_address(instance, &sin);
688  * \endcode
689  *
690  * This changes the local address that RTP is expected on to the address given in the sin
691  * structure.
692  *
693  * \since 1.6.3
694  */
695 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
696
697 /*!
698  * \brief Get the local address that we are expecting RTP on
699  *
700  * \param instance The RTP instance to get the address from
701  * \param address The variable to store the address in
702  *
703  * \retval 0 success
704  * \retval -1 failure
705  *
706  * Example usage:
707  *
708  * \code
709  * struct sockaddr_in sin;
710  * ast_rtp_instance_get_local_address(instance, &sin);
711  * \endcode
712  *
713  * This gets the local address that we are expecting RTP on and stores it in the 'sin' structure.
714  *
715  * \since 1.6.3
716  */
717 int ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
718
719 /*!
720  * \brief Get the address of the remote endpoint that we are sending RTP to
721  *
722  * \param instance The instance that we want to get the remote address for
723  * \param address A structure to put the address into
724  *
725  * \retval 0 success
726  * \retval -1 failure
727  *
728  * Example usage:
729  *
730  * \code
731  * struct sockaddr_in sin;
732  * ast_rtp_instance_get_remote_address(instance, &sin);
733  * \endcode
734  *
735  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
736  * into the sin structure.
737  *
738  * \since 1.6.3
739  */
740 int ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
741
742 /*!
743  * \brief Set the value of an RTP instance extended property
744  *
745  * \param instance The RTP instance to set the extended property on
746  * \param property The extended property to set
747  * \param value The value to set the extended property to
748  *
749  * \since 1.6.3
750  */
751 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
752
753 /*!
754  * \brief Get the value of an RTP instance extended property
755  *
756  * \param instance The RTP instance to get the extended property on
757  * \param property The extended property to get
758  *
759  * \since 1.6.3
760  */
761 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
762
763 /*!
764  * \brief Set the value of an RTP instance property
765  *
766  * \param instance The RTP instance to set the property on
767  * \param property The property to modify
768  * \param value The value to set the property to
769  *
770  * Example usage:
771  *
772  * \code
773  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
774  * \endcode
775  *
776  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
777  *
778  * \since 1.6.3
779  */
780 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
781
782 /*!
783  * \brief Get the value of an RTP instance property
784  *
785  * \param instance The RTP instance to get the property from
786  * \param property The property to get
787  *
788  * \retval Current value of the property
789  *
790  * Example usage:
791  *
792  * \code
793  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
794  * \endcode
795  *
796  * This returns the current value of the NAT property on the instance pointed to by instance.
797  *
798  * \since 1.6.3
799  */
800 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
801
802 /*!
803  * \brief Get the codecs structure of an RTP instance
804  *
805  * \param instance The RTP instance to get the codecs structure from
806  *
807  * Example usage:
808  *
809  * \code
810  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
811  * \endcode
812  *
813  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
814  *
815  * \since 1.6.3
816  */
817 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
818
819 /*!
820  * \brief Clear payload information from an RTP instance
821  *
822  * \param codecs The codecs structure that payloads will be cleared from
823  * \param instance Optionally the instance that the codecs structure belongs to
824  *
825  * Example usage:
826  *
827  * \code
828  * struct ast_rtp_codecs codecs;
829  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
830  * \endcode
831  *
832  * This clears the codecs structure and puts it into a pristine state.
833  *
834  * \since 1.6.3
835  */
836 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
837
838 /*!
839  * \brief Set payload information on an RTP instance to the default
840  *
841  * \param codecs The codecs structure to set defaults on
842  * \param instance Optionally the instance that the codecs structure belongs to
843  *
844  * Example usage:
845  *
846  * \code
847  * struct ast_rtp_codecs codecs;
848  * ast_rtp_codecs_payloads_default(&codecs, NULL);
849  * \endcode
850  *
851  * This sets the default payloads on the codecs structure.
852  *
853  * \since 1.6.3
854  */
855 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
856
857 /*!
858  * \brief Copy payload information from one RTP instance to another
859  *
860  * \param src The source codecs structure
861  * \param dst The destination codecs structure that the values from src will be copied to
862  * \param instance Optionally the instance that the dst codecs structure belongs to
863  *
864  * Example usage:
865  *
866  * \code
867  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
868  * \endcode
869  *
870  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
871  *
872  * \since 1.6.3
873  */
874 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
875
876 /*!
877  * \brief Record payload information that was seen in an m= SDP line
878  *
879  * \param codecs The codecs structure to muck with
880  * \param instance Optionally the instance that the codecs structure belongs to
881  * \param payload Numerical payload that was seen in the m= SDP line
882  *
883  * Example usage:
884  *
885  * \code
886  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
887  * \endcode
888  *
889  * This records that the numerical payload '0' was seen in the codecs structure.
890  *
891  * \since 1.6.3
892  */
893 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
894
895 /*!
896  * \brief Record payload information that was seen in an a=rtpmap: SDP line
897  *
898  * \param codecs The codecs structure to muck with
899  * \param instance Optionally the instance that the codecs structure belongs to
900  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
901  * \param mimetype The string mime type that was seen
902  * \param mimesubtype The strin mime sub type that was seen
903  * \param options Optional options that may change the behavior of this specific payload
904  *
905  * \retval 0 success
906  * \retval -1 failure
907  *
908  * Example usage:
909  *
910  * \code
911  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
912  * \endcode
913  *
914  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
915  *
916  * \since 1.6.3
917  */
918 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);
919
920 /*!
921  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
922  *
923  * \param rtp RTP structure to modify
924  * \param instance Optionally the instance that the codecs structure belongs to
925  * \param pt Payload type entry to modify
926  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
927  * \param mimesubtype MIME subtype of media stream (typically a codec name)
928  * \param options Zero or more flags from the ast_rtp_options enum
929  * \param sample_rate The sample rate of the media stream
930  *
931  * This function 'fills in' an entry in the list of possible formats for
932  * a media stream associated with an RTP structure.
933  *
934  * \retval 0 on success
935  * \retval -1 if the payload type is out of range
936  * \retval -2 if the mimeType/mimeSubtype combination was not found
937  *
938  * \since 1.6.3
939  */
940 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
941                                   char *mimetype, char *mimesubtype,
942                                   enum ast_rtp_options options,
943                                   unsigned int sample_rate);
944
945 /*!
946  * \brief Remove payload information
947  *
948  * \param codecs The codecs structure to muck with
949  * \param instance Optionally the instance that the codecs structure belongs to
950  * \param payload Numerical payload to unset
951  *
952  * Example usage:
953  *
954  * \code
955  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
956  * \endcode
957  *
958  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
959  *
960  * \since 1.6.3
961  */
962 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
963
964 /*!
965  * \brief Retrieve payload information by payload
966  *
967  * \param codecs Codecs structure to look in
968  * \param payload Numerical payload to look up
969  *
970  * \retval Payload information
971  *
972  * Example usage:
973  *
974  * \code
975  * struct ast_rtp_payload_type payload_type;
976  * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
977  * \endcode
978  *
979  * This looks up the information for payload '0' from the codecs structure.
980  *
981  * \since 1.6.3
982  */
983 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
984
985 /*!
986  * \brief Get the sample rate associated with known RTP payload types
987  *
988  * \param asterisk_format True if the value in the 'code' parameter is an AST_FORMAT value
989  * \param code Format code, either from AST_FORMAT list or from AST_RTP list
990  *
991  * \return the sample rate if the format was found, zero if it was not found
992  *
993  * \since 1.6.3
994  */
995 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, int code);
996
997 /*!
998  * \brief Retrieve all formats that were found
999  *
1000  * \param codecs Codecs structure to look in
1001  * \param astFormats An integer to put the Asterisk formats in
1002  * \param nonastformats An integer to put the non-Asterisk formats in
1003  *
1004  * Example usage:
1005  *
1006  * \code
1007  * int astformats, nonastformats;
1008  * ast_rtp_codecs_payload_Formats(&codecs, &astformats, &nonastformats);
1009  * \endcode
1010  *
1011  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
1012  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
1013  *
1014  * \since 1.6.3
1015  */
1016 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, int *astformats, int *nonastformats);
1017
1018 /*!
1019  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
1020  *
1021  * \param codecs Codecs structure to look in
1022  * \param asterisk_format Non-zero if the given code is an Asterisk format value
1023  * \param code The format to look for
1024  *
1025  * \retval Numerical payload
1026  *
1027  * Example usage:
1028  *
1029  * \code
1030  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, AST_FORMAT_ULAW);
1031  * \endcode
1032  *
1033  * This looks for the numerical payload for ULAW in the codecs structure.
1034  *
1035  * \since 1.6.3
1036  */
1037 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int asterisk_format, const int code);
1038
1039 /*!
1040  * \brief Retrieve mime subtype information on a payload
1041  *
1042  * \param asterisk_format Non-zero if the given code is an Asterisk format value
1043  * \param code Format to look up
1044  * \param options Additional options that may change the result
1045  *
1046  * \retval Mime subtype success
1047  * \retval NULL failure
1048  *
1049  * Example usage:
1050  *
1051  * \code
1052  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, AST_FORMAT_ULAW, 0);
1053  * \endcode
1054  *
1055  * This looks up the mime subtype for the ULAW format.
1056  *
1057  * \since 1.6.3
1058  */
1059 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, const int code, enum ast_rtp_options options);
1060
1061 /*!
1062  * \brief Convert formats into a string and put them into a buffer
1063  *
1064  * \param buf Buffer to put the mime output into
1065  * \param capability Formats that we are looking up
1066  * \param asterisk_format Non-zero if the given capability are Asterisk format capabilities
1067  * \param options Additional options that may change the result
1068  *
1069  * \retval non-NULL success
1070  * \retval NULL failure
1071  *
1072  * Example usage:
1073  *
1074  * \code
1075  * char buf[256] = "";
1076  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), AST_FORMAT_ULAW | AST_FORMAT_ALAW, 1, 0);
1077  * \endcode
1078  *
1079  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
1080  *
1081  * \since 1.6.3
1082  */
1083 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, const int capability, const int asterisk_format, enum ast_rtp_options options);
1084
1085 /*!
1086  * \brief Set codec packetization preferences
1087  *
1088  * \param codecs Codecs structure to muck with
1089  * \param instance Optionally the instance that the codecs structure belongs to
1090  * \param prefs Codec packetization preferences
1091  *
1092  * Example usage:
1093  *
1094  * \code
1095  * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
1096  * \endcode
1097  *
1098  * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
1099  *
1100  * \since 1.6.3
1101  */
1102 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
1103
1104 /*!
1105  * \brief Begin sending a DTMF digit
1106  *
1107  * \param instance The RTP instance to send the DTMF on
1108  * \param digit What DTMF digit to send
1109  *
1110  * \retval 0 success
1111  * \retval -1 failure
1112  *
1113  * Example usage:
1114  *
1115  * \code
1116  * ast_rtp_instance_dtmf_begin(instance, '1');
1117  * \endcode
1118  *
1119  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
1120  * continue being sent until it is ended.
1121  *
1122  * \since 1.6.3
1123  */
1124 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
1125
1126 /*!
1127  * \brief Stop sending a DTMF digit
1128  *
1129  * \param instance The RTP instance to stop the DTMF on
1130  * \param digit What DTMF digit to stop
1131  *
1132  * \retval 0 success
1133  * \retval -1 failure
1134  *
1135  * Example usage:
1136  *
1137  * \code
1138  * ast_rtp_instance_dtmf_end(instance, '1');
1139  * \endcode
1140  *
1141  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
1142  *
1143  * \since 1.6.3
1144  */
1145 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
1146
1147 /*!
1148  * \brief Set the DTMF mode that should be used
1149  *
1150  * \param instance the RTP instance to set DTMF mode on
1151  * \param dtmf_mode The DTMF mode that is in use
1152  *
1153  * \retval 0 success
1154  * \retval -1 failure
1155  *
1156  * Example usage:
1157  *
1158  * \code
1159  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
1160  * \endcode
1161  *
1162  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
1163  *
1164  * \since 1.6.3
1165  */
1166 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
1167
1168 /*!
1169  * \brief Get the DTMF mode of an RTP instance
1170  *
1171  * \param instance The RTP instance to get the DTMF mode of
1172  *
1173  * \retval DTMF mode
1174  *
1175  * Example usage:
1176  *
1177  * \code
1178  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
1179  * \endcode
1180  *
1181  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
1182  *
1183  * \since 1.6.3
1184  */
1185 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
1186
1187 /*!
1188  * \brief Mark an RTP instance not to update SSRC on a new source
1189  *
1190  * \param instance Instance to update
1191  *
1192  * Example usage:
1193  *
1194  * \code
1195  * ast_rtp_instance_set_constantssrc(instance);
1196  * \endcode
1197  *
1198  * This sets the indicated instance to not update the RTP SSRC when new_source
1199  * is called.
1200  *
1201  * \since 1.6.3
1202  */
1203 void ast_rtp_instance_set_constantssrc(struct ast_rtp_instance *instance);
1204 /*!
1205  * \brief Indicate a new source of audio has dropped in
1206  *
1207  * \param instance Instance that the new media source is feeding into
1208  *
1209  * Example usage:
1210  *
1211  * \code
1212  * ast_rtp_instance_new_source(instance);
1213  * \endcode
1214  *
1215  * This indicates that a new source of media is feeding the instance pointed to by
1216  * instance.
1217  *
1218  * \since 1.6.3
1219  */
1220 void ast_rtp_instance_new_source(struct ast_rtp_instance *instance);
1221
1222 /*!
1223  * \brief Set QoS parameters on an RTP session
1224  *
1225  * \param instance Instance to set the QoS parameters on
1226  * \param tos Terms of service value
1227  * \param cos Class of service value
1228  * \param desc What is setting the QoS values
1229  *
1230  * \retval 0 success
1231  * \retval -1 failure
1232  *
1233  * Example usage:
1234  *
1235  * \code
1236  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
1237  * \endcode
1238  *
1239  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
1240  *
1241  * \since 1.6.3
1242  */
1243 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
1244
1245 /*!
1246  * \brief Stop an RTP instance
1247  *
1248  * \param instance Instance that media is no longer going to at this time
1249  *
1250  * Example usage:
1251  *
1252  * \code
1253  * ast_rtp_instance_stop(instance);
1254  * \endcode
1255  *
1256  * This tells the RTP engine being used for the instance pointed to by instance
1257  * that media is no longer going to it at this time, but may in the future.
1258  *
1259  * \since 1.6.3
1260  */
1261 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
1262
1263 /*!
1264  * \brief Get the file descriptor for an RTP session (or RTCP)
1265  *
1266  * \param instance Instance to get the file descriptor for
1267  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
1268  *
1269  * \retval fd success
1270  * \retval -1 failure
1271  *
1272  * Example usage:
1273  *
1274  * \code
1275  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
1276  * \endcode
1277  *
1278  * This retrieves the file descriptor for the socket carrying media on the instance
1279  * pointed to by instance.
1280  *
1281  * \since 1.6.3
1282  */
1283 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
1284
1285 /*!
1286  * \brief Get the RTP glue that binds a channel to the RTP engine
1287  *
1288  * \param type Name of the glue we want
1289  *
1290  * \retval non-NULL success
1291  * \retval NULL failure
1292  *
1293  * Example usage:
1294  *
1295  * \code
1296  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
1297  * \endcode
1298  *
1299  * This retrieves the RTP glue that has the name 'Example'.
1300  *
1301  * \since 1.6.3
1302  */
1303 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
1304
1305 /*!
1306  * \brief Bridge two channels that use RTP instances
1307  *
1308  * \param c0 First channel part of the bridge
1309  * \param c1 Second channel part of the bridge
1310  * \param flags Bridging flags
1311  * \param fo If a frame needs to be passed up it is stored here
1312  * \param rc Channel that passed the above frame up
1313  * \param timeoutms How long the channels should be bridged for
1314  *
1315  * \retval Bridge result
1316  *
1317  * \note This should only be used by channel drivers in their technology declaration.
1318  *
1319  * \since 1.6.3
1320  */
1321 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);
1322
1323 /*!
1324  * \brief Get the other RTP instance that an instance is bridged to
1325  *
1326  * \param instance The RTP instance that we want
1327  *
1328  * \retval non-NULL success
1329  * \retval NULL failure
1330  *
1331  * Example usage:
1332  *
1333  * \code
1334  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
1335  * \endcode
1336  *
1337  * This gets the RTP instance that instance0 is bridged to.
1338  *
1339  * \since 1.6.3
1340  */
1341 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
1342
1343 /*!
1344  * \brief Make two channels compatible for early bridging
1345  *
1346  * \param c0 First channel part of the bridge
1347  * \param c1 Second channel part of the bridge
1348  *
1349  * \since 1.6.3
1350  */
1351 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1352
1353 /*!
1354  * \brief Early bridge two channels that use RTP instances
1355  *
1356  * \param c0 First channel part of the bridge
1357  * \param c1 Second channel part of the bridge
1358  *
1359  * \retval 0 success
1360  * \retval -1 failure
1361  *
1362  * \note This should only be used by channel drivers in their technology declaration.
1363  *
1364  * \since 1.6.3
1365  */
1366 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1367
1368 /*!
1369  * \brief Initialize RED support on an RTP instance
1370  *
1371  * \param instance The instance to initialize RED support on
1372  * \param buffer_time How long to buffer before sending
1373  * \param payloads Payload values
1374  * \param generations Number of generations
1375  *
1376  * \retval 0 success
1377  * \retval -1 failure
1378  *
1379  * \since 1.6.3
1380  */
1381 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
1382
1383 /*!
1384  * \brief Buffer a frame in an RTP instance for RED
1385  *
1386  * \param instance The instance to buffer the frame on
1387  * \param frame Frame that we want to buffer
1388  *
1389  * \retval 0 success
1390  * \retval -1 failure
1391  *
1392  * \since 1.6.3
1393  */
1394 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
1395
1396 /*!
1397  * \brief Retrieve statistics about an RTP instance
1398  *
1399  * \param instance Instance to get statistics on
1400  * \param stats Structure to put results into
1401  * \param stat What statistic(s) to retrieve
1402  *
1403  * \retval 0 success
1404  * \retval -1 failure
1405  *
1406  * Example usage:
1407  *
1408  * \code
1409  * struct ast_rtp_instance_stats stats;
1410  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
1411  * \endcode
1412  *
1413  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
1414  * stats structure.
1415  *
1416  * \since 1.6.3
1417  */
1418 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
1419
1420 /*!
1421  * \brief Set standard statistics from an RTP instance on a channel
1422  *
1423  * \param chan Channel to set the statistics on
1424  * \param instance The RTP instance that statistics will be retrieved from
1425  *
1426  * Example usage:
1427  *
1428  * \code
1429  * ast_rtp_instance_set_stats_vars(chan, rtp);
1430  * \endcode
1431  *
1432  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
1433  * by chan.
1434  *
1435  * \since 1.6.3
1436  */
1437 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
1438
1439 /*!
1440  * \brief Retrieve quality statistics about an RTP instance
1441  *
1442  * \param instance Instance to get statistics on
1443  * \param field What quality statistic to retrieve
1444  * \param buf What buffer to put the result into
1445  * \param size Size of the above buffer
1446  *
1447  * \retval non-NULL success
1448  * \retval NULL failure
1449  *
1450  * Example usage:
1451  *
1452  * \code
1453  * char quality[AST_MAX_USER_FIELD];
1454  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
1455  * \endcode
1456  *
1457  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
1458  *
1459  * \since 1.6.3
1460  */
1461 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
1462
1463 /*!
1464  * \brief Request that the underlying RTP engine provide audio frames in a specific format
1465  *
1466  * \param instance The RTP instance to change read format on
1467  * \param format Format that frames are wanted in
1468  *
1469  * \retval 0 success
1470  * \retval -1 failure
1471  *
1472  * Example usage:
1473  *
1474  * \code
1475  * ast_rtp_instance_set_read_format(instance, AST_FORMAT_ULAW);
1476  * \endcode
1477  *
1478  * This requests that the RTP engine provide audio frames in the ULAW format.
1479  *
1480  * \since 1.6.3
1481  */
1482 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, int format);
1483
1484 /*!
1485  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
1486  *
1487  * \param instance The RTP instance to change write format on
1488  * \param format Format that frames will be provided in
1489  *
1490  * \retval 0 success
1491  * \retval -1 failure
1492  *
1493  * Example usage:
1494  *
1495  * \code
1496  * ast_rtp_instance_set_write_format(instance, AST_FORMAT_ULAW);
1497  * \endcode
1498  *
1499  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
1500  *
1501  * \since 1.6.3
1502  */
1503 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, int format);
1504
1505 /*!
1506  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
1507  *
1508  * \param chan Our own Asterisk channel
1509  * \param instance The first RTP instance
1510  * \param peer The peer Asterisk channel
1511  *
1512  * \retval 0 success
1513  * \retval -1 failure
1514  *
1515  * Example usage:
1516  *
1517  * \code
1518  * ast_rtp_instance_make_compatible(instance, peer);
1519  * \endcode
1520  *
1521  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
1522  *
1523  * \since 1.6.3
1524  */
1525 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
1526
1527 /*! \brief Request the formats that can be transcoded
1528  *
1529  * \param instance The RTP instance
1530  * \param to_endpoint Formats being sent/received towards the endpoint
1531  * \param to_asterisk Formats being sent/received towards Asterisk
1532  *
1533  * \retval supported formats
1534  *
1535  * Example usage:
1536  *
1537  * \code
1538  * ast_rtp_instance_available_formats(instance, AST_FORMAT_ULAW, AST_FORMAT_SLINEAR);
1539  * \endcode
1540  *
1541  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
1542  *
1543  * \since 1.6.3
1544  */
1545 int ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, int to_endpoint, int to_asterisk);
1546
1547 /*!
1548  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
1549  *
1550  * \param instance The RTP instance
1551  *
1552  * \retval 0 success
1553  * \retval -1 failure
1554  *
1555  * Example usage:
1556  *
1557  * \code
1558  * ast_rtp_instance_activate(instance);
1559  * \endcode
1560  *
1561  * This tells the underlying RTP engine of instance that packets will now flow.
1562  *
1563  * \since 1.6.3
1564  */
1565 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
1566
1567 /*!
1568  * \brief Request that the underlying RTP engine send a STUN BIND request
1569  *
1570  * \param instance The RTP instance
1571  * \param suggestion The suggested destination
1572  * \param username Optionally a username for the request
1573  *
1574  * Example usage:
1575  *
1576  * \code
1577  * ast_rtp_instance_stun_request(instance, NULL, NULL);
1578  * \endcode
1579  *
1580  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
1581  * 'instance'.
1582  *
1583  * \since 1.6.3
1584  */
1585 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct sockaddr_in *suggestion, const char *username);
1586
1587 /*!
1588  * \brief Set the RTP timeout value
1589  *
1590  * \param instance The RTP instance
1591  * \param timeout Value to set the timeout to
1592  *
1593  * Example usage:
1594  *
1595  * \code
1596  * ast_rtp_instance_set_timeout(instance, 5000);
1597  * \endcode
1598  *
1599  * This sets the RTP timeout value on 'instance' to be 5000.
1600  *
1601  * \since 1.6.3
1602  */
1603 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
1604
1605 /*!
1606  * \brief Set the RTP timeout value for when the instance is on hold
1607  *
1608  * \param instance The RTP instance
1609  * \param timeout Value to set the timeout to
1610  *
1611  * Example usage:
1612  *
1613  * \code
1614  * ast_rtp_instance_set_hold_timeout(instance, 5000);
1615  * \endcode
1616  *
1617  * This sets the RTP hold timeout value on 'instance' to be 5000.
1618  *
1619  * \since 1.6.3
1620  */
1621 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
1622
1623 /*!
1624  * \brief Get the RTP timeout value
1625  *
1626  * \param instance The RTP instance
1627  *
1628  * \retval timeout value
1629  *
1630  * Example usage:
1631  *
1632  * \code
1633  * int timeout = ast_rtp_instance_get_timeout(instance);
1634  * \endcode
1635  *
1636  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
1637  *
1638  * \since 1.6.3
1639  */
1640 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
1641
1642 /*!
1643  * \brief Get the RTP timeout value for when an RTP instance is on hold
1644  *
1645  * \param instance The RTP instance
1646  *
1647  * \retval timeout value
1648  *
1649  * Example usage:
1650  *
1651  * \code
1652  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
1653  * \endcode
1654  *
1655  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
1656  *
1657  * \since 1.6.3
1658  */
1659 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
1660
1661 /*!
1662  * \brief Get the RTP engine in use on an RTP instance
1663  *
1664  * \param instance The RTP instance
1665  *
1666  * \retval pointer to the engine
1667  *
1668  * Example usage:
1669  *
1670  * \code
1671  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
1672  * \endcode
1673  *
1674  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
1675  *
1676  * \since 1.6.3
1677  */
1678 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
1679
1680 /*!
1681  * \brief Get the RTP glue in use on an RTP instance
1682  *
1683  * \param instance The RTP instance
1684  *
1685  * \retval pointer to the glue
1686  *
1687  * Example:
1688  *
1689  * \code
1690  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
1691  * \endcode
1692  *
1693  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
1694  *
1695  * \since 1.6.3
1696  */
1697 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
1698
1699 /*!
1700  * \brief Get the channel that is associated with an RTP instance while in a bridge
1701  *
1702  * \param instance The RTP instance
1703  *
1704  * \retval pointer to the channel
1705  *
1706  * Example:
1707  *
1708  * \code
1709  * struct ast_channel *chan = ast_rtp_instance_get_chan(instance);
1710  * \endcode
1711  *
1712  * This gets the channel associated with the RTP instance pointed to by 'instance'.
1713  *
1714  * \note This will only return a channel while in a local or remote bridge.
1715  *
1716  * \since 1.6.3
1717  */
1718 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance);
1719
1720 #if defined(__cplusplus) || defined(c_plusplus)
1721 }
1722 #endif
1723
1724 #endif /* _ASTERISK_RTP_ENGINE_H */