rohc_decomp.h − The ROHC decompression API
#include <rohc/rohc_decomp.h>
The decompression API of the ROHC library allows a program to decompress some ROHC packets into uncompressed packets.
The program shall first create a decompressor context and configure it. It then may decompress as many packets as needed. When done, the ROHC decompressor context shall be destroyed.
struct
rohc_decomp *rohc_decomp_new2(const rohc_cid_type_t
cid_type,
const rohc_cid_t max_cid,
const rohc_mode_t mode);
void rohc_decomp_free(struct rohc_decomp *const decomp);
rohc_status_t rohc_decompress3(struct rohc_decomp *const
decomp,
const struct rohc_buf rohc_packet,
struct rohc_buf *const uncomp_packet,
struct rohc_buf *const rcvd_feedback,
struct rohc_buf *const feedback_send);
const char *rohc_decomp_get_state_descr(const
rohc_decomp_state_t state);
bool rohc_decomp_get_last_packet_info(const struct
rohc_decomp *const decomp,
rohc_decomp_last_packet_info_t *const info);
bool rohc_decomp_get_context_info(const struct rohc_decomp
*const decomp,
const rohc_cid_t cid,
rohc_decomp_context_info_t *const info);
bool rohc_decomp_get_general_info(const struct rohc_decomp
*const decomp,
rohc_decomp_general_info_t *const info);
bool rohc_decomp_get_cid_type(const struct rohc_decomp
*const decomp,
rohc_cid_type_t *const cid_type);
bool rohc_decomp_get_max_cid(const struct rohc_decomp *const
decomp,
size_t *const max_cid);
bool rohc_decomp_set_mrru(struct rohc_decomp *const decomp,
const size_t mrru);
bool rohc_decomp_get_mrru(const struct rohc_decomp *const
decomp,
size_t *const mrru);
bool rohc_decomp_set_prtt(struct rohc_decomp *const decomp,
const size_t prtt);
bool rohc_decomp_get_prtt(const struct rohc_decomp *const
decomp,
size_t *const prtt);
bool rohc_decomp_set_rate_limits(struct rohc_decomp *const
decomp,
const size_t k,
const size_t n,
const size_t k_1,
const size_t n_1,
const size_t k_2,
const size_t n_2);
bool rohc_decomp_get_rate_limits(const struct rohc_decomp
*const decomp,
size_t *const k,
size_t *const n,
size_t *const k_1,
size_t *const n_1,
size_t *const k_2,
size_t *const n_2);
bool rohc_decomp_set_features(struct rohc_decomp *const
decomp,
const rohc_decomp_features_t features);
bool rohc_decomp_profile_enabled(const struct rohc_decomp
*const decomp,
const rohc_profile_t profile);
bool rohc_decomp_enable_profile(struct rohc_decomp *const
decomp,
const rohc_profile_t profile);
bool rohc_decomp_disable_profile(struct rohc_decomp *const
decomp,
const rohc_profile_t profile);
bool rohc_decomp_enable_profiles(struct rohc_decomp *const
decomp,
...);
bool rohc_decomp_disable_profiles(struct rohc_decomp *const
decomp,
...);
bool rohc_decomp_set_traces_cb2(struct rohc_decomp * decomp,
rohc_trace_callback2_t callback,
void *const priv_ctxt);
The ROHC
decompressor states
The different ROHC operation states at decompressor as
defined in section 4.3.2 of RFC 3095.
enum
rohc_decomp_state_t {
ROHC_DECOMP_STATE_UNKNOWN, /* Unknown decompressor state
*/
ROHC_DECOMP_STATE_NC, /* The No Context state */
ROHC_DECOMP_STATE_SC, /* The Static Context state */
ROHC_DECOMP_STATE_FC, /* The Full Context state */
};
The
different features of the ROHC decompressor
Features for the ROHC decompressor control whether
mechanisms defined as optional by RFCs are enabled or not.
They can be set or unset with the function
rohc_decomp_set_features.
enum
rohc_decomp_features_t {
ROHC_DECOMP_FEATURE_NONE, /* No feature at all */
ROHC_DECOMP_FEATURE_CRC_REPAIR, /* Attempt packet repair
in case of CRC failure */
ROHC_DECOMP_FEATURE_COMPAT_1_6_x, /* Be compatible with
1.6.x versions */
ROHC_DECOMP_FEATURE_DUMP_PACKETS, /* Dump content of
packets in traces (beware: performance impact) */
};
Some
information about one decompression context
The structure is used by the
rohc_decomp_get_context_info function to store some
information about one decompression context.
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_decomp_get_context_info.
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, packets_nr, comp_bytes_nr, uncomp_bytes_nr, corrected_crc_failures, corrected_sn_wraparounds, and corrected_wrong_sn_updates.
struct
rohc_decomp_context_info_t {
unsigned short version_major; /* The major version of
this structure */
unsigned short version_minor; /* The minor version of
this structure */
unsigned long packets_nr; /* The number of packets
processed by the context */
unsigned long comp_bytes_nr; /* The number of
compressed bytes received by the context */
unsigned long uncomp_bytes_nr; /* The number of
uncompressed bytes produced by the context */
unsigned long corrected_crc_failures; /* The number
of successful corrections upon CRC failure */
unsigned long corrected_sn_wraparounds; /* The number
of successful corrections of SN wraparound upon CRC failure
*/
unsigned long corrected_wrong_sn_updates; /* The
number of successful corrections of incorrect SN updates
upon CRC failure */
};
Some
information about the last decompressed packet
The structure is used by the
rohc_decomp_get_last_packet_info function to store
some information about the last decompressed 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_decomp_get_last_packet_info.
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_mode, context_state, profile_id, nr_lost_packets, nr_misordered_packets, and is_duplicated
• Major 0 / Minor = 1 added: corrected_crc_failures, corrected_sn_wraparounds, corrected_wrong_sn_updates, and packet_type
struct
rohc_decomp_last_packet_info_t {
unsigned short version_major; /* The major version of
this structure */
unsigned short version_minor; /* The minor version of
this structure */
rohc_mode_t context_mode; /* The mode of the last
context used by the compressor */
rohc_decomp_state_t context_state; /* The state of
the last context used by the compressor */
int profile_id; /* The profile ID of the last context
used by the compressor */
unsigned long nr_lost_packets; /* The number of
(possible) lost packet(s) before last packet */
unsigned long nr_misordered_packets; /* The number of
packet(s) before the last packet if late */
bool is_duplicated; /* Is last packet a (possible)
duplicated packet? */
unsigned long corrected_crc_failures; /* The number
of successful corrections upon CRC failure */
unsigned long corrected_sn_wraparounds; /* The number
of successful corrections of SN wraparound upon CRC failure
*/
unsigned long corrected_wrong_sn_updates; /* The
number of successful corrections of incorrect SN updates
upon CRC failure */
rohc_packet_t packet_type; /* The type of the last
decompressed ROHC packet */
unsigned long total_last_comp_size; /* The compressed
size (in bytes) of the last decompressed packet */
unsigned long header_last_comp_size; /* The
compressed size (in bytes) of the last decompressed header
*/
unsigned long total_last_uncomp_size; /* The
uncompressed size (in bytes) of the last decompressed packet
*/
unsigned long header_last_uncomp_size; /* The
uncompressed size (in bytes) of the last decompressed header
*/
};
Some general
information about the decompressor
The structure is used by the
rohc_decomp_get_general_info function to store some
general information about the decompressor.
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_decomp_get_general_info.
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, comp_bytes_nr, and uncomp_bytes_nr.
struct
rohc_decomp_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 decompressor */
unsigned long packets_nr; /* The number of packets
processed by the decompressor */
unsigned long comp_bytes_nr; /* The number of
compressed bytes received by the decompressor */
unsigned long uncomp_bytes_nr; /* The number of
uncompressed bytes produced by the decompressor */
unsigned long corrected_crc_failures; /* The
cumulative number of successful corrections upon CRC failure
*/
unsigned long corrected_sn_wraparounds; /* The
cumulative number of successful corrections of SN wraparound
upon CRC failure */
unsigned long corrected_wrong_sn_updates; /* The
cumulative number of successful corrections of incorrect SN
updates upon CRC failure */
};
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) */
};
rohc_decomp_new2(3), rohc_decomp_free(3), rohc_decompress3(3), rohc_decomp_get_state_descr(3), rohc_decomp_get_last_packet_info(3), rohc_decomp_get_context_info(3), rohc_decomp_get_general_info(3), rohc_decomp_get_cid_type(3), rohc_decomp_get_max_cid(3), rohc_decomp_set_mrru(3), rohc_decomp_get_mrru(3), rohc_decomp_set_prtt(3), rohc_decomp_get_prtt(3), rohc_decomp_set_rate_limits(3), rohc_decomp_get_rate_limits(3), rohc_decomp_set_features(3), rohc_decomp_profile_enabled(3), rohc_decomp_enable_profile(3), rohc_decomp_disable_profile(3), rohc_decomp_enable_profiles(3), rohc_decomp_disable_profiles(3), rohc_decomp_set_traces_cb2(3)