00001 /* 00002 * Copyright 2012,2013,2014 Didier Barvaux 00003 * Copyright 2007,2009,2010,2012,2014 Viveris Technologies 00004 * 00005 * This library is free software; you can redistribute it and/or 00006 * modify it under the terms of the GNU Lesser General Public 00007 * License as published by the Free Software Foundation; either 00008 * version 2.1 of the License, or (at your option) any later version. 00009 * 00010 * This library is distributed in the hope that it will be useful, 00011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 * Lesser General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU Lesser General Public 00016 * License along with this library; if not, write to the Free Software 00017 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 00018 */ 00019 00020 /** 00021 * @file rohc_decomp.h 00022 * @brief ROHC decompression routines 00023 * @author Didier Barvaux <didier.barvaux@toulouse.viveris.com> 00024 * @author Didier Barvaux <didier@barvaux.org> 00025 * @author David Moreau from TAS 00026 */ 00027 00028 #ifndef ROHC_DECOMP_H 00029 #define ROHC_DECOMP_H 00030 00031 #ifdef __cplusplus 00032 extern "C" 00033 { 00034 #endif 00035 00036 #include <rohc/rohc.h> 00037 #include <rohc/rohc_packets.h> 00038 #include <rohc/rohc_traces.h> 00039 #include <rohc/rohc_buf.h> 00040 00041 00042 /** Macro that handles DLL export declarations gracefully */ 00043 #ifdef DLL_EXPORT /* passed by autotools on command line */ 00044 # define ROHC_EXPORT __declspec(dllexport) 00045 #else 00046 # define ROHC_EXPORT 00047 #endif 00048 00049 00050 /* 00051 * Declare the private ROHC decompressor structure that is defined inside the 00052 * library. 00053 */ 00054 00055 struct rohc_decomp; 00056 00057 00058 00059 /* 00060 * Public structures and types 00061 */ 00062 00063 00064 /** 00065 * @brief The ROHC decompressor states 00066 * 00067 * The different ROHC operation states at decompressor as defined in section 00068 * 4.3.2 of RFC 3095. 00069 * 00070 * @ingroup rohc_decomp 00071 * 00072 * @see rohc_decomp_get_state_descr 00073 */ 00074 typedef enum 00075 { 00076 /** Unknown decompressor state */ 00077 ROHC_DECOMP_STATE_UNKNOWN = 0, 00078 /** The No Context state */ 00079 ROHC_DECOMP_STATE_NC = 1, 00080 /** The Static Context state */ 00081 ROHC_DECOMP_STATE_SC = 2, 00082 /** The Full Context state */ 00083 ROHC_DECOMP_STATE_FC = 3, 00084 } rohc_decomp_state_t; 00085 00086 00087 /** 00088 * @brief Some information about the last decompressed packet 00089 * 00090 * The structure is used by the \ref rohc_decomp_get_last_packet_info function 00091 * to store some information about the last decompressed packet. 00092 * 00093 * Versioning works as follow: 00094 * - The \e version_major field defines the compatibility level. If the major 00095 * number given by user does not match the one expected by the library, 00096 * an error is returned. 00097 * - The \e version_minor field defines the extension level. If the minor 00098 * number given by user does not match the one expected by the library, 00099 * only the fields supported in that minor version will be filled by 00100 * \ref rohc_decomp_get_last_packet_info. 00101 * 00102 * Notes for developers: 00103 * - Increase the major version if a field is removed. 00104 * - Increase the major version if a field is added at the beginning or in 00105 * the middle of the structure. 00106 * - Increase the minor version if a field is added at the very end of the 00107 * structure. 00108 * - The version_major and version_minor fields must be located at the very 00109 * beginning of the structure. 00110 * - The structure must be packed. 00111 * 00112 * Supported versions: 00113 * - Major 0 / Minor 0 contains: version_major, version_minor, context_mode, 00114 * context_state, profile_id, nr_lost_packets, nr_misordered_packets, and 00115 * is_duplicated 00116 * - Major 0 / Minor = 1 added: corrected_crc_failures, 00117 * corrected_sn_wraparounds, corrected_wrong_sn_updates, and packet_type 00118 * 00119 * @ingroup rohc_decomp 00120 * 00121 * @see rohc_decomp_get_last_packet_info 00122 */ 00123 typedef struct 00124 { 00125 /** The major version of this structure */ 00126 unsigned short version_major; 00127 /** The minor version of this structure */ 00128 unsigned short version_minor; 00129 /** The mode of the last context used by the compressor */ 00130 rohc_mode_t context_mode; 00131 /** The state of the last context used by the compressor */ 00132 rohc_decomp_state_t context_state; 00133 /** The profile ID of the last context used by the compressor */ 00134 int profile_id; 00135 /** The number of (possible) lost packet(s) before last packet */ 00136 unsigned long nr_lost_packets; 00137 /** The number of packet(s) before the last packet if late */ 00138 unsigned long nr_misordered_packets; 00139 /** Is last packet a (possible) duplicated packet? */ 00140 bool is_duplicated; 00141 00142 /* added in 0.1 */ 00143 /** The number of successful corrections upon CRC failure */ 00144 unsigned long corrected_crc_failures; 00145 /** The number of successful corrections of SN wraparound upon CRC failure */ 00146 unsigned long corrected_sn_wraparounds; 00147 /** The number of successful corrections of incorrect SN updates upon CRC 00148 * failure */ 00149 unsigned long corrected_wrong_sn_updates; 00150 /** The type of the last decompressed ROHC packet */ 00151 rohc_packet_t packet_type; 00152 00153 } __attribute__((packed)) rohc_decomp_last_packet_info_t; 00154 00155 00156 /** 00157 * @brief Some information about one decompression context 00158 * 00159 * The structure is used by the \ref rohc_decomp_get_context_info function 00160 * to store some information about one decompression context. 00161 * 00162 * Versioning works as follow: 00163 * - The \e version_major field defines the compatibility level. If the major 00164 * number given by user does not match the one expected by the library, 00165 * an error is returned. 00166 * - The \e version_minor field defines the extension level. If the minor 00167 * number given by user does not match the one expected by the library, 00168 * only the fields supported in that minor version will be filled by 00169 * \ref rohc_decomp_get_context_info. 00170 * 00171 * Notes for developers: 00172 * - Increase the major version if a field is removed. 00173 * - Increase the major version if a field is added at the beginning or in 00174 * the middle of the structure. 00175 * - Increase the minor version if a field is added at the very end of the 00176 * structure. 00177 * - The version_major and version_minor fields must be located at the very 00178 * beginning of the structure. 00179 * - The structure must be packed. 00180 * 00181 * Supported versions: 00182 * - Major 0 / Minor 0 contains: version_major, version_minor, packets_nr, 00183 * comp_bytes_nr, uncomp_bytes_nr, corrected_crc_failures, 00184 * corrected_sn_wraparounds, and corrected_wrong_sn_updates. 00185 * 00186 * @ingroup rohc_decomp 00187 * 00188 * @see rohc_decomp_get_context_info 00189 */ 00190 typedef struct 00191 { 00192 /** The major version of this structure */ 00193 unsigned short version_major; 00194 /** The minor version of this structure */ 00195 unsigned short version_minor; 00196 /** The number of packets processed by the context */ 00197 unsigned long packets_nr; 00198 /** The number of compressed bytes received by the context */ 00199 unsigned long comp_bytes_nr; 00200 /** The number of uncompressed bytes produced by the context */ 00201 unsigned long uncomp_bytes_nr; 00202 /** The number of successful corrections upon CRC failure */ 00203 unsigned long corrected_crc_failures; 00204 /** The number of successful corrections of SN wraparound upon CRC failure */ 00205 unsigned long corrected_sn_wraparounds; 00206 /** The number of successful corrections of incorrect SN updates upon CRC 00207 * failure */ 00208 unsigned long corrected_wrong_sn_updates; 00209 00210 } __attribute__((packed)) rohc_decomp_context_info_t; 00211 00212 00213 /** 00214 * @brief Some general information about the decompressor 00215 * 00216 * The structure is used by the \ref rohc_decomp_get_general_info function 00217 * to store some general information about the decompressor. 00218 * 00219 * Versioning works as follow: 00220 * - The \e version_major field defines the compatibility level. If the major 00221 * number given by user does not match the one expected by the library, 00222 * an error is returned. 00223 * - The \e version_minor field defines the extension level. If the minor 00224 * number given by user does not match the one expected by the library, 00225 * only the fields supported in that minor version will be filled by 00226 * \ref rohc_decomp_get_general_info. 00227 * 00228 * Notes for developers: 00229 * - Increase the major version if a field is removed. 00230 * - Increase the major version if a field is added at the beginning or in 00231 * the middle of the structure. 00232 * - Increase the minor version if a field is added at the very end of the 00233 * structure. 00234 * - The version_major and version_minor fields must be located at the very 00235 * beginning of the structure. 00236 * - The structure must be packed. 00237 * 00238 * Supported versions: 00239 * - major 0 and minor = 0 contains: version_major, version_minor, 00240 * contexts_nr, packets_nr, comp_bytes_nr, and uncomp_bytes_nr. 00241 * 00242 * @ingroup rohc_decomp 00243 * 00244 * @see rohc_decomp_get_general_info 00245 */ 00246 typedef struct 00247 { 00248 /** The major version of this structure */ 00249 unsigned short version_major; 00250 /** The minor version of this structure */ 00251 unsigned short version_minor; 00252 /** The number of contexts used by the decompressor */ 00253 size_t contexts_nr; 00254 /** The number of packets processed by the decompressor */ 00255 unsigned long packets_nr; 00256 /** The number of compressed bytes received by the decompressor */ 00257 unsigned long comp_bytes_nr; 00258 /** The number of uncompressed bytes produced by the decompressor */ 00259 unsigned long uncomp_bytes_nr; 00260 00261 /* added in 0.1 */ 00262 /** The cumulative number of successful corrections upon CRC failure */ 00263 unsigned long corrected_crc_failures; 00264 /** The cumulative number of successful corrections of SN wraparound 00265 * upon CRC failure */ 00266 unsigned long corrected_sn_wraparounds; 00267 /** The cumulative number of successful corrections of incorrect SN updates 00268 * upon CRC failure */ 00269 unsigned long corrected_wrong_sn_updates; 00270 00271 } __attribute__((packed)) rohc_decomp_general_info_t; 00272 00273 00274 /** 00275 * @brief The different features of the ROHC decompressor 00276 * 00277 * Features for the ROHC decompressor control whether mechanisms defined as 00278 * optional by RFCs are enabled or not. They can be set or unset with the 00279 * function \ref rohc_decomp_set_features. 00280 * 00281 * @ingroup rohc_decomp 00282 * 00283 * @see rohc_decomp_set_features 00284 */ 00285 typedef enum 00286 { 00287 /** No feature at all */ 00288 ROHC_DECOMP_FEATURE_NONE = 0, 00289 /** Attempt packet repair in case of CRC failure */ 00290 ROHC_DECOMP_FEATURE_CRC_REPAIR = (1 << 0), 00291 /** Be compatible with 1.6.x versions */ 00292 ROHC_DECOMP_FEATURE_COMPAT_1_6_x = (1 << 1), 00293 /** Dump content of packets in traces (beware: performance impact) */ 00294 ROHC_DECOMP_FEATURE_DUMP_PACKETS = (1 << 3), 00295 00296 } rohc_decomp_features_t; 00297 00298 00299 00300 /* 00301 * Functions related to decompressor: 00302 */ 00303 00304 struct rohc_decomp * ROHC_EXPORT rohc_decomp_new2(const rohc_cid_type_t cid_type, 00305 const rohc_cid_t max_cid, 00306 const rohc_mode_t mode) 00307 __attribute__((warn_unused_result)); 00308 00309 void ROHC_EXPORT rohc_decomp_free(struct rohc_decomp *const decomp); 00310 00311 rohc_status_t ROHC_EXPORT rohc_decompress3(struct rohc_decomp *const decomp, 00312 const struct rohc_buf rohc_packet, 00313 struct rohc_buf *const uncomp_packet, 00314 struct rohc_buf *const rcvd_feedback, 00315 struct rohc_buf *const feedback_send) 00316 __attribute__((warn_unused_result)); 00317 00318 00319 00320 /* 00321 * Functions related to statistics: 00322 */ 00323 00324 const char * ROHC_EXPORT rohc_decomp_get_state_descr(const rohc_decomp_state_t state) 00325 __attribute__((warn_unused_result, const)); 00326 00327 bool ROHC_EXPORT rohc_decomp_get_general_info(const struct rohc_decomp *const decomp, 00328 rohc_decomp_general_info_t *const info) 00329 __attribute__((warn_unused_result)); 00330 00331 bool ROHC_EXPORT rohc_decomp_get_context_info(const struct rohc_decomp *const decomp, 00332 const rohc_cid_t cid, 00333 rohc_decomp_context_info_t *const info) 00334 __attribute__((warn_unused_result)); 00335 00336 bool ROHC_EXPORT rohc_decomp_get_last_packet_info(const struct rohc_decomp *const decomp, 00337 rohc_decomp_last_packet_info_t *const info) 00338 __attribute__((warn_unused_result)); 00339 00340 00341 /* 00342 * Functions related to user parameters 00343 */ 00344 00345 /* CID */ 00346 00347 bool ROHC_EXPORT rohc_decomp_get_cid_type(const struct rohc_decomp *const decomp, 00348 rohc_cid_type_t *const cid_type) 00349 __attribute__((warn_unused_result)); 00350 00351 bool ROHC_EXPORT rohc_decomp_get_max_cid(const struct rohc_decomp *const decomp, 00352 size_t *const max_cid) 00353 __attribute__((warn_unused_result)); 00354 00355 /* MRRU */ 00356 00357 bool ROHC_EXPORT rohc_decomp_set_mrru(struct rohc_decomp *const decomp, 00358 const size_t mrru) 00359 __attribute__((warn_unused_result)); 00360 00361 bool ROHC_EXPORT rohc_decomp_get_mrru(const struct rohc_decomp *const decomp, 00362 size_t *const mrru) 00363 __attribute__((warn_unused_result)); 00364 00365 /* pRTT */ 00366 00367 bool ROHC_EXPORT rohc_decomp_set_prtt(struct rohc_decomp *const decomp, 00368 const size_t prtt) 00369 __attribute__((warn_unused_result)); 00370 00371 bool ROHC_EXPORT rohc_decomp_get_prtt(const struct rohc_decomp *const decomp, 00372 size_t *const prtt) 00373 __attribute__((warn_unused_result)); 00374 00375 /* feedback rate-limiting */ 00376 00377 bool ROHC_EXPORT rohc_decomp_set_rate_limits(struct rohc_decomp *const decomp, 00378 const size_t k, const size_t n, 00379 const size_t k_1, const size_t n_1, 00380 const size_t k_2, const size_t n_2) 00381 __attribute__((warn_unused_result)); 00382 00383 bool ROHC_EXPORT rohc_decomp_get_rate_limits(const struct rohc_decomp *const decomp, 00384 size_t *const k, size_t *const n, 00385 size_t *const k_1, size_t *const n_1, 00386 size_t *const k_2, size_t *const n_2) 00387 __attribute__((warn_unused_result)); 00388 00389 /* decompression library features */ 00390 00391 bool ROHC_EXPORT rohc_decomp_set_features(struct rohc_decomp *const decomp, 00392 const rohc_decomp_features_t features) 00393 __attribute__((warn_unused_result)); 00394 00395 00396 /* 00397 * Functions related to decompression profiles 00398 */ 00399 00400 bool ROHC_EXPORT rohc_decomp_profile_enabled(const struct rohc_decomp *const decomp, 00401 const rohc_profile_t profile) 00402 __attribute__((warn_unused_result)); 00403 00404 bool ROHC_EXPORT rohc_decomp_enable_profile(struct rohc_decomp *const decomp, 00405 const rohc_profile_t profile) 00406 __attribute__((warn_unused_result)); 00407 00408 bool ROHC_EXPORT rohc_decomp_disable_profile(struct rohc_decomp *const decomp, 00409 const rohc_profile_t profile) 00410 __attribute__((warn_unused_result)); 00411 00412 bool ROHC_EXPORT rohc_decomp_enable_profiles(struct rohc_decomp *const decomp, 00413 ...) 00414 __attribute__((warn_unused_result)); 00415 00416 bool ROHC_EXPORT rohc_decomp_disable_profiles(struct rohc_decomp *const decomp, 00417 ...) 00418 __attribute__((warn_unused_result)); 00419 00420 00421 /* 00422 * Functions related to traces 00423 */ 00424 00425 bool ROHC_EXPORT rohc_decomp_set_traces_cb2(struct rohc_decomp *const decomp, 00426 rohc_trace_callback2_t callback, 00427 void *const priv_ctxt) 00428 __attribute__((warn_unused_result)); 00429 00430 00431 #undef ROHC_EXPORT /* do not pollute outside this header */ 00432 00433 #ifdef __cplusplus 00434 } 00435 #endif 00436 00437 #endif /* ROHC_DECOMP_H */ 00438
1.6.1