public class VpnService.Builder extends Object
VpnService
.VpnService
Constructor and Description |
---|
Builder() |
Modifier and Type | Method and Description |
---|---|
VpnService.Builder |
addAddress(InetAddress address,
int prefixLength)
Add a network address to the VPN interface.
|
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 |
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(InetAddress address)
Add a DNS server 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 |
addRoute(InetAddress address,
int prefixLength)
Add a network route to the VPN interface.
|
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 |
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.
|
public VpnService.Builder setSession(String session)
public VpnService.Builder setConfigureIntent(PendingIntent intent)
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.public VpnService.Builder setMtu(int mtu)
IllegalArgumentException
- if the value is not positive.public VpnService.Builder addAddress(InetAddress address, int prefixLength)
establish()
.
Adding an address implicitly allows traffic from that address family
(i.e., IPv4 or IPv6) to be routed over the VPN. @see #allowFamilyIllegalArgumentException
- if the address is invalid.public VpnService.Builder addAddress(String address, int prefixLength)
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 #allowFamilyIllegalArgumentException
- if the address is invalid.addAddress(InetAddress, int)
public VpnService.Builder addRoute(InetAddress address, int prefixLength)
IllegalArgumentException
- if the route is invalid.public VpnService.Builder addRoute(String address, int prefixLength)
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 #allowFamilyIllegalArgumentException
- if the route is invalid.addRoute(InetAddress, int)
public VpnService.Builder addDnsServer(InetAddress address)
IllegalArgumentException
- if the address is invalid.public VpnService.Builder addDnsServer(String address)
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 #allowFamilyIllegalArgumentException
- if the address is invalid.addDnsServer(InetAddress)
public VpnService.Builder addSearchDomain(String domain)
public VpnService.Builder allowFamily(int family)
family
must be either AF_INET
(for IPv4) or AF_INET6
(for IPv6).
IllegalArgumentException
is thrown if it's neither.family
- The address family (AF_INET
or AF_INET6
) to allow.VpnService.Builder
object to facilitate chaining of method calls.public VpnService.Builder addAllowedApplication(String packageName) throws PackageManager.NameNotFoundException
VpnService.Builder
may have only a set of allowed applications OR a set of disallowed
ones, but not both. Calling this method after addDisallowedApplication(java.lang.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.packageName
- The full name (e.g.: "com.google.apps.contacts") of an application.VpnService.Builder
object to facilitate chaining method calls.PackageManager.NameNotFoundException
- If the application isn't installed.public VpnService.Builder addDisallowedApplication(String packageName) throws PackageManager.NameNotFoundException
VpnService.Builder
may have only a set of allowed applications OR a set of disallowed
ones, but not both. Calling this method after addAllowedApplication(java.lang.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.packageName
- The full name (e.g.: "com.google.apps.contacts") of an application.VpnService.Builder
object to facilitate chaining method calls.PackageManager.NameNotFoundException
- If the application isn't installed.public VpnService.Builder allowBypass()
ConnectivityManager.bindProcessToNetwork(android.net.Network)
to instead send/receive
directly over the underlying network or any other network they have permissions for.VpnService.Builder
object to facilitate chaining of method calls.public VpnService.Builder setBlocking(boolean blocking)
establish()
is non-blocking.blocking
- True to put the descriptor into blocking mode; false for non-blocking.VpnService.Builder
object to facilitate chaining method calls.public VpnService.Builder setUnderlyingNetworks(Network[] networks)
networks
- An array of networks the VPN uses to tunnel traffic to/from its servers.VpnService.Builder
object to facilitate chaining method calls.VpnService.setUnderlyingNetworks(android.net.Network[])
public ParcelFileDescriptor establish()
ParcelFileDescriptor.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.
ParcelFileDescriptor
of the VPN interface, or
null
if the application is not prepared.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
.VpnService