← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject/pjmedia/include/pjmedia/stream.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject/pjmedia/include/pjmedia/stream.h
1
 
/* $Id: stream.h 3553 2011-05-05 06:14:19Z nanang $ */
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 <pj/sock.h>
36
 
 
37
 
PJ_BEGIN_DECL
38
 
 
39
 
 
40
 
/**
41
 
 * @defgroup PJMED_STRM Streams
42
 
 * @ingroup PJMEDIA_PORT
43
 
 * @brief Communicating with remote peer via the network
44
 
 * @{
45
 
 *
46
 
 * A media stream is a bidirectional multimedia communication between two
47
 
 * endpoints. It corresponds to a media description (m= line) in SDP
48
 
 * session descriptor.
49
 
 *
50
 
 * A media stream consists of two unidirectional channels:
51
 
 *  - encoding channel, which transmits unidirectional media to remote, and
52
 
 *  - decoding channel, which receives unidirectional media from remote.
53
 
 *
54
 
 * A media stream exports media port interface (see @ref PJMEDIA_PORT)
55
 
 * and application normally uses this interface to interconnect the stream
56
 
 * to other PJMEDIA components.
57
 
 *
58
 
 * A media stream internally manages the following objects:
59
 
 *  - an instance of media codec (see @ref PJMEDIA_CODEC),
60
 
 *  - an @ref PJMED_JBUF,
61
 
 *  - two instances of RTP sessions (#pjmedia_rtp_session, one for each
62
 
 *    direction),
63
 
 *  - one instance of RTCP session (#pjmedia_rtcp_session),
64
 
 *  - and a reference to media transport to send and receive packets
65
 
 *    to/from the network (see @ref PJMEDIA_TRANSPORT).
66
 
 *
67
 
 * Streams are created by calling #pjmedia_stream_create(), specifying
68
 
 * #pjmedia_stream_info structure in the parameter. Application can construct
69
 
 * the #pjmedia_stream_info structure manually, or use 
70
 
 * #pjmedia_stream_info_from_sdp() or #pjmedia_session_info_from_sdp() 
71
 
 * functions to construct the #pjmedia_stream_info from local and remote 
72
 
 * SDP session descriptors.
73
 
 *
74
 
 * Application can also use @ref PJMEDIA_SESSION to indirectly create the
75
 
 * streams.
76
 
 */
77
 
 
78
 
/**
79
 
 * Opaque declaration for media channel.
80
 
 * Media channel is unidirectional flow of media from sender to
81
 
 * receiver.
82
 
 */
83
 
typedef struct pjmedia_channel pjmedia_channel;
84
 
 
85
 
/** 
86
 
 * This structure describes media stream information. Each media stream
87
 
 * corresponds to one "m=" line in SDP session descriptor, and it has
88
 
 * its own RTP/RTCP socket pair.
89
 
 */
90
 
struct pjmedia_stream_info
91
 
{
92
 
    pjmedia_type        type;       /**< Media type (audio, video)          */
93
 
    pjmedia_tp_proto    proto;      /**< Transport protocol (RTP/AVP, etc.) */
94
 
    pjmedia_dir         dir;        /**< Media direction.                   */
95
 
    pj_sockaddr         rem_addr;   /**< Remote RTP address                 */
96
 
    pj_sockaddr         rem_rtcp;   /**< Optional remote RTCP address. If
97
 
                                         sin_family is zero, the RTP address
98
 
                                         will be calculated from RTP.       */
99
 
#if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0)
100
 
    pj_bool_t           rtcp_xr_enabled;
101
 
                                    /**< Specify whether RTCP XR is enabled.*/
102
 
    pj_uint32_t         rtcp_xr_interval; /**< RTCP XR interval.            */
103
 
    pj_sockaddr         rtcp_xr_dest;/**<Additional remote RTCP XR address.
104
 
                                         This is useful for third-party (e.g:
105
 
                                         network monitor) to monitor the 
106
 
                                         stream. If sin_family is zero, 
107
 
                                         this will be ignored.              */
108
 
#endif
109
 
    pjmedia_codec_info  fmt;        /**< Incoming codec format info.        */
110
 
    pjmedia_codec_param *param;     /**< Optional codec param.              */
111
 
    unsigned            tx_pt;      /**< Outgoing codec paylaod type.       */
112
 
    unsigned            tx_maxptime;/**< Outgoing codec max ptime.          */
113
 
    int                 tx_event_pt;/**< Outgoing pt for telephone-events.  */
114
 
    int                 rx_event_pt;/**< Incoming pt for telephone-events.  */
115
 
    pj_uint32_t         ssrc;       /**< RTP SSRC.                          */
116
 
    pj_uint32_t         rtp_ts;     /**< Initial RTP timestamp.             */
117
 
    pj_uint16_t         rtp_seq;    /**< Initial RTP sequence number.       */
118
 
    pj_uint8_t          rtp_seq_ts_set;
119
 
                                    /**< Bitmask flags if initial RTP sequence 
120
 
                                         and/or timestamp for sender are set.
121
 
                                         bit 0/LSB : sequence flag 
122
 
                                         bit 1     : timestamp flag         */
123
 
    int                 jb_init;    /**< Jitter buffer init delay in msec.  
124
 
                                         (-1 for default).                  */
125
 
    int                 jb_min_pre; /**< Jitter buffer minimum prefetch
126
 
                                         delay in msec (-1 for default).    */
127
 
    int                 jb_max_pre; /**< Jitter buffer maximum prefetch
128
 
                                         delay in msec (-1 for default).    */
129
 
    int                 jb_max;     /**< Jitter buffer max delay in msec.   */
130
 
 
131
 
#if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0
132
 
    pj_bool_t           use_ka;     /**< Stream keep-alive and NAT hole punch
133
 
                                         (see #PJMEDIA_STREAM_ENABLE_KA)
134
 
                                         is enabled?                        */
135
 
#endif
136
 
};
137
 
 
138
 
 
139
 
/**
140
 
 * @see pjmedia_stream_info.
141
 
 */
142
 
typedef struct pjmedia_stream_info pjmedia_stream_info;
143
 
 
144
 
 
145
 
 
146
 
/**
147
 
 * Create a media stream based on the specified parameter. After the stream
148
 
 * has been created, application normally would want to get the media port 
149
 
 * interface of the streams, by calling pjmedia_stream_get_port(). The 
150
 
 * media port interface exports put_frame() and get_frame() function, used
151
 
 * to transmit and receive media frames from the stream.
152
 
 *
153
 
 * Without application calling put_frame() and get_frame(), there will be 
154
 
 * no media frames transmitted or received by the stream.
155
 
 *
156
 
 * @param endpt         Media endpoint.
157
 
 * @param pool          Pool to allocate memory for the stream. A large
158
 
 *                      number of memory may be needed because jitter
159
 
 *                      buffer needs to preallocate some storage.
160
 
 * @param info          Stream information.
161
 
 * @param tp            Stream transport instance used to transmit 
162
 
 *                      and receive RTP/RTCP packets to/from the underlying 
163
 
 *                      transport. 
164
 
 * @param user_data     Arbitrary user data (for future callback feature).
165
 
 * @param p_stream      Pointer to receive the media stream.
166
 
 *
167
 
 * @return              PJ_SUCCESS on success.
168
 
 */
169
 
PJ_DECL(pj_status_t) pjmedia_stream_create(pjmedia_endpt *endpt,
170
 
                                           pj_pool_t *pool,
171
 
                                           const pjmedia_stream_info *info,
172
 
                                           pjmedia_transport *tp,
173
 
                                           void *user_data,
174
 
                                           pjmedia_stream **p_stream);
175
 
 
176
 
/**
177
 
 * Destroy the media stream.
178
 
 *
179
 
 * @param stream        The media stream.
180
 
 *
181
 
 * @return              PJ_SUCCESS on success.
182
 
 */
183
 
PJ_DECL(pj_status_t) pjmedia_stream_destroy(pjmedia_stream *stream);
184
 
 
185
 
 
186
 
/**
187
 
 * Get the last frame type retreived from the jitter buffer.
188
 
 *
189
 
 * @param stream        The media stream.
190
 
 *
191
 
 * @return              Jitter buffer frame type.
192
 
 */
193
 
PJ_DEF(char) pjmedia_stream_get_last_jb_frame_type(pjmedia_stream *stream);
194
 
 
195
 
 
196
 
/**
197
 
 * Get the media port interface of the stream. The media port interface
198
 
 * declares put_frame() and get_frame() function, which is the only 
199
 
 * way for application to transmit and receive media frames from the
200
 
 * stream.
201
 
 *
202
 
 * @param stream        The media stream.
203
 
 * @param p_port        Pointer to receive the port interface.
204
 
 *
205
 
 * @return              PJ_SUCCESS on success.
206
 
 */
207
 
PJ_DECL(pj_status_t) pjmedia_stream_get_port(pjmedia_stream *stream,
208
 
                                             pjmedia_port **p_port );
209
 
 
210
 
 
211
 
/**
212
 
 * Get the media transport object associated with this stream.
213
 
 *
214
 
 * @param st            The media stream.
215
 
 *
216
 
 * @return              The transport object being used by the stream.
217
 
 */
218
 
PJ_DECL(pjmedia_transport*) pjmedia_stream_get_transport(pjmedia_stream *st);
219
 
 
220
 
 
221
 
/**
222
 
 * Start the media stream. This will start the appropriate channels
223
 
 * in the media stream, depending on the media direction that was set
224
 
 * when the stream was created.
225
 
 *
226
 
 * @param stream        The media stream.
227
 
 *
228
 
 * @return              PJ_SUCCESS on success.
229
 
 */
230
 
PJ_DECL(pj_status_t) pjmedia_stream_start(pjmedia_stream *stream);
231
 
 
232
 
 
233
 
/**
234
 
 * Get the stream statistics. See also
235
 
 * #pjmedia_stream_get_stat_jbuf()
236
 
 *
237
 
 * @param stream        The media stream.
238
 
 * @param stat          Media stream statistics.
239
 
 *
240
 
 * @return              PJ_SUCCESS on success.
241
 
 */
242
 
PJ_DECL(pj_status_t) pjmedia_stream_get_stat( const pjmedia_stream *stream,
243
 
                                              pjmedia_rtcp_stat *stat);
244
 
 
245
 
 
246
 
/**
247
 
 * Reset the stream statistics.
248
 
 *
249
 
 * @param stream        The media stream.
250
 
 *
251
 
 * @return              PJ_SUCCESS on success.
252
 
 */
253
 
PJ_DECL(pj_status_t) pjmedia_stream_reset_stat(pjmedia_stream *stream);
254
 
 
255
 
 
256
 
#if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0)
257
 
/**
258
 
 * Get the stream extended report statistics (RTCP XR).
259
 
 *
260
 
 * @param stream        The media stream.
261
 
 * @param stat          Media stream extended report statistics.
262
 
 *
263
 
 * @return              PJ_SUCCESS on success.
264
 
 */
265
 
PJ_DECL(pj_status_t) pjmedia_stream_get_stat_xr( const pjmedia_stream *stream,
266
 
                                                 pjmedia_rtcp_xr_stat *stat);
267
 
#endif
268
 
 
269
 
/**
270
 
 * Get current jitter buffer state. See also
271
 
 * #pjmedia_stream_get_stat()
272
 
 *
273
 
 * @param stream        The media stream.
274
 
 * @param state         Jitter buffer state.
275
 
 *
276
 
 * @return              PJ_SUCCESS on success.
277
 
 */
278
 
PJ_DECL(pj_status_t) pjmedia_stream_get_stat_jbuf(const pjmedia_stream *stream,
279
 
                                                  pjmedia_jb_state *state);
280
 
 
281
 
 
282
 
/**
283
 
 * Pause the individual channel in the stream.
284
 
 *
285
 
 * @param stream        The media channel.
286
 
 * @param dir           Which direction to pause.
287
 
 *
288
 
 * @return              PJ_SUCCESS on success.
289
 
 */
290
 
PJ_DECL(pj_status_t) pjmedia_stream_pause( pjmedia_stream *stream,
291
 
                                           pjmedia_dir dir);
292
 
 
293
 
/**
294
 
 * Resume the individual channel in the stream.
295
 
 *
296
 
 * @param stream        The media channel.
297
 
 * @param dir           Which direction to resume.
298
 
 *
299
 
 * @return              PJ_SUCCESS on success;
300
 
 */
301
 
PJ_DECL(pj_status_t) pjmedia_stream_resume(pjmedia_stream *stream,
302
 
                                           pjmedia_dir dir);
303
 
 
304
 
/**
305
 
 * Transmit DTMF to this stream. The DTMF will be transmitted uisng
306
 
 * RTP telephone-events as described in RFC 2833. This operation is
307
 
 * only valid for audio stream.
308
 
 *
309
 
 * @param stream        The media stream.
310
 
 * @param ascii_digit   String containing digits to be sent to remote.
311
 
 *                      Currently the maximum number of digits are 32.
312
 
 *
313
 
 * @return              PJ_SUCCESS on success.
314
 
 */
315
 
PJ_DECL(pj_status_t) pjmedia_stream_dial_dtmf(pjmedia_stream *stream,
316
 
                                              const pj_str_t *ascii_digit);
317
 
 
318
 
 
319
 
/**
320
 
 * Check if the stream has incoming DTMF digits in the incoming DTMF
321
 
 * queue. Incoming DTMF digits received via RFC 2833 mechanism are
322
 
 * saved in the incoming digits queue.
323
 
 *
324
 
 * @param stream        The media stream.
325
 
 *
326
 
 * @return              Non-zero (PJ_TRUE) if the stream has received DTMF
327
 
 *                      digits in the .
328
 
 */
329
 
PJ_DECL(pj_bool_t) pjmedia_stream_check_dtmf(pjmedia_stream *stream);
330
 
 
331
 
 
332
 
/**
333
 
 * Retrieve the incoming DTMF digits from the stream, and remove the digits
334
 
 * from stream's DTMF buffer. Note that the digits buffer will not be NULL 
335
 
 * terminated.
336
 
 *
337
 
 * @param stream        The media stream.
338
 
 * @param ascii_digits  Buffer to receive the digits. The length of this
339
 
 *                      buffer is indicated in the "size" argument.
340
 
 * @param size          On input, contains the maximum digits to be copied
341
 
 *                      to the buffer.
342
 
 *                      On output, it contains the actual digits that has
343
 
 *                      been copied to the buffer.
344
 
 *
345
 
 * @return              Non-zero (PJ_TRUE) if the stream has received DTMF
346
 
 *                      digits in the .
347
 
 */
348
 
PJ_DECL(pj_status_t) pjmedia_stream_get_dtmf( pjmedia_stream *stream,
349
 
                                              char *ascii_digits,
350
 
                                              unsigned *size);
351
 
 
352
 
 
353
 
/**
354
 
 * Set callback to be called upon receiving DTMF digits. If callback is
355
 
 * registered, the stream will not buffer incoming DTMF but rather call
356
 
 * the callback as soon as DTMF digit is received completely.
357
 
 *
358
 
 * @param stream        The media stream.
359
 
 * @param cb            Callback to be called upon receiving DTMF digits.
360
 
 *                      The DTMF digits will be given to the callback as
361
 
 *                      ASCII digits.
362
 
 * @param user_data     User data to be returned back when the callback
363
 
 *                      is called.
364
 
 *
365
 
 * @return              PJ_SUCCESS on success.
366
 
 */
367
 
PJ_DECL(pj_status_t)
368
 
pjmedia_stream_set_dtmf_callback(pjmedia_stream *stream,
369
 
                                 void (*cb)(pjmedia_stream*, 
370
 
                                            void *user_data, 
371
 
                                            int digit), 
372
 
                                 void *user_data);
373
 
 
374
 
/**
375
 
 * @}
376
 
 */
377
 
 
378
 
PJ_END_DECL
379
 
 
380
 
 
381
 
#endif  /* __PJMEDIA_STREAM_H__ */