Sun Jun 12 16:37:48 2011

Asterisk developer's documentation


rtp.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file rtp.h
00021  * \brief Supports RTP and RTCP with Symmetric RTP support for NAT traversal.
00022  *
00023  * RTP is defined in RFC 3550.
00024  */
00025 
00026 #ifndef _ASTERISK_RTP_H
00027 #define _ASTERISK_RTP_H
00028 
00029 #include <netinet/in.h>
00030 
00031 #include "asterisk/frame.h"
00032 #include "asterisk/io.h"
00033 #include "asterisk/sched.h"
00034 #include "asterisk/channel.h"
00035 #include "asterisk/linkedlists.h"
00036 
00037 #if defined(__cplusplus) || defined(c_plusplus)
00038 extern "C" {
00039 #endif
00040 
00041 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
00042 /*! DTMF (RFC2833) */
00043 #define AST_RTP_DTMF             (1 << 0)
00044 /*! 'Comfort Noise' (RFC3389) */
00045 #define AST_RTP_CN               (1 << 1)
00046 /*! DTMF (Cisco Proprietary) */
00047 #define AST_RTP_CISCO_DTMF       (1 << 2)
00048 /*! Maximum RTP-specific code */
00049 #define AST_RTP_MAX              AST_RTP_CISCO_DTMF
00050 
00051 #define MAX_RTP_PT         256
00052 
00053 enum ast_rtp_options {
00054    AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
00055 };
00056 
00057 enum ast_rtp_get_result {
00058    /*! Failed to find the RTP structure */
00059    AST_RTP_GET_FAILED = 0,
00060    /*! RTP structure exists but true native bridge can not occur so try partial */
00061    AST_RTP_TRY_PARTIAL,
00062    /*! RTP structure exists and native bridge can occur */
00063    AST_RTP_TRY_NATIVE,
00064 };
00065 
00066 struct ast_rtp;
00067 
00068 struct ast_rtp_protocol {
00069    /*! Get RTP struct, or NULL if unwilling to transfer */
00070    enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00071    /*! Get RTP struct, or NULL if unwilling to transfer */
00072    enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00073    /*! Set RTP peer */
00074    int (* const set_rtp_peer)(struct ast_channel *chan, struct ast_rtp *peer, struct ast_rtp *vpeer, int codecs, int nat_active);
00075    int (* const get_codec)(struct ast_channel *chan);
00076    const char * const type;
00077    AST_LIST_ENTRY(ast_rtp_protocol) list;
00078 };
00079 
00080 struct ast_rtp_quality {
00081    unsigned int local_ssrc;          /* Our SSRC */
00082    unsigned int local_lostpackets;   /* Our lost packets */
00083    double       local_jitter;        /* Our calculated jitter */
00084    unsigned int local_count;         /* Number of received packets */
00085    unsigned int remote_ssrc;         /* Their SSRC */
00086    unsigned int remote_lostpackets;  /* Their lost packets */
00087    double       remote_jitter;       /* Their reported jitter */
00088    unsigned int remote_count;        /* Number of transmitted packets */
00089    double       rtt;                 /* Round trip time */
00090 };
00091 
00092 
00093 #define FLAG_3389_WARNING     (1 << 0)
00094 
00095 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
00096 
00097 /*!
00098  * \brief Get the amount of space required to hold an RTP session
00099  * \return number of bytes required
00100  */
00101 size_t ast_rtp_alloc_size(void);
00102 
00103 /*!
00104  * \brief Initializate a RTP session.
00105  *
00106  * \param sched
00107  * \param io
00108  * \param rtcpenable
00109  * \param callbackmode
00110  * \returns A representation (structure) of an RTP session.
00111  */
00112 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
00113 
00114 /*!
00115  * \brief Initializate a RTP session using an in_addr structure.
00116  *
00117  * This fuction gets called by ast_rtp_new().
00118  *
00119  * \param sched
00120  * \param io
00121  * \param rtcpenable
00122  * \param callbackmode
00123  * \param in
00124  * \returns A representation (structure) of an RTP session.
00125  */
00126 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
00127 
00128 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00129 
00130 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
00131 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00132 
00133 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
00134 
00135 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
00136 
00137 void ast_rtp_destroy(struct ast_rtp *rtp);
00138 
00139 void ast_rtp_reset(struct ast_rtp *rtp);
00140 
00141 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
00142 
00143 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
00144 
00145 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
00146 
00147 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
00148 
00149 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
00150 
00151 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
00152 
00153 int ast_rtp_fd(struct ast_rtp *rtp);
00154 
00155 int ast_rtcp_fd(struct ast_rtp *rtp);
00156 
00157 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
00158 
00159 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
00160 
00161 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
00162 
00163 int ast_rtp_settos(struct ast_rtp *rtp, int tos);
00164 
00165 void ast_rtp_update_source(struct ast_rtp *rtp);
00166 
00167 /*!
00168 * \brief Indicate a new source of audio has dropped in and the ssrc should change
00169 *
00170 * \param instance Instance that the new media source is feeding into
00171 *
00172 * Example usage:
00173 *
00174 * \code
00175 * ast_rtp_instance_change_source(instance);
00176 * \endcode
00177 *
00178 * This indicates that the source of media that is feeding the instance pointed to by
00179 * instance has changed and that the marker bit should be set and the SSRC updated.
00180 */
00181 void ast_rtp_change_source(struct ast_rtp *instance);
00182 
00183 /*! \brief  Setting RTP payload types from lines in a SDP description: */
00184 void ast_rtp_pt_clear(struct ast_rtp* rtp);
00185 /*! \brief Set payload types to defaults */
00186 void ast_rtp_pt_default(struct ast_rtp* rtp);
00187 
00188 /*! \brief Copy payload types between RTP structures */
00189 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
00190 
00191 /*! \brief Activate payload type */
00192 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
00193 
00194 /*! \brief clear payload type */
00195 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
00196 
00197 /*! \brief Initiate payload type to a known MIME media type for a codec */
00198 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
00199               char *mimeType, char *mimeSubtype,
00200               enum ast_rtp_options options);
00201 
00202 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
00203 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
00204 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
00205 
00206 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
00207               int* astFormats, int* nonAstFormats);
00208 
00209 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
00210 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
00211                enum ast_rtp_options options);
00212 
00213 /*! \brief Build a string of MIME subtype names from a capability list */
00214 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
00215                const int isAstFormat, enum ast_rtp_options options);
00216 
00217 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
00218 
00219 int ast_rtp_getnat(struct ast_rtp *rtp);
00220 
00221 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
00222 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
00223 
00224 /*! \brief Compensate for devices that send RFC2833 packets all at once */
00225 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
00226 
00227 /*! \brief Enable STUN capability */
00228 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
00229 
00230 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
00231 
00232 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
00233 
00234 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
00235 
00236 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
00237 
00238 /*! \brief If possible, create an early bridge directly between the devices without
00239            having to send a re-invite later */
00240 int ast_rtp_early_bridge(struct ast_channel *dest, struct ast_channel *src);
00241 
00242 void ast_rtp_stop(struct ast_rtp *rtp);
00243 
00244 /*! \brief Return RTCP quality string */
00245 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual);
00246 
00247 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
00248 int ast_rtcp_send_h261fur(void *data);
00249 
00250 void ast_rtp_new_init(struct ast_rtp *rtp);
00251 
00252 void ast_rtp_init(void);
00253 
00254 int ast_rtp_reload(void);
00255 
00256 int ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
00257 
00258 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
00259 
00260 int ast_rtp_codec_getformat(int pt);
00261 
00262 /*! \brief Set rtp timeout */
00263 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
00264 /*! \brief Set rtp hold timeout */
00265 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
00266 /*! \brief set RTP keepalive interval */
00267 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
00268 /*! \brief Get RTP keepalive interval */
00269 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
00270 /*! \brief Get rtp hold timeout */
00271 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
00272 /*! \brief Get rtp timeout */
00273 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
00274 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
00275 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
00276 
00277 #if defined(__cplusplus) || defined(c_plusplus)
00278 }
00279 #endif
00280 
00281 #endif /* _ASTERISK_RTP_H */

Generated on Sun Jun 12 16:37:48 2011 for Asterisk - the Open Source PBX by  doxygen 1.5.6