Thu Jul 9 13:40:40 2009

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 "asterisk/network.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 /*! Maxmum number of payload defintions for a RTP session */
00052 #define MAX_RTP_PT         256
00053 
00054 #define FLAG_3389_WARNING     (1 << 0)
00055 
00056 enum ast_rtp_options {
00057    AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
00058 };
00059 
00060 enum ast_rtp_get_result {
00061    /*! Failed to find the RTP structure */
00062    AST_RTP_GET_FAILED = 0,
00063    /*! RTP structure exists but true native bridge can not occur so try partial */
00064    AST_RTP_TRY_PARTIAL,
00065    /*! RTP structure exists and native bridge can occur */
00066    AST_RTP_TRY_NATIVE,
00067 };
00068 
00069 struct ast_rtp;
00070 
00071 /*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem 
00072 */
00073 struct ast_rtp_protocol {
00074    /*! Get RTP struct, or NULL if unwilling to transfer */
00075    enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00076    /*! Get RTP struct, or NULL if unwilling to transfer */
00077    enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00078    /*! Get RTP struct, or NULL if unwilling to transfer */
00079    enum ast_rtp_get_result (* const get_trtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00080    /*! Set RTP peer */
00081    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);
00082    int (* const get_codec)(struct ast_channel *chan);
00083    const char * const type;
00084    AST_LIST_ENTRY(ast_rtp_protocol) list;
00085 };
00086 
00087 /*! \brief RTCP quality report storage */
00088 struct ast_rtp_quality {
00089    unsigned int local_ssrc;          /*!< Our SSRC */
00090    unsigned int local_lostpackets;   /*!< Our lost packets */
00091    double       local_jitter;        /*!< Our calculated jitter */
00092    unsigned int local_count;         /*!< Number of received packets */
00093    unsigned int remote_ssrc;         /*!< Their SSRC */
00094    unsigned int remote_lostpackets;  /*!< Their lost packets */
00095    double       remote_jitter;       /*!< Their reported jitter */
00096    unsigned int remote_count;        /*!< Number of transmitted packets */
00097    double       rtt;                 /*!< Round trip time */
00098 };
00099 
00100 /*! RTP callback structure */
00101 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
00102 
00103 /*!
00104  * \brief Get the amount of space required to hold an RTP session
00105  * \return number of bytes required
00106  */
00107 size_t ast_rtp_alloc_size(void);
00108 
00109 /*!
00110  * \brief Initializate a RTP session.
00111  *
00112  * \param sched
00113  * \param io
00114  * \param rtcpenable
00115  * \param callbackmode
00116  * \returns A representation (structure) of an RTP session.
00117  */
00118 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
00119 
00120 /*!
00121  * \brief Initializate a RTP session using an in_addr structure.
00122  *
00123  * This fuction gets called by ast_rtp_new().
00124  *
00125  * \param sched
00126  * \param io
00127  * \param rtcpenable
00128  * \param callbackmode
00129  * \param in
00130  * \returns A representation (structure) of an RTP session.
00131  */
00132 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
00133 
00134 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00135 
00136 /*! 
00137  * \since 1.4.26
00138  * \brief set potential alternate source for RTP media
00139  *
00140  * This function may be used to give the RTP stack a hint that there is a potential
00141  * second source of media. One case where this is used is when the SIP stack receives
00142  * a REINVITE to which it will be replying with a 491. In such a scenario, the IP and
00143  * port information in the SDP of that REINVITE lets us know that we may receive media
00144  * from that source/those sources even though the SIP transaction was unable to be completed
00145  * successfully
00146  *
00147  * \param rtp The RTP structure we wish to set up an alternate host/port on
00148  * \param alt The address information for the alternate media source
00149  * \retval void
00150  */
00151 void ast_rtp_set_alt_peer(struct ast_rtp *rtp, struct sockaddr_in *alt);
00152 
00153 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
00154 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00155 
00156 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
00157 
00158 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
00159 
00160 /*! Destroy RTP session */
00161 void ast_rtp_destroy(struct ast_rtp *rtp);
00162 
00163 void ast_rtp_reset(struct ast_rtp *rtp);
00164 
00165 /*! Stop RTP session, do not destroy structure */
00166 void ast_rtp_stop(struct ast_rtp *rtp);
00167 
00168 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
00169 
00170 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
00171 
00172 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
00173 
00174 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
00175 
00176 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
00177 
00178 int ast_rtp_fd(struct ast_rtp *rtp);
00179 
00180 int ast_rtcp_fd(struct ast_rtp *rtp);
00181 
00182 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
00183 
00184 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
00185 
00186 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
00187 
00188 int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int cos, char *desc);
00189 
00190 void ast_rtp_new_source(struct ast_rtp *rtp);
00191 
00192 /*! \brief  Setting RTP payload types from lines in a SDP description: */
00193 void ast_rtp_pt_clear(struct ast_rtp* rtp);
00194 /*! \brief Set payload types to defaults */
00195 void ast_rtp_pt_default(struct ast_rtp* rtp);
00196 
00197 /*! \brief Copy payload types between RTP structures */
00198 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
00199 
00200 /*! \brief Activate payload type */
00201 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
00202 
00203 /*! \brief clear payload type */
00204 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
00205 
00206 /*! \brief Initiate payload type to a known MIME media type for a codec */
00207 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
00208               char *mimeType, char *mimeSubtype,
00209               enum ast_rtp_options options);
00210 
00211 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
00212 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
00213 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
00214 
00215 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
00216               int* astFormats, int* nonAstFormats);
00217 
00218 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
00219 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
00220                enum ast_rtp_options options);
00221 
00222 /*! \brief Build a string of MIME subtype names from a capability list */
00223 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
00224                const int isAstFormat, enum ast_rtp_options options);
00225 
00226 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
00227 
00228 int ast_rtp_getnat(struct ast_rtp *rtp);
00229 
00230 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
00231 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
00232 
00233 /*! \brief Compensate for devices that send RFC2833 packets all at once */
00234 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
00235 
00236 /*! \brief Enable STUN capability */
00237 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
00238 
00239 /*! \brief Generic STUN request
00240  * send a generic stun request to the server specified.
00241  * \param s the socket used to send the request
00242  * \param dst the address of the STUN server
00243  * \param username if non null, add the username in the request
00244  * \param answer if non null, the function waits for a response and
00245  *    puts here the externally visible address.
00246  * \return 0 on success, other values on error.
00247  * The interface it may change in the future.
00248  */
00249 int ast_stun_request(int s, struct sockaddr_in *dst,
00250    const char *username, struct sockaddr_in *answer);
00251 
00252 /*! \brief Send STUN request for an RTP socket
00253  * Deprecated, this is just a wrapper for ast_rtp_stun_request()
00254  */
00255 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
00256 
00257 /*! \brief The RTP bridge.
00258    \arg \ref AstRTPbridge
00259 */
00260 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
00261 
00262 /*! \brief Register an RTP channel client */
00263 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
00264 
00265 /*! \brief Unregister an RTP channel client */
00266 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
00267 
00268 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
00269 
00270 /*! \brief If possible, create an early bridge directly between the devices without
00271            having to send a re-invite later */
00272 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
00273 
00274 /*! \brief Return RTCP quality string */
00275 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual);
00276 
00277 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
00278 int ast_rtcp_send_h261fur(void *data);
00279 
00280 void ast_rtp_init(void);                                      /*! Initialize RTP subsystem */
00281 int ast_rtp_reload(void);                                     /*! reload rtp configuration */
00282 void ast_rtp_new_init(struct ast_rtp *rtp);
00283 
00284 /*! \brief Set codec preference */
00285 void ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
00286 
00287 /*! \brief Get codec preference */
00288 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
00289 
00290 /*! \brief get format from predefined dynamic payload format */
00291 int ast_rtp_codec_getformat(int pt);
00292 
00293 /*! \brief Set rtp timeout */
00294 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
00295 /*! \brief Set rtp hold timeout */
00296 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
00297 /*! \brief set RTP keepalive interval */
00298 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
00299 /*! \brief Get RTP keepalive interval */
00300 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
00301 /*! \brief Get rtp hold timeout */
00302 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
00303 /*! \brief Get rtp timeout */
00304 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
00305 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
00306 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
00307 
00308 #if defined(__cplusplus) || defined(c_plusplus)
00309 }
00310 #endif
00311 
00312 #endif /* _ASTERISK_RTP_H */

Generated on Thu Jul 9 13:40:40 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7