← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/rtp.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
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.0.1/pjmedia/include/pjmedia/rtp.h
1
 
/* $Id: rtp.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_RTP_H__
21
 
#define __PJMEDIA_RTP_H__
22
 
 
23
 
 
24
 
/**
25
 
 * @file rtp.h
26
 
 * @brief RTP packet and RTP session declarations.
27
 
 */
28
 
#include <pjmedia/types.h>
29
 
 
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
 
34
 
/**
35
 
 * @defgroup PJMED_RTP RTP Session and Encapsulation (RFC 3550)
36
 
 * @ingroup PJMEDIA_SESSION
37
 
 * @brief RTP format and session management
38
 
 * @{
39
 
 *
40
 
 * The RTP module is designed to be dependent only to PJLIB, it does not depend
41
 
 * on any other parts of PJMEDIA library. The RTP module does not even depend
42
 
 * on any transports (sockets), to promote even more use, such as in DSP
43
 
 * development (where transport may be handled by different processor).
44
 
 *
45
 
 * An RTCP implementation is available, in separate module. Please see
46
 
 * @ref PJMED_RTCP.
47
 
 *
48
 
 * The functions that are provided by this module:
49
 
 *  - creating RTP header for each outgoing packet.
50
 
 *  - decoding RTP packet into RTP header and payload.
51
 
 *  - provide simple RTP session management (sequence number, etc.)
52
 
 *
53
 
 * The RTP module does not use any dynamic memory at all.
54
 
 *
55
 
 * \section P1 How to Use the RTP Module
56
 
 *
57
 
 * First application must call #pjmedia_rtp_session_init() to initialize the RTP
58
 
 * session.
59
 
 *
60
 
 * When application wants to send RTP packet, it needs to call
61
 
 * #pjmedia_rtp_encode_rtp() to build the RTP header. Note that this WILL NOT build
62
 
 * the complete RTP packet, but instead only the header. Application can
63
 
 * then either concatenate the header with the payload, or send the two
64
 
 * fragments (the header and the payload) using scatter-gather transport API
65
 
 * (e.g. \a sendv()).
66
 
 *
67
 
 * When application receives an RTP packet, first it should call
68
 
 * #pjmedia_rtp_decode_rtp to decode RTP header and payload, then it should call
69
 
 * #pjmedia_rtp_session_update to check whether we can process the RTP payload,
70
 
 * and to let the RTP session updates its internal status. The decode function
71
 
 * is guaranteed to point the payload to the correct position regardless of
72
 
 * any options present in the RTP packet.
73
 
 *
74
 
 */
75
 
 
76
 
#ifdef _MSC_VER
77
 
#   pragma warning(disable:4214)    // bit field types other than int
78
 
#endif
79
 
 
80
 
 
81
 
/**
82
 
 * RTP packet header. Note that all RTP functions here will work with this
83
 
 * header in network byte order.
84
 
 */
85
 
#pragma pack(1)
86
 
struct pjmedia_rtp_hdr
87
 
{
88
 
#if defined(PJ_IS_BIG_ENDIAN) && (PJ_IS_BIG_ENDIAN!=0)
89
 
    pj_uint16_t v:2;            /**< packet type/version            */
90
 
    pj_uint16_t p:1;            /**< padding flag                   */
91
 
    pj_uint16_t x:1;            /**< extension flag                 */
92
 
    pj_uint16_t cc:4;           /**< CSRC count                     */
93
 
    pj_uint16_t m:1;            /**< marker bit                     */
94
 
    pj_uint16_t pt:7;           /**< payload type                   */
95
 
#else
96
 
    pj_uint16_t cc:4;           /**< CSRC count                     */
97
 
    pj_uint16_t x:1;            /**< header extension flag          */
98
 
    pj_uint16_t p:1;            /**< padding flag                   */
99
 
    pj_uint16_t v:2;            /**< packet type/version            */
100
 
    pj_uint16_t pt:7;           /**< payload type                   */
101
 
    pj_uint16_t m:1;            /**< marker bit                     */
102
 
#endif
103
 
    pj_uint16_t seq;            /**< sequence number                */
104
 
    pj_uint32_t ts;             /**< timestamp                      */
105
 
    pj_uint32_t ssrc;           /**< synchronization source         */
106
 
};
107
 
#pragma pack()
108
 
 
109
 
/**
110
 
 * @see pjmedia_rtp_hdr
111
 
 */
112
 
typedef struct pjmedia_rtp_hdr pjmedia_rtp_hdr;
113
 
 
114
 
 
115
 
/**
116
 
 * RTP extendsion header.
117
 
 */
118
 
struct pjmedia_rtp_ext_hdr
119
 
{
120
 
    pj_uint16_t profile_data;   /**< Profile data.          */
121
 
    pj_uint16_t length;         /**< Length.                */
122
 
};
123
 
 
124
 
/**
125
 
 * @see pjmedia_rtp_ext_hdr
126
 
 */
127
 
typedef struct pjmedia_rtp_ext_hdr pjmedia_rtp_ext_hdr;
128
 
 
129
 
 
130
 
#pragma pack(1)
131
 
 
132
 
/**
133
 
 * Declaration for DTMF telephony-events (RFC2833).
134
 
 */
135
 
struct pjmedia_rtp_dtmf_event
136
 
{
137
 
    pj_uint8_t  event;      /**< Event type ID.     */
138
 
    pj_uint8_t  e_vol;      /**< Event volume.      */
139
 
    pj_uint16_t duration;   /**< Event duration.    */
140
 
};
141
 
 
142
 
/**
143
 
 * @see pjmedia_rtp_dtmf_event
144
 
 */
145
 
typedef struct pjmedia_rtp_dtmf_event pjmedia_rtp_dtmf_event;
146
 
 
147
 
#pragma pack()
148
 
 
149
 
 
150
 
/**
151
 
 * A generic sequence number management, used by both RTP and RTCP.
152
 
 */
153
 
struct pjmedia_rtp_seq_session
154
 
{
155
 
    pj_uint16_t     max_seq;        /**< Highest sequence number heard      */
156
 
    pj_uint32_t     cycles;         /**< Shifted count of seq number cycles */
157
 
    pj_uint32_t     base_seq;       /**< Base seq number                    */
158
 
    pj_uint32_t     bad_seq;        /**< Last 'bad' seq number + 1          */
159
 
    pj_uint32_t     probation;      /**< Sequ. packets till source is valid */
160
 
};
161
 
 
162
 
/**
163
 
 * @see pjmedia_rtp_seq_session
164
 
 */
165
 
typedef struct pjmedia_rtp_seq_session pjmedia_rtp_seq_session;
166
 
 
167
 
 
168
 
/**
169
 
 * RTP session descriptor.
170
 
 */
171
 
struct pjmedia_rtp_session
172
 
{
173
 
    pjmedia_rtp_hdr         out_hdr;    /**< Saved hdr for outgoing pkts.   */
174
 
    pjmedia_rtp_seq_session seq_ctrl;   /**< Sequence number management.    */
175
 
    pj_uint16_t             out_pt;     /**< Default outgoing payload type. */
176
 
    pj_uint32_t             out_extseq; /**< Outgoing extended seq #.       */
177
 
    pj_uint32_t             peer_ssrc;  /**< Peer SSRC.                     */
178
 
    pj_uint32_t             received;   /**< Number of received packets.    */
179
 
};
180
 
 
181
 
/**
182
 
 * @see pjmedia_rtp_session
183
 
 */
184
 
typedef struct pjmedia_rtp_session pjmedia_rtp_session;
185
 
 
186
 
 
187
 
/**
188
 
 * This structure is used to receive additional information about the
189
 
 * state of incoming RTP packet.
190
 
 */
191
 
struct pjmedia_rtp_status
192
 
{
193
 
    union {
194
 
        struct flag {
195
 
            int bad:1;      /**< General flag to indicate that sequence is
196
 
                                 bad, and application should not process
197
 
                                 this packet. More information will be given
198
 
                                 in other flags.                            */
199
 
            int badpt:1;    /**< Bad payload type.                          */
200
 
            int badssrc:1;  /**< Bad SSRC                                   */
201
 
            int dup:1;      /**< Indicates duplicate packet                 */
202
 
            int outorder:1; /**< Indicates out of order packet              */
203
 
            int probation:1;/**< Indicates that session is in probation
204
 
                                 until more packets are received.           */
205
 
            int restart:1;  /**< Indicates that sequence number has made
206
 
                                 a large jump, and internal base sequence
207
 
                                 number has been adjusted.                  */
208
 
        } flag;             /**< Status flags.                              */
209
 
 
210
 
        pj_uint16_t value;  /**< Status value, to conveniently address all
211
 
                                 flags.                                     */
212
 
 
213
 
    } status;               /**< Status information union.                  */
214
 
 
215
 
    pj_uint16_t diff;       /**< Sequence number difference from previous
216
 
                                 packet. Normally the value should be 1.
217
 
                                 Value greater than one may indicate packet
218
 
                                 loss. If packet with lower sequence is
219
 
                                 received, the value will be set to zero.
220
 
                                 If base sequence has been restarted, the
221
 
                                 value will be one.                         */
222
 
};
223
 
 
224
 
 
225
 
/**
226
 
 * RTP session settings.
227
 
 */
228
 
typedef struct pjmedia_rtp_session_setting
229
 
{
230
 
    pj_uint8_t       flags;         /**< Bitmask flags to specify whether such
231
 
                                         field is set. Bitmask contents are:
232
 
                                         (bit #0 is LSB)
233
 
                                         bit #0: default payload type
234
 
                                         bit #1: sender SSRC
235
 
                                         bit #2: sequence
236
 
                                         bit #3: timestamp                  */
237
 
    int              default_pt;    /**< Default payload type.              */
238
 
    pj_uint32_t      sender_ssrc;   /**< Sender SSRC.                       */
239
 
    pj_uint16_t      seq;           /**< Sequence.                          */
240
 
    pj_uint32_t      ts;            /**< Timestamp.                         */
241
 
} pjmedia_rtp_session_setting;
242
 
 
243
 
 
244
 
/**
245
 
 * @see pjmedia_rtp_status
246
 
 */
247
 
typedef struct pjmedia_rtp_status pjmedia_rtp_status;
248
 
 
249
 
 
250
 
/**
251
 
 * This function will initialize the RTP session according to given parameters.
252
 
 *
253
 
 * @param ses           The session.
254
 
 * @param default_pt    Default payload type.
255
 
 * @param sender_ssrc   SSRC used for outgoing packets, in host byte order.
256
 
 *
257
 
 * @return              PJ_SUCCESS if successfull.
258
 
 */
259
 
PJ_DECL(pj_status_t) pjmedia_rtp_session_init( pjmedia_rtp_session *ses,
260
 
                                               int default_pt,
261
 
                                               pj_uint32_t sender_ssrc );
262
 
 
263
 
/**
264
 
 * This function will initialize the RTP session according to given parameters
265
 
 * defined in RTP session settings.
266
 
 *
267
 
 * @param ses           The session.
268
 
 * @param settings      RTP session settings.
269
 
 *
270
 
 * @return              PJ_SUCCESS if successfull.
271
 
 */
272
 
PJ_DECL(pj_status_t) pjmedia_rtp_session_init2(
273
 
                                    pjmedia_rtp_session *ses,
274
 
                                    pjmedia_rtp_session_setting settings);
275
 
 
276
 
 
277
 
/**
278
 
 * Create the RTP header based on arguments and current state of the RTP
279
 
 * session.
280
 
 *
281
 
 * @param ses           The session.
282
 
 * @param pt            Payload type.
283
 
 * @param m             Marker flag.
284
 
 * @param payload_len   Payload length in bytes.
285
 
 * @param ts_len        Timestamp length.
286
 
 * @param rtphdr        Upon return will point to RTP packet header.
287
 
 * @param hdrlen        Upon return will indicate the size of RTP packet header
288
 
 *
289
 
 * @return              PJ_SUCCESS if successfull.
290
 
 */
291
 
PJ_DECL(pj_status_t) pjmedia_rtp_encode_rtp( pjmedia_rtp_session *ses,
292
 
                                             int pt, int m,
293
 
                                             int payload_len, int ts_len,
294
 
                                             const void **rtphdr,
295
 
                                             int *hdrlen );
296
 
 
297
 
/**
298
 
 * This function decodes incoming packet into RTP header and payload.
299
 
 * The decode function is guaranteed to point the payload to the correct
300
 
 * position regardless of any options present in the RTP packet.
301
 
 *
302
 
 * Note that this function does not modify the returned RTP header to
303
 
 * host byte order.
304
 
 *
305
 
 * @param ses           The session.
306
 
 * @param pkt           The received RTP packet.
307
 
 * @param pkt_len       The length of the packet.
308
 
 * @param hdr           Upon return will point to the location of the RTP
309
 
 *                      header inside the packet. Note that the RTP header
310
 
 *                      will be given back as is, meaning that the fields
311
 
 *                      will be in network byte order.
312
 
 * @param payload       Upon return will point to the location of the
313
 
 *                      payload inside the packet.
314
 
 * @param payloadlen    Upon return will indicate the size of the payload.
315
 
 *
316
 
 * @return              PJ_SUCCESS if successfull.
317
 
 */
318
 
PJ_DECL(pj_status_t) pjmedia_rtp_decode_rtp( pjmedia_rtp_session *ses,
319
 
                                             const void *pkt, int pkt_len,
320
 
                                             const pjmedia_rtp_hdr **hdr,
321
 
                                             const void **payload,
322
 
                                             unsigned *payloadlen);
323
 
 
324
 
/**
325
 
 * Call this function everytime an RTP packet is received to check whether
326
 
 * the packet can be received and to let the RTP session performs its internal
327
 
 * calculations.
328
 
 *
329
 
 * @param ses       The session.
330
 
 * @param hdr       The RTP header of the incoming packet. The header must
331
 
 *                  be given with fields in network byte order.
332
 
 * @param seq_st    Optional structure to receive the status of the RTP packet
333
 
 *                  processing.
334
 
 */
335
 
PJ_DECL(void) pjmedia_rtp_session_update( pjmedia_rtp_session *ses,
336
 
                                          const pjmedia_rtp_hdr *hdr,
337
 
                                          pjmedia_rtp_status *seq_st);
338
 
 
339
 
 
340
 
/**
341
 
 * Call this function everytime an RTP packet is received to check whether
342
 
 * the packet can be received and to let the RTP session performs its internal
343
 
 * calculations.
344
 
 *
345
 
 * @param ses       The session.
346
 
 * @param hdr       The RTP header of the incoming packet. The header must
347
 
 *                  be given with fields in network byte order.
348
 
 * @param seq_st    Optional structure to receive the status of the RTP packet
349
 
 *                  processing.
350
 
 * @param check_pt  Flag to indicate whether payload type needs to be validate.
351
 
 *
352
 
 * @see pjmedia_rtp_session_update()
353
 
 */
354
 
PJ_DECL(void) pjmedia_rtp_session_update2(pjmedia_rtp_session *ses,
355
 
                                          const pjmedia_rtp_hdr *hdr,
356
 
                                          pjmedia_rtp_status *seq_st,
357
 
                                          pj_bool_t check_pt);
358
 
 
359
 
 
360
 
/*
361
 
 * INTERNAL:
362
 
 */
363
 
 
364
 
/**
365
 
 * Internal function for creating sequence number control, shared by RTCP
366
 
 * implementation.
367
 
 *
368
 
 * @param seq_ctrl  The sequence control instance.
369
 
 * @param seq       Sequence number to initialize.
370
 
 */
371
 
void pjmedia_rtp_seq_init(pjmedia_rtp_seq_session *seq_ctrl,
372
 
                          pj_uint16_t seq);
373
 
 
374
 
 
375
 
/**
376
 
 * Internal function update sequence control, shared by RTCP implementation.
377
 
 *
378
 
 * @param seq_ctrl      The sequence control instance.
379
 
 * @param seq           Sequence number to update.
380
 
 * @param seq_status    Optional structure to receive additional information
381
 
 *                      about the packet.
382
 
 */
383
 
void pjmedia_rtp_seq_update( pjmedia_rtp_seq_session *seq_ctrl,
384
 
                             pj_uint16_t seq,
385
 
                             pjmedia_rtp_status *seq_status);
386
 
 
387
 
/**
388
 
 * @}
389
 
 */
390
 
 
391
 
PJ_END_DECL
392
 
 
393
 
 
394
 
#endif  /* __PJMEDIA_RTP_H__ */