rohc_library

NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
BUGS
AVAILABILITY
AUTHORS
SEE ALSO
COLOPHON

NAME

rohc_library - The ROHC library

SYNOPSIS

#include <rohc/rohc.h>
#include <rohc/rohc_traces.h>
#include <rohc/rohc_profiles.h>
#include <rohc/rohc_packets.h>
#include <rohc/rohc_time.h>
#include <rohc/rohc_buf.h>
#include <rohc/rohc_comp.h>
#include <rohc/rohc_decomp.h>

DESCRIPTION

The RObust Header Compression (ROHC) library is an implementation of the ROHC protocol. See rohc_protocol(7) for details. It provides an easy and robust way for applications to reduce their bandwidth usage on network links with limited capacity or expensive costs. Headers of network packets are compressed with the ROHC protocol and algorithms.

The ROHC library is intended for developers who want to reduce the bandwidth requirements of their applications. The library is published under the LGPL license (version 2.1 or later).

The ROHC library supports both the ROHCv1 and ROHCv2 versions of the ROHC protocol.

The API of the ROHC library is divided into three parts: the common API, the compression API, and the decompression API.

The common API
The common API of the ROHC library allows a program to print the version of the ROHC library, or retrieve the description of ROHC modes and packets. No initialization is required. See rohc.h(3) for more details.

The compression API
The compression API of the ROHC library allows a program to compress the protocol headers of some uncompressed packets into ROHC packets. See rohc_comp.h(3) for more details.

The decompression API
The decompression API of the ROHC library allows a program to decompress some ROHC packets into uncompressed packets. See rohc_decomp.h(3) for more details.

EXAMPLE

The example code below creates a ROHC compressor, compresses an IP packet, then frees the ROHC compressor.

If the code is recorded in a file named example.c, the code can be compiled with the following command:

$ gcc −o example −Wall −g $( pkg−config −−cflags −−libs rohc ) example.c

Then the code can be executed as follow:

$ ./example
create the ROHC compressor
please define a callback for compressor traces
enable several ROHC compression profiles

build a fake IP packet
0x45 0x00 0x00 0x26 0x00 0x00 0x00 0x00
0x01 0x86 0xbe 0xef 0x01 0x02 0x03 0x04
0x05 0x06 0x07 0x08 0x68 0x65 0x6c 0x6c
0x6f 0x2c 0x20 0x52 0x4f 0x48 0x43 0x20
0x77 0x6f 0x72 0x6c 0x64 0x21

compress the fake IP packet
ROHC packet resulting from the ROHC compression:
0xfd 0x04 0x77 0x40 0x86 0x01 0x02 0x03
0x04 0x05 0x06 0x07 0x08 0x00 0x01 0x00
0x00 0x20 0x00 0x9d 0x56 0x68 0x65 0x6c
0x6c 0x6f 0x2c 0x20 0x52 0x4f 0x48 0x43
0x20 0x77 0x6f 0x72 0x6c 0x64 0x21

destroy the ROHC decompressor

The program ended successfully. The ROHC packet is larger than the IP packet
(39 bytes versus 38 bytes). This is expected since we only compress one packet
in this simple example. Keep in mind that ROHC is designed to compress streams
of packets not one single packet.

Example code:

#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <string.h>
#include <arpa/inet.h>

/* includes required to use the compression part of the ROHC library */
#include <rohc/rohc.h>
#include <rohc/rohc_comp.h>

/** The size (in bytes) of the buffers used in the program */
#define BUFFER_SIZE 2048

/** The payload for the fake IP packet */
#define FAKE_PAYLOAD "hello, ROHC world!"

/**
* @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();

}

/**
* @brief The main entry point for the simple ROHC program
*
* @param argc The number of arguments given to the program
* @param argv The table of arguments given to the program
* @return 0 in case of success, 1 otherwise
*/
int main(int argc, char **argv)
{

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);
unsigned int seed;
size_t i;
rohc_status_t status;
/* initialize the random generator */
seed = time(NULL);
srand(seed);
/* Create a ROHC compressor with small CIDs and the largest MAX_CID
* possible for small CIDs */
printf("create the ROHC compressor\n");
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;
}
/* Enable the compression profiles you need */
printf("enable several ROHC compression profiles\n");
if(!rohc_comp_enable_profiles(compressor,
ROHC_PROFILE_UNCOMPRESSED,
ROHC_PROFILE_IP,
ROHC_PROFILE_UDP,
ROHC_PROFILE_UDPLITE, −1))
{
	fprintf(stderr, "failed to enable the IP/UDP and IP/UDP−Lite "
	"profiles\n");
	goto release_compressor;
}
printf("\n");
/* create a fake IP packet for the purpose of this simple program */
printf("build a fake IP packet\n");
rohc_buf_byte_at(ip_packet, 0) = 4 << 4; /* IP version 4 */
rohc_buf_byte_at(ip_packet, 0) \|= 5; /* IHL: min. IPv4 header length
(in 32−bit words) */
rohc_buf_byte_at(ip_packet, 1) = 0; /* TOS */
ip_packet.len = 5 * 4 + strlen(FAKE_PAYLOAD);
rohc_buf_byte_at(ip_packet, 2) = (ip_packet.len >> 8) & 0xff; /* Total Length */
rohc_buf_byte_at(ip_packet, 3) = ip_packet.len & 0xff;
rohc_buf_byte_at(ip_packet, 4) = 0; /* IP−ID */
rohc_buf_byte_at(ip_packet, 5) = 0;
rohc_buf_byte_at(ip_packet, 6) = 0; /* Fragment Offset and IP flags */
rohc_buf_byte_at(ip_packet, 7) = 0;
rohc_buf_byte_at(ip_packet, 8) = 1; /* TTL */
rohc_buf_byte_at(ip_packet, 9) = 134; /* Protocol: unassigned number */
rohc_buf_byte_at(ip_packet, 10) = 0xa9; /* IP Checksum */
rohc_buf_byte_at(ip_packet, 11) = 0x3f;
rohc_buf_byte_at(ip_packet, 12) = 0x01; /* Source address */
rohc_buf_byte_at(ip_packet, 13) = 0x02;
rohc_buf_byte_at(ip_packet, 14) = 0x03;
rohc_buf_byte_at(ip_packet, 15) = 0x04;
rohc_buf_byte_at(ip_packet, 16) = 0x05; /* Destination address */
rohc_buf_byte_at(ip_packet, 17) = 0x06;
rohc_buf_byte_at(ip_packet, 18) = 0x07;
rohc_buf_byte_at(ip_packet, 19) = 0x08;
/* copy the payload just after the IP header */
memcpy(rohc_buf_data_at(ip_packet, 5 * 4), FAKE_PAYLOAD, strlen(FAKE_PAYLOAD));
/* dump the newly−created IP packet on terminal */
for(i = 0; i < ip_packet.len; i++)
{
	printf("0x%02x ", rohc_buf_byte_at(ip_packet, i));
	if(i != 0 && ((i + 1) % 8) == 0)
	{
		printf("\n");
	}
}
if(i != 0 && ((i + 1) % 8) != 0) /* be sure to go to the line */
{
	printf("\n");
}
printf("\n");
/* Now, compress this fake IP packet */
printf("compress the fake IP packet\n");
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) configuredef rohc_comp_set_mrru, the rohc_packet buffer contains the
	* with ef rohc_comp_get_segment can be used to
	* first ROHC segment and
	* retrieve the next ones. */
	fprintf(stderr, "compression of fake IP packet generated several ROHC "
	"segments\n");
	goto release_compressor;
}
else if(status == ROHC_STATUS_OK)
{
	/* success: compression succeeded, and resulting ROHC packet fits the
	* Maximum Reconstructed Reception Unit (MRRU) configured withef rohc_comp_set_mrru, the rohc_packet buffer contains the ROHC
	*
	* packet */
	/* dump the ROHC packet on terminal */
	printf("\nROHC packet resulting from the ROHC compression:\n");
	for(i = 0; i < rohc_packet.len; i++)
	{
		printf("0x%02x ", rohc_buf_byte_at(rohc_packet, i));
		if(i != 0 && ((i + 1) % 8) == 0)
		{
			printf("\n");
		}
	}
	if(i != 0 && ((i + 1) % 8) != 0) /* be sure to go to the line */
	{
		printf("\n");
	}
}
else
{
	/* compressor failed to compress the IP packet */
	fprintf(stderr, "compression of fake IP packet failed\n");
	goto release_compressor;
}
printf("\n\n");
/* Release the ROHC compressor when you do not need it anymore */
printf("destroy the ROHC decompressor\n");
rohc_comp_free(compressor);
printf("\n");
printf("The program ended successfully. The ROHC packet is larger than "
"the IP packet (39 bytes versus 38 bytes). This is expected since "
"we only compress one packet in this simple example. Keep in mind "
"that ROHC is designed to compress streams of packets not one "
"single packet.\n\n");
return 0;

release_compressor:

rohc_comp_free(compressor);

error:

	fprintf(stderr, "an error occurred during program execution, "
	"abort program\n");
	return 1;

}

BUGS

Bugs for the ROHC library are handled in the online bugtracker at https://bugs.launchpad.net/rohc

AVAILABILITY

Information on how to get the ROHC library and related information is available at the ROHC library website <https://rohc-lib.org/>.

AUTHORS

The ROHC library is the combined work of several hackers. See the AUTHORS file for the list of contributors.

All parts of the ROHC library package are protected by GNU copyleft licenses. All files are distributed under the terms of the GNU Lesser General Public License (LGPL) version 2.1 or later, including the documentation files. See the COPYING file for the full text of the license.

COLOPHON

This page is part of release 2.4.0 of the ROHC library project. A description of the project, and information about reporting bugs, can be found at https://rohc-lib.org/.