|
ROHC compression/decompression library
|
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 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00041 # include <rohc/rohc_comp.h> 00042 #endif /* !ROHC_ENABLE_DEPRECATED_API */ 00043 00044 00045 /** Macro that handles DLL export declarations gracefully */ 00046 #ifdef DLL_EXPORT /* passed by autotools on command line */ 00047 #define ROHC_EXPORT __declspec(dllexport) 00048 #else 00049 #define ROHC_EXPORT 00050 #endif 00051 00052 00053 /* 00054 * Declare the private ROHC decompressor structure that is defined inside the 00055 * library. 00056 */ 00057 00058 struct rohc_decomp; 00059 00060 00061 00062 /* 00063 * Public structures and types 00064 */ 00065 00066 00067 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00068 00069 /** 00070 * @brief The ROHC decompressor states 00071 * 00072 * The different ROHC operation states at decompressor as defined in section 00073 * 4.3.2 of RFC 3095. 00074 * 00075 * @deprecated do not use this type anymore, use \ref rohc_decomp_state_t 00076 * instead 00077 * 00078 * @ingroup rohc_decomp 00079 * 00080 * @see rohc_decomp_get_state_descr 00081 */ 00082 typedef enum 00083 { 00084 /// The No Context state 00085 NO_CONTEXT = 1, 00086 /// The Static Context state 00087 STATIC_CONTEXT = 2, 00088 /// The Full Context state 00089 FULL_CONTEXT = 3, 00090 } rohc_d_state 00091 ROHC_DEPRECATED("please do not use this type anymore, " 00092 "use rohc_decomp_state_t instead"); 00093 00094 #endif /* !ROHC_ENABLE_DEPRECATED_API) */ 00095 00096 /** 00097 * @brief The ROHC decompressor states 00098 * 00099 * The different ROHC operation states at decompressor as defined in section 00100 * 4.3.2 of RFC 3095. 00101 * 00102 * @ingroup rohc_decomp 00103 * 00104 * @see rohc_decomp_get_state_descr 00105 */ 00106 typedef enum 00107 { 00108 /** The No Context state */ 00109 ROHC_DECOMP_STATE_NC = 1, 00110 /** The Static Context state */ 00111 ROHC_DECOMP_STATE_SC = 2, 00112 /** The Full Context state */ 00113 ROHC_DECOMP_STATE_FC = 3, 00114 } rohc_decomp_state_t; 00115 00116 00117 /** 00118 * @brief Some information about the last decompressed packet 00119 * 00120 * The structure is used by the \ref rohc_decomp_get_last_packet_info function 00121 * to store some information about the last decompressed packet. 00122 * 00123 * Versioning works as follow: 00124 * - The \e version_major field defines the compatibility level. If the major 00125 * number given by user does not match the one expected by the library, 00126 * an error is returned. 00127 * - The \e version_minor field defines the extension level. If the minor 00128 * number given by user does not match the one expected by the library, 00129 * only the fields supported in that minor version will be filled by 00130 * \ref rohc_decomp_get_last_packet_info. 00131 * 00132 * Notes for developers: 00133 * - Increase the major version if a field is removed. 00134 * - Increase the major version if a field is added at the beginning or in 00135 * the middle of the structure. 00136 * - Increase the minor version if a field is added at the very end of the 00137 * structure. 00138 * - The version_major and version_minor fields must be located at the very 00139 * beginning of the structure. 00140 * - The structure must be packed. 00141 * 00142 * Supported versions: 00143 * - Major 0 / Minor 0 contains: version_major, version_minor, context_mode, 00144 * context_state, profile_id, nr_lost_packets, nr_misordered_packets, and 00145 * is_duplicated 00146 * - Major 0 / Minor = 1 added: corrected_crc_failures, 00147 * corrected_sn_wraparounds, corrected_wrong_sn_updates, and packet_type 00148 * 00149 * @ingroup rohc_decomp 00150 * 00151 * @see rohc_decomp_get_last_packet_info 00152 */ 00153 typedef struct 00154 { 00155 /** The major version of this structure */ 00156 unsigned short version_major; 00157 /** The minor version of this structure */ 00158 unsigned short version_minor; 00159 /** The mode of the last context used by the compressor */ 00160 rohc_mode_t context_mode; 00161 /** The state of the last context used by the compressor */ 00162 rohc_decomp_state_t context_state; 00163 /** The profile ID of the last context used by the compressor */ 00164 int profile_id; 00165 /** The number of (possible) lost packet(s) before last packet */ 00166 unsigned long nr_lost_packets; 00167 /** The number of packet(s) before the last packet if late */ 00168 unsigned long nr_misordered_packets; 00169 /** Is last packet a (possible) duplicated packet? */ 00170 bool is_duplicated; 00171 00172 /* added in 0.1 */ 00173 /** The number of successful corrections upon CRC failure */ 00174 unsigned long corrected_crc_failures; 00175 /** The number of successful corrections of SN wraparound upon CRC failure */ 00176 unsigned long corrected_sn_wraparounds; 00177 /** The number of successful corrections of incorrect SN updates upon CRC 00178 * failure */ 00179 unsigned long corrected_wrong_sn_updates; 00180 /** The type of the last decompressed ROHC packet */ 00181 rohc_packet_t packet_type; 00182 00183 } __attribute__((packed)) rohc_decomp_last_packet_info_t; 00184 00185 00186 /** 00187 * @brief Some general information about the decompressor 00188 * 00189 * The structure is used by the \ref rohc_decomp_get_general_info function 00190 * to store some general information about the decompressor. 00191 * 00192 * Versioning works as follow: 00193 * - The \e version_major field defines the compatibility level. If the major 00194 * number given by user does not match the one expected by the library, 00195 * an error is returned. 00196 * - The \e version_minor field defines the extension level. If the minor 00197 * number given by user does not match the one expected by the library, 00198 * only the fields supported in that minor version will be filled by 00199 * \ref rohc_decomp_get_general_info. 00200 * 00201 * Notes for developers: 00202 * - Increase the major version if a field is removed. 00203 * - Increase the major version if a field is added at the beginning or in 00204 * the middle of the structure. 00205 * - Increase the minor version if a field is added at the very end of the 00206 * structure. 00207 * - The version_major and version_minor fields must be located at the very 00208 * beginning of the structure. 00209 * - The structure must be packed. 00210 * 00211 * Supported versions: 00212 * - major 0 and minor = 0 contains: version_major, version_minor, 00213 * contexts_nr, packets_nr, comp_bytes_nr, and uncomp_bytes_nr. 00214 * 00215 * @ingroup rohc_decomp 00216 * 00217 * @see rohc_decomp_get_general_info 00218 */ 00219 typedef struct 00220 { 00221 /** The major version of this structure */ 00222 unsigned short version_major; 00223 /** The minor version of this structure */ 00224 unsigned short version_minor; 00225 /** The number of contexts used by the decompressor */ 00226 size_t contexts_nr; 00227 /** The number of packets processed by the decompressor */ 00228 unsigned long packets_nr; 00229 /** The number of compressed bytes received by the decompressor */ 00230 unsigned long comp_bytes_nr; 00231 /** The number of uncompressed bytes produced by the decompressor */ 00232 unsigned long uncomp_bytes_nr; 00233 } __attribute__((packed)) rohc_decomp_general_info_t; 00234 00235 00236 /** 00237 * @brief The different features of the ROHC decompressor 00238 * 00239 * Features for the ROHC decompressor control whether mechanisms defined as 00240 * optional by RFCs are enabled or not. They can be set or unset with the 00241 * function \ref rohc_decomp_set_features. 00242 * 00243 * @ingroup rohc_decomp 00244 * 00245 * @see rohc_decomp_set_features 00246 */ 00247 typedef enum 00248 { 00249 /** No feature at all */ 00250 ROHC_DECOMP_FEATURE_NONE = 0, 00251 /** Attempt packet repair in case of CRC failure */ 00252 ROHC_DECOMP_FEATURE_CRC_REPAIR = (1 << 0), 00253 /** Be compatible with 1.6.x versions */ 00254 ROHC_DECOMP_FEATURE_COMPAT_1_6_x = (1 << 1), 00255 00256 } rohc_decomp_features_t; 00257 00258 00259 00260 /* 00261 * Functions related to decompressor: 00262 */ 00263 00264 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00265 struct rohc_decomp * ROHC_EXPORT rohc_alloc_decompressor(struct rohc_comp *compressor) 00266 ROHC_DEPRECATED("please do not use this function anymore, " 00267 "use rohc_decomp_new() instead"); 00268 void ROHC_EXPORT rohc_free_decompressor(struct rohc_decomp *decomp) 00269 ROHC_DEPRECATED("please do not use this function anymore, " 00270 "use rohc_decomp_free() instead"); 00271 00272 struct rohc_decomp * ROHC_EXPORT rohc_decomp_new(const rohc_cid_type_t cid_type, 00273 const rohc_cid_t max_cid, 00274 const rohc_mode_t mode, 00275 struct rohc_comp *const comp) 00276 __attribute__((warn_unused_result)) 00277 ROHC_DEPRECATED("please do not use this function anymore, " 00278 "use rohc_decomp_new2() instead"); 00279 #endif 00280 struct rohc_decomp * ROHC_EXPORT rohc_decomp_new2(const rohc_cid_type_t cid_type, 00281 const rohc_cid_t max_cid, 00282 const rohc_mode_t mode) 00283 __attribute__((warn_unused_result)); 00284 void ROHC_EXPORT rohc_decomp_free(struct rohc_decomp *const decomp); 00285 00286 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00287 int ROHC_EXPORT rohc_decompress(struct rohc_decomp *decomp, 00288 unsigned char *ibuf, 00289 int isize, 00290 unsigned char *obuf, 00291 int osize) 00292 ROHC_DEPRECATED("please do not use this function anymore, use " 00293 "rohc_decompress3() instead"); 00294 00295 int ROHC_EXPORT rohc_decompress2(struct rohc_decomp *const decomp, 00296 const struct rohc_ts arrival_time, 00297 const unsigned char *const rohc_packet, 00298 const size_t rohc_packet_len, 00299 unsigned char *const uncomp_packet, 00300 const size_t uncom_packet_max_len, 00301 size_t *const uncomp_packet_len) 00302 __attribute__((warn_unused_result)) 00303 ROHC_DEPRECATED("please do not use this function anymore, use " 00304 "rohc_decompress3() instead"); 00305 #endif /* !ROHC_ENABLE_DEPRECATED_API */ 00306 00307 rohc_status_t ROHC_EXPORT rohc_decompress3(struct rohc_decomp *const decomp, 00308 const struct rohc_buf rohc_packet, 00309 struct rohc_buf *const uncomp_packet, 00310 struct rohc_buf *const rcvd_feedback, 00311 struct rohc_buf *const feedback_send) 00312 __attribute__((warn_unused_result)); 00313 00314 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00315 int ROHC_EXPORT rohc_decompress_both(struct rohc_decomp *decomp, 00316 unsigned char *ibuf, 00317 int isize, 00318 unsigned char *obuf, 00319 int osize, 00320 int large) 00321 ROHC_DEPRECATED("please do not use this function anymore, use " 00322 "rohc_decomp_new() and rohc_decompress3() instead"); 00323 #endif /* !ROHC_ENABLE_DEPRECATED_API */ 00324 00325 00326 /* 00327 * Functions related to statistics: 00328 */ 00329 00330 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00331 int ROHC_EXPORT rohc_d_statistics(struct rohc_decomp *decomp, 00332 unsigned int indent, 00333 char *buffer) 00334 ROHC_DEPRECATED("please do not use this function anymore, use " 00335 "rohc_decomp_get_general_info() and " 00336 "rohc_decomp_get_last_packet_info() instead"); 00337 00338 void ROHC_EXPORT clear_statistics(struct rohc_decomp *decomp) 00339 ROHC_DEPRECATED("please do not use this function anymore"); 00340 #endif /* !ROHC_ENABLE_DEPRECATED_API */ 00341 00342 const char * ROHC_EXPORT rohc_decomp_get_state_descr(const rohc_decomp_state_t state); 00343 00344 bool ROHC_EXPORT rohc_decomp_get_general_info(const struct rohc_decomp *const decomp, 00345 rohc_decomp_general_info_t *const info) 00346 __attribute__((warn_unused_result)); 00347 00348 bool ROHC_EXPORT rohc_decomp_get_last_packet_info(const struct rohc_decomp *const decomp, 00349 rohc_decomp_last_packet_info_t *const info) 00350 __attribute__((warn_unused_result)); 00351 00352 00353 /* 00354 * Functions related to user parameters 00355 */ 00356 00357 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00358 void ROHC_EXPORT user_interactions(struct rohc_decomp *decomp, 00359 int feedback_maxval) 00360 ROHC_DEPRECATED("please do not use this function anymore"); 00361 #endif 00362 00363 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00364 bool ROHC_EXPORT rohc_decomp_set_cid_type(struct rohc_decomp *const decomp, 00365 const rohc_cid_type_t cid_type) 00366 __attribute__((warn_unused_result)) 00367 ROHC_DEPRECATED("please do not use this function anymore, use the " 00368 "parameter cid_type of rohc_decomp_new() instead"); 00369 #endif 00370 bool ROHC_EXPORT rohc_decomp_get_cid_type(const struct rohc_decomp *const decomp, 00371 rohc_cid_type_t *const cid_type) 00372 __attribute__((warn_unused_result)); 00373 00374 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00375 bool ROHC_EXPORT rohc_decomp_set_max_cid(struct rohc_decomp *const decomp, 00376 const size_t max_cid) 00377 __attribute__((warn_unused_result)) 00378 ROHC_DEPRECATED("please do not use this function anymore, use the " 00379 "parameter max_cid of rohc_decomp_new() instead"); 00380 #endif 00381 bool ROHC_EXPORT rohc_decomp_get_max_cid(const struct rohc_decomp *const decomp, 00382 size_t *const max_cid) 00383 __attribute__((warn_unused_result)); 00384 00385 bool ROHC_EXPORT rohc_decomp_set_mrru(struct rohc_decomp *const decomp, 00386 const size_t mrru) 00387 __attribute__((warn_unused_result)); 00388 bool ROHC_EXPORT rohc_decomp_get_mrru(const struct rohc_decomp *const decomp, 00389 size_t *const mrru) 00390 __attribute__((warn_unused_result)); 00391 00392 bool ROHC_EXPORT rohc_decomp_set_features(struct rohc_decomp *const decomp, 00393 const rohc_decomp_features_t features) 00394 __attribute__((warn_unused_result)); 00395 00396 00397 /* 00398 * Functions related to decompression profiles 00399 */ 00400 00401 bool ROHC_EXPORT rohc_decomp_profile_enabled(const struct rohc_decomp *const decomp, 00402 const rohc_profile_t profile) 00403 __attribute__((warn_unused_result)); 00404 00405 bool ROHC_EXPORT rohc_decomp_enable_profile(struct rohc_decomp *const decomp, 00406 const rohc_profile_t profile) 00407 __attribute__((warn_unused_result)); 00408 00409 bool ROHC_EXPORT rohc_decomp_disable_profile(struct rohc_decomp *const decomp, 00410 const rohc_profile_t profile) 00411 __attribute__((warn_unused_result)); 00412 00413 bool ROHC_EXPORT rohc_decomp_enable_profiles(struct rohc_decomp *const decomp, 00414 ...) 00415 __attribute__((warn_unused_result)); 00416 00417 bool ROHC_EXPORT rohc_decomp_disable_profiles(struct rohc_decomp *const decomp, 00418 ...) 00419 __attribute__((warn_unused_result)); 00420 00421 00422 /* 00423 * Functions related to traces 00424 */ 00425 00426 #if !defined(ROHC_ENABLE_DEPRECATED_API) || ROHC_ENABLE_DEPRECATED_API == 1 00427 00428 bool ROHC_EXPORT rohc_decomp_set_traces_cb(struct rohc_decomp *const decomp, 00429 rohc_trace_callback_t callback) 00430 __attribute__((warn_unused_result)) 00431 ROHC_DEPRECATED("do not use this function anymore, " 00432 "use rohc_decomp_set_traces_cb2() instead"); 00433 00434 #endif /* !ROHC_ENABLE_DEPRECATED_API */ 00435 00436 bool ROHC_EXPORT rohc_decomp_set_traces_cb2(struct rohc_decomp *const decomp, 00437 rohc_trace_callback2_t callback, 00438 void *const priv_ctxt) 00439 __attribute__((warn_unused_result)); 00440 00441 00442 #undef ROHC_EXPORT /* do not pollute outside this header */ 00443 00444 #ifdef __cplusplus 00445 } 00446 #endif 00447 00448 #endif /* ROHC_DECOMP_H */ 00449
1.7.6.1