Tizen Native API  5.5
VPN Service

The Virtual Private Network (VPN) API provides functions for managing VPN.

Required Header

#include <vpn_service.h>

Overview

The VPN Service functions for managing VPN. There can be only one VPN connection running at the same time. The existing interface is deactivated when a new one is created. Using the VPN Service, you can implement features that allow the users of your application to:

Related Features

This API is related with the following features:

Functions

int vpnsvc_init (const char *iface_name, vpnsvc_h *handle)
 Initializes VPN interface.
int vpnsvc_deinit (vpnsvc_h handle)
 De-Initializes VPN interface.
int vpnsvc_protect (vpnsvc_h handle, int socket_fd, const char *iface_name)
 Protect a socket from VPN connections.
int vpnsvc_read (vpnsvc_h handle, int timeout_ms)
 Waits for the read event on VPN interface descriptor, but no more than the indicated timeout in milliseconds.
int vpnsvc_write (vpnsvc_h handle, const char *data, size_t size)
 Writes the data supplied into the VPN interface.
int vpnsvc_block_networks (vpnsvc_h handle, char *routes_dest_vpn_addr[], int routes_vpn_prefix[], size_t num_allow_routes_vpn, char *routes_dest_orig_addr[], int routes_orig_prefix[], size_t num_allow_routes_orig)
 Blocks all traffics except specified allowing networks.
int vpnsvc_unblock_networks (vpnsvc_h handle)
 Removes any restrictions imposed by vpnsvc_block_networks().
int vpnsvc_update_settings (vpnsvc_h handle)
 Updates settings (Local IP / Remote IP / MTU).
int vpnsvc_get_iface_fd (vpnsvc_h handle, int *iface_fd)
 Gets the fd of the VPN interface.
int vpnsvc_get_iface_index (vpnsvc_h handle, int *iface_index)
 Gets the index of VPN interface.
int vpnsvc_get_iface_name (vpnsvc_h handle, char **iface_name)
 Gets the name of VPN interface.
int vpnsvc_set_mtu (vpnsvc_h handle, int mtu)
 Sets the MTU of the VPN interface.
int vpnsvc_set_blocking (vpnsvc_h handle, bool blocking)
 Sets blocking mode of the file descriptor of VPN interface.
int vpnsvc_set_session (vpnsvc_h handle, const char *session)
 Sets the session name for the VPN. (It will be displayed in system-managed dialogs and notifications.)
int vpnsvc_get_session (vpnsvc_h handle, char **session)
 Gets the session name for the VPN.
int vpnsvc_set_local_ip_address (vpnsvc_h handle, const char *local_ip)
 Sets the VPN client IP address.
int vpnsvc_set_remote_ip_address (vpnsvc_h handle, const char *remote_ip)
 Sets the VPN server IP address.
int vpnsvc_add_route (vpnsvc_h handle, const char *route_address, int prefix)
 Adds the route address.
int vpnsvc_remove_route (vpnsvc_h handle, const char *route_address, int prefix)
 Removes the route address.
int vpnsvc_add_dns_server (vpnsvc_h handle, const char *dns_server)
 Adds the DNS server name.
int vpnsvc_remove_dns_server (vpnsvc_h handle, const char *dns_server)
 Removes the DNS server name.

Typedefs

typedef void * vpnsvc_h
 The VPN interface handle.

Typedef Documentation

typedef void* vpnsvc_h

The VPN interface handle.

This handle can be obtained by calling vpnsvc_init() and destroyed by calling vpnsvc_deinit().

Since :
3.0
See also:
vpnsvc_init()
vpnsvc_deinit()

Enumeration Type Documentation

Enumeration for VPN service error types.

Indicate formats of error type field

Enumerator:
VPNSVC_ERROR_NONE 

Successful

VPNSVC_ERROR_INVALID_PARAMETER 

Invalid parameter

VPNSVC_ERROR_OUT_OF_MEMORY 

Out of memory

VPNSVC_ERROR_PERMISSION_DENIED 

Permission denied

VPNSVC_ERROR_NO_SUCH_FILE 

No such file or directory

VPNSVC_ERROR_IO_ERROR 

IO error

VPNSVC_ERROR_TIMEOUT 

Time out error or no answer

VPNSVC_ERROR_IPC_FAILED 

Failed to communicate with server

VPNSVC_ERROR_NOT_SUPPORTED 

Not Supported


Function Documentation

int vpnsvc_add_dns_server ( vpnsvc_h  handle,
const char *  dns_server 
)

Adds the DNS server name.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Remarks:
The dns address should be set after enabling VPN interface.
Parameters:
[in]handleThe VPN interface handle
[in]dns_serverThe DNS server address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_add_route ( vpnsvc_h  handle,
const char *  route_address,
int  prefix 
)

Adds the route address.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Remarks:
The route address should be set after enabling VPN interface.
Parameters:
[in]handleThe VPN interface handle
[in]route_addressDestination address of the routes (IPv4 only)
[in]prefixThe prefix of routes, netmask length (also called a prefix, e.g. 8, 16, 24, 32)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_block_networks ( vpnsvc_h  handle,
char *  routes_dest_vpn_addr[],
int  routes_vpn_prefix[],
size_t  num_allow_routes_vpn,
char *  routes_dest_orig_addr[],
int  routes_orig_prefix[],
size_t  num_allow_routes_orig 
)

Blocks all traffics except specified allowing networks.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet
Parameters:
[in]handleThe VPN interface handle
[in]routes_dest_vpn_addrDestination address of the routes, the list of allowing networks over VPN interface (e.g., VPN interface such as tun0, etc).
[in]routes_vpn_prefixThe prefix of VPN interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]num_allow_routes_vpnThe number of allowing networks over VPN interface
[in]routes_dest_orig_addrDestination address of the routes, the list of allowing networks over the original interface (e.g., original interface such as eth0, wlan0, etc).
[in]routes_orig_prefixThe prefix of Original interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32).
[in]num_allow_routes_origThe number of allowing networks over the original interface
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Postcondition:
Please call vpnsvc_unblock_networks() if you want to allow all traffics.
See also:
vpnsvc_unblock_networks()
int vpnsvc_deinit ( vpnsvc_h  handle)

De-Initializes VPN interface.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet
Parameters:
[in]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_get_iface_fd ( vpnsvc_h  handle,
int *  iface_fd 
)

Gets the fd of the VPN interface.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[out]iface_fdThe vpn interface fd
Returns:
The fd value of VPN interface. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
int vpnsvc_get_iface_index ( vpnsvc_h  handle,
int *  iface_index 
)

Gets the index of VPN interface.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[out]iface_indexThe VPN interface index
Returns:
The index of the VPN interface. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_get_iface_name ( vpnsvc_h  handle,
char **  iface_name 
)

Gets the name of VPN interface.

Since :
3.0
Remarks:
The iface_name should be released using free()
Parameters:
[in]handleThe VPN interface handle
[out]iface_nameThe name of VPN interface name
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_get_session ( vpnsvc_h  handle,
char **  session 
)

Gets the session name for the VPN.

Since :
3.0
Remarks:
The session should be released using free()
Parameters:
[in]handleThe VPN interface handle
[out]sessionThe Session Name returned
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_init ( const char *  iface_name,
vpnsvc_h handle 
)

Initializes VPN interface.

You should call vpnsvc_get_iface_name() for checking the actual initialized VPN interface name. (In case of duplicated interface name)

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet
Remarks:
The handle should be released using vpnsvc_deinit().
Parameters:
[in]iface_nameThe VPN interface name
[out]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Postcondition:
Please call vpnsvc_deinit() if you want to de-initialize VPN interface.
Please call vpnsvc_get_iface_fd() if you want to know the fd(file descriptor) of VPN interface.
Please call vpnsvc_get_iface_index() if you want to know the index of VPN interface.
Please call vpnsvc_get_iface_name() if you want to know the name of VPN interface.
See also:
vpnsvc_deinit()
vpnsvc_get_iface_fd()
vpnsvc_get_iface_index()
vpnsvc_get_iface_name()
int vpnsvc_protect ( vpnsvc_h  handle,
int  socket_fd,
const char *  iface_name 
)

Protect a socket from VPN connections.

After protecting, data sent through this socket will go directly to the underlying network.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet
Parameters:
[in]handleThe VPN interface handle
[in]socket_fdThe opened socket file descriptor
[in]iface_nameThe network interface name (e.g., interface name such as eth0, ppp0, etc) through which the VPN is working
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
int vpnsvc_read ( vpnsvc_h  handle,
int  timeout_ms 
)

Waits for the read event on VPN interface descriptor, but no more than the indicated timeout in milliseconds.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[in]timeout_msThe value of timeout (milliseconds)
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_TIMEOUTTimeout (no answer in timeout_ms)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_remove_dns_server ( vpnsvc_h  handle,
const char *  dns_server 
)

Removes the DNS server name.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Parameters:
[in]handleThe VPN interface handle
[in]dns_serverThe DNS server address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_remove_route ( vpnsvc_h  handle,
const char *  route_address,
int  prefix 
)

Removes the route address.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Parameters:
[in]handleThe VPN interface handle
[in]route_addressDestination address of the routes (IPv4 only)
[in]prefixThe prefix of routes, netmask length (also called a prefix, e.g. 8, 16, 24, 32)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_set_blocking ( vpnsvc_h  handle,
bool  blocking 
)

Sets blocking mode of the file descriptor of VPN interface.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[in]blockingThe blocking mode flag; True = BLOCKING, False = NON_BLOCKING (Default : BLOCKING)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORFailed to set the blocking flags
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_set_local_ip_address ( vpnsvc_h  handle,
const char *  local_ip 
)

Sets the VPN client IP address.

Since :
3.0
Remarks:
The local address should be set before enabling VPN interface.
vpnsvc_update_settings() should be invoked after setting local IP address.
Parameters:
[in]handleThe VPN interface handle
[in]local_ipThe local (VPN client) IP address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_set_mtu ( vpnsvc_h  handle,
int  mtu 
)

Sets the MTU of the VPN interface.

Since :
3.0
Remarks:
vpnsvc_update_settings() should be invoked after setting MTU.
Parameters:
[in]handleThe VPN interface handle
[in]mtuThe MTU (Maximum Transmission Unit) value to be set for VPN interface. Default MTU size is 1500.
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_set_remote_ip_address ( vpnsvc_h  handle,
const char *  remote_ip 
)

Sets the VPN server IP address.

Since :
3.0
Remarks:
The remote address should be set before enabling VPN interface.
vpnsvc_update_settings() should be invoked after setting remote IP address.
Parameters:
[in]handleThe VPN interface handle
[in]remote_ipThe remote (VPN server) IP address (IPv4 only)
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IO_ERRORI/O Error (e.g. socket I/O error)
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_set_session ( vpnsvc_h  handle,
const char *  session 
)

Sets the session name for the VPN. (It will be displayed in system-managed dialogs and notifications.)

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[in]sessionThe Session Name
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
Before calling this function, VPN interface should be initialized already.
See also:
vpnsvc_init()

Removes any restrictions imposed by vpnsvc_block_networks().

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
http://tizen.org/privilege/internet
Parameters:
[in]handleThe VPN interface handle
Returns:
0 on success. otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported

Updates settings (Local IP / Remote IP / MTU).

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/vpnservice
Parameters:
[in]handleThe VPN interface handle
Returns:
0 on success. Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_IPC_FAILEDCannot connect to service daemon
VPNSVC_ERROR_PERMISSION_DENIEDPermission Denied
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()
int vpnsvc_write ( vpnsvc_h  handle,
const char *  data,
size_t  size 
)

Writes the data supplied into the VPN interface.

Since :
3.0
Parameters:
[in]handleThe VPN interface handle
[in]dataData writing to VPN interface
[in]sizeThe size of data
Returns:
On success, the number of bytes written is returned (zero indicates nothing was written). Otherwise, a negative error value.
Return values:
VPNSVC_ERROR_NONESuccess
VPNSVC_ERROR_INVALID_PARAMETERInvalid parameter
VPNSVC_ERROR_NOT_SUPPORTEDNot Supported
Incase of negative error, please refer to standard posix write API's error code.
Precondition:
The VPN interface should be initialized already.
See also:
vpnsvc_init()