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