Skip to content

Most visited

Recently visited

navigation
Added in API level 14

VpnService.Builder

public class VpnService.Builder
extends Object

java.lang.Object
   ↳ android.net.VpnService.Builder


Helper class to create a VPN interface. This class should be always used within the scope of the outer VpnService.

See also:

Summary

Public constructors

VpnService.Builder()

Public methods

VpnService.Builder addAddress(String address, int prefixLength)

Convenience method to add a network address to the VPN interface using a numeric address string.

VpnService.Builder addAddress(InetAddress address, int prefixLength)

Add a network address to the VPN interface.

VpnService.Builder addAllowedApplication(String packageName)

Adds an application that's allowed to access the VPN connection.

VpnService.Builder addDisallowedApplication(String packageName)

Adds an application that's denied access to the VPN connection.

VpnService.Builder addDnsServer(String address)

Convenience method to add a DNS server to the VPN connection using a numeric address string.

VpnService.Builder addDnsServer(InetAddress address)

Add a DNS server to the VPN connection.

VpnService.Builder addRoute(String address, int prefixLength)

Convenience method to add a network route to the VPN interface using a numeric address string.

VpnService.Builder addRoute(InetAddress address, int prefixLength)

Add a network route to the VPN interface.

VpnService.Builder addSearchDomain(String domain)

Add a search domain to the DNS resolver.

VpnService.Builder allowBypass()

Allows all apps to bypass this VPN connection.

VpnService.Builder allowFamily(int family)

Allows traffic from the specified address family.

ParcelFileDescriptor establish()

Create a VPN interface using the parameters supplied to this builder.

VpnService.Builder setBlocking(boolean blocking)

Sets the VPN interface's file descriptor to be in blocking/non-blocking mode.

VpnService.Builder setConfigureIntent(PendingIntent intent)

Set the PendingIntent to an activity for users to configure the VPN connection.

VpnService.Builder setMtu(int mtu)

Set the maximum transmission unit (MTU) of the VPN interface.

VpnService.Builder setSession(String session)

Set the name of this session.

VpnService.Builder setUnderlyingNetworks(Network[] networks)

Sets the underlying networks used by the VPN for its upstream connections.

Inherited methods

From class java.lang.Object

Public constructors

VpnService.Builder

Added in API level 14
VpnService.Builder ()

Public methods

addAddress

Added in API level 14
VpnService.Builder addAddress (String address, 
                int prefixLength)

Convenience method to add a network address to the VPN interface using a numeric address string. See InetAddress for the definitions of numeric address formats. Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address String
prefixLength int
Returns
VpnService.Builder
Throws
IllegalArgumentException if the address is invalid.

See also:

addAddress

Added in API level 14
VpnService.Builder addAddress (InetAddress address, 
                int prefixLength)

Add a network address to the VPN interface. Both IPv4 and IPv6 addresses are supported. At least one address must be set before calling establish(). Adding an address implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address InetAddress
prefixLength int
Returns
VpnService.Builder
Throws
IllegalArgumentException if the address is invalid.

addAllowedApplication

Added in API level 21
VpnService.Builder addAllowedApplication (String packageName)

Adds an application that's allowed to access the VPN connection. If this method is called at least once, only applications added through this method (and no others) are allowed access. Else (if this method is never called), all applications are allowed by default. If some applications are added, other, un-added applications will use networking as if the VPN wasn't running. A VpnService.Builder may have only a set of allowed applications OR a set of disallowed ones, but not both. Calling this method after addDisallowedApplication(String) has already been called, or vice versa, will throw an UnsupportedOperationException. packageName must be the canonical name of a currently installed application. PackageManager.NameNotFoundException is thrown if there's no such application.

Parameters
packageName String: The full name (e.g.: "com.google.apps.contacts") of an application.
Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining method calls.
Throws
PackageManager.NameNotFoundException} If the application isn't installed.
PackageManager.NameNotFoundException

addDisallowedApplication

Added in API level 21
VpnService.Builder addDisallowedApplication (String packageName)

Adds an application that's denied access to the VPN connection. By default, all applications are allowed access, except for those denied through this method. Denied applications will use networking as if the VPN wasn't running. A VpnService.Builder may have only a set of allowed applications OR a set of disallowed ones, but not both. Calling this method after addAllowedApplication(String) has already been called, or vice versa, will throw an UnsupportedOperationException. packageName must be the canonical name of a currently installed application. PackageManager.NameNotFoundException is thrown if there's no such application.

Parameters
packageName String: The full name (e.g.: "com.google.apps.contacts") of an application.
Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining method calls.
Throws
PackageManager.NameNotFoundException} If the application isn't installed.
PackageManager.NameNotFoundException

addDnsServer

Added in API level 14
VpnService.Builder addDnsServer (String address)

Convenience method to add a DNS server to the VPN connection using a numeric address string. See InetAddress for the definitions of numeric address formats. Adding a server implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address String
Returns
VpnService.Builder
Throws
IllegalArgumentException if the address is invalid.

See also:

addDnsServer

Added in API level 14
VpnService.Builder addDnsServer (InetAddress address)

Add a DNS server to the VPN connection. Both IPv4 and IPv6 addresses are supported. If none is set, the DNS servers of the default network will be used. Adding a server implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address InetAddress
Returns
VpnService.Builder
Throws
IllegalArgumentException if the address is invalid.

addRoute

Added in API level 14
VpnService.Builder addRoute (String address, 
                int prefixLength)

Convenience method to add a network route to the VPN interface using a numeric address string. See InetAddress for the definitions of numeric address formats. Adding a route implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address String
prefixLength int
Returns
VpnService.Builder
Throws
IllegalArgumentException if the route is invalid.

See also:

addRoute

Added in API level 14
VpnService.Builder addRoute (InetAddress address, 
                int prefixLength)

Add a network route to the VPN interface. Both IPv4 and IPv6 routes are supported. Adding a route implicitly allows traffic from that address family (i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamily

Parameters
address InetAddress
prefixLength int
Returns
VpnService.Builder
Throws
IllegalArgumentException if the route is invalid.

addSearchDomain

Added in API level 14
VpnService.Builder addSearchDomain (String domain)

Add a search domain to the DNS resolver.

Parameters
domain String
Returns
VpnService.Builder

allowBypass

Added in API level 21
VpnService.Builder allowBypass ()

Allows all apps to bypass this VPN connection. By default, all traffic from apps is forwarded through the VPN interface and it is not possible for apps to side-step the VPN. If this method is called, apps may use methods such as bindProcessToNetwork(Network) to instead send/receive directly over the underlying network or any other network they have permissions for.

Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining of method calls.

allowFamily

Added in API level 21
VpnService.Builder allowFamily (int family)

Allows traffic from the specified address family. By default, if no address, route or DNS server of a specific family (IPv4 or IPv6) is added to this VPN, then all outgoing traffic of that family is blocked. If any address, route or DNS server is added, that family is allowed. This method allows an address family to be unblocked even without adding an address, route or DNS server of that family. Traffic of that family will then typically fall-through to the underlying network if it's supported. family must be either AF_INET (for IPv4) or AF_INET6 (for IPv6). IllegalArgumentException is thrown if it's neither.

Parameters
family int: The address family (AF_INET or AF_INET6) to allow.
Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining of method calls.

establish

Added in API level 14
ParcelFileDescriptor establish ()

Create a VPN interface using the parameters supplied to this builder. The interface works on IP packets, and a file descriptor is returned for the application to access them. Each read retrieves an outgoing packet which was routed to the interface. Each write injects an incoming packet just like it was received from the interface. The file descriptor is put into non-blocking mode by default to avoid blocking Java threads. To use the file descriptor completely in native space, see detachFd(). The application MUST close the file descriptor when the VPN connection is terminated. The VPN interface will be removed and the network will be restored by the system automatically.

To avoid conflicts, there can be only one active VPN interface at the same time. Usually network parameters are never changed during the lifetime of a VPN connection. It is also common for an application to create a new file descriptor after closing the previous one. However, it is rare but not impossible to have two interfaces while performing a seamless handover. In this case, the old interface will be deactivated when the new one is created successfully. Both file descriptors are valid but now outgoing packets will be routed to the new interface. Therefore, after draining the old file descriptor, the application MUST close it and start using the new file descriptor. If the new interface cannot be created, the existing interface and its file descriptor remain untouched.

An exception will be thrown if the interface cannot be created for any reason. However, this method returns null if the application is not prepared or is revoked. This helps solve possible race conditions between other VPN applications.

Returns
ParcelFileDescriptor ParcelFileDescriptor of the VPN interface, or null if the application is not prepared.
Throws
IllegalArgumentException if a parameter is not accepted by the operating system.
IllegalStateException if a parameter cannot be applied by the operating system.
SecurityException if the service is not properly declared in AndroidManifest.xml.

See also:

setBlocking

Added in API level 21
VpnService.Builder setBlocking (boolean blocking)

Sets the VPN interface's file descriptor to be in blocking/non-blocking mode. By default, the file descriptor returned by establish() is non-blocking.

Parameters
blocking boolean: True to put the descriptor into blocking mode; false for non-blocking.
Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining method calls.

setConfigureIntent

Added in API level 14
VpnService.Builder setConfigureIntent (PendingIntent intent)

Set the PendingIntent to an activity for users to configure the VPN connection. If it is not set, the button to configure will not be shown in system-managed dialogs.

Parameters
intent PendingIntent
Returns
VpnService.Builder

setMtu

Added in API level 14
VpnService.Builder setMtu (int mtu)

Set the maximum transmission unit (MTU) of the VPN interface. If it is not set, the default value in the operating system will be used.

Parameters
mtu int
Returns
VpnService.Builder
Throws
IllegalArgumentException if the value is not positive.

setSession

Added in API level 14
VpnService.Builder setSession (String session)

Set the name of this session. It will be displayed in system-managed dialogs and notifications. This is recommended not required.

Parameters
session String
Returns
VpnService.Builder

setUnderlyingNetworks

Added in API level 22
VpnService.Builder setUnderlyingNetworks (Network[] networks)

Sets the underlying networks used by the VPN for its upstream connections.

Parameters
networks Network: An array of networks the VPN uses to tunnel traffic to/from its servers.
Returns
VpnService.Builder this VpnService.Builder object to facilitate chaining method calls.

See also:

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.