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