liblinphone 3.9.1

- Main Page
- Related Pages
- Modules
- Data Structures

Typedefs | Enumerations | Functions
Tunnel

## Typedefs
typedef struct _LinphoneTunnelConfig | LinphoneTunnelConfig
typedef enum _LinphoneTunnelMode | LinphoneTunnelMode
typedef struct _LinphoneTunnel | LinphoneTunnel

## Enumerations
enum | _LinphoneTunnelMode { LinphoneTunnelModeDisable, LinphoneTunnelModeEnable, LinphoneTunnelModeAuto }

## Functions
LinphoneTunnelMode | linphone_tunnel_mode_from_string (const char *string)
const char * | linphone_tunnel_mode_to_string (LinphoneTunnelMode mode)
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_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)
void | linphone_tunnel_config_destroy (LinphoneTunnelConfig *tunnel)
void | linphone_tunnel_add_server (LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config)
void | linphone_tunnel_remove_server (LinphoneTunnel *tunnel, LinphoneTunnelConfig *tunnel_config)
const MSList * | 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)
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)
bool_t | linphone_core_tunnel_available (void)
LinphoneTunnel * | linphone_core_get_tunnel (const LinphoneCore *lc)

## Detailed Description

## Typedef Documentation

typedef struct _LinphoneTunnelConfig LinphoneTunnelConfig

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:

1 LinphoneTunnel *tunnel = linphone_core_get_tunnel(linphone_core);
2 LinphoneTunnelConfig *config=linphone_tunnel_config_new(); //instantiate tunnel configuration
3 linphone_tunnel_config_set_host(config, "tunnel.linphone.org"); //set tunnel server host address
4 linphone_tunnel_config_set_port(config, 443); //set tunnel server port
5 linphone_tunnel_add_server(tunnel, config); //provision tunnel config
6 linphone_tunnel_set_mode(tunnel, LinphoneTunnelModeEnable); //activate the tunnel unconditional
7
8 while (!linphone_tunnel_connected(tunnel)) { //wait for tunnel to be ready
9 linphone_core_iterate(linphone_core); //schedule core main loop
10 ms_sleep(100); //wait 100ms
11 }
12
13 LinphoneCall *call = linphone_core_invite(linphone_core,"sip:foo@example.org"); //place an outgoing call
14 linphone_call_ref(call); //acquire a reference on the call to avoid deletion after completion
15 //...
16 linphone_core_terminate_call(linphone_core,call);
17
18 while (linphone_call_get_state(call) != LinphoneCallReleased) { //wait for call to be in release state
19 linphone_core_iterate(linphone_core); //schedule core main loop
20 ms_sleep(100); //wait 100ms
21 }
22
23 linphone_tunnel_set_mode(tunnel, LinphoneTunnelModeDisable); //deactivate tunnel
24 linphone_call_unref(call); //release reference on the call

typedef enum _LinphoneTunnelMode LinphoneTunnelMode

Enum describing the tunnel modes.

typedef struct _LinphoneTunnel LinphoneTunnel

Linphone tunnel object.

## Enumeration Type Documentation

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

LinphoneTunnelMode linphone_tunnel_mode_from_string | ( | const char * | string | ) |

Convert a string into LinphoneTunnelMode enum

Parameters

  string | String to convert

Returns
  An LinphoneTunnelMode enum. If the passed string is NULL or does not match with any mode, the LinphoneTunnelModeDisable is returned.

const char* linphone_tunnel_mode_to_string | ( | LinphoneTunnelMode | mode | ) |

Convert a tunnel mode enum into string

Parameters

  mode | Enum to convert

Returns
  "disable", "enable" or "auto"

LinphoneTunnelConfig* linphone_tunnel_config_new | ( | void |  | ) |

Create a new tunnel configuration

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

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

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

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

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

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

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).

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.

void linphone_tunnel_config_destroy | ( | LinphoneTunnelConfig * | tunnel | ) |

Destroy a tunnel configuration

Parameters

  tunnel | LinphoneTunnelConfig object

void linphone_tunnel_add_server | ( | LinphoneTunnel * | tunnel,
|  | LinphoneTunnelConfig * | tunnel_config
| ) |  |

Add a tunnel server configuration.

Parameters

  tunnel | LinphoneTunnel object
  tunnel_config | LinphoneTunnelConfig object

void linphone_tunnel_remove_server | ( | LinphoneTunnel * | tunnel,
|  | LinphoneTunnelConfig * | tunnel_config
| ) |  |

Remove a tunnel server configuration.

Parameters

  tunnel | LinphoneTunnel object
  tunnel_config | LinphoneTunnelConfig object

const MSList* linphone_tunnel_get_servers | ( | const LinphoneTunnel * | tunnel | ) |

Get added servers

Parameters

  tunnel | LinphoneTunnel object

Returns
  A list of LinphoneTunnelConfig objects.

void linphone_tunnel_clean_servers | ( | LinphoneTunnel * | tunnel | ) |

Remove all tunnel server addresses previously entered with linphone_tunnel_add_server()

Parameters

  tunnel | LinphoneTunnel object

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

LinphoneTunnelMode linphone_tunnel_get_mode | ( | const LinphoneTunnel * | tunnel | ) |

Get the tunnel mode

Parameters

  tunnel | LinphoneTunnel object

Returns
  The current LinphoneTunnelMode

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.

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

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

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

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

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.

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.

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

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()

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()

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)

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()

bool_t linphone_core_tunnel_available | ( | void |  | ) |

True if tunnel support was compiled.

LinphoneTunnel* linphone_core_get_tunnel | ( | const LinphoneCore * | lc | ) |

get tunnel instance if available

Parameters

  lc | core object

Returns
  LinphoneTunnel or NULL if not available