The ROHC decompression API

Data Structures
struct	rohc_decomp_last_packet_info_t
	Some information about the last decompressed packet. More...
struct	rohc_decomp_context_info_t
	Some information about one decompression context. More...
struct	rohc_decomp_general_info_t
	Some general information about the decompressor. More...

Enumerations
enum	rohc_decomp_state_t { ROHC_DECOMP_STATE_UNKNOWN = 0, ROHC_DECOMP_STATE_NC = 1, ROHC_DECOMP_STATE_SC = 2, ROHC_DECOMP_STATE_FC = 3 }
	The ROHC decompressor states. More...
enum	rohc_decomp_features_t { ROHC_DECOMP_FEATURE_NONE = 0, ROHC_DECOMP_FEATURE_CRC_REPAIR = (1 << 0), ROHC_DECOMP_FEATURE_COMPAT_1_6_x = (1 << 1), ROHC_DECOMP_FEATURE_DUMP_PACKETS = (1 << 3) }
	The different features of the ROHC decompressor. More...

Functions
struct rohc_decomp *	rohc_decomp_new2 (const rohc_cid_type_t cid_type, const rohc_cid_t max_cid, const rohc_mode_t mode)
	Create a new ROHC decompressor. More...
void	rohc_decomp_free (struct rohc_decomp *const decomp)
	Destroy the given ROHC decompressor. More...
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)
	Decompress the given ROHC packet into one uncompressed packet. More...
const char *	rohc_decomp_get_state_descr (const rohc_decomp_state_t state)
	Give a description for the given ROHC decompression context state. More...
bool	rohc_decomp_get_last_packet_info (const struct rohc_decomp *const decomp, rohc_decomp_last_packet_info_t *const info)
	Get some information about the last decompressed packet. More...
bool	rohc_decomp_get_context_info (const struct rohc_decomp *const decomp, const rohc_cid_t cid, rohc_decomp_context_info_t *const info)
	Get some information about the given decompression context. More...
bool	rohc_decomp_get_general_info (const struct rohc_decomp *const decomp, rohc_decomp_general_info_t *const info)
	Get some general information about the decompressor. More...
bool	rohc_decomp_get_cid_type (const struct rohc_decomp *const decomp, rohc_cid_type_t *const cid_type)
	Get the CID type that the decompressor uses. More...
bool	rohc_decomp_get_max_cid (const struct rohc_decomp *const decomp, size_t *const max_cid)
	Get the maximal CID value the decompressor uses. More...
bool	rohc_decomp_set_mrru (struct rohc_decomp *const decomp, const size_t mrru)
	Set the Maximum Reconstructed Reception Unit (MRRU). More...
bool	rohc_decomp_get_mrru (const struct rohc_decomp *const decomp, size_t *const mrru)
	Get the Maximum Reconstructed Reception Unit (MRRU). More...
bool	rohc_decomp_set_prtt (struct rohc_decomp *const decomp, const size_t prtt)
	Set the number of packets sent during one Round-Trip Time (RTT). More...
bool	rohc_decomp_get_prtt (const struct rohc_decomp *const decomp, size_t *const prtt)
	Get the number of packets sent during one Round-Trip Time (RTT). More...
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)
	Set the rate limits for feedbacks. More...
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)
	Get the rate limits for feedbacks currently configured. More...
bool	rohc_decomp_set_features (struct rohc_decomp *const decomp, const rohc_decomp_features_t features)
	Enable/disable features for ROHC decompressor. More...
bool	rohc_decomp_profile_enabled (const struct rohc_decomp *const decomp, const rohc_profile_t profile)
	Is the given decompression profile enabled for a decompressor? More...
bool	rohc_decomp_enable_profile (struct rohc_decomp *const decomp, const rohc_profile_t profile)
	Enable a decompression profile for a decompressor. More...
bool	rohc_decomp_disable_profile (struct rohc_decomp *const decomp, const rohc_profile_t profile)
	Disable a decompression profile for a decompressor. More...
bool	rohc_decomp_enable_profiles (struct rohc_decomp *const decomp,...)
	Enable several decompression profiles for a decompressor. More...
bool	rohc_decomp_disable_profiles (struct rohc_decomp *const decomp,...)
	Disable several decompression profiles for a decompressor. More...
bool	rohc_decomp_set_traces_cb2 (struct rohc_decomp *decomp, rohc_trace_callback2_t callback, void *const priv_ctxt)
	Set the callback function used to manage traces in decompressor. More...

Detailed Description

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.

Enumeration Type Documentation

enum rohc_decomp_features_t

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.

See also

rohc_decomp_set_features

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

enum rohc_decomp_state_t

The ROHC decompressor states.

The different ROHC operation states at decompressor as defined in section 4.3.2 of RFC 3095.

See also

rohc_decomp_get_state_descr

Enumerator
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

Function Documentation

bool rohc_decomp_disable_profile	(	struct rohc_decomp *const	decomp,
		const rohc_profile_t	profile
	)

Disable a decompression profile for a decompressor.

Disable a decompression profiles for a decompressor.

The ROHC decompressor does not use the decompression profiles that were disabled. Thus disabling a profile might cause the decompressor to reject streams. Decompression will always fail if no profile at all is enabled.

If the profile is already disabled, nothing is performed and success is reported.

Parameters

decomp	The ROHC decompressor
profile	The profile to disable

Returns

true if the profile exists, false if the profile does not exist

See also

rohc_decomp_enable_profile

rohc_decomp_enable_profiles

rohc_decomp_disable_profiles

bool rohc_decomp_disable_profiles	(	struct rohc_decomp *const	decomp,
			...
	)

Disable several decompression profiles for a decompressor.

Disable several decompression profiles for a decompressor. The list of profiles to disable shall stop with -1.

The ROHC decompressor does not use the decompression profiles that were disabled. Thus disabling a profile might cause the decompressor to reject streams. Decompression will always fail if no profile at all is enabled.

If one or more of the profiles are already disabled, nothing is performed and success is reported.

Parameters

decomp	The ROHC decompressor
...	The sequence of decompression profiles to disable, the sequence shall be terminated by -1

Returns

true if all of the profiles exist, false if at least one of the profiles does not exist

See also

rohc_decomp_enable_profile

rohc_decomp_enable_profiles

rohc_decomp_disable_profile

bool rohc_decomp_enable_profile	(	struct rohc_decomp *const	decomp,
		const rohc_profile_t	profile
	)

Enable a decompression profile for a decompressor.

Enable a decompression profiles for a decompressor.

The ROHC decompressor does not use the decompression profiles that are not enabled. Thus not enabling a profile might cause the decompressor to reject streams. Decompression will always fail if no profile at all is enabled.

If the profile is already enabled, nothing is performed and success is reported.

Parameters

decomp	The ROHC decompressor
profile	The profile to enable

Returns

true if the profile exists, false if the profile does not exist

Example:

        struct rohc_decomp *decompressor;       /* the ROHC decompressor */

...

        if(!rohc_decomp_enable_profile(decompressor, ROHC_PROFILE_UNCOMPRESSED))
        {
                fprintf(stderr, "failed to enable the Uncompressed profile\n");
                goto release_decompressor;
        }
        if(!rohc_decomp_enable_profile(decompressor, ROHC_PROFILE_IP))
        {
                fprintf(stderr, "failed to enable the IP-only profile\n");
                goto release_decompressor;
        }

...

See also

rohc_decomp_enable_profiles

rohc_decomp_disable_profile

rohc_decomp_disable_profiles

bool rohc_decomp_enable_profiles	(	struct rohc_decomp *const	decomp,
			...
	)

Enable several decompression profiles for a decompressor.

Enable several decompression profiles for a decompressor. The list of profiles to enable shall stop with -1.

The ROHC decompressor does not use the decompression profiles that are not enabled. Thus not enabling a profile might cause the decompressor to reject streams. Decompression will always fail if no profile at all is enabled.

If one or more of the profiles are already enabled, nothing is performed and success is reported.

Parameters

decomp	The ROHC decompressor
...	The sequence of decompression profiles to enable, the sequence shall be terminated by -1

Returns

true if all of the profiles exist, false if at least one of the profiles does not exist

Example:

        struct rohc_decomp *decompressor;       /* the ROHC decompressor */

...

        if(!rohc_decomp_enable_profiles(decompressor, ROHC_PROFILE_UDP,
                                        ROHC_PROFILE_UDPLITE, -1))
        {
                fprintf(stderr, "failed to enable the IP/UDP and IP/UDP-Lite "
                        "profiles\n");
                goto release_decompressor;
        }

...

See also

rohc_decomp_enable_profile

rohc_decomp_disable_profile

rohc_decomp_disable_profiles

void rohc_decomp_free

(

struct rohc_decomp *const

decomp

)

Destroy the given ROHC decompressor.

Destroy a ROHC decompressor that was successfully created with rohc_decomp_new2

Parameters

decomp

The decompressor to destroy

Example:

        struct rohc_decomp *decompressor;       /* the ROHC decompressor */

...

        /* Create a ROHC decompressor to operate:
         *  - with large CIDs,
         *  - with the maximum of 5 streams (MAX_CID = 4),
         *  - in Unidirectional mode (U-mode).
         */

        decompressor = rohc_decomp_new2(ROHC_LARGE_CID, 4, ROHC_U_MODE);
        if(decompressor == NULL)
        {
                fprintf(stderr, "failed create the ROHC decompressor\n");
                goto error;
        }

...

        rohc_decomp_free(decompressor);

See also

rohc_decomp_new2

bool rohc_decomp_get_cid_type	(	const struct rohc_decomp *const	decomp,
		rohc_cid_type_t *const	cid_type
	)

Get the CID type that the decompressor uses.

Get the CID type that the decompressor currently uses.

Parameters

	decomp	The ROHC decompressor
[out]	cid_type	The current CID type among ROHC_SMALL_CID and ROHC_LARGE_CID

Returns

true if the CID type was successfully retrieved, false otherwise

bool rohc_decomp_get_context_info	(	const struct rohc_decomp *const	decomp,
		const rohc_cid_t	cid,
		rohc_decomp_context_info_t *const	info
	)

Get some information about the given decompression context.

Get some information about the given decompression context.

To use the function, call it with a pointer on a pre-allocated rohc_decomp_context_info_t structure with the version_major and version_minor fields set to one of the following supported versions:

• Major 0, minor 0

See rohc_decomp_context_info_t for details about fields that are supported in the above versions.

Parameters

	decomp	The ROHC decompressor to get information from
	cid	The Context ID to get information for
[in,out]	info	The structure where information will be stored

Returns

true in case of success, false otherwise

See also

rohc_decomp_context_info_t

bool rohc_decomp_get_general_info	(	const struct rohc_decomp *const	decomp,
		rohc_decomp_general_info_t *const	info
	)

Get some general information about the decompressor.

Get some general information about the decompressor.

To use the function, call it with a pointer on a pre-allocated rohc_decomp_general_info_t structure with the version_major and version_minor fields set to one of the following supported versions:

• Major 0, minor 0

See the rohc_decomp_general_info_t structure for details about fields that are supported in the above versions.

Parameters

	decomp	The ROHC decompressor to get information from
[in,out]	info	The structure where information will be stored

Returns

true in case of success, false otherwise

See also

rohc_decomp_general_info_t

bool rohc_decomp_get_last_packet_info	(	const struct rohc_decomp *const	decomp,
		rohc_decomp_last_packet_info_t *const	info
	)

Get some information about the last decompressed packet.

Get some information about the last decompressed packet.

To use the function, call it with a pointer on a pre-allocated rohc_decomp_last_packet_info_t structure with the version_major and version_minor fields set to one of the following supported versions:

• Major 0, minor 0
• Major 0, minor 1

See rohc_decomp_last_packet_info_t for details about fields that are supported in the above versions.

Parameters

	decomp	The ROHC decompressor to get information from
[in,out]	info	The structure where information will be stored

Returns

true in case of success, false otherwise

See also

rohc_decomp_last_packet_info_t

bool rohc_decomp_get_max_cid	(	const struct rohc_decomp *const	decomp,
		size_t *const	max_cid
	)

Get the maximal CID value the decompressor uses.

Get the maximal CID value the decompressor uses, ie. the MAX_CID parameter defined in RFC 3095.

Parameters

	decomp	The ROHC decompressor
[out]	max_cid	The current maximal CID value

Returns

true if MAX_CID was successfully retrieved, false otherwise

bool rohc_decomp_get_mrru	(	const struct rohc_decomp *const	decomp,
		size_t *const	mrru
	)

Get the Maximum Reconstructed Reception Unit (MRRU).

Get the current Maximum Reconstructed Reception Unit (MRRU).

The MRRU is the largest cumulative length (in bytes) of the ROHC segments that are parts of the same ROHC packet. In short, the ROHC decompressor does not expect to reassemble ROHC segments whose total length is larger than MRRU. So, the ROHC compressor shall not segment ROHC packets greater than the MRRU.

The MRRU value must be in range [0 ; ROHC_MAX_MRRU]. Remember that the MRRU includes the 32-bit CRC that protects it. If MRRU value is 0, segmentation is disabled.

If segmentation is enabled and used by the compressor, the function rohc_decompress3 will return ROHC_OK and one empty uncompressed packet upon decompression until the last segment is received (or a non-segment is received). Decompressed data will be returned at that time.

Parameters

	decomp	The ROHC decompressor
[out]	mrru	The current MRRU value (in bytes)

Returns

true if MRRU was successfully retrieved, false otherwise

See also

rohc_decomp_set_mrru

rohc_decompress3

rohc_comp_set_mrru

rohc_comp_get_mrru

bool rohc_decomp_get_prtt	(	const struct rohc_decomp *const	decomp,
		size_t *const	prtt
	)

Get the number of packets sent during one Round-Trip Time (RTT).

Get the maximum number of packets sent in worst case by the remote ROHC compressor for one given stream (ie. one compression/decompression context) during one Round-Trip Time (RTT).

The number of packets sent by the remote ROHC compressor is used to estimate how many SN bits those feedbacks shall transmit to avoid any ambiguity at compressor about the ROHC packet that is (n)acknowledged by the decompressor.

The pRTT value must be in range [0 ; SIZE_MAX/2[. If set to 0, all SN bits are always transmitted.

The default value is 50 packets / RTT, ie. a RTT of 1 second with one packet transmitted every 20 milliseconds (classic VoIP stream). If your network streams and conditions differ, change the default value.

Parameters

	decomp	The ROHC decompressor
[out]	prtt	The number of packets sent during one RTT

Returns

true if pRTT was successfully retrieved, false otherwise

See also

rohc_decomp_set_prtt

rohc_decompress3

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
	)

Get the rate limits for feedbacks currently configured.

Get the rate limits for positive feedbacks (ACK) and negative feedbacks (NACK and STATIC-NACK).

There are 3 different rate limits:

• the rate limit to avoid sending the same type of feedback too often: it applies to all feedback types (ACK, NACK, STATIC-NACK) and it is specified by the parameters k and n ;
• the rate limit to avoid sending NACKs too quickly after a sporadic CRC failure: it is specified by the parameters k_1 and n_1 ;
• the rate limit to avoid sending STATIC-NACKs too quickly after a sporadic CRC failure: it is specified by the parameters k_2 and n_2 ;

In all 3 cases above, the k/k_1/k_2 and n/n_1/n_2 parameters define 3 ratios of packets:

• a feedback is sent every k packets out of n packets that cause the same feedback type to be sent ;
• a NACK is not sent before k_1 packets out of n_1 packets failed because of a CRC failure in the Full Context state ;
• a STATIC-NACK is not sent before k_1 packets out of n_1 packets failed because of a CRC failure in the Static Context state ;

The default values are:

• k = 1 and n = default pRTT (see rohc_decomp_set_prtt for details)
• k_1 = 30 and n_1 = 100, ie. 30%
• k_2 = 30 and n_2 = 100, ie. 30%

If your network streams and conditions differ, change the default value.

Parameters

	decomp	The ROHC decompressor
[out]	k	The k rate-limit parameter to avoid sending feedback too often
[out]	n	The n rate-limit parameter to avoid sending feedback too often
[out]	k_1	The k_1 rate-limit param. to avoid sending NACKs too quickly
[out]	n_1	The n_1 rate-limit param. to avoid sending NACKs too quickly
[out]	k_2	The k_2 rate-limit param. to avoid sending STATIC-NACKs too quickly
[out]	n_2	The n_2 rate-limit param. to avoid sending STATIC-NACKs too quickly

Returns

true if rate-limits were successfully retrieved, false otherwise

See also

rohc_decomp_set_rate_limits

rohc_decomp_set_prtt

rohc_decomp_get_prtt

rohc_decompress3

const char* rohc_decomp_get_state_descr

(

const rohc_decomp_state_t

state

)

Give a description for the given ROHC decompression context state.

Give a description for the given ROHC decompression context state.

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 decompression context states used by the library. If unsure, ask on the mailing list.

Parameters

state

The decompression context state to get a description for

Returns

A string that describes the given decompression context state

struct rohc_decomp* rohc_decomp_new2	(	const rohc_cid_type_t	cid_type,
		const rohc_cid_t	max_cid,
		const rohc_mode_t	mode
	)

Create a new ROHC decompressor.

Create a new ROHC decompressor with the given type of CIDs, MAX_CID, and operational mode.

Parameters

cid_type	The type of Context IDs (CID) that the ROHC decompressor shall operate with. Accepted values are: ROHC_SMALL_CID for small CIDs ROHC_LARGE_CID for large CIDs
max_cid	The maximum value that the ROHC decompressor should use for context IDs (CID). As CIDs starts with value 0, the number of contexts is max_cid + 1. Accepted values are: [0, ROHC_SMALL_CID_MAX] if cid_type is ROHC_SMALL_CID [0, ROHC_LARGE_CID_MAX] if cid_type is ROHC_LARGE_CID
mode	The operational mode that the ROHC decompressor shall target. Accepted values are: ROHC_U_MODE for the Unidirectional mode, ROHC_O_MODE for the Bidirectional Optimistic mode, ROHC_R_MODE for the Bidirectional Reliable mode is not supported yet: specifying ROHC_R_MODE is an error.

Returns

The created decompressor if successful, NULL if creation failed

Warning

Don't forget to free decompressor memory with rohc_decomp_free if rohc_decomp_new2 succeeded

Example:

        struct rohc_decomp *decompressor;       /* the ROHC decompressor */

...

        /* Create a ROHC decompressor to operate:
         *  - with large CIDs,
         *  - with the maximum of 5 streams (MAX_CID = 4),
         *  - in Unidirectional mode (U-mode).
         */

        decompressor = rohc_decomp_new2(ROHC_LARGE_CID, 4, ROHC_U_MODE);
        if(decompressor == NULL)
        {
                fprintf(stderr, "failed create the ROHC decompressor\n");
                goto error;
        }

...

        rohc_decomp_free(decompressor);

See also

rohc_decomp_free

rohc_decompress3

rohc_decomp_set_traces_cb2

rohc_decomp_enable_profiles

rohc_decomp_enable_profile

rohc_decomp_disable_profiles

rohc_decomp_disable_profile

rohc_decomp_set_mrru

rohc_decomp_set_features

bool rohc_decomp_profile_enabled	(	const struct rohc_decomp *const	decomp,
		const rohc_profile_t	profile
	)

Is the given decompression profile enabled for a decompressor?

Is the given decompression profile enabled or disabled for a decompressor?

Parameters

decomp	The ROHC decompressor
profile	The profile to ask status for

Returns

Possible return values:

• true if the profile exists and is enabled,
• false if the decompressor is not valid, the profile does not exist, or the profile is disabled

See also

rohc_decomp_enable_profile

rohc_decomp_enable_profiles

rohc_decomp_disable_profile

rohc_decomp_disable_profiles

bool rohc_decomp_set_features	(	struct rohc_decomp *const	decomp,
		const rohc_decomp_features_t	features
	)

Enable/disable features for ROHC decompressor.

Enable/disable features for ROHC decompressor. Features control whether mechanisms defined as optional by RFCs are enabled or not.

Available features are listed by rohc_decomp_features_t. They may be combined by XOR'ing them together.

Warning

Changing the feature set while library is used is not supported

Parameters

decomp	The ROHC decompressor
features	The feature set to enable/disable

Returns

true if the feature set was successfully enabled/disabled, false if a problem occurred

See also

rohc_decomp_features_t

bool rohc_decomp_set_mrru	(	struct rohc_decomp *const	decomp,
		const size_t	mrru
	)

Set the Maximum Reconstructed Reception Unit (MRRU).

Set the Maximum Reconstructed Reception Unit (MRRU).

The MRRU is the largest cumulative length (in bytes) of the ROHC segments that are parts of the same ROHC packet. In short, the ROHC decompressor does not expect to reassemble ROHC segments whose total length is larger than MRRU. So, the ROHC compressor shall not segment ROHC packets greater than the MRRU.

The MRRU value must be in range [0 ; ROHC_MAX_MRRU]. Remember that the MRRU includes the 32-bit CRC that protects it. If set to 0, segmentation is disabled as no segment headers are allowed on the channel. Every received segment will be dropped.

If segmentation is enabled and used by the compressor, the function rohc_decompress3 will return ROHC_OK and one empty uncompressed packet upon decompression until the last segment is received (or a non-segment is received). Decompressed data will be returned at that time.

Warning

Changing the MRRU value while library is used may lead to destruction of the current RRU.

Parameters

decomp	The ROHC decompressor
mrru	The new MRRU value (in bytes)

Returns

true if the MRRU was successfully set, false otherwise

Example:

        struct rohc_decomp *decomp;

size_t mrru = 500;
...

        /* create the ROHC decompressor in uni-directional mode */
        decomp = rohc_decomp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX, ROHC_U_MODE);
        if(decomp == NULL)
        {
                fprintf(stderr, "failed to create the ROHC decompressor\n");
                goto destroy_comp;
        }

...

        /* set the MRRU at decompressor */
        if(!rohc_decomp_set_mrru(decomp, mrru))
        {
                fprintf(stderr, "failed to set the MRRU at decompressor\n");
                goto destroy_decomp;
        }

...

See also

rohc_decomp_get_mrru

rohc_decompress3

rohc_comp_set_mrru

rohc_comp_get_mrru

bool rohc_decomp_set_prtt	(	struct rohc_decomp *const	decomp,
		const size_t	prtt
	)

Set the number of packets sent during one Round-Trip Time (RTT).

Set the maximum number of packets sent in worst case by the remote ROHC compressor for one given stream (ie. one compression/decompression context) during one Round-Trip Time (RTT).

The number of packets sent by the remote ROHC compressor is used to estimate how many SN bits those feedbacks shall transmit to avoid any ambiguity at compressor about the ROHC packet that is (n)acknowledged by the decompressor.

The pRTT value must be in range [0 ; SIZE_MAX/2[. If set to 0, all SN bits are always transmitted.

The default value is 50 packets / RTT, ie. a RTT of 1 second with one packet transmitted every 20 milliseconds (classic VoIP stream). If your network streams and conditions differ, change the default value.

Parameters

decomp	The ROHC decompressor
prtt	The number of packets sent during one RTT

Returns

true if the new value was successfully set, false otherwise

Example:

        struct rohc_decomp *decomp;

rohc_cid_type_t cid_type = ROHC_SMALL_CID;
rohc_cid_t max_cid = ROHC_SMALL_CID_MAX;
...

        /* create the ROHC decompressor in bi-directional mode */
        decomp = rohc_decomp_new2(cid_type, max_cid, ROHC_O_MODE);
        if(decomp == NULL)
        {
                fprintf(stderr, "failed to create the ROHC decompressor\n");
                goto destroy_comp;
        }

...

                if(!rohc_decomp_set_prtt(decomp, 0))
                {
                        fprintf(stderr, "failed to configure decompressor pRTT\n");
                        goto destroy_decomp;
                }

...

See also

rohc_decomp_get_prtt

rohc_decompress3

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
	)

Set the rate limits for feedbacks.

Set the rate limits for positive feedbacks (ACK) and negative feedbacks (NACK and STATIC-NACK).

There are 3 different rate limits:

• the rate limit to avoid sending the same type of feedback too often: it applies to all feedback types (ACK, NACK, STATIC-NACK) and it is specified by the parameters k and n ;
• the rate limit to avoid sending NACKs too quickly after a sporadic CRC failure: it is specified by the parameters k_1 and n_1 ;
• the rate limit to avoid sending STATIC-NACKs too quickly after a sporadic CRC failure: it is specified by the parameters k_2 and n_2 ;

In all 3 cases above, the k/k_1/k_2 and n/n_1/n_2 parameters define 3 ratios of packets:

• a feedback is sent every k packets out of n packets that cause the same feedback type to be sent ;
• a NACK is not sent before k_1 packets out of n_1 packets failed because of a CRC failure in the Full Context state ;
• a STATIC-NACK is not sent before k_1 packets out of n_1 packets failed because of a CRC failure in the Static Context state ;

The default values are:

• k = 1 and n = default pRTT (see rohc_decomp_set_prtt for details)
• k_1 = 30 and n_1 = 100, ie. 30%
• k_2 = 30 and n_2 = 100, ie. 30%

If your network streams and conditions differ, change the default value.

The n/n_1/n_2 values shall not be zero.

Parameters

decomp	The ROHC decompressor
k	The k rate-limit parameter to avoid sending feedback too often
n	The n rate-limit parameter to avoid sending feedback too often
k_1	The k_1 rate-limit parameter to avoid sending NACKs too quickly
n_1	The n_1 rate-limit parameter to avoid sending NACKs too quickly
k_2	The k_2 rate-limit parameter to avoid sending STATIC-NACKs too quickly
n_2	The n_2 rate-limit parameter to avoid sending STATIC-NACKs too quickly

Returns

true if the new values were successfully set, false otherwise

Example:

        struct rohc_decomp *decomp;

...

        /* create the ROHC decompressor in unidirectional mode */
        decomp = rohc_decomp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX, ROHC_U_MODE);
        if(decomp == NULL)
        {
                fprintf(stderr, "failed to create the ROHC decompressor\n");
                goto destroy_comp;
        }

...

        /* increase the default rate limits */
        if(!rohc_decomp_set_rate_limits(decomp, 4, 100, 20, 100, 20, 100))
        {
                fprintf(stderr, "failed to increase the default rate limits\n");
                goto destroy_decomp;
        }

...

See also

rohc_decomp_get_rate_limits

rohc_decomp_set_prtt

rohc_decomp_get_prtt

rohc_decompress3

bool rohc_decomp_set_traces_cb2	(	struct rohc_decomp *	decomp,
		rohc_trace_callback2_t	callback,
		void *const	priv_ctxt
	)

Set the callback function used to manage traces in decompressor.

Set the user-defined callback function used to manage traces in the decompressor.

The function will be called by the ROHC library every time it wants to print something related to decompression, 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...).

Warning

The callback can not be modified after library initialization

Parameters

decomp	The ROHC decompressor
callback	Two possible cases: The callback function used to manage traces NULL to remove the previous callback
priv_ctxt	An optional private context, may be NULL

Returns

true on success, false otherwise

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
	)

Decompress the given ROHC packet into one uncompressed packet.

Decompress the given ROHC packet into an uncompressed packet. The decompression always returns ROHC_OK in case of success. The caller shall however be ready to handle several cases:

• the uncompressed packet uncomp_packet might be empty if the ROHC packet contained only feedback data or if the ROHC packet was not a final segment
• the received feedback rcvd_feedback might be empty if the ROHC packet doesn't contain at least one feedback item

If feedback_send is not NULL, the decompression may return some feedback information on it. In such a case, the caller is responsible to send it to the compressor through any feedback channel.

Time-related features in the ROHC protocol: set the rohc_packet.time parameter to 0 if arrival time of the ROHC packet is unknown or to disable the time-related features in the ROHC protocol.

Parameters

	decomp	The ROHC decompressor
	rohc_packet	The compressed packet to decompress
[out]	uncomp_packet	The resulting uncompressed packet
[out]	rcvd_feedback	The feedback received from the remote peer for the same-side associated ROHC compressor through the feedback channel: If NULL, ignore the received feedback data If not NULL, store the received feedback in at the given address
[out]	feedback_send	The feedback to be transmitted to the remote compressor through the feedback channel: If NULL, the decompression won't generate feedback information for its compressor If not NULL, may store the generated feedback at the given address

Returns

Possible return values:

• ROHC_STATUS_OK if a decompressed packet is returned
• ROHC_STATUS_NO_CONTEXT if no decompression context matches the CID stored in the given ROHC packet and the ROHC packet is not an IR packet
• ROHC_STATUS_OUTPUT_TOO_SMALL if the output buffer is too small for the compressed packet
• ROHC_STATUS_MALFORMED if the decompression failed because the ROHC packet is malformed
• ROHC_STATUS_BAD_CRC if the CRC detected a transmission or decompression problem
• ROHC_STATUS_ERROR if another problem occurred

Example #1:

        struct rohc_decomp *decompressor;       /* the ROHC decompressor */

        /* the buffer that will contain the ROHC packet to decompress */
        unsigned char rohc_buffer[BUFFER_SIZE];
        struct rohc_buf rohc_packet = rohc_buf_init_empty(rohc_buffer, BUFFER_SIZE);
        /* the buffer that will contain the resulting IP packet */
        unsigned char ip_buffer[BUFFER_SIZE];
        struct rohc_buf ip_packet = rohc_buf_init_empty(ip_buffer, BUFFER_SIZE);
        /* we do not want to handle feedback in this simple example */
        struct rohc_buf *rcvd_feedback = NULL;
        struct rohc_buf *feedback_send = NULL;

...

        status = rohc_decompress3(decompressor, rohc_packet, &ip_packet,
                                  rcvd_feedback, feedback_send);

        if(status == ROHC_STATUS_OK)
        {
                /* decompression is successful */
                if(!rohc_buf_is_empty(ip_packet))
                {
                        /* ip_packet.len bytes of decompressed IP data available in
                         * ip_packet: dump the IP packet on the standard output */
                        printf("IP packet resulting from the ROHC decompression:\n");
                        dump_packet(ip_packet);
                }
                else
                {
                        /* no IP packet was decompressed because of ROHC segmentation or
                         * feedback-only packet:
                         *  - the ROHC packet was a non-final segment, so at least another
                         *    ROHC segment is required to be able to decompress the full
                         *    ROHC packet
                         *  - the ROHC packet was a feedback-only packet, it contained only
                         *    feedback information, so there was nothing to decompress */
                        printf("no IP packet decompressed");
                }
        }
        else
        {
                /* failure: decompressor failed to decompress the ROHC packet */
                fprintf(stderr, "decompression of fake ROHC packet failed\n");

        }

See also

rohc_decomp_set_mrru