VpnManager
open class VpnManager
kotlin.Any | |
↳ | android.net.VpnManager |
This class provides an interface for apps to manage platform VPN profiles
Apps can use this API to provide profiles with which the platform can set up a VPN without further app intermediation. When a VPN profile is present and the app is selected as an always-on VPN, the platform will directly trigger the negotiation of the VPN without starting or waking the app (unlike VpnService).
VPN apps using supported protocols should preferentially use this API over the VpnService
API for ease-of-development and reduced maintenance burden. This also give the user the guarantee that VPN network traffic is not subjected to on-device packet interception.
Summary
Constants | |
---|---|
static String |
Action sent in |
static String |
The always-on state of this VPN was changed |
static String |
The user deactivated the VPN. |
static String |
An IKE protocol error occurred. |
static String |
A network error occurred. |
static Int |
|
static Int |
|
static Int |
An |
static Int |
An |
static Int |
An |
static Int |
An |
static String |
Extra for the error class, as an |
static String |
Extra for an error code, as an |
static String |
The key of the session that experienced this event, as a |
static String |
A |
static String |
The |
static String |
The network that was underlying the VPN when the event occurred, as a |
static String |
The |
static String |
The VpnProfileState at the time that this event occurred. |
Public methods | |
---|---|
open Unit |
Delete the VPN profile configuration that was provisioned by the calling app |
open VpnProfileState? |
Retrieve the VpnProfileState for the profile provisioned by the calling package. |
open Intent? |
provisionVpnProfile(profile: PlatformVpnProfile) Install a VpnProfile configuration keyed on the calling app's package name. |
open Unit |
Request the startup of a previously provisioned VPN. |
open String |
Request the startup of a previously provisioned VPN. |
open Unit |
Tear down the VPN provided by the calling app (if any) |
Constants
ACTION_VPN_MANAGER_EVENT
static val ACTION_VPN_MANAGER_EVENT: String
Action sent in android.content.Intent
s 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
, aString
for the session key, as returned bystartProvisionedVpnProfileSession
.EXTRA_TIMESTAMP_MILLIS
, a long for the timestamp at which the error occurred, in milliseconds since the epoch, as returned byjava.lang.System#currentTimeMillis
.EXTRA_UNDERLYING_NETWORK
, aNetwork
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
, aNetworkCapabilities
for the underlying network at the time the error occurred.EXTRA_UNDERLYING_LINK_PROPERTIES
, aLinkProperties
for the underlying network at the time the error occurred.
CATEGORY_EVENT_IKE_ERROR
or CATEGORY_EVENT_NETWORK_ERROR
, the following extras will be populated :
EXTRA_ERROR_CLASS
, anint
for the class of error, eitherERROR_CLASS_RECOVERABLE
orERROR_CLASS_NOT_RECOVERABLE
.EXTRA_ERROR_CODE
, anint
error code specific to the error. SeeEXTRA_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 theERROR_CODE_NETWORK_*
constants. - For
CATEGORY_EVENT_IKE_ERROR
, this is one of values defined inandroid.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"
Public methods
deleteProvisionedVpnProfile
open fun deleteProvisionedVpnProfile(): Unit
Delete the VPN profile configuration that was provisioned by the calling app
Exceptions | |
---|---|
java.lang.SecurityException |
if this would violate user settings |
getProvisionedVpnProfileState
open fun getProvisionedVpnProfileState(): VpnProfileState?
Retrieve the VpnProfileState for the profile provisioned by the calling package.
Return | |
---|---|
VpnProfileState? |
the VpnProfileState with current information, or null if there was no profile provisioned and started 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.
Parameters | |
---|---|
profile |
PlatformVpnProfile: the VpnProfile provided by this package. Will override any previous VpnProfile stored for this package. This value cannot be null . |
Return | |
---|---|
Intent? |
an Intent requesting user consent to start the VPN, or null if consent is not required based on privileges or previous user consent. |
startProvisionedVpnProfile
open funstartProvisionedVpnProfile(): 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.
Exceptions | |
---|---|
java.lang.SecurityException |
exception if user or device settings prevent this VPN from being setup, or if user consent has not been granted |
startProvisionedVpnProfileSession
open fun startProvisionedVpnProfileSession(): String
Request the startup of a previously provisioned VPN.
Return | |
---|---|
String |
A unique key corresponding to this session. This value cannot be null . |
Exceptions | |
---|---|
java.lang.SecurityException |
exception if user or device settings prevent this VPN from being setup, or if user consent has not been granted |
stopProvisionedVpnProfile
open fun stopProvisionedVpnProfile(): Unit
Tear down the VPN provided by the calling app (if any)