|
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_comp.h 00019 * @brief ROHC compression 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 COMP_H 00026 #define COMP_H 00027 00028 #include "rohc.h" 00029 #include "rohc_packets.h" 00030 #include "rohc_traces.h" 00031 00032 #include <stdlib.h> 00033 #ifdef __KERNEL__ 00034 # include <linux/types.h> 00035 #else 00036 # include <stdbool.h> 00037 #endif 00038 00039 00040 /** Macro that handles DLL export declarations gracefully */ 00041 #ifdef DLL_EXPORT /* passed by autotools on command line */ 00042 #define ROHC_EXPORT __declspec(dllexport) 00043 #else 00044 #define ROHC_EXPORT 00045 #endif 00046 00047 00048 /* 00049 * Declare the private ROHC compressor structure that is defined inside the 00050 * library. 00051 */ 00052 00053 struct rohc_comp; 00054 00055 00056 /* 00057 * Public structures and types 00058 */ 00059 00060 00061 /** 00062 * @brief The different ROHC compressor states 00063 * 00064 * See 4.3.1 in the RFC 3095. 00065 * 00066 * If you add a new compressor state, please also add the corresponding 00067 * textual description in \ref rohc_comp_get_state_descr. 00068 * 00069 * @ingroup rohc_comp 00070 */ 00071 typedef enum 00072 { 00073 /** The Initialization and Refresh (IR) state */ 00074 IR = 1, 00075 /** The First Order (FO) state */ 00076 FO = 2, 00077 /** The Second Order (SO) state */ 00078 SO = 3, 00079 } rohc_c_state; 00080 00081 00082 #if !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 00083 00084 /** 00085 * @brief Some information about the last compressed packet 00086 * 00087 * Non-extensible version of rohc_comp_last_packet_info2_t 00088 * 00089 * @ingroup rohc_comp 00090 */ 00091 typedef struct 00092 { 00093 /** The mode of the last context used by the compressor */ 00094 rohc_mode context_mode; 00095 /** The state of the last context used by the compressor */ 00096 rohc_c_state context_state; 00097 /** The type of ROHC packet created for the last compressed packet */ 00098 rohc_packet_t packet_type; 00099 /** The uncompressed size (in bytes) of the last compressed packet */ 00100 unsigned long total_last_uncomp_size; 00101 /** The uncompressed size (in bytes) of the last compressed header */ 00102 unsigned long header_last_uncomp_size; 00103 /** The compressed size (in bytes) of the last compressed packet */ 00104 unsigned long total_last_comp_size; 00105 /** The compressed size (in bytes) of the last compressed header */ 00106 unsigned long header_last_comp_size; 00107 } rohc_comp_last_packet_info_t; 00108 00109 #endif /* !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 */ 00110 00111 00112 /** 00113 * @brief Some information about the last compressed packet 00114 * 00115 * Extensible version of rohc_comp_last_packet_info_t. Versioning works 00116 * as follow: 00117 * - The 'version_major' field defines the compatibility level. If the major 00118 * number given by user does not match the one expected by the library, 00119 * an error is returned. 00120 * - The 'version_minor' field defines the extension level. If the minor 00121 * number given by user does not match the one expected by the library, 00122 * only the fields supported in that minor version will be filled by 00123 * \ref rohc_comp_get_last_packet_info2. 00124 * 00125 * Notes for developers: 00126 * - Increase the major version if a field is removed. 00127 * - Increase the major version if a field is added at the beginning or in 00128 * the middle of the structure. 00129 * - Increase the minor version if a field is added at the very end of the 00130 * structure. 00131 * - The version_major and version_minor fields must be located at the very 00132 * beginning of the structure. 00133 * - The structure must be packed. 00134 * 00135 * Supported versions: 00136 * - Major = 0: 00137 * - Minor = 0: 00138 * version_major 00139 * version_minor 00140 * context_id 00141 * is_context_init 00142 * context_mode 00143 * context_state 00144 * context_used 00145 * profile_id 00146 * packet_type 00147 * total_last_uncomp_size 00148 * header_last_uncomp_size 00149 * total_last_comp_size 00150 * header_last_comp_size 00151 * 00152 * @ingroup rohc_comp 00153 */ 00154 typedef struct 00155 { 00156 /** The major version of this structure */ 00157 unsigned short version_major; 00158 /** The minor version of this structure */ 00159 unsigned short version_minor; 00160 /** The Context ID (CID) */ 00161 unsigned int context_id; 00162 /** Whether the context was initialized (created/re-used) by the packet */ 00163 bool is_context_init; 00164 /** The mode of the last context used by the compressor */ 00165 rohc_mode context_mode; 00166 /** The state of the last context used by the compressor */ 00167 rohc_c_state context_state; 00168 /** Whether the last context used by the compressor is still in use */ 00169 bool context_used; 00170 /** The profile ID of the last context used by the compressor */ 00171 int profile_id; 00172 /** The type of ROHC packet created for the last compressed packet */ 00173 rohc_packet_t packet_type; 00174 /** The uncompressed size (in bytes) of the last compressed packet */ 00175 unsigned long total_last_uncomp_size; 00176 /** The uncompressed size (in bytes) of the last compressed header */ 00177 unsigned long header_last_uncomp_size; 00178 /** The compressed size (in bytes) of the last compressed packet */ 00179 unsigned long total_last_comp_size; 00180 /** The compressed size (in bytes) of the last compressed header */ 00181 unsigned long header_last_comp_size; 00182 } __attribute__((packed)) rohc_comp_last_packet_info2_t; 00183 00184 00185 /** 00186 * @brief Some general information about the compressor 00187 * 00188 * Versioning works as follow: 00189 * - The 'version_major' field defines the compatibility level. If the major 00190 * number given by user does not match the one expected by the library, 00191 * an error is returned. 00192 * - The 'version_minor' field defines the extension level. If the minor 00193 * number given by user does not match the one expected by the library, 00194 * only the fields supported in that minor version will be filled by 00195 * \ref rohc_comp_get_general_info. 00196 * 00197 * Notes for developers: 00198 * - Increase the major version if a field is removed. 00199 * - Increase the major version if a field is added at the beginning or in 00200 * the middle of the structure. 00201 * - Increase the minor version if a field is added at the very end of the 00202 * structure. 00203 * - The version_major and version_minor fields must be located at the very 00204 * beginning of the structure. 00205 * - The structure must be packed. 00206 * 00207 * Supported versions: 00208 * - Major = 0: 00209 * - Minor = 0: 00210 * version_major 00211 * version_minor 00212 * 00213 * @ingroup rohc_comp 00214 */ 00215 typedef struct 00216 { 00217 /** The major version of this structure */ 00218 unsigned short version_major; 00219 /** The minor version of this structure */ 00220 unsigned short version_minor; 00221 /** The number of contexts used by the compressor */ 00222 size_t contexts_nr; 00223 /** The number of packets processed by the compressor */ 00224 unsigned long packets_nr; 00225 /** The number of uncompressed bytes received by the compressor */ 00226 unsigned long uncomp_bytes_nr; 00227 /** The number of compressed bytes produced by the compressor */ 00228 unsigned long comp_bytes_nr; 00229 } __attribute__((packed)) rohc_comp_general_info_t; 00230 00231 00232 /** 00233 * @brief The prototype of the RTP detection callback 00234 * 00235 * @param ip The innermost IP packet 00236 * @param udp The UDP header of the packet 00237 * @param payload The UDP payload of the packet 00238 * @param payload_size The size of the UDP payload (in bytes) 00239 * @param rtp_private A pointer to a memory area to be used by the callback 00240 * function, may be NULL. 00241 * @return true if the packet is an RTP packet, false otherwise 00242 * 00243 * @see rohc_comp_set_rtp_detection_cb 00244 * @ingroup rohc_comp 00245 */ 00246 typedef bool (*rohc_rtp_detection_callback_t)(const unsigned char *const ip, 00247 const unsigned char *const udp, 00248 const unsigned char *const payload, 00249 const unsigned int payload_size, 00250 void *const rtp_private) 00251 __attribute__((warn_unused_result)); 00252 00253 00254 /** 00255 * @brief The prototype of the callback for random numbers 00256 * 00257 * @param comp The ROHC compressor 00258 * @param user_context The context given by the user when he/she called the 00259 * rohc_comp_set_random_cb function, may be NULL. 00260 * 00261 * @see rohc_comp_set_random_cb 00262 * @ingroup rohc_comp 00263 */ 00264 typedef int (*rohc_comp_random_cb_t) (const struct rohc_comp *const comp, 00265 void *const user_context) 00266 __attribute__((warn_unused_result)); 00267 00268 00269 /* 00270 * Prototypes of main public functions related to ROHC compression 00271 */ 00272 00273 struct rohc_comp * ROHC_EXPORT rohc_alloc_compressor(int max_cid, 00274 int jam_use, 00275 int adapt_size, 00276 int encap_size); 00277 void ROHC_EXPORT rohc_free_compressor(struct rohc_comp *comp); 00278 00279 bool ROHC_EXPORT rohc_comp_set_traces_cb(struct rohc_comp *const comp, 00280 rohc_trace_callback_t callback) 00281 __attribute__((warn_unused_result)); 00282 00283 bool ROHC_EXPORT rohc_comp_set_random_cb(struct rohc_comp *const comp, 00284 rohc_comp_random_cb_t callback, 00285 void *const user_context) 00286 __attribute__((warn_unused_result)); 00287 00288 #if !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 00289 int ROHC_EXPORT rohc_compress(struct rohc_comp *comp, 00290 unsigned char *ibuf, 00291 int isize, 00292 unsigned char *obuf, 00293 int osize) 00294 ROHC_DEPRECATED("please do not use this function anymore, " 00295 "use rohc_compress2() instead"); 00296 #endif /* !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 */ 00297 00298 int ROHC_EXPORT rohc_compress2(struct rohc_comp *const comp, 00299 const unsigned char *const uncomp_packet, 00300 const size_t uncomp_packet_len, 00301 unsigned char *const rohc_packet, 00302 const size_t rohc_packet_max_len, 00303 size_t *const rohc_packet_len) 00304 __attribute__((warn_unused_result)); 00305 00306 int ROHC_EXPORT rohc_comp_get_segment(struct rohc_comp *const comp, 00307 unsigned char *const segment, 00308 const size_t max_len, 00309 size_t *const len) 00310 __attribute__((warn_unused_result)); 00311 00312 bool ROHC_EXPORT rohc_comp_force_contexts_reinit(struct rohc_comp *const comp) 00313 __attribute__((warn_unused_result)); 00314 00315 00316 /* 00317 * Prototypes of public functions related to user interaction 00318 */ 00319 00320 int ROHC_EXPORT rohc_c_is_enabled(struct rohc_comp *comp); 00321 int ROHC_EXPORT rohc_c_using_small_cid(struct rohc_comp *comp); 00322 00323 void ROHC_EXPORT rohc_activate_profile(struct rohc_comp *comp, int profile); 00324 00325 void ROHC_EXPORT rohc_c_set_header(struct rohc_comp *compressor, int value); 00326 00327 #if !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 00328 void ROHC_EXPORT rohc_c_set_mrru(struct rohc_comp *compressor, int value) 00329 ROHC_DEPRECATED("please do not use this function anymore, " 00330 "use rohc_comp_set_mrru() instead"); 00331 #endif /* !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 */ 00332 bool ROHC_EXPORT rohc_comp_set_mrru(struct rohc_comp *const comp, 00333 const size_t mrru) 00334 __attribute__((warn_unused_result)); 00335 bool ROHC_EXPORT rohc_comp_get_mrru(const struct rohc_comp *const comp, 00336 size_t *const mrru) 00337 __attribute__((warn_unused_result)); 00338 00339 void ROHC_EXPORT rohc_c_set_max_cid(struct rohc_comp *compressor, int value); 00340 bool ROHC_EXPORT rohc_comp_get_max_cid(const struct rohc_comp *const comp, 00341 size_t *const max_cid) 00342 __attribute__((warn_unused_result)); 00343 00344 void ROHC_EXPORT rohc_c_set_large_cid(struct rohc_comp *compressor, int value); 00345 bool ROHC_EXPORT rohc_comp_get_cid_type(const struct rohc_comp *const comp, 00346 rohc_cid_type_t *const cid_type) 00347 __attribute__((warn_unused_result)); 00348 00349 void ROHC_EXPORT rohc_c_set_enable(struct rohc_comp *compressor, int value); 00350 00351 /* RTP stream detection through UDP ports */ 00352 bool ROHC_EXPORT rohc_comp_add_rtp_port(struct rohc_comp *const comp, 00353 const unsigned int port) 00354 __attribute__((warn_unused_result)); 00355 bool ROHC_EXPORT rohc_comp_remove_rtp_port(struct rohc_comp *const comp, 00356 const unsigned int port) 00357 __attribute__((warn_unused_result)); 00358 bool ROHC_EXPORT rohc_comp_reset_rtp_ports(struct rohc_comp *const comp) 00359 __attribute__((warn_unused_result)); 00360 00361 /* RTP stream detection through callback */ 00362 bool ROHC_EXPORT rohc_comp_set_rtp_detection_cb(struct rohc_comp *const comp, 00363 rohc_rtp_detection_callback_t callback, 00364 void *const rtp_private) 00365 __attribute__((warn_unused_result)); 00366 00367 00368 /* 00369 * Prototypes of public functions related to ROHC feedback 00370 */ 00371 00372 #if !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 00373 void ROHC_EXPORT c_piggyback_feedback(struct rohc_comp *comp, 00374 unsigned char *packet, 00375 int size) 00376 ROHC_DEPRECATED("please do not use this function anymore, " 00377 "use rohc_comp_piggyback_feedback() instead"); 00378 #endif /* !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 */ 00379 bool ROHC_EXPORT rohc_comp_piggyback_feedback(struct rohc_comp *const comp, 00380 const unsigned char *const feedback, 00381 const size_t size) 00382 __attribute__((warn_unused_result)); 00383 void ROHC_EXPORT c_deliver_feedback(struct rohc_comp *comp, 00384 unsigned char *feedback, 00385 int size); 00386 int ROHC_EXPORT rohc_feedback_flush(struct rohc_comp *comp, 00387 unsigned char *obuf, 00388 int osize); 00389 bool ROHC_EXPORT rohc_feedback_remove_locked(struct rohc_comp *const comp) 00390 __attribute__((warn_unused_result)); 00391 bool ROHC_EXPORT rohc_feedback_unlock(struct rohc_comp *const comp) 00392 __attribute__((warn_unused_result)); 00393 00394 /* Configure robustness to packet loss/damage */ 00395 bool ROHC_EXPORT rohc_comp_set_wlsb_window_width(struct rohc_comp *const comp, 00396 const size_t width) 00397 __attribute__((warn_unused_result)); 00398 bool ROHC_EXPORT rohc_comp_set_periodic_refreshes(struct rohc_comp *const comp, 00399 const size_t ir_timeout, 00400 const size_t fo_timeout) 00401 __attribute__((warn_unused_result)); 00402 00403 00404 /* 00405 * Prototypes of public functions related to ROHC compression statistics 00406 */ 00407 00408 #if !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 00409 int ROHC_EXPORT rohc_c_info(char *buffer) 00410 ROHC_DEPRECATED("please do not use this function anymore, " 00411 "use rohc_comp_get_general_info() instead"); 00412 int ROHC_EXPORT rohc_c_statistics(struct rohc_comp *comp, 00413 unsigned int indent, 00414 char *buffer) 00415 ROHC_DEPRECATED("please do not use this function anymore, " 00416 "use rohc_comp_get_general_info() instead"); 00417 int ROHC_EXPORT rohc_c_context(struct rohc_comp *comp, 00418 int cid, 00419 unsigned int indent, 00420 char *buffer) 00421 ROHC_DEPRECATED("please do not use this function anymore, " 00422 "use rohc_comp_get_general_info() instead"); 00423 int ROHC_EXPORT rohc_comp_get_last_packet_info(const struct rohc_comp *const comp, 00424 rohc_comp_last_packet_info_t *const info) 00425 ROHC_DEPRECATED("please do not use this function anymore, " 00426 "use rohc_comp_get_last_packet_info2() instead"); 00427 #endif /* !defined(ENABLE_DEPRECATED_API) || ENABLE_DEPRECATED_API == 1 */ 00428 00429 bool ROHC_EXPORT rohc_comp_get_general_info(const struct rohc_comp *const comp, 00430 rohc_comp_general_info_t *const info) 00431 __attribute__((warn_unused_result)); 00432 00433 bool ROHC_EXPORT rohc_comp_get_last_packet_info2(const struct rohc_comp *const comp, 00434 rohc_comp_last_packet_info2_t *const info); 00435 00436 const char * ROHC_EXPORT rohc_comp_get_state_descr(const rohc_c_state state); 00437 00438 00439 #undef ROHC_EXPORT /* do not pollute outside this header */ 00440 00441 #endif 00442
1.7.6.1