ROHC compression/decompression library
Data Structures | Macros | Typedefs | Enumerations | Functions
The ROHC compressor/decompressor common API

Data Structures

struct  rohc_buf
 A network buffer for the ROHC library. More...
 
struct  rohc_ts
 A timestamp for the ROHC library. More...
 

Macros

#define ROHC_ETHERTYPE   0x22f1
 The Ethertype assigned to the ROHC protocol by the IEEE. More...
 
#define ROHC_LARGE_CID_MAX   ((1U << 14) - 1) /* 2^14 - 1 = 16383 */
 The maximum value for large CIDs. More...
 
#define ROHC_SMALL_CID_MAX   15U
 The maximum value for small CIDs. More...
 
#define rohc_buf_init_empty(__data, __max_len)
 Initialize the given network buffer with no data. More...
 
#define rohc_buf_init_full(__data, __len, __time)
 Initialize the given network buffer with all its data. More...
 
#define rohc_buf_byte_at(__buf, __offset)   ((__buf).data)[(__buf).offset + (__offset)]
 Get the byte at the given offset in the given network buffer. More...
 
#define rohc_buf_byte(__buf)   rohc_buf_byte_at((__buf), 0)
 Get the next byte in the given network buffer. More...
 
#define ROHC_PROFILE_GENERAL   0xffff
 A general profile number used for traces not related to a specific profile. More...
 

Typedefs

typedef 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. More...
 

Enumerations

enum  rohc_status_t {
  ROHC_STATUS_OK = 0, ROHC_STATUS_SEGMENT = 1, ROHC_STATUS_MALFORMED = 2, ROHC_STATUS_NO_CONTEXT = 3,
  ROHC_STATUS_BAD_CRC = 4, ROHC_STATUS_OUTPUT_TOO_SMALL = 5, ROHC_STATUS_ERROR = 6
}
 The status code of several functions in the library API. More...
 
enum  rohc_mode_t { ROHC_UNKNOWN_MODE = 0, ROHC_U_MODE = 1, ROHC_O_MODE = 2, ROHC_R_MODE = 3 }
 ROHC operation modes. More...
 
enum  rohc_cid_type_t { ROHC_LARGE_CID, ROHC_SMALL_CID }
 The different types of Context IDs (CID) More...
 
enum  rohc_profile_t {
  ROHC_PROFILE_UNCOMPRESSED = 0x0000, ROHC_PROFILE_RTP = 0x0001, ROHC_PROFILE_UDP = 0x0002, ROHC_PROFILE_ESP = 0x0003,
  ROHC_PROFILE_IP = 0x0004, ROHC_PROFILE_RTP_LLA = 0x0005, ROHC_PROFILE_TCP = 0x0006, ROHC_PROFILE_UDPLITE_RTP = 0x0007,
  ROHC_PROFILE_UDPLITE = 0x0008, ROHC_PROFILE_MAX = 0x0009
}
 The different ROHC compression/decompression profiles. More...
 
enum  rohc_trace_level_t {
  ROHC_TRACE_DEBUG = 0, ROHC_TRACE_INFO = 1, ROHC_TRACE_WARNING = 2, ROHC_TRACE_ERROR = 3,
  ROHC_TRACE_LEVEL_MAX
}
 The different levels of the traces. More...
 
enum  rohc_trace_entity_t { ROHC_TRACE_COMP = 0, ROHC_TRACE_DECOMP = 1, ROHC_TRACE_ENTITY_MAX }
 The different entities concerned by the traces. More...
 

Functions

static bool rohc_buf_is_malformed (const struct rohc_buf buf)
 Is the given network buffer malformed? More...
 
static bool rohc_buf_is_empty (const struct rohc_buf buf)
 Is the given network buffer empty? More...
 
static void rohc_buf_pull (struct rohc_buf *const buf, const size_t offset)
 Pull the beginning of the given network buffer. More...
 
static void rohc_buf_push (struct rohc_buf *const buf, const size_t offset)
 Push the beginning of the given network buffer. More...
 
static size_t rohc_buf_avail_len (const struct rohc_buf buf)
 How many bytes the given network buffer may contain? More...
 
static uint8_t * rohc_buf_data (const struct rohc_buf buf)
 Get the bytes in the given network buffer. More...
 
static uint8_t * rohc_buf_data_at (const struct rohc_buf buf, const size_t offset)
 Get the bytes at the given offset in the given network buffer. More...
 
static void rohc_buf_prepend (struct rohc_buf *const buf, const uint8_t *const data, const size_t len)
 Add data at the beginning of the given network buffer. More...
 
static void rohc_buf_append (struct rohc_buf *const buf, const uint8_t *const data, const size_t len)
 Add data at the end of the given network buffer. More...
 
static void rohc_buf_append_buf (struct rohc_buf *const dst, const struct rohc_buf src)
 Add a network buffer at the end of the given network buffer. More...
 
static void rohc_buf_reset (struct rohc_buf *const buf)
 Reset the given network buffer. More...
 
char * rohc_version (void)
 Get the version of the ROHC library. More...
 
const char * rohc_strerror (const rohc_status_t status)
 Give a description for the given ROHC status code. More...
 
const char * rohc_get_mode_descr (const rohc_mode_t mode)
 Give a description for the given ROHC mode. More...
 
const char * rohc_get_profile_descr (const rohc_profile_t profile)
 Give a description for the given ROHC profile. More...
 
const char * rohc_get_packet_descr (const rohc_packet_t packet_type)
 Give a description for the given type of ROHC packet. More...
 
const char * rohc_get_ext_descr (const rohc_ext_t ext_type)
 Give a description for the given type of ROHC extension. More...
 
rohc_packet_t rohc_get_packet_type (const char *const packet_id)
 Get the packet type from a packet identifier. More...
 

Detailed Description

The common API of the ROHC library allows a program to print the version of the ROHC library, or retrieve the description of ROHC modes and packets. No initialization is required.

Macro Definition Documentation

#define rohc_buf_byte (   __buf)    rohc_buf_byte_at((__buf), 0)

Get the next byte in the given network buffer.

Parameters
__bufThe network buffer to get the next byte from
Returns
The next byte stored in the network buffer
#define rohc_buf_byte_at (   __buf,
  __offset 
)    ((__buf).data)[(__buf).offset + (__offset)]

Get the byte at the given offset in the given network buffer.

Parameters
__bufThe network buffer to get a byte from
__offsetThe offset to get bytes at
Returns
The byte stored in the network buffer at the offset
#define rohc_buf_init_empty (   __data,
  __max_len 
)
Value:
{ \
.time = { .sec = 0, .nsec = 0, }, \
.data = (__data), \
.max_len = (__max_len), \
.offset = 0, \
.len = 0, \
}

Initialize the given network buffer with no data.

This method is used to initialize an empty network buffer that will be used to create a packet. For example, the ROHC packet for a compression operation, or the uncompressed packet for a decompression operation.

Parameters
__dataThe packet data to point to
__max_lenThe maxmimum length (in bytes) of the packet data
Example:
1 #define PKT_DATA_LEN 145U
2 uint8_t pkt_data[PKT_DATA_LEN];
3 struct rohc_buf packet = rohc_buf_init_empty(pkt_data, PKT_DATA_LEN);
#define rohc_buf_init_full (   __data,
  __len,
  __time 
)
Value:
{ \
.time = (__time), \
.data = (__data), \
.max_len = (__len), \
.offset = 0, \
.len = (__len), \
}

Initialize the given network buffer with all its data.

This method is used to initialize a network buffer that will be used for parsing only. For example, the uncompressed packet for a compression operation, or the ROHC packet for a decompression operation.

Parameters
__dataThe packet data to point to
__lenThe maxmimum length (in bytes) of the packet data
__timeThe timestamp at which the packet was received/handled
Example:
1 #define PKT_DATA_LEN 145U
2 const uint8_t pkt_data[PKT_DATA_LEN];
3 const struct rohc_ts arrival_time = { .sec = 1399745625, .nsec = 42 };
4 const struct rohc_buf packet =
5  rohc_buf_init_full(pkt_data, PKT_DATA_LEN, arrival_time);
#define ROHC_ETHERTYPE   0x22f1

The Ethertype assigned to the ROHC protocol by the IEEE.

See also
http://standards.ieee.org/regauth/ethertype/eth.txt
#define ROHC_LARGE_CID_MAX   ((1U << 14) - 1) /* 2^14 - 1 = 16383 */

The maximum value for large CIDs.

See also
rohc_comp_new
rohc_c_set_max_cid
rohc_decomp_set_max_cid
#define ROHC_PROFILE_GENERAL   0xffff

A general profile number used for traces not related to a specific profile.

#define ROHC_SMALL_CID_MAX   15U

The maximum value for small CIDs.

See also
rohc_comp_new
rohc_c_set_max_cid
rohc_decomp_set_max_cid
Example:
struct rohc_comp *compressor; /* the ROHC compressor */
gen_random_num, NULL);
if(compressor == NULL)
{
fprintf(stderr, "failed create the ROHC compressor\n");
goto error;
}

Typedef Documentation

typedef 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.

User-defined function that is called by the ROHC library every time it wants to print something, from errors to debug. User may thus decide what traces are interesting (filter on level, source entity, or profile) and what to do with them (print on console, storage in file, syslog...).

The user-defined function is set by calling:

Both functions accept the NULL value to fully disable tracing.

Parameters
priv_ctxtAn optional private context, may be NULL
levelThe level of the message,
See also
rohc_trace_level_t
Parameters
entityThe entity concerned by the traces
See also
rohc_trace_entity_t
Parameters
profileThe number of the profile concerned by the message
formatThe format string for the trace message
See also
rohc_trace_level_t
rohc_trace_entity_t
rohc_comp_set_traces2_cb
rohc_decomp_set_traces2_cb

Enumeration Type Documentation

The different types of Context IDs (CID)

The different types of Context IDs (CID) a ROHC compressor or a ROHC decompressor may use.

Possible values are:

  • ROHC_LARGE_CID : large CID means that a ROHC compressor or a ROHC decompressor may identify contexts with IDs in the range [0, ROHC_LARGE_CID_MAX ], ie. it may uniquely identify at most ROHC_LARGE_CID_MAX + 1 streams.
  • ROHC_SMALL_CID : small CID means that a ROHC compressor or a ROHC decompressor may identify contexts with IDs in the range [0, ROHC_SMALL_CID_MAX ], ie. it may uniquely identify at most ROHC_SMALL_CID_MAX + 1 streams.

In short, you choose the CID type in function of the number of simultaneous streams you have to compress efficiently.

See also
ROHC_SMALL_CID_MAX ROHC_LARGE_CID_MAX
Enumerator
ROHC_LARGE_CID 

The context uses large CID.

CID values shall be in the range [0, ROHC_LARGE_CID_MAX].

ROHC_SMALL_CID 

The context uses small CID.

CID value shall be in the range [0, ROHC_SMALL_CID_MAX].

ROHC operation modes.

The different ROHC operation modes as defined in section 4.4 of RFC 3095.

If you add a new operation mode, please also add the corresponding textual description in rohc_get_mode_descr.

See also
rohc_get_mode_descr
Enumerator
ROHC_UNKNOWN_MODE 

Unknown operational mode

ROHC_U_MODE 

The Unidirectional mode (U-mode)

ROHC_O_MODE 

The Bidirectional Optimistic mode (O-mode)

ROHC_R_MODE 

The Bidirectional Reliable mode (R-mode)

The different ROHC compression/decompression profiles.

If you add a new compression/decompression profile, please also add the corresponding textual description in rohc_get_profile_descr.

See also
rohc_get_profile_descr
Enumerator
ROHC_PROFILE_UNCOMPRESSED 

The ROHC Uncompressed profile (RFC 3095, section 5.10)

ROHC_PROFILE_RTP 

The ROHC RTP profile (RFC 3095, section 8)

ROHC_PROFILE_UDP 

The ROHC UDP profile (RFC 3095, section 5.11)

ROHC_PROFILE_ESP 

The ROHC ESP profile (RFC 3095, section 5.12)

ROHC_PROFILE_IP 

The ROHC IP-only profile (RFC 3843, section 5)

ROHC_PROFILE_RTP_LLA 

The ROHC IP/UDP/RTP Link-Layer Assisted Profile (LLA) profile (RFC 4362, section 6)

ROHC_PROFILE_TCP 

The ROHC TCP profile (RFC 4996)

ROHC_PROFILE_UDPLITE_RTP 

The ROHC UDP-Lite/RTP profile (RFC 4019, section 7)

ROHC_PROFILE_UDPLITE 

The ROHC UDP-Lite profile (RFC 4019, section 7)

ROHC_PROFILE_MAX 

The status code of several functions in the library API.

Enumerator
ROHC_STATUS_OK 

The action was successful

ROHC_STATUS_SEGMENT 

The action was successful but packet needs to be segmented

ROHC_STATUS_MALFORMED 

The action failed due to a malformed packet

ROHC_STATUS_NO_CONTEXT 

The action failed because no matching context exists

ROHC_STATUS_BAD_CRC 

The action failed due to a CRC failure

ROHC_STATUS_OUTPUT_TOO_SMALL 

The action failed because output buffer is too small

ROHC_STATUS_ERROR 

The action encountered an undefined problem

The different entities concerned by the traces.

Used for the source entity parameter of the rohc_trace_callback2_t user-defined callback.

See also
rohc_trace_callback2_t
rohc_comp_set_traces_cb2
rohc_decomp_set_traces_cb2
Enumerator
ROHC_TRACE_COMP 

Compressor traces

ROHC_TRACE_DECOMP 

Decompressor traces

ROHC_TRACE_ENTITY_MAX 

The maximum number of trace entities

The different levels of the traces.

Used for the level parameter of the rohc_trace_callback2_t user-defined callback.

See also
rohc_trace_callback2_t
rohc_comp_set_traces_cb2
rohc_decomp_set_traces_cb2
Enumerator
ROHC_TRACE_DEBUG 

Print debug traces

ROHC_TRACE_INFO 

Print info (or lower) traces

ROHC_TRACE_WARNING 

Print warning (or lower) traces

ROHC_TRACE_ERROR 

Print error (or lower) traces

ROHC_TRACE_LEVEL_MAX 

The maximum number of trace levels

Function Documentation

static void rohc_buf_append ( struct rohc_buf *const  buf,
const uint8_t *const  data,
const size_t  len 
)
inlinestatic

Add data at the end of the given network buffer.

Parameters
bufThe network buffer to append data to
dataThe data to append
lenThe length (in bytes) of the data to append
static void rohc_buf_append_buf ( struct rohc_buf *const  dst,
const struct rohc_buf  src 
)
inlinestatic

Add a network buffer at the end of the given network buffer.

Parameters
dstThe network buffer to append data to
srcThe network buffer to append data from
static size_t rohc_buf_avail_len ( const struct rohc_buf  buf)
inlinestatic

How many bytes the given network buffer may contain?

Parameters
bufThe network buffer to check
Returns
The number of bytes one may write to the given network buffer
static uint8_t * rohc_buf_data ( const struct rohc_buf  buf)
inlinestatic

Get the bytes in the given network buffer.

This function is a shortcut for:

1 rohc_buf_data_at(buf, 0);
Parameters
bufThe network buffer to get bytes from
Returns
The bytes stored in the network buffer
static uint8_t * rohc_buf_data_at ( const struct rohc_buf  buf,
const size_t  offset 
)
inlinestatic

Get the bytes at the given offset in the given network buffer.

Parameters
bufThe network buffer to get bytes from
offsetThe offset to get bytes at
Returns
The bytes stored in the network buffer at the offset
static bool rohc_buf_is_empty ( const struct rohc_buf  buf)
inlinestatic

Is the given network buffer empty?

Empty means no data at all.

Parameters
bufThe network buffer to check for
Returns
true if the given network is empty, false if not
static bool rohc_buf_is_malformed ( const struct rohc_buf  buf)
inlinestatic

Is the given network buffer malformed?

Parameters
bufThe network buffer to check for
Returns
true if the given network is malformed, false if not
static void rohc_buf_prepend ( struct rohc_buf *const  buf,
const uint8_t *const  data,
const size_t  len 
)
inlinestatic

Add data at the beginning of the given network buffer.

Parameters
bufThe network buffer to prepend data to
dataThe data to prepend
lenThe length (in bytes) of the data to prepend
static void rohc_buf_pull ( struct rohc_buf *const  buf,
const size_t  offset 
)
inlinestatic

Pull the beginning of the given network buffer.

Pulling the beginning of the buffer increases the space at the beginning of the buffer. This is useful when parsing a network packet (once bytes are read, pull them) for example.

Parameters
bufThe network buffer to check for
offsetThe offset to pull the beginning of the buffer of
static void rohc_buf_push ( struct rohc_buf *const  buf,
const size_t  offset 
)
inlinestatic

Push the beginning of the given network buffer.

Pushing the beginning of the buffer decreases the space at the beginning of the buffer. This is useful to prepend a network header before the network buffer.

Parameters
bufThe network buffer to check for
offsetThe offset to push the beginning of the buffer of
static void rohc_buf_reset ( struct rohc_buf *const  buf)
inlinestatic

Reset the given network buffer.

Parameters
bufThe network buffer to remove all data from
const char* rohc_get_ext_descr ( const rohc_ext_t  ext_type)

Give a description for the given type of ROHC extension.

Give a description for the given type of ROHC extension.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of the extensions used by the library. If unsure, ask on the mailing list.

Parameters
ext_typeThe type of extension to get a description for
Returns
A string that describes the given extension type
const char* rohc_get_mode_descr ( const rohc_mode_t  mode)

Give a description for the given ROHC mode.

Give a description for the given ROHC mode.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of modes used by the library. If unsure, ask on the mailing list.

Parameters
modeThe ROHC mode to get a description for
Returns
A string that describes the given ROHC mode
const char* rohc_get_packet_descr ( const rohc_packet_t  packet_type)

Give a description for the given type of ROHC packet.

Give a description for the given type of ROHC packet.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of the packets used by the library. If unsure, ask on the mailing list.

Parameters
packet_typeThe type of packet to get a description for
Returns
A string that describes the given packet type
rohc_packet_t rohc_get_packet_type ( const char *const  packet_id)

Get the packet type from a packet identifier.

Parameters
packet_idThe identifier of packet (NULL-terminated string)
Returns
The corresponding packet type
const char* rohc_get_profile_descr ( const rohc_profile_t  profile)

Give a description for the given ROHC profile.

Give a description for the given ROHC compression/decompression profile.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of profiles used by the library. If unsure, ask on the mailing list.

Parameters
profileThe ROHC profile to get a description for
Returns
A string that describes the given ROHC profile
const char* rohc_strerror ( const rohc_status_t  status)

Give a description for the given ROHC status code.

Give a description for the given ROHC status code.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of status codes returned by the library. If unsure, ask on the mailing list.

Parameters
statusThe ROHC status code to get a description for
Returns
A string that describes the given ROHC status code
char* rohc_version ( void  )

Get the version of the ROHC library.

Get the version of the ROHC library

Returns
the version of the library
Example:
const char *version;
version = rohc_version();
printf("ROHC version %s\n", version);