Tizen Native API
5.5
|
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:
- Initialize / Deinitialize the VPN device
- Routing management
- DNS management
- Firewall management To enable or disable VPN interface, you should launch VPN popup by using app-control.
Related Features
This API is related with the following features:
- http://tizen.org/feature/network.vpn
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
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
enum vpnsvc_error_e |
Enumeration for VPN service error types.
Indicate formats of error type field
- Enumerator:
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] handle The VPN interface handle [in] dns_server The DNS server address (IPv4 only)
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] route_address Destination address of the routes (IPv4 only) [in] prefix The 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_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] routes_dest_vpn_addr Destination address of the routes, the list of allowing networks over VPN interface (e.g., VPN interface such as tun0, etc). [in] routes_vpn_prefix The prefix of VPN interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32). [in] num_allow_routes_vpn The number of allowing networks over VPN interface [in] routes_dest_orig_addr Destination 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_prefix The prefix of Original interface, netmask length (also called a prefix, e.g. 8, 16, 24, 32). [in] num_allow_routes_orig The number of allowing networks over the original interface
- Returns:
- 0 on success. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle
- Returns:
- 0 on success. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [out] iface_fd The vpn interface fd
- Returns:
- The fd value of VPN interface. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not Supported
int vpnsvc_get_iface_index | ( | vpnsvc_h | handle, |
int * | iface_index | ||
) |
Gets the index of VPN interface.
- Since :
- 3.0
- Parameters:
-
[in] handle The VPN interface handle [out] iface_index The VPN interface index
- Returns:
- The index of the VPN interface. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [out] iface_name The name of VPN interface name
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [out] session The Session Name returned
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not 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_name The VPN interface name [out] handle The VPN interface handle
- Returns:
- 0 on success. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not 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.
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] handle The VPN interface handle [in] socket_fd The opened socket file descriptor [in] iface_name The 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_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] timeout_ms The value of timeout (milliseconds)
- Returns:
- 0 on success. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_TIMEOUT Timeout (no answer in timeout_ms) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] dns_server The DNS server address (IPv4 only)
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] route_address Destination address of the routes (IPv4 only) [in] prefix The 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_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] blocking The blocking mode flag; True = BLOCKING, False = NON_BLOCKING (Default : BLOCKING)
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR Failed to set the blocking flags VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] local_ip The local (VPN client) IP address (IPv4 only)
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] mtu The 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_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] remote_ip The remote (VPN server) IP address (IPv4 only)
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IO_ERROR I/O Error (e.g. socket I/O error) VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] session The Session Name
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not Supported
- Precondition:
- Before calling this function, VPN interface should be initialized already.
- See also:
- vpnsvc_init()
int vpnsvc_unblock_networks | ( | vpnsvc_h | handle | ) |
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] handle The VPN interface handle
- Returns:
- 0 on success. otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not Supported
int vpnsvc_update_settings | ( | vpnsvc_h | handle | ) |
Updates settings (Local IP / Remote IP / MTU).
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/vpnservice
- Parameters:
-
[in] handle The VPN interface handle
- Returns:
- 0 on success. Otherwise, a negative error value.
- Return values:
-
VPNSVC_ERROR_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_IPC_FAILED Cannot connect to service daemon VPNSVC_ERROR_PERMISSION_DENIED Permission Denied VPNSVC_ERROR_NOT_SUPPORTED Not 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] handle The VPN interface handle [in] data Data writing to VPN interface [in] size The 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_NONE Success VPNSVC_ERROR_INVALID_PARAMETER Invalid parameter VPNSVC_ERROR_NOT_SUPPORTED Not Supported In case 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()