Tunnel

Typedefs
typedef struct _LinphoneTunnel	LinphoneTunnel
typedef enum _LinphoneTunnelMode	LinphoneTunnelMode

Enumerations
enum	_LinphoneTunnelMode {   LinphoneTunnelModeDisable,   LinphoneTunnelModeEnable,   LinphoneTunnelModeAuto }

Functions
bool_t	linphone_core_tunnel_available (void)
LinphoneTunnel *	linphone_core_get_tunnel (const LinphoneCore *lc)
LinphoneTunnelConfig *	linphone_tunnel_config_new (void)
void	linphone_tunnel_config_set_host (LinphoneTunnelConfig *tunnel, const char *host)
const char *	linphone_tunnel_config_get_host (const LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_port (LinphoneTunnelConfig *tunnel, int port)
int	linphone_tunnel_config_get_port (const LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_host2 (LinphoneTunnelConfig *tunnel, const char *host)
const char *	linphone_tunnel_config_get_host2 (const LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_port2 (LinphoneTunnelConfig *tunnel, int port)
int	linphone_tunnel_config_get_port2 (const LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_remote_udp_mirror_port (LinphoneTunnelConfig *tunnel, int remote_udp_mirror_port)
int	linphone_tunnel_config_get_remote_udp_mirror_port (const LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_delay (LinphoneTunnelConfig *tunnel, int delay)
int	linphone_tunnel_config_get_delay (const LinphoneTunnelConfig *tunnel)
LinphoneTunnelConfig *	linphone_tunnel_config_ref (LinphoneTunnelConfig *cfg)
void	linphone_tunnel_config_unref (LinphoneTunnelConfig *cfg)
void	linphone_tunnel_config_destroy (LinphoneTunnelConfig *tunnel)
void	linphone_tunnel_config_set_user_data (LinphoneTunnelConfig *cfg, void *ud)
void *	linphone_tunnel_config_get_user_data (LinphoneTunnelConfig *cfg)
void	linphone_tunnel_add_server (LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config)
void	linphone_tunnel_remove_server (LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config)
const bctbx_list_t *	linphone_tunnel_get_servers (const LinphoneTunnel *tunnel)
void	linphone_tunnel_clean_servers (LinphoneTunnel *tunnel)
void	linphone_tunnel_set_mode (LinphoneTunnel *tunnel, LinphoneTunnelMode mode)
LinphoneTunnelMode	linphone_tunnel_get_mode (const LinphoneTunnel *tunnel)
void	linphone_tunnel_enable_dual_mode (LinphoneTunnel *tunnel, bool_t dual_mode_enabled)
bool_t	linphone_tunnel_dual_mode_enabled (const LinphoneTunnel *tunnel)
bool_t	linphone_tunnel_get_activated (const LinphoneTunnel *tunnel)
bool_t	linphone_tunnel_connected (const LinphoneTunnel *tunnel)
void	linphone_tunnel_reconnect (LinphoneTunnel *tunnel)
void	linphone_tunnel_enable_sip (LinphoneTunnel *tunnel, bool_t enable)
bool_t	linphone_tunnel_sip_enabled (const LinphoneTunnel *tunnel)
void	linphone_tunnel_set_http_proxy (LinphoneTunnel *tunnel, const char *host, int port, const char *username, const char *passwd)
void	linphone_tunnel_get_http_proxy (LinphoneTunnel *tunnel, const char **host, int *port, const char **username, const char **passwd)
void	linphone_tunnel_set_http_proxy_auth_info (LinphoneTunnel *tunnel, const char *username, const char *passwd)
void	linphone_tunnel_enable (LinphoneTunnel *tunnel, bool_t enabled)
bool_t	linphone_tunnel_enabled (const LinphoneTunnel *tunnel)
void	linphone_tunnel_auto_detect (LinphoneTunnel *tunnel)
bool_t	linphone_tunnel_auto_detect_enabled (LinphoneTunnel *tunnel)
void	linphone_tunnel_simulate_udp_loss (LinphoneTunnel *tunnel, bool_t enabled)

Detailed Description

Typedef Documentation

LinphoneTunnel

typedef struct _LinphoneTunnel LinphoneTunnel

Linphone tunnel object.

LinphoneTunnelMode

typedef enum _LinphoneTunnelMode LinphoneTunnelMode

Enum describing the tunnel modes.

Enumeration Type Documentation

_LinphoneTunnelMode

enum _LinphoneTunnelMode

Enum describing the tunnel modes.

Enumerator
LinphoneTunnelModeDisable	The tunnel is disabled
LinphoneTunnelModeEnable	The tunnel is enabled
LinphoneTunnelModeAuto	The tunnel is enabled automatically if it is required

Function Documentation

linphone_core_get_tunnel()

LinphoneTunnel* linphone_core_get_tunnel

(

const LinphoneCore *

lc

)

get tunnel instance if available

Parameters

lc	core object

Returns

LinphoneTunnel or NULL if not available

linphone_core_tunnel_available()

bool_t linphone_core_tunnel_available

(

void

)

True if tunnel support was compiled.

linphone_tunnel_add_server()

void linphone_tunnel_add_server	(	LinphoneTunnel *	tunnel,
		LinphoneTunnelConfig *	tunnel_config
	)

Add a tunnel server configuration.

Parameters

tunnel	LinphoneTunnel object
tunnel_config	LinphoneTunnelConfig object

linphone_tunnel_auto_detect()

void linphone_tunnel_auto_detect

(

LinphoneTunnel *

tunnel

)

Start tunnel need detection.

Parameters

tunnel

object In auto detect mode, the tunnel manager try to establish a real time rtp communication with the tunnel server on specified port. In case of success, the tunnel is automatically turned off. Otherwise, if no udp communication is feasible, tunnel mode is turned on. Call this method each time to run the auto detection algorithm

Deprecated:

Replaced by linphone_tunnel_set_mode(LinphoneTunnelModeAuto)

linphone_tunnel_auto_detect_enabled()

bool_t linphone_tunnel_auto_detect_enabled

(

LinphoneTunnel *

tunnel

)

Tell whether tunnel auto detection is enabled.

Parameters

[in]

tunnel

LinphoneTunnel object.

Returns

TRUE if auto detection is enabled, FALSE otherwise.

Deprecated:

Replaced by linphone_tunnel_get_mode()

linphone_tunnel_clean_servers()

void linphone_tunnel_clean_servers

(

LinphoneTunnel *

tunnel

)

Remove all tunnel server addresses previously entered with linphone_tunnel_add_server()

Parameters

tunnel

LinphoneTunnel object

linphone_tunnel_config_destroy()

void linphone_tunnel_config_destroy

(

LinphoneTunnelConfig *

tunnel

)

Destroy a tunnel configuration

Parameters

tunnel

LinphoneTunnelConfig object

Deprecated:

use linphone_tunnel_config_unref().

linphone_tunnel_config_get_delay()

int linphone_tunnel_config_get_delay

(

const LinphoneTunnelConfig *

tunnel

)

Get the UDP packet round trip delay in ms for a tunnel configuration.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The UDP packet round trip delay in ms.

linphone_tunnel_config_get_host()

const char* linphone_tunnel_config_get_host

(

const LinphoneTunnelConfig *

tunnel

)

Get the IP address or hostname of the tunnel server.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The tunnel server IP address or hostname

linphone_tunnel_config_get_host2()

const char* linphone_tunnel_config_get_host2

(

const LinphoneTunnelConfig *

tunnel

)

Get the IP address or hostname of the second tunnel server when using dual tunnel client.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The tunnel server IP address or hostname

linphone_tunnel_config_get_port()

int linphone_tunnel_config_get_port

(

const LinphoneTunnelConfig *

tunnel

)

Get the TLS port of the tunnel server.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The TLS port of the tunnel server

linphone_tunnel_config_get_port2()

int linphone_tunnel_config_get_port2

(

const LinphoneTunnelConfig *

tunnel

)

Get the TLS port of the second tunnel server when using dual tunnel client.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The TLS port of the tunnel server

linphone_tunnel_config_get_remote_udp_mirror_port()

int linphone_tunnel_config_get_remote_udp_mirror_port

(

const LinphoneTunnelConfig *

tunnel

)

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.

Parameters

tunnel

LinphoneTunnelConfig object

Returns

The remote port on the tunnel server side used to test UDP reachability

linphone_tunnel_config_get_user_data()

void* linphone_tunnel_config_get_user_data

(

LinphoneTunnelConfig *

cfg

)

Retrieve user data from the tunnel config

Parameters

cfg	the tunnel config

Returns

the user data

linphone_tunnel_config_new()

LinphoneTunnelConfig* linphone_tunnel_config_new

(

void

)

Linphone tunnel aims is to bypass IP traffic blocking due to aggressive firewalls which typically only authorize TCP traffic with destination port 443.
Its principle is tunneling all SIP and/or RTP traffic through a single secure https connection up to a detunnelizer server.
This set of methods enhance LinphoneCore functionalities in order to provide an easy to use API to

• 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
• start/stop the tunneling service
• perform auto-detection whether tunneling is required, based on a test of sending/receiving a flow of UDP packets.

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.

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.
Finally tunnel mode configuration is achieved by function linphone_tunnel_set_mode.
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:

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

Create a new tunnel configuration

linphone_tunnel_config_ref()

LinphoneTunnelConfig* linphone_tunnel_config_ref

(

LinphoneTunnelConfig *

cfg

)

Increment the refcount of LinphoneTunnelConfig object.

Parameters

cfg	the LinphoneTunnelConfig object.

Returns

the same cfg object.

linphone_tunnel_config_set_delay()

void linphone_tunnel_config_set_delay	(	LinphoneTunnelConfig *	tunnel,
		int	delay
	)

Set the UDP packet round trip delay in ms for a tunnel configuration.

Parameters

tunnel	LinphoneTunnelConfig object
delay	The UDP packet round trip delay in ms considered as acceptable (recommended value is 1000 ms).

linphone_tunnel_config_set_host()

void linphone_tunnel_config_set_host	(	LinphoneTunnelConfig *	tunnel,
		const char *	host
	)

Set the IP address or hostname of the tunnel server.

Parameters

tunnel	LinphoneTunnelConfig object
host	The tunnel server IP address or hostname

linphone_tunnel_config_set_host2()

void linphone_tunnel_config_set_host2	(	LinphoneTunnelConfig *	tunnel,
		const char *	host
	)

Set the IP address or hostname of the second tunnel server when using dual tunnel client.

Parameters

tunnel	LinphoneTunnelConfig object
host	The tunnel server IP address or hostname

linphone_tunnel_config_set_port()

void linphone_tunnel_config_set_port	(	LinphoneTunnelConfig *	tunnel,
		int	port
	)

Set tls port of server.

Parameters

tunnel	LinphoneTunnelConfig object
port	The tunnel server TLS port, recommended value is 443

linphone_tunnel_config_set_port2()

void linphone_tunnel_config_set_port2	(	LinphoneTunnelConfig *	tunnel,
		int	port
	)

Set tls port of the second server when using dual tunnel client.

Parameters

tunnel	LinphoneTunnelConfig object
port	The tunnel server TLS port, recommended value is 443

linphone_tunnel_config_set_remote_udp_mirror_port()

void linphone_tunnel_config_set_remote_udp_mirror_port	(	LinphoneTunnelConfig *	tunnel,
		int	remote_udp_mirror_port
	)

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.

Parameters

tunnel	LinphoneTunnelConfig object
remote_udp_mirror_port	The remote port on the tunnel server side used to test UDP reachability, set to -1 to disable the feature

linphone_tunnel_config_set_user_data()

void linphone_tunnel_config_set_user_data	(	LinphoneTunnelConfig *	cfg,
		void *	ud
	)

Store a user data in the tunnel config object

Parameters

cfg	the tunnel config
ud	the user data

linphone_tunnel_config_unref()

void linphone_tunnel_config_unref

(

LinphoneTunnelConfig *

cfg

)

Decrement the refcount of LinphoneTunnelConfig object.

Parameters

cfg	the LinphoneTunnelConfig object.

linphone_tunnel_connected()

bool_t linphone_tunnel_connected

(

const LinphoneTunnel *

tunnel

)

Check whether the tunnel is connected

Parameters

tunnel

LinphoneTunnel object

Returns

A boolean value telling if the tunnel is connected

linphone_tunnel_dual_mode_enabled()

bool_t linphone_tunnel_dual_mode_enabled

(

const LinphoneTunnel *

tunnel

)

Get the dual tunnel client mode

Parameters

tunnel

LinphoneTunnel object

Returns

TRUE if dual tunnel client mode is enabled, FALSE otherwise

linphone_tunnel_enable()

void linphone_tunnel_enable	(	LinphoneTunnel *	tunnel,
		bool_t	enabled
	)

Sets whether tunneling of SIP and RTP is required.

Parameters

tunnel	object
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.

Deprecated:

Replaced by linphone_tunnel_set_mode()

linphone_tunnel_enable_dual_mode()

void linphone_tunnel_enable_dual_mode	(	LinphoneTunnel *	tunnel,
		bool_t	dual_mode_enabled
	)

Sets whether or not to use the dual tunnel client mode. By default this feature is disabled. After enabling it, add a server with 2 hosts and 2 ports for the feature to work.

Parameters

tunnel	LinphoneTunnel object
dual_mode_enabled	TRUE to enable it, FALSE to disable it

linphone_tunnel_enable_sip()

void linphone_tunnel_enable_sip	(	LinphoneTunnel *	tunnel,
		bool_t	enable
	)

Set whether SIP packets must be directly sent to a UA or pass through the tunnel

Parameters

tunnel	LinphoneTunnel object
enable	If true, SIP packets shall pass through the tunnel

linphone_tunnel_enabled()

bool_t linphone_tunnel_enabled

(

const LinphoneTunnel *

tunnel

)

Check whether tunnel is enabled

Parameters

tunnel

Tunnel object

Returns

Returns a boolean indicating whether tunneled operation is enabled.

Deprecated:

Replaced by linphone_tunnel_get_mode()

linphone_tunnel_get_activated()

bool_t linphone_tunnel_get_activated

(

const LinphoneTunnel *

tunnel

)

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.

Parameters

tunnel

the tunnel

Returns

TRUE if tunnel is in use, FALSE otherwise.

linphone_tunnel_get_http_proxy()

void linphone_tunnel_get_http_proxy	(	LinphoneTunnel *	tunnel,
		const char **	host,
		int *	port,
		const char **	username,
		const char **	passwd
	)

Retrieve optional http proxy configuration previously set with linphone_tunnel_set_http_proxy().

Parameters

tunnel	LinphoneTunnel object
host	http proxy host
port	http proxy port
username	Optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
passwd	Optional http proxy password. Use NULL if not needed.

linphone_tunnel_get_mode()

LinphoneTunnelMode linphone_tunnel_get_mode

(

const LinphoneTunnel *

tunnel

)

Get the tunnel mode

Parameters

tunnel

LinphoneTunnel object

Returns

The current LinphoneTunnelMode

linphone_tunnel_get_servers()

const bctbx_list_t* linphone_tunnel_get_servers

(

const LinphoneTunnel *

tunnel

)

Get added servers

Parameters

tunnel

LinphoneTunnel object

Returns

A list of LinphoneTunnelConfig objects.

linphone_tunnel_reconnect()

void linphone_tunnel_reconnect

(

LinphoneTunnel *

tunnel

)

Force reconnection to the tunnel server. 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.

Parameters

tunnel

LinphoneTunnel object

linphone_tunnel_remove_server()

void linphone_tunnel_remove_server	(	LinphoneTunnel *	tunnel,
		LinphoneTunnelConfig *	tunnel_config
	)

Remove a tunnel server configuration.

Parameters

tunnel	LinphoneTunnel object
tunnel_config	LinphoneTunnelConfig object

linphone_tunnel_set_http_proxy()

void linphone_tunnel_set_http_proxy	(	LinphoneTunnel *	tunnel,
		const char *	host,
		int	port,
		const char *	username,
		const char *	passwd
	)

Set an optional http proxy to go through when connecting to tunnel server.

Parameters

tunnel	LinphoneTunnel object
host	http proxy host
port	http proxy port
username	Optional http proxy username if the proxy request authentication. Currently only basic authentication is supported. Use NULL if not needed.
passwd	Optional http proxy password. Use NULL if not needed.

linphone_tunnel_set_http_proxy_auth_info()

void linphone_tunnel_set_http_proxy_auth_info	(	LinphoneTunnel *	tunnel,
		const char *	username,
		const char *	passwd
	)

Set authentication info for the http proxy

Parameters

tunnel	LinphoneTunnel object
username	User name
passwd	Password

linphone_tunnel_set_mode()

void linphone_tunnel_set_mode	(	LinphoneTunnel *	tunnel,
		LinphoneTunnelMode	mode
	)

Set the tunnel mode. 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.

Parameters

tunnel	LinphoneTunnel object
mode	The desired LinphoneTunnelMode

linphone_tunnel_sip_enabled()

bool_t linphone_tunnel_sip_enabled

(

const LinphoneTunnel *

tunnel

)

Check whether tunnel is set to transport SIP packets

Parameters

tunnel

LinphoneTunnel object

Returns

A boolean value telling whether SIP packets shall pass through the tunnel