ROHC compression/decompression library
rohc_comp.h
Go to the documentation of this file.
1 /*
2  * Copyright 2010,2012,2013,2014 Didier Barvaux
3  * Copyright 2013 Friedrich
4  * Copyright 2009,2010 Thales Communications
5  * Copyright 2007,2009,2010,2012,2013,2014,2017 Viveris Technologies
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 /**
23  * @file rohc_comp.h
24  * @brief ROHC compression routines
25  * @author Didier Barvaux <didier.barvaux@toulouse.viveris.com>
26  * @author Didier Barvaux <didier@barvaux.org>
27  */
28 
29 #ifndef ROHC_COMP_H
30 #define ROHC_COMP_H
31 
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #endif
36 
37 #include <rohc/rohc.h>
38 #include <rohc/rohc_profiles.h>
39 #include <rohc/rohc_packets.h>
40 #include <rohc/rohc_traces.h>
41 #include <rohc/rohc_time.h>
42 #include <rohc/rohc_buf.h>
43 
44 #include <stdlib.h>
45 #include <stdint.h>
46 #include <stdbool.h>
47 
48 
49 /** Macro that handles DLL export declarations gracefully */
50 #ifdef DLL_EXPORT /* passed by autotools on command line */
51 # define ROHC_EXPORT __declspec(dllexport)
52 #else
53 # define ROHC_EXPORT
54 #endif
55 
56 
57 /*
58  * Declare the private ROHC compressor structure that is defined inside the
59  * library.
60  */
61 
62 struct rohc_comp;
63 
64 
65 /*
66  * Public structures and types
67  */
68 
69 
70 /**
71  * @brief The different ROHC compressor states
72  *
73  * The different ROHC operation states at compressor as defined in section
74  * 4.3.1 of RFC 3095. The CR operation state is defined in RFC 4164.
75  *
76  * If you add a new compressor state, please also add the corresponding
77  * textual description in \ref rohc_comp_get_state_descr.
78  *
79  * @ingroup rohc_comp
80  *
81  * @see rohc_comp_get_state_descr
82  */
83 typedef enum
84 {
85  /** Unknown compressor state */
87  /** The Initialization and Refresh (IR) compressor state */
89  /** The First Order (FO) compressor state */
91  /** The Second Order (SO) compressor state */
93  /** The Context Replication (CR) compressor state */
95 
97 
98 
99 /**
100  * @brief Some information about the last compressed packet
101  *
102  * The structure is used by the \ref rohc_comp_get_last_packet_info2 function
103  * to store some information about the last compressed packet.
104  *
105  * Versioning works as follow:
106  * - The \e version_major field defines the compatibility level. If the major
107  * number given by user does not match the one expected by the library,
108  * an error is returned.
109  * - The \e version_minor field defines the extension level. If the minor
110  * number given by user does not match the one expected by the library,
111  * only the fields supported in that minor version will be filled by
112  * \ref rohc_comp_get_last_packet_info2.
113  *
114  * Notes for developers:
115  * - Increase the major version if a field is removed.
116  * - Increase the major version if a field is added at the beginning or in
117  * the middle of the structure.
118  * - Increase the minor version if a field is added at the very end of the
119  * structure.
120  * - The version_major and version_minor fields must be located at the very
121  * beginning of the structure.
122  * - The structure must be packed.
123  *
124  * Supported versions:
125  * - Major 0 / Minor 0 contains: version_major, version_minor, context_id,
126  * is_context_init, context_mode, context_state, context_used, profile_id,
127  * packet_type, total_last_uncomp_size, header_last_uncomp_size,
128  * total_last_comp_size, and header_last_comp_size
129  *
130  * @ingroup rohc_comp
131  *
132  * @see rohc_comp_get_last_packet_info2
133  */
134 typedef struct
135 {
136  /** The major version of this structure */
137  unsigned short version_major;
138  /** The minor version of this structure */
139  unsigned short version_minor;
140  /** The Context ID (CID) */
141  unsigned int context_id;
142  /** Whether the context was initialized (created/re-used) by the packet */
144  /** The mode of the last context used by the compressor */
146  /** The state of the last context used by the compressor */
148  /** Whether the last context used by the compressor is still in use */
150  /** The profile ID of the last context used by the compressor */
152  /** The type of ROHC packet created for the last compressed packet */
154  /** The uncompressed size (in bytes) of the last compressed packet */
155  unsigned long total_last_uncomp_size;
156  /** The uncompressed size (in bytes) of the last compressed header */
157  unsigned long header_last_uncomp_size;
158  /** The compressed size (in bytes) of the last compressed packet */
159  unsigned long total_last_comp_size;
160  /** The compressed size (in bytes) of the last compressed header */
161  unsigned long header_last_comp_size;
162 } __attribute__((packed)) rohc_comp_last_packet_info2_t;
163 
164 
165 /**
166  * @brief Some general information about the compressor
167  *
168  * The structure is used by the \ref rohc_comp_get_general_info function
169  * to store some general information about the compressor.
170  *
171  * Versioning works as follow:
172  * - The \e version_major field defines the compatibility level. If the major
173  * number given by user does not match the one expected by the library,
174  * an error is returned.
175  * - The \e version_minor field defines the extension level. If the minor
176  * number given by user does not match the one expected by the library,
177  * only the fields supported in that minor version will be filled by
178  * \ref rohc_comp_get_general_info.
179  *
180  * Notes for developers:
181  * - Increase the major version if a field is removed.
182  * - Increase the major version if a field is added at the beginning or in
183  * the middle of the structure.
184  * - Increase the minor version if a field is added at the very end of the
185  * structure.
186  * - The version_major and version_minor fields must be located at the very
187  * beginning of the structure.
188  * - The structure must be packed.
189  *
190  * Supported versions:
191  * - major 0 and minor = 0 contains: version_major, version_minor,
192  * contexts_nr, packets_nr, uncomp_bytes_nr, and comp_bytes_nr.
193  *
194  * @ingroup rohc_comp
195  *
196  * @see rohc_comp_get_general_info
197  */
198 typedef struct
199 {
200  /** The major version of this structure */
201  unsigned short version_major;
202  /** The minor version of this structure */
203  unsigned short version_minor;
204  /** The number of contexts used by the compressor */
205  size_t contexts_nr;
206  /** The number of packets processed by the compressor */
207  unsigned long packets_nr;
208  /** The number of uncompressed bytes received by the compressor */
209  unsigned long uncomp_bytes_nr;
210  /** The number of compressed bytes produced by the compressor */
211  unsigned long comp_bytes_nr;
212 } __attribute__((packed)) rohc_comp_general_info_t;
213 
214 
215 /**
216  * @brief The different features of the ROHC compressor
217  *
218  * Features for the ROHC compressor control whether mechanisms defined as
219  * optional by RFCs are enabled or not. They can be set or unset with the
220  * function \ref rohc_comp_set_features.
221  *
222  * @ingroup rohc_comp
223  *
224  * @see rohc_comp_set_features
225  */
226 typedef enum
227 {
228  /** No feature at all */
230  /** Be compatible with 1.6.x versions */
232  /** Do not check IP checksums at compressor */
234  /** Dump content of packets in traces (beware: performance impact) */
236  /** Allow periodic refreshes based on inter-packet time */
238 
240 
241 
242 /**
243  * @brief The prototype of the RTP detection callback
244  *
245  * User-defined function that is called by the ROHC library for every UDP
246  * packet to determine whether the UDP packet transports RTP data. If the
247  * function returns true, the RTP profile is used to compress the packet.
248  * Otherwise the UDP profile is used.
249  *
250  * The user-defined function is set by calling the function
251  * \ref rohc_comp_set_rtp_detection_cb
252  *
253  * @param ip The innermost IP packet
254  * @param udp The UDP header of the packet
255  * @param payload The UDP payload of the packet
256  * @param payload_size The size of the UDP payload (in bytes)
257  * @param rtp_private A pointer to a memory area to be used by the callback
258  * function, may be NULL.
259  * @return true if the packet is an RTP packet, false otherwise
260  *
261  * @see rohc_comp_set_rtp_detection_cb
262  * @ingroup rohc_comp
263  */
264 typedef bool (*rohc_rtp_detection_callback_t)(const unsigned char *const ip,
265  const unsigned char *const udp,
266  const unsigned char *const payload,
267  const unsigned int payload_size,
268  void *const rtp_private)
269  __attribute__((warn_unused_result));
270 
271 
272 /**
273  * @brief The prototype of the callback for random numbers
274  *
275  * User-defined function that is called when the ROHC library requires a random
276  * number. Currently, the ROHC library uses it when initializing the Sequence
277  * Number (SN) of contexts using the IP-only, IP/UDP, and IP/UDP-Lite profiles.
278  *
279  * The user-defined function is set by calling the function
280  * \ref rohc_comp_new2
281  *
282  * @param comp The ROHC compressor
283  * @param user_context The context given by the user when he/she called the
284  * \ref rohc_comp_new2 function, may be NULL.
285  *
286  * @see rohc_comp_new2
287  * @ingroup rohc_comp
288  */
289 typedef int (*rohc_comp_random_cb_t) (const struct rohc_comp *const comp,
290  void *const user_context)
291  __attribute__((warn_unused_result));
292 
293 
294 /*
295  * Prototypes of main public functions related to ROHC compression
296  */
297 
298 struct rohc_comp * ROHC_EXPORT rohc_comp_new2(const rohc_cid_type_t cid_type,
299  const rohc_cid_t max_cid,
300  const rohc_comp_random_cb_t rand_cb,
301  void *const rand_priv)
302  __attribute__((warn_unused_result));
303 
304 void ROHC_EXPORT rohc_comp_free(struct rohc_comp *const comp);
305 
306 bool ROHC_EXPORT rohc_comp_set_traces_cb2(struct rohc_comp *const comp,
307  rohc_trace_callback2_t callback,
308  void *const priv_ctxt)
309  __attribute__((warn_unused_result));
310 
312  const struct rohc_buf uncomp_packet,
313  struct rohc_buf *const rohc_packet)
314  __attribute__((warn_unused_result));
315 
317  struct rohc_buf *const rohc_packet,
318  const size_t min_pkt_len)
319  __attribute__((warn_unused_result));
320 
322  struct rohc_buf *const segment)
323  __attribute__((warn_unused_result));
324 
326  __attribute__((warn_unused_result));
327 
328 
329 /*
330  * Prototypes of public functions related to user interaction
331  */
332 
333 bool ROHC_EXPORT rohc_comp_profile_enabled(const struct rohc_comp *const comp,
334  const rohc_profile_t profile)
335  __attribute__((warn_unused_result));
336 
337 bool ROHC_EXPORT rohc_comp_enable_profile(struct rohc_comp *const comp,
338  const rohc_profile_t profile)
339  __attribute__((warn_unused_result));
340 bool ROHC_EXPORT rohc_comp_disable_profile(struct rohc_comp *const comp,
341  const rohc_profile_t profile)
342  __attribute__((warn_unused_result));
343 
344 bool ROHC_EXPORT rohc_comp_enable_profiles(struct rohc_comp *const comp,
345  ...)
346  __attribute__((warn_unused_result));
347 bool ROHC_EXPORT rohc_comp_disable_profiles(struct rohc_comp *const comp,
348  ...)
349  __attribute__((warn_unused_result));
350 
351 bool ROHC_EXPORT rohc_comp_set_mrru(struct rohc_comp *const comp,
352  const size_t mrru)
353  __attribute__((warn_unused_result));
354 bool ROHC_EXPORT rohc_comp_get_mrru(const struct rohc_comp *const comp,
355  size_t *const mrru)
356  __attribute__((warn_unused_result));
357 
358 bool ROHC_EXPORT rohc_comp_get_max_cid(const struct rohc_comp *const comp,
359  size_t *const max_cid)
360  __attribute__((warn_unused_result));
361 
362 bool ROHC_EXPORT rohc_comp_get_cid_type(const struct rohc_comp *const comp,
363  rohc_cid_type_t *const cid_type)
364  __attribute__((warn_unused_result));
365 
368  void *const rtp_private)
369  __attribute__((warn_unused_result));
370 
371 bool ROHC_EXPORT rohc_comp_set_features(struct rohc_comp *const comp,
373  __attribute__((warn_unused_result));
374 
375 bool ROHC_EXPORT rohc_comp_deliver_feedback2(struct rohc_comp *const comp,
376  const struct rohc_buf feedback)
377  __attribute__((warn_unused_result));
378 
379 
380 /*
381  * Prototypes of public functions that configure robustness to packet
382  * loss/damage
383  */
384 
386  const size_t width)
387  __attribute__((warn_unused_result));
388 
389 bool ROHC_EXPORT rohc_comp_set_reorder_ratio(struct rohc_comp *const comp,
391  __attribute__((warn_unused_result));
392 
394  const size_t ir_timeout,
395  const size_t fo_timeout)
396  __attribute__((warn_unused_result));
397 
399  const uint64_t ir_timeout,
400  const uint64_t fo_timeout)
401  __attribute__((warn_unused_result));
402 
403 bool ROHC_EXPORT rohc_comp_set_list_trans_nr(struct rohc_comp *const comp,
404  const size_t list_trans_nr)
405  __attribute__((warn_unused_result));
406 
407 
408 /*
409  * Prototypes of public functions related to ROHC compression statistics
410  */
411 
412 bool ROHC_EXPORT rohc_comp_get_general_info(const struct rohc_comp *const comp,
413  rohc_comp_general_info_t *const info)
414  __attribute__((warn_unused_result));
415 
416 bool ROHC_EXPORT rohc_comp_get_last_packet_info2(const struct rohc_comp *const comp,
417  rohc_comp_last_packet_info2_t *const info)
418  __attribute__((warn_unused_result));
419 
421  __attribute__((warn_unused_result, const));
422 
423 
424 #undef ROHC_EXPORT /* do not pollute outside this header */
425 
426 #ifdef __cplusplus
427 }
428 #endif
429 
430 #endif /* ROHC_COMP_H */
431 
Definition: rohc_comp.h:231
rohc_reordering_offset_t reorder_ratio
Definition: rohc_comp_internals.h:204
bool ROHC_EXPORT rohc_comp_get_cid_type(const struct rohc_comp *const comp, rohc_cid_type_t *const cid_type)
Get the CID type that the compressor uses.
Definition: rohc_comp.c:2005
int(* rohc_comp_random_cb_t)(const struct rohc_comp *const comp, void *const user_context)
The prototype of the callback for random numbers.
Definition: rohc_comp.h:289
size_t rohc_cid_t
Definition: rohc.h:195
rohc_packet_t packet_type
Definition: rohc_comp.h:153
bool ROHC_EXPORT rohc_comp_force_contexts_reinit(struct rohc_comp *const comp)
Force the compressor to re-initialize all its contexts.
Definition: rohc_comp.c:1079
bool ROHC_EXPORT rohc_comp_set_features(struct rohc_comp *const comp, const rohc_comp_features_t features)
Enable/disable features for ROHC compressor.
Definition: rohc_comp.c:2041
rohc_comp_features_t features
Definition: rohc_comp_internals.h:135
bool context_used
Definition: rohc_comp.h:149
rohc_reordering_offset_t
The different values of reordering offset.
Definition: rohc.h:203
bool ROHC_EXPORT rohc_comp_set_periodic_refreshes_time(struct rohc_comp *const comp, const uint64_t ir_timeout, const uint64_t fo_timeout)
Set the timeouts in ms for IR and FO periodic refreshes.
Definition: rohc_comp.c:1299
rohc_mode_t
ROHC operation modes.
Definition: rohc.h:111
bool ROHC_EXPORT rohc_comp_set_mrru(struct rohc_comp *const comp, const size_t mrru)
Set the Maximum Reconstructed Reception Unit (MRRU).
Definition: rohc_comp.c:1849
bool ROHC_EXPORT rohc_comp_get_general_info(const struct rohc_comp *const comp, rohc_comp_general_info_t *const info)
Get some general information about the compressor.
Definition: rohc_comp.c:2366
unsigned short version_minor
Definition: rohc_comp.h:139
bool ROHC_EXPORT rohc_comp_set_traces_cb2(struct rohc_comp *const comp, rohc_trace_callback2_t callback, void *const priv_ctxt)
Set the callback function used to manage traces in compressor.
Definition: rohc_comp.c:451
unsigned short version_major
Definition: rohc_comp.h:201
bool ROHC_EXPORT rohc_comp_disable_profile(struct rohc_comp *const comp, const rohc_profile_t profile)
Disable a compression profile for a compressor.
Definition: rohc_comp.c:1649
bool ROHC_EXPORT rohc_comp_set_wlsb_window_width(struct rohc_comp *const comp, const size_t width)
Set the window width for the W-LSB encoding scheme.
Definition: rohc_comp.c:1129
rohc_status_t
The status code of several functions in the library API.
Definition: rohc.h:79
The ROHC compressor.
Definition: rohc_comp_internals.h:129
rohc_cid_type_t
The different types of Context IDs (CID)
Definition: rohc.h:176
Some general information about the compressor.
Definition: rohc_comp.h:198
bool ROHC_EXPORT rohc_comp_get_max_cid(const struct rohc_comp *const comp, size_t *const max_cid)
Get the maximal CID value the compressor uses.
Definition: rohc_comp.c:1976
rohc_status_t ROHC_EXPORT rohc_comp_get_segment2(struct rohc_comp *const comp, struct rohc_buf *const segment)
Get the next ROHC segment if any.
Definition: rohc_comp.c:955
rohc_comp_state_t context_state
Definition: rohc_comp.h:147
rohc_mode_t context_mode
Definition: rohc_comp.h:145
size_t contexts_nr
Definition: rohc_comp.h:205
struct rohc_comp *ROHC_EXPORT rohc_comp_new2(const rohc_cid_type_t cid_type, const rohc_cid_t max_cid, const rohc_comp_random_cb_t rand_cb, void *const rand_priv)
Create a new ROHC compressor.
Definition: rohc_comp.c:248
unsigned long packets_nr
Definition: rohc_comp.h:207
bool is_context_init
Definition: rohc_comp.h:143
void(* rohc_trace_callback2_t)(void *const priv_ctxt, const rohc_trace_level_t level, const rohc_trace_entity_t entity, const int profile, const char *const format,...)
The function prototype for the trace callback.
Definition: rohc_traces.h:118
unsigned long total_last_comp_size
Definition: rohc_comp.h:159
unsigned long header_last_comp_size
Definition: rohc_comp.h:161
bool ROHC_EXPORT rohc_comp_set_reorder_ratio(struct rohc_comp *const comp, const rohc_reordering_offset_t reorder_ratio)
Set the reordering ratio for the W-LSB encoding scheme.
Definition: rohc_comp.c:1179
bool ROHC_EXPORT rohc_comp_set_periodic_refreshes(struct rohc_comp *const comp, const size_t ir_timeout, const size_t fo_timeout)
Set the timeouts in packets for IR and FO periodic refreshes.
Definition: rohc_comp.c:1239
bool ROHC_EXPORT rohc_comp_get_last_packet_info2(const struct rohc_comp *const comp, rohc_comp_last_packet_info2_t *const info)
Get some information about the last compressed packet.
Definition: rohc_comp.c:2283
void ROHC_EXPORT rohc_comp_free(struct rohc_comp *const comp)
Destroy the given ROHC compressor.
Definition: rohc_comp.c:392
Definition: rohc_comp.h:86
Definition: rohc_comp.h:92
Definition: rohc_comp.h:235
bool(* rohc_rtp_detection_callback_t)(const unsigned char *const ip, const unsigned char *const udp, const unsigned char *const payload, const unsigned int payload_size, void *const rtp_private)
The prototype of the RTP detection callback.
Definition: rohc_comp.h:264
bool ROHC_EXPORT rohc_comp_deliver_feedback2(struct rohc_comp *const comp, const struct rohc_buf feedback)
Deliver a feedback packet to the compressor.
Definition: rohc_comp.c:2176
Definition: rohc_comp.h:237
unsigned long total_last_uncomp_size
Definition: rohc_comp.h:155
unsigned long uncomp_bytes_nr
Definition: rohc_comp.h:209
const char *ROHC_EXPORT rohc_comp_get_state_descr(const rohc_comp_state_t state)
Give a description for the given ROHC compression context state.
Definition: rohc_comp.c:2429
rohc_status_t ROHC_EXPORT rohc_comp_pad(struct rohc_comp *const comp, struct rohc_buf *const rohc_packet, const size_t min_pkt_len)
Pad the given ROHC compressed packet.
Definition: rohc_comp.c:832
A network buffer for the ROHC library.
Definition: rohc_buf.h:102
bool ROHC_EXPORT rohc_comp_profile_enabled(const struct rohc_comp *const comp, const rohc_profile_t profile)
Is the given compression profile enabled for a compressor?
Definition: rohc_comp.c:1511
bool ROHC_EXPORT rohc_comp_disable_profiles(struct rohc_comp *const comp,...)
Disable several compression profiles for a compressor.
Definition: rohc_comp.c:1773
Definition: rohc_comp.h:229
rohc_comp_features_t
The different features of the ROHC compressor.
Definition: rohc_comp.h:226
rohc_comp_state_t
The different ROHC compressor states.
Definition: rohc_comp.h:83
unsigned short version_minor
Definition: rohc_comp.h:203
Definition: rohc_comp.h:90
bool ROHC_EXPORT rohc_comp_enable_profile(struct rohc_comp *const comp, const rohc_profile_t profile)
Enable a compression profile for a compressor.
Definition: rohc_comp.c:1574
bool ROHC_EXPORT rohc_comp_enable_profiles(struct rohc_comp *const comp,...)
Enable several compression profiles for a compressor.
Definition: rohc_comp.c:1715
size_t list_trans_nr
Definition: rohc_comp_internals.h:222
void * rtp_private
Definition: rohc_comp_internals.h:174
#define ROHC_EXPORT
Definition: rohc_comp.h:53
Definition: rohc_comp.h:94
unsigned long header_last_uncomp_size
Definition: rohc_comp.h:157
Definition: rohc_comp.h:233
Definition: rohc_comp.h:88
Some information about the last compressed packet.
Definition: rohc_comp.h:134
bool ROHC_EXPORT rohc_comp_set_rtp_detection_cb(struct rohc_comp *const comp, rohc_rtp_detection_callback_t callback, void *const rtp_private)
Set the RTP detection callback function.
Definition: rohc_comp.c:1441
rohc_status_t ROHC_EXPORT rohc_compress4(struct rohc_comp *const comp, const struct rohc_buf uncomp_packet, struct rohc_buf *const rohc_packet)
Compress the given uncompressed packet into a ROHC packet.
Definition: rohc_comp.c:547
rohc_profile_t
The different ROHC compression/decompression profiles.
Definition: rohc_profiles.h:70
rohc_packet_t
The different types of ROHC packets.
Definition: rohc_packets.h:55
bool ROHC_EXPORT rohc_comp_set_list_trans_nr(struct rohc_comp *const comp, const size_t list_trans_nr)
Set the number of uncompressed transmissions for list compression.
Definition: rohc_comp.c:1359
size_t mrru
Definition: rohc_comp_internals.h:218
unsigned int context_id
Definition: rohc_comp.h:141
unsigned short version_major
Definition: rohc_comp.h:137
bool ROHC_EXPORT rohc_comp_get_mrru(const struct rohc_comp *const comp, size_t *const mrru)
Get the Maximum Reconstructed Reception Unit (MRRU).
Definition: rohc_comp.c:1947
int profile_id
Definition: rohc_comp.h:151
unsigned long comp_bytes_nr
Definition: rohc_comp.h:211