ROHC compression/decompression library
Data Structures | Typedefs | Enumerations | Functions
The ROHC compression API

Data Structures

struct  rohc_comp_last_packet_info2_t
 Some information about the last compressed packet. More...
 
struct  rohc_comp_general_info_t
 Some general information about the compressor. More...
 

Typedefs

typedef bool(* rohc_rtp_detection_callback_t) (const unsigned char *const ip, const unsigned char *const udp, const unsigned char *const payload, const unsigned int payload_size, void *const rtp_private)
 The prototype of the RTP detection callback. More...
 
typedef int(* rohc_comp_random_cb_t) (const struct rohc_comp *const comp, void *const user_context)
 The prototype of the callback for random numbers. More...
 

Enumerations

enum  rohc_reordering_offset_t { ROHC_REORDERING_NONE = 0, ROHC_REORDERING_QUARTER = 1, ROHC_REORDERING_HALF = 2, ROHC_REORDERING_THREEQUARTERS = 3 }
 The different values of reordering offset. More...
 
enum  rohc_comp_state_t {
  ROHC_COMP_STATE_UNKNOWN = 0, ROHC_COMP_STATE_IR = 1, ROHC_COMP_STATE_FO = 2, ROHC_COMP_STATE_SO = 3,
  ROHC_COMP_STATE_CR = 4
}
 The different ROHC compressor states. More...
 
enum  rohc_comp_features_t {
  ROHC_COMP_FEATURE_NONE = 0, ROHC_COMP_FEATURE_COMPAT_1_6_x = (1 << 0), ROHC_COMP_FEATURE_NO_IP_CHECKSUMS = (1 << 2), ROHC_COMP_FEATURE_DUMP_PACKETS = (1 << 3),
  ROHC_COMP_FEATURE_TIME_BASED_REFRESHES = (1 << 4)
}
 The different features of the ROHC compressor. More...
 

Functions

struct rohc_comprohc_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)
 Create a new ROHC compressor. More...
 
void rohc_comp_free (struct rohc_comp *const comp)
 Destroy the given ROHC compressor. More...
 
bool rohc_comp_set_traces_cb2 (struct rohc_comp *const comp, rohc_trace_callback2_t callback, void *const priv_ctxt)
 Set the callback function used to manage traces in compressor. More...
 
rohc_status_t rohc_compress4 (struct rohc_comp *const comp, const struct rohc_buf uncomp_packet, struct rohc_buf *const rohc_packet)
 Compress the given uncompressed packet into a ROHC packet. More...
 
rohc_status_t rohc_comp_pad (struct rohc_comp *const comp, struct rohc_buf *const rohc_pkt, const size_t min_pkt_len)
 Pad the given ROHC compressed packet. More...
 
rohc_status_t rohc_comp_get_segment2 (struct rohc_comp *const comp, struct rohc_buf *const segment)
 Get the next ROHC segment if any. More...
 
bool rohc_comp_force_contexts_reinit (struct rohc_comp *const comp)
 Force the compressor to re-initialize all its contexts. More...
 
bool rohc_comp_set_wlsb_window_width (struct rohc_comp *const comp, const size_t width)
 Set the window width for the W-LSB encoding scheme. More...
 
bool rohc_comp_set_reorder_ratio (struct rohc_comp *const comp, const rohc_reordering_offset_t reorder_ratio)
 Set the reordering ratio for the W-LSB encoding scheme. More...
 
bool rohc_comp_set_periodic_refreshes (struct rohc_comp *const comp, const size_t ir_timeout, const size_t fo_timeout)
 Set the timeouts in packets for IR and FO periodic refreshes. More...
 
bool rohc_comp_set_periodic_refreshes_time (struct rohc_comp *const comp, const uint64_t ir_timeout, const uint64_t fo_timeout)
 Set the timeouts in ms for IR and FO periodic refreshes. More...
 
bool rohc_comp_set_list_trans_nr (struct rohc_comp *const comp, const size_t list_trans_nr)
 Set the number of uncompressed transmissions for list compression. More...
 
bool rohc_comp_set_rtp_detection_cb (struct rohc_comp *const comp, rohc_rtp_detection_callback_t callback, void *const rtp_private)
 Set the RTP detection callback function. More...
 
bool rohc_comp_profile_enabled (const struct rohc_comp *const comp, const rohc_profile_t profile)
 Is the given compression profile enabled for a compressor? More...
 
bool rohc_comp_enable_profile (struct rohc_comp *const comp, const rohc_profile_t profile)
 Enable a compression profile for a compressor. More...
 
bool rohc_comp_disable_profile (struct rohc_comp *const comp, const rohc_profile_t profile)
 Disable a compression profile for a compressor. More...
 
bool rohc_comp_enable_profiles (struct rohc_comp *const comp,...)
 Enable several compression profiles for a compressor. More...
 
bool rohc_comp_disable_profiles (struct rohc_comp *const comp,...)
 Disable several compression profiles for a compressor. More...
 
bool rohc_comp_set_mrru (struct rohc_comp *const comp, const size_t mrru)
 Set the Maximum Reconstructed Reception Unit (MRRU). More...
 
bool rohc_comp_get_mrru (const struct rohc_comp *const comp, size_t *const mrru)
 Get the Maximum Reconstructed Reception Unit (MRRU). More...
 
bool rohc_comp_get_max_cid (const struct rohc_comp *const comp, size_t *const max_cid)
 Get the maximal CID value the compressor uses. More...
 
bool rohc_comp_get_cid_type (const struct rohc_comp *const comp, rohc_cid_type_t *const cid_type)
 Get the CID type that the compressor uses. More...
 
bool rohc_comp_set_features (struct rohc_comp *const comp, const rohc_comp_features_t features)
 Enable/disable features for ROHC compressor. More...
 
bool rohc_comp_deliver_feedback2 (struct rohc_comp *const comp, const struct rohc_buf feedback)
 Deliver a feedback packet to the compressor. More...
 
bool rohc_comp_get_last_packet_info2 (const struct rohc_comp *const comp, rohc_comp_last_packet_info2_t *const info)
 Get some information about the last compressed packet. More...
 
bool rohc_comp_get_general_info (const struct rohc_comp *const comp, rohc_comp_general_info_t *const info)
 Get some general information about the compressor. More...
 
const char * rohc_comp_get_state_descr (const rohc_comp_state_t state)
 Give a description for the given ROHC compression context state. More...
 

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

Typedef Documentation

◆ rohc_comp_random_cb_t

typedef int(* rohc_comp_random_cb_t) (const struct rohc_comp *const comp, void *const user_context)

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

Parameters
compThe ROHC compressor
user_contextThe context given by the user when he/she called the rohc_comp_new2 function, may be NULL.
See also
rohc_comp_new2

◆ rohc_rtp_detection_callback_t

typedef bool(* rohc_rtp_detection_callback_t) (const unsigned char *const ip, const unsigned char *const udp, const unsigned char *const payload, const unsigned int payload_size, void *const rtp_private)

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

Parameters
ipThe innermost IP packet
udpThe UDP header of the packet
payloadThe UDP payload of the packet
payload_sizeThe size of the UDP payload (in bytes)
rtp_privateA pointer to a memory area to be used by the callback function, may be NULL.
Returns
true if the packet is an RTP packet, false otherwise
See also
rohc_comp_set_rtp_detection_cb

Enumeration Type Documentation

◆ rohc_comp_features_t

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.

See also
rohc_comp_set_features
Enumerator
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

◆ rohc_comp_state_t

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.

See also
rohc_comp_get_state_descr
Enumerator
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

◆ rohc_reordering_offset_t

The different values of reordering offset.

Enumerator
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

Function Documentation

◆ rohc_comp_deliver_feedback2()

bool rohc_comp_deliver_feedback2 ( struct rohc_comp *const  comp,
const struct rohc_buf  feedback 
)

Deliver a feedback packet to the compressor.

When feedback data is received by a decompressor, this function may be called to deliver the feedback data to the corresponding profile/context on the same-side associated compressor.

Parameters
compThe ROHC compressor
feedbackThe feedback data
Returns
true if the feedback was successfully taken into account, false if the feedback could not be taken into account

◆ rohc_comp_disable_profile()

bool rohc_comp_disable_profile ( struct rohc_comp *const  comp,
const rohc_profile_t  profile 
)

Disable a compression profile for a compressor.

Disable a compression profile for a compressor.

The ROHC compressor does not use the compression profiles that were disabled. Thus disabling a profile might affect compression performances. Compression will fail if no profile at all is enabled.

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

Parameters
compThe ROHC compressor
profileThe profile to disable
Returns
true if the profile exists, false if the profile does not exist
See also
rohc_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profiles

◆ rohc_comp_disable_profiles()

bool rohc_comp_disable_profiles ( struct rohc_comp *const  comp,
  ... 
)

Disable several compression profiles for a compressor.

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

The ROHC compressor does not use the compression profiles that were disabled. Thus disabling a profile might affect compression performances. Compression will 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
compThe ROHC compressor
...The sequence of compression 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_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profile

◆ rohc_comp_enable_profile()

bool rohc_comp_enable_profile ( struct rohc_comp *const  comp,
const rohc_profile_t  profile 
)

Enable a compression profile for a compressor.

Enable a compression profiles for a compressor.

The ROHC compressor does not use the compression profiles that are not enabled. Thus not enabling a profile might affect compression performances. Compression will fail if no profile at all is enabled.

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

The ROHCv1 and ROHCv2 profiles are incompatible. The same profile cannot be enabled in both versions 1 and 2.

Parameters
compThe ROHC compressor
profileThe profile to enable
Returns
true if the profile exists, false if the profile does not exist or a similar profile is already enabled
Example:
struct rohc_comp *compressor; /* the ROHC compressor */
...
{
fprintf(stderr, "failed to enable the Uncompressed profile\n");
goto release_compressor;
}
{
fprintf(stderr, "failed to enable the IP-only profile\n");
goto release_compressor;
}
...
See also
rohc_comp_enable_profiles
rohc_comp_disable_profile
rohc_comp_disable_profiles

◆ rohc_comp_enable_profiles()

bool rohc_comp_enable_profiles ( struct rohc_comp *const  comp,
  ... 
)

Enable several compression profiles for a compressor.

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

The ROHC compressor does not use the compression profiles that are not enabled. Thus not enabling a profile might affect compression performances. Compression will 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
compThe ROHC compressor
...The sequence of compression 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_comp *compressor; /* the ROHC compressor */
...
{
fprintf(stderr, "failed to enable the IP/UDP and IP/UDP-Lite "
"profiles\n");
goto release_compressor;
}
...
See also
rohc_comp_enable_profile
rohc_comp_disable_profile
rohc_comp_disable_profiles

◆ rohc_comp_force_contexts_reinit()

bool rohc_comp_force_contexts_reinit ( struct rohc_comp *const  comp)

Force the compressor to re-initialize all its contexts.

Make all contexts restart their initialization with decompressor, ie. they go in the lowest compression state. This function can be used once the ROHC channel is established again after an interruption.

The function implements the CONTEXT_REINITIALIZATION signal described by RFC 3095 at §6.3.1 as:

   CONTEXT_REINITIALIZATION -- signal
   This parameter triggers a reinitialization of the entire context at
   the decompressor, both the static and the dynamic part.  The
   compressor MUST, when CONTEXT_REINITIALIZATION is triggered, back off
   to the IR state and fully reinitialize the context by sending IR
   packets with both the static and dynamic chains covering the entire
   uncompressed headers until it is reasonably confident that the
   decompressor contexts are reinitialized.  The context
   reinitialization MUST be done for all contexts at the compressor.
   This parameter may for instance be used to do context relocation at,
   e.g., a cellular handover that results in a change of compression
   point in the radio access network.
Parameters
compThe ROHC compressor
Returns
true in case of success, false otherwise

◆ rohc_comp_free()

void rohc_comp_free ( struct rohc_comp *const  comp)

Destroy the given ROHC compressor.

Destroy a ROHC compressor that was successfully created with rohc_comp_new2

Parameters
compThe ROHC compressor to destroy
Example:
struct rohc_comp *compressor; /* the ROHC compressor */
...
gen_random_num, NULL);
if(compressor == NULL)
{
fprintf(stderr, "failed create the ROHC compressor\n");
goto error;
}
...
rohc_comp_free(compressor);
See also
rohc_comp_new2

◆ rohc_comp_get_cid_type()

bool rohc_comp_get_cid_type ( const struct rohc_comp *const  comp,
rohc_cid_type_t *const  cid_type 
)

Get the CID type that the compressor uses.

Get the CID type that the compressor currently uses.

Parameters
compThe ROHC compressor
[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

◆ rohc_comp_get_general_info()

bool rohc_comp_get_general_info ( const struct rohc_comp *const  comp,
rohc_comp_general_info_t *const  info 
)

Get some general information about the compressor.

Get some general information about the compressor.

To use the function, call it with a pointer on a pre-allocated rohc_comp_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_comp_general_info_t structure for details about fields that are supported in the above versions.

Parameters
compThe ROHC compressor to get information from
[in,out]infoThe structure where information will be stored
Returns
true in case of success, false otherwise
See also
rohc_comp_general_info_t

◆ rohc_comp_get_last_packet_info2()

bool rohc_comp_get_last_packet_info2 ( const struct rohc_comp *const  comp,
rohc_comp_last_packet_info2_t *const  info 
)

Get some information about the last compressed packet.

Get some information about the last compressed packet.

To use the function, call it with a pointer on a pre-allocated rohc_comp_last_packet_info2_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_comp_last_packet_info2_t structure for details about fields that are supported in the above versions.

Parameters
compThe ROHC compressor to get information from
[in,out]infoThe structure where information will be stored
Returns
true in case of success, false otherwise
See also
rohc_comp_last_packet_info2_t

◆ rohc_comp_get_max_cid()

bool rohc_comp_get_max_cid ( const struct rohc_comp *const  comp,
size_t *const  max_cid 
)

Get the maximal CID value the compressor uses.

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

Parameters
compThe ROHC compressor
[out]max_cidThe current maximal CID value
Returns
true if MAX_CID was successfully retrieved, false otherwise

◆ rohc_comp_get_mrru()

bool rohc_comp_get_mrru ( const struct rohc_comp *const  comp,
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_comp_get_segment2 can be used to retrieve ROHC segments.

Parameters
compThe ROHC compressor
[out]mrruThe current MRRU value (in bytes)
Returns
true if MRRU was successfully retrieved, false otherwise
Example:
struct rohc_comp *comp;
size_t mrru;
...
/* retrieve current compressor MRRU */
if(!rohc_comp_get_mrru(comp, &mrru))
{
fprintf(stderr, "failed to get MRRU for compressor\n");
goto error;
}
printf("the current MMRU at compressor is %zu bytes\n", mrru);
...
See also
rohc_comp_set_mrru
rohc_comp_get_segment2
rohc_decomp_set_mrru
rohc_decomp_get_mrru

◆ rohc_comp_get_segment2()

rohc_status_t rohc_comp_get_segment2 ( struct rohc_comp *const  comp,
struct rohc_buf *const  segment 
)

Get the next ROHC segment if any.

Get the next ROHC segment if any.

To get all the segments of one ROHC packet, call this function until ROHC_STATUS_OK or ROHC_STATUS_ERROR is returned.

Parameters
compThe ROHC compressor
[out]segmentThe buffer where to store the ROHC segment
Returns
Possible return values:
Example:
struct rohc_comp *comp;
...
// compress the IP packet with a small ROHC buffer
status = rohc_compress4(comp, ip_packet, &rohc_packet);
if(status == ROHC_STATUS_SEGMENT)
{
/* ROHC segmentation is required to compress the IP packet */
/* get the segments */
while((status = rohc_comp_get_segment2(comp, &rohc_packet)) == ROHC_STATUS_SEGMENT)
{
/* new ROHC segment retrieved */
...
// decompress the ROHC segment here, the function
// rohc_decompress3 shall return ROHC_STATUS_OK
// and no decompressed packet
...
if(uncomp_packet.len > 0)
{
fprintf(stderr, "\tdecompression of ROHC segment succeeded while "
"it should have not\n");
goto destroy_decomp;
}
rohc_packet.len = 0;
}
if(status != ROHC_STATUS_OK)
{
fprintf(stderr, "failed to generate ROHC segment (status = %d)\n",
status);
goto destroy_decomp;
}
/* final ROHC segment retrieved */
// decompress the final ROHC segment here, the function
// rohc_decompress4 shall return ROHC_STATUS_OK
if(uncomp_packet.len == 0)
{
fprintf(stderr, "\tdecompression of ROHC segment failed while it "
"should have succeeded\n");
goto destroy_decomp;
}
}
else if(status != ROHC_STATUS_OK)
{
// handle compression error here
...
See also
rohc_comp_get_mrru
rohc_comp_set_mrru
rohc_compress4

◆ rohc_comp_get_state_descr()

const char* rohc_comp_get_state_descr ( const rohc_comp_state_t  state)

Give a description for the given ROHC compression context state.

Give a description for the given ROHC compression 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 compression context states used by the library. If unsure, ask on the mailing list.

Parameters
stateThe compression context state to get a description for
Returns
A string that describes the given compression context state

◆ rohc_comp_new2()

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 
)

Create a new ROHC compressor.

Create a new ROHC compressor with the given type of CIDs and MAX_CID.

The user-defined callback for random numbers is called by the ROHC library every time a new random number is required. It currently happens only to initiate the Sequence Number (SN) of new IP-only, IP/UDP, or IP/UDP-Lite streams to a random value as defined by RFC 3095.

Parameters
cid_typeThe type of Context IDs (CID) that the ROHC compressor shall operate with. Accepted values are:
max_cidThe maximum value that the ROHC compressor should use for context IDs (CID). As CIDs starts with value 0, the number of contexts is max_cid + 1.
Accepted values are:
rand_cbThe random callback to set
rand_privPrivate data that will be given to the callback, may be used as a context by user
Returns
The created compressor if successful, NULL if creation failed
Warning
Don't forget to free compressor memory with rohc_comp_free if rohc_comp_new2 succeeded
Example:
struct rohc_comp *compressor; /* the ROHC compressor */
...
gen_random_num, NULL);
if(compressor == NULL)
{
fprintf(stderr, "failed create the ROHC compressor\n");
goto error;
}
...
rohc_comp_free(compressor);
See also
rohc_comp_free
rohc_compress4
rohc_comp_set_traces_cb2
rohc_comp_enable_profiles
rohc_comp_enable_profile
rohc_comp_disable_profiles
rohc_comp_disable_profile
rohc_comp_set_mrru
rohc_comp_set_wlsb_window_width
rohc_comp_set_periodic_refreshes
rohc_comp_set_rtp_detection_cb

◆ rohc_comp_pad()

rohc_status_t rohc_comp_pad ( struct rohc_comp *const  comp,
struct rohc_buf *const  rohc_pkt,
const size_t  min_pkt_len 
)

Pad the given ROHC compressed packet.

Add as many padding bytes as required to get a ROHC packet of the given length.

Parameters
compThe ROHC compressor
[in,out]rohc_pktThe compressed ROHC packet to pad up to min_pkt_len
min_pkt_lenThe minimum length of the ROHC packet
Returns
Possible return values:
See also
rohc_compress4

◆ rohc_comp_profile_enabled()

bool rohc_comp_profile_enabled ( const struct rohc_comp *const  comp,
const rohc_profile_t  profile 
)

Is the given compression profile enabled for a compressor?

Is the given compression profile enabled or disabled for a compressor?

Parameters
compThe ROHC compressor
profileThe profile to ask status for
Returns
Possible return values:
  • true if the profile exists and is enabled,
  • false if the compressor is not valid, the profile does not exist, or the profile is disabled
See also
rohc_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profile
rohc_comp_disable_profiles

◆ rohc_comp_set_features()

bool rohc_comp_set_features ( struct rohc_comp *const  comp,
const rohc_comp_features_t  features 
)

Enable/disable features for ROHC compressor.

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

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

Warning
Changing the feature set while library is used is not supported
Parameters
compThe ROHC compressor
featuresThe feature set to enable/disable
Returns
true if the feature set was successfully enabled/disabled, false if a problem occurred
See also
rohc_comp_features_t

◆ rohc_comp_set_list_trans_nr()

bool rohc_comp_set_list_trans_nr ( struct rohc_comp *const  comp,
const size_t  list_trans_nr 
)

Set the number of uncompressed transmissions for list compression.

Set the number of transmissions required for list compression. This matches the L parameter described in RFC 3095 and 4815. The compressor sends the list items uncompressed L times before compressing them. The compressor also sends the list structure L times before compressing it out.

The L parameter is set to ROHC_LIST_DEFAULT_L by default.

Warning
The value can not be modified after library initialization
Parameters
compThe ROHC compressor
list_trans_nrThe number of times the list items or the list itself are sent uncompressed before being sent compressed
Returns
true if the new value is accepted, false if the value is rejected

◆ rohc_comp_set_mrru()

bool rohc_comp_set_mrru ( struct rohc_comp *const  comp,
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. No segment will be generated.

According to RF5225 §6.1, ROHC segmentation cannot be enabled if any ROHCv2 profile is also enabled.

If segmentation is enabled and used by the compressor, the function rohc_comp_get_segment2 can be used to retrieve ROHC segments.

Parameters
compThe ROHC compressor
mrruThe new MRRU value (in bytes)
Returns
true if the MRRU was successfully set, false otherwise
Example:
struct rohc_comp *comp;
size_t mrru = 500;
...
/* set the MRRU at compressor */
if(!rohc_comp_set_mrru(comp, mrru))
{
fprintf(stderr, "failed to set the MRRU at compressor\n");
goto destroy_comp;
}
...
See also
rohc_comp_get_mrru
rohc_comp_get_segment2
rohc_decomp_set_mrru

◆ rohc_comp_set_periodic_refreshes()

bool rohc_comp_set_periodic_refreshes ( struct rohc_comp *const  comp,
const size_t  ir_timeout,
const size_t  fo_timeout 
)

Set the timeouts in packets for IR and FO periodic refreshes.

Set the timeout values for IR and FO periodic refreshes. The IR timeout shall be greater than the FO timeout. Both timeouts are expressed in number of compressed packets.

The IR timeout is set to CHANGE_TO_IR_COUNT by default. The FO timeout is set to CHANGE_TO_FO_COUNT by default.

Warning
The values can not be modified after library initialization
Parameters
compThe ROHC compressor
ir_timeoutThe number of packets to compress before going back to IR state to force a context refresh
fo_timeoutThe number of packets to compress before going back to FO state to force a context refresh
Returns
true in case of success, false in case of failure

◆ rohc_comp_set_periodic_refreshes_time()

bool rohc_comp_set_periodic_refreshes_time ( struct rohc_comp *const  comp,
const uint64_t  ir_timeout,
const uint64_t  fo_timeout 
)

Set the timeouts in ms for IR and FO periodic refreshes.

Set the timeout values for IR and FO periodic refreshes. The IR timeout shall be greater than the FO timeout. Both timeouts are expressed in milliseconds.

The IR timeout is set to CHANGE_TO_IR_TIME by default. The FO timeout is set to CHANGE_TO_FO_TIME by default.

Warning
The values can not be modified after library initialization
Parameters
compThe ROHC compressor
ir_timeoutThe delay (in ms) before going back to IR state to force a context refresh
fo_timeoutThe delay (in ms) before going back to FO state to force a context refresh
Returns
true in case of success, false in case of failure

◆ rohc_comp_set_reorder_ratio()

bool rohc_comp_set_reorder_ratio ( struct rohc_comp *const  comp,
const rohc_reordering_offset_t  reorder_ratio 
)

Set the reordering ratio for the W-LSB encoding scheme.

The control field reorder_ratio specifies how much reordering is handled by the W-LSB encoding of the MSN in ROHCv2 profiles.

The reordering ration is set to ROHC_REORDERING_NONE by default.

Parameters
compThe ROHC compressor
reorder_ratioThe reordering ratio
Returns
true in case of success, false in case of failure

◆ rohc_comp_set_rtp_detection_cb()

bool rohc_comp_set_rtp_detection_cb ( struct rohc_comp *const  comp,
rohc_rtp_detection_callback_t  callback,
void *const  rtp_private 
)

Set the RTP detection callback function.

Set or replace the callback function that the ROHC library will call to detect RTP streams among other UDP streams.

The function is called once per UDP packet to compress, with the IP and UDP headers and the UDP payload. If the callback function returns true, the RTP profile is used for compression, otherwise the IP/UDP profile is used instead.

Special value NULL may be used to disable the detection of RTP streams with the callback method. The detection will then be based on a list of UDP ports dedicated for RTP streams.

Parameters
compThe ROHC compressor
callbackThe callback function used to detect RTP packets The callback is deactivated if NULL is given as parameter
rtp_privateA pointer to an external memory area provided and used by the callback user
Returns
true on success, false otherwise
Example:
/**
* @brief The RTP detection callback which does detect RTP stream
*
* @param ip The innermost IP packet
* @param udp The UDP header of the packet
* @param payload The UDP payload of the packet
* @param payload_size The size of the UDP payload (in bytes)
* @return true if the packet is an RTP packet, false otherwise
*/
static bool rtp_detect(const unsigned char *const ip,
const unsigned char *const udp,
const unsigned char *const payload,
const unsigned int payload_size,
void *const rtp_private)
{
uint16_t udp_dport;
bool is_rtp;
/* check UDP destination port */
memcpy(&udp_dport, udp + 2, sizeof(uint16_t));
if(ntohs(udp_dport) == 10042)
{
/* we think that the UDP packet is a RTP packet */
fprintf(stderr, "RTP packet detected (expected UDP port)\n");
is_rtp = true;
}
else
{
/* we think that the UDP packet is not a RTP packet */
fprintf(stderr, "RTP packet not detected (wrong UDP port)\n");
is_rtp = false;
}
return is_rtp;
}
...
struct rohc_comp *compressor; /* the ROHC compressor */
...
gen_random_num, NULL);
if(compressor == NULL)
{
fprintf(stderr, "failed create the ROHC compressor\n");
goto error;
}
...
if(!rohc_comp_set_rtp_detection_cb(compressor, rtp_detect, NULL))
{
fprintf(stderr, "failed to set RTP detection callback\n");
goto error;
}
...
rohc_comp_free(compressor);
See also
rohc_rtp_detection_callback_t
rohc_comp_add_rtp_port
rohc_comp_remove_rtp_port
rohc_comp_reset_rtp_ports

◆ rohc_comp_set_traces_cb2()

bool rohc_comp_set_traces_cb2 ( struct rohc_comp *const  comp,
rohc_trace_callback2_t  callback,
void *const  priv_ctxt 
)

Set the callback function used to manage traces in compressor.

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

The function will be called by the ROHC library every time it wants to print something related to compression, 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
compThe ROHC compressor
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
Example:
/**
* @brief Callback to print traces of the ROHC library
*
* @param priv_ctxt An optional private context, may be NULL
* @param level The priority level of the trace
* @param entity The entity that emitted the trace among:
* \li ROHC_TRACE_COMP
* \li ROHC_TRACE_DECOMP
* @param profile The ID of the ROHC compression/decompression profile
* the trace is related to
* @param format The format string of the trace
*/
static void print_rohc_traces(void *const priv_ctxt,
const rohc_trace_level_t level,
const rohc_trace_entity_t entity,
const int profile,
const char *const format,
...)
{
va_list args;
va_start(args, format);
vfprintf(stdout, format, args);
va_end(args);
}
...
struct rohc_comp *compressor; /* the ROHC compressor */
...
gen_random_num, NULL);
if(compressor == NULL)
{
fprintf(stderr, "failed create the ROHC compressor\n");
goto error;
}
...
if(!rohc_comp_set_traces_cb2(compressor, print_rohc_traces, NULL))
{
fprintf(stderr, "failed to set the callback for traces on "
"compressor\n");
goto release_compressor;
}
...
rohc_comp_free(compressor);

◆ rohc_comp_set_wlsb_window_width()

bool rohc_comp_set_wlsb_window_width ( struct rohc_comp *const  comp,
const size_t  width 
)

Set the window width for the W-LSB encoding scheme.

Set the window width for the Window-based Least Significant Bits (W-LSB) encoding. See section 4.5.2 of RFC 3095 for more details about the encoding scheme.

The width of the W-LSB window is set to 4 by default.

Warning
The value can not be modified after library initialization
Parameters
compThe ROHC compressor
widthThe width of the W-LSB sliding window
Returns
true in case of success, false in case of failure

◆ rohc_compress4()

rohc_status_t rohc_compress4 ( struct rohc_comp *const  comp,
const struct rohc_buf  uncomp_packet,
struct rohc_buf *const  rohc_packet 
)

Compress the given uncompressed packet into a ROHC packet.

Compress the given uncompressed packet into a ROHC packet. The compression may succeed into two different ways:

Notes:

  • ROHC segmentation: The ROHC compressor has to use ROHC segmentation if the output buffer rohc_packet was too small for the compressed ROHC packet and if the Maximum Reconstructed Reception Unit (MRRU) configured with the function rohc_comp_set_mrru was not exceeded. If ROHC segmentation is used, one may use the rohc_comp_get_segment2 function to retrieve all the ROHC segments one by one.
  • Time-related features in the ROHC protocol: Set the uncomp_packet.time parameter to 0 if arrival time of the uncompressed packet is unknown or to disable the time-related features in the ROHC protocol.
Parameters
compThe ROHC compressor
uncomp_packetThe uncompressed packet to compress
[out]rohc_packetThe resulting compressed ROHC packet
Returns
Possible return values:
Example:
struct rohc_comp *compressor; /* the ROHC compressor */
/* the buffer that will contain the IPv4 packet to compress */
unsigned char ip_buffer[BUFFER_SIZE];
struct rohc_buf ip_packet = rohc_buf_init_empty(ip_buffer, BUFFER_SIZE);
/* the buffer that will contain the resulting ROHC packet */
unsigned char rohc_buffer[BUFFER_SIZE];
struct rohc_buf rohc_packet = rohc_buf_init_empty(rohc_buffer, BUFFER_SIZE);
...
status = rohc_compress4(compressor, ip_packet, &rohc_packet);
if(status == ROHC_STATUS_SEGMENT)
{
/* success: compression succeeded, but resulting ROHC packet was too
* large for the Maximum Reconstructed Reception Unit (MRRU) configured
* with \ref rohc_comp_set_mrru, the rohc_packet buffer contains the
* first ROHC segment and \ref rohc_comp_get_segment can be used to
* retrieve the next ones. */
...
}
else if(status == ROHC_STATUS_OK)
{
/* success: compression succeeded, and resulting ROHC packet fits the
* Maximum Reconstructed Reception Unit (MRRU) configured with
* \ref rohc_comp_set_mrru, the rohc_packet buffer contains the
* rohc_packet_len bytes of the ROHC packet */
...
}
else
{
/* compressor failed to compress the IP packet */
...
}
...
See also
rohc_comp_set_mrru
rohc_comp_get_segment2