|
ROHC compression/decompression library
|
00001 /* 00002 * This program is free software; you can redistribute it and/or modify 00003 * it under the terms of the GNU General Public License as published by 00004 * the Free Software Foundation; either version 2 of the License, or 00005 * (at your option) any later version. 00006 * 00007 * This program is distributed in the hope that it will be useful, 00008 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00009 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00010 * GNU General Public License for more details. 00011 * 00012 * You should have received a copy of the GNU General Public License 00013 * along with this program; if not, write to the Free Software 00014 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00015 */ 00016 00017 /** 00018 * @file rohc.h 00019 * @brief ROHC common definitions and routines 00020 * @author Didier Barvaux <didier.barvaux@toulouse.viveris.com> 00021 * @author Didier Barvaux <didier@barvaux.org> 00022 * @author The hackers from ROHC for Linux 00023 */ 00024 00025 #ifndef ROHC_H 00026 #define ROHC_H 00027 00028 /** 00029 * \mainpage 00030 * 00031 * 00032 * <h2>Introduction</h2> 00033 * 00034 * <p>The ROHC library provides an easy and robust way for applications to 00035 * reduce their bandwidth usage on network links with limited capacity. 00036 * Headers of network packets are compressed with the ROHC protocol and 00037 * algorithms.</p> 00038 * 00039 * <p>RObust Header Compression (ROHC) is a set of standards defined by the 00040 * <a href="http://www.ietf.org/">IETF</a>. The ROHC library is a free, 00041 * opensource and efficient implementation of them. The list of features 00042 * implemented is available on a separate page: \ref features</p> 00043 * 00044 * <ul> 00045 * <li>Official website: <a href="http://rohc-lib.org/"> 00046 * http://rohc-lib.org/</a></li> 00047 * <li>Project page on Launchpad: <a href="http://launchpad.net/rohc"> 00048 * http://launchpad.net/rohc</a></li> 00049 * <li>Mailing list: <a href="mailto:rohc@lists.launchpad.net"> 00050 * rohc@lists.launchpad.net</a></li> 00051 * <li>Mailing list archives: <a href="http://lists.launchpad.net/rohc/"> 00052 * http://lists.launchpad.net/rohc/</a></li> 00053 * <li>Bugtracker: <a href="http://bugs.launchpad.net/rohc"> 00054 * http://bugs.launchpad.net/rohc</a></li> 00055 * </ul> 00056 * 00057 * 00058 * <h2>License</h2> 00059 * 00060 * <p>The project is licensed under GPL2+. 00061 * See the <a href="http://bazaar.launchpad.net/%7Edidier-barvaux/rohc/1.4.x/annotate/head%3A/COPYING">COPYING</a> 00062 * and <a href="http://bazaar.launchpad.net/%7Edidier-barvaux/rohc/1.4.x/annotate/head%3A/AUTHORS">AUTHORS</a> 00063 * files for more details.</p> 00064 * 00065 * 00066 * <h2>Libraries</h2> 00067 * 00068 * <p> 00069 * The sources are in the src subdirectory. The sources are separated into 00070 * three libraries: 00071 * <ul> 00072 * <li>a library that contains the routines used for both the compression 00073 * and the decompression processes</li> 00074 * <li>a library that handles the compression process</li> 00075 * <li>a library that handles the decompression process</li> 00076 * </ul> 00077 * </p> 00078 * 00079 * <p>See the <a href="http://bazaar.launchpad.net/%7Edidier-barvaux/rohc/1.4.x/annotate/head%3A/INSTALL"> INSTALL file</a> 00080 * to learn to build the libraries.</p> 00081 * 00082 * 00083 * <h2>API documentation</h2> 00084 * <p>The APIs for ROHC common, compression and decompression are available on 00085 * separate pages: 00086 * <ul> 00087 * <li>\ref rohc_common</li> 00088 * <li>\ref rohc_comp</li> 00089 * <li>\ref rohc_decomp</li> 00090 * </ul> 00091 * </p> 00092 * 00093 * 00094 * <h2>Non-regression tests</h2> 00095 * 00096 * <p> 00097 * The test subdirectory contains several test applications. See the <a href="http://bazaar.launchpad.net/%7Edidier-barvaux/rohc/1.4.x/annotate/head%3A/INSTALL">INSTALL file</a> to learn how to use these tools. 00098 * </p> 00099 * 00100 * 00101 * <h2>References</h2> 00102 * 00103 * <table style="border-collapse: collapse; border: solid thin black;"> 00104 * <tr> 00105 * <td>RFC 3095</td> 00106 * <td> 00107 * <p> 00108 * RObust Header Compression (ROHC): Framework and four profiles: RTP, 00109 * UDP, ESP, and uncompressed.<br> 00110 * <a href="http://www.ietf.org/rfc/rfc3095.txt"> 00111 * http://www.ietf.org/rfc/rfc3095.txt</a> 00112 * </p> 00113 * </td> 00114 * </tr> 00115 * <tr> 00116 * <td>RFC 3096</td> 00117 * <td> 00118 * <p> 00119 * Requirements for robust IP/UDP/RTP header compression.<br> 00120 * <a href="http://www.ietf.org/rfc/rfc3096.txt"> 00121 * http://www.ietf.org/rfc/rfc3096.txt</a> 00122 * </p> 00123 * </td> 00124 * </tr> 00125 * <tr> 00126 * <td>RFC 3828</td> 00127 * <td> 00128 * <p> 00129 * The Lightweight User Datagram Protocol (UDP-Lite).<br> 00130 * <a href="http://www.ietf.org/rfc/rfc3828.txt"> 00131 * http://www.ietf.org/rfc/rfc3828.txt</a> 00132 * </p> 00133 * </td> 00134 * </tr> 00135 * <tr> 00136 * <td>RFC 3843 00137 * <td> 00138 * <p> 00139 * RObust Header Compression (ROHC): A Compression Profile for IP.<br> 00140 * <a href="http://www.ietf.org/rfc/rfc3843.txt"> 00141 * http://www.ietf.org/rfc/rfc3843.txt</a> 00142 * </p> 00143 * </td> 00144 * </tr> 00145 * <tr> 00146 * <td>RFC 4019</td> 00147 * <td> 00148 * <p> 00149 * RObust Header Compression (ROHC): Profiles for User Datagram Protocol 00150 * (UDP) Lite.<br> 00151 * <a href="http://www.ietf.org/rfc/rfc4019.txt"> 00152 * http://www.ietf.org/rfc/rfc4019.txt</a> 00153 * </p> 00154 * </td> 00155 * </tr> 00156 * <tr> 00157 * <td>ROHC library</td> 00158 * <td> 00159 * <p> 00160 * The Open Source ROHC library described by the documentation you are 00161 * currently reading.<br> 00162 * <a href="http://launchpad.net/rohc">http://launchpad.net/rohc</a> 00163 * </p> 00164 * </td> 00165 * </tr> 00166 * <tr> 00167 * <td>ROHC Linux</td> 00168 * <td> 00169 * <p> 00170 * A GPL-licensed implementation of ROHC over PPP for the 2.4 Linux 00171 * kernel. The ROHC library is mainly based on this software.<br> 00172 * <a href="http://rohc.sourceforge.net/">http://rohc.sourceforge.net/</a> 00173 * </p> 00174 * </td> 00175 * </tr> 00176 * <tr> 00177 * <td>UDP-Lite</td> 00178 * <td> 00179 * <p> 00180 * An UDP-Lite implementation for the Linux kernel.<br> 00181 * <a href="http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/"> 00182 * http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/</a> 00183 * </p> 00184 * </td> 00185 * </tr> 00186 * </table> 00187 */ 00188 00189 00190 /** 00191 * \page features Library features 00192 * 00193 * <p>Unsupported features are in <span style="color: red;">red</span>.</p> 00194 * <p>Limitations are in <span style="color: orange;">orange</span>.</p> 00195 * 00196 * <p>See the <a href="https://answers.launchpad.net/rohc/+faq/1806">FAQ about compliance with IETF RFCs</a> for additional details.</p> 00197 * 00198 * <h2>Main features</h2> 00199 * 00200 * <ul> 00201 * <li>ROHC compression</li> 00202 * <li>ROHC decompression</li> 00203 * <li>ROHC channels: small and large Channel IDs (CIDs)</li> 00204 * <li> 00205 * ROHC modes: 00206 * <ul> 00207 * <li>Unidirectional mode (U-mode)</li> 00208 * <li>Bidirectional Optimistic mode (O-mode)</li> 00209 * <li style="color: red;">Bidirectional Reliable mode (R-mode)</li> 00210 * </ul> 00211 * </li> 00212 * <li> 00213 * ROHC states: 00214 * <ul> 00215 * <li>Initialization & Refresh (IR)</li> 00216 * <li>First Order (FO)</li> 00217 * <li>Second Order (SO)</li> 00218 * </ul> 00219 * </li> 00220 * <li> 00221 * Feedback: 00222 * <ul> 00223 * <li>Feedback packets</li> 00224 * <li>Piggy-backed feedbacks</li> 00225 * <li>Negative ACKs</li> 00226 * </ul> 00227 * </li> 00228 * <li> 00229 * ROHC packets: 00230 * <ul> 00231 * <li>Feedback packets (RFC 3095, §5.2.1 and §5.2.2)</li> 00232 * <li> 00233 * IR packet (RFC 3095, §5.2.3) 00234 * <ul> 00235 * <li style="color: orange;">Optional dynamic part is always sent</li> 00236 * </ul> 00237 * </li> 00238 * <li>IR-DYN packet (RFC 3095, §5.2.3)</li> 00239 * <li> 00240 * Packet type 0 (RFC 3095, §5.7.1) 00241 * <ul> 00242 * <li>UO-0</li> 00243 * <li style="color: red;">R-0</li> 00244 * <li style="color: red;">R-0-CRC</li> 00245 * </ul> 00246 * </li> 00247 * <li style="color: red;"> 00248 * Packet type 1 for R-mode (RFC 3095, §5.7.2) 00249 * <ul> 00250 * <li style="color: red;">R-1</li> 00251 * <li style="color: red;">R-1-TS</li> 00252 * <li style="color: red;">R-1-ID</li> 00253 * </ul> 00254 * </li> 00255 * <li> 00256 * Packet type 1 for U/O-mode (RFC 3095, §5.7.3) 00257 * <ul> 00258 * <li>UO-1</li> 00259 * <li>UO-1-ID</li> 00260 * <li>UO-1-TS</li> 00261 * </ul> 00262 * </li> 00263 * <li> 00264 * Packet type 2 (RFC 3095, §5.7.4) 00265 * <ul> 00266 * <li>UOR-2</li> 00267 * </ul> 00268 * </li> 00269 * </ul> 00270 * </li> 00271 * <li>Actions upon CRC failure (RFC 3095, §5.3.2.2.3, §5.3.2.2.4 and §5.3.2.2.5)</li> 00272 * </ul> 00273 * 00274 * <h2>ROHC profiles</h2> 00275 * 00276 * <ul> 00277 * <li>Uncompressed (0x0000)</li> 00278 * <li>RTP (0x0001)</li> 00279 * <li>UDP (0x0002)</li> 00280 * <li style="color: red;">ESP (0x0003)</li> 00281 * <li>IP-only (0x0004)</li> 00282 * <li style="color: red;">TCP (0x0006)</li> 00283 * <li>UDP-Light (0x0008)</li> 00284 * </ul> 00285 * 00286 * <h2>Features shared by all supported profiles</h2> 00287 * 00288 * <ul> 00289 * <li>Compression of up to two IPv4/IPv6 headers</li> 00290 * <li style="color: red;">Compressed IPv4 Header Extension List (RFC 3095, §5.8.4.1 & §5.8.5.1)</li> 00291 * <li>Compressed IPv6 Header Extension List (RFC 3095, §5.8.4.1 & §5.8.5.1)</li> 00292 * <li>Authentication Header (AH) Compression (RFC 3095, §5.8.4.2)</li> 00293 * <li style="color: red;">Encapsulating Security Payload Header (ESP) Compression (RFC 3095, §5.8.4.3)</li> 00294 * <li style="color: red;">GRE Header Compression (RFC 3095, §5.8.4.4)</li> 00295 * <li>Forced context reinitialization controled by the user</li> 00296 * <li>Fixed sizes parameters in order to specify the size of ROHC packets</li> 00297 * <li style="color: red;">Optional Reverse decompression (RFC 3095, §6.1)</li> 00298 * <li style="color: red;">ROHC segmentation (RFC 3095, §5.2.5)</li> 00299 * </ul> 00300 * 00301 * <h2>Profile-specific features</h2> 00302 * 00303 * <table style="border-collapse: collapse; border: solid thin black;"> 00304 * <tr> 00305 * <td>Uncompressed</td> 00306 * <td> 00307 * 00308 * </td> 00309 * </tr> 00310 * <tr> 00311 * <td>RTP</td> 00312 * <td> 00313 * <ul> 00314 * <li style="color: red;">Compressed CSRC List (RFC 3095, §5.8.5.2)</li> 00315 * <li style="color: red;">Timer-based compression of RTP Timestamp (RFC 3095, §4.5.4)</li> 00316 * </ul> 00317 * </td> 00318 * </tr> 00319 * <tr> 00320 * <td>UDP</td> 00321 * <td> 00322 * 00323 * </td> 00324 * </tr> 00325 * <tr> 00326 * <td>IP-only</td> 00327 * <td> 00328 * <ul> 00329 * <li style="color: red;">more than 2 IPv4/IPv6 headers</li> 00330 * </ul> 00331 * </td> 00332 * </tr> 00333 * <tr> 00334 * <td>UDP-Lite</td> 00335 * <td> 00336 * <ul> 00337 * <li>Checksum Coverage (CC) compression</li> 00338 * </ul> 00339 * </td> 00340 * </tr> 00341 * </table> 00342 * 00343 * <h2>Encoding methods</h2> 00344 * 00345 * <ul> 00346 * <li>Least Significant Bits (LSB) encoding (RFC 3095, §4.5.1)</li> 00347 * <li>Window-based LSB (W-LSB) encoding (RFC 3095, §4.5.2)</li> 00348 * <li>Scaled RTP Timestamp encoding (RFC 3095, §4.5.3)</li> 00349 * <li style="color: red;">Timer-based compression of RTP Timestamp (RFC 3095, §4.5.4)</li> 00350 * <li>Offset IP-ID encoding (RFC 3095, §4.5.5)</li> 00351 * <li>Self-describing variable-length (SDVL) values (RFC 3095, §4.5.6)</li> 00352 * <li> 00353 * Encoded values across several fields in compressed headers (RFC 3095, §4.5.7) 00354 * <ul> 00355 * <li style="color: orange;">Not fully respected: if more bits than stricly necessary are available, more bits are sent</li> 00356 * </ul> 00357 * </li> 00358 * </ul> 00359 * 00360 * <h2>Non-standard ROHC enhancements</h2> 00361 * 00362 * <ul> 00363 * <li> 00364 * Use of encapsulation padding for sending larger packets</li> 00365 * <ul> 00366 * <li style="color: orange;">Padding not used with Compressed IPv6 Header Extension List</li> 00367 * </ul> 00368 * </li> 00369 * <li>Optional simplification of UOR-2-TS / UOR-2-ID packets to help distinguish them at decompressor</li> 00370 * </ul> 00371 */ 00372 00373 00374 /** Macro that handles deprecated declarations gracefully */ 00375 #if defined __GNUC__ && \ 00376 (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)) 00377 /* __attribute__((deprecated(msg))) is supported by GCC 4.5 and later */ 00378 #define ROHC_DEPRECATED(msg) __attribute__((deprecated(msg))) 00379 #elif defined __GNUC__ && \ 00380 (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)) 00381 /* __attribute__((deprecated)) is supported by GCC 3.1 and later */ 00382 #define ROHC_DEPRECATED(msg) __attribute__((deprecated)) 00383 #else 00384 /* no support */ 00385 #define ROHC_DEPRECATED(msg) 00386 #endif 00387 00388 00389 /** 00390 * @brief The Ethertype assigned to the ROHC protocol by the IEEE 00391 * 00392 * @see http://standards.ieee.org/regauth/ethertype/eth.txt 00393 */ 00394 #define ROHC_ETHERTYPE 0x22f1 00395 00396 00397 /* 00398 * Below are some return codes: 00399 */ 00400 00401 /// Return code: the action done without problem 00402 #define ROHC_OK 1 00403 /// Return code: the action can not proceed because no context is defined 00404 #define ROHC_ERROR_NO_CONTEXT -1 00405 /// Return code: the action failed due to an unattended or malformed packet 00406 #define ROHC_ERROR_PACKET_FAILED -2 00407 /// Return code: the action failed because the packet only contains feedback info 00408 #define ROHC_FEEDBACK_ONLY -3 00409 /// Return code: the action failed due to a CRC failure 00410 #define ROHC_ERROR_CRC -4 00411 /// Return code: the action encountered a problem 00412 #define ROHC_ERROR -5 00413 /// Return code: the packet needs to be parsed again 00414 #define ROHC_NEED_REPARSE -6 00415 00416 00417 /** 00418 * @brief ROHC operation modes (see 4.4 in the RFC 3095) 00419 * 00420 * If you add a new operation mode, please also add the corresponding textual 00421 * description in \ref rohc_get_mode_descr. 00422 */ 00423 typedef enum 00424 { 00425 /// The Unidirectional mode (U-mode) 00426 U_MODE = 1, 00427 /// The Bidirectional Optimistic mode (O-mode) 00428 O_MODE = 2, 00429 /// The Bidirectional Reliable mode (R-mode) 00430 R_MODE = 3, 00431 } rohc_mode; 00432 00433 00434 /** The maximum value for large CIDs */ 00435 #define ROHC_LARGE_CID_MAX ((1 << 14) - 1) /* 2^14 - 1 = 16383 */ 00436 /** The maximum value for small CIDs */ 00437 #define ROHC_SMALL_CID_MAX 15 00438 00439 00440 /** 00441 * @brief The different types of Context IDs (CID) a stream/context may use 00442 * 00443 * Possible values are: ROHC_LARGE_CID, ROHC_SMALL_CID. 00444 * Small CID means CID in the \f$[0-ROHC_SMALL_CID_MAX]\f$ interval. 00445 * Large CID means CID in the \f$[0-ROHC_LARGE_CID_MAX]\f$ interval. 00446 */ 00447 typedef enum 00448 { 00449 /** 00450 * @brief The context uses large CID 00451 * Value in the \f$[0-ROHC_LARGE_CID_MAX]\f$ interval. 00452 */ 00453 ROHC_LARGE_CID, 00454 /** 00455 * @brief The context uses small CID 00456 * Value in the \f$[0-ROHC_SMALL_CID_MAX]\f$ interval. 00457 */ 00458 ROHC_SMALL_CID, 00459 } rohc_cid_type_t; 00460 00461 00462 /** 00463 * @brief ROHC medium (CID characteristics). 00464 */ 00465 struct medium 00466 { 00467 /** The CID type: large or small */ 00468 rohc_cid_type_t cid_type; 00469 00470 /// The maximum CID value 00471 int max_cid; 00472 }; 00473 00474 00475 /* 00476 * ROHC profiles numbers allocated by the IANA (see 8 in the RFC 3095): 00477 */ 00478 00479 /// The number allocated for the ROHC Uncompressed profile 00480 #define ROHC_PROFILE_UNCOMPRESSED 0x0000 00481 /// The number allocated for the ROHC RTP profile 00482 #define ROHC_PROFILE_RTP 0x0001 00483 /// The number allocated for the ROHC UDP profile 00484 #define ROHC_PROFILE_UDP 0x0002 00485 /// The number allocated for the ROHC IP-only profile (see 5 in the RFC 3843) 00486 #define ROHC_PROFILE_IP 0x0004 00487 /// The number allocated for the ROHC UDP-Lite profile (see 7 in the RFC 4019) 00488 #define ROHC_PROFILE_UDPLITE 0x0008 00489 00490 00491 /* 00492 * The limits for the compressor states changes: 00493 */ 00494 00495 /// @brief The maximal number of packets sent in > IR states (= FO and SO 00496 /// states) before changing back the state to IR (periodic refreshes) 00497 #define CHANGE_TO_IR_COUNT 1700 00498 00499 /// @brief The maximal number of packets sent in > FO states (= SO state) 00500 /// before changing back the state to FO (periodic refreshes) 00501 #define CHANGE_TO_FO_COUNT 700 00502 00503 /// @brief Defines the minimal number of packets that must be sent while 00504 /// in IR state before being able to switch to the FO state 00505 #define MAX_IR_COUNT 3 00506 00507 /// @brief Defines the minimal number of packets that must be sent while 00508 /// in FO state before being able to switch to the SO state 00509 #define MAX_FO_COUNT 3 00510 00511 /// @brief Defines the minimal number of packets that must be sent while in 00512 /// INIT_STRIDE state before being able to switch to the SEND_SCALED 00513 /// state 00514 #define ROHC_INIT_TS_STRIDE_MIN 3U 00515 00516 00517 /* 00518 * The different CRC types and tables for ROHC compression/decompression 00519 * 00520 * TODO API: define constants as private and move in crc.h or even crc.c 00521 * TODO API: use an enum instead of constants 00522 */ 00523 00524 /** The CRC-2 type */ 00525 #define CRC_TYPE_2 1 00526 /** The CRC-3 type */ 00527 #define CRC_TYPE_3 2 00528 /** The CRC-6 type */ 00529 #define CRC_TYPE_6 3 00530 /** The CRC-7 type */ 00531 #define CRC_TYPE_7 4 00532 /** The CRC-8 type */ 00533 #define CRC_TYPE_8 5 00534 00535 00536 /* TODO API: remove these variables once compatibility is not needed anymore */ 00537 00538 /** The table to enable fast CRC-2 computation 00539 * @deprecated please do not use this variable anymore */ 00540 extern unsigned char crc_table_2[256] 00541 ROHC_DEPRECATED("please do not use this variable anymore, simply drop it"); 00542 00543 /** The table to enable fast CRC-3 computation 00544 * @deprecated please do not use this variable anymore */ 00545 extern unsigned char crc_table_3[256] 00546 ROHC_DEPRECATED("please do not use this variable anymore, simply drop it"); 00547 00548 /** The table to enable fast CRC-6 computation 00549 * @deprecated please do not use this variable anymore */ 00550 extern unsigned char crc_table_6[256] 00551 ROHC_DEPRECATED("please do not use this variable anymore, simply drop it"); 00552 00553 /** The table to enable fast CRC-7 computation 00554 * @deprecated please do not use this variable anymore */ 00555 extern unsigned char crc_table_7[256] 00556 ROHC_DEPRECATED("please do not use this variable anymore, simply drop it"); 00557 00558 /** The table to enable fast CRC-8 computation 00559 * @deprecated please do not use this variable anymore */ 00560 extern unsigned char crc_table_8[256] 00561 ROHC_DEPRECATED("please do not use this variable anymore, simply drop it"); 00562 00563 00564 /* 00565 * Prototypes of public up-to-date functions 00566 */ 00567 00568 char * rohc_version(void); 00569 00570 const char * rohc_get_mode_descr(const rohc_mode mode); 00571 00572 00573 /* 00574 * Prototypes of public deprecated functions 00575 * 00576 * TODO API: remove this function once compatibility is not needed anymore 00577 */ 00578 00579 int crc_get_polynom(int type) 00580 ROHC_DEPRECATED("please do not use this function anymore, simply drop it"); 00581 00582 void crc_init_table(unsigned char *table, unsigned char polynum) 00583 ROHC_DEPRECATED("please do not use this function anymore, simply drop it"); 00584 00585 #endif 00586
1.7.6.1