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