Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 19 | */ |
| 20 | #ifndef __PJMEDIA_STREAM_H__ |
| 21 | #define __PJMEDIA_STREAM_H__ |
| 22 | |
| 23 | |
| 24 | /** |
| 25 | * @file stream.h |
| 26 | * @brief Media Stream. |
| 27 | */ |
| 28 | |
| 29 | #include <pjmedia/codec.h> |
| 30 | #include <pjmedia/endpoint.h> |
| 31 | #include <pjmedia/jbuf.h> |
| 32 | #include <pjmedia/port.h> |
| 33 | #include <pjmedia/rtcp.h> |
| 34 | #include <pjmedia/transport.h> |
| 35 | #include <pjmedia/vid_codec.h> |
| 36 | #include <pj/sock.h> |
| 37 | |
| 38 | PJ_BEGIN_DECL |
| 39 | |
| 40 | |
| 41 | /** |
| 42 | * @defgroup PJMED_STRM Streams |
| 43 | * @ingroup PJMEDIA_PORT |
| 44 | * @brief Communicating with remote peer via the network |
| 45 | * @{ |
| 46 | * |
| 47 | * A media stream is a bidirectional multimedia communication between two |
| 48 | * endpoints. It corresponds to a media description (m= line) in SDP |
| 49 | * session descriptor. |
| 50 | * |
| 51 | * A media stream consists of two unidirectional channels: |
| 52 | * - encoding channel, which transmits unidirectional media to remote, and |
| 53 | * - decoding channel, which receives unidirectional media from remote. |
| 54 | * |
| 55 | * A media stream exports media port interface (see @ref PJMEDIA_PORT) |
| 56 | * and application normally uses this interface to interconnect the stream |
| 57 | * to other PJMEDIA components. |
| 58 | * |
| 59 | * A media stream internally manages the following objects: |
| 60 | * - an instance of media codec (see @ref PJMEDIA_CODEC), |
| 61 | * - an @ref PJMED_JBUF, |
| 62 | * - two instances of RTP sessions (#pjmedia_rtp_session, one for each |
| 63 | * direction), |
| 64 | * - one instance of RTCP session (#pjmedia_rtcp_session), |
| 65 | * - and a reference to media transport to send and receive packets |
| 66 | * to/from the network (see @ref PJMEDIA_TRANSPORT). |
| 67 | * |
| 68 | * Streams are created by calling #pjmedia_stream_create(), specifying |
| 69 | * #pjmedia_stream_info structure in the parameter. Application can construct |
| 70 | * the #pjmedia_stream_info structure manually, or use |
| 71 | * #pjmedia_stream_info_from_sdp() or #pjmedia_session_info_from_sdp() |
| 72 | * functions to construct the #pjmedia_stream_info from local and remote |
| 73 | * SDP session descriptors. |
| 74 | * |
| 75 | * Application can also use @ref PJMEDIA_SESSION to indirectly create the |
| 76 | * streams. |
| 77 | */ |
| 78 | |
| 79 | /** |
| 80 | * Opaque declaration for media channel. |
| 81 | * Media channel is unidirectional flow of media from sender to |
| 82 | * receiver. |
| 83 | */ |
| 84 | typedef struct pjmedia_channel pjmedia_channel; |
| 85 | |
| 86 | /** |
| 87 | * This structure describes media stream information. Each media stream |
| 88 | * corresponds to one "m=" line in SDP session descriptor, and it has |
| 89 | * its own RTP/RTCP socket pair. |
| 90 | */ |
| 91 | typedef struct pjmedia_stream_info |
| 92 | { |
| 93 | pjmedia_type type; /**< Media type (audio, video) */ |
| 94 | pjmedia_tp_proto proto; /**< Transport protocol (RTP/AVP, etc.) */ |
| 95 | pjmedia_dir dir; /**< Media direction. */ |
| 96 | pj_sockaddr rem_addr; /**< Remote RTP address */ |
| 97 | pj_sockaddr rem_rtcp; /**< Optional remote RTCP address. If |
| 98 | sin_family is zero, the RTP address |
| 99 | will be calculated from RTP. */ |
| 100 | #if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0) |
| 101 | pj_bool_t rtcp_xr_enabled; |
| 102 | /**< Specify whether RTCP XR is enabled.*/ |
| 103 | pj_uint32_t rtcp_xr_interval; /**< RTCP XR interval. */ |
| 104 | pj_sockaddr rtcp_xr_dest;/**<Additional remote RTCP XR address. |
| 105 | This is useful for third-party (e.g: |
| 106 | network monitor) to monitor the |
| 107 | stream. If sin_family is zero, |
| 108 | this will be ignored. */ |
| 109 | #endif |
| 110 | pjmedia_codec_info fmt; /**< Incoming codec format info. */ |
| 111 | pjmedia_codec_param *param; /**< Optional codec param. */ |
| 112 | unsigned tx_pt; /**< Outgoing codec paylaod type. */ |
| 113 | unsigned rx_pt; /**< Incoming codec paylaod type. */ |
| 114 | unsigned tx_maxptime;/**< Outgoing codec max ptime. */ |
| 115 | int tx_event_pt;/**< Outgoing pt for telephone-events. */ |
| 116 | int rx_event_pt;/**< Incoming pt for telephone-events. */ |
| 117 | pj_uint32_t ssrc; /**< RTP SSRC. */ |
| 118 | pj_uint32_t rtp_ts; /**< Initial RTP timestamp. */ |
| 119 | pj_uint16_t rtp_seq; /**< Initial RTP sequence number. */ |
| 120 | pj_uint8_t rtp_seq_ts_set; |
| 121 | /**< Bitmask flags if initial RTP sequence |
| 122 | and/or timestamp for sender are set. |
| 123 | bit 0/LSB : sequence flag |
| 124 | bit 1 : timestamp flag */ |
| 125 | int jb_init; /**< Jitter buffer init delay in msec. |
| 126 | (-1 for default). */ |
| 127 | int jb_min_pre; /**< Jitter buffer minimum prefetch |
| 128 | delay in msec (-1 for default). */ |
| 129 | int jb_max_pre; /**< Jitter buffer maximum prefetch |
| 130 | delay in msec (-1 for default). */ |
| 131 | int jb_max; /**< Jitter buffer max delay in msec. */ |
| 132 | |
| 133 | #if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0 |
| 134 | pj_bool_t use_ka; /**< Stream keep-alive and NAT hole punch |
| 135 | (see #PJMEDIA_STREAM_ENABLE_KA) |
| 136 | is enabled? */ |
| 137 | #endif |
| 138 | pj_bool_t rtcp_sdes_bye_disabled; |
| 139 | /**< Disable automatic sending of RTCP |
| 140 | SDES and BYE. */ |
| 141 | } pjmedia_stream_info; |
| 142 | |
| 143 | |
| 144 | /** |
| 145 | * This function will initialize the stream info based on information |
| 146 | * in both SDP session descriptors for the specified stream index. |
| 147 | * The remaining information will be taken from default codec parameters. |
| 148 | * If socket info array is specified, the socket will be copied to the |
| 149 | * session info as well. |
| 150 | * |
| 151 | * @param si Stream info structure to be initialized. |
| 152 | * @param pool Pool to allocate memory. |
| 153 | * @param endpt PJMEDIA endpoint instance. |
| 154 | * @param local Local SDP session descriptor. |
| 155 | * @param remote Remote SDP session descriptor. |
| 156 | * @param stream_idx Media stream index in the session descriptor. |
| 157 | * |
| 158 | * @return PJ_SUCCESS if stream info is successfully initialized. |
| 159 | */ |
| 160 | PJ_DECL(pj_status_t) |
| 161 | pjmedia_stream_info_from_sdp( pjmedia_stream_info *si, |
| 162 | pj_pool_t *pool, |
| 163 | pjmedia_endpt *endpt, |
| 164 | const pjmedia_sdp_session *local, |
| 165 | const pjmedia_sdp_session *remote, |
| 166 | unsigned stream_idx); |
| 167 | |
| 168 | |
| 169 | /** |
| 170 | * Create a media stream based on the specified parameter. After the stream |
| 171 | * has been created, application normally would want to get the media port |
| 172 | * interface of the streams, by calling pjmedia_stream_get_port(). The |
| 173 | * media port interface exports put_frame() and get_frame() function, used |
| 174 | * to transmit and receive media frames from the stream. |
| 175 | * |
| 176 | * Without application calling put_frame() and get_frame(), there will be |
| 177 | * no media frames transmitted or received by the stream. |
| 178 | * |
| 179 | * @param endpt Media endpoint. |
| 180 | * @param pool Pool to allocate memory for the stream. A large |
| 181 | * number of memory may be needed because jitter |
| 182 | * buffer needs to preallocate some storage. |
| 183 | * @param info Stream information. |
| 184 | * @param tp Stream transport instance used to transmit |
| 185 | * and receive RTP/RTCP packets to/from the underlying |
| 186 | * transport. |
| 187 | * @param user_data Arbitrary user data (for future callback feature). |
| 188 | * @param p_stream Pointer to receive the media stream. |
| 189 | * |
| 190 | * @return PJ_SUCCESS on success. |
| 191 | */ |
| 192 | PJ_DECL(pj_status_t) pjmedia_stream_create(pjmedia_endpt *endpt, |
| 193 | pj_pool_t *pool, |
| 194 | const pjmedia_stream_info *info, |
| 195 | pjmedia_transport *tp, |
| 196 | void *user_data, |
| 197 | pjmedia_stream **p_stream); |
| 198 | |
| 199 | /** |
| 200 | * Destroy the media stream. |
| 201 | * |
| 202 | * @param stream The media stream. |
| 203 | * |
| 204 | * @return PJ_SUCCESS on success. |
| 205 | */ |
| 206 | PJ_DECL(pj_status_t) pjmedia_stream_destroy(pjmedia_stream *stream); |
| 207 | |
| 208 | |
| 209 | /** |
| 210 | * Get the last frame type retreived from the jitter buffer. |
| 211 | * |
| 212 | * @param stream The media stream. |
| 213 | * |
| 214 | * @return Jitter buffer frame type. |
| 215 | */ |
| 216 | PJ_DEF(char) pjmedia_stream_get_last_jb_frame_type(pjmedia_stream *stream); |
| 217 | |
| 218 | |
| 219 | /** |
| 220 | * Get the media port interface of the stream. The media port interface |
| 221 | * declares put_frame() and get_frame() function, which is the only |
| 222 | * way for application to transmit and receive media frames from the |
| 223 | * stream. |
| 224 | * |
| 225 | * @param stream The media stream. |
| 226 | * @param p_port Pointer to receive the port interface. |
| 227 | * |
| 228 | * @return PJ_SUCCESS on success. |
| 229 | */ |
| 230 | PJ_DECL(pj_status_t) pjmedia_stream_get_port(pjmedia_stream *stream, |
| 231 | pjmedia_port **p_port ); |
| 232 | |
| 233 | |
| 234 | /** |
| 235 | * Get the media transport object associated with this stream. |
| 236 | * |
| 237 | * @param st The media stream. |
| 238 | * |
| 239 | * @return The transport object being used by the stream. |
| 240 | */ |
| 241 | PJ_DECL(pjmedia_transport*) pjmedia_stream_get_transport(pjmedia_stream *st); |
| 242 | |
| 243 | |
| 244 | /** |
| 245 | * Start the media stream. This will start the appropriate channels |
| 246 | * in the media stream, depending on the media direction that was set |
| 247 | * when the stream was created. |
| 248 | * |
| 249 | * @param stream The media stream. |
| 250 | * |
| 251 | * @return PJ_SUCCESS on success. |
| 252 | */ |
| 253 | PJ_DECL(pj_status_t) pjmedia_stream_start(pjmedia_stream *stream); |
| 254 | |
| 255 | |
| 256 | /** |
| 257 | * Get the stream info. |
| 258 | * |
| 259 | * @param stream The media stream. |
| 260 | * @param info Stream info. |
| 261 | * |
| 262 | * @return PJ_SUCCESS on success. |
| 263 | */ |
| 264 | PJ_DECL(pj_status_t) pjmedia_stream_get_info( const pjmedia_stream *stream, |
| 265 | pjmedia_stream_info *info); |
| 266 | |
| 267 | /** |
| 268 | * Get the stream statistics. See also |
| 269 | * #pjmedia_stream_get_stat_jbuf() |
| 270 | * |
| 271 | * @param stream The media stream. |
| 272 | * @param stat Media stream statistics. |
| 273 | * |
| 274 | * @return PJ_SUCCESS on success. |
| 275 | */ |
| 276 | PJ_DECL(pj_status_t) pjmedia_stream_get_stat( const pjmedia_stream *stream, |
| 277 | pjmedia_rtcp_stat *stat); |
| 278 | |
| 279 | |
| 280 | /** |
| 281 | * Reset the stream statistics. |
| 282 | * |
| 283 | * @param stream The media stream. |
| 284 | * |
| 285 | * @return PJ_SUCCESS on success. |
| 286 | */ |
| 287 | PJ_DECL(pj_status_t) pjmedia_stream_reset_stat(pjmedia_stream *stream); |
| 288 | |
| 289 | |
| 290 | #if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0) |
| 291 | /** |
| 292 | * Get the stream extended report statistics (RTCP XR). |
| 293 | * |
| 294 | * @param stream The media stream. |
| 295 | * @param stat Media stream extended report statistics. |
| 296 | * |
| 297 | * @return PJ_SUCCESS on success. |
| 298 | */ |
| 299 | PJ_DECL(pj_status_t) pjmedia_stream_get_stat_xr( const pjmedia_stream *stream, |
| 300 | pjmedia_rtcp_xr_stat *stat); |
| 301 | #endif |
| 302 | |
| 303 | /** |
| 304 | * Get current jitter buffer state. See also |
| 305 | * #pjmedia_stream_get_stat() |
| 306 | * |
| 307 | * @param stream The media stream. |
| 308 | * @param state Jitter buffer state. |
| 309 | * |
| 310 | * @return PJ_SUCCESS on success. |
| 311 | */ |
| 312 | PJ_DECL(pj_status_t) pjmedia_stream_get_stat_jbuf(const pjmedia_stream *stream, |
| 313 | pjmedia_jb_state *state); |
| 314 | |
| 315 | |
| 316 | /** |
| 317 | * Pause the individual channel in the stream. |
| 318 | * |
| 319 | * @param stream The media channel. |
| 320 | * @param dir Which direction to pause. |
| 321 | * |
| 322 | * @return PJ_SUCCESS on success. |
| 323 | */ |
| 324 | PJ_DECL(pj_status_t) pjmedia_stream_pause( pjmedia_stream *stream, |
| 325 | pjmedia_dir dir); |
| 326 | |
| 327 | /** |
| 328 | * Resume the individual channel in the stream. |
| 329 | * |
| 330 | * @param stream The media channel. |
| 331 | * @param dir Which direction to resume. |
| 332 | * |
| 333 | * @return PJ_SUCCESS on success; |
| 334 | */ |
| 335 | PJ_DECL(pj_status_t) pjmedia_stream_resume(pjmedia_stream *stream, |
| 336 | pjmedia_dir dir); |
| 337 | |
| 338 | /** |
| 339 | * Transmit DTMF to this stream. The DTMF will be transmitted uisng |
| 340 | * RTP telephone-events as described in RFC 2833. This operation is |
| 341 | * only valid for audio stream. |
| 342 | * |
| 343 | * @param stream The media stream. |
| 344 | * @param ascii_digit String containing digits to be sent to remote. |
| 345 | * Currently the maximum number of digits are 32. |
| 346 | * |
| 347 | * @return PJ_SUCCESS on success. |
| 348 | */ |
| 349 | PJ_DECL(pj_status_t) pjmedia_stream_dial_dtmf(pjmedia_stream *stream, |
| 350 | const pj_str_t *ascii_digit); |
| 351 | |
| 352 | |
| 353 | /** |
| 354 | * Check if the stream has incoming DTMF digits in the incoming DTMF |
| 355 | * queue. Incoming DTMF digits received via RFC 2833 mechanism are |
| 356 | * saved in the incoming digits queue. |
| 357 | * |
| 358 | * @param stream The media stream. |
| 359 | * |
| 360 | * @return Non-zero (PJ_TRUE) if the stream has received DTMF |
| 361 | * digits in the . |
| 362 | */ |
| 363 | PJ_DECL(pj_bool_t) pjmedia_stream_check_dtmf(pjmedia_stream *stream); |
| 364 | |
| 365 | |
| 366 | /** |
| 367 | * Retrieve the incoming DTMF digits from the stream, and remove the digits |
| 368 | * from stream's DTMF buffer. Note that the digits buffer will not be NULL |
| 369 | * terminated. |
| 370 | * |
| 371 | * @param stream The media stream. |
| 372 | * @param ascii_digits Buffer to receive the digits. The length of this |
| 373 | * buffer is indicated in the "size" argument. |
| 374 | * @param size On input, contains the maximum digits to be copied |
| 375 | * to the buffer. |
| 376 | * On output, it contains the actual digits that has |
| 377 | * been copied to the buffer. |
| 378 | * |
| 379 | * @return Non-zero (PJ_TRUE) if the stream has received DTMF |
| 380 | * digits in the . |
| 381 | */ |
| 382 | PJ_DECL(pj_status_t) pjmedia_stream_get_dtmf( pjmedia_stream *stream, |
| 383 | char *ascii_digits, |
| 384 | unsigned *size); |
| 385 | |
| 386 | |
| 387 | /** |
| 388 | * Set callback to be called upon receiving DTMF digits. If callback is |
| 389 | * registered, the stream will not buffer incoming DTMF but rather call |
| 390 | * the callback as soon as DTMF digit is received completely. |
| 391 | * |
| 392 | * @param stream The media stream. |
| 393 | * @param cb Callback to be called upon receiving DTMF digits. |
| 394 | * The DTMF digits will be given to the callback as |
| 395 | * ASCII digits. |
| 396 | * @param user_data User data to be returned back when the callback |
| 397 | * is called. |
| 398 | * |
| 399 | * @return PJ_SUCCESS on success. |
| 400 | */ |
| 401 | PJ_DECL(pj_status_t) |
| 402 | pjmedia_stream_set_dtmf_callback(pjmedia_stream *stream, |
| 403 | void (*cb)(pjmedia_stream*, |
| 404 | void *user_data, |
| 405 | int digit), |
| 406 | void *user_data); |
| 407 | |
| 408 | |
| 409 | /** |
| 410 | * Send RTCP SDES for the media stream. |
| 411 | * |
| 412 | * @param stream The media stream. |
| 413 | * |
| 414 | * @return PJ_SUCCESS on success. |
| 415 | */ |
| 416 | PJ_DECL(pj_status_t) |
| 417 | pjmedia_stream_send_rtcp_sdes( pjmedia_stream *stream ); |
| 418 | |
| 419 | /** |
| 420 | * Send RTCP BYE for the media stream. |
| 421 | * |
| 422 | * @param stream The media stream. |
| 423 | * |
| 424 | * @return PJ_SUCCESS on success. |
| 425 | */ |
| 426 | PJ_DECL(pj_status_t) |
| 427 | pjmedia_stream_send_rtcp_bye( pjmedia_stream *stream ); |
| 428 | |
| 429 | /** |
| 430 | * @} |
| 431 | */ |
| 432 | |
| 433 | PJ_END_DECL |
| 434 | |
| 435 | |
| 436 | #endif /* __PJMEDIA_STREAM_H__ */ |