linphone_tunnel.h 14.8 KB
Newer Older
Guillaume Beraudo's avatar
Guillaume Beraudo committed
1
/***************************************************************************
jehan's avatar
jehan committed
2
 *            linphone_tunnel.h
Guillaume Beraudo's avatar
Guillaume Beraudo committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
 *
 *  Fri Dec 9, 2011
 *  Copyright  2011  Belledonne Communications
 *  Author: Guillaume Beraudo
 *  Email: guillaume dot beraudo at linphone dot org
 ****************************************************************************/

/*
 *  This program 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 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program 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 this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */
25

26 27
#ifndef LINPHONETUNNEL_H
#define LINPHONETUNNEL_H
Guillaume Beraudo's avatar
Guillaume Beraudo committed
28 29 30

#include "linphonecore.h"

jehan's avatar
jehan committed
31

jehan's avatar
jehan committed
32 33 34
/**
 * @addtogroup tunnel
 * @{
35 36
**/

jehan's avatar
jehan committed
37
	/**
jehan's avatar
jehan committed
38 39 40 41 42 43
	 * Linphone tunnel aims is to bypass IP traffic blocking due to aggressive firewalls which typically only authorize TCP traffic with destination port 443.
	 * <br> Its principle is tunneling all SIP and/or RTP traffic through a single secure https connection up to a detunnelizer server.
	 * <br> This set of methods enhance  LinphoneCore functionalities in order to provide an easy to use API to
	 * \li provision tunnel servers IP addresses and ports. This functionality is an option not implemented under GPL. Availability can be check at runtime using function #linphone_core_tunnel_available
	 * \li start/stop the tunneling service
	 * \li perform auto-detection whether tunneling is required, based on a test of sending/receiving a flow of UDP packets.
jehan's avatar
jehan committed
44 45 46
	 *
	 * It takes in charge automatically the SIP registration procedure when connecting or disconnecting to a tunnel server.
	 * No other action on LinphoneCore is required to enable full operation in tunnel mode.
jehan's avatar
jehan committed
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
	 *
	 * <br> Provision is done using object #LinphoneTunnelConfig created by function #linphone_tunnel_config_new(). Functions #linphone_tunnel_config_set_host
	 *  and #linphone_tunnel_config_set_port allow to point to tunnel server IP/port. Once set, use function #linphone_tunnel_add_server to provision a tunnel server.
	 *  <br> Finally  tunnel mode configuration is achieved by function #linphone_tunnel_set_mode.
	 *  <br> Tunnel connection status can be checked using function #linphone_tunnel_connected.
	 *
	 * Bellow pseudo code that can be use to configure, enable, check state and disable tunnel functionality:
	 *
	 * \code
	LinphoneTunnel *tunnel = linphone_core_get_tunnel(linphone_core);
	LinphoneTunnelConfig *config=linphone_tunnel_config_new(); //instantiate tunnel configuration
	linphone_tunnel_config_set_host(config, "tunnel.linphone.org"); //set tunnel server host address
	linphone_tunnel_config_set_port(config, 443); //set tunnel server port
	linphone_tunnel_add_server(tunnel, config); //provision tunnel config
	linphone_tunnel_set_mode(tunnel, LinphoneTunnelModeEnable); //activate the tunnel unconditional

	while (!linphone_tunnel_connected(tunnel)) { //wait for tunnel to be ready
		linphone_core_iterate(linphone_core); //schedule core main loop
		ms_sleep(100); //wait 100ms
	}

	LinphoneCall *call = linphone_core_invite(linphone_core,"sip:foo@example.org"); //place an outgoing call
	linphone_call_ref(call); //acquire a reference on the call to avoid deletion after completion
	//...
	linphone_core_terminate_call(linphone_core,call);

	while (linphone_call_get_state(call) != LinphoneCallReleased) { //wait for call to be in release state
		linphone_core_iterate(linphone_core); //schedule core main loop
		ms_sleep(100); //wait 100ms
	}

	linphone_tunnel_set_mode(tunnel, LinphoneTunnelModeDisable); //deactivate tunnel
	linphone_call_unref(call); //release reference on the call

	\endcode
*
*	**/
jehan's avatar
jehan committed
84

Guillaume Beraudo's avatar
Guillaume Beraudo committed
85 86 87 88 89
#ifdef __cplusplus
extern "C"
{
#endif

90 91
typedef struct _LinphoneTunnelConfig LinphoneTunnelConfig;

92 93 94
/**
 * Enum describing the tunnel modes.
**/
95
typedef enum _LinphoneTunnelMode {
96 97 98
	LinphoneTunnelModeDisable,	/**< The tunnel is disabled. */
	LinphoneTunnelModeEnable,	/**< The tunnel is enabled. */
	LinphoneTunnelModeAuto	/**< The tunnel is enabled automatically if it is required. */
99 100
} LinphoneTunnelMode;

François Grisez's avatar
François Grisez committed
101
/**
102
 * Convert a string into LinphoneTunnelMode enum
François Grisez's avatar
François Grisez committed
103 104 105 106
 * @param string String to convert
 * @return An LinphoneTunnelMode enum. If the passed string is NULL or
 * does not match with any mode, the LinphoneTunnelModeDisable is returned.
 */
107
LINPHONE_PUBLIC LinphoneTunnelMode linphone_tunnel_mode_from_string(const char *string);
François Grisez's avatar
François Grisez committed
108 109

/**
110
 * Convert a tunnel mode enum into string
François Grisez's avatar
François Grisez committed
111 112 113
 * @param mode Enum to convert
 * @return "disable", "enable" or "auto"
 */
114
LINPHONE_PUBLIC const char *linphone_tunnel_mode_to_string(LinphoneTunnelMode mode);
François Grisez's avatar
François Grisez committed
115

jehan's avatar
jehan committed
116
/**
117
 * Create a new tunnel configuration
jehan's avatar
jehan committed
118
 */
119
LINPHONE_PUBLIC LinphoneTunnelConfig *linphone_tunnel_config_new(void);
120

jehan's avatar
jehan committed
121
/**
122 123 124
 * Set the IP address or hostname of the tunnel server.
 * @param tunnel LinphoneTunnelConfig object
 * @param host The tunnel server IP address or hostname
125
 */
126
LINPHONE_PUBLIC void linphone_tunnel_config_set_host(LinphoneTunnelConfig *tunnel, const char *host);
127 128

/**
129 130 131
 * Get the IP address or hostname of the tunnel server.
 * @param tunnel LinphoneTunnelConfig object
 * @return The tunnel server IP address or hostname
132
 */
133
LINPHONE_PUBLIC const char *linphone_tunnel_config_get_host(const LinphoneTunnelConfig *tunnel);
134 135 136

/**
 * Set tls port of server.
137 138
 * @param tunnel LinphoneTunnelConfig object
 * @param port The tunnel server TLS port, recommended value is 443
139
 */
140
LINPHONE_PUBLIC void linphone_tunnel_config_set_port(LinphoneTunnelConfig *tunnel, int port);
141 142

/**
143 144 145
 * Get the TLS port of the tunnel server.
 * @param tunnel LinphoneTunnelConfig object
 * @return The TLS port of the tunnel server
146
 */
147
LINPHONE_PUBLIC int linphone_tunnel_config_get_port(const LinphoneTunnelConfig *tunnel);
148 149

/**
150 151 152 153
 * Set the remote port on the tunnel server side used to test UDP reachability.
 * This is used when the mode is set auto, to detect whether the tunnel has to be enabled or not.
 * @param tunnel LinphoneTunnelConfig object
 * @param remote_udp_mirror_port The remote port on the tunnel server side used to test UDP reachability, set to -1 to disable the feature
154
 */
155
LINPHONE_PUBLIC void linphone_tunnel_config_set_remote_udp_mirror_port(LinphoneTunnelConfig *tunnel, int remote_udp_mirror_port);
156 157

/**
158 159 160 161
 * Get the remote port on the tunnel server side used to test UDP reachability.
 * This is used when the mode is set auto, to detect whether the tunnel has to be enabled or not.
 * @param tunnel LinphoneTunnelConfig object
 * @return The remote port on the tunnel server side used to test UDP reachability
162
 */
163
LINPHONE_PUBLIC int linphone_tunnel_config_get_remote_udp_mirror_port(const LinphoneTunnelConfig *tunnel);
164 165

/**
166 167 168
 * Set the UDP packet round trip delay in ms for a tunnel configuration.
 * @param tunnel LinphoneTunnelConfig object
 * @param delay The UDP packet round trip delay in ms considered as acceptable (recommended value is 1000 ms).
jehan's avatar
jehan committed
169
 */
170
LINPHONE_PUBLIC void linphone_tunnel_config_set_delay(LinphoneTunnelConfig *tunnel, int delay);
171 172

/**
173 174 175
 * Get the UDP packet round trip delay in ms for a tunnel configuration.
 * @param tunnel LinphoneTunnelConfig object
 * @return The UDP packet round trip delay in ms.
176
 */
177
LINPHONE_PUBLIC int linphone_tunnel_config_get_delay(const LinphoneTunnelConfig *tunnel);
178

179 180 181 182 183 184 185 186 187 188 189 190 191
/**
 * Increment the refcount of LinphoneTunnelConfig object.
 * @param cfg the LinphoneTunnelConfig object.
 * @return the same cfg object.
**/
LINPHONE_PUBLIC LinphoneTunnelConfig * linphone_tunnel_config_ref(LinphoneTunnelConfig *cfg);


/**
 * Decrement the refcount of LinphoneTunnelConfig object.
 * @param cfg the LinphoneTunnelConfig object.
**/
LINPHONE_PUBLIC void linphone_tunnel_config_unref(LinphoneTunnelConfig *cfg);
192 193
/**
 * Destroy a tunnel configuration
194
 * @param tunnel LinphoneTunnelConfig object
195
 * @deprecated use linphone_tunnel_config_unref().
196
 */
197
LINPHONE_PUBLIC void linphone_tunnel_config_destroy(LinphoneTunnelConfig *tunnel);
198

199 200 201 202 203 204 205 206 207 208 209 210 211 212
/**
 * Store a user data in the tunnel config object
 * @param cfg the tunnel config
 * @param ud the user data
**/
LINPHONE_PUBLIC void linphone_tunnel_config_set_user_data(LinphoneTunnelConfig *cfg, void *ud);

/**
 * Retrieve user data from the tunnel config
 * @param cfg the tunnel config
 * @return the user data
**/
LINPHONE_PUBLIC void *linphone_tunnel_config_get_user_data(LinphoneTunnelConfig *cfg);

213
/**
214 215 216
 * Add a tunnel server configuration.
 * @param tunnel LinphoneTunnel object
 * @param tunnel_config LinphoneTunnelConfig object
217
 */
218
LINPHONE_PUBLIC void linphone_tunnel_add_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
219 220

/**
221 222 223
 * Remove a tunnel server configuration.
 * @param tunnel LinphoneTunnel object
 * @param tunnel_config LinphoneTunnelConfig object
224
 */
225
LINPHONE_PUBLIC void linphone_tunnel_remove_server(LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config);
226

jehan's avatar
jehan committed
227
/**
228 229 230
 * Get added servers
 * @param tunnel LinphoneTunnel object
 * @return \mslist{LinphoneTunnelConfig}
231
 */
232
LINPHONE_PUBLIC const MSList *linphone_tunnel_get_servers(const LinphoneTunnel *tunnel);
233

jehan's avatar
jehan committed
234
/**
235 236
 * Remove all tunnel server addresses previously entered with linphone_tunnel_add_server()
 * @param tunnel LinphoneTunnel object
jehan's avatar
jehan committed
237
**/
238
LINPHONE_PUBLIC void linphone_tunnel_clean_servers(LinphoneTunnel *tunnel);
239

jehan's avatar
jehan committed
240
/**
241
 * Set the tunnel mode.
242 243 244 245
 * The tunnel mode can be 'enable', 'disable' or 'auto'
 * If the mode is set to 'auto', the tunnel manager will try to established an RTP session
 * with the tunnel server on the UdpMirrorPort. If the connection fail, the tunnel is automatically
 * activated whereas the tunnel is automatically disabled if the connection succeed.
246 247
 * @param tunnel LinphoneTunnel object
 * @param mode The desired LinphoneTunnelMode
jehan's avatar
jehan committed
248
**/
249
LINPHONE_PUBLIC void linphone_tunnel_set_mode(LinphoneTunnel *tunnel, LinphoneTunnelMode mode);
250

jehan's avatar
jehan committed
251
/**
252 253 254
 * Get the tunnel mode
 * @param tunnel LinphoneTunnel object
 * @return The current LinphoneTunnelMode
jehan's avatar
jehan committed
255
**/
256
LINPHONE_PUBLIC LinphoneTunnelMode linphone_tunnel_get_mode(const LinphoneTunnel *tunnel);
257

258 259 260 261 262 263 264 265 266
/**
 * Returns whether the tunnel is activated. If mode is set to auto, this gives indication whether the automatic detection determined
 * that tunnel was necessary or not.
 * @param tunnel the tunnel
 * @return TRUE if tunnel is in use, FALSE otherwise.
**/
LINPHONE_PUBLIC bool_t linphone_tunnel_get_activated(const LinphoneTunnel *tunnel);


267
/**
268 269 270
 * Check whether the tunnel is connected
 * @param tunnel LinphoneTunnel object
 * @return A boolean value telling if the tunnel is connected
271
**/
272
LINPHONE_PUBLIC bool_t linphone_tunnel_connected(const LinphoneTunnel *tunnel);
273

jehan's avatar
jehan committed
274
/**
275
 * Force reconnection to the tunnel server.
jehan's avatar
jehan committed
276 277 278
 * This method is useful when the device switches from wifi to Edge/3G or vice versa. In most cases the tunnel client socket
 * won't be notified promptly that its connection is now zombie, so it is recommended to call this method that will cause
 * the lost connection to be closed and new connection to be issued.
279
 * @param tunnel LinphoneTunnel object
jehan's avatar
jehan committed
280
**/
281
LINPHONE_PUBLIC void linphone_tunnel_reconnect(LinphoneTunnel *tunnel);
282

283
/**
284 285
 * Set whether SIP packets must be directly sent to a UA or pass through the tunnel
 * @param tunnel LinphoneTunnel object
286
 * @param enable If true, SIP packets shall pass through the tunnel
287
 */
288
LINPHONE_PUBLIC void linphone_tunnel_enable_sip(LinphoneTunnel *tunnel, bool_t enable);
289 290

/**
291 292 293
 * Check whether tunnel is set to transport SIP packets
 * @param tunnel LinphoneTunnel object
 * @return A boolean value telling whether SIP packets shall pass through the tunnel
294
 */
295
LINPHONE_PUBLIC bool_t linphone_tunnel_sip_enabled(const LinphoneTunnel *tunnel);
296

297 298 299
/**
 * Set an optional http proxy to go through when connecting to tunnel server.
 * @param tunnel LinphoneTunnel object
300 301 302 303
 * @param host http proxy host
 * @param port http proxy port
 * @param username Optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 * @param passwd Optional http proxy password. Use NULL if not needed.
304
 **/
305
LINPHONE_PUBLIC void linphone_tunnel_set_http_proxy(LinphoneTunnel *tunnel, const char *host, int port, const char* username,const char* passwd);
306 307 308 309

/**
 * Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().
 * @param tunnel LinphoneTunnel object
310 311 312 313
 * @param host http proxy host
 * @param port http proxy port
 * @param username Optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
 * @param passwd Optional http proxy password. Use NULL if not needed.
314
 **/
315
LINPHONE_PUBLIC void linphone_tunnel_get_http_proxy(LinphoneTunnel*tunnel,const char **host, int *port, const char **username, const char **passwd);
Guillaume Beraudo's avatar
Guillaume Beraudo committed
316

317
/**
318
 * Set authentication info for the http proxy
319 320 321 322
 * @param tunnel LinphoneTunnel object
 * @param username User name
 * @param passwd Password
 */
323
LINPHONE_PUBLIC void linphone_tunnel_set_http_proxy_auth_info(LinphoneTunnel*tunnel, const char* username,const char* passwd);
324

325
/**
326 327
 * Sets whether tunneling of SIP and RTP is required.
 * @param tunnel object
328 329
 * @param enabled If true enter in tunneled mode, if false exits from tunneled mode.
 * The TunnelManager takes care of refreshing SIP registration when switching on or off the tunneled mode.
330
 * @deprecated Replaced by linphone_tunnel_set_mode()
331 332 333 334
**/
LINPHONE_PUBLIC void linphone_tunnel_enable(LinphoneTunnel *tunnel, bool_t enabled);

/**
335 336
 * Check whether tunnel is enabled
 * @param tunnel Tunnel object
337
 * @return Returns a boolean indicating whether tunneled operation is enabled.
338
 * @deprecated Replaced by linphone_tunnel_get_mode()
339 340 341 342
**/
LINPHONE_PUBLIC bool_t linphone_tunnel_enabled(const LinphoneTunnel *tunnel);

/**
343
 * Start tunnel need detection.
344
 * @param  tunnel object
345 346
 * In auto detect mode, the tunnel manager try to establish a real time rtp communication with the tunnel server on  specified port.
 * <br>In case of success, the tunnel is automatically turned off. Otherwise, if no udp communication is feasible, tunnel mode is turned on.
347
 * <br> Call this method each time to run the auto detection algorithm
348
 * @deprecated Replaced by linphone_tunnel_set_mode(LinphoneTunnelModeAuto)
349 350 351 352
 */
LINPHONE_PUBLIC void linphone_tunnel_auto_detect(LinphoneTunnel *tunnel);

/**
353
 * Tell whether tunnel auto detection is enabled.
354 355
 * @param[in] tunnel LinphoneTunnel object.
 * @return TRUE if auto detection is enabled, FALSE otherwise.
356
 * @deprecated Replaced by linphone_tunnel_get_mode()
357 358 359
 */
LINPHONE_PUBLIC bool_t linphone_tunnel_auto_detect_enabled(LinphoneTunnel *tunnel);

360 361 362 363
/**
 * @}
**/

Guillaume Beraudo's avatar
Guillaume Beraudo committed
364 365 366 367 368
#ifdef __cplusplus
}
#endif


369
#endif //LINPHONETUNNEL_H
370