← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/stream.h
 
1
/* $Id: stream.h 3841 2011-10-24 09:28:13Z ming $ */
 
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__ */