include/asterisk/rtp.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*!
  20  * \file rtp.h
  21  * \brief Supports RTP and RTCP with Symmetric RTP support for NAT traversal.
  22  *
  23  * RTP is defined in RFC 3550.
  24  */
  25
  26 #ifndef _ASTERISK_RTP_H
  27 #define _ASTERISK_RTP_H
  28
  29 #include "asterisk/network.h"
  30
  31 #include "asterisk/frame.h"
  32 #include "asterisk/io.h"
  33 #include "asterisk/sched.h"
  34 #include "asterisk/channel.h"
  35 #include "asterisk/linkedlists.h"
  36
  37 #if defined(__cplusplus) || defined(c_plusplus)
  38 extern "C" {
  39 #endif
  40
  41 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
  42 /*! DTMF (RFC2833) */
  43 #define AST_RTP_DTMF                    (1 << 0)
  44 /*! 'Comfort Noise' (RFC3389) */
  45 #define AST_RTP_CN                      (1 << 1)
  46 /*! DTMF (Cisco Proprietary) */
  47 #define AST_RTP_CISCO_DTMF              (1 << 2)
  48 /*! Maximum RTP-specific code */
  49 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
  50
  51 /*! Maxmum number of payload defintions for a RTP session */
  52 #define MAX_RTP_PT                      256
  53
  54 /*! T.140 Redundancy Maxium number of generations */
  55 #define RED_MAX_GENERATION 5
  56
  57 #define FLAG_3389_WARNING               (1 << 0)
  58
  59 enum ast_rtp_options {
  60         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
  61 };
  62
  63 enum ast_rtp_get_result {
  64         /*! Failed to find the RTP structure */
  65         AST_RTP_GET_FAILED = 0,
  66         /*! RTP structure exists but true native bridge can not occur so try partial */
  67         AST_RTP_TRY_PARTIAL,
  68         /*! RTP structure exists and native bridge can occur */
  69         AST_RTP_TRY_NATIVE,
  70 };
  71
  72 /*! \brief Variables used in ast_rtcp_get function */
  73 enum ast_rtp_qos_vars {
  74         AST_RTP_TXCOUNT,
  75         AST_RTP_RXCOUNT,
  76         AST_RTP_TXJITTER,
  77         AST_RTP_RXJITTER,
  78         AST_RTP_RXPLOSS,
  79         AST_RTP_TXPLOSS,
  80         AST_RTP_RTT
  81 };
  82
  83 struct ast_rtp;
  84 /*! T.140 Redundancy structure*/
  85 struct rtp_red;
  86
  87 /*! \brief The value of each payload format mapping: */
  88 struct rtpPayloadType {
  89         int isAstFormat;                /*!< whether the following code is an AST_FORMAT */
  90         int code;
  91 };
  92
  93 /*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem
  94 */
  95 struct ast_rtp_protocol {
  96         /*! Get RTP struct, or NULL if unwilling to transfer */
  97         enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
  98         /*! Get RTP struct, or NULL if unwilling to transfer */
  99         enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
 100         /*! Get RTP struct, or NULL if unwilling to transfer */
 101         enum ast_rtp_get_result (* const get_trtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
 102         /*! Set RTP peer */
 103         int (* const set_rtp_peer)(struct ast_channel *chan, struct ast_rtp *peer, struct ast_rtp *vpeer, struct ast_rtp *tpeer, int codecs, int nat_active);
 104         int (* const get_codec)(struct ast_channel *chan);
 105         const char * const type;
 106         AST_LIST_ENTRY(ast_rtp_protocol) list;
 107 };
 108
 109 enum ast_rtp_quality_type {
 110         RTPQOS_SUMMARY = 0,
 111         RTPQOS_JITTER,
 112         RTPQOS_LOSS,
 113         RTPQOS_RTT
 114 };
 115
 116 /*! \brief RTCP quality report storage */
 117 struct ast_rtp_quality {
 118         unsigned int local_ssrc;          /*!< Our SSRC */
 119         unsigned int local_lostpackets;   /*!< Our lost packets */
 120         double       local_jitter;        /*!< Our calculated jitter */
 121         unsigned int local_count;         /*!< Number of received packets */
 122         unsigned int remote_ssrc;         /*!< Their SSRC */
 123         unsigned int remote_lostpackets;  /*!< Their lost packets */
 124         double       remote_jitter;       /*!< Their reported jitter */
 125         unsigned int remote_count;        /*!< Number of transmitted packets */
 126         double       rtt;                 /*!< Round trip time */
 127 };
 128
 129 /*! RTP callback structure */
 130 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
 131
 132 /*!
 133  * \brief Get the amount of space required to hold an RTP session
 134  * \return number of bytes required
 135  */
 136 size_t ast_rtp_alloc_size(void);
 137
 138 /*!
 139  * \brief Initializate a RTP session.
 140  *
 141  * \param sched
 142  * \param io
 143  * \param rtcpenable
 144  * \param callbackmode
 145  * \return A representation (structure) of an RTP session.
 146  */
 147 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
 148
 149 /*!
 150  * \brief Initializate a RTP session using an in_addr structure.
 151  *
 152  * This fuction gets called by ast_rtp_new().
 153  *
 154  * \param sched
 155  * \param io
 156  * \param rtcpenable
 157  * \param callbackmode
 158  * \param in
 159  * \return A representation (structure) of an RTP session.
 160  */
 161 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
 162
 163 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
 164
 165 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
 166 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
 167
 168 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
 169
 170 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
 171
 172 /*! Destroy RTP session */
 173 void ast_rtp_destroy(struct ast_rtp *rtp);
 174
 175 void ast_rtp_reset(struct ast_rtp *rtp);
 176
 177 /*! Stop RTP session, do not destroy structure */
 178 void ast_rtp_stop(struct ast_rtp *rtp);
 179
 180 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
 181
 182 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
 183
 184 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
 185
 186 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
 187
 188 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
 189
 190 int ast_rtp_fd(struct ast_rtp *rtp);
 191
 192 int ast_rtcp_fd(struct ast_rtp *rtp);
 193
 194 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
 195
 196 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
 197
 198 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
 199
 200 int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int cos, char *desc);
 201
 202 void ast_rtp_new_source(struct ast_rtp *rtp);
 203
 204 /*! \brief  Setting RTP payload types from lines in a SDP description: */
 205 void ast_rtp_pt_clear(struct ast_rtp* rtp);
 206 /*! \brief Set payload types to defaults */
 207 void ast_rtp_pt_default(struct ast_rtp* rtp);
 208
 209 /*! \brief Copy payload types between RTP structures */
 210 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
 211
 212 /*! \brief Activate payload type */
 213 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
 214
 215 /*! \brief clear payload type */
 216 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
 217
 218 /*! \brief Set payload type to a known MIME media type for a codec
 219  *
 220  * \param rtp RTP structure to modify
 221  * \param pt Payload type entry to modify
 222  * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
 223  * \param mimeSubtype MIME subtype of media stream (typically a codec name)
 224  * \param options Zero or more flags from the ast_rtp_options enum
 225  *
 226  * This function 'fills in' an entry in the list of possible formats for
 227  * a media stream associated with an RTP structure.
 228  *
 229  * \retval 0 on success
 230  * \retval -1 if the payload type is out of range
 231  * \retval -2 if the mimeType/mimeSubtype combination was not found
 232  */
 233 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
 234                              char *mimeType, char *mimeSubtype,
 235                              enum ast_rtp_options options);
 236
 237 /*! \brief Set payload type to a known MIME media type for a codec with a specific sample rate
 238  *
 239  * \param rtp RTP structure to modify
 240  * \param pt Payload type entry to modify
 241  * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
 242  * \param mimeSubtype MIME subtype of media stream (typically a codec name)
 243  * \param options Zero or more flags from the ast_rtp_options enum
 244  * \param sample_rate The sample rate of the media stream
 245  *
 246  * This function 'fills in' an entry in the list of possible formats for
 247  * a media stream associated with an RTP structure.
 248  *
 249  * \retval 0 on success
 250  * \retval -1 if the payload type is out of range
 251  * \retval -2 if the mimeType/mimeSubtype combination was not found
 252  */
 253 int ast_rtp_set_rtpmap_type_rate(struct ast_rtp* rtp, int pt,
 254                                  char *mimeType, char *mimeSubtype,
 255                                  enum ast_rtp_options options,
 256                                  unsigned int sample_rate);
 257
 258 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
 259 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
 260 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
 261
 262 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
 263                                  int* astFormats, int* nonAstFormats);
 264
 265 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
 266 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
 267                                         enum ast_rtp_options options);
 268
 269 /*! \brief Get the sample rate associated with known RTP payload types
 270  *
 271  * \param isAstFormat True if the value in the 'code' parameter is an AST_FORMAT value
 272  * \param code Format code, either from AST_FORMAT list or from AST_RTP list
 273  *
 274  * \return the sample rate if the format was found, zero if it was not found
 275  */
 276 unsigned int ast_rtp_lookup_sample_rate(int isAstFormat, int code);
 277
 278 /*! \brief Build a string of MIME subtype names from a capability list */
 279 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
 280                                    const int isAstFormat, enum ast_rtp_options options);
 281
 282 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
 283
 284 int ast_rtp_getnat(struct ast_rtp *rtp);
 285
 286 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
 287 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
 288
 289 /*! \brief Compensate for devices that send RFC2833 packets all at once */
 290 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
 291
 292 /*! \brief Enable STUN capability */
 293 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
 294
 295 /*! \brief Generic STUN request
 296  * send a generic stun request to the server specified.
 297  * \param s the socket used to send the request
 298  * \param dst the address of the STUN server
 299  * \param username if non null, add the username in the request
 300  * \param answer if non null, the function waits for a response and
 301  *    puts here the externally visible address.
 302  * \return 0 on success, other values on error.
 303  * The interface it may change in the future.
 304  */
 305 int ast_stun_request(int s, struct sockaddr_in *dst,
 306         const char *username, struct sockaddr_in *answer);
 307
 308 /*! \brief Send STUN request for an RTP socket
 309  * Deprecated, this is just a wrapper for ast_rtp_stun_request()
 310  */
 311 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
 312
 313 /*! \brief The RTP bridge.
 314         \arg \ref AstRTPbridge
 315 */
 316 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
 317
 318 /*! \brief Register an RTP channel client */
 319 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
 320
 321 /*! \brief Unregister an RTP channel client */
 322 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
 323
 324 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
 325
 326 /*! \brief If possible, create an early bridge directly between the devices without
 327            having to send a re-invite later */
 328 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
 329
 330 /*! \brief Get QOS stats on a RTP channel
 331  * \since 1.6.1
 332  */
 333 int ast_rtp_get_qos(struct ast_rtp *rtp, const char *qos, char *buf, unsigned int buflen);
 334
 335 /*! \brief Return RTP and RTCP QoS values
 336  * \since 1.6.1
 337  */
 338 unsigned int ast_rtp_get_qosvalue(struct ast_rtp *rtp, enum ast_rtp_qos_vars value);
 339
 340 /*! \brief Set RTPAUDIOQOS(...) variables on a channel when it is being hung up
 341  * \since 1.6.1
 342  */
 343 void ast_rtp_set_vars(struct ast_channel *chan, struct ast_rtp *rtp);
 344
 345 /*! \brief Return RTCP quality string
 346  *
 347  *  \param rtp An rtp structure to get qos information about.
 348  *
 349  *  \param qual An (optional) rtp quality structure that will be
 350  *              filled with the quality information described in
 351  *              the ast_rtp_quality structure. This structure is
 352  *              not dependent on any qtype, so a call for any
 353  *              type of information would yield the same results
 354  *              because ast_rtp_quality is not a data type
 355  *              specific to any qos type.
 356  *
 357  *  \param qtype The quality type you'd like, default should be
 358  *               RTPQOS_SUMMARY which returns basic information
 359  *               about the call. The return from RTPQOS_SUMMARY
 360  *               is basically ast_rtp_quality in a string. The
 361  *               other types are RTPQOS_JITTER, RTPQOS_LOSS and
 362  *               RTPQOS_RTT which will return more specific
 363  *               statistics.
 364  * \version 1.6.1 added qtype parameter
 365  */
 366 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual, enum ast_rtp_quality_type qtype);
 367 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
 368 int ast_rtcp_send_h261fur(void *data);
 369
 370 void ast_rtp_init(void);                                      /*! Initialize RTP subsystem */
 371 int ast_rtp_reload(void);                                     /*! reload rtp configuration */
 372 void ast_rtp_new_init(struct ast_rtp *rtp);
 373
 374 /*! \brief Set codec preference */
 375 void ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
 376
 377 /*! \brief Get codec preference */
 378 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
 379
 380 /*! \brief get format from predefined dynamic payload format */
 381 int ast_rtp_codec_getformat(int pt);
 382
 383 /*! \brief Set rtp timeout */
 384 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
 385 /*! \brief Set rtp hold timeout */
 386 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
 387 /*! \brief set RTP keepalive interval */
 388 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
 389 /*! \brief Get RTP keepalive interval */
 390 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
 391 /*! \brief Get rtp hold timeout */
 392 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
 393 /*! \brief Get rtp timeout */
 394 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
 395 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
 396 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
 397
 398 /*! \brief Initalize t.140 redudancy
 399  * \param ti time between each t140red frame is sent
 400  * \param red_pt payloadtype for RTP packet
 401  * \param pt payloadtype numbers for each generation including primary data
 402  * \param num_gen number of redundant generations, primary data excluded
 403  * \since 1.6.1
 404  */
 405 int rtp_red_init(struct ast_rtp *rtp, int ti, int *pt, int num_gen);
 406
 407 /*! \brief Buffer t.140 data */
 408 void red_buffer_t140(struct ast_rtp *rtp, struct ast_frame *f);
 409
 410
 411
 412 #if defined(__cplusplus) || defined(c_plusplus)
 413 }
 414 #endif
 415
 416 #endif /* _ASTERISK_RTP_H */