ROHC compression/decompression library
Data Structures | Enumerations | Functions
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_decomprohc_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

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)

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
decompThe ROHC decompressor
profileThe 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
decompThe 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
decompThe ROHC decompressor
profileThe profile to enable
Returns
true if the profile exists, false if the profile does not exist
Example:
struct rohc_decomp *decompressor; /* the ROHC decompressor */
1 ...
{
fprintf(stderr, "failed to enable the Uncompressed profile\n");
goto release_decompressor;
}
{
fprintf(stderr, "failed to enable the IP-only profile\n");
goto release_decompressor;
}
1 ...
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
decompThe 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 */
1 ...
{
fprintf(stderr, "failed to enable the IP/UDP and IP/UDP-Lite "
"profiles\n");
goto release_decompressor;
}
1 ...
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
decompThe decompressor to destroy
Example:
struct rohc_decomp *decompressor; /* the ROHC decompressor */
1 ...
/* Create a ROHC decompressor to operate:
* - with large CIDs,
* - with the maximum of 5 streams (MAX_CID = 4),
* - in Unidirectional mode (U-mode).
*/
if(decompressor == NULL)
{
fprintf(stderr, "failed create the ROHC decompressor\n");
goto error;
}
1 ...
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
decompThe ROHC decompressor
[out]cid_typeThe 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
decompThe ROHC decompressor to get information from
cidThe Context ID to get information for
[in,out]infoThe 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
decompThe ROHC decompressor to get information from
[in,out]infoThe 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
decompThe ROHC decompressor to get information from
[in,out]infoThe 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
decompThe ROHC decompressor
[out]max_cidThe 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
decompThe ROHC decompressor
[out]mrruThe 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
decompThe ROHC decompressor
[out]prttThe 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
decompThe ROHC decompressor
[out]kThe k rate-limit parameter to avoid sending feedback too often
[out]nThe n rate-limit parameter to avoid sending feedback too often
[out]k_1The k_1 rate-limit param. to avoid sending NACKs too quickly
[out]n_1The n_1 rate-limit param. to avoid sending NACKs too quickly
[out]k_2The k_2 rate-limit param. to avoid sending STATIC-NACKs too quickly
[out]n_2The 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
stateThe 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_typeThe type of Context IDs (CID) that the ROHC decompressor shall operate with.
Accepted values are:
max_cidThe 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:
modeThe operational mode that the ROHC decompressor shall target.
Accepted values are:
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 */
1 ...
/* Create a ROHC decompressor to operate:
* - with large CIDs,
* - with the maximum of 5 streams (MAX_CID = 4),
* - in Unidirectional mode (U-mode).
*/
if(decompressor == NULL)
{
fprintf(stderr, "failed create the ROHC decompressor\n");
goto error;
}
1 ...
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
decompThe ROHC decompressor
profileThe 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
decompThe ROHC decompressor
featuresThe 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
decompThe ROHC decompressor
mrruThe new MRRU value (in bytes)
Returns
true if the MRRU was successfully set, false otherwise
Example:
struct rohc_decomp *decomp;
1 size_t mrru = 500;
2 ...
/* create the ROHC decompressor in uni-directional mode */
if(decomp == NULL)
{
fprintf(stderr, "failed to create the ROHC decompressor\n");
goto destroy_comp;
}
1 ...
/* 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;
}
1 ...
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
decompThe ROHC decompressor
prttThe number of packets sent during one RTT
Returns
true if the new value was successfully set, false otherwise
Example:
struct rohc_decomp *decomp;
1 rohc_cid_type_t cid_type = ROHC_SMALL_CID;
2 rohc_cid_t max_cid = ROHC_SMALL_CID_MAX;
3 ...
/* 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;
}
1 ...
if(!rohc_decomp_set_prtt(decomp, 0))
{
fprintf(stderr, "failed to configure decompressor pRTT\n");
goto destroy_decomp;
}
1 ...
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
decompThe ROHC decompressor
kThe k rate-limit parameter to avoid sending feedback too often
nThe n rate-limit parameter to avoid sending feedback too often
k_1The k_1 rate-limit parameter to avoid sending NACKs too quickly
n_1The n_1 rate-limit parameter to avoid sending NACKs too quickly
k_2The k_2 rate-limit parameter to avoid sending STATIC-NACKs too quickly
n_2The 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;
1 ...
/* create the ROHC decompressor in unidirectional mode */
if(decomp == NULL)
{
fprintf(stderr, "failed to create the ROHC decompressor\n");
goto destroy_comp;
}
1 ...
/* 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;
}
1 ...
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
decompThe ROHC decompressor
callbackTwo possible cases:
  • The callback function used to manage traces
  • NULL to remove the previous callback
priv_ctxtAn 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
decompThe ROHC decompressor
rohc_packetThe compressed packet to decompress
[out]uncomp_packetThe resulting uncompressed packet
[out]rcvd_feedbackThe 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_sendThe 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:
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;
1 ...
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