chan_sip: fix problem directmediapermit/deny uses the wrong address
[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         /*! If asterisk_format is set, this is the internal
231          * asterisk format represented by the payload */
232         struct ast_format format;
233         /*! Actual internal RTP specific value of the payload */
234         int rtp_code;
235
236 };
237
238 /*! Structure that represents statistics from an RTP instance */
239 struct ast_rtp_instance_stats {
240         /*! Number of packets transmitted */
241         unsigned int txcount;
242         /*! Number of packets received */
243         unsigned int rxcount;
244         /*! Jitter on transmitted packets */
245         double txjitter;
246         /*! Jitter on received packets */
247         double rxjitter;
248         /*! Maximum jitter on remote side */
249         double remote_maxjitter;
250         /*! Minimum jitter on remote side */
251         double remote_minjitter;
252         /*! Average jitter on remote side */
253         double remote_normdevjitter;
254         /*! Standard deviation jitter on remote side */
255         double remote_stdevjitter;
256         /*! Maximum jitter on local side */
257         double local_maxjitter;
258         /*! Minimum jitter on local side */
259         double local_minjitter;
260         /*! Average jitter on local side */
261         double local_normdevjitter;
262         /*! Standard deviation jitter on local side */
263         double local_stdevjitter;
264         /*! Number of transmitted packets lost */
265         unsigned int txploss;
266         /*! Number of received packets lost */
267         unsigned int rxploss;
268         /*! Maximum number of packets lost on remote side */
269         double remote_maxrxploss;
270         /*! Minimum number of packets lost on remote side */
271         double remote_minrxploss;
272         /*! Average number of packets lost on remote side */
273         double remote_normdevrxploss;
274         /*! Standard deviation packets lost on remote side */
275         double remote_stdevrxploss;
276         /*! Maximum number of packets lost on local side */
277         double local_maxrxploss;
278         /*! Minimum number of packets lost on local side */
279         double local_minrxploss;
280         /*! Average number of packets lost on local side */
281         double local_normdevrxploss;
282         /*! Standard deviation packets lost on local side */
283         double local_stdevrxploss;
284         /*! Total round trip time */
285         double rtt;
286         /*! Maximum round trip time */
287         double maxrtt;
288         /*! Minimum round trip time */
289         double minrtt;
290         /*! Average round trip time */
291         double normdevrtt;
292         /*! Standard deviation round trip time */
293         double stdevrtt;
294         /*! Our SSRC */
295         unsigned int local_ssrc;
296         /*! Their SSRC */
297         unsigned int remote_ssrc;
298 };
299
300 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
301 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
302 placement = value; \
303 if (stat == current_stat) { \
304 return 0; \
305 } \
306 }
307
308 #define AST_RTP_STAT_TERMINATOR(combined) \
309 if (stat == combined) { \
310 return 0; \
311 }
312
313 /*! Structure that represents an RTP stack (engine) */
314 struct ast_rtp_engine {
315         /*! Name of the RTP engine, used when explicitly requested */
316         const char *name;
317         /*! Module this RTP engine came from, used for reference counting */
318         struct ast_module *mod;
319         /*! Callback for setting up a new RTP instance */
320         int (*new)(struct ast_rtp_instance *instance, struct ast_sched_context *sched, struct ast_sockaddr *sa, void *data);
321         /*! Callback for destroying an RTP instance */
322         int (*destroy)(struct ast_rtp_instance *instance);
323         /*! Callback for writing out a frame */
324         int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
325         /*! Callback for stopping the RTP instance */
326         void (*stop)(struct ast_rtp_instance *instance);
327         /*! Callback for starting RFC2833 DTMF transmission */
328         int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
329         /*! Callback for stopping RFC2833 DTMF transmission */
330         int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
331         int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
332         /*! Callback to indicate that we should update the marker bit */
333         void (*update_source)(struct ast_rtp_instance *instance);
334         /*! Callback to indicate that we should update the marker bit and ssrc */
335         void (*change_source)(struct ast_rtp_instance *instance);
336         /*! Callback for setting an extended RTP property */
337         int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
338         /*! Callback for getting an extended RTP property */
339         void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
340         /*! Callback for setting an RTP property */
341         void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
342         /*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
343         void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
344         /*! Callback for setting packetization preferences */
345         void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
346         /*! Callback for setting the remote address that RTP is to be sent to */
347         void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
348         /*! Callback for setting an alternate remote address */
349         void (*alt_remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
350         /*! Callback for changing DTMF mode */
351         int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
352         /*! Callback for getting DTMF mode */
353         enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
354         /*! Callback for retrieving statistics */
355         int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
356         /*! Callback for setting QoS values */
357         int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
358         /*! Callback for retrieving a file descriptor to poll on, not always required */
359         int (*fd)(struct ast_rtp_instance *instance, int rtcp);
360         /*! Callback for initializing RED support */
361         int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
362         /*! Callback for buffering a frame using RED */
363         int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
364         /*! Callback for reading a frame from the RTP engine */
365         struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
366         /*! Callback to locally bridge two RTP instances */
367         int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
368         /*! Callback to set the read format */
369         int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
370         /*! Callback to set the write format */
371         int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
372         /*! Callback to make two instances compatible */
373         int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
374         /*! Callback to see if two instances are compatible with DTMF */
375         int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
376         /*! Callback to indicate that packets will now flow */
377         int (*activate)(struct ast_rtp_instance *instance);
378         /*! Callback to request that the RTP engine send a STUN BIND request */
379         void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
380         /*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
381         void (*available_formats)(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
382         /*! Callback to send CNG */
383         int (*sendcng)(struct ast_rtp_instance *instance, int level);
384         /*! Linked list information */
385         AST_RWLIST_ENTRY(ast_rtp_engine) entry;
386 };
387
388 /*! Structure that represents codec and packetization information */
389 struct ast_rtp_codecs {
390         /*! Codec packetization preferences */
391         struct ast_codec_pref pref;
392         /*! Payloads present */
393         struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT];
394 };
395
396 /*! Structure that represents the glue that binds an RTP instance to a channel */
397 struct ast_rtp_glue {
398         /*! Name of the channel driver that this glue is responsible for */
399         const char *type;
400         /*! Module that the RTP glue came from */
401         struct ast_module *mod;
402         /*!
403          * \brief Callback for retrieving the RTP instance carrying audio
404          * \note This function increases the reference count on the returned RTP instance.
405          */
406         enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
407         /*!
408          * \brief Used to prevent two channels from remotely bridging audio rtp if the channel tech has a
409          *        reason for prohibiting it based on qualities that need to be compared from both channels.
410          * \note This function should only be called with two channels of the same technology
411          * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, function this is not used.
412          */
413         int (*allow_rtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
414         /*!
415          * \brief Callback for retrieving the RTP instance carrying video
416          * \note This function increases the reference count on the returned RTP instance.
417          */
418         enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
419         /*!
420          * \brief Used to prevent two channels from remotely bridging video rtp if the channel tech has a
421          *        reason for prohibiting it based on qualities that need to be compared from both channels.
422          * \note This function should only be called with two channels of the same technology
423          * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, this function is not used.
424          */
425         int (*allow_vrtp_remote)(struct ast_channel *chan1, struct ast_channel *chan2);
426
427         /*!
428          * \brief Callback for retrieving the RTP instance carrying text
429          * \note This function increases the reference count on the returned RTP instance.
430          */
431         enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
432         /*! Callback for updating the destination that the remote side should send RTP to */
433         int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, const struct ast_format_cap *cap, int nat_active);
434         /*! Callback for retrieving codecs that the channel can do.  Result returned in result_cap*/
435         void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
436         /*! Linked list information */
437         AST_RWLIST_ENTRY(ast_rtp_glue) entry;
438 };
439
440 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
441
442 /*!
443  * \brief Register an RTP engine
444  *
445  * \param engine Structure of the RTP engine to register
446  * \param module Module that the RTP engine is part of
447  *
448  * \retval 0 success
449  * \retval -1 failure
450  *
451  * Example usage:
452  *
453  * \code
454  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
455  * \endcode
456  *
457  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
458  * associate a module with it.
459  *
460  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
461  *       associated with the RTP engine and use counting is performed.
462  *
463  * \since 1.8
464  */
465 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
466
467 /*!
468  * \brief Unregister an RTP engine
469  *
470  * \param engine Structure of the RTP engine to unregister
471  *
472  * \retval 0 success
473  * \retval -1 failure
474  *
475  * Example usage:
476  *
477  * \code
478  * ast_rtp_engine_unregister(&example_rtp_engine);
479  * \endcode
480  *
481  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
482  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
483  *
484  * \since 1.8
485  */
486 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
487
488 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
489
490 void ast_rtp_engine_unregister_srtp(void);
491 int ast_rtp_engine_srtp_is_registered(void);
492
493 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
494
495 /*!
496  * \brief Register RTP glue
497  *
498  * \param glue The glue to register
499  * \param module Module that the RTP glue is part of
500  *
501  * \retval 0 success
502  * \retval -1 failure
503  *
504  * Example usage:
505  *
506  * \code
507  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
508  * \endcode
509  *
510  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
511  * associate a module with it.
512  *
513  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
514  *       associated with the RTP glue and use counting is performed.
515  *
516  * \since 1.8
517  */
518 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
519
520 /*!
521  * \brief Unregister RTP glue
522  *
523  * \param glue The glue to unregister
524  *
525  * \retval 0 success
526  * \retval -1 failure
527  *
528  * Example usage:
529  *
530  * \code
531  * ast_rtp_glue_unregister(&example_rtp_glue);
532  * \endcode
533  *
534  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
535  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
536  *
537  * \since 1.8
538  */
539 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
540
541 /*!
542  * \brief Create a new RTP instance
543  *
544  * \param engine_name Name of the engine to use for the RTP instance
545  * \param sched Scheduler context that the RTP engine may want to use
546  * \param sa Address we want to bind to
547  * \param data Unique data for the engine
548  *
549  * \retval non-NULL success
550  * \retval NULL failure
551  *
552  * Example usage:
553  *
554  * \code
555  * struct ast_rtp_instance *instance = NULL;
556  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
557  * \endcode
558  *
559  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
560  * in the address structure.
561  *
562  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
563  *       another depending on it's own configuration.
564  *
565  * \since 1.8
566  */
567 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
568                 struct ast_sched_context *sched, const struct ast_sockaddr *sa,
569                 void *data);
570
571 /*!
572  * \brief Destroy an RTP instance
573  *
574  * \param instance The RTP instance to destroy
575  *
576  * \retval 0 success
577  * \retval -1 failure
578  *
579  * Example usage:
580  *
581  * \code
582  * ast_rtp_instance_destroy(instance);
583  * \endcode
584  *
585  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
586  * memory and may not be used again.
587  *
588  * \since 1.8
589  */
590 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
591
592 /*!
593  * \brief Set the data portion of an RTP instance
594  *
595  * \param instance The RTP instance to manipulate
596  * \param data Pointer to data
597  *
598  * Example usage:
599  *
600  * \code
601  * ast_rtp_instance_set_data(instance, blob);
602  * \endcode
603  *
604  * This sets the data pointer on the RTP instance pointed to by 'instance' to
605  * blob.
606  *
607  * \since 1.8
608  */
609 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
610
611 /*!
612  * \brief Get the data portion of an RTP instance
613  *
614  * \param instance The RTP instance we want the data portion from
615  *
616  * Example usage:
617  *
618  * \code
619  * struct *blob = ast_rtp_instance_get_data(instance);
620  ( \endcode
621  *
622  * This gets the data pointer on the RTP instance pointed to by 'instance'.
623  *
624  * \since 1.8
625  */
626 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
627
628 /*!
629  * \brief Send a frame out over RTP
630  *
631  * \param instance The RTP instance to send frame out on
632  * \param frame the frame to send out
633  *
634  * \retval 0 success
635  * \retval -1 failure
636  *
637  * Example usage:
638  *
639  * \code
640  * ast_rtp_instance_write(instance, frame);
641  * \endcode
642  *
643  * This gives the frame pointed to by frame to the RTP engine being used for the instance
644  * and asks that it be transmitted to the current remote address set on the RTP instance.
645  *
646  * \since 1.8
647  */
648 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
649
650 /*!
651  * \brief Receive a frame over RTP
652  *
653  * \param instance The RTP instance to receive frame on
654  * \param rtcp Whether to read in RTCP or not
655  *
656  * \retval non-NULL success
657  * \retval NULL failure
658  *
659  * Example usage:
660  *
661  * \code
662  * struct ast_frame *frame;
663  * frame = ast_rtp_instance_read(instance, 0);
664  * \endcode
665  *
666  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
667  *
668  * \since 1.8
669  */
670 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
671
672 /*!
673  * \brief Set the address of the remote endpoint that we are sending RTP to
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_remote_address(instance, &sin);
685  * \endcode
686  *
687  * This changes the 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_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
693
694
695 /*!
696  * \brief Set the address of an an alternate RTP address to receive from
697  *
698  * \param instance The RTP instance to change the address on
699  * \param address Address to set it to
700  *
701  * \retval 0 success
702  * \retval -1 failure
703  *
704  * Example usage:
705  *
706  * \code
707  * ast_rtp_instance_set_alt_remote_address(instance, &address);
708  * \endcode
709  *
710  * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin
711  * structure.
712  *
713  * \since 1.8
714  */
715 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
716
717 /*!
718  * \brief Set the address that we are expecting to receive RTP on
719  *
720  * \param instance The RTP instance to change the address on
721  * \param address Address to set it to
722  *
723  * \retval 0 success
724  * \retval -1 failure
725  *
726  * Example usage:
727  *
728  * \code
729  * ast_rtp_instance_set_local_address(instance, &sin);
730  * \endcode
731  *
732  * This changes the local address that RTP is expected on to the address given in the sin
733  * structure.
734  *
735  * \since 1.8
736  */
737 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
738                 const struct ast_sockaddr *address);
739
740 /*!
741  * \brief Get the local address that we are expecting RTP on
742  *
743  * \param instance The RTP instance to get the address from
744  * \param address The variable to store the address in
745  *
746  * Example usage:
747  *
748  * \code
749  * struct ast_sockaddr address;
750  * ast_rtp_instance_get_local_address(instance, &address);
751  * \endcode
752  *
753  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
754  *
755  * \since 1.8
756  */
757 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
758
759 /*!
760  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
761  *
762  * \param instance The instance that we want to get the local address for
763  * \param address An initialized address that may be overwritten if the local address is different
764  *
765  * \retval 0 address was not changed
766  * \retval 1 address was changed
767  * Example usage:
768  *
769  * \code
770  * struct ast_sockaddr address;
771  * int ret;
772  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
773  * \endcode
774  *
775  * This retrieves the current local address set on the instance pointed to by instance and puts the value
776  * into the address structure.
777  *
778  * \since 1.8
779  */
780 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
781
782 /*!
783  * \brief Get the address of the remote endpoint that we are sending RTP to
784  *
785  * \param instance The instance that we want to get the remote address for
786  * \param address A structure to put the address into
787  *
788  * Example usage:
789  *
790  * \code
791  * struct ast_sockaddr address;
792  * ast_rtp_instance_get_remote_address(instance, &address);
793  * \endcode
794  *
795  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
796  * into the address structure.
797  *
798  * \since 1.8
799  */
800 void ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
801
802 /*!
803  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
804  *
805  * \param instance The instance that we want to get the remote address for
806  * \param address An initialized address that may be overwritten if the remote address is different
807  *
808  * \retval 0 address was not changed
809  * \retval 1 address was changed
810  * Example usage:
811  *
812  * \code
813  * struct ast_sockaddr address;
814  * int ret;
815  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
816  * \endcode
817  *
818  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
819  * into the address structure.
820  *
821  * \since 1.8
822  */
823
824 int ast_rtp_instance_get_and_cmp_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
825
826 /*!
827  * \brief Set the value of an RTP instance extended property
828  *
829  * \param instance The RTP instance to set the extended property on
830  * \param property The extended property to set
831  * \param value The value to set the extended property to
832  *
833  * \since 1.8
834  */
835 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
836
837 /*!
838  * \brief Get the value of an RTP instance extended property
839  *
840  * \param instance The RTP instance to get the extended property on
841  * \param property The extended property to get
842  *
843  * \since 1.8
844  */
845 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
846
847 /*!
848  * \brief Set the value of an RTP instance property
849  *
850  * \param instance The RTP instance to set the property on
851  * \param property The property to modify
852  * \param value The value to set the property to
853  *
854  * Example usage:
855  *
856  * \code
857  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
858  * \endcode
859  *
860  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
861  *
862  * \since 1.8
863  */
864 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
865
866 /*!
867  * \brief Get the value of an RTP instance property
868  *
869  * \param instance The RTP instance to get the property from
870  * \param property The property to get
871  *
872  * \retval Current value of the property
873  *
874  * Example usage:
875  *
876  * \code
877  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
878  * \endcode
879  *
880  * This returns the current value of the NAT property on the instance pointed to by instance.
881  *
882  * \since 1.8
883  */
884 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
885
886 /*!
887  * \brief Get the codecs structure of an RTP instance
888  *
889  * \param instance The RTP instance to get the codecs structure from
890  *
891  * Example usage:
892  *
893  * \code
894  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
895  * \endcode
896  *
897  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
898  *
899  * \since 1.8
900  */
901 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
902
903 /*!
904  * \brief Clear payload information from an RTP instance
905  *
906  * \param codecs The codecs structure that payloads will be cleared from
907  * \param instance Optionally the instance that the codecs structure belongs to
908  *
909  * Example usage:
910  *
911  * \code
912  * struct ast_rtp_codecs codecs;
913  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
914  * \endcode
915  *
916  * This clears the codecs structure and puts it into a pristine state.
917  *
918  * \since 1.8
919  */
920 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
921
922 /*!
923  * \brief Set payload information on an RTP instance to the default
924  *
925  * \param codecs The codecs structure to set defaults on
926  * \param instance Optionally the instance that the codecs structure belongs to
927  *
928  * Example usage:
929  *
930  * \code
931  * struct ast_rtp_codecs codecs;
932  * ast_rtp_codecs_payloads_default(&codecs, NULL);
933  * \endcode
934  *
935  * This sets the default payloads on the codecs structure.
936  *
937  * \since 1.8
938  */
939 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
940
941 /*!
942  * \brief Copy payload information from one RTP instance to another
943  *
944  * \param src The source codecs structure
945  * \param dest The destination codecs structure that the values from src will be copied to
946  * \param instance Optionally the instance that the dst codecs structure belongs to
947  *
948  * Example usage:
949  *
950  * \code
951  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
952  * \endcode
953  *
954  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
955  *
956  * \since 1.8
957  */
958 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
959
960 /*!
961  * \brief Record payload information that was seen in an m= SDP line
962  *
963  * \param codecs The codecs structure to muck with
964  * \param instance Optionally the instance that the codecs structure belongs to
965  * \param payload Numerical payload that was seen in the m= SDP line
966  *
967  * Example usage:
968  *
969  * \code
970  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
971  * \endcode
972  *
973  * This records that the numerical payload '0' was seen in the codecs structure.
974  *
975  * \since 1.8
976  */
977 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
978
979 /*!
980  * \brief Record payload information that was seen in an a=rtpmap: SDP line
981  *
982  * \param codecs The codecs structure to muck with
983  * \param instance Optionally the instance that the codecs structure belongs to
984  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
985  * \param mimetype The string mime type that was seen
986  * \param mimesubtype The strin mime sub type that was seen
987  * \param options Optional options that may change the behavior of this specific payload
988  *
989  * \retval 0 success
990  * \retval -1 failure, invalid payload numbe
991  * \retval -2 failure, unknown mimetype
992  *
993  * Example usage:
994  *
995  * \code
996  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
997  * \endcode
998  *
999  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
1000  *
1001  * \since 1.8
1002  */
1003 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);
1004
1005 /*!
1006  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
1007  *
1008  * \param codecs RTP structure to modify
1009  * \param instance Optionally the instance that the codecs structure belongs to
1010  * \param pt Payload type entry to modify
1011  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
1012  * \param mimesubtype MIME subtype of media stream (typically a codec name)
1013  * \param options Zero or more flags from the ast_rtp_options enum
1014  * \param sample_rate The sample rate of the media stream
1015  *
1016  * This function 'fills in' an entry in the list of possible formats for
1017  * a media stream associated with an RTP structure.
1018  *
1019  * \retval 0 on success
1020  * \retval -1 if the payload type is out of range
1021  * \retval -2 if the mimeType/mimeSubtype combination was not found
1022  *
1023  * \since 1.8
1024  */
1025 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
1026                                   char *mimetype, char *mimesubtype,
1027                                   enum ast_rtp_options options,
1028                                   unsigned int sample_rate);
1029
1030 /*!
1031  * \brief Remove payload information
1032  *
1033  * \param codecs The codecs structure to muck with
1034  * \param instance Optionally the instance that the codecs structure belongs to
1035  * \param payload Numerical payload to unset
1036  *
1037  * Example usage:
1038  *
1039  * \code
1040  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
1041  * \endcode
1042  *
1043  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
1044  *
1045  * \since 1.8
1046  */
1047 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
1048
1049 /*!
1050  * \brief Retrieve payload information by payload
1051  *
1052  * \param codecs Codecs structure to look in
1053  * \param payload Numerical payload to look up
1054  *
1055  * \retval Payload information
1056  *
1057  * Example usage:
1058  *
1059  * \code
1060  * struct ast_rtp_payload_type payload_type;
1061  * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
1062  * \endcode
1063  *
1064  * This looks up the information for payload '0' from the codecs structure.
1065  *
1066  * \since 1.8
1067  */
1068 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
1069
1070 /*!
1071  * \brief Retrieve the actual ast_format stored on the codecs structure for a specific payload
1072  *
1073  * \param codecs Codecs structure to look in
1074  * \param payload Numerical payload to look up
1075  *
1076  * \retval pointer to format structure on success
1077  * \retval NULL on failure
1078  *
1079  * \since 10.0
1080  */
1081 struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *codecs, int payload);
1082
1083 /*!
1084  * \brief Get the sample rate associated with known RTP payload types
1085  *
1086  * \param asterisk_format True if the value in format is to be used.
1087  * \param An asterisk format
1088  * \param code from AST_RTP list
1089  *
1090  * \return the sample rate if the format was found, zero if it was not found
1091  *
1092  * \since 1.8
1093  */
1094 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, struct ast_format *format, int code);
1095
1096 /*!
1097  * \brief Retrieve all formats that were found
1098  *
1099  * \param codecs Codecs structure to look in
1100  * \param astformats A capabilities structure to put the Asterisk formats in.
1101  * \param nonastformats An integer to put the non-Asterisk formats in
1102  *
1103  * Example usage:
1104  *
1105  * \code
1106  * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
1107  * int nonastformats;
1108  * ast_rtp_codecs_payload_formats(&codecs, &astformats, &nonastformats);
1109  * \endcode
1110  *
1111  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
1112  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
1113  *
1114  * \since 1.8
1115  */
1116 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
1117
1118 /*!
1119  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
1120  *
1121  * \param codecs Codecs structure to look in
1122  * \param asterisk_format Non-zero if the given Asterisk format is present
1123  * \param format Asterisk format to look for
1124  * \param code The format to look for
1125  *
1126  * \retval Numerical payload
1127  *
1128  * Example usage:
1129  *
1130  * \code
1131  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
1132  * \endcode
1133  *
1134  * This looks for the numerical payload for ULAW in the codecs structure.
1135  *
1136  * \since 1.8
1137  */
1138 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
1139
1140 /*!
1141  * \brief Retrieve mime subtype information on a payload
1142  *
1143  * \param asterisk_format Non-zero to look up using Asterisk format
1144  * \param format Asterisk format to look up
1145  * \param code RTP code to look up
1146  * \param options Additional options that may change the result
1147  *
1148  * \retval Mime subtype success
1149  * \retval NULL failure
1150  *
1151  * Example usage:
1152  *
1153  * \code
1154  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
1155  * \endcode
1156  *
1157  * This looks up the mime subtype for the ULAW format.
1158  *
1159  * \since 1.8
1160  */
1161 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, struct ast_format *format, int code, enum ast_rtp_options options);
1162
1163 /*!
1164  * \brief Convert formats into a string and put them into a buffer
1165  *
1166  * \param buf Buffer to put the mime output into
1167  * \param ast_format_capability Asterisk Formats we are looking up.
1168  * \param rtp_capability RTP codes that we are looking up
1169  * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
1170  * \param options Additional options that may change the result
1171  *
1172  * \retval non-NULL success
1173  * \retval NULL failure
1174  *
1175  * Example usage:
1176  *
1177  * \code
1178  * char buf[256] = "";
1179  * struct ast_format tmp_fmt;
1180  * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
1181  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1182  * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
1183  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
1184  * ast_format_cap_destroy(cap);
1185  * \endcode
1186  *
1187  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
1188  *
1189  * \since 1.8
1190  */
1191 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, struct ast_format_cap *ast_format_capability, int rtp_capability, const int asterisk_format, enum ast_rtp_options options);
1192
1193 /*!
1194  * \brief Set codec packetization preferences
1195  *
1196  * \param codecs Codecs structure to muck with
1197  * \param instance Optionally the instance that the codecs structure belongs to
1198  * \param prefs Codec packetization preferences
1199  *
1200  * Example usage:
1201  *
1202  * \code
1203  * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
1204  * \endcode
1205  *
1206  * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
1207  *
1208  * \since 1.8
1209  */
1210 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
1211
1212 /*!
1213  * \brief Begin sending a DTMF digit
1214  *
1215  * \param instance The RTP instance to send the DTMF on
1216  * \param digit What DTMF digit to send
1217  *
1218  * \retval 0 success
1219  * \retval -1 failure
1220  *
1221  * Example usage:
1222  *
1223  * \code
1224  * ast_rtp_instance_dtmf_begin(instance, '1');
1225  * \endcode
1226  *
1227  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
1228  * continue being sent until it is ended.
1229  *
1230  * \since 1.8
1231  */
1232 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
1233
1234 /*!
1235  * \brief Stop sending a DTMF digit
1236  *
1237  * \param instance The RTP instance to stop the DTMF on
1238  * \param digit What DTMF digit to stop
1239  *
1240  * \retval 0 success
1241  * \retval -1 failure
1242  *
1243  * Example usage:
1244  *
1245  * \code
1246  * ast_rtp_instance_dtmf_end(instance, '1');
1247  * \endcode
1248  *
1249  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
1250  *
1251  * \since 1.8
1252  */
1253 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
1254 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
1255
1256 /*!
1257  * \brief Set the DTMF mode that should be used
1258  *
1259  * \param instance the RTP instance to set DTMF mode on
1260  * \param dtmf_mode The DTMF mode that is in use
1261  *
1262  * \retval 0 success
1263  * \retval -1 failure
1264  *
1265  * Example usage:
1266  *
1267  * \code
1268  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
1269  * \endcode
1270  *
1271  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
1272  *
1273  * \since 1.8
1274  */
1275 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
1276
1277 /*!
1278  * \brief Get the DTMF mode of an RTP instance
1279  *
1280  * \param instance The RTP instance to get the DTMF mode of
1281  *
1282  * \retval DTMF mode
1283  *
1284  * Example usage:
1285  *
1286  * \code
1287  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
1288  * \endcode
1289  *
1290  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
1291  *
1292  * \since 1.8
1293  */
1294 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
1295
1296 /*!
1297  * \brief Indicate that the RTP marker bit should be set on an RTP stream
1298  *
1299  * \param instance Instance that the new media source is feeding into
1300  *
1301  * Example usage:
1302  *
1303  * \code
1304  * ast_rtp_instance_update_source(instance);
1305  * \endcode
1306  *
1307  * This indicates that the source of media that is feeding the instance pointed to by
1308  * instance has been updated and that the marker bit should be set.
1309  *
1310  * \since 1.8
1311  */
1312 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
1313
1314 /*!
1315  * \brief Indicate a new source of audio has dropped in and the ssrc should change
1316  *
1317  * \param instance Instance that the new media source is feeding into
1318  *
1319  * Example usage:
1320  *
1321  * \code
1322  * ast_rtp_instance_change_source(instance);
1323  * \endcode
1324  *
1325  * This indicates that the source of media that is feeding the instance pointed to by
1326  * instance has changed and that the marker bit should be set and the SSRC updated.
1327  *
1328  * \since 1.8
1329  */
1330 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
1331
1332 /*!
1333  * \brief Set QoS parameters on an RTP session
1334  *
1335  * \param instance Instance to set the QoS parameters on
1336  * \param tos Terms of service value
1337  * \param cos Class of service value
1338  * \param desc What is setting the QoS values
1339  *
1340  * \retval 0 success
1341  * \retval -1 failure
1342  *
1343  * Example usage:
1344  *
1345  * \code
1346  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
1347  * \endcode
1348  *
1349  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
1350  *
1351  * \since 1.8
1352  */
1353 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
1354
1355 /*!
1356  * \brief Stop an RTP instance
1357  *
1358  * \param instance Instance that media is no longer going to at this time
1359  *
1360  * Example usage:
1361  *
1362  * \code
1363  * ast_rtp_instance_stop(instance);
1364  * \endcode
1365  *
1366  * This tells the RTP engine being used for the instance pointed to by instance
1367  * that media is no longer going to it at this time, but may in the future.
1368  *
1369  * \since 1.8
1370  */
1371 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
1372
1373 /*!
1374  * \brief Get the file descriptor for an RTP session (or RTCP)
1375  *
1376  * \param instance Instance to get the file descriptor for
1377  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
1378  *
1379  * \retval fd success
1380  * \retval -1 failure
1381  *
1382  * Example usage:
1383  *
1384  * \code
1385  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
1386  * \endcode
1387  *
1388  * This retrieves the file descriptor for the socket carrying media on the instance
1389  * pointed to by instance.
1390  *
1391  * \since 1.8
1392  */
1393 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
1394
1395 /*!
1396  * \brief Get the RTP glue that binds a channel to the RTP engine
1397  *
1398  * \param type Name of the glue we want
1399  *
1400  * \retval non-NULL success
1401  * \retval NULL failure
1402  *
1403  * Example usage:
1404  *
1405  * \code
1406  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
1407  * \endcode
1408  *
1409  * This retrieves the RTP glue that has the name 'Example'.
1410  *
1411  * \since 1.8
1412  */
1413 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
1414
1415 /*!
1416  * \brief Bridge two channels that use RTP instances
1417  *
1418  * \param c0 First channel part of the bridge
1419  * \param c1 Second channel part of the bridge
1420  * \param flags Bridging flags
1421  * \param fo If a frame needs to be passed up it is stored here
1422  * \param rc Channel that passed the above frame up
1423  * \param timeoutms How long the channels should be bridged for
1424  *
1425  * \retval Bridge result
1426  *
1427  * \note This should only be used by channel drivers in their technology declaration.
1428  *
1429  * \since 1.8
1430  */
1431 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);
1432
1433 /*!
1434  * \brief Get the other RTP instance that an instance is bridged to
1435  *
1436  * \param instance The RTP instance that we want
1437  *
1438  * \retval non-NULL success
1439  * \retval NULL failure
1440  *
1441  * Example usage:
1442  *
1443  * \code
1444  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
1445  * \endcode
1446  *
1447  * This gets the RTP instance that instance0 is bridged to.
1448  *
1449  * \since 1.8
1450  */
1451 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
1452
1453 /*!
1454  * \brief Make two channels compatible for early bridging
1455  *
1456  * \param c0 First channel part of the bridge
1457  * \param c1 Second channel part of the bridge
1458  *
1459  * \since 1.8
1460  */
1461 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
1462
1463 /*!
1464  * \brief Early bridge two channels that use RTP instances
1465  *
1466  * \param c0 First channel part of the bridge
1467  * \param c1 Second channel part of the bridge
1468  *
1469  * \retval 0 success
1470  * \retval -1 failure
1471  *
1472  * \note This should only be used by channel drivers in their technology declaration.
1473  *
1474  * \since 1.8
1475  */
1476 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
1477
1478 /*!
1479  * \brief Initialize RED support on an RTP instance
1480  *
1481  * \param instance The instance to initialize RED support on
1482  * \param buffer_time How long to buffer before sending
1483  * \param payloads Payload values
1484  * \param generations Number of generations
1485  *
1486  * \retval 0 success
1487  * \retval -1 failure
1488  *
1489  * \since 1.8
1490  */
1491 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
1492
1493 /*!
1494  * \brief Buffer a frame in an RTP instance for RED
1495  *
1496  * \param instance The instance to buffer the frame on
1497  * \param frame Frame that we want to buffer
1498  *
1499  * \retval 0 success
1500  * \retval -1 failure
1501  *
1502  * \since 1.8
1503  */
1504 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
1505
1506 /*!
1507  * \brief Retrieve statistics about an RTP instance
1508  *
1509  * \param instance Instance to get statistics on
1510  * \param stats Structure to put results into
1511  * \param stat What statistic(s) to retrieve
1512  *
1513  * \retval 0 success
1514  * \retval -1 failure
1515  *
1516  * Example usage:
1517  *
1518  * \code
1519  * struct ast_rtp_instance_stats stats;
1520  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
1521  * \endcode
1522  *
1523  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
1524  * stats structure.
1525  *
1526  * \since 1.8
1527  */
1528 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
1529
1530 /*!
1531  * \brief Set standard statistics from an RTP instance on a channel
1532  *
1533  * \param chan Channel to set the statistics on
1534  * \param instance The RTP instance that statistics will be retrieved from
1535  *
1536  * Example usage:
1537  *
1538  * \code
1539  * ast_rtp_instance_set_stats_vars(chan, rtp);
1540  * \endcode
1541  *
1542  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
1543  * by chan.
1544  *
1545  * \since 1.8
1546  */
1547 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
1548
1549 /*!
1550  * \brief Retrieve quality statistics about an RTP instance
1551  *
1552  * \param instance Instance to get statistics on
1553  * \param field What quality statistic to retrieve
1554  * \param buf What buffer to put the result into
1555  * \param size Size of the above buffer
1556  *
1557  * \retval non-NULL success
1558  * \retval NULL failure
1559  *
1560  * Example usage:
1561  *
1562  * \code
1563  * char quality[AST_MAX_USER_FIELD];
1564  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
1565  * \endcode
1566  *
1567  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
1568  *
1569  * \since 1.8
1570  */
1571 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
1572
1573 /*!
1574  * \brief Request that the underlying RTP engine provide audio frames in a specific format
1575  *
1576  * \param instance The RTP instance to change read format on
1577  * \param format Format that frames are wanted in
1578  *
1579  * \retval 0 success
1580  * \retval -1 failure
1581  *
1582  * Example usage:
1583  *
1584  * \code
1585  * struct ast_format tmp_fmt;
1586  * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1587  * \endcode
1588  *
1589  * This requests that the RTP engine provide audio frames in the ULAW format.
1590  *
1591  * \since 1.8
1592  */
1593 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
1594
1595 /*!
1596  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
1597  *
1598  * \param instance The RTP instance to change write format on
1599  * \param format Format that frames will be provided in
1600  *
1601  * \retval 0 success
1602  * \retval -1 failure
1603  *
1604  * Example usage:
1605  *
1606  * \code
1607  * struct ast_format tmp_fmt;
1608  * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
1609  * \endcode
1610  *
1611  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
1612  *
1613  * \since 1.8
1614  */
1615 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
1616
1617 /*!
1618  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
1619  *
1620  * \param chan Our own Asterisk channel
1621  * \param instance The first RTP instance
1622  * \param peer The peer Asterisk channel
1623  *
1624  * \retval 0 success
1625  * \retval -1 failure
1626  *
1627  * Example usage:
1628  *
1629  * \code
1630  * ast_rtp_instance_make_compatible(instance, peer);
1631  * \endcode
1632  *
1633  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
1634  *
1635  * \since 1.8
1636  */
1637 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
1638
1639 /*! \brief Request the formats that can be transcoded
1640  *
1641  * \param instance The RTP instance
1642  * \param to_endpoint Formats being sent/received towards the endpoint
1643  * \param to_asterisk Formats being sent/received towards Asterisk
1644  * \param result capabilities structure to store and return supported formats in.
1645  *
1646  * Example usage:
1647  *
1648  * \code
1649  * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
1650  * \endcode
1651  *
1652  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
1653  *
1654  * \since 1.8
1655  */
1656 void ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
1657
1658 /*!
1659  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
1660  *
1661  * \param instance The RTP instance
1662  *
1663  * \retval 0 success
1664  * \retval -1 failure
1665  *
1666  * Example usage:
1667  *
1668  * \code
1669  * ast_rtp_instance_activate(instance);
1670  * \endcode
1671  *
1672  * This tells the underlying RTP engine of instance that packets will now flow.
1673  *
1674  * \since 1.8
1675  */
1676 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
1677
1678 /*!
1679  * \brief Request that the underlying RTP engine send a STUN BIND request
1680  *
1681  * \param instance The RTP instance
1682  * \param suggestion The suggested destination
1683  * \param username Optionally a username for the request
1684  *
1685  * Example usage:
1686  *
1687  * \code
1688  * ast_rtp_instance_stun_request(instance, NULL, NULL);
1689  * \endcode
1690  *
1691  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
1692  * 'instance'.
1693  *
1694  * \since 1.8
1695  */
1696 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
1697
1698 /*!
1699  * \brief Set the RTP timeout value
1700  *
1701  * \param instance The RTP instance
1702  * \param timeout Value to set the timeout to
1703  *
1704  * Example usage:
1705  *
1706  * \code
1707  * ast_rtp_instance_set_timeout(instance, 5000);
1708  * \endcode
1709  *
1710  * This sets the RTP timeout value on 'instance' to be 5000.
1711  *
1712  * \since 1.8
1713  */
1714 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
1715
1716 /*!
1717  * \brief Set the RTP timeout value for when the instance is on hold
1718  *
1719  * \param instance The RTP instance
1720  * \param timeout Value to set the timeout to
1721  *
1722  * Example usage:
1723  *
1724  * \code
1725  * ast_rtp_instance_set_hold_timeout(instance, 5000);
1726  * \endcode
1727  *
1728  * This sets the RTP hold timeout value on 'instance' to be 5000.
1729  *
1730  * \since 1.8
1731  */
1732 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
1733
1734 /*!
1735  * \brief Set the RTP keepalive interval
1736  *
1737  * \param instance The RTP instance
1738  * \param period Value to set the keepalive interval to
1739  *
1740  * Example usage:
1741  *
1742  * \code
1743  * ast_rtp_instance_set_keepalive(instance, 5000);
1744  * \endcode
1745  *
1746  * This sets the RTP keepalive interval on 'instance' to be 5000.
1747  *
1748  * \since 1.8
1749  */
1750 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
1751
1752 /*!
1753  * \brief Get the RTP timeout value
1754  *
1755  * \param instance The RTP instance
1756  *
1757  * \retval timeout value
1758  *
1759  * Example usage:
1760  *
1761  * \code
1762  * int timeout = ast_rtp_instance_get_timeout(instance);
1763  * \endcode
1764  *
1765  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
1766  *
1767  * \since 1.8
1768  */
1769 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
1770
1771 /*!
1772  * \brief Get the RTP timeout value for when an RTP instance is on hold
1773  *
1774  * \param instance The RTP instance
1775  *
1776  * \retval timeout value
1777  *
1778  * Example usage:
1779  *
1780  * \code
1781  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
1782  * \endcode
1783  *
1784  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
1785  *
1786  * \since 1.8
1787  */
1788 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
1789
1790 /*!
1791  * \brief Get the RTP keepalive interval
1792  *
1793  * \param instance The RTP instance
1794  *
1795  * \retval period Keepalive interval value
1796  *
1797  * Example usage:
1798  *
1799  * \code
1800  * int interval = ast_rtp_instance_get_keepalive(instance);
1801  * \endcode
1802  *
1803  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
1804  *
1805  * \since 1.8
1806  */
1807 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
1808
1809 /*!
1810  * \brief Get the RTP engine in use on an RTP instance
1811  *
1812  * \param instance The RTP instance
1813  *
1814  * \retval pointer to the engine
1815  *
1816  * Example usage:
1817  *
1818  * \code
1819  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
1820  * \endcode
1821  *
1822  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
1823  *
1824  * \since 1.8
1825  */
1826 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
1827
1828 /*!
1829  * \brief Get the RTP glue in use on an RTP instance
1830  *
1831  * \param instance The RTP instance
1832  *
1833  * \retval pointer to the glue
1834  *
1835  * Example:
1836  *
1837  * \code
1838  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
1839  * \endcode
1840  *
1841  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
1842  *
1843  * \since 1.8
1844  */
1845 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
1846
1847 /*!
1848  * \brief Get the channel that is associated with an RTP instance while in a bridge
1849  *
1850  * \param instance The RTP instance
1851  *
1852  * \retval pointer to the channel
1853  *
1854  * Example:
1855  *
1856  * \code
1857  * struct ast_channel *chan = ast_rtp_instance_get_chan(instance);
1858  * \endcode
1859  *
1860  * This gets the channel associated with the RTP instance pointed to by 'instance'.
1861  *
1862  * \note This will only return a channel while in a local or remote bridge.
1863  *
1864  * \since 1.8
1865  */
1866 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance);
1867
1868 /*!
1869  * \brief Send a comfort noise packet to the RTP instance
1870  *
1871  * \param instance The RTP instance
1872  * \param level Magnitude of the noise level
1873  *
1874  * \retval 0 Success
1875  * \retval non-zero Failure
1876  */
1877 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
1878
1879 /*!
1880  * \brief Add or replace the SRTP policies for the given RTP instance
1881  *
1882  * \param instance the RTP instance
1883  * \param remote_policy the remote endpoint's policy
1884  * \param local_policy our policy for this RTP instance's remote endpoint
1885  *
1886  * \retval 0 Success
1887  * \retval non-zero Failure
1888  */
1889 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy);
1890
1891 /*!
1892  * \brief Obtain the SRTP instance associated with an RTP instance
1893  *
1894  * \param instance the RTP instance
1895  * \retval the SRTP instance on success
1896  * \retval NULL if no SRTP instance exists
1897  */
1898 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance);
1899
1900 /*! \brief Custom formats declared in codecs.conf at startup must be communicated to the rtp_engine
1901  * so their mime type can payload number can be initialized. */
1902 int ast_rtp_engine_load_format(const struct ast_format *format);
1903
1904 /*! \brief Formats requiring the use of a format attribute interface must have that
1905  * interface registered in order for the rtp engine to handle it correctly.  If an
1906  * attribute interface is unloaded, this function must be called to notify the rtp_engine. */
1907 int ast_rtp_engine_unload_format(const struct ast_format *format);
1908
1909 #if defined(__cplusplus) || defined(c_plusplus)
1910 }
1911 #endif
1912
1913 #endif /* _ASTERISK_RTP_ENGINE_H */