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