User Tools

Site Tools


library-first-application

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

library-first-application [2016/01/03 20:12]
didier [Note about licencing] update for LGPL
library-first-application [2016/08/27 20:01] (current)
didier redirect to the tutorial on the website
Line 1: Line 1:
-======== How to use the ROHC library in your own program? ======== +See the [[https://​rohc-lib.org/​presentation/getting-started/|getting started tutorial]] on the website.
- +
-Follow this procedure in order to know how to use the ROHC library in your own program. +
- +
- +
-===== Preparation ===== +
- +
-==== Installing the ROHC library ==== +
- +
-If not done yet, [[library-install|install the library]]. +
- +
-==== Documentation ==== +
- +
-While following this tutorial, keep a look at the [[library-api|online API documentation]]. +
- +
-==== Note about licencing ==== +
- +
-**For all versions up to 1.6.x:** the ROHC library is published under the GPL license version 2 or later. The GPL license requires any derivative work to be published under the GPL. Any program that uses the ROHC library must therefore be distributed under the GPL licence. +
- +
-**For all versions since 1.7.0:** The ROHC library is published under the LGPL license version 2.1 or later. The LGPL license requires any derivative work to be published under the LGPL **only if the library is used as a static library**. Any program that uses the ROHC library as a static library must therefore be distributed under the LGPL licence, but **any program that uses the ROHC library as a shared library may be distributed under any licence (even proprietary)**. +
- +
-==== A directory for your application ==== +
- +
-Create a directory to host the code you are going to write during this tutorial:<​code>​ +
-$ mkdir $HOME/​rohc_first_application +
-</​code>​ +
- +
-Create a file ''​myprogram.c''​ with your favorite text editor (vim, emacs, gedit, kate...):<​code>​ +
-$ cd $HOME/​rohc_first_application +
-$ vim rohc_first_application.c +
-</​code>​ +
- +
- +
- +
-===== Using the ROHC compressor ===== +
- +
-==== Library headers ==== +
- +
-First, include the following ROHC headers to use one or more ROHC compressor in ''​rohc_first_application.c''<​code c> +
-#include <​rohc.h>​ +
-#include <​rohc_comp.h>​ +
-</​code>​ +
- +
-==== Create a ROHC compressor ==== +
- +
-Then, create a ROHC compressor with small CIDs (last 3 parameters are deprecated, always set them to 0):<code c> +
-comp = rohc_alloc_compressor(ROHC_SMALL_CID_MAX,​ 0, 0, 0); +
-if(comp == NULL) +
-+
-    fprintf(stderr,​ "​cannot create the ROHC compressor\n"​);​ +
-    /* manage the error here */ +
-+
-</​code>​ +
- +
-Refer to the API documentation to get more information about the arguments of +
-the [[http://​rohc-lib.org/​doc/rohc-doc-1.6.0/group__rohc__comp.html#​ga721fd34fc0cd9e1d789b693eb6bb6485|rohc_alloc_compressor() function]]+
- +
-==== Enable the compression profiles ==== +
- +
-**This API is available for versions >= 1.7.0 only.** +
- +
-**Do not enable the TCP profile for versions 1.7.x in production environments,​ the profile is not stable enough. Switch to a >= 2.0.0 version.** +
- +
-Then, enable the compression profiles you need (choose a subset of the ''​ROHC_PROFILE_''​ constants, end the list with ''​-1''​):<​code c> +
-bool status; +
- +
-status = rohc_comp_enable_profiles(comp,​ +
-                                   ​ROHC_PROFILE_UNCOMPRESSED,​ +
-                                   ​ROHC_PROFILE_UDP,​ +
-                                   ​ROHC_PROFILE_IP,​ +
-                                   ​ROHC_PROFILE_UDPLITE,​ +
-                                   ​ROHC_PROFILE_RTP,​ +
-                                   ​ROHC_PROFILE_ESP,​ +
-                                   ​ROHC_PROFILE_TCP,​ -1); +
-if(!status) +
-+
-    fprintf(stderr,​ "​failed to enable the compression profiles\n"​);​ +
-    /* manage the error here */ +
-+
-</​code>​ +
- +
- +
-==== Compress a IP packet ==== +
- +
-Then, you may compress as many IP packets as you want. +
- +
-For versions < 1.7.0:<​code c> +
-const size_t max_size = 2048; +
-unsigned char ip_packet[max_size];​ +
-size_t ip_packet_len;​ +
-unsigned char rohc_packet[max_size];​ +
-size_t rohc_packet_len;​ +
-int ret; +
- +
-/* read the IP packet somewhere, store it in the buffer named '​ip_packet',​ +
-   set its length in the '​ip_packet_len'​ variable */ +
- +
-ret = rohc_compress2(comp,​ +
-                     ​ip_packet,​ ip_packet_len,​ +
-                     ​rohc_packet,​ max_size, &​rohc_packet_len);​ +
-if(ret != ROHC_OK) +
-+
-   ​fprintf(stderr,​ "​compression of packet failed\n"​);​ +
-   /* manage the error here */ +
-}</​code>​ +
- +
-For versions >= 1.7.0:<​code c> +
-struct timespec arrival_time = { .tv_sec = 0, .tv_nsec = 0 }; +
-const size_t max_size = 2048; +
-unsigned char ip_packet[max_size];​ +
-size_t ip_packet_len;​ +
-unsigned char rohc_packet[max_size];​ +
-size_t rohc_packet_len;​ +
-int ret; +
- +
-/* read the IP packet somewhere, store it in the buffer named '​ip_packet',​ +
-   set its length in the '​ip_packet_len'​ variable, and optionally set its +
-   ​arrival timestamp in the '​arrival_time'​ variable */ +
- +
-ret = rohc_compress3(comp,​ arrival_time,​ +
-                     ​ip_packet,​ ip_packet_len,​ +
-                     ​rohc_packet,​ max_size, &​rohc_packet_len);​ +
-if(ret != ROHC_OK) +
-+
-   ​fprintf(stderr,​ "​compression of packet failed\n"​);​ +
-   /* manage the error here */ +
-}</​code>​ +
- +
-The compressed ROHC packet is now available in the ''​rohc_packet''​ buffer. Its length is stored in the ''​rohc_packet_len''​ variable. +
- +
-==== Destroy the ROHC compressor ==== +
- +
-At program shutdown, do not forget to free the created compressor:<​code c> +
-rohc_free_compressor(comp);</​code>​ +
- +
-==== Build your application ==== +
- +
-Now, build your program:<​code>​ +
-$ gcc -o rohc_first_application -g -Wall \ +
-    $(pkg-config rohc --cflags) \ +
-    rohc_first_application.c \ +
-    $(pkg-config rohc --libs )</​code>​ +
- +
-And, test your program:<​code>​ +
-$ ./​rohc_first_application</​code>​ +
- +
- +
-Several [[https://​github.com/​didier-barvaux/​rohc/​tree/​master/​examples|examples]] are also available in the sources. +
- +
-**Note:** if you didn't install the ROHC library in the ''/​usr''​ directory (option ''​%%--prefix=<​basedir>​%%''​ for ''​configure''​ script during installation),​ then you must adapt the command that builds the program in consequence:<​code>​ +
-$ gcc -o rohc_first_application -g -Wall \ +
-   $( PKG_CONFIG_PATH=/<​basedir>/​lib/​pkgconfig/​ pkg-config rohc --cflags ) \ +
-   ​rohc_first_application.c \ +
-   $( PKG_CONFIG_PATH=/<​basedir>/​lib/​pkgconfig/​ pkg-config rohc --libs )</​code>​ +
- +
- +
-===== Using the ROHC decompressor ===== +
- +
-==== Library headers ==== +
- +
-First, include the following ROHC headers to use one or more ROHC decompressor in your program:<​code c> +
-#include <​rohc.h>​ +
-#include <​rohc_decomp.h></​code>​ +
- +
-==== Create a ROHC decompressor ==== +
- +
-Then, create a ROHC decompressor:<​code c> +
-decomp = rohc_alloc_decompressor(NULL);​ +
-if(decomp == NULL) +
-+
-    fprintf(stderr,​ "​cannot create the ROHC decompressor\n"​);​ +
-    /* manage the error here */ +
-}</​code>​ +
- +
-As you passed ''​NULL''​ as the first argument of the ''​rohc_alloc_decompressor()''​ function, you created a standalone ROHC decompressor that is not associated with any compressor. So, the ROHC library is running in unidirectional mode. To use the library in bidirectional mode, create a ROHC decompressor as above but associate it with an already created ROHC compressor:<​code c> +
-decomp = rohc_alloc_decompressor(existing_comp);​ +
-if(decomp == NULL) +
-+
-    fprintf(stderr,​ "​cannot create the ROHC decompressor\n"​);​ +
-    /* manage the error here */ +
-}</​code>​ +
- +
-==== Enable the decompression profiles ==== +
- +
-**This API is available for versions >= 1.7.0 only.** +
- +
-**Do not enable the TCP profile for versions 1.7.x in production environments,​ the profile is not stable enough. Switch to a >= 2.0.0 version.** +
- +
-Then, enable the decompression profiles you need (choose a subset of the ''​ROHC_PROFILE_''​ constants, end the list with ''​-1''​):<​code c> +
-bool status; +
- +
-status = rohc_decomp_enable_profiles(decomp,​ +
-                                     ​ROHC_PROFILE_UNCOMPRESSED,​ +
-                                     ​ROHC_PROFILE_UDP,​ +
-                                     ​ROHC_PROFILE_IP,​ +
-                                     ​ROHC_PROFILE_UDPLITE,​ +
-                                     ​ROHC_PROFILE_RTP,​ +
-                                     ​ROHC_PROFILE_ESP,​ +
-                                     ​ROHC_PROFILE_TCP,​ -1); +
-if(!status) +
-+
-    fprintf(stderr,​ "​failed to enable the decompression profiles\n"​);​ +
-    /* manage the error here */ +
-+
-</​code>​ +
- +
- +
-==== Decompress a ROHC packet ==== +
- +
-Then, you may decompress as many ROHC packets as you want. +
- +
-For versions < 1.7.0:<​code c> +
-const size_t max_size = 2048; +
-unsigned char rohc_packet[max_size];​ +
-size_t rohc_packet_len;​ +
-unsigned char ip_packet[max_size];​ +
-int ip_packet_len;​ +
- +
-/* read the ROHC packet somewhere, store it in the buffer named '​rohc_packet',​ +
-   set its length in the '​rohc_packet_len'​ variable */ +
- +
-ip_packet_len = rohc_decompress(decomp,​ +
-                                rohc_packet,​ rohc_packet_len,​ +
-                                ip_packet, max_size);​ +
-if(ip_packet_len == ROHC_FEEDBACK_ONLY) +
-+
-    /* the ROHC packet contained feedback only, so there is no +
-       ​decompressed IP data */ +
-    /* manage this special case here, do not treat it as an error */ +
-+
-else if(ip_packet_len == ROHC_NON_FINAL_SEGMENT) +
-+
-    /* the ROHC data contained a part of a ROHC packet, ie. a ROHC +
-       ​segment,​ so there is no decompressed IP data */ +
-    /* manage this special case here, do not treat it as an error */ +
-+
-else if(ip_packet_len <= 0) +
-+
-    fprintf(stderr,​ "​decompression of packet failed\n"​);​ +
-    /* manage the error here */ +
-}</​code>​ +
- +
- +
-For versions >= 1.7.0:<​code c> +
-struct timespec arrival_time = { .tv_sec = 0, .tv_nsec = 0 }; +
-const size_t max_size = 2048; +
-unsigned char rohc_packet[max_size];​ +
-size_t rohc_packet_len;​ +
-unsigned char ip_packet[max_size];​ +
-size_t ip_packet_len;​ +
-int ret; +
- +
-/* read the ROHC packet somewhere, store it in the buffer named '​rohc_packet',​ +
-   set its length in the '​rohc_packet_len'​ variable, and optionally set its +
-   ​arrival timestamp in the '​arrival_time'​ variable */ +
- +
-ret = rohc_decompress2(decomp,​ arrival_time,​ +
-                       ​rohc_packet,​ rohc_packet_len,​ +
-                       ​ip_packet,​ max_size, &​ip_packet_len);​ +
-if(ret == ROHC_FEEDBACK_ONLY) +
-+
-    /* the ROHC packet contained feedback only, so there is no +
-       ​decompressed IP data */ +
-    /* manage this special case here, do not treat it as an error */ +
-+
-else if(ret == ROHC_NON_FINAL_SEGMENT) +
-+
-    /* the ROHC data contained a part of a ROHC packet, ie. a ROHC +
-       ​segment,​ so there is no decompressed IP data */ +
-    /* manage this special case here, do not treat it as an error */ +
-+
-else if(ret != ROHC_OK) +
-+
-    fprintf(stderr,​ "​decompression of packet failed\n"​);​ +
-    /* manage the error here */ +
-}</​code>​ +
- +
-The decompressed IP packet is now available in the ''​ip_packet''​ buffer. Its length is stored in the ''​ip_packet_len''​ variable. +
- +
-==== Destroy the ROHC decompressor ==== +
- +
-At program shutdown, do not forget to free the created decompressor:<​code c> +
-rohc_free_decompressor(decomp);</​code>​ +
- +
-==== Build your application ==== +
- +
-Now, build your program:<​code>​ +
-$ gcc -o rohc_first_application -g -Wall \ +
-    $(pkg-config rohc --cflags) \ +
-    rohc_first_application.c \ +
-    $(pkg-config rohc --libs )</​code>​ +
- +
-And, test your program:<​code>​ +
-$ ./​rohc_first_application</​code>​ +
- +
-**Note:** if you didn't install the ROHC library in the ''/​usr''​ directory (option ''​%%--prefix=<​basedir>​%%''​ for ''​configure''​ script during installation),​ then you must adapt the command that builds the program in consequence:<​code>​ +
-$ gcc -o rohc_first_application -g -Wall \ +
-   $( PKG_CONFIG_PATH=/<​basedir>/​lib/​pkgconfig/​ pkg-config rohc --cflags ) \ +
-   ​rohc_first_application.c \ +
-   $( PKG_CONFIG_PATH=/<​basedir>/​lib/​pkgconfig/​ pkg-config rohc --libs )</​code>​ +
- +
- +
- +
-===== Getting help ===== +
- +
-To get help, ask your question ​on the [[http://​lists.launchpad.net/​rohc/​|mailing list]]. +
library-first-application.txt · Last modified: 2016/08/27 20:01 by didier