1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
/*
* Copyright (C) 2009-2010 Mamadou Diop.
*
* Contact: Mamadou Diop <diopmamadou(at)doubango.org>
*
* This file is part of Open Source Doubango Framework.
*
* DOUBANGO is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* DOUBANGO is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with DOUBANGO.
*
*/
/**@file tcomp.c
* @brief SigComp (RFC 3320) Implementation for 2.5G and 3G cellular networks.
*
* @author Mamadou Diop <diopmamadou(at)yahoo.fr>
*
* @date Created: Sat Nov 8 16:54:58 2009 mdiop
*/
#include "tcomp.h"
/** @mainpage tinySigComp API Overview
*
* This file is an overview of <b>tinySigComp</b> API.
*
* <b>tinySigComp</b> is a tiny but fully featured SigComp implementation for 2.5G, 3G and 4G cellular networks. This library is also used in Doubango project to provide SigComp
* support for 3GPP IMS and OMA networks.
* This API is designed to efficiently work on embedded systems whith limited memory and low computing power.
*
* As many operators have begun to commercially deploy IMS, the relevance of using SigComp to lower bandwidth usage will come quickly.
* In my own opinion I think that most operators (especially those using RCS) will question how to reduce SIP signaling (registration, billing, presence, messaging …)
* bandwidth usage (who will pay bits?).
* These questions will especially concern using SIP (or all other text-based protocols) in wireless handsets as part of 2.5G, 3G and 4G cellular networks.
*
* SigComp stands for Signaling Compression and has been defined in <a href="http://www.ietf.org/rfc/rfc3320.txt">RFC 3320</a> by the Internet Engineering Task Force (IETF) ROHC working group.
* <br> <br>
*
* @image html SigComp_Architecture.png "SigComp Architecture"
*
* Many application protocols used for multimedia communications are text-based and engineered for bandwidth rich links. As a result the messages have not been optimized in
* terms of size. For example, typical IMS/SIP messages range from a few hundred bytes up to two thousand bytes or more. For this reason, SigComp is mandatory for
* 3GPP IMS netwoks and <a href="http://en.wikipedia.org/wiki/Push_to_Talk_over_Cellular">PoC systems</a>.
*
* SigComp could also be useful for RCS (Rich Communication Suite) networks because of the size of the SIP packets (more than three thousand bytes for presence publication).
* Using SigComp in IMS/RCS context will reduce the round-trip over slow radio links.
*
* @par Supported OS
*
* - Windows XX/Vista (Visual Studio 2005/2008 or Mingw32)
* - Windows Mobile 5 and later (Visual Studio 2005/2008 or Mingw32ce/cegcc toolchain)
* - Symbian S60 (Carbide.c++ v2.0 with S60_3rd_FP2_SDK_v1.1)
* - Google Android
* - Mac OS X, iPhone (Xcode)
* - All Linux, FreeBSD, ... (GCC 4.x)
*
*
* @par FEATURES
*
* The goal of this project is to provide a SigComp framework which:
*
* - Could be used as an external API or Framework
* - Highly portable (Coded in ANSI-C without any external dependencies)
* - Easily configurable (memory usage, priorities in static dictionaries, stateful/stateless modes, dynamic/static/shared compression types …)
* - Easy to integrate with any existing SIP/IMS stack, Proxy-CSCF, PoC client …
* - Allow to easily plug your own compressor (DEFLATE – RFC 1951- will be the default)
* -
* - Robust
* - Efficiently run on mobile handsets (small footprint)
* - Use small memory (UDVM decompression)
* - Run fast without high CPU usage
* - Supports both TCP and UDP compression modes
* - Thread-safe
*
* @par COMPLIANCE
*
* - <a href="http://www.ietf.org/rfc/rfc3320.txt">RFC 3320</a>: Signaling Compression (SigComp)
* - <a href="http://www.ietf.org/rfc/rfc3321.txt">RFC 3321</a>: Signaling Compression (SigComp) - Extended Operations
* - <a href="http://www.ietf.org/rfc/rfc3485.txt">RFC 3485</a>: The Session Initiation Protocol (SIP) and Session Description Protocol (SDP) Static Dictionary for Signaling Compression (SigComp)
* - <a href="http://www.ietf.org/rfc/rfc4077.txt">RFC 4077</a>: A Negative Acknowledgement Mechanism for Signaling Compression
* - <a href="http://www.ietf.org/rfc/rfc4464.txt">RFC 4464</a>: Signaling Compression (SigComp) Users' Guide
* - <a href="http://www.ietf.org/rfc/rfc4465.txt">RFC 4465</a>: Signaling Compression (SigComp) Torture Tests
* - <a href="http://www.ietf.org/rfc/rfc4896.txt">RFC 4896</a>: Signaling Compression (SigComp) Corrections and Clarifications
* - <a href="http://www.ietf.org/rfc/rfc5049.txt">RFC 5049</a>: Applying Signaling Compression (SigComp) to the Session Initiation Protocol (SIP)
* - <a href="http://www.ietf.org/rfc/rfc5112.txt">RFC 5112</a>: The Presence-Specific Static Dictionary for Signaling Compression (Sigcomp)
* - <a href="http://www.ietf.org/rfc/rfc1662.txt">RFC 1662</a>: PPP in HDLC-like Framing
* - <a href="http://www.ietf.org/rfc/rfc1951.txt">RFC 1951</a>: DEFLATE Compressed Data Format Specification version
* - <a href="http://www.ietf.org/rfc/rfc3174.txt">RFC 3174</a>: US Secure Hash Algorithm 1 (SHA1)
* - 3GPP TR23.979 Annex C: Required SigComp performance
*
* @par Getting started
*
* - @ref tcomp_udp_compression_page
* - @ref tcomp_udp_decompression_page
*/
/** @page tcomp_udp_compression_page SigComp UDP compression
* It is easy to compress SIP a message and send it over UDP connection. The compression can be safely done in multithreaded appilaction because
* <a href ="http://doubango.org/API/tinySigComp/">tinySigComp</a> is thread-safe.
* You need <a href ="http://doubango.org/API/tinySAK/">tinySAK</a> in order to compile the code below.
*
* Include header files:
* @code
* #include "tsk_debug.h" // tinySAK debugging functions.
* #include "tcomp_manager.h" // tinySigComp API functions.
* @endcode
*
* Compartment Identifier: Used in SIP messages (sigomp-id) and tinySigComp to allocate/deallocate memory associated
* to a compartment.
* @code
* #define COMPARTMENT_ID "urn:uuid:2e5fdc76-00be-4314-8202-1116fa82a475"
* @endcode
*
* Preparation:
* @code
* #define MAX_BUFFER_SIZE 0xFFFF
*
* int i = 0;
* tsk_size_t outLen = 0;
* tcomp_result_t *result = 0;
* char outputBuffer[MAX_BUFFER_SIZE];
*
* tcomp_manager_handle_t *manager = 0;
* // Create SigComp manager
* manager = TCOMP_MANAGER_CREATE();
* // Add SIP/Presence dictionnaries (not mandatory)
* tcomp_manager_addSipSdpDictionary(manager);
* tcomp_manager_addPresenceDictionary(manager);
* // Create result object and set compartment id --> It is recomanded to use one result object per manager.
* result = TCOMP_RESULT_CREATE();
* tcomp_result_setCompartmentId(result, COMPARTMENT_ID, strlen(COMPARTMENT_ID));
* // Set user parameters (not mandatory)
* tcomp_manager_setDecompression_Memory_Size(manager, 8192);
* tcomp_manager_setCycles_Per_Bit(manager, 64);
* tcomp_manager_setState_Memory_Size(manager, 8192);
*
* @endcode
* Compress one or several messages using the code below:
* @code
* // Compress the SIP message
* outLen = tcomp_manager_compress(manager,
* COMPARTMENT_ID, strlen(COMPARTMENT_ID), // Compartment
* "REGISTER ...", strlen("REGISTER ..."), // Sip message to compress and it's size
* outputBuffer, sizeof(outputBuffer), // The ouptut buffer and it's size
* FALSE // Indicates whether to compress as stream (SCTP, TCP...) message or not
* );
*
* if(outLen){
* // send SigComp message over UDP connection
* sendto(sock, outputBuffer, outLen , 0, (SOCKADDR *)address, sizeof(address));
* }
* else{
* // MUST never happen.
* }
* @endcode
* To safely release all resources:
* @code
* // Close the compartment
* tcomp_manager_closeCompartment(manager, COMPARTMENT_ID, strlen(COMPARTMENT_ID));
* // Delete the result object
* TSK_OBJECT_SAFE_FREE(result);
* // Delete the manager
* TSK_OBJECT_SAFE_FREE(manager);
* @endcode
*/
/** @page tcomp_udp_decompression_page SigComp UDP decompression
* Decompression is as easy as compression (thread-safe).
*/
|
