Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
Benny Prijono | a771a51 | 2007-02-19 01:13:53 +0000 | [diff] [blame] | 3 | * Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org> |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 18 | */ |
| 19 | #ifndef __PJMEDIA_STREAM_H__ |
| 20 | #define __PJMEDIA_STREAM_H__ |
| 21 | |
| 22 | |
| 23 | /** |
| 24 | * @file stream.h |
Benny Prijono | 274975a | 2006-02-15 12:24:23 +0000 | [diff] [blame] | 25 | * @brief Media Stream. |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 26 | */ |
| 27 | |
| 28 | #include <pjmedia/sound.h> |
| 29 | #include <pjmedia/codec.h> |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 30 | #include <pjmedia/endpoint.h> |
Benny Prijono | f04ffdd | 2006-02-21 00:11:18 +0000 | [diff] [blame] | 31 | #include <pjmedia/port.h> |
Benny Prijono | 6996823 | 2006-04-06 19:29:03 +0000 | [diff] [blame] | 32 | #include <pjmedia/rtcp.h> |
Benny Prijono | 37235af | 2006-06-18 02:02:36 +0000 | [diff] [blame] | 33 | #include <pjmedia/transport.h> |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 34 | #include <pj/sock.h> |
| 35 | |
| 36 | PJ_BEGIN_DECL |
| 37 | |
| 38 | |
| 39 | /** |
Benny Prijono | 37235af | 2006-06-18 02:02:36 +0000 | [diff] [blame] | 40 | * @defgroup PJMED_STRM Streams |
| 41 | * @ingroup PJMEDIA_PORT |
| 42 | * @brief Media port for communicating with remote peer via the network. |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 43 | * @{ |
Benny Prijono | 274975a | 2006-02-15 12:24:23 +0000 | [diff] [blame] | 44 | * |
| 45 | * A media stream is a bidirectional multimedia communication between two |
Benny Prijono | 37235af | 2006-06-18 02:02:36 +0000 | [diff] [blame] | 46 | * endpoints. It corresponds to a media description (m= line) in SDP |
| 47 | * session descriptor. |
Benny Prijono | 274975a | 2006-02-15 12:24:23 +0000 | [diff] [blame] | 48 | * |
| 49 | * A media stream consists of two unidirectional channels: |
| 50 | * - encoding channel, which transmits unidirectional media to remote, and |
| 51 | * - decoding channel, which receives unidirectional media from remote. |
Benny Prijono | 24cf04b | 2006-02-15 12:41:43 +0000 | [diff] [blame] | 52 | * |
Benny Prijono | 37235af | 2006-06-18 02:02:36 +0000 | [diff] [blame] | 53 | * A media stream exports media port interface (see @ref PJMEDIA_PORT_CONCEPT) |
| 54 | * and application normally uses this interface to interconnect the stream |
| 55 | * to other PJMEDIA components. |
| 56 | * |
| 57 | * A media stream internally manages the following objects: |
| 58 | * - an instance of media codec (see @ref PJMEDIA_CODEC), |
| 59 | * - an @ref PJMED_JBUF, |
| 60 | * - two instances of RTP sessions (#pjmedia_rtp_session, one for each |
| 61 | * direction), |
| 62 | * - one instance of RTCP session (#pjmedia_rtcp_session), |
| 63 | * - and a reference to media transport to send and receive packets |
| 64 | * to/from the network (see @ref PJMEDIA_TRANSPORT_H). |
| 65 | * |
| 66 | * Streams are created by calling #pjmedia_stream_create(), specifying |
| 67 | * #pjmedia_stream_info structure in the parameter. Application can construct |
| 68 | * the #pjmedia_stream_info structure manually, or use |
| 69 | * #pjmedia_stream_info_from_sdp() or #pjmedia_session_info_from_sdp() |
| 70 | * functions to construct the #pjmedia_stream_info from local and remote |
| 71 | * SDP session descriptors. |
| 72 | * |
| 73 | * Application can also use @ref PJMEDIA_SESSION to indirectly create the |
| 74 | * streams. |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 75 | */ |
| 76 | |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 77 | /** |
| 78 | * Opaque declaration for media channel. |
| 79 | * Media channel is unidirectional flow of media from sender to |
| 80 | * receiver. |
| 81 | */ |
| 82 | typedef struct pjmedia_channel pjmedia_channel; |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 83 | |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 84 | /** |
| 85 | * This structure describes media stream information. Each media stream |
| 86 | * corresponds to one "m=" line in SDP session descriptor, and it has |
| 87 | * its own RTP/RTCP socket pair. |
| 88 | */ |
| 89 | struct pjmedia_stream_info |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 90 | { |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 91 | pjmedia_type type; /**< Media type (audio, video) */ |
| 92 | pjmedia_dir dir; /**< Media direction. */ |
Benny Prijono | 5186eae | 2007-12-03 14:38:25 +0000 | [diff] [blame^] | 93 | pj_sockaddr rem_addr; /**< Remote RTP address */ |
| 94 | pj_sockaddr rem_rtcp; /**< Optional remote RTCP address. If |
Benny Prijono | b12106f | 2006-06-29 14:45:17 +0000 | [diff] [blame] | 95 | sin_family is zero, the RTP address |
| 96 | will be calculated from RTP. */ |
Benny Prijono | 8f0e8dc | 2006-03-06 13:30:39 +0000 | [diff] [blame] | 97 | pjmedia_codec_info fmt; /**< Incoming codec format info. */ |
Benny Prijono | 8befd9f | 2006-05-13 22:46:23 +0000 | [diff] [blame] | 98 | pjmedia_codec_param *param; /**< Optional codec param. */ |
Benny Prijono | 8f0e8dc | 2006-03-06 13:30:39 +0000 | [diff] [blame] | 99 | unsigned tx_pt; /**< Outgoing codec paylaod type. */ |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 100 | int tx_event_pt;/**< Outgoing pt for telephone-events. */ |
| 101 | int rx_event_pt;/**< Incoming pt for telephone-events. */ |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 102 | pj_uint32_t ssrc; /**< RTP SSRC. */ |
Benny Prijono | 8befd9f | 2006-05-13 22:46:23 +0000 | [diff] [blame] | 103 | int jb_init; /**< Jitter buffer init delay in msec. |
| 104 | (-1 for default). */ |
| 105 | int jb_min_pre; /**< Jitter buffer minimum prefetch |
| 106 | delay in msec (-1 for default). */ |
| 107 | int jb_max_pre; /**< Jitter buffer maximum prefetch |
| 108 | delay in msec (-1 for default). */ |
Benny Prijono | 9eb3367 | 2006-05-02 17:49:31 +0000 | [diff] [blame] | 109 | int jb_max; /**< Jitter buffer max delay in msec. */ |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 110 | }; |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 111 | |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 112 | |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 113 | /** |
Benny Prijono | 8befd9f | 2006-05-13 22:46:23 +0000 | [diff] [blame] | 114 | * @see pjmedia_stream_info. |
| 115 | */ |
| 116 | typedef struct pjmedia_stream_info pjmedia_stream_info; |
| 117 | |
| 118 | |
Benny Prijono | b04c9e0 | 2006-05-17 17:17:39 +0000 | [diff] [blame] | 119 | |
| 120 | /** |
Benny Prijono | 1d709a2 | 2006-04-27 23:48:08 +0000 | [diff] [blame] | 121 | * Create a media stream based on the specified parameter. After the stream |
| 122 | * has been created, application normally would want to get the media port |
| 123 | * interface of the streams, by calling pjmedia_stream_get_port(). The |
| 124 | * media port interface exports put_frame() and get_frame() function, used |
| 125 | * to transmit and receive media frames from the stream. |
| 126 | * |
| 127 | * Without application calling put_frame() and get_frame(), there will be |
| 128 | * no media frames transmitted or received by the stream. |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 129 | * |
| 130 | * @param endpt Media endpoint. |
| 131 | * @param pool Pool to allocate memory for the stream. A large |
| 132 | * number of memory may be needed because jitter |
| 133 | * buffer needs to preallocate some storage. |
| 134 | * @param info Stream information. |
Benny Prijono | b04c9e0 | 2006-05-17 17:17:39 +0000 | [diff] [blame] | 135 | * @param tp Stream transport instance used to transmit |
| 136 | * and receive RTP/RTCP packets to/from the underlying |
| 137 | * transport. |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 138 | * @param user_data Arbitrary user data (for future callback feature). |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 139 | * @param p_stream Pointer to receive the media stream. |
| 140 | * |
| 141 | * @return PJ_SUCCESS on success. |
| 142 | */ |
| 143 | PJ_DECL(pj_status_t) pjmedia_stream_create(pjmedia_endpt *endpt, |
| 144 | pj_pool_t *pool, |
| 145 | const pjmedia_stream_info *info, |
Benny Prijono | b04c9e0 | 2006-05-17 17:17:39 +0000 | [diff] [blame] | 146 | pjmedia_transport *tp, |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 147 | void *user_data, |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 148 | pjmedia_stream **p_stream); |
| 149 | |
| 150 | /** |
| 151 | * Destroy the media stream. |
| 152 | * |
| 153 | * @param stream The media stream. |
| 154 | * |
| 155 | * @return PJ_SUCCESS on success. |
| 156 | */ |
| 157 | PJ_DECL(pj_status_t) pjmedia_stream_destroy(pjmedia_stream *stream); |
| 158 | |
Benny Prijono | 1d709a2 | 2006-04-27 23:48:08 +0000 | [diff] [blame] | 159 | |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 160 | /** |
Benny Prijono | 1d709a2 | 2006-04-27 23:48:08 +0000 | [diff] [blame] | 161 | * Get the media port interface of the stream. The media port interface |
| 162 | * declares put_frame() and get_frame() function, which is the only |
| 163 | * way for application to transmit and receive media frames from the |
| 164 | * stream. |
Benny Prijono | f04ffdd | 2006-02-21 00:11:18 +0000 | [diff] [blame] | 165 | * |
| 166 | * @param stream The media stream. |
| 167 | * @param p_port Pointer to receive the port interface. |
| 168 | * |
| 169 | * @return PJ_SUCCESS on success. |
| 170 | */ |
| 171 | PJ_DECL(pj_status_t) pjmedia_stream_get_port(pjmedia_stream *stream, |
| 172 | pjmedia_port **p_port ); |
| 173 | |
| 174 | |
| 175 | /** |
Benny Prijono | b04c9e0 | 2006-05-17 17:17:39 +0000 | [diff] [blame] | 176 | * Get the media transport object associated with this stream. |
| 177 | * |
| 178 | * @param st The media stream. |
| 179 | * |
| 180 | * @return The transport object being used by the stream. |
| 181 | */ |
| 182 | PJ_DECL(pjmedia_transport*) pjmedia_stream_get_transport(pjmedia_stream *st); |
| 183 | |
| 184 | |
| 185 | /** |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 186 | * Start the media stream. This will start the appropriate channels |
| 187 | * in the media stream, depending on the media direction that was set |
| 188 | * when the stream was created. |
| 189 | * |
| 190 | * @param stream The media stream. |
| 191 | * |
| 192 | * @return PJ_SUCCESS on success. |
| 193 | */ |
| 194 | PJ_DECL(pj_status_t) pjmedia_stream_start(pjmedia_stream *stream); |
| 195 | |
| 196 | |
| 197 | /** |
| 198 | * Get the stream statistics. |
| 199 | * |
| 200 | * @param stream The media stream. |
| 201 | * @param stat Media stream statistics. |
| 202 | * |
| 203 | * @return PJ_SUCCESS on success. |
| 204 | */ |
| 205 | PJ_DECL(pj_status_t) pjmedia_stream_get_stat( const pjmedia_stream *stream, |
Benny Prijono | 6996823 | 2006-04-06 19:29:03 +0000 | [diff] [blame] | 206 | pjmedia_rtcp_stat *stat); |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 207 | |
| 208 | /** |
| 209 | * Pause the individual channel in the stream. |
| 210 | * |
Benny Prijono | 274975a | 2006-02-15 12:24:23 +0000 | [diff] [blame] | 211 | * @param stream The media channel. |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 212 | * @param dir Which direction to pause. |
| 213 | * |
| 214 | * @return PJ_SUCCESS on success. |
| 215 | */ |
| 216 | PJ_DECL(pj_status_t) pjmedia_stream_pause( pjmedia_stream *stream, |
| 217 | pjmedia_dir dir); |
| 218 | |
| 219 | /** |
| 220 | * Resume the individual channel in the stream. |
| 221 | * |
Benny Prijono | 274975a | 2006-02-15 12:24:23 +0000 | [diff] [blame] | 222 | * @param stream The media channel. |
Benny Prijono | 1519e57 | 2006-02-08 22:43:39 +0000 | [diff] [blame] | 223 | * @param dir Which direction to resume. |
| 224 | * |
| 225 | * @return PJ_SUCCESS on success; |
| 226 | */ |
| 227 | PJ_DECL(pj_status_t) pjmedia_stream_resume(pjmedia_stream *stream, |
| 228 | pjmedia_dir dir); |
| 229 | |
Benny Prijono | 349a0f2 | 2006-02-22 09:21:09 +0000 | [diff] [blame] | 230 | /** |
| 231 | * Transmit DTMF to this stream. The DTMF will be transmitted uisng |
| 232 | * RTP telephone-events as described in RFC 2833. This operation is |
| 233 | * only valid for audio stream. |
| 234 | * |
| 235 | * @param stream The media stream. |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 236 | * @param ascii_digit String containing digits to be sent to remote. |
| 237 | * Currently the maximum number of digits are 32. |
Benny Prijono | 349a0f2 | 2006-02-22 09:21:09 +0000 | [diff] [blame] | 238 | * |
| 239 | * @return PJ_SUCCESS on success. |
| 240 | */ |
| 241 | PJ_DECL(pj_status_t) pjmedia_stream_dial_dtmf(pjmedia_stream *stream, |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 242 | const pj_str_t *ascii_digit); |
Benny Prijono | 349a0f2 | 2006-02-22 09:21:09 +0000 | [diff] [blame] | 243 | |
| 244 | |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 245 | /** |
| 246 | * Check if the stream has incoming DTMF digits in the incoming DTMF |
| 247 | * queue. Incoming DTMF digits received via RFC 2833 mechanism are |
| 248 | * saved in the incoming digits queue. |
| 249 | * |
| 250 | * @param stream The media stream. |
| 251 | * |
| 252 | * @return Non-zero (PJ_TRUE) if the stream has received DTMF |
| 253 | * digits in the . |
| 254 | */ |
| 255 | PJ_DECL(pj_bool_t) pjmedia_stream_check_dtmf(pjmedia_stream *stream); |
| 256 | |
| 257 | |
| 258 | /** |
Benny Prijono | b04c9e0 | 2006-05-17 17:17:39 +0000 | [diff] [blame] | 259 | * Retrieve the incoming DTMF digits from the stream, and remove the digits |
| 260 | * from stream's DTMF buffer. Note that the digits buffer will not be NULL |
| 261 | * terminated. |
Benny Prijono | 06c7094 | 2006-02-22 12:06:39 +0000 | [diff] [blame] | 262 | * |
| 263 | * @param stream The media stream. |
| 264 | * @param ascii_digits Buffer to receive the digits. The length of this |
| 265 | * buffer is indicated in the "size" argument. |
| 266 | * @param size On input, contains the maximum digits to be copied |
| 267 | * to the buffer. |
| 268 | * On output, it contains the actual digits that has |
| 269 | * been copied to the buffer. |
| 270 | * |
| 271 | * @return Non-zero (PJ_TRUE) if the stream has received DTMF |
| 272 | * digits in the . |
| 273 | */ |
| 274 | PJ_DECL(pj_status_t) pjmedia_stream_get_dtmf( pjmedia_stream *stream, |
| 275 | char *ascii_digits, |
| 276 | unsigned *size); |
| 277 | |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 278 | |
| 279 | /** |
Benny Prijono | 0875ae8 | 2006-12-26 00:11:48 +0000 | [diff] [blame] | 280 | * Set callback to be called upon receiving DTMF digits. If callback is |
| 281 | * registered, the stream will not buffer incoming DTMF but rather call |
| 282 | * the callback as soon as DTMF digit is received completely. |
| 283 | * |
| 284 | * @param stream The media stream. |
| 285 | * @param cb Callback to be called upon receiving DTMF digits. |
| 286 | * The DTMF digits will be given to the callback as |
| 287 | * ASCII digits. |
| 288 | * @param user_data User data to be returned back when the callback |
| 289 | * is called. |
| 290 | * |
| 291 | * @return PJ_SUCCESS on success. |
| 292 | */ |
| 293 | PJ_DECL(pj_status_t) |
| 294 | pjmedia_stream_set_dtmf_callback(pjmedia_stream *stream, |
| 295 | void (*cb)(pjmedia_stream*, |
| 296 | void *user_data, |
| 297 | int digit), |
| 298 | void *user_data); |
| 299 | |
| 300 | /** |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 301 | * @} |
| 302 | */ |
| 303 | |
| 304 | PJ_END_DECL |
| 305 | |
| 306 | |
| 307 | #endif /* __PJMEDIA_STREAM_H__ */ |