Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / sock_qos.h
1 /* $Id$ */
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__ */
427