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

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_comprohc_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_comprohc_comp_new (const rohc_cid_type_t cid_type, const rohc_cid_t max_cid)
 Create a new ROHC compressor.
struct rohc_comprohc_comp_new2 (const rohc_cid_type_t cid_type, const rohc_cid_t max_cid, const rohc_comp_random_cb_t rand_cb, void *const rand_priv)
 Create a new ROHC compressor.
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:
compThe ROHC compressor
user_contextThe 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:
ipThe innermost IP packet
udpThe UDP header of the packet
payloadThe UDP payload of the packet
payload_sizeThe size of the UDP payload (in bytes)
rtp_privateA pointer to a memory area to be used by the callback function, may be NULL.
Returns:
true if the packet is an RTP packet, false otherwise
See also:
rohc_comp_set_rtp_detection_cb

Enumeration Type Documentation

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

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

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:
compThe ROHC compressor
packetThe feedback data
sizeThe 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:
compThe ROHC compressor
feedbackThe feedback data
sizeThe 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:
compThe ROHC compressor
profileThe 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_cidThe maximal CID value the compressor should use for contexts
jam_usenot used anymore, must be 0
adapt_sizenot used anymore, ignored
encap_sizenot 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:
bufferThe 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:
compThe 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.

Enable the ROHC compressor.

Deprecated:
do not use this function anymore, the ROHC compressor shall be considered always enabled now
Parameters:
compThe ROHC compressor
enable1 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:
compThe ROHC compressor
headerThe 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:
compThe ROHC compressor
large_cidWhether 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:
compThe ROHC compressor
valueThe 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:
compThe ROHC compressor
valueThe 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:
compThe ROHC compressor
indentThe indent level to beautify the XML output
bufferThe 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:
compThe 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:
compThe ROHC compressor
portThe 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:
compThe ROHC compressor
packetThe feedback data
sizeThe 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:
compThe ROHC compressor
feedbackThe feedback data
Returns:
true if the feedback was successfully taken into account, false if the feedback could not be taken into account
bool rohc_comp_disable_profile ( struct rohc_comp *const  comp,
const rohc_profile_t  profile 
)

Disable a compression profile for a compressor.

Disable a compression profile for a compressor.

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

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

Parameters:
compThe ROHC compressor
profileThe profile to disable
Returns:
true if the profile exists, false if the profile does not exist
See also:
rohc_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profiles
bool rohc_comp_disable_profiles ( struct rohc_comp *const  comp,
  ... 
)

Disable several compression profiles for a compressor.

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

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

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

Parameters:
compThe ROHC compressor
...The sequence of compression profiles to disable, the sequence shall be terminated by -1
Returns:
true if all of the profiles exist, false if at least one of the profiles does not exist
See also:
rohc_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profile
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:
compThe ROHC compressor
profileThe 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:
compThe ROHC compressor
...The sequence of compression profiles to enable, the sequence shall be terminated by -1
Returns:
true if all of the profiles exist, false if at least one of the profiles does not exist
Example:
        struct rohc_comp *compressor;           /* the ROHC compressor */
        ...
        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:
compThe 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:
compThe 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:
compThe ROHC compressor
[out]cid_typeThe current CID type among ROHC_SMALL_CID and ROHC_LARGE_CID
Returns:
true if the CID type was successfully retrieved, false otherwise
bool rohc_comp_get_general_info ( const struct rohc_comp *const  comp,
rohc_comp_general_info_t *const  info 
)

Get some general information about the compressor.

Get some general information about the compressor.

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

  • Major 0, minor 0

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

Parameters:
compThe ROHC compressor to get information from
[in,out]infoThe structure where information will be stored
Returns:
true in case of success, false otherwise
See also:
rohc_comp_general_info_t
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:
compThe ROHC compressor to get information from
[in,out]infothe structure where information will be stored
Returns:
Possible return values:
bool rohc_comp_get_last_packet_info2 ( const struct rohc_comp *const  comp,
rohc_comp_last_packet_info2_t *const  info 
)

Get some information about the last compressed packet.

Get some information about the last compressed packet.

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

  • Major 0, minor 0

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

Parameters:
compThe ROHC compressor to get information from
[in,out]infoThe structure where information will be stored
Returns:
true in case of success, false otherwise
See also:
rohc_comp_last_packet_info2_t
bool rohc_comp_get_max_cid ( const struct rohc_comp *const  comp,
size_t *const  max_cid 
)

Get the maximal CID value the compressor uses.

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

Parameters:
compThe ROHC compressor
[out]max_cidThe current maximal CID value
Returns:
true if MAX_CID was successfully retrieved, false otherwise
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:
compThe ROHC compressor
[out]mrruThe current MRRU value (in bytes)
Returns:
true if MRRU was successfully retrieved, false otherwise
Example:
        struct rohc_comp *comp;
        size_t mrru;
        ...
        /* retrieve current compressor MRRU */
        if(!rohc_comp_get_mrru(comp, &mrru))
        {
                fprintf(stderr, "failed to get MRRU for compressor\n");
                goto error;
        }
        printf("the current MMRU at compressor is %zu bytes\n", mrru);
        ...
See also:
rohc_comp_set_mrru
rohc_comp_get_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.

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:
compThe ROHC compressor
segmentThe buffer where to store the ROHC segment
max_lenThe maximum length (in bytes) of the buffer for the ROHC segment
[out]lenThe 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.

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

Give a description for the given ROHC compression context state.

Give a description for the given ROHC compression context state.

The descriptions are not part of the API. They may change between releases without any warning. Do NOT use them for other means that providing to users a textual description of compression context states used by the library. If unsure, ask on the mailing list.

Parameters:
stateThe compression context state to get a description for
Returns:
A string that describes the given compression context state
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_typeThe type of Context IDs (CID) that the ROHC compressor shall operate with. Accepted values are:
max_cidThe maximum value that the ROHC compressor should use for context IDs (CID). As CIDs starts with value 0, the number of contexts is max_cid + 1.
Accepted values are:
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_typeThe type of Context IDs (CID) that the ROHC compressor shall operate with. Accepted values are:
max_cidThe maximum value that the ROHC compressor should use for context IDs (CID). As CIDs starts with value 0, the number of contexts is max_cid + 1.
Accepted values are:
rand_cbThe random callback to set
rand_privPrivate data that will be given to the callback, may be used as a context by user
Returns:
The created compressor if successful, NULL if creation failed
Warning:
Don't forget to free compressor memory with rohc_comp_free if rohc_comp_new2 succeeded
Example:
        struct rohc_comp *compressor;           /* the ROHC compressor */
        ...
        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:
compThe ROHC compressor
feedbackThe feedback data
sizeThe 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:
compThe ROHC compressor
profileThe profile to ask status for
Returns:
Possible return values:
  • true if the profile exists and is enabled,
  • false if the compressor is not valid, the profile does not exist, or the profile is disabled
See also:
rohc_comp_enable_profile
rohc_comp_enable_profiles
rohc_comp_disable_profile
rohc_comp_disable_profiles
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:
compThe ROHC compressor
portThe 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:
compThe 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:
compThe ROHC compressor
featuresThe feature set to enable/disable
Returns:
true if the feature set was successfully enabled/disabled, false if a problem occurred
See also:
rohc_comp_features_t
bool rohc_comp_set_list_trans_nr ( struct rohc_comp *const  comp,
const size_t  list_trans_nr 
)

Set the number of uncompressed transmissions for list compression.

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

The L parameter is set to ROHC_LIST_DEFAULT_L by default.

Warning:
The value can not be modified after library initialization
Parameters:
compThe ROHC compressor
list_trans_nrThe number of times the list items or the list itself are sent uncompressed before being sent compressed
Returns:
true if the new value is accepted, false if the value is rejected
bool rohc_comp_set_mrru ( struct rohc_comp *const  comp,
const size_t  mrru 
)

Set the Maximum Reconstructed Reception Unit (MRRU).

Set the Maximum Reconstructed Reception Unit (MRRU).

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

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

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

Parameters:
compThe ROHC compressor
mrruThe new MRRU value (in bytes)
Returns:
true if the MRRU was successfully set, false otherwise
Example:
        struct rohc_comp *comp;
        size_t mrru = 500;
        ...
        /* set the MRRU at compressor */
        if(!rohc_comp_set_mrru(comp, mrru))
        {
                fprintf(stderr, "failed to set the MRRU at compressor\n");
                goto destroy_comp;
        }
        ...
See also:
rohc_comp_get_mrru
rohc_comp_get_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:
compThe ROHC compressor
ir_timeoutThe number of packets to compress before going back to IR state to force a context refresh
fo_timeoutThe number of packets to compress before going back to FO state to force a context refresh
Returns:
true in case of success, false in case of failure
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:
compThe ROHC compressor to set the random callback for
callbackThe random callback to set
user_contextPrivate 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:
compThe ROHC compressor
callbackThe callback function used to detect RTP packets The callback is deactivated if NULL is given as parameter
rtp_privateA pointer to an external memory area provided and used by the callback user
Returns:
true on success, false otherwise
Example:
/**
 * @brief The RTP detection callback which does detect RTP stream
 *
 * @param ip           The innermost IP packet
 * @param udp          The UDP header of the packet
 * @param payload      The UDP payload of the packet
 * @param payload_size The size of the UDP payload (in bytes)
 * @return             true if the packet is an RTP packet, false otherwise
 */
static bool rtp_detect(const unsigned char *const ip,
                       const unsigned char *const udp,
                       const unsigned char *const payload,
                       const unsigned int payload_size,
                       void *const rtp_private)
{
        uint16_t udp_dport;
        bool is_rtp;

        /* check UDP destination port */
        memcpy(&udp_dport, udp + 2, sizeof(uint16_t));
        if(ntohs(udp_dport) == 10042)
        {
                /* we think that the UDP packet is a RTP packet */
                fprintf(stderr, "RTP packet detected (expected UDP port)\n");
                is_rtp = true;
        }
        else
        {
                /* we think that the UDP packet is not a RTP packet */
                fprintf(stderr, "RTP packet not detected (wrong UDP port)\n");
                is_rtp = false;
        }

        return is_rtp;
}
        ...
        struct rohc_comp *compressor;           /* the ROHC compressor */
        ...
        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:
compThe ROHC compressor
callbackTwo 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:
compThe ROHC compressor
callbackTwo possible cases:
  • The callback function used to manage traces
  • NULL to remove the previous callback
priv_ctxtAn optional private context, may be NULL
Returns:
true on success, false otherwise
Example:
/**
 * @brief Callback to print traces of the ROHC library
 *
 * @param priv_ctxt  An optional private context, may be NULL
 * @param level      The priority level of the trace
 * @param entity     The entity that emitted the trace among:
 *                    \li ROHC_TRACE_COMP
 *                    \li ROHC_TRACE_DECOMP
 * @param profile    The ID of the ROHC compression/decompression profile
 *                   the trace is related to
 * @param format     The format string of the trace
 */
static void print_rohc_traces(void *const priv_ctxt,
                              const rohc_trace_level_t level,
                              const rohc_trace_entity_t entity,
                              const int profile,
                              const char *const format,
                              ...)
{
        va_list args;
        va_start(args, format);
        vfprintf(stdout, format, args);
        va_end(args);
}
        ...
        struct rohc_comp *compressor;           /* the ROHC compressor */
        ...
        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:
compThe ROHC compressor
widthThe 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:
compThe ROHC compressor
ibufThe uncompressed packet to compress
isizeThe size of the uncompressed packet
obufThe buffer where to store the ROHC packet
osizeThe 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:
compThe ROHC compressor
uncomp_packetThe uncompressed packet to compress
uncomp_packet_lenThe size of the uncompressed packet
rohc_packetThe buffer where to store the ROHC packet
rohc_packet_max_lenThe maximum length (in bytes) of the buffer for the ROHC packet
[out]rohc_packet_lenThe 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:

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:
compThe ROHC compressor
arrival_timeThe time at which packet was received (0 if unknown, or to disable time-related features in the ROHC protocol)
uncomp_packetThe uncompressed packet to compress
uncomp_packet_lenThe size of the uncompressed packet
rohc_packetThe buffer where to store the ROHC packet
rohc_packet_max_lenThe maximum length (in bytes) of the buffer for the ROHC packet
[out]rohc_packet_lenThe length (in bytes) of the ROHC packet
Returns:
Possible return values:
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:

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:
compThe ROHC compressor
uncomp_packetThe uncompressed packet to compress
[out]rohc_packetThe resulting compressed ROHC packet
Returns:
Possible return values:
Example:
        struct rohc_comp *compressor;           /* the ROHC compressor */
        /* the buffer that will contain the IPv4 packet to compress */
        unsigned char ip_buffer[BUFFER_SIZE];
        struct rohc_buf ip_packet = rohc_buf_init_empty(ip_buffer, BUFFER_SIZE);
        /* the buffer that will contain the resulting ROHC packet */
        unsigned char rohc_buffer[BUFFER_SIZE];
        struct rohc_buf rohc_packet = rohc_buf_init_empty(rohc_buffer, BUFFER_SIZE);
        ...
        status = rohc_compress4(compressor, ip_packet, &rohc_packet);
        if(status == ROHC_STATUS_SEGMENT)
        {
                /* success: compression succeeded, but resulting ROHC packet was too
                 * large for the Maximum Reconstructed Reception Unit (MRRU) configured
                 * with \ref rohc_comp_set_mrru, the rohc_packet buffer contains the
                 * first ROHC segment 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:
compThe 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:
compThe ROHC compressor
[out]obufThe buffer where to store the feedback-only packet
osizeThe 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:
compThe 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:
compThe 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:
compThe 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