Data Structures
struct	rohc_comp_last_packet_info_t
	Some information about the last compressed packet. More...
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.
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.
Enumerations
enum	rohc_c_state { IR = 1, FO = 2, SO = 3 }
	The different ROHC compressor states. More...
enum	rohc_comp_state_t { ROHC_COMP_STATE_IR = 1, ROHC_COMP_STATE_FO = 2, ROHC_COMP_STATE_SO = 3 }
	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) }
	The different features of the ROHC compressor. More...
Functions
struct rohc_comp *	rohc_alloc_compressor (int max_cid, int jam_use, int adapt_size, int encap_size)
	Create one ROHC compressor.
void	rohc_free_compressor (struct rohc_comp *comp)
	Destroy one ROHC compressor.
struct rohc_comp *	rohc_comp_new (const rohc_cid_type_t cid_type, const rohc_cid_t max_cid)
	Create a new ROHC compressor.
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.
void	rohc_comp_free (struct rohc_comp *const comp)
	Destroy the given ROHC compressor.
bool	rohc_comp_set_traces_cb (struct rohc_comp *const comp, rohc_trace_callback_t callback)
	Set the callback function used to manage traces in compressor.
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.
bool	rohc_comp_set_random_cb (struct rohc_comp const comp, rohc_comp_random_cb_t callback, void const user_context)
	Set the user-defined callback for random numbers.
int	rohc_compress (struct rohc_comp comp, unsigned char ibuf, int isize, unsigned char *obuf, int osize)
	Compress the given uncompressed packet into a ROHC packet.
int	rohc_compress2 (struct rohc_comp const comp, const unsigned char const uncomp_packet, const size_t uncomp_packet_len, unsigned char const rohc_packet, const size_t rohc_packet_max_len, size_t const rohc_packet_len)
	Compress the given uncompressed packet into a ROHC packet.
int	rohc_compress3 (struct rohc_comp const comp, const struct rohc_ts arrival_time, const unsigned char const uncomp_packet, const size_t uncomp_packet_len, unsigned char const rohc_packet, const size_t rohc_packet_max_len, size_t const rohc_packet_len)
	Compress the given uncompressed packet into a ROHC packet.
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.
int	rohc_comp_get_segment (struct rohc_comp const comp, unsigned char const segment, const size_t max_len, size_t *const len)
	Get the next ROHC segment if any.
rohc_status_t	rohc_comp_get_segment2 (struct rohc_comp const comp, struct rohc_buf const segment)
	Get the next ROHC segment if any.
bool	rohc_comp_force_contexts_reinit (struct rohc_comp *const comp)
	Force the compressor to re-initialize all its contexts.
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.
bool	rohc_comp_set_periodic_refreshes (struct rohc_comp *const comp, const size_t ir_timeout, const size_t fo_timeout)
	Set the timeout values for IR and FO periodic refreshes.
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.
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.
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?
void	rohc_activate_profile (struct rohc_comp *comp, int profile)
	Activate a profile for a compressor.
bool	rohc_comp_enable_profile (struct rohc_comp *const comp, const rohc_profile_t profile)
	Enable a compression profile for a compressor.
bool	rohc_comp_disable_profile (struct rohc_comp *const comp, const rohc_profile_t profile)
	Disable a compression profile for a compressor.
bool	rohc_comp_enable_profiles (struct rohc_comp *const comp,...)
	Enable several compression profiles for a compressor.
bool	rohc_comp_disable_profiles (struct rohc_comp *const comp,...)
	Disable several compression profiles for a compressor.
int	rohc_c_using_small_cid (struct rohc_comp *comp)
	Whether the compressor uses small CID or not.
void	rohc_c_set_header (struct rohc_comp *comp, int header)
	Set the maximal header size. The maximal header size is ignored for the moment.
void	rohc_c_set_mrru (struct rohc_comp *comp, int value)
	Set the Maximum Reconstructed Reception Unit (MRRU).
bool	rohc_comp_set_mrru (struct rohc_comp *const comp, const size_t mrru)
	Set the Maximum Reconstructed Reception Unit (MRRU).
bool	rohc_comp_get_mrru (const struct rohc_comp const comp, size_t const mrru)
	Get the Maximum Reconstructed Reception Unit (MRRU).
void	rohc_c_set_max_cid (struct rohc_comp *comp, int value)
	Set the maximal CID value the compressor should use.
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.
void	rohc_c_set_large_cid (struct rohc_comp *comp, int large_cid)
	Tell the compressor to use large CIDs.
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.
bool	rohc_comp_add_rtp_port (struct rohc_comp *const comp, const unsigned int port)
	Add a port to the list of UDP ports dedicated for RTP traffic.
bool	rohc_comp_remove_rtp_port (struct rohc_comp *const comp, const unsigned int port)
	Remove a port from the list of UDP ports dedicated to RTP traffic.
bool	rohc_comp_reset_rtp_ports (struct rohc_comp *const comp)
	Reset the list of dedicated RTP ports.
bool	rohc_comp_set_features (struct rohc_comp *const comp, const rohc_comp_features_t features)
	Enable/disable features for ROHC compressor.
void	rohc_c_set_enable (struct rohc_comp *comp, int enable)
	Enable the ROHC compressor.
int	rohc_c_is_enabled (struct rohc_comp *comp)
	Whether the ROHC compressor is enabled or not.
int	rohc_c_info (char *buffer)
	Get information about available compression profiles.
int	rohc_c_statistics (struct rohc_comp comp, unsigned int indent, char buffer)
	Get information about a ROHC compressor.
void	c_piggyback_feedback (struct rohc_comp comp, unsigned char feedback, int size)
	Add a feedback packet to the next outgoing ROHC packet (piggybacking)
bool	rohc_comp_piggyback_feedback (struct rohc_comp const comp, const unsigned char const feedback, const size_t size)
	Add a feedback packet to the next outgoing ROHC packet (piggybacking)
void	c_deliver_feedback (struct rohc_comp comp, unsigned char packet, int size)
	Callback called by a decompressor to deliver a feedback packet to the compressor.
bool	rohc_comp_deliver_feedback (struct rohc_comp const comp, const uint8_t const packet, const size_t size)
	Deliver a feedback packet to the compressor.
bool	rohc_comp_deliver_feedback2 (struct rohc_comp *const comp, const struct rohc_buf feedback)
	Deliver a feedback packet to the compressor.
int	rohc_feedback_flush (struct rohc_comp comp, unsigned char obuf, int osize)
	Send as much feedback data as possible.
size_t	rohc_feedback_avail_bytes (const struct rohc_comp *const comp)
	How many bytes of unsent feedback data are available at compressor?
int	rohc_comp_get_last_packet_info (const struct rohc_comp const comp, rohc_comp_last_packet_info_t const info)
	Get some information about the last compressed packet.
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.
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.
const char *	rohc_comp_get_state_descr (const rohc_comp_state_t state)
	Give a description for the given ROHC compression context state.
bool	rohc_feedback_remove_locked (struct rohc_comp *const comp)
	Remove all feedbacks locked during the packet build.
bool	rohc_feedback_unlock (struct rohc_comp *const comp)
	Unlock all feedbacks locked during the packet build.

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

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_set_random_cb

Parameters:

comp	The ROHC compressor
user_context	The context given by the user when he/she called the rohc_comp_set_random_cb function, may be NULL.

See also:: rohc_comp_set_random_cb

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

enum rohc_c_state

The different ROHC compressor states.

The different ROHC operation states at compressor as defined in section 4.3.1 of RFC 3095.

If you add a new compressor state, please also add the corresponding textual description in rohc_comp_get_state_descr.

Deprecated:: do not use this type anymore, use rohc_comp_state_t instead

See also:: rohc_comp_get_state_descr

Enumerator:

IR	The Initialization and Refresh (IR) compressor state
FO	The First Order (FO) compressor state
SO	The Second Order (SO) compressor state

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

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.

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_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

Function Documentation

void c_deliver_feedback	(	struct rohc_comp *	comp,
		unsigned char *	packet,
		int	size
	)

Callback called by a decompressor to deliver a feedback packet to the compressor.

When feedback is received by the decompressor, this function is called and delivers the feedback to the right profile/context of the compressor.

Deprecated:: please do not use this function anymore, use rohc_comp_deliver_feedback2() instead

Parameters:

comp	The ROHC compressor
packet	The feedback data
size	The length of the feedback packet

void c_piggyback_feedback	(	struct rohc_comp *	comp,
		unsigned char *	feedback,
		int	size
	)

Add a feedback packet to the next outgoing ROHC packet (piggybacking)

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and prepend feedback data yourself

Parameters:

comp	The ROHC compressor
feedback	The feedback data
size	The length of the feedback packet

void rohc_activate_profile	(	struct rohc_comp *	comp,
		int	profile
	)

Activate a profile for a compressor.

Deprecated:: do not use this function anymore, use rohc_comp_enable_profile() instead

Parameters:

comp	The ROHC compressor
profile	The ID of the profile to activate

struct rohc_comp* rohc_alloc_compressor	(	int	max_cid,
		int	jam_use,
		int	adapt_size,
		int	encap_size
	)		`[read]`

Create one ROHC compressor.

Deprecated:: do not use this function anymore, use rohc_comp_new2() instead

Parameters:

max_cid	The maximal CID value the compressor should use for contexts
jam_use	not used anymore, must be 0
adapt_size	not used anymore, ignored
encap_size	not used anymore, ignored

Returns:: The newly-created compressor if successful, NULL otherwise

Warning:: Don't forget to free compressor memory with rohc_free_compressor if rohc_alloc_compressor 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_free_compressor; rohc_comp_set_traces_cb; rohc_comp_set_random_cb; rohc_comp_enable_profiles; rohc_comp_enable_profile; rohc_comp_disable_profiles; rohc_comp_disable_profile; rohc_comp_set_wlsb_window_width; rohc_comp_set_periodic_refreshes; rohc_comp_set_rtp_detection_cb; rohc_comp_reset_rtp_ports; rohc_comp_add_rtp_port; rohc_comp_remove_rtp_port

int rohc_c_info ( char * buffer )

Get information about available compression profiles.

This function outputs XML.

Deprecated:: do not use this function anymore, use rohc_comp_get_general_info() instead

Parameters:

buffer The buffer where to store profile information

Returns:: The length of the data stored in the buffer

int rohc_c_is_enabled ( struct rohc_comp * comp )

Whether the ROHC compressor is enabled or not.

Return whether the ROHC compressor is enabled or not.

Deprecated:: do not use this function anymore, the ROHC compressor shall be considered always enabled now

Parameters:

comp	The ROHC compressor

Returns:: 1 if the compressor is enabled, 0 if not

void rohc_c_set_enable	(	struct rohc_comp *	comp,
		int	enable
	)

Enable the ROHC compressor.

Deprecated:: do not use this function anymore, the ROHC compressor shall be considered always enabled now

Parameters:

comp	The ROHC compressor
enable	1 to enable the compressor, 0 to disable it

void rohc_c_set_header	(	struct rohc_comp *	comp,
		int	header
	)

Set the maximal header size. The maximal header size is ignored for the moment.

Deprecated:: do not use this function anymore, simply remove it from your code

Parameters:

comp	The ROHC compressor
header	The maximal header size

void rohc_c_set_large_cid	(	struct rohc_comp *	comp,
		int	large_cid
	)

Tell the compressor to use large CIDs.

Deprecated:: please do not use this function anymore, use the parameter cid_type of rohc_comp_new2() instead

Parameters:

comp	The ROHC compressor
large_cid	Whether to use large CIDs or not

void rohc_c_set_max_cid	(	struct rohc_comp *	comp,
		int	value
	)

Set the maximal CID value the compressor should use.

Deprecated:: please do not use this function anymore, use the parameter max_cid of rohc_comp_new2() instead

Parameters:

comp	The ROHC compressor
value	The new maximal CID value

void rohc_c_set_mrru	(	struct rohc_comp *	comp,
		int	value
	)

Set the Maximum Reconstructed Reception Unit (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.

Deprecated:: do not use this function anymore, use rohc_comp_set_mrru() instead

Parameters:

comp	The ROHC compressor
value	The new MRRU value

int rohc_c_statistics	(	struct rohc_comp *	comp,
		unsigned int	indent,
		char *	buffer
	)

Get information about a ROHC compressor.

This function outputs XML.

Deprecated:: do not use this function anymore, use rohc_comp_get_general_info() instead

Parameters:

comp	The ROHC compressor
indent	The indent level to beautify the XML output
buffer	The buffer where to store the information

Returns:: The length of the data stored in the buffer if successful, -1 if an error occurs

int rohc_c_using_small_cid ( struct rohc_comp * comp )

Whether the compressor uses small CID or not.

Deprecated:: please do not use this function anymore, use rohc_comp_get_cid_type() instead

Parameters:

comp	The ROHC compressor

Returns:: Whether the compressor uses small CID or not

bool rohc_comp_add_rtp_port	(	struct rohc_comp *const	comp,
		const unsigned int	port
	)

Add a port to the list of UDP ports dedicated for RTP traffic.

If no function callback was defined for the detection of RTP streams, the detection is based on a list of UDP ports dedicated for RTP streams.

This function allows to update the list by adding the given UDP port to the list of UDP ports dedicated for RTP traffic.

Deprecated:: please do not use this function anymore, use rohc_comp_set_rtp_detection_cb() instead

Parameters:

comp	The ROHC compressor
port	The UDP port to add in the list

Returns:: true on success, false otherwise

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;
        }

        ...

        if(!rohc_comp_reset_rtp_ports(compressor))
        {
                fprintf(stderr, "failed to reset list of RTP ports\n");
                goto error;
        }

        if(!rohc_comp_add_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to enable RTP port 1234\n");
                goto error;
        }
        if(!rohc_comp_add_rtp_port(compressor, 10042))
        {
                fprintf(stderr, "failed to enable RTP port 10042\n");
                goto error;
        }

        if(!rohc_comp_remove_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to remove RTP port 1234\n");
                goto error;
        }

        ...

        rohc_comp_free(compressor);

See also:: rohc_comp_remove_rtp_port; rohc_comp_reset_rtp_ports; rohc_comp_set_rtp_detection_cb

bool rohc_comp_deliver_feedback	(	struct rohc_comp *const	comp,
		const uint8_t *const	packet,
		const size_t	size
	)

Deliver a feedback packet to the compressor.

When feedback is received by the decompressor, this function is called and delivers the feedback to the right profile/context of the compressor.

Deprecated:: please do not use this function anymore, use rohc_comp_deliver_feedback2() instead

Parameters:

comp	The ROHC compressor
packet	The feedback data
size	The length of the feedback packet

Returns:: true if the feedback was successfully taken into account, false if the feedback could not be taken into account

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

Deliver a feedback packet to the compressor.

When feedback is received by the decompressor, this function is called and delivers the feedback to the right profile/context of the 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

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

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

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.

Parameters:

comp	The ROHC compressor
profile	The profile to enable

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

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

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_UDPLITE, -1))
        {
                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

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.

Parameters:

comp	The ROHC compressor

Returns:: true in case of success, false otherwise

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

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

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

int rohc_comp_get_last_packet_info	(	const struct rohc_comp *const	comp,
		rohc_comp_last_packet_info_t *const	info
	)

Get some information about the last compressed packet.

Deprecated:: do not use this function anymore, use rohc_comp_get_last_packet_info2() instead

Parameters:

	comp	The ROHC compressor to get information from
[in,out]	info	the structure where information will be stored

Returns:

Possible return values:

ROHC_OK in case of success,
ROHC_ERROR otherwise

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

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

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_segment 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_segment; rohc_decomp_set_mrru; rohc_decomp_get_mrru

int rohc_comp_get_segment	(	struct rohc_comp *const	comp,
		unsigned char *const	segment,
		const size_t	max_len,
		size_t *const	len
	)

Get the next ROHC segment if any.

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

Deprecated:: please do not use this function anymore, use rohc_comp_get_segment2() instead

Parameters:

	comp	The ROHC compressor
	segment	The buffer where to store the ROHC segment
	max_len	The maximum length (in bytes) of the buffer for the ROHC segment
[out]	len	The length (in bytes) of the ROHC segment

Returns:

Possible return values:

ROHC_NEED_SEGMENT if a ROHC segment is returned and more segments are available,
ROHC_OK if a ROHC segment is returned and no more ROHC segment is available
ROHC_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_decompress4 shall return
                        // ROHC_NON_FINAL_SEGMENT
                        ...

                        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_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_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_OK or ROHC_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

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

struct rohc_comp* rohc_comp_new	(	const rohc_cid_type_t	cid_type,
		const rohc_cid_t	max_cid
	)		`[read]`

Create a new ROHC compressor.

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

Deprecated:: do not use this function anymore, use rohc_comp_new2() instead

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

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_new 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_cb; rohc_comp_set_random_cb; 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_reset_rtp_ports; rohc_comp_add_rtp_port; rohc_comp_remove_rtp_port

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
	)		`[read]`

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_cb; 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

bool rohc_comp_piggyback_feedback	(	struct rohc_comp *const	comp,
		const unsigned char *const	feedback,
		const size_t	size
	)

Add a feedback packet to the next outgoing ROHC packet (piggybacking)

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and prepend feedback data yourself

Parameters:

comp	The ROHC compressor
feedback	The feedback data
size	The length of the feedback packet

Returns:: true in case of success, false otherwise

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

bool rohc_comp_remove_rtp_port	(	struct rohc_comp *const	comp,
		const unsigned int	port
	)

Remove a port from the list of UDP ports dedicated to RTP traffic.

If no function callback was defined for the detection of RTP streams, the detection is based on a list of UDP ports dedicated for RTP streams.

This function allows to update the list by removing the given UDP port to the list of UDP ports dedicated for RTP traffic.

Deprecated:: please do not use this function anymore, use rohc_comp_set_rtp_detection_cb() instead

Parameters:

comp	The ROHC compressor
port	The UDP port to remove

Returns:: true on success, false otherwise

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;
        }

        ...

        if(!rohc_comp_reset_rtp_ports(compressor))
        {
                fprintf(stderr, "failed to reset list of RTP ports\n");
                goto error;
        }

        if(!rohc_comp_add_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to enable RTP port 1234\n");
                goto error;
        }
        if(!rohc_comp_add_rtp_port(compressor, 10042))
        {
                fprintf(stderr, "failed to enable RTP port 10042\n");
                goto error;
        }

        if(!rohc_comp_remove_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to remove RTP port 1234\n");
                goto error;
        }

        ...

        rohc_comp_free(compressor);

See also:: rohc_comp_add_rtp_port; rohc_comp_reset_rtp_ports

bool rohc_comp_reset_rtp_ports ( struct rohc_comp *const comp )

Reset the list of dedicated RTP ports.

If no function callback was defined for the detection of RTP streams, the detection is based on a list of UDP ports dedicated for RTP streams.

This function allows to update the list by emptying the list of UDP ports dedicated for RTP traffic.

Deprecated:: please do not use this function anymore, use rohc_comp_set_rtp_detection_cb() instead

Parameters:

comp	The ROHC compressor

Returns:: true on success, false otherwise

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;
        }

        ...

        if(!rohc_comp_reset_rtp_ports(compressor))
        {
                fprintf(stderr, "failed to reset list of RTP ports\n");
                goto error;
        }

        if(!rohc_comp_add_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to enable RTP port 1234\n");
                goto error;
        }
        if(!rohc_comp_add_rtp_port(compressor, 10042))
        {
                fprintf(stderr, "failed to enable RTP port 10042\n");
                goto error;
        }

        if(!rohc_comp_remove_rtp_port(compressor, 1234))
        {
                fprintf(stderr, "failed to remove RTP port 1234\n");
                goto error;
        }

        ...

        rohc_comp_free(compressor);

See also:: rohc_comp_add_rtp_port; rohc_comp_remove_rtp_port

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

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:

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

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.

If segmentation is enabled and used by the compressor, the function rohc_comp_get_segment 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_segment; rohc_decomp_set_mrru

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

Set the timeout values 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

bool rohc_comp_set_random_cb	(	struct rohc_comp *const	comp,
		rohc_comp_random_cb_t	callback,
		void *const	user_context
	)

Set the user-defined callback for random numbers.

Set the user-defined callback for random numbers. The callback 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.

If no callback is defined, an internal one that always returns 0 will be defined for compatibility reasons.

Deprecated:: do not use this function anymore, use rohc_comp_new2() instead

Parameters:

comp	The ROHC compressor to set the random callback for
callback	The random callback to set
user_context	Private data that will be given to the callback, may be used as a context by user

Example:

/**
 * @brief Generate a random number
 *
 * @param comp          The ROHC compressor
 * @param user_context  Should always be NULL
 * @return              A random number
 */
static int gen_random_num(const struct rohc_comp *const comp,
                          void *const user_context)
{
        return rand();
}

...

        unsigned int seed;

        /* initialize the random generator */
        seed = time(NULL);
        srand(seed);

...

        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;
        }

...

        // set the callback for random numbers
        if(!rohc_comp_set_random_cb(compressor, gen_random_num, NULL))
        {
                fprintf(stderr, "failed to set the callback for random numbers\n");
                goto release_compressor;
        }

        ...

        rohc_comp_free(compressor);

See also:: rohc_comp_random_cb_t

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

bool rohc_comp_set_traces_cb	(	struct rohc_comp *const	comp,
		rohc_trace_callback_t	callback
	)

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; The callback set by this function is ignored if another callback is set with rohc_comp_set_traces_cb2

Deprecated:: do not use this function anymore, use rohc_comp_set_traces_cb2() instead

Parameters:

comp	The ROHC compressor
callback	Two possible cases: The callback function used to manage traces NULL to remove the previous callback

Returns:: true on success, false otherwise

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; The callback set by this function will remove any callback set set with rohc_comp_set_traces_cb

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

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 must be a power of 2; 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

int rohc_compress	(	struct rohc_comp *	comp,
		unsigned char *	ibuf,
		int	isize,
		unsigned char *	obuf,
		int	osize
	)

Compress the given uncompressed packet into a ROHC packet.

Deprecated:: do not use this function anymore, use rohc_compress4() instead

Parameters:

comp	The ROHC compressor
ibuf	The uncompressed packet to compress
isize	The size of the uncompressed packet
obuf	The buffer where to store the ROHC packet
osize	The size of the buffer for the ROHC packet

Returns:: The size of the ROHC packet in case of success, 0 in case of error

int rohc_compress2	(	struct rohc_comp *const	comp,
		const unsigned char *const	uncomp_packet,
		const size_t	uncomp_packet_len,
		unsigned char *const	rohc_packet,
		const size_t	rohc_packet_max_len,
		size_t *const	rohc_packet_len
	)

Compress the given uncompressed packet into a ROHC packet.

May return a full ROHC packet, or a segment of a ROHC packet if the output buffer was too small for the ROHC packet or if MRRU was exceeded. Use the rohc_comp_get_segment function to retrieve next ROHC segments.

Deprecated:: do not use this function anymore, use rohc_compress4() instead

Parameters:

	comp	The ROHC compressor
	uncomp_packet	The uncompressed packet to compress
	uncomp_packet_len	The size of the uncompressed packet
	rohc_packet	The buffer where to store the ROHC packet
	rohc_packet_max_len	The maximum length (in bytes) of the buffer for the ROHC packet
[out]	rohc_packet_len	The length (in bytes) of the ROHC packet

Returns:

ROHC_OK if a ROHC packet is returned
ROHC_NEED_SEGMENT if no compressed data is returned and segmentation required
ROHC_ERROR if an error occurred

int rohc_compress3	(	struct rohc_comp *const	comp,
		const struct rohc_ts	arrival_time,
		const unsigned char *const	uncomp_packet,
		const size_t	uncomp_packet_len,
		unsigned char *const	rohc_packet,
		const size_t	rohc_packet_max_len,
		size_t *const	rohc_packet_len
	)

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_OK and a full ROHC packet,
return ROHC_NEED_SEGMENT and no ROHC data if ROHC segmentation is required.

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_segment function to retrieve all the ROHC segments one by one.

Deprecated:: do not use this function anymore, use rohc_compress4() instead

Parameters:

	comp	The ROHC compressor
	arrival_time	The time at which packet was received (0 if unknown, or to disable time-related features in the ROHC protocol)
	uncomp_packet	The uncompressed packet to compress
	uncomp_packet_len	The size of the uncompressed packet
	rohc_packet	The buffer where to store the ROHC packet
	rohc_packet_max_len	The maximum length (in bytes) of the buffer for the ROHC packet
[out]	rohc_packet_len	The length (in bytes) of the ROHC packet

Returns:

Possible return values:

ROHC_OK if a ROHC packet is returned
ROHC_NEED_SEGMENT if no ROHC data is returned and ROHC segments can be retrieved with rohc_comp_get_segment
ROHC_ERROR if an error occurred

Example:

        struct rohc_comp *compressor;           /* the ROHC compressor */

        const struct rohc_ts arrival_time = { .sec = 0, .nsec = 0 };

        unsigned char ip_packet[BUFFER_SIZE];   // the buffer that will contain
                                                // the IPv4 packet to compress
        size_t ip_packet_len;                   // the length (in bytes) of the
                                                // IPv4 packet
        unsigned char rohc_packet[BUFFER_SIZE]; // the buffer that will contain
                                                // the resulting ROHC packet
        size_t rohc_packet_len;                 // the length (in bytes) of the
                                                // resulting ROHC packet
        ...

        ret = rohc_compress3(compressor, arrival_time, ip_packet, ip_packet_len,
                             rohc_packet, BUFFER_SIZE, &rohc_packet_len);

        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 of rohc_packet_len bytes 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_segment

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_OK and a full ROHC packet,
return ROHC_NEED_SEGMENT and no ROHC data if ROHC segmentation is required.

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_segment 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_segment
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 of rohc_packet_len bytes 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_segment

size_t rohc_feedback_avail_bytes ( const struct rohc_comp *const comp )

How many bytes of unsent feedback data are available at compressor?

How many bytes of unsent feedback data are available at compressor? It might be useful to know how many feedback data is waiting to be sent before flushing them with the rohc_feedback_flush function.

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and handle feedback data yourself

Parameters:

comp	The ROHC compressor

Returns:: The number of bytes of unsent feedback data, 0 if no unsent feedback data is available

See also:: rohc_feedback_flush

int rohc_feedback_flush	(	struct rohc_comp *	comp,
		unsigned char *	obuf,
		int	osize
	)

Send as much feedback data as possible.

Flush unsent feedback data as much as possible. Flushing stops either because there is no more unsent feedback data in compressor, or either because the given buffer is too small.

The rohc_feedback_flush function starts a transaction. The feedback data are not removed from the compressor's context when the function is called (they are only locked). There are two ways to close the transaction:

A call to the function rohc_feedback_remove_locked to tell the ROHC compressor that feedback bytes were successfully sent. The feedback data will be removed from the compressor's context.
A call to the function rohc_feedback_unlock to tell the ROHC compressor that feedback bytes failed to be sent successfully (eg. a temporary network problem). The feedback data will be unlocked but not removed from the compressor's context. This way, the compressor will try to send them again.

The rohc_feedback_avail_bytes function might be useful to flush only when a given amount of unsent feedback data is reached. It might be useful to correctly size the buffer given to rohc_feedback_flush.

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and send feedback data yourself

Parameters:

	comp	The ROHC compressor
[out]	obuf	The buffer where to store the feedback-only packet
	osize	The size of the buffer for the feedback-only packet

Returns:: The size of the feedback-only packet, 0 if there is no feedback data to send

See also:: rohc_feedback_remove_locked; rohc_feedback_unlock; rohc_feedback_avail_bytes

bool rohc_feedback_remove_locked ( struct rohc_comp *const comp )

Remove all feedbacks locked during the packet build.

Remove all feedbacks locked during the packet build from the compressor's context. A call to function rohc_feedback_remove_locked closes the transaction started by the function rohc_feedback_flush. It frees the compressor's internal memory related to feedback data once the feedback data was sent for sure.

If the feedback data failed to be sent correctly (eg. temporary network problem), then the feedback data shall not be removed but only unlocked with the rohc_feedback_unlock function. This way, feedback data could be sent again later.

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and handle feedback data yourself

Parameters:

comp	The ROHC compressor

Returns:: true if action succeeded, false in case of error

See also:: rohc_feedback_unlock; rohc_feedback_flush

bool rohc_feedback_unlock ( struct rohc_comp *const comp )

Unlock all feedbacks locked during the packet build.

Unlock all feedbacks locked during the packet build, but do not remove them from the compressor's context. A call to function rohc_feedback_unlock closes the transaction started by the function rohc_feedback_flush. It allows the compressor to send the unlocked feedback bytes again after the the program failed to send them correctly (eg. temporary network problem).

If the feedback data was sent successfully, then the feedback data shall not be unlocked, but removed with the rohc_feedback_remove_locked function. This way, feedback data will not be sent again later.

Deprecated:: please do not use this function anymore, instead use rohc_decompress3() and handle feedback data yourself

Parameters:

comp	The ROHC compressor

Returns:: true if action succeeded, false in case of error

See also:: rohc_feedback_remove_locked; rohc_feedback_flush

void rohc_free_compressor ( struct rohc_comp * comp )

Destroy one ROHC compressor.

Destroy a ROHC compressor that was successfully created with rohc_alloc_compressor

Deprecated:: do not use this function anymore, use rohc_comp_free() instead

Parameters:

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation