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 <netinet/in.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 #define MAX_RTP_PT                      256
  52
  53 enum ast_rtp_options {
  54         AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
  55 };
  56
  57 enum ast_rtp_get_result {
  58         /*! Failed to find the RTP structure */
  59         AST_RTP_GET_FAILED = 0,
  60         /*! RTP structure exists but true native bridge can not occur so try partial */
  61         AST_RTP_TRY_PARTIAL,
  62         /*! RTP structure exists and native bridge can occur */
  63         AST_RTP_TRY_NATIVE,
  64 };
  65
  66 struct ast_rtp;
  67
  68 struct ast_rtp_protocol {
  69         /*! Get RTP struct, or NULL if unwilling to transfer */
  70         enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
  71         /*! Get RTP struct, or NULL if unwilling to transfer */
  72         enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
  73         /*! Set RTP peer */
  74         int (* const set_rtp_peer)(struct ast_channel *chan, struct ast_rtp *peer, struct ast_rtp *vpeer, int codecs, int nat_active);
  75         int (* const get_codec)(struct ast_channel *chan);
  76         const char * const type;
  77         AST_LIST_ENTRY(ast_rtp_protocol) list;
  78 };
  79
  80 struct ast_rtp_quality {
  81         unsigned int local_ssrc;          /* Our SSRC */
  82         unsigned int local_lostpackets;   /* Our lost packets */
  83         double       local_jitter;        /* Our calculated jitter */
  84         unsigned int local_count;         /* Number of received packets */
  85         unsigned int remote_ssrc;         /* Their SSRC */
  86         unsigned int remote_lostpackets;  /* Their lost packets */
  87         double       remote_jitter;       /* Their reported jitter */
  88         unsigned int remote_count;        /* Number of transmitted packets */
  89         double       rtt;                 /* Round trip time */
  90 };
  91
  92
  93 #define FLAG_3389_WARNING               (1 << 0)
  94
  95 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
  96
  97 /*!
  98  * \brief Get the amount of space required to hold an RTP session
  99  * \return number of bytes required
 100  */
 101 size_t ast_rtp_alloc_size(void);
 102
 103 /*!
 104  * \brief Initializate a RTP session.
 105  *
 106  * \param sched
 107  * \param io
 108  * \param rtcpenable
 109  * \param callbackmode
 110  * \returns A representation (structure) of an RTP session.
 111  */
 112 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
 113
 114 /*!
 115  * \brief Initializate a RTP session using an in_addr structure.
 116  *
 117  * This fuction gets called by ast_rtp_new().
 118  *
 119  * \param sched
 120  * \param io
 121  * \param rtcpenable
 122  * \param callbackmode
 123  * \param in
 124  * \returns A representation (structure) of an RTP session.
 125  */
 126 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
 127
 128 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
 129
 130 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
 131 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
 132
 133 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
 134
 135 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
 136
 137 void ast_rtp_destroy(struct ast_rtp *rtp);
 138
 139 void ast_rtp_reset(struct ast_rtp *rtp);
 140
 141 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
 142
 143 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
 144
 145 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
 146
 147 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
 148
 149 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
 150
 151 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
 152
 153 int ast_rtp_fd(struct ast_rtp *rtp);
 154
 155 int ast_rtcp_fd(struct ast_rtp *rtp);
 156
 157 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
 158
 159 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
 160
 161 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
 162
 163 int ast_rtp_settos(struct ast_rtp *rtp, int tos);
 164
 165 void ast_rtp_new_source(struct ast_rtp *rtp);
 166
 167 /*! \brief  Setting RTP payload types from lines in a SDP description: */
 168 void ast_rtp_pt_clear(struct ast_rtp* rtp);
 169 /*! \brief Set payload types to defaults */
 170 void ast_rtp_pt_default(struct ast_rtp* rtp);
 171
 172 /*! \brief Copy payload types between RTP structures */
 173 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
 174
 175 /*! \brief Activate payload type */
 176 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
 177
 178 /*! \brief clear payload type */
 179 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
 180
 181 /*! \brief Initiate payload type to a known MIME media type for a codec */
 182 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
 183                              char *mimeType, char *mimeSubtype,
 184                              enum ast_rtp_options options);
 185
 186 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
 187 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
 188 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
 189
 190 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
 191                              int* astFormats, int* nonAstFormats);
 192
 193 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
 194 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
 195                                         enum ast_rtp_options options);
 196
 197 /*! \brief Build a string of MIME subtype names from a capability list */
 198 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
 199                                    const int isAstFormat, enum ast_rtp_options options);
 200
 201 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
 202
 203 int ast_rtp_getnat(struct ast_rtp *rtp);
 204
 205 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
 206 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
 207
 208 /*! \brief Compensate for devices that send RFC2833 packets all at once */
 209 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
 210
 211 /*! \brief Enable STUN capability */
 212 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
 213
 214 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
 215
 216 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
 217
 218 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
 219
 220 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
 221
 222 /*! \brief If possible, create an early bridge directly between the devices without
 223            having to send a re-invite later */
 224 int ast_rtp_early_bridge(struct ast_channel *dest, struct ast_channel *src);
 225
 226 void ast_rtp_stop(struct ast_rtp *rtp);
 227
 228 /*! \brief Return RTCP quality string */
 229 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual);
 230
 231 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
 232 int ast_rtcp_send_h261fur(void *data);
 233
 234 void ast_rtp_new_init(struct ast_rtp *rtp);
 235
 236 void ast_rtp_init(void);
 237
 238 int ast_rtp_reload(void);
 239
 240 int ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
 241
 242 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
 243
 244 int ast_rtp_codec_getformat(int pt);
 245
 246 /*! \brief Set rtp timeout */
 247 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
 248 /*! \brief Set rtp hold timeout */
 249 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
 250 /*! \brief set RTP keepalive interval */
 251 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
 252 /*! \brief Get RTP keepalive interval */
 253 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
 254 /*! \brief Get rtp hold timeout */
 255 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
 256 /*! \brief Get rtp timeout */
 257 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
 258 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
 259 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
 260
 261 #if defined(__cplusplus) || defined(c_plusplus)
 262 }
 263 #endif
 264
 265 #endif /* _ASTERISK_RTP_H */