VpnManager

ACTION_VPN_MANAGER_EVENT

static val ACTION_VPN_MANAGER_EVENT: String

Action sent in android.content.Intents to VpnManager clients when an event occurred.

If the provisioning application declares a service handling this intent action, but is not already running, it will be started. Upon starting, the application is granted a short grace period to run in the background even while the device is idle to handle any potential failures. Applications requiring long-running actions triggered by one of these events should declare a foreground service to prevent being killed once the grace period expires. This action will have a category of either CATEGORY_EVENT_IKE_ERROR, CATEGORY_EVENT_NETWORK_ERROR, or CATEGORY_EVENT_DEACTIVATED_BY_USER, that the app can use to filter events it's interested in reacting to. It will also contain the following extras :

• EXTRA_SESSION_KEY, a String for the session key, as returned by startProvisionedVpnProfileSession.
• EXTRA_TIMESTAMP_MILLIS, a long for the timestamp at which the error occurred, in milliseconds since the epoch, as returned by java.lang.System#currentTimeMillis.
• EXTRA_UNDERLYING_NETWORK, a Network containing the underlying network at the time the error occurred, or null if none. Note that this network may have disconnected already.
• EXTRA_UNDERLYING_NETWORK_CAPABILITIES, a NetworkCapabilities for the underlying network at the time the error occurred.
• EXTRA_UNDERLYING_LINK_PROPERTIES, a LinkProperties for the underlying network at the time the error occurred.

• EXTRA_ERROR_CLASS, an int for the class of error, either ERROR_CLASS_RECOVERABLE or ERROR_CLASS_NOT_RECOVERABLE.
• EXTRA_ERROR_CODE, an int error code specific to the error. See EXTRA_ERROR_CODE for details.

Value: "android.net.action.VPN_MANAGER_EVENT"

CATEGORY_EVENT_ALWAYS_ON_STATE_CHANGED

static val CATEGORY_EVENT_ALWAYS_ON_STATE_CHANGED: String

The always-on state of this VPN was changed

This may be the result of a user changing VPN settings, or a Device Policy Manager app having changed the VPN policy.

Value: "android.net.category.EVENT_ALWAYS_ON_STATE_CHANGED"

CATEGORY_EVENT_DEACTIVATED_BY_USER

static val CATEGORY_EVENT_DEACTIVATED_BY_USER: String

The user deactivated the VPN. This can happen either when the user turns the VPN off explicitly, or when they select a different VPN provider.

Value: "android.net.category.EVENT_DEACTIVATED_BY_USER"

CATEGORY_EVENT_IKE_ERROR

static val CATEGORY_EVENT_IKE_ERROR: String

An IKE protocol error occurred. Codes (in EXTRA_ERROR_CODE) are the codes from android.net.ipsec.ike.exceptions.IkeProtocolException, as defined by IANA in "IKEv2 Notify Message Types - Error Types".

Value: "android.net.category.EVENT_IKE_ERROR"

CATEGORY_EVENT_NETWORK_ERROR

static val CATEGORY_EVENT_NETWORK_ERROR: String

A network error occurred. Error codes (in EXTRA_ERROR_CODE) are ERROR_CODE_NETWORK_*.

Value: "android.net.category.EVENT_NETWORK_ERROR"

ERROR_CLASS_NOT_RECOVERABLE

static val ERROR_CLASS_NOT_RECOVERABLE: Int

EXTRA_ERROR_CLASS coding for a non-recoverable error. This error is fatal, e.g. configuration error. The stack will not retry connection.

Value: 1

ERROR_CLASS_RECOVERABLE

static val ERROR_CLASS_RECOVERABLE: Int

EXTRA_ERROR_CLASS coding for a recoverable error. The stack experienced an error but will retry with exponential backoff, e.g. network timeout.

Value: 2

ERROR_CODE_NETWORK_IO

static val ERROR_CODE_NETWORK_IO: Int

An EXTRA_ERROR_CODE for CATEGORY_EVENT_NETWORK_ERROR indicating an input/output error. This code happens when reading or writing to sockets on the underlying networks was terminated by an I/O error. {@see IOException}.

Value: 3

ERROR_CODE_NETWORK_LOST

static val ERROR_CODE_NETWORK_LOST: Int

An EXTRA_ERROR_CODE for CATEGORY_EVENT_NETWORK_ERROR indicating that network connectivity was lost. The most common reason for this error is that the underlying network was disconnected, {@see android.net.ipsec.ike.exceptions.IkeNetworkLostException}.

Value: 2

ERROR_CODE_NETWORK_PROTOCOL_TIMEOUT

static val ERROR_CODE_NETWORK_PROTOCOL_TIMEOUT: Int

An EXTRA_ERROR_CODE for CATEGORY_EVENT_NETWORK_ERROR indicating a timeout. For Ikev2 VPNs, this happens typically after a retransmission failure. {@see android.net.ipsec.ike.exceptions.IkeTimeoutException}

Value: 1

ERROR_CODE_NETWORK_UNKNOWN_HOST

static val ERROR_CODE_NETWORK_UNKNOWN_HOST: Int

An EXTRA_ERROR_CODE for CATEGORY_EVENT_NETWORK_ERROR to indicate that the network host isn't known. This happens when domain name resolution could not resolve an IP address for the specified host. {@see java.net.UnknownHostException}

Value: 0

EXTRA_ERROR_CLASS

static val EXTRA_ERROR_CLASS: String

Extra for the error class, as an int. This is always either ERROR_CLASS_NOT_RECOVERABLE or ERROR_CLASS_RECOVERABLE. This extra is only populated for error categories.

Value: "android.net.extra.ERROR_CLASS"

EXTRA_ERROR_CODE

static val EXTRA_ERROR_CODE: String

Extra for an error code, as an int.

• For CATEGORY_EVENT_NETWORK_ERROR, this is one of the ERROR_CODE_NETWORK_* constants.
• For CATEGORY_EVENT_IKE_ERROR, this is one of values defined in android.net.ipsec.ike.exceptions.IkeProtocolException.ERROR_TYPE_*.

Value: "android.net.extra.ERROR_CODE"

EXTRA_SESSION_KEY

static val EXTRA_SESSION_KEY: String

The key of the session that experienced this event, as a String. This is the same key that was returned by startProvisionedVpnProfileSession.

Value: "android.net.extra.SESSION_KEY"

EXTRA_TIMESTAMP_MILLIS

static val EXTRA_TIMESTAMP_MILLIS: String

A long timestamp containing the time at which the event occurred. This is a number of milliseconds since the epoch, suitable to be compared with java.lang.System#currentTimeMillis.

Value: "android.net.extra.TIMESTAMP_MILLIS"

EXTRA_UNDERLYING_LINK_PROPERTIES

static val EXTRA_UNDERLYING_LINK_PROPERTIES: String

The LinkProperties of the underlying network when the event occurred.

This extra will be null if there was no underlying network at the time of the event, or the underlying network has no bearing on the event, as in the case of:

• CATEGORY_EVENT_DEACTIVATED_BY_USER
• CATEGORY_EVENT_ALWAYS_ON_STATE_CHANGED

Value: "android.net.extra.UNDERLYING_LINK_PROPERTIES"

EXTRA_UNDERLYING_NETWORK

static val EXTRA_UNDERLYING_NETWORK: String

The network that was underlying the VPN when the event occurred, as a Network.

This extra will be null if there was no underlying network at the time of the event, or the underlying network has no bearing on the event, as in the case of:

• CATEGORY_EVENT_DEACTIVATED_BY_USER
• CATEGORY_EVENT_ALWAYS_ON_STATE_CHANGED

Value: "android.net.extra.UNDERLYING_NETWORK"

EXTRA_UNDERLYING_NETWORK_CAPABILITIES

static val EXTRA_UNDERLYING_NETWORK_CAPABILITIES: String

The NetworkCapabilities of the underlying network when the event occurred.

This extra will be null if there was no underlying network at the time of the event, or the underlying network has no bearing on the event, as in the case of:

• CATEGORY_EVENT_DEACTIVATED_BY_USER
• CATEGORY_EVENT_ALWAYS_ON_STATE_CHANGED

Value: "android.net.extra.UNDERLYING_NETWORK_CAPABILITIES"

EXTRA_VPN_PROFILE_STATE

static val EXTRA_VPN_PROFILE_STATE: String

The VpnProfileState at the time that this event occurred.

This extra may be null if the VPN was revoked by the user, or the profile was deleted.

Value: "android.net.extra.VPN_PROFILE_STATE"

deleteProvisionedVpnProfile

open fun deleteProvisionedVpnProfile(): Unit

Delete the VPN profile configuration that was provisioned by the calling app

getProvisionedVpnProfileState

open fun getProvisionedVpnProfileState(): VpnProfileState?

Retrieve the VpnProfileState for the profile provisioned by the calling package.

provisionVpnProfile

open fun provisionVpnProfile(profile: PlatformVpnProfile): Intent?

Install a VpnProfile configuration keyed on the calling app's package name.

This method returns null if user consent has already been granted, or an Intent to a system activity. If an intent is returned, the application should launch the activity using android.app.Activity#startActivityForResult to request user consent. The activity may pop up a dialog to require user action, and the result will come back via its android.app.Activity#onActivityResult. If the result is Activity.RESULT_OK, the user has consented, and the VPN profile can be started.

startProvisionedVpnProfile

open fun startProvisionedVpnProfile(): Unit

Deprecated: This method is replaced by startProvisionedVpnProfileSession which returns a session key for the caller to diagnose the errors.

Request the startup of a previously provisioned VPN.

startProvisionedVpnProfileSession

open fun startProvisionedVpnProfileSession(): String

Request the startup of a previously provisioned VPN.

stopProvisionedVpnProfile

open fun stopProvisionedVpnProfile(): Unit

Tear down the VPN provided by the calling app (if any)