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 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_packets.h>
39 #include <rohc/rohc_traces.h>
40 #include <rohc/rohc_time.h>
41 #include <rohc/rohc_buf.h>
42 
43 #include <stdlib.h>
44 #include <stdint.h>
45 #ifdef __KERNEL__
46 # include <linux/types.h>
47 #else
48 # include <stdbool.h>
49 #endif
50 
51 
52 /** Macro that handles DLL export declarations gracefully */
53 #ifdef DLL_EXPORT /* passed by autotools on command line */
54 # define ROHC_EXPORT __declspec(dllexport)
55 #else
56 # define ROHC_EXPORT
57 #endif
58 
59 
60 /*
61  * Declare the private ROHC compressor structure that is defined inside the
62  * library.
63  */
64 
65 struct rohc_comp;
66 
67 
68 /*
69  * Public structures and types
70  */
71 
72 
73 /**
74  * @brief The different ROHC compressor states
75  *
76  * The different ROHC operation states at compressor as defined in section
77  * 4.3.1 of RFC 3095.
78  *
79  * If you add a new compressor state, please also add the corresponding
80  * textual description in \ref rohc_comp_get_state_descr.
81  *
82  * @ingroup rohc_comp
83  *
84  * @see rohc_comp_get_state_descr
85  */
86 typedef enum
87 {
88  /** Unknown compressor state */
90  /** The Initialization and Refresh (IR) compressor state */
92  /** The First Order (FO) compressor state */
94  /** The Second Order (SO) compressor state */
96 
98 
99 
100 /**
101  * @brief Some information about the last compressed packet
102  *
103  * The structure is used by the \ref rohc_comp_get_last_packet_info2 function
104  * to store some information about the last compressed packet.
105  *
106  * Versioning works as follow:
107  * - The \e version_major field defines the compatibility level. If the major
108  * number given by user does not match the one expected by the library,
109  * an error is returned.
110  * - The \e version_minor field defines the extension level. If the minor
111  * number given by user does not match the one expected by the library,
112  * only the fields supported in that minor version will be filled by
113  * \ref rohc_comp_get_last_packet_info2.
114  *
115  * Notes for developers:
116  * - Increase the major version if a field is removed.
117  * - Increase the major version if a field is added at the beginning or in
118  * the middle of the structure.
119  * - Increase the minor version if a field is added at the very end of the
120  * structure.
121  * - The version_major and version_minor fields must be located at the very
122  * beginning of the structure.
123  * - The structure must be packed.
124  *
125  * Supported versions:
126  * - Major 0 / Minor 0 contains: version_major, version_minor, context_id,
127  * is_context_init, context_mode, context_state, context_used, profile_id,
128  * packet_type, total_last_uncomp_size, header_last_uncomp_size,
129  * total_last_comp_size, and header_last_comp_size
130  *
131  * @ingroup rohc_comp
132  *
133  * @see rohc_comp_get_last_packet_info2
134  */
135 typedef struct
136 {
137  /** The major version of this structure */
138  unsigned short version_major;
139  /** The minor version of this structure */
140  unsigned short version_minor;
141  /** The Context ID (CID) */
142  unsigned int context_id;
143  /** Whether the context was initialized (created/re-used) by the packet */
145  /** The mode of the last context used by the compressor */
147  /** The state of the last context used by the compressor */
149  /** Whether the last context used by the compressor is still in use */
151  /** The profile ID of the last context used by the compressor */
153  /** The type of ROHC packet created for the last compressed packet */
155  /** The uncompressed size (in bytes) of the last compressed packet */
156  unsigned long total_last_uncomp_size;
157  /** The uncompressed size (in bytes) of the last compressed header */
158  unsigned long header_last_uncomp_size;
159  /** The compressed size (in bytes) of the last compressed packet */
160  unsigned long total_last_comp_size;
161  /** The compressed size (in bytes) of the last compressed header */
162  unsigned long header_last_comp_size;
163 } __attribute__((packed)) rohc_comp_last_packet_info2_t;
164 
165 
166 /**
167  * @brief Some general information about the compressor
168  *
169  * The structure is used by the \ref rohc_comp_get_general_info function
170  * to store some general information about the compressor.
171  *
172  * Versioning works as follow:
173  * - The \e version_major field defines the compatibility level. If the major
174  * number given by user does not match the one expected by the library,
175  * an error is returned.
176  * - The \e version_minor field defines the extension level. If the minor
177  * number given by user does not match the one expected by the library,
178  * only the fields supported in that minor version will be filled by
179  * \ref rohc_comp_get_general_info.
180  *
181  * Notes for developers:
182  * - Increase the major version if a field is removed.
183  * - Increase the major version if a field is added at the beginning or in
184  * the middle of the structure.
185  * - Increase the minor version if a field is added at the very end of the
186  * structure.
187  * - The version_major and version_minor fields must be located at the very
188  * beginning of the structure.
189  * - The structure must be packed.
190  *
191  * Supported versions:
192  * - major 0 and minor = 0 contains: version_major, version_minor,
193  * contexts_nr, packets_nr, uncomp_bytes_nr, and comp_bytes_nr.
194  *
195  * @ingroup rohc_comp
196  *
197  * @see rohc_comp_get_general_info
198  */
199 typedef struct
200 {
201  /** The major version of this structure */
202  unsigned short version_major;
203  /** The minor version of this structure */
204  unsigned short version_minor;
205  /** The number of contexts used by the compressor */
206  size_t contexts_nr;
207  /** The number of packets processed by the compressor */
208  unsigned long packets_nr;
209  /** The number of uncompressed bytes received by the compressor */
210  unsigned long uncomp_bytes_nr;
211  /** The number of compressed bytes produced by the compressor */
212  unsigned long comp_bytes_nr;
213 } __attribute__((packed)) rohc_comp_general_info_t;
214 
215 
216 /**
217  * @brief The different features of the ROHC compressor
218  *
219  * Features for the ROHC compressor control whether mechanisms defined as
220  * optional by RFCs are enabled or not. They can be set or unset with the
221  * function \ref rohc_comp_set_features.
222  *
223  * @ingroup rohc_comp
224  *
225  * @see rohc_comp_set_features
226  */
227 typedef enum
228 {
229  /** No feature at all */
231  /** Be compatible with 1.6.x versions */
233  /** Do not check IP checksums at compressor */
235  /** Dump content of packets in traces (beware: performance impact) */
237 
239 
240 
241 /**
242  * @brief The prototype of the RTP detection callback
243  *
244  * User-defined function that is called by the ROHC library for every UDP
245  * packet to determine whether the UDP packet transports RTP data. If the
246  * function returns true, the RTP profile is used to compress the packet.
247  * Otherwise the UDP profile is used.
248  *
249  * The user-defined function is set by calling the function
250  * \ref rohc_comp_set_rtp_detection_cb
251  *
252  * @param ip The innermost IP packet
253  * @param udp The UDP header of the packet
254  * @param payload The UDP payload of the packet
255  * @param payload_size The size of the UDP payload (in bytes)
256  * @param rtp_private A pointer to a memory area to be used by the callback
257  * function, may be NULL.
258  * @return true if the packet is an RTP packet, false otherwise
259  *
260  * @see rohc_comp_set_rtp_detection_cb
261  * @ingroup rohc_comp
262  */
263 typedef bool (*rohc_rtp_detection_callback_t)(const unsigned char *const ip,
264  const unsigned char *const udp,
265  const unsigned char *const payload,
266  const unsigned int payload_size,
267  void *const rtp_private)
268  __attribute__((warn_unused_result));
269 
270 
271 /**
272  * @brief The prototype of the callback for random numbers
273  *
274  * User-defined function that is called when the ROHC library requires a random
275  * number. Currently, the ROHC library uses it when initializing the Sequence
276  * Number (SN) of contexts using the IP-only, IP/UDP, and IP/UDP-Lite profiles.
277  *
278  * The user-defined function is set by calling the function
279  * \ref rohc_comp_new2
280  *
281  * @param comp The ROHC compressor
282  * @param user_context The context given by the user when he/she called the
283  * \ref rohc_comp_new2 function, may be NULL.
284  *
285  * @see rohc_comp_new2
286  * @ingroup rohc_comp
287  */
288 typedef int (*rohc_comp_random_cb_t) (const struct rohc_comp *const comp,
289  void *const user_context)
290  __attribute__((warn_unused_result));
291 
292 
293 /*
294  * Prototypes of main public functions related to ROHC compression
295  */
296 
297 struct rohc_comp * ROHC_EXPORT rohc_comp_new2(const rohc_cid_type_t cid_type,
298  const rohc_cid_t max_cid,
299  const rohc_comp_random_cb_t rand_cb,
300  void *const rand_priv)
301  __attribute__((warn_unused_result));
302 
303 void ROHC_EXPORT rohc_comp_free(struct rohc_comp *const comp);
304 
305 bool ROHC_EXPORT rohc_comp_set_traces_cb2(struct rohc_comp *const comp,
306  rohc_trace_callback2_t callback,
307  void *const priv_ctxt)
308  __attribute__((warn_unused_result));
309 
311  const struct rohc_buf uncomp_packet,
312  struct rohc_buf *const rohc_packet)
313  __attribute__((warn_unused_result));
314 
316  struct rohc_buf *const segment)
317  __attribute__((warn_unused_result));
318 
320  __attribute__((warn_unused_result));
321 
322 
323 /*
324  * Prototypes of public functions related to user interaction
325  */
326 
327 bool ROHC_EXPORT rohc_comp_profile_enabled(const struct rohc_comp *const comp,
328  const rohc_profile_t profile)
329  __attribute__((warn_unused_result));
330 
331 bool ROHC_EXPORT rohc_comp_enable_profile(struct rohc_comp *const comp,
332  const rohc_profile_t profile)
333  __attribute__((warn_unused_result));
334 bool ROHC_EXPORT rohc_comp_disable_profile(struct rohc_comp *const comp,
335  const rohc_profile_t profile)
336  __attribute__((warn_unused_result));
337 
338 bool ROHC_EXPORT rohc_comp_enable_profiles(struct rohc_comp *const comp,
339  ...)
340  __attribute__((warn_unused_result));
341 bool ROHC_EXPORT rohc_comp_disable_profiles(struct rohc_comp *const comp,
342  ...)
343  __attribute__((warn_unused_result));
344 
345 bool ROHC_EXPORT rohc_comp_set_mrru(struct rohc_comp *const comp,
346  const size_t mrru)
347  __attribute__((warn_unused_result));
348 bool ROHC_EXPORT rohc_comp_get_mrru(const struct rohc_comp *const comp,
349  size_t *const mrru)
350  __attribute__((warn_unused_result));
351 
352 bool ROHC_EXPORT rohc_comp_get_max_cid(const struct rohc_comp *const comp,
353  size_t *const max_cid)
354  __attribute__((warn_unused_result));
355 
356 bool ROHC_EXPORT rohc_comp_get_cid_type(const struct rohc_comp *const comp,
357  rohc_cid_type_t *const cid_type)
358  __attribute__((warn_unused_result));
359 
362  void *const rtp_private)
363  __attribute__((warn_unused_result));
364 
365 bool ROHC_EXPORT rohc_comp_set_features(struct rohc_comp *const comp,
367  __attribute__((warn_unused_result));
368 
369 bool ROHC_EXPORT rohc_comp_deliver_feedback2(struct rohc_comp *const comp,
370  const struct rohc_buf feedback)
371  __attribute__((warn_unused_result));
372 
373 
374 /*
375  * Prototypes of public functions that configure robustness to packet
376  * loss/damage
377  */
378 
380  const size_t width)
381  __attribute__((warn_unused_result));
382 
384  const size_t ir_timeout,
385  const size_t fo_timeout)
386  __attribute__((warn_unused_result));
387 
388 bool ROHC_EXPORT rohc_comp_set_list_trans_nr(struct rohc_comp *const comp,
389  const size_t list_trans_nr)
390  __attribute__((warn_unused_result));
391 
392 
393 /*
394  * Prototypes of public functions related to ROHC compression statistics
395  */
396 
397 bool ROHC_EXPORT rohc_comp_get_general_info(const struct rohc_comp *const comp,
398  rohc_comp_general_info_t *const info)
399  __attribute__((warn_unused_result));
400 
401 bool ROHC_EXPORT rohc_comp_get_last_packet_info2(const struct rohc_comp *const comp,
402  rohc_comp_last_packet_info2_t *const info)
403  __attribute__((warn_unused_result));
404 
406  __attribute__((warn_unused_result, const));
407 
408 
409 #undef ROHC_EXPORT /* do not pollute outside this header */
410 
411 #ifdef __cplusplus
412 }
413 #endif
414 
415 #endif /* ROHC_COMP_H */
416 
Definition: rohc_comp.h:232
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:1722
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:288
size_t rohc_cid_t
Definition: rohc.h:195
rohc_packet_t packet_type
Definition: rohc_comp.h:154
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:964
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:1758
rohc_comp_features_t features
Definition: rohc_comp_internals.h:127
bool context_used
Definition: rohc_comp.h:150
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:1592
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:2082
unsigned short version_minor
Definition: rohc_comp.h:140
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:432
unsigned short version_major
Definition: rohc_comp.h:202
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:1387
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:1016
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:121
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:199
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:1693
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:840
rohc_comp_state_t context_state
Definition: rohc_comp.h:148
rohc_mode_t context_mode
Definition: rohc_comp.h:146
size_t contexts_nr
Definition: rohc_comp.h:206
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:231
unsigned long packets_nr
Definition: rohc_comp.h:208
bool is_context_init
Definition: rohc_comp.h:144
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:160
unsigned long header_last_comp_size
Definition: rohc_comp.h:162
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 timeout values for IR and FO periodic refreshes.
Definition: rohc_comp.c:1079
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:1999
void ROHC_EXPORT rohc_comp_free(struct rohc_comp *const comp)
Destroy the given ROHC compressor.
Definition: rohc_comp.c:373
Definition: rohc_comp.h:89
Definition: rohc_comp.h:95
Definition: rohc_comp.h:236
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:263
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:1892
unsigned long total_last_uncomp_size
Definition: rohc_comp.h:156
unsigned long uncomp_bytes_nr
Definition: rohc_comp.h:210
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:2145
A network buffer for the ROHC library.
Definition: rohc_buf.h:104
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:1257
bool ROHC_EXPORT rohc_comp_disable_profiles(struct rohc_comp *const comp,...)
Disable several compression profiles for a compressor.
Definition: rohc_comp.c:1519
Definition: rohc_comp.h:230
rohc_comp_features_t
The different features of the ROHC compressor.
Definition: rohc_comp.h:227
rohc_comp_state_t
The different ROHC compressor states.
Definition: rohc_comp.h:86
unsigned short version_minor
Definition: rohc_comp.h:204
Definition: rohc_comp.h:93
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:1325
bool ROHC_EXPORT rohc_comp_enable_profiles(struct rohc_comp *const comp,...)
Enable several compression profiles for a compressor.
Definition: rohc_comp.c:1461
size_t list_trans_nr
Definition: rohc_comp_internals.h:205
void * rtp_private
Definition: rohc_comp_internals.h:166
#define ROHC_EXPORT
Definition: rohc_comp.h:56
unsigned long header_last_uncomp_size
Definition: rohc_comp.h:158
Definition: rohc_comp.h:234
Definition: rohc_comp.h:91
Some information about the last compressed packet.
Definition: rohc_comp.h:135
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:1220
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:528
rohc_profile_t
The different ROHC compression/decompression profiles.
Definition: rohc.h:212
rohc_packet_t
The different types of ROHC packets.
Definition: rohc_packets.h:49
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:1138
size_t mrru
Definition: rohc_comp_internals.h:201
unsigned int context_id
Definition: rohc_comp.h:142
unsigned short version_major
Definition: rohc_comp.h:138
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:1664
int profile_id
Definition: rohc_comp.h:152
unsigned long comp_bytes_nr
Definition: rohc_comp.h:212