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
.
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Convenience method to add a network address to the VPN interface
using a numeric address string.
| |||||||||||
Add a network address to the VPN interface.
| |||||||||||
Adds an application that's allowed to access the VPN connection.
| |||||||||||
Adds an application that's denied access to the VPN connection.
| |||||||||||
Convenience method to add a DNS server to the VPN connection
using a numeric address string.
| |||||||||||
Add a DNS server to the VPN connection.
| |||||||||||
Convenience method to add a network route to the VPN interface
using a numeric address string.
| |||||||||||
Add a network route to the VPN interface.
| |||||||||||
Add a search domain to the DNS resolver.
| |||||||||||
Allows all apps to bypass this VPN connection.
| |||||||||||
Allows traffic from the specified address family.
| |||||||||||
Create a VPN interface using the parameters supplied to this
builder.
| |||||||||||
Sets the VPN interface's file descriptor to be in blocking/non-blocking mode.
| |||||||||||
Set the
PendingIntent to an activity for users to
configure the VPN connection.
| |||||||||||
Set the maximum transmission unit (MTU) of the VPN interface.
| |||||||||||
Set the name of this session.
| |||||||||||
Sets the underlying networks used by the VPN for its upstream connections.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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
IllegalArgumentException | if the address is invalid. |
---|
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
IllegalArgumentException | if the address is invalid. |
---|
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.
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. | |
PackageManager.NameNotFoundException |
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.
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. | |
PackageManager.NameNotFoundException |
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
IllegalArgumentException | if the address is invalid. |
---|
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
IllegalArgumentException | if the address is invalid. |
---|
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
IllegalArgumentException | if the route is invalid. |
---|
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
IllegalArgumentException | if the route is invalid. |
---|
Add a search domain to the DNS resolver.
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 setProcessDefaultNetwork(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.
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.
family | The address family (AF_INET or AF_INET6 ) to allow. |
---|
VpnService.Builder
object to facilitate chaining of method calls.
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.
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 . |
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.
blocking | True to put the descriptor into blocking mode; false for non-blocking. |
---|
VpnService.Builder
object to facilitate chaining method calls.
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.
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.
IllegalArgumentException | if the value is not positive. |
---|
Set the name of this session. It will be displayed in system-managed dialogs and notifications. This is recommended not required.
Sets the underlying networks used by the VPN for its upstream connections.
networks | An array of networks the VPN uses to tunnel traffic to/from its servers. |
---|
VpnService.Builder
object to facilitate chaining method calls.