rohc_comp.h

NAME
SYNOPSIS
DESCRIPTION
STRUCTURES
SEE ALSO

NAME

rohc_comp.h − The ROHC compression API

SYNOPSIS

#include <rohc/rohc_comp.h>

DESCRIPTION

The compression API of the ROHC library allows a program to compress the protocol headers of some uncompressed packets into ROHC packets.

The program shall first create a compressor context and configure it. It then may compress as many packets as needed. When done, the ROHC compressor context shall be destroyed.

struct rohc_comp *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);
void rohc_comp_free(struct rohc_comp *const comp);
bool rohc_comp_set_traces_cb2(struct rohc_comp *const comp,
rohc_trace_callback2_t callback,
void *const priv_ctxt);
rohc_status_t rohc_compress4(struct rohc_comp *const comp,
const struct rohc_buf uncomp_packet,
struct rohc_buf *const rohc_packet);
rohc_status_t rohc_comp_pad(struct rohc_comp *const comp,
struct rohc_buf *const rohc_pkt,
const size_t min_pkt_len);
rohc_status_t rohc_comp_get_segment2(struct rohc_comp *const comp,
struct rohc_buf *const segment);
bool rohc_comp_force_contexts_reinit(struct rohc_comp *const comp);
bool rohc_comp_set_wlsb_window_width(struct rohc_comp *const comp,
const size_t width);
bool rohc_comp_set_reorder_ratio(struct rohc_comp *const comp,
const rohc_reordering_offset_t reorder_ratio);
bool rohc_comp_set_periodic_refreshes(struct rohc_comp *const comp,
const size_t ir_timeout,
const size_t fo_timeout);
bool rohc_comp_set_periodic_refreshes_time(struct rohc_comp *const comp,
const uint64_t ir_timeout,
const uint64_t fo_timeout);
bool rohc_comp_set_list_trans_nr(struct rohc_comp *const comp,
const size_t list_trans_nr);
bool rohc_comp_set_rtp_detection_cb(struct rohc_comp *const comp,
rohc_rtp_detection_callback_t callback,
void *const rtp_private);
bool rohc_comp_profile_enabled(const struct rohc_comp *const comp,
const rohc_profile_t profile);
bool rohc_comp_enable_profile(struct rohc_comp *const comp,
const rohc_profile_t profile);
bool rohc_comp_disable_profile(struct rohc_comp *const comp,
const rohc_profile_t profile);
bool rohc_comp_enable_profiles(struct rohc_comp *const comp,
...);
bool rohc_comp_disable_profiles(struct rohc_comp *const comp,
...);
bool rohc_comp_set_mrru(struct rohc_comp *const comp,
const size_t mrru);
bool rohc_comp_get_mrru(const struct rohc_comp *const comp,
size_t *const mrru);
bool rohc_comp_get_max_cid(const struct rohc_comp *const comp,
size_t *const max_cid);
bool rohc_comp_get_cid_type(const struct rohc_comp *const comp,
rohc_cid_type_t *const cid_type);
bool rohc_comp_set_features(struct rohc_comp *const comp,
const rohc_comp_features_t features);
bool rohc_comp_deliver_feedback2(struct rohc_comp *const comp,
const struct rohc_buf feedback);
bool rohc_comp_get_last_packet_info2(const struct rohc_comp *const comp,
rohc_comp_last_packet_info2_t *const info);
bool rohc_comp_get_general_info(const struct rohc_comp *const comp,
rohc_comp_general_info_t *const info);
const char *rohc_comp_get_state_descr(const rohc_comp_state_t state);

STRUCTURES

The different values of reordering offset

enum rohc_reordering_offset_t {
ROHC_REORDERING_NONE, /* No reordering accepted */
ROHC_REORDERING_QUARTER, /* Reordering accepted on 1/4 of the WLSB */
ROHC_REORDERING_HALF, /* Reordering accepted on 1/2 of the WLSB */
ROHC_REORDERING_THREEQUARTERS, /* Reordering accepted on 3/4 of the WLSB */
};

The different ROHC compressor states
The different ROHC operation states at compressor as defined in section 4.3.1 of RFC 3095. The CR operation state is defined in RFC 4164.

If you add a new compressor state, please also add the corresponding textual description in rohc_comp_get_state_descr.

enum rohc_comp_state_t {
ROHC_COMP_STATE_UNKNOWN, /* Unknown compressor state */
ROHC_COMP_STATE_IR, /* The Initialization and Refresh (IR) compressor state */
ROHC_COMP_STATE_FO, /* The First Order (FO) compressor state */
ROHC_COMP_STATE_SO, /* The Second Order (SO) compressor state */
ROHC_COMP_STATE_CR, /* The Context Replication (CR) compressor state */
};

The different features of the ROHC compressor
Features for the ROHC compressor control whether mechanisms defined as optional by RFCs are enabled or not. They can be set or unset with the function rohc_comp_set_features.

enum rohc_comp_features_t {
ROHC_COMP_FEATURE_NONE, /* No feature at all */
ROHC_COMP_FEATURE_COMPAT_1_6_x, /* Be compatible with 1.6.x versions */
ROHC_COMP_FEATURE_NO_IP_CHECKSUMS, /* Do not check IP checksums at compressor */
ROHC_COMP_FEATURE_DUMP_PACKETS, /* Dump content of packets in traces (beware: performance impact) */
ROHC_COMP_FEATURE_TIME_BASED_REFRESHES, /* Allow periodic refreshes based on inter-packet time */
};

The prototype of the RTP detection callback
User-defined function that is called by the ROHC library for every UDP packet to determine whether the UDP packet transports RTP data. If the function returns true, the RTP profile is used to compress the packet. Otherwise the UDP profile is used.

The user-defined function is set by calling the function rohc_comp_set_rtp_detection_cb

Return true if the packet is an RTP packet, false otherwise

typedef bool (*rohc_rtp_detection_callback_t) (
const unsigned char *const ip, /* The innermost IP packet */
const unsigned char *const udp, /* The UDP header of the packet */
const unsigned char *const payload, /* The UDP payload of the packet */
const unsigned int payload_size, /* The size of the UDP payload (in bytes) */
void *const rtp_private /* A pointer to a memory area to be used by the callback function, may be NULL. */
);

The prototype of the callback for random numbers
User-defined function that is called when the ROHC library requires a random number. Currently, the ROHC library uses it when initializing the Sequence Number (SN) of contexts using the IP-only, IP/UDP, and IP/UDP-Lite profiles.

The user-defined function is set by calling the function rohc_comp_new2

typedef int (*rohc_comp_random_cb_t) (
const struct rohc_comp *const comp, /* The ROHC compressor */
void *const user_context /* The context given by the user when he/she called the rohc_comp_new2 function, may be NULL. */
);

Some information about the last compressed packet
The structure is used by the rohc_comp_get_last_packet_info2 function to store some information about the last compressed packet.

Versioning works as follow:

• The version_major field defines the compatibility level. If the major number given by user does not match the one expected by the library, an error is returned.

• The version_minor field defines the extension level. If the minor number given by user does not match the one expected by the library, only the fields supported in that minor version will be filled by rohc_comp_get_last_packet_info2.

Notes for developers:

• Increase the major version if a field is removed.

• Increase the major version if a field is added at the beginning or in the middle of the structure.

• Increase the minor version if a field is added at the very end of the structure.

• The version_major and version_minor fields must be located at the very beginning of the structure.

• The structure must be packed.

Supported versions:

• Major 0 / Minor 0 contains: version_major, version_minor, context_id, is_context_init, context_mode, context_state, context_used, profile_id, packet_type, total_last_uncomp_size, header_last_uncomp_size, total_last_comp_size, and header_last_comp_size

struct rohc_comp_last_packet_info2_t {
unsigned short version_major; /* The major version of this structure */
unsigned short version_minor; /* The minor version of this structure */
unsigned int context_id; /* The Context ID (CID) */
bool is_context_init; /* Whether the context was initialized (created/re-used) by the packet */
rohc_mode_t context_mode; /* The mode of the last context used by the compressor */
rohc_comp_state_t context_state; /* The state of the last context used by the compressor */
bool context_used; /* Whether the last context used by the compressor is still in use */
int profile_id; /* The profile ID of the last context used by the compressor */
rohc_packet_t packet_type; /* The type of ROHC packet created for the last compressed packet */
unsigned long total_last_uncomp_size; /* The uncompressed size (in bytes) of the last compressed packet */
unsigned long header_last_uncomp_size; /* The uncompressed size (in bytes) of the last compressed header */
unsigned long total_last_comp_size; /* The compressed size (in bytes) of the last compressed packet */
unsigned long header_last_comp_size; /* The compressed size (in bytes) of the last compressed header */
};

Some general information about the compressor
The structure is used by the rohc_comp_get_general_info function to store some general information about the compressor.

Versioning works as follow:

• The version_major field defines the compatibility level. If the major number given by user does not match the one expected by the library, an error is returned.

Notes for developers:

• Increase the major version if a field is removed.

• Increase the major version if a field is added at the beginning or in the middle of the structure.

• Increase the minor version if a field is added at the very end of the structure.

• The version_major and version_minor fields must be located at the very beginning of the structure.

• The structure must be packed.

Supported versions:

• major 0 and minor = 0 contains: version_major, version_minor, contexts_nr, packets_nr, uncomp_bytes_nr, and comp_bytes_nr.

struct rohc_comp_general_info_t {
unsigned short version_major; /* The major version of this structure */
unsigned short version_minor; /* The minor version of this structure */
size_t contexts_nr; /* The number of contexts used by the compressor */
unsigned long packets_nr; /* The number of packets processed by the compressor */
unsigned long uncomp_bytes_nr; /* The number of uncompressed bytes received by the compressor */
unsigned long comp_bytes_nr; /* The number of compressed bytes produced by the compressor */
};

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) */
};