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_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. 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_optimistic_approach (struct rohc_comp *const comp, const size_t repetitions_nr)
	Set the number of repetitions required to gain transmission confidence. 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

comp	The ROHC compressor
user_context	The 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

ip	The innermost IP packet
udp	The UDP header of the packet
payload	The UDP payload of the packet
payload_size	The size of the UDP payload (in bytes)
rtp_private	A 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

enum 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

enum 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

enum 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

comp	The ROHC compressor
feedback	The 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.

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

comp	The ROHC compressor
profile	The 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

comp	The 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

comp	The ROHC compressor
profile	The 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 */
...

if(!rohc_comp_enable_profile(compressor, ROHC_PROFILE_UNCOMPRESSED))
{
fprintf(stderr, "failed to enable the Uncompressed profile\n");
goto release_compressor;
}
if(!rohc_comp_enable_profile(compressor, ROHC_PROFILE_IP))
{
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

comp	The 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 */
...

if(!rohc_comp_enable_profiles(compressor, ROHC_PROFILE_UDP,
ROHC_PROFILE_ESP, -1))
{
fprintf(stderr, "failed to enable the IP/UDP and IP/ESP 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

comp	The 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

comp	The ROHC compressor to destroy

Example:: struct rohc_comp *compressor; /* the ROHC compressor */
...

compressor = rohc_comp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX,
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

	comp	The ROHC compressor
[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

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

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

	comp	The ROHC compressor 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_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.

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

	comp	The ROHC compressor 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_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

	comp	The ROHC compressor
[out]	max_cid	The 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

	comp	The ROHC compressor
[out]	mrru	The 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.

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

Parameters

	comp	The ROHC compressor
[out]	segment	The buffer where to store the ROHC segment

Returns

Possible return values:

ROHC_STATUS_SEGMENT if a ROHC segment is returned and more segments are available,
ROHC_STATUS_OK if a ROHC segment is returned and no more ROHC segment is available
ROHC_STATUS_ERROR if an error occurred

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.

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

state The 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_type	The type of Context IDs (CID) that the ROHC compressor 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 compressor 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
rand_cb	The random callback to set
rand_priv	Private 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 */
...

compressor = rohc_comp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX,
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_optimistic_approach; 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

	comp	The ROHC compressor
[in,out]	rohc_pkt	The compressed ROHC packet to pad up to min_pkt_len
	min_pkt_len	The minimum length of the ROHC packet

Returns

Possible return values:

ROHC_STATUS_OK if a padded ROHC packet is returned
ROHC_STATUS_OUTPUT_TOO_SMALL if the buffer is too small for the padded ROHC packet
ROHC_STATUS_ERROR if an error occurred

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

comp	The ROHC compressor
profile	The 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

comp	The ROHC compressor
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_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_OA_REPEAT_DEFAULT by default.

Warning: The value can not be modified after library initialization

Parameters

comp	The ROHC compressor
list_trans_nr	The 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

Deprecated:: please use rohc_comp_set_optimistic_approach() instead

◆ 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).

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

comp	The ROHC compressor
mrru	The 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_optimistic_approach()

bool rohc_comp_set_optimistic_approach	(	struct rohc_comp *const	comp,
		const size_t	repetitions_nr
	)

Set the number of repetitions required to gain transmission confidence.

The Optimistic Approach is defined by RFC 3095 §5.3.1.1.1 as follow:

Transition to a higher compression state in Unidirectional mode is carried out according to the optimistic approach principle. This means that the compressor transits to a higher compression state when it is fairly confident that the decompressor has received enough information to correctly decompress packets sent according to the higher compression state.

When the compressor is in the IR state, it will stay there until it assumes that the decompressor has correctly received the static context information. For transition from the FO to the SO state, the compressor should be confident that the decompressor has all parameters needed to decompress according to a fixed pattern.

The compressor normally obtains its confidence about decompressor status by sending several packets with the same information according to the lower compression state. If the decompressor receives any of these packets, it will be in sync with the compressor. The number of consecutive packets to send for confidence is not defined in this document.

This function allows the library users to set the number of repetitions required by the ROHC compressor to gain confidence that the ROHC decompressor got the transmitted information.

It controls:

the number of IR packets transmitted in a row at context initialization,
the number of context-updating packets transmitted in case of stream change,
the number of transmissions of TS stride, list structures or list items before they are considered as known,
the width of the W-LSB window.

The number of repetitions may be chosen as follow: a/ define the largest loss burst that you want to be robust to, b/ increment that number by one, so that at least one packet per burst is received by the decompressor.

Warning: The value can not be modified after library initialization

Parameters

comp	The ROHC compressor to configure
repetitions_nr	The number of repetitions (4 by default)

Returns: true in case of success, false in case of failure

◆ 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

comp	The ROHC compressor
ir_timeout	The number of packets to compress before going back to IR state to force a context refresh
fo_timeout	The 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

comp	The ROHC compressor
ir_timeout	The delay (in ms) before going back to IR state to force a context refresh
fo_timeout	The 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

comp	The ROHC compressor
reorder_ratio	The 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

comp	The ROHC compressor
callback	The callback function used to detect RTP packets The callback is deactivated if NULL is given as parameter
rtp_private	A 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 */
...

compressor = rohc_comp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX,
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

comp	The ROHC compressor
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

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 */
...

compressor = rohc_comp_new2(ROHC_SMALL_CID, ROHC_SMALL_CID_MAX,
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

comp	The ROHC compressor
width	The width of the W-LSB sliding window

Returns: true in case of success, false in case of failure

Deprecated:: please use rohc_comp_set_optimistic_approach() instead

◆ 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:

return ROHC_STATUS_OK and a full ROHC packet,
return ROHC_STATUS_SEGMENT and no ROHC data if ROHC segmentation is required.

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

	comp	The ROHC compressor
	uncomp_packet	The uncompressed packet to compress
[out]	rohc_packet	The resulting compressed ROHC packet

Returns

Possible return values:

ROHC_STATUS_OK if a ROHC packet is returned
ROHC_STATUS_SEGMENT if no ROHC data is returned and ROHC segments can be retrieved with successive calls to rohc_comp_get_segment2
ROHC_STATUS_OUTPUT_TOO_SMALL if the output buffer is too small for the compressed packet
ROHC_STATUS_ERROR if an error occurred

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ rohc_comp_random_cb_t

◆ rohc_rtp_detection_callback_t

Enumeration Type Documentation

◆ rohc_comp_features_t

◆ rohc_comp_state_t

◆ rohc_reordering_offset_t

Function Documentation

◆ rohc_comp_deliver_feedback2()

◆ rohc_comp_disable_profile()

◆ rohc_comp_disable_profiles()

◆ rohc_comp_enable_profile()

◆ rohc_comp_enable_profiles()

◆ rohc_comp_force_contexts_reinit()

◆ rohc_comp_free()

◆ rohc_comp_get_cid_type()

◆ rohc_comp_get_general_info()

◆ rohc_comp_get_last_packet_info2()

◆ rohc_comp_get_max_cid()

◆ rohc_comp_get_mrru()

◆ rohc_comp_get_segment2()

◆ rohc_comp_get_state_descr()

◆ rohc_comp_new2()

◆ rohc_comp_pad()

◆ rohc_comp_profile_enabled()

◆ rohc_comp_set_features()

◆ rohc_comp_set_list_trans_nr()

◆ rohc_comp_set_mrru()

◆ rohc_comp_set_optimistic_approach()

◆ rohc_comp_set_periodic_refreshes()

◆ rohc_comp_set_periodic_refreshes_time()

◆ rohc_comp_set_reorder_ratio()

◆ rohc_comp_set_rtp_detection_cb()

◆ rohc_comp_set_traces_cb2()

◆ rohc_comp_set_wlsb_window_width()

◆ rohc_compress4()