include/asterisk/rtp_engine.h

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