rohc.h

NAME
SYNOPSIS
DESCRIPTION
STRUCTURES
SEE ALSO

NAME

rohc.h − The ROHC compressor/decompressor common API

SYNOPSIS

#include <rohc/rohc.h>

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.

bool rohc_buf_is_malformed(const struct rohc_buf buf);
bool rohc_buf_is_empty(const struct rohc_buf buf);
void rohc_buf_pull(struct rohc_buf *const buf,
const size_t offset);
void rohc_buf_push(struct rohc_buf *const buf,
const size_t offset);
size_t rohc_buf_avail_len(const struct rohc_buf buf);
uint8_t *rohc_buf_data(const struct rohc_buf buf);
uint8_t *rohc_buf_data_at(const struct rohc_buf buf,
const size_t offset);
void rohc_buf_prepend(struct rohc_buf *const buf,
const uint8_t *const data,
const size_t len);
void rohc_buf_append(struct rohc_buf *const buf,
const uint8_t *const data,
const size_t len);
void rohc_buf_append_buf(struct rohc_buf *const dst,
const struct rohc_buf src);
void rohc_buf_reset(struct rohc_buf *const buf);
char *rohc_version(void);
const char *rohc_strerror(const rohc_status_t status);
const char *rohc_get_mode_descr(const rohc_mode_t mode);
const char *rohc_get_packet_descr(const rohc_packet_t packet_type);
const char *rohc_get_ext_descr(const rohc_ext_t ext_type);
rohc_packet_t rohc_get_packet_type(const char *const packet_id);
const char *rohc_get_profile_descr(const rohc_profile_t profile);
bool rohc_profile_is_rohcv1(const rohc_profile_t profile);
bool rohc_profile_is_rohcv2(const rohc_profile_t profile);
rohc_profile_t rohc_profile_get_other_version(const rohc_profile_t profile);

STRUCTURES

The status code of several functions in the library API

enum rohc_status_t {
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 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.

enum rohc_mode_t {
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 types of Context IDs (CID)
CID values shall be in the range [0, ROHC_LARGE_CID_MAXCID value shall be in the range [0, ROHC_SMALL_CID_MAXThe 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.

enum rohc_cid_type_t {
ROHC_LARGE_CID, /* The context uses large CID. */
ROHC_SMALL_CID, /* The context uses small CID. */
};

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.

enum rohc_profile_t {
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, /* */
};

The different levels of the traces
Used for the level parameter of the rohc_trace_callback2_t user-defined callback.

enum rohc_trace_level_t {
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 */
};

The different entities concerned by the traces
Used for the source entity parameter of the rohc_trace_callback2_t user-defined callback.

enum rohc_trace_entity_t {
ROHC_TRACE_COMP, /* Compressor traces */
ROHC_TRACE_DECOMP, /* Decompressor traces */
ROHC_TRACE_ENTITY_MAX, /* The maximum number of trace entities */
};

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:

• function rohc_comp_set_traces_cb2 for a ROHC compressor,

• function rohc_decomp_set_traces_cb2 for a ROHC decompressor.

Both functions accept the NULL value to fully disable tracing.

typedef void (*rohc_trace_callback2_t) (
void *const priv_ctxt, /* An optional private context, may be NULL */
const rohc_trace_level_t level, /* The level of the message, */
const rohc_trace_entity_t entity, /* The entity concerned by the traces */
const int profile, /* The number of the profile concerned by the message */
const char *const format /* The format string for the trace message */
);

A network buffer for the ROHC library
May represent one uncompressed packet, one ROHC packet, or a ROHC feedback.

The network buffer does not contain the packet data itself. It only has a pointer on it. This is designed this way for performance reasons: no copy required to initialize a network buffer, the struct is small and may be passed as copy to function.

The network buffer is able to keep some free space at its beginning. The unused space at the beginning of the buffer may be used to prepend a network header at the very end of the packet handling.

The beginning of the network buffer may also be shifted forward with the rohc_buf_pull function or shifted backward with the rohc_buf_push function. This is useful when parsing a network packet (once bytes are read, shift them forward) for example.

The network buffer may be initialized manually (see below) or with the helper functions rohc_buf_init_empty or rohc_buf_init_full...

struct rohc_buf {
struct rohc_ts time; /* The timestamp associated to the data */
uint8_t *data; /* The buffer data */
size_t max_len; /* The maximum length of the buffer */
size_t offset; /* The offset for the beginning of the data */
size_t len; /* The data length (in bytes) */
};