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