← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjlib/include/pj/sock_qos.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-2.0.1/pjlib/include/pj/sock_qos.h
 
1
/* $Id: sock_qos.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 __PJ_SOCK_QOS_H__
 
21
#define __PJ_SOCK_QOS_H__
 
22
 
 
23
/**
 
24
 * @file sock_qos.h
 
25
 * @brief Socket QoS API
 
26
 */
 
27
 
 
28
#include <pj/sock.h>
 
29
 
 
30
PJ_BEGIN_DECL
 
31
 
 
32
 
 
33
/**
 
34
 * @defgroup socket_qos Socket Quality of Service (QoS) API: TOS, DSCP, WMM, IEEE 802.1p
 
35
 * @ingroup PJ_SOCK
 
36
 * @{
 
37
 
 
38
 
 
39
    \section intro QoS Technologies
 
40
 
 
41
    QoS settings are available for both Layer 2 and 3 of TCP/IP protocols:
 
42
 
 
43
    \subsection intro_ieee8021p Layer 2: IEEE 802.1p for Ethernet
 
44
 
 
45
    IEEE 802.1p tagging will mark frames sent by a host for prioritized
 
46
    delivery using a 3-bit Priority field in the virtual local area network
 
47
    (VLAN) header of the Ethernet frame. The VLAN header is placed inside
 
48
    the Ethernet header, between the Source Address field and either the
 
49
    Length field (for an IEEE 802.3 frame) or the EtherType field (for an
 
50
    Ethernet II frame).
 
51
 
 
52
    \subsection intro_wmm Layer 2: WMM
 
53
 
 
54
    At the Network Interface layer for IEEE 802.11 wireless, the Wi-Fi
 
55
    Alliance certification for Wi-Fi Multimedia (WMM) defines four access
 
56
    categories for prioritizing network traffic. These access categories
 
57
    are (in order of highest to lowest priority) voice, video, best-effort,
 
58
    and background. Host support for WMM prioritization requires that both
 
59
    wireless network adapters and their drivers support WMM. Wireless
 
60
    access points (APs) must have WMM enabled.
 
61
 
 
62
    \subsection intro_dscp Layer 3: DSCP
 
63
 
 
64
    At the Internet layer, you can use Differentiated Services/Diffserv and
 
65
    set the value of the Differentiated Services Code Point (DSCP) in the
 
66
    IP header. As defined in RFC 2474, the DSCP value is the high-order 6 bits
 
67
    of the IP version 4 (IPv4) TOS field and the IP version 6 (IPv6) Traffic
 
68
    Class field.
 
69
 
 
70
    \subsection intro_other Layer 3: Other
 
71
 
 
72
    Other mechanisms exist (such as RSVP, IntServ) but this will not be
 
73
    implemented.
 
74
 
 
75
 
 
76
    \section availability QoS Availability
 
77
 
 
78
    \subsection linux Linux
 
79
 
 
80
    DSCP is available via IP TOS option.
 
81
 
 
82
    Ethernet 802.1p tagging is done by setting setsockopt(SO_PRIORITY) option
 
83
    of the socket, then with the set_egress_map option of the vconfig utility
 
84
    to convert this to set vlan-qos field of the packet.
 
85
 
 
86
    WMM is not known to be available.
 
87
 
 
88
    \subsection windows Windows and Windows Mobile
 
89
 
 
90
    (It's a mess!)
 
91
 
 
92
    DSCP is settable with setsockopt() on Windows 2000 or older, but Windows
 
93
    would silently ignore this call on WinXP or later, unless administrator
 
94
    modifies the registry. On Windows 2000, Windows XP, and Windows Server
 
95
    2003, GQoS (Generic QoS) API is the standard API, but this API may not be
 
96
    supported in the future. On Vista and Windows 7, the is a new QoS2 API,
 
97
    also known as Quality Windows Audio-Video Experience (qWAVE).
 
98
 
 
99
    IEEE 802.1p tagging is available via Traffic Control (TC) API, available
 
100
    on Windows XP SP2, but this needs administrator access. For Vista and
 
101
    later, it's in qWAVE.
 
102
 
 
103
    WMM is available for mobile platforms on Windows Mobile 6 platform and
 
104
    Windows Embedded CE 6, via setsockopt(IP_DSCP_TRAFFIC_TYPE). qWAVE
 
105
    supports this as well.
 
106
 
 
107
    \subsection symbian Symbian S60 3rd Ed
 
108
 
 
109
    Both DSCP and WMM is supported via RSocket::SetOpt() with will set both
 
110
    Layer 2 and Layer 3 QoS settings accordingly. Internally, PJLIB sets the
 
111
    DSCP field of the socket, and based on certain DSCP values mapping,
 
112
    Symbian will set the WMM tag accordingly.
 
113
 
 
114
    \section api PJLIB's QoS API Abstraction
 
115
 
 
116
    Based on the above, the following API is implemented.
 
117
 
 
118
    Declare the following "standard" traffic types.
 
119
 
 
120
    \code
 
121
     typedef enum pj_qos_type
 
122
     {
 
123
        PJ_QOS_TYPE_BEST_EFFORT,
 
124
        PJ_QOS_TYPE_BACKGROUND,
 
125
        PJ_QOS_TYPE_VIDEO,
 
126
        PJ_QOS_TYPE_VOICE,
 
127
        PJ_QOS_TYPE_CONTROL
 
128
     } pj_qos_type;
 
129
    \endcode
 
130
 
 
131
    The traffic classes above will determine how the Layer 2 and 3 QoS
 
132
    settings will be used. The standard mapping between the classes above
 
133
    to the corresponding Layer 2 and 3 settings are as follows:
 
134
 
 
135
    \code
 
136
    =================================================================
 
137
    PJLIB Traffic Type  IP DSCP         WMM                 802.1p
 
138
    -----------------------------------------------------------------
 
139
    BEST_EFFORT         0x00            BE (Bulk Effort)        0
 
140
    BACKGROUND          0x08            BK (Bulk)               2
 
141
    VIDEO               0x28            VI (Video)              5
 
142
    VOICE               0x30            VO (Voice)              6
 
143
    CONTROL             0x38            VO (Voice)              7
 
144
    =================================================================
 
145
    \endcode
 
146
 
 
147
    There are two sets of API provided to manipulate the QoS parameters.
 
148
 
 
149
    \subsection portable_api Portable API
 
150
 
 
151
    The first set of API is:
 
152
 
 
153
    \code
 
154
     // Set QoS parameters
 
155
     PJ_DECL(pj_status_t) pj_sock_set_qos_type(pj_sock_t sock,
 
156
                                               pj_qos_type val);
 
157
 
 
158
     // Get QoS parameters
 
159
     PJ_DECL(pj_status_t) pj_sock_get_qos_type(pj_sock_t sock,
 
160
                                               pj_qos_type *p_val);
 
161
    \endcode
 
162
 
 
163
    The API will set the traffic type according to the DSCP class, for both
 
164
    Layer 2 and Layer 3 QoS settings, where it's available. If any of the
 
165
    layer QoS setting is not settable, the API will silently ignore it.
 
166
    If both layers are not setable, the API will return error.
 
167
 
 
168
    The API above is the recommended use of QoS, since it is the most
 
169
    portable across all platforms.
 
170
 
 
171
    \subsection detail_api Fine Grained Control API
 
172
 
 
173
    The second set of API is intended for application that wants to fine
 
174
    tune the QoS parameters.
 
175
 
 
176
    The Layer 2 and 3 QoS parameters are stored in pj_qos_params structure:
 
177
 
 
178
    \code
 
179
     typedef enum pj_qos_flag
 
180
     {
 
181
        PJ_QOS_PARAM_HAS_DSCP = 1,
 
182
        PJ_QOS_PARAM_HAS_SO_PRIO = 2,
 
183
        PJ_QOS_PARAM_HAS_WMM = 4
 
184
     } pj_qos_flag;
 
185
 
 
186
     typedef enum pj_qos_wmm_prio
 
187
     {
 
188
        PJ_QOS_WMM_PRIO_BULK_EFFORT,
 
189
        PJ_QOS_WMM_PRIO_BULK,
 
190
        PJ_QOS_WMM_PRIO_VIDEO,
 
191
        PJ_QOS_WMM_PRIO_VOICE
 
192
     } pj_qos_wmm_prio;
 
193
 
 
194
     typedef struct pj_qos_params
 
195
     {
 
196
        pj_uint8_t      flags;    // Determines which values to
 
197
                                  // set, bitmask of pj_qos_flag
 
198
        pj_uint8_t      dscp_val; // The 6 bits DSCP value to set
 
199
        pj_uint8_t      so_prio;  // SO_PRIORITY value
 
200
        pj_qos_wmm_prio wmm_prio; // WMM priority value
 
201
     } pj_qos_params;
 
202
    \endcode
 
203
 
 
204
    The second set of API with more fine-grained control over the parameters
 
205
    are:
 
206
 
 
207
    \code
 
208
     // Retrieve QoS params for the specified traffic type
 
209
     PJ_DECL(pj_status_t) pj_qos_get_params(pj_qos_type type,
 
210
                                            pj_qos_params *p);
 
211
 
 
212
     // Set QoS parameters to the socket
 
213
     PJ_DECL(pj_status_t) pj_sock_set_qos_params(pj_sock_t sock,
 
214
                                                 const pj_qos_params *p);
 
215
 
 
216
     // Get QoS parameters from the socket
 
217
     PJ_DECL(pj_status_t) pj_sock_get_qos_params(pj_sock_t sock,
 
218
                                                 pj_qos_params *p);
 
219
    \endcode
 
220
 
 
221
 
 
222
    Important:
 
223
 
 
224
    The pj_sock_set/get_qos_params() APIs are not portable, and it's probably
 
225
    only going to be implemented on Linux. Application should always try to
 
226
    use pj_sock_set_qos_type() instead.
 
227
 */
 
228
 
 
229
 
 
230
/**
 
231
 * High level traffic classification.
 
232
 */
 
233
typedef enum pj_qos_type
 
234
{
 
235
    PJ_QOS_TYPE_BEST_EFFORT,    /**< Best effort traffic (default value).
 
236
                                     Any QoS function calls with specifying
 
237
                                     this value are effectively no-op   */
 
238
    PJ_QOS_TYPE_BACKGROUND,     /**< Background traffic.                */
 
239
    PJ_QOS_TYPE_VIDEO,          /**< Video traffic.                     */
 
240
    PJ_QOS_TYPE_VOICE,          /**< Voice traffic.                     */
 
241
    PJ_QOS_TYPE_CONTROL         /**< Control traffic.                   */
 
242
} pj_qos_type;
 
243
 
 
244
/**
 
245
 * Bitmask flag to indicate which QoS layer setting is set in the
 
246
 * \a flags field of the #pj_qos_params structure.
 
247
 */
 
248
typedef enum pj_qos_flag
 
249
{
 
250
    PJ_QOS_PARAM_HAS_DSCP = 1,      /**< DSCP field is set.         */
 
251
    PJ_QOS_PARAM_HAS_SO_PRIO = 2,   /**< Socket SO_PRIORITY         */
 
252
    PJ_QOS_PARAM_HAS_WMM = 4        /**< WMM  field is set.         */
 
253
} pj_qos_flag;
 
254
 
 
255
 
 
256
/**
 
257
 * Standard WMM priorities.
 
258
 */
 
259
typedef enum pj_qos_wmm_prio
 
260
{
 
261
    PJ_QOS_WMM_PRIO_BULK_EFFORT,        /**< Bulk effort priority   */
 
262
    PJ_QOS_WMM_PRIO_BULK,               /**< Bulk priority.         */
 
263
    PJ_QOS_WMM_PRIO_VIDEO,              /**< Video priority         */
 
264
    PJ_QOS_WMM_PRIO_VOICE               /**< Voice priority         */
 
265
} pj_qos_wmm_prio;
 
266
 
 
267
 
 
268
/**
 
269
 * QoS parameters to be set or retrieved to/from the socket.
 
270
 */
 
271
typedef struct pj_qos_params
 
272
{
 
273
    pj_uint8_t      flags;    /**< Determines which values to
 
274
                                   set, bitmask of pj_qos_flag      */
 
275
    pj_uint8_t      dscp_val; /**< The 6 bits DSCP value to set     */
 
276
    pj_uint8_t      so_prio;  /**< SO_PRIORITY value                */
 
277
    pj_qos_wmm_prio wmm_prio; /**< WMM priority value               */
 
278
} pj_qos_params;
 
279
 
 
280
 
 
281
 
 
282
/**
 
283
 * This is the high level and portable API to enable QoS on the specified
 
284
 * socket, by setting the traffic type to the specified parameter.
 
285
 *
 
286
 * @param sock      The socket.
 
287
 * @param type      Traffic type to be set.
 
288
 *
 
289
 * @return          PJ_SUCCESS if at least Layer 2 or Layer 3 setting is
 
290
 *                  successfully set. If both Layer 2 and Layer 3 settings
 
291
 *                  can't be set, this function will return error.
 
292
 */
 
293
PJ_DECL(pj_status_t) pj_sock_set_qos_type(pj_sock_t sock,
 
294
                                          pj_qos_type type);
 
295
 
 
296
/**
 
297
 * This is the high level and portable API to get the traffic type that has
 
298
 * been set on the socket. On occasions where the Layer 2 or Layer 3 settings
 
299
 * were modified by using low level API, this function may return approximation
 
300
 * of the closest QoS type that matches the settings.
 
301
 *
 
302
 * @param sock      The socket.
 
303
 * @param p_type    Pointer to receive the traffic type of the socket.
 
304
 *
 
305
 * @return          PJ_SUCCESS if traffic type for the socket can be obtained
 
306
 *                  or approximated..
 
307
 */
 
308
PJ_DECL(pj_status_t) pj_sock_get_qos_type(pj_sock_t sock,
 
309
                                          pj_qos_type *p_type);
 
310
 
 
311
 
 
312
/**
 
313
 * This is a convenience function to apply QoS to the socket, and print error
 
314
 * logging if the operations failed. Both QoS traffic type and the low level
 
315
 * QoS parameters can be applied with this function.
 
316
 *
 
317
 * @param sock          The socket handle.
 
318
 * @param qos_type      QoS traffic type. The QoS traffic type will be applied
 
319
 *                      only if the value is not PJ_QOS_TYPE_BEST_EFFORT,
 
320
 * @param qos_params    Optional low-level QoS parameters. This will be
 
321
 *                      applied only if this argument is not NULL and the
 
322
 *                      flags inside the structure is non-zero. Upon return,
 
323
 *                      the flags will indicate which parameters have been
 
324
 *                      applied successfully.
 
325
 * @param log_level     This function will print to log at this level upon
 
326
 *                      encountering errors.
 
327
 * @param log_sender    Optional sender name in the log.
 
328
 * @param sock_name     Optional name to help identify the socket in the log.
 
329
 *
 
330
 * @return              PJ_SUCCESS if at least Layer 2 or Layer 3 setting is
 
331
 *                      successfully set. If both Layer 2 and Layer 3 settings
 
332
 *                      can't be set, this function will return error.
 
333
 *
 
334
 * @see pj_sock_apply_qos2()
 
335
 */
 
336
PJ_DECL(pj_status_t) pj_sock_apply_qos(pj_sock_t sock,
 
337
                                       pj_qos_type qos_type,
 
338
                                       pj_qos_params *qos_params,
 
339
                                       unsigned log_level,
 
340
                                       const char *log_sender,
 
341
                                       const char *sock_name);
 
342
 
 
343
/**
 
344
 * Variant of #pj_sock_apply_qos() where the \a qos_params parameter is
 
345
 * const.
 
346
 *
 
347
 * @see pj_sock_apply_qos()
 
348
 */
 
349
PJ_DECL(pj_status_t) pj_sock_apply_qos2(pj_sock_t sock,
 
350
                                        pj_qos_type qos_type,
 
351
                                        const pj_qos_params *qos_params,
 
352
                                        unsigned log_level,
 
353
                                        const char *log_sender,
 
354
                                        const char *sock_name);
 
355
 
 
356
/**
 
357
 * Retrieve the standard mapping of QoS params for the specified traffic
 
358
 * type.
 
359
 *
 
360
 * @param type      The traffic type from which the QoS parameters
 
361
 *                  are to be retrieved.
 
362
 * @param p_param   Pointer to receive the QoS parameters.
 
363
 *
 
364
 * @return          PJ_SUCCESS on success or the appropriate error code.
 
365
 */
 
366
PJ_DECL(pj_status_t) pj_qos_get_params(pj_qos_type type,
 
367
                                       pj_qos_params *p_param);
 
368
 
 
369
 
 
370
/**
 
371
 * Retrieve the traffic type that matches the specified QoS parameters.
 
372
 * If no exact matching is found, this function will return an
 
373
 * approximation of the closest matching traffic type for the specified
 
374
 * QoS parameters.
 
375
 *
 
376
 * @param param     Structure containing QoS parameters to map into
 
377
 *                  "standard" traffic types.
 
378
 * @param p_type    Pointer to receive the traffic type.
 
379
 *
 
380
 * @return          PJ_SUCCESS on success or the appropriate error code.
 
381
 */
 
382
PJ_DECL(pj_status_t) pj_qos_get_type(const pj_qos_params *param,
 
383
                                     pj_qos_type *p_type);
 
384
 
 
385
 
 
386
/**
 
387
 * This is a low level API to set QoS parameters to the socket.
 
388
 *
 
389
 * @param sock      The socket.
 
390
 * @param param     Structure containing QoS parameters to be applied
 
391
 *                  to the socket. Upon return, the \a flags field
 
392
 *                  of this structure will be set with bitmask value
 
393
 *                  indicating which QoS settings have successfully
 
394
 *                  been applied to the socket.
 
395
 *
 
396
 * @return          PJ_SUCCESS if at least one field setting has been
 
397
 *                  successfully set. If no setting can't be set,
 
398
 *                  this function will return error.
 
399
 */
 
400
PJ_DECL(pj_status_t) pj_sock_set_qos_params(pj_sock_t sock,
 
401
                                            pj_qos_params *param);
 
402
 
 
403
/**
 
404
 * This is a low level API to get QoS parameters from the socket.
 
405
 *
 
406
 * @param sock      The socket.
 
407
 * @param p_param   Pointer to receive the parameters. Upon returning
 
408
 *                  successfully, the \a flags field of this structure
 
409
 *                  will be initialized with the appropriate bitmask
 
410
 *                  to indicate which fields have been successfully
 
411
 *                  retrieved.
 
412
 *
 
413
 * @return          PJ_SUCCESS on success or the appropriate error code.
 
414
 */
 
415
PJ_DECL(pj_status_t) pj_sock_get_qos_params(pj_sock_t sock,
 
416
                                            pj_qos_params *p_param);
 
417
 
 
418
 
 
419
/**
 
420
 * @}
 
421
 */
 
422
 
 
423
 
 
424
PJ_END_DECL
 
425
 
 
426
#endif  /* __PJ_SOCK_QOS_H__ */