Thu Apr 28 2011 17:13:35

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 /*! T.140 Redundancy Maxium number of generations */
00055 #define RED_MAX_GENERATION 5
00056 
00057 #define FLAG_3389_WARNING     (1 << 0)
00058 
00059 enum ast_rtp_options {
00060    AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
00061 };
00062 
00063 enum ast_rtp_get_result {
00064    /*! Failed to find the RTP structure */
00065    AST_RTP_GET_FAILED = 0,
00066    /*! RTP structure exists but true native bridge can not occur so try partial */
00067    AST_RTP_TRY_PARTIAL,
00068    /*! RTP structure exists and native bridge can occur */
00069    AST_RTP_TRY_NATIVE,
00070 };
00071 
00072 /*! \brief Variables used in ast_rtcp_get function */
00073 enum ast_rtp_qos_vars {
00074    AST_RTP_TXCOUNT,
00075    AST_RTP_RXCOUNT,
00076    AST_RTP_TXJITTER,
00077    AST_RTP_RXJITTER,
00078    AST_RTP_RXPLOSS,
00079    AST_RTP_TXPLOSS,
00080    AST_RTP_RTT
00081 };
00082 
00083 struct ast_rtp;
00084 /*! T.140 Redundancy structure*/
00085 struct rtp_red;
00086 
00087 /*! \brief The value of each payload format mapping: */
00088 struct rtpPayloadType {
00089    int isAstFormat;     /*!< whether the following code is an AST_FORMAT */
00090    int code;
00091 };
00092 
00093 /*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem 
00094 */
00095 struct ast_rtp_protocol {
00096    /*! Get RTP struct, or NULL if unwilling to transfer */
00097    enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00098    /*! Get RTP struct, or NULL if unwilling to transfer */
00099    enum ast_rtp_get_result (* const get_vrtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00100    /*! Get RTP struct, or NULL if unwilling to transfer */
00101    enum ast_rtp_get_result (* const get_trtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
00102    /*! Set RTP peer */
00103    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);
00104    int (* const get_codec)(struct ast_channel *chan);
00105    const char * const type;
00106    AST_LIST_ENTRY(ast_rtp_protocol) list;
00107 };
00108 
00109 enum ast_rtp_quality_type {
00110    RTPQOS_SUMMARY = 0,
00111    RTPQOS_JITTER,
00112    RTPQOS_LOSS,
00113    RTPQOS_RTT
00114 };
00115 
00116 /*! \brief RTCP quality report storage */
00117 struct ast_rtp_quality {
00118    unsigned int local_ssrc;          /*!< Our SSRC */
00119    unsigned int local_lostpackets;   /*!< Our lost packets */
00120    double       local_jitter;        /*!< Our calculated jitter */
00121    unsigned int local_count;         /*!< Number of received packets */
00122    unsigned int remote_ssrc;         /*!< Their SSRC */
00123    unsigned int remote_lostpackets;  /*!< Their lost packets */
00124    double       remote_jitter;       /*!< Their reported jitter */
00125    unsigned int remote_count;        /*!< Number of transmitted packets */
00126    double       rtt;                 /*!< Round trip time */
00127 };
00128 
00129 /*! RTP callback structure */
00130 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
00131 
00132 /*!
00133  * \brief Get the amount of space required to hold an RTP session
00134  * \return number of bytes required
00135  */
00136 size_t ast_rtp_alloc_size(void);
00137 
00138 /*!
00139  * \brief Initializate a RTP session.
00140  *
00141  * \param sched
00142  * \param io
00143  * \param rtcpenable
00144  * \param callbackmode
00145  * \return A representation (structure) of an RTP session.
00146  */
00147 struct ast_rtp *ast_rtp_new(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode);
00148 
00149 /*!
00150  * \brief Initializate a RTP session using an in_addr structure.
00151  *
00152  * This fuction gets called by ast_rtp_new().
00153  *
00154  * \param sched
00155  * \param io
00156  * \param rtcpenable
00157  * \param callbackmode
00158  * \param in
00159  * \return A representation (structure) of an RTP session.
00160  */
00161 struct ast_rtp *ast_rtp_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int rtcpenable, int callbackmode, struct in_addr in);
00162 
00163 void ast_rtp_set_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00164 
00165 /*! 
00166  * \since 1.4.26
00167  * \brief set potential alternate source for RTP media
00168  *
00169  * This function may be used to give the RTP stack a hint that there is a potential
00170  * second source of media. One case where this is used is when the SIP stack receives
00171  * a REINVITE to which it will be replying with a 491. In such a scenario, the IP and
00172  * port information in the SDP of that REINVITE lets us know that we may receive media
00173  * from that source/those sources even though the SIP transaction was unable to be completed
00174  * successfully
00175  *
00176  * \param rtp The RTP structure we wish to set up an alternate host/port on
00177  * \param alt The address information for the alternate media source
00178  * \retval void
00179  */
00180 void ast_rtp_set_alt_peer(struct ast_rtp *rtp, struct sockaddr_in *alt);
00181 
00182 /* Copies from rtp to them and returns 1 if there was a change or 0 if it was already the same */
00183 int ast_rtp_get_peer(struct ast_rtp *rtp, struct sockaddr_in *them);
00184 
00185 void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
00186 
00187 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
00188 
00189 /*! Destroy RTP session */
00190 void ast_rtp_destroy(struct ast_rtp *rtp);
00191 
00192 void ast_rtp_reset(struct ast_rtp *rtp);
00193 
00194 /*! Stop RTP session, do not destroy structure */
00195 void ast_rtp_stop(struct ast_rtp *rtp);
00196 
00197 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
00198 
00199 void ast_rtp_set_data(struct ast_rtp *rtp, void *data);
00200 
00201 int ast_rtp_write(struct ast_rtp *rtp, struct ast_frame *f);
00202 
00203 struct ast_frame *ast_rtp_read(struct ast_rtp *rtp);
00204 
00205 struct ast_frame *ast_rtcp_read(struct ast_rtp *rtp);
00206 
00207 int ast_rtp_fd(struct ast_rtp *rtp);
00208 
00209 int ast_rtcp_fd(struct ast_rtp *rtp);
00210 
00211 int ast_rtp_senddigit_begin(struct ast_rtp *rtp, char digit);
00212 
00213 int ast_rtp_senddigit_end(struct ast_rtp *rtp, char digit);
00214 int ast_rtp_senddigit_end_with_duration(struct ast_rtp *rtp, char digit, unsigned int duration);
00215 
00216 int ast_rtp_sendcng(struct ast_rtp *rtp, int level);
00217 
00218 int ast_rtp_setqos(struct ast_rtp *rtp, int tos, int cos, char *desc);
00219 
00220 /*! \brief Indicate that we need to set the marker bit */
00221 void ast_rtp_new_source(struct ast_rtp *rtp);
00222 
00223 /*! \brief Indicate that we need to set the marker bit and change the ssrc */
00224 void ast_rtp_change_source(struct ast_rtp *rtp);
00225 
00226 /*! \brief  Setting RTP payload types from lines in a SDP description: */
00227 void ast_rtp_pt_clear(struct ast_rtp* rtp);
00228 /*! \brief Set payload types to defaults */
00229 void ast_rtp_pt_default(struct ast_rtp* rtp);
00230 
00231 /*! \brief Copy payload types between RTP structures */
00232 void ast_rtp_pt_copy(struct ast_rtp *dest, struct ast_rtp *src);
00233 
00234 /*! \brief Activate payload type */
00235 void ast_rtp_set_m_type(struct ast_rtp* rtp, int pt);
00236 
00237 /*! \brief clear payload type */
00238 void ast_rtp_unset_m_type(struct ast_rtp* rtp, int pt);
00239 
00240 /*! \brief Set payload type to a known MIME media type for a codec
00241  *
00242  * \param rtp RTP structure to modify
00243  * \param pt Payload type entry to modify
00244  * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
00245  * \param mimeSubtype MIME subtype of media stream (typically a codec name)
00246  * \param options Zero or more flags from the ast_rtp_options enum
00247  *
00248  * This function 'fills in' an entry in the list of possible formats for
00249  * a media stream associated with an RTP structure.
00250  *
00251  * \retval 0 on success
00252  * \retval -1 if the payload type is out of range
00253  * \retval -2 if the mimeType/mimeSubtype combination was not found
00254  */
00255 int ast_rtp_set_rtpmap_type(struct ast_rtp* rtp, int pt,
00256               char *mimeType, char *mimeSubtype,
00257               enum ast_rtp_options options);
00258 
00259 /*! \brief Set payload type to a known MIME media type for a codec with a specific sample rate
00260  *
00261  * \param rtp RTP structure to modify
00262  * \param pt Payload type entry to modify
00263  * \param mimeType top-level MIME type of media stream (typically "audio", "video", "text", etc.)
00264  * \param mimeSubtype MIME subtype of media stream (typically a codec name)
00265  * \param options Zero or more flags from the ast_rtp_options enum
00266  * \param sample_rate The sample rate of the media stream
00267  *
00268  * This function 'fills in' an entry in the list of possible formats for
00269  * a media stream associated with an RTP structure.
00270  *
00271  * \retval 0 on success
00272  * \retval -1 if the payload type is out of range
00273  * \retval -2 if the mimeType/mimeSubtype combination was not found
00274  */
00275 int ast_rtp_set_rtpmap_type_rate(struct ast_rtp* rtp, int pt,
00276              char *mimeType, char *mimeSubtype,
00277              enum ast_rtp_options options,
00278              unsigned int sample_rate);
00279 
00280 /*! \brief  Mapping between RTP payload format codes and Asterisk codes: */
00281 struct rtpPayloadType ast_rtp_lookup_pt(struct ast_rtp* rtp, int pt);
00282 int ast_rtp_lookup_code(struct ast_rtp* rtp, int isAstFormat, int code);
00283 
00284 void ast_rtp_get_current_formats(struct ast_rtp* rtp,
00285              int* astFormats, int* nonAstFormats);
00286 
00287 /*! \brief  Mapping an Asterisk code into a MIME subtype (string): */
00288 const char *ast_rtp_lookup_mime_subtype(int isAstFormat, int code,
00289                enum ast_rtp_options options);
00290 
00291 /*! \brief Get the sample rate associated with known RTP payload types
00292  *
00293  * \param isAstFormat True if the value in the 'code' parameter is an AST_FORMAT value
00294  * \param code Format code, either from AST_FORMAT list or from AST_RTP list
00295  *
00296  * \return the sample rate if the format was found, zero if it was not found
00297  */
00298 unsigned int ast_rtp_lookup_sample_rate(int isAstFormat, int code);
00299 
00300 /*! \brief Build a string of MIME subtype names from a capability list */
00301 char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability,
00302                const int isAstFormat, enum ast_rtp_options options);
00303 
00304 void ast_rtp_setnat(struct ast_rtp *rtp, int nat);
00305 
00306 int ast_rtp_getnat(struct ast_rtp *rtp);
00307 
00308 /*! \brief Indicate whether this RTP session is carrying DTMF or not */
00309 void ast_rtp_setdtmf(struct ast_rtp *rtp, int dtmf);
00310 
00311 /*! \brief Compensate for devices that send RFC2833 packets all at once */
00312 void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
00313 
00314 /*! \brief Enable STUN capability */
00315 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
00316 
00317 /*! \brief Generic STUN request
00318  * send a generic stun request to the server specified.
00319  * \param s the socket used to send the request
00320  * \param dst the address of the STUN server
00321  * \param username if non null, add the username in the request
00322  * \param answer if non null, the function waits for a response and
00323  *    puts here the externally visible address.
00324  * \return 0 on success, other values on error.
00325  * The interface it may change in the future.
00326  */
00327 int ast_stun_request(int s, struct sockaddr_in *dst,
00328    const char *username, struct sockaddr_in *answer);
00329 
00330 /*! \brief Send STUN request for an RTP socket
00331  * Deprecated, this is just a wrapper for ast_rtp_stun_request()
00332  */
00333 void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
00334 
00335 /*! \brief The RTP bridge.
00336    \arg \ref AstRTPbridge
00337 */
00338 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
00339 
00340 /*! \brief Register an RTP channel client */
00341 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
00342 
00343 /*! \brief Unregister an RTP channel client */
00344 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
00345 
00346 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
00347 
00348 /*! \brief If possible, create an early bridge directly between the devices without
00349            having to send a re-invite later */
00350 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
00351 
00352 /*! \brief Get QOS stats on a RTP channel
00353  * \since 1.6.1
00354  */
00355 int ast_rtp_get_qos(struct ast_rtp *rtp, const char *qos, char *buf, unsigned int buflen);
00356 
00357 /*! \brief Return RTP and RTCP QoS values
00358  * \since 1.6.1
00359  */
00360 unsigned int ast_rtp_get_qosvalue(struct ast_rtp *rtp, enum ast_rtp_qos_vars value);
00361 
00362 /*! \brief Set RTPAUDIOQOS(...) variables on a channel when it is being hung up
00363  * \since 1.6.1
00364  */
00365 void ast_rtp_set_vars(struct ast_channel *chan, struct ast_rtp *rtp);
00366 
00367 /*! \brief Return RTCP quality string 
00368  *
00369  *  \param rtp An rtp structure to get qos information about.
00370  *
00371  *  \param qual An (optional) rtp quality structure that will be 
00372  *              filled with the quality information described in 
00373  *              the ast_rtp_quality structure. This structure is
00374  *              not dependent on any qtype, so a call for any
00375  *              type of information would yield the same results
00376  *              because ast_rtp_quality is not a data type 
00377  *              specific to any qos type.
00378  *
00379  *  \param qtype The quality type you'd like, default should be
00380  *               RTPQOS_SUMMARY which returns basic information
00381  *               about the call. The return from RTPQOS_SUMMARY
00382  *               is basically ast_rtp_quality in a string. The
00383  *               other types are RTPQOS_JITTER, RTPQOS_LOSS and
00384  *               RTPQOS_RTT which will return more specific 
00385  *               statistics.
00386  * \version 1.6.1 added qtype parameter
00387  */
00388 char *ast_rtp_get_quality(struct ast_rtp *rtp, struct ast_rtp_quality *qual, enum ast_rtp_quality_type qtype);
00389 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
00390 int ast_rtcp_send_h261fur(void *data);
00391 
00392 void ast_rtp_init(void);                                      /*! Initialize RTP subsystem */
00393 int ast_rtp_reload(void);                                     /*! reload rtp configuration */
00394 void ast_rtp_new_init(struct ast_rtp *rtp);
00395 
00396 /*! \brief Set codec preference */
00397 void ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
00398 
00399 /*! \brief Get codec preference */
00400 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
00401 
00402 /*! \brief get format from predefined dynamic payload format */
00403 int ast_rtp_codec_getformat(int pt);
00404 
00405 /*! \brief Set rtp timeout */
00406 void ast_rtp_set_rtptimeout(struct ast_rtp *rtp, int timeout);
00407 /*! \brief Set rtp hold timeout */
00408 void ast_rtp_set_rtpholdtimeout(struct ast_rtp *rtp, int timeout);
00409 /*! \brief set RTP keepalive interval */
00410 void ast_rtp_set_rtpkeepalive(struct ast_rtp *rtp, int period);
00411 /*! \brief Get RTP keepalive interval */
00412 int ast_rtp_get_rtpkeepalive(struct ast_rtp *rtp);
00413 /*! \brief Get rtp hold timeout */
00414 int ast_rtp_get_rtpholdtimeout(struct ast_rtp *rtp);
00415 /*! \brief Get rtp timeout */
00416 int ast_rtp_get_rtptimeout(struct ast_rtp *rtp);
00417 /* \brief Put RTP timeout timers on hold during another transaction, like T.38 */
00418 void ast_rtp_set_rtptimers_onhold(struct ast_rtp *rtp);
00419 
00420 /*! \brief Initalize t.140 redudancy 
00421  * \param ti time between each t140red frame is sent
00422  * \param red_pt payloadtype for RTP packet
00423  * \param pt payloadtype numbers for each generation including primary data
00424  * \param num_gen number of redundant generations, primary data excluded
00425  * \since 1.6.1
00426  */
00427 int rtp_red_init(struct ast_rtp *rtp, int ti, int *pt, int num_gen);
00428 
00429 /*! \brief Buffer t.140 data */
00430 void red_buffer_t140(struct ast_rtp *rtp, struct ast_frame *f);
00431 
00432 
00433 
00434 #if defined(__cplusplus) || defined(c_plusplus)
00435 }
00436 #endif
00437 
00438 #endif /* _ASTERISK_RTP_H */