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