VpnService.Builder.Establish Method

Reference

Definition

Namespace:: Android.Net

Assembly:: Mono.Android.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

[Android.Runtime.Register("establish", "()Landroid/os/ParcelFileDescriptor;", "GetEstablishHandler")]
public virtual Android.OS.ParcelFileDescriptor? Establish ();

[<Android.Runtime.Register("establish", "()Landroid/os/ParcelFileDescriptor;", "GetEstablishHandler")>]
abstract member Establish : unit -> Android.OS.ParcelFileDescriptor
override this.Establish : unit -> Android.OS.ParcelFileDescriptor

Returns

ParcelFileDescriptor

ParcelFileDescriptor of the VPN interface, or null if the application is not prepared.

Attributes: RegisterAttribute

Exceptions

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.

Remarks

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 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.

Java documentation for android.net.VpnService.Builder.establish().

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to