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...
Defines
#define	ROHC_ETHERTYPE 0x22f1
	The Ethertype assigned to the ROHC protocol by the IEEE.
#define	ROHC_LARGE_CID_MAX ((1U << 14) - 1)
	The maximum value for large CIDs.
#define	ROHC_SMALL_CID_MAX 15U
	The maximum value for small CIDs.
#define	rohc_buf_init_empty(__data, __max_len)
	Initialize the given network buffer with no data.
#define	rohc_buf_init_full(__data, __len, __time)
	Initialize the given network buffer with all its data.
#define	rohc_buf_byte_at(__buf, __offset) ((__buf).data)[(__buf).offset + (__offset)]
	Get the byte at the given offset in the given network buffer.
#define	rohc_buf_byte(__buf) rohc_buf_byte_at((__buf), 0)
	Get the next byte in the given network buffer.
#define	ROHC_PROFILE_GENERAL 0xffff
	A general profile number used for traces not related to a specific profile.
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.
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?
static bool	rohc_buf_is_empty (const struct rohc_buf buf)
	Is the given network buffer empty?
static void	rohc_buf_pull (struct rohc_buf *const buf, const size_t offset)
	Pull the beginning of the given network buffer.
static void	rohc_buf_push (struct rohc_buf *const buf, const size_t offset)
	Push the beginning of the given network buffer.
static size_t	rohc_buf_avail_len (const struct rohc_buf buf)
	How many bytes the given network buffer may contain?
static uint8_t *	rohc_buf_data (const struct rohc_buf buf)
	Get the bytes in the given network buffer.
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.
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.
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.
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.
static void	rohc_buf_reset (struct rohc_buf *const buf)
	Reset the given network buffer.
char *	rohc_version (void)
	Get the version of the ROHC library.
const char *	rohc_strerror (const rohc_status_t status)
	Give a description for the given ROHC status code.
const char *	rohc_get_mode_descr (const rohc_mode_t mode)
	Give a description for the given ROHC mode.
const char *	rohc_get_profile_descr (const rohc_profile_t profile)
	Give a description for the given ROHC profile.
const char *	rohc_get_packet_descr (const rohc_packet_t packet_type)
	Give a description for the given type of ROHC packet.
const char *	rohc_get_ext_descr (const rohc_ext_t ext_type)
	Give a description for the given type of ROHC extension.
rohc_packet_t	rohc_get_packet_type (const char *const packet_id)
	Get the packet type from a packet identifier.

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.

Define Documentation

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

Get the next byte in the given network buffer.

Parameters:

__buf

The 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:

	__buf	The network buffer to get a byte from
	__offset	The 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:

	__data	The packet data to point to
	__max_len	The 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);

#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:

	__data	The packet data to point to
	__len	The maxmimum length (in bytes) of the packet data
	__time	The 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);

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

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:: simple_rohc_program.c define ROHC compressor simple_rohc_program.c create ROHC compressor

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:

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.

Parameters:

	priv_ctxt	An optional private context, may be NULL
	level	The level of the message,

See also:: rohc_trace_level_t

Parameters:

entity

The entity concerned by the traces

See also:: rohc_trace_entity_t

Parameters:

	profile	The number of the profile concerned by the message
	format	The 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

enum 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].

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

enum rohc_profile_t

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

enum 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

enum 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

enum 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

static void rohc_buf_append	(	struct rohc_buf *const	buf,
		const uint8_t *const	data,
		const size_t	len
	)			`[inline, static]`

Add data at the end of the given network buffer.

Parameters:

	buf	The network buffer to append data to
	data	The data to append
	len	The length (in bytes) of the data to append

static void rohc_buf_append_buf	(	struct rohc_buf *const	dst,
		const struct rohc_buf	src
	)			`[inline, static]`

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

Parameters:

	dst	The network buffer to append data to
	src	The network buffer to append data from

static size_t rohc_buf_avail_len ( const struct rohc_buf buf ) [inline, static]

How many bytes the given network buffer may contain?

Parameters:

buf

The 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 ) [inline, static]

Get the bytes in the given network buffer.

This function is a shortcut for:

        rohc_buf_data_at(buf, 0);

Parameters:

buf

The 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
	)			`[inline, static]`

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

Parameters:

	buf	The network buffer to get bytes from
	offset	The 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 ) [inline, static]

Is the given network buffer empty?

Empty means no data at all.

Parameters:

buf

The 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 ) [inline, static]

Is the given network buffer malformed?

Parameters:

buf

The 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
	)			`[inline, static]`

Add data at the beginning of the given network buffer.

Parameters:

	buf	The network buffer to prepend data to
	data	The data to prepend
	len	The length (in bytes) of the data to prepend

static void rohc_buf_pull	(	struct rohc_buf *const	buf,
		const size_t	offset
	)			`[inline, static]`

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:

	buf	The network buffer to check for
	offset	The offset to pull the beginning of the buffer of

static void rohc_buf_push	(	struct rohc_buf *const	buf,
		const size_t	offset
	)			`[inline, static]`

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:

	buf	The network buffer to check for
	offset	The offset to push the beginning of the buffer of

static void rohc_buf_reset ( struct rohc_buf *const buf ) [inline, static]

Reset the given network buffer.

Parameters:

buf

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

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_type

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

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:

mode

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

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_type

The 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_id

The 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:

profile

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

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:

status

The 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:: print_rohc_version.c get ROHC version

The ROHC compressor/decompressor common API

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation