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, ROHCv2_PROFILE_IP_UDP_RTP = 0x0101, ROHCv2_PROFILE_IP_UDP = 0x0102, ROHCv2_PROFILE_IP_ESP = 0x0103,
  ROHCv2_PROFILE_IP = 0x0104, ROHCv2_PROFILE_IP_UDPLITE_RTP = 0x0107, ROHCv2_PROFILE_IP_UDPLITE = 0x0108, ROHC_PROFILE_MAX = 0x0109
}
 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_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...
 
const char * rohc_get_profile_descr (const rohc_profile_t profile)
 Give a description for the given ROHC profile. More...
 
bool rohc_profile_is_rohcv1 (const rohc_profile_t profile)
 Is the given profile one ROHCv1 profile? More...
 
bool rohc_profile_is_rohcv2 (const rohc_profile_t profile)
 Is the given profile one ROHCv2 profile? More...
 
rohc_profile_t rohc_profile_get_other_version (const rohc_profile_t profile)
 Get the other version of the given profile. 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

◆ rohc_buf_byte

#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

◆ rohc_buf_byte_at

#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

◆ rohc_buf_init_empty

#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:
#define PKT_DATA_LEN 145U
uint8_t pkt_data[PKT_DATA_LEN];
struct rohc_buf packet = rohc_buf_init_empty(pkt_data, PKT_DATA_LEN);

◆ rohc_buf_init_full

#define rohc_buf_init_full (   __data,
  __len,
  __time 
)
Value:
{ \
.time = (__time), \
.data = (__data), \
.max_len = (__len), \
.offset = 0, \
.len = (__len), \
}
size_t offset
Definition: rohc_buf.h:107
size_t len
Definition: rohc_buf.h:108
uint8_t * data
Definition: rohc_buf.h:105

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:
#define PKT_DATA_LEN 145U
const uint8_t pkt_data[PKT_DATA_LEN];
const struct rohc_ts arrival_time = { .sec = 1399745625, .nsec = 42 };
const struct rohc_buf packet =
rohc_buf_init_full(pkt_data, PKT_DATA_LEN, arrival_time);

◆ ROHC_ETHERTYPE

#define ROHC_ETHERTYPE   0x22f1

The Ethertype assigned to the ROHC protocol by the IEEE.

See also
http://standards.ieee.org/regauth/ethertype/eth.txt

◆ ROHC_LARGE_CID_MAX

#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

◆ ROHC_PROFILE_GENERAL

#define ROHC_PROFILE_GENERAL   0xffff

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

◆ ROHC_SMALL_CID_MAX

#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

◆ rohc_trace_callback2_t

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

◆ rohc_cid_type_t

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_mode_t

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)

◆ rohc_profile_t

The different ROHC compression/decompression profiles.

The ROHC profiles numbers are allocated by the IANA:

  • see §8 in the RFC 3095 (ROHCv1)
  • see §5 in the RFC 3843 (ROHCv1 IP-only)
  • see §7 in the RFC 4019 (ROHCv1 UDP-Lite)
  • see §11 in the RFC 6846 (ROHCv1 TCP)
  • see §8 in the RFC 5252 (ROHCv2)

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 ROHCv1 Uncompressed profile (RFC 3095, section 5.10)

ROHC_PROFILE_RTP 

The ROHCv1 RTP profile (RFC 3095, section 8)

ROHC_PROFILE_UDP 

The ROHCv1 UDP profile (RFC 3095, section 5.11)

ROHC_PROFILE_ESP 

The ROHCv1 ESP profile (RFC 3095, section 5.12)

ROHC_PROFILE_IP 

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

ROHC_PROFILE_RTP_LLA 

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

ROHC_PROFILE_TCP 

The ROHCv1 TCP profile (RFC 4996)

ROHC_PROFILE_UDPLITE_RTP 

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

ROHC_PROFILE_UDPLITE 

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

ROHCv2_PROFILE_IP_UDP_RTP 

The ROHCv2 RTP/UDP/IP profile

ROHCv2_PROFILE_IP_UDP 

The ROHCv2 UDP/IP profile

ROHCv2_PROFILE_IP_ESP 

The ROHCv2 ESP/IP profile

ROHCv2_PROFILE_IP 

The ROHCv2 IP-only profile

ROHCv2_PROFILE_IP_UDPLITE_RTP 

The ROHCv2 IP/UDP-Lite/RTP profile

ROHCv2_PROFILE_IP_UDPLITE 

The ROHCv2 IP/UDP-Lite profile

ROHC_PROFILE_MAX 

◆ rohc_status_t

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

◆ rohc_trace_entity_t

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

◆ rohc_trace_level_t

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

◆ rohc_buf_append()

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

◆ rohc_buf_append_buf()

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

◆ rohc_buf_avail_len()

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

◆ rohc_buf_data()

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:

Parameters
bufThe network buffer to get bytes from
Returns
The bytes stored in the network buffer

◆ rohc_buf_data_at()

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

◆ rohc_buf_is_empty()

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

◆ rohc_buf_is_malformed()

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

◆ rohc_buf_prepend()

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

◆ rohc_buf_pull()

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

◆ rohc_buf_push()

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

◆ rohc_buf_reset()

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

◆ rohc_get_ext_descr()

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

◆ rohc_get_mode_descr()

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

◆ rohc_get_packet_descr()

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_get_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

◆ rohc_get_profile_descr()

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

◆ rohc_profile_get_other_version()

rohc_profile_t rohc_profile_get_other_version ( const rohc_profile_t  profile)

Get the other version of the given profile.

Parameters
profileThe profile ID for which to get the other version
Returns
The ROHCv1 profile if the given one is ROHCv2, the ROHCv2 profile if the given one is ROHCv1, ROHC_PROFILE_MAX otherwise

◆ rohc_profile_is_rohcv1()

bool rohc_profile_is_rohcv1 ( const rohc_profile_t  profile)

Is the given profile one ROHCv1 profile?

Parameters
profileThe profile ID to check for
Returns
true if profile is one ROHCv1 profile, false if profile is one ROHCv2 profile

◆ rohc_profile_is_rohcv2()

bool rohc_profile_is_rohcv2 ( const rohc_profile_t  profile)

Is the given profile one ROHCv2 profile?

Parameters
profileThe profile ID to check for
Returns
true if profile is one ROHCv2 profile, false if profile is one ROHCv1 profile

◆ rohc_strerror()

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

◆ rohc_version()

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);