← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia/vid_stream.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia/vid_stream.h
 
1
/* $Id: vid_stream.h 4043 2012-04-12 13:41:50Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2011 Teluu Inc. (http://www.teluu.com)
 
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_VID_STREAM_H__
 
20
#define __PJMEDIA_VID_STREAM_H__
 
21
 
 
22
 
 
23
/**
 
24
 * @file vid_stream.h
 
25
 * @brief Video Stream.
 
26
 */
 
27
 
 
28
#include <pjmedia/endpoint.h>
 
29
#include <pjmedia/jbuf.h>
 
30
#include <pjmedia/port.h>
 
31
#include <pjmedia/rtcp.h>
 
32
#include <pjmedia/transport.h>
 
33
#include <pjmedia/vid_codec.h>
 
34
#include <pj/sock.h>
 
35
 
 
36
PJ_BEGIN_DECL
 
37
 
 
38
 
 
39
/**
 
40
 * @defgroup PJMED_VID_STRM Video streams
 
41
 * @ingroup PJMEDIA_PORT
 
42
 * @brief Video communication via the network
 
43
 * @{
 
44
 *
 
45
 * A video stream is a bidirectional video communication between two
 
46
 * endpoints. It corresponds to a video media description ("m=video" line)
 
47
 * in SDP session descriptor.
 
48
 *
 
49
 * A video stream consists of two unidirectional channels:
 
50
 *  - encoding channel, which transmits unidirectional video to remote, and
 
51
 *  - decoding channel, which receives unidirectional media from remote.
 
52
 *
 
53
 * A video stream exports two media port interface (see @ref PJMEDIA_PORT),
 
54
 * one for each direction, and application normally uses this interface to
 
55
 * interconnect the stream to other PJMEDIA components, e.g: the video
 
56
 * capture port supplies frames to the encoding port and video renderer
 
57
 * consumes frames from the decoding port.
 
58
 *
 
59
 * A video stream internally manages the following objects:
 
60
 *  - an instance of video codec (see @ref PJMEDIA_VID_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 video transport to send and receive packets
 
66
 *    to/from the network (see @ref PJMEDIA_TRANSPORT).
 
67
 *
 
68
 * Video streams are created by calling #pjmedia_vid_stream_create(),
 
69
 * specifying #pjmedia_stream_info structure in the parameter. Application
 
70
 * can construct the #pjmedia_vid_stream_info structure manually, or use 
 
71
 * #pjmedia_vid_stream_info_from_sdp() function to construct the
 
72
 * #pjmedia_vid stream_info from local and remote SDP session descriptors.
 
73
 */
 
74
 
 
75
 
 
76
/**
 
77
 * Enumeration of video stream sending rate control.
 
78
 */
 
79
typedef enum pjmedia_vid_stream_rc_method
 
80
{
 
81
    /**
 
82
     * No sending rate control. All outgoing RTP packets will be transmitted
 
83
     * immediately right after encoding process is done.
 
84
     */
 
85
    PJMEDIA_VID_STREAM_RC_NONE              = 0,
 
86
 
 
87
    /**
 
88
     * Simple blocking. Each outgoing RTP packet transmission may be delayed
 
89
     * to avoid peak bandwidth that is much higher than specified. The thread
 
90
     * invoking the video stream put_frame(), e.g: video capture device thread,
 
91
     * will be blocked whenever transmission delay takes place.
 
92
     */
 
93
    PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING   = 1
 
94
 
 
95
} pjmedia_vid_stream_rc_method;
 
96
 
 
97
 
 
98
/**
 
99
 * Structure of configuration settings for video stream sending rate control.
 
100
 */
 
101
typedef struct pjmedia_vid_stream_rc_config
 
102
{
 
103
    /**
 
104
     * Rate control method.
 
105
     *
 
106
     * Default: PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING.
 
107
     */
 
108
    pjmedia_vid_stream_rc_method    method;
 
109
 
 
110
    /**
 
111
     * Upstream/outgoing bandwidth. If this is set to zero, the video stream
 
112
     * will use codec maximum bitrate setting.
 
113
     *
 
114
     * Default: 0 (follow codec maximum bitrate).
 
115
     */
 
116
    unsigned                        bandwidth;
 
117
 
 
118
} pjmedia_vid_stream_rc_config;
 
119
 
 
120
 
 
121
/** 
 
122
 * This structure describes video stream information. Each video stream
 
123
 * corresponds to one "m=" line in SDP session descriptor, and it has
 
124
 * its own RTP/RTCP socket pair.
 
125
 */
 
126
typedef struct pjmedia_vid_stream_info
 
127
{
 
128
    pjmedia_type        type;       /**< Media type (audio, video)          */
 
129
    pjmedia_tp_proto    proto;      /**< Transport protocol (RTP/AVP, etc.) */
 
130
    pjmedia_dir         dir;        /**< Media direction.                   */
 
131
    pj_sockaddr         rem_addr;   /**< Remote RTP address                 */
 
132
    pj_sockaddr         rem_rtcp;   /**< Optional remote RTCP address. If
 
133
                                         sin_family is zero, the RTP address
 
134
                                         will be calculated from RTP.       */
 
135
    unsigned            tx_pt;      /**< Outgoing codec paylaod type.       */
 
136
    unsigned            rx_pt;      /**< Incoming codec paylaod type.       */
 
137
    pj_uint32_t         ssrc;       /**< RTP SSRC.                          */
 
138
    pj_uint32_t         rtp_ts;     /**< Initial RTP timestamp.             */
 
139
    pj_uint16_t         rtp_seq;    /**< Initial RTP sequence number.       */
 
140
    pj_uint8_t          rtp_seq_ts_set;
 
141
                                    /**< Bitmask flags if initial RTP sequence 
 
142
                                         and/or timestamp for sender are set.
 
143
                                         bit 0/LSB : sequence flag 
 
144
                                         bit 1     : timestamp flag         */
 
145
    int                 jb_init;    /**< Jitter buffer init delay in msec.  
 
146
                                         (-1 for default).                  */
 
147
    int                 jb_min_pre; /**< Jitter buffer minimum prefetch
 
148
                                         delay in msec (-1 for default).    */
 
149
    int                 jb_max_pre; /**< Jitter buffer maximum prefetch
 
150
                                         delay in msec (-1 for default).    */
 
151
    int                 jb_max;     /**< Jitter buffer max delay in msec.   */
 
152
 
 
153
#if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0
 
154
    pj_bool_t           use_ka;     /**< Stream keep-alive and NAT hole punch
 
155
                                         (see #PJMEDIA_STREAM_ENABLE_KA)
 
156
                                         is enabled?                        */
 
157
#endif
 
158
 
 
159
    pjmedia_vid_codec_info   codec_info;  /**< Incoming codec format info.  */
 
160
    pjmedia_vid_codec_param *codec_param; /**< Optional codec param.        */
 
161
 
 
162
    pj_bool_t           rtcp_sdes_bye_disabled; 
 
163
                                    /**< Disable automatic sending of RTCP
 
164
                                         SDES and BYE.                      */
 
165
 
 
166
    pjmedia_vid_stream_rc_config rc_cfg;
 
167
                                    /**< Stream send rate control settings. */
 
168
} pjmedia_vid_stream_info;
 
169
 
 
170
 
 
171
/**
 
172
 * This function will initialize the video stream info based on information
 
173
 * in both SDP session descriptors for the specified stream index. 
 
174
 * The remaining information will be taken from default codec parameters. 
 
175
 * If socket info array is specified, the socket will be copied to the 
 
176
 * session info as well.
 
177
 *
 
178
 * @param si            Stream info structure to be initialized.
 
179
 * @param pool          Pool to allocate memory.
 
180
 * @param endpt         PJMEDIA endpoint instance.
 
181
 * @param local         Local SDP session descriptor.
 
182
 * @param remote        Remote SDP session descriptor.
 
183
 * @param stream_idx    Media stream index in the session descriptor.
 
184
 *
 
185
 * @return              PJ_SUCCESS if stream info is successfully initialized.
 
186
 */
 
187
PJ_DECL(pj_status_t)
 
188
pjmedia_vid_stream_info_from_sdp(pjmedia_vid_stream_info *si,
 
189
                                 pj_pool_t *pool,
 
190
                                 pjmedia_endpt *endpt,
 
191
                                 const pjmedia_sdp_session *local,
 
192
                                 const pjmedia_sdp_session *remote,
 
193
                                 unsigned stream_idx);
 
194
 
 
195
 
 
196
/**
 
197
 * Initialize the video stream rate control with default settings.
 
198
 *
 
199
 * @param cfg           Video stream rate control structure to be initialized.
 
200
 */
 
201
PJ_DECL(void)
 
202
pjmedia_vid_stream_rc_config_default(pjmedia_vid_stream_rc_config *cfg);
 
203
 
 
204
 
 
205
/*
 
206
 * Opaque declaration for video stream.
 
207
 */
 
208
typedef struct pjmedia_vid_stream pjmedia_vid_stream;
 
209
 
 
210
 
 
211
/**
 
212
 * Create a video stream based on the specified parameter. After the video
 
213
 * stream has been created, application normally would want to get the media
 
214
 * port interface of the stream, by calling pjmedia_vid_stream_get_port().
 
215
 * The media port interface exports put_frame() and get_frame() function,
 
216
 * used to transmit and receive media frames from the stream.
 
217
 *
 
218
 * Without application calling put_frame() and get_frame(), there will be 
 
219
 * no media frames transmitted or received by the stream.
 
220
 *
 
221
 * @param endpt         Media endpoint.
 
222
 * @param pool          Optional pool to allocate memory for the stream. If
 
223
 *                      this is not specified, one will be created internally.
 
224
 *                      A large number of memory may be needed because jitter
 
225
 *                      buffer needs to preallocate some storage.
 
226
 * @param info          Stream information to create the stream. Upon return,
 
227
 *                      this info will be updated with the information from
 
228
 *                      the instantiated codec. Note that if the "pool"
 
229
 *                      argument is NULL, some fields in this "info" parameter
 
230
 *                      will be allocated from the internal pool of the
 
231
 *                      stream, which means that they will only remain valid
 
232
 *                      as long as the stream is not destroyed.
 
233
 * @param tp            Media transport instance used to transmit and receive
 
234
 *                      RTP/RTCP packets to/from the underlying network.
 
235
 * @param user_data     Arbitrary user data (for future callback feature).
 
236
 * @param p_stream      Pointer to receive the video stream.
 
237
 *
 
238
 * @return              PJ_SUCCESS on success.
 
239
 */
 
240
PJ_DECL(pj_status_t) pjmedia_vid_stream_create(
 
241
                                        pjmedia_endpt *endpt,
 
242
                                        pj_pool_t *pool,
 
243
                                        pjmedia_vid_stream_info *info,
 
244
                                        pjmedia_transport *tp,
 
245
                                        void *user_data,
 
246
                                        pjmedia_vid_stream **p_stream);
 
247
 
 
248
/**
 
249
 * Destroy the video stream.
 
250
 *
 
251
 * @param stream        The video stream.
 
252
 *
 
253
 * @return              PJ_SUCCESS on success.
 
254
 */
 
255
PJ_DECL(pj_status_t) pjmedia_vid_stream_destroy(pjmedia_vid_stream *stream);
 
256
 
 
257
 
 
258
/**
 
259
 * Get the media port interface of the stream. The media port interface
 
260
 * declares put_frame() and get_frame() function, which is the only 
 
261
 * way for application to transmit and receive media frames from the
 
262
 * stream. As bidirectional video streaming may have different video
 
263
 * formats in the encoding and decoding direction, there are two media
 
264
 * ports exported by the video stream, one for each direction.
 
265
 *
 
266
 * @param stream        The video stream.
 
267
 * @param dir           The video direction.
 
268
 * @param p_port        Pointer to receive the port interface.
 
269
 *
 
270
 * @return              PJ_SUCCESS on success.
 
271
 */
 
272
PJ_DECL(pj_status_t) pjmedia_vid_stream_get_port(
 
273
                                            pjmedia_vid_stream *stream,
 
274
                                            pjmedia_dir dir,
 
275
                                            pjmedia_port **p_port);
 
276
 
 
277
 
 
278
/**
 
279
 * Get the media transport object associated with this stream.
 
280
 *
 
281
 * @param st            The video stream.
 
282
 *
 
283
 * @return              The transport object being used by the stream.
 
284
 */
 
285
PJ_DECL(pjmedia_transport*) pjmedia_vid_stream_get_transport(
 
286
                                            pjmedia_vid_stream *st);
 
287
 
 
288
 
 
289
/**
 
290
 * Get the stream statistics. See also #pjmedia_stream_get_stat_jbuf()
 
291
 *
 
292
 * @param stream        The video stream.
 
293
 * @param stat          Media stream statistics.
 
294
 *
 
295
 * @return              PJ_SUCCESS on success.
 
296
 */
 
297
PJ_DECL(pj_status_t) pjmedia_vid_stream_get_stat(
 
298
                                            const pjmedia_vid_stream *stream,
 
299
                                            pjmedia_rtcp_stat *stat);
 
300
 
 
301
/**
 
302
 * Reset the video stream statistics.
 
303
 *
 
304
 * @param stream        The video stream.
 
305
 *
 
306
 * @return              PJ_SUCCESS on success.
 
307
 */
 
308
PJ_DECL(pj_status_t) pjmedia_vid_stream_reset_stat(pjmedia_vid_stream *stream);
 
309
 
 
310
 
 
311
/**
 
312
 * Get current jitter buffer state. See also #pjmedia_stream_get_stat()
 
313
 *
 
314
 * @param stream        The video stream.
 
315
 * @param state         Jitter buffer state.
 
316
 *
 
317
 * @return              PJ_SUCCESS on success.
 
318
 */
 
319
PJ_DECL(pj_status_t) pjmedia_vid_stream_get_stat_jbuf(
 
320
                                            const pjmedia_vid_stream *stream,
 
321
                                            pjmedia_jb_state *state);
 
322
 
 
323
 
 
324
/**
 
325
 * Get the stream info.
 
326
 *
 
327
 * @param stream        The video stream.
 
328
 * @param info          Video stream info.
 
329
 *
 
330
 * @return              PJ_SUCCESS on success.
 
331
 */
 
332
PJ_DECL(pj_status_t) pjmedia_vid_stream_get_info(
 
333
                                            const pjmedia_vid_stream *stream,
 
334
                                            pjmedia_vid_stream_info *info);
 
335
 
 
336
 
 
337
/**
 
338
 * Start the video stream. This will start the appropriate channels
 
339
 * in the video stream, depending on the video direction that was set
 
340
 * when the stream was created.
 
341
 *
 
342
 * @param stream        The video stream.
 
343
 *
 
344
 * @return              PJ_SUCCESS on success.
 
345
 */
 
346
PJ_DECL(pj_status_t) pjmedia_vid_stream_start(pjmedia_vid_stream *stream);
 
347
 
 
348
 
 
349
/**
 
350
 * Query if the stream is started on the specified direction.
 
351
 *
 
352
 * @param stream        The video stream.
 
353
 * @param dir           The direction to be checked.
 
354
 *
 
355
 * @return              PJ_TRUE if stream is started.
 
356
 */
 
357
PJ_DECL(pj_bool_t) pjmedia_vid_stream_is_running(pjmedia_vid_stream *stream,
 
358
                                                 pjmedia_dir dir);
 
359
 
 
360
/**
 
361
 * Pause stream channels.
 
362
 *
 
363
 * @param stream        The video stream.
 
364
 * @param dir           Which channel direction to pause.
 
365
 *
 
366
 * @return              PJ_SUCCESS on success.
 
367
 */
 
368
PJ_DECL(pj_status_t) pjmedia_vid_stream_pause(pjmedia_vid_stream *stream,
 
369
                                              pjmedia_dir dir);
 
370
 
 
371
/**
 
372
 * Resume stream channels.
 
373
 *
 
374
 * @param stream        The video stream.
 
375
 * @param dir           Which channel direction to resume.
 
376
 *
 
377
 * @return              PJ_SUCCESS on success;
 
378
 */
 
379
PJ_DECL(pj_status_t) pjmedia_vid_stream_resume(pjmedia_vid_stream *stream,
 
380
                                               pjmedia_dir dir);
 
381
 
 
382
 
 
383
/**
 
384
 * Force stream to send video keyframe on the next transmission.
 
385
 *
 
386
 * @param stream        The video stream.
 
387
 *
 
388
 * @return              PJ_SUCCESS on success;
 
389
 */
 
390
PJ_DECL(pj_status_t) pjmedia_vid_stream_send_keyframe(
 
391
                                                pjmedia_vid_stream *stream);
 
392
 
 
393
 
 
394
/**
 
395
 * Send RTCP SDES for the media stream.
 
396
 *
 
397
 * @param stream        The media stream.
 
398
 *
 
399
 * @return              PJ_SUCCESS on success.
 
400
 */
 
401
PJ_DECL(pj_status_t) pjmedia_vid_stream_send_rtcp_sdes(
 
402
                                                pjmedia_vid_stream *stream);
 
403
 
 
404
 
 
405
/**
 
406
 * Send RTCP BYE for the media stream.
 
407
 *
 
408
 * @param stream        The media stream.
 
409
 *
 
410
 * @return              PJ_SUCCESS on success.
 
411
 */
 
412
PJ_DECL(pj_status_t) pjmedia_vid_stream_send_rtcp_bye(
 
413
                                                pjmedia_vid_stream *stream);
 
414
 
 
415
 
 
416
/**
 
417
 * @}
 
418
 */
 
419
 
 
420
PJ_END_DECL
 
421
 
 
422
 
 
423
#endif  /* __PJMEDIA_VID_STREAM_H__ */