Merge "Expose VpnManager events API" (e82d94fd) · Commits · e / os / android_frameworks_base

core/api/current.txt

+17 −0

Original line number	Diff line number	Diff line
		@@ -25543,6 +25543,23 @@ package android.net {
		method @Deprecated public void startProvisionedVpnProfile();
		method @NonNull public String startProvisionedVpnProfileSession();
		method public void stopProvisionedVpnProfile();
		field public static final String ACTION_VPN_MANAGER_EVENT = "android.net.action.VPN_MANAGER_EVENT";
		field public static final String CATEGORY_EVENT_DEACTIVATED_BY_USER = "android.net.category.EVENT_DEACTIVATED_BY_USER";
		field public static final String CATEGORY_EVENT_IKE_ERROR = "android.net.category.EVENT_IKE_ERROR";
		field public static final String CATEGORY_EVENT_NETWORK_ERROR = "android.net.category.EVENT_NETWORK_ERROR";
		field public static final int ERROR_CLASS_NOT_RECOVERABLE = 1; // 0x1
		field public static final int ERROR_CLASS_RECOVERABLE = 2; // 0x2
		field public static final int ERROR_CODE_NETWORK_IO = 3; // 0x3
		field public static final int ERROR_CODE_NETWORK_LOST = 2; // 0x2
		field public static final int ERROR_CODE_NETWORK_PROTOCOL_TIMEOUT = 1; // 0x1
		field public static final int ERROR_CODE_NETWORK_UNKNOWN_HOST = 0; // 0x0
		field public static final String EXTRA_ERROR_CLASS = "android.net.extra.ERROR_CLASS";
		field public static final String EXTRA_ERROR_CODE = "android.net.extra.ERROR_CODE";
		field public static final String EXTRA_SESSION_KEY = "android.net.extra.SESSION_KEY";
		field public static final String EXTRA_TIMESTAMP = "android.net.extra.TIMESTAMP";
		field public static final String EXTRA_UNDERLYING_LINK_PROPERTIES = "android.net.extra.UNDERLYING_LINK_PROPERTIES";
		field public static final String EXTRA_UNDERLYING_NETWORK = "android.net.extra.UNDERLYING_NETWORK";
		field public static final String EXTRA_UNDERLYING_NETWORK_CAPABILITIES = "android.net.extra.UNDERLYING_NETWORK_CAPABILITIES";
		}

		public class VpnService extends android.app.Service {

core/java/android/net/VpnManager.java

+95 −51

Original line number	Diff line number	Diff line
		@@ -24,6 +24,7 @@ import android.annotation.IntDef;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.annotation.RequiresPermission;
		import android.annotation.SdkConstant;
		import android.annotation.SystemApi;
		import android.annotation.UserIdInt;
		import android.app.Activity;
		@@ -52,7 +53,7 @@ import java.util.List;
		* app (unlike VpnService).
		*
		* <p>VPN apps using supported protocols should preferentially use this API over the {@link
		* VpnService} API for ease-of-development and reduced maintainance burden. This also give the user
		* 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.
		*
		* @see Ikev2VpnProfile
		@@ -97,130 +98,173 @@ public class VpnManager {
		public static final String NOTIFICATION_CHANNEL_VPN = "VPN";

		/**
		* Action sent in the intent when an error occurred.
		* Action sent in {@link android.content.Intent}s to VpnManager clients when an event occurred.
		*
		* @hide
		* This action will have a category of either {@link #CATEGORY_EVENT_IKE_ERROR},
		* {@link #CATEGORY_EVENT_NETWORK_ERROR}, or {@link #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 :
		* <ul>
		* <li>{@link #EXTRA_SESSION_KEY}, a {@code String} for the session key, as returned by
		* {@link #startProvisionedVpnProfileSession}.
		* <li>{@link #EXTRA_TIMESTAMP}, a long for the timestamp at which the error occurred,
		* in milliseconds since the epoch, as returned by
		* {@link java.lang.System#currentTimeMillis}.
		* <li>{@link #EXTRA_UNDERLYING_NETWORK}, a {@link Network} containing the underlying
		* network at the time the error occurred, or null if none. Note that this network
		* may have disconnected already.
		* <li>{@link #EXTRA_UNDERLYING_NETWORK_CAPABILITIES}, a {@link NetworkCapabilities} for
		* the underlying network at the time the error occurred.
		* <li>{@link #EXTRA_UNDERLYING_LINK_PROPERTIES}, a {@link LinkProperties} for the underlying
		* network at the time the error occurred.
		* </ul>
		* When this event is an error, either {@link #CATEGORY_EVENT_IKE_ERROR} or
		* {@link #CATEGORY_EVENT_NETWORK_ERROR}, the following extras will be populated :
		* <ul>
		* <li>{@link #EXTRA_ERROR_CLASS}, an {@code int} for the class of error, either
		* {@link #ERROR_CLASS_RECOVERABLE} or {@link #ERROR_CLASS_NOT_RECOVERABLE}.
		* <li>{@link #EXTRA_ERROR_CODE}, an {@code int} error code specific to the error. See
		* {@link #EXTRA_ERROR_CODE} for details.
		* </ul>
		*/
		public static final String ACTION_VPN_MANAGER_ERROR = "android.net.action.VPN_MANAGER_ERROR";
		@SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION)
		public static final String ACTION_VPN_MANAGER_EVENT = "android.net.action.VPN_MANAGER_EVENT";

		/**
		* An IKE protocol error. Codes are the codes from IkeProtocolException, RFC 7296.
		* An IKE protocol error occurred.
		*
		* @hide
		* Codes (in {@link #EXTRA_ERROR_CODE}) are the codes from
		* {@link android.net.ipsec.ike.exceptions.IkeProtocolException}, as defined by IANA in
		* "IKEv2 Notify Message Types - Error Types".
		*/
		public static final String CATEGORY_ERROR_IKE = "android.net.category.ERROR_IKE";
		@SdkConstant(SdkConstant.SdkConstantType.INTENT_CATEGORY)
		public static final String CATEGORY_EVENT_IKE_ERROR = "android.net.category.EVENT_IKE_ERROR";

		/**
		* User deactivated the VPN, either by turning it off or selecting a different VPN provider.
		* The error code is always 0.
		* A network error occurred.
		*
		* @hide
		* Error codes (in {@link #EXTRA_ERROR_CODE}) are ERROR_CODE_NETWORK_*.
		*/
		public static final String CATEGORY_ERROR_USER_DEACTIVATED =
		"android.net.category.ERROR_USER_DEACTIVATED";
		@SdkConstant(SdkConstant.SdkConstantType.INTENT_CATEGORY)
		public static final String CATEGORY_EVENT_NETWORK_ERROR =
		"android.net.category.EVENT_NETWORK_ERROR";

		/**
		* Network error. Error codes are ERROR_CODE_NETWORK_*.
		* The user deactivated the VPN.
		*
		* @hide
		* This can happen either when the user turns the VPN off explicitly, or when they select
		* a different VPN provider.
		*/
		public static final String CATEGORY_ERROR_NETWORK = "android.net.category.ERROR_NETWORK";
		@SdkConstant(SdkConstant.SdkConstantType.INTENT_CATEGORY)
		public static final String CATEGORY_EVENT_DEACTIVATED_BY_USER =
		"android.net.category.EVENT_DEACTIVATED_BY_USER";

		/**
		* The key of the session that experienced this error, as returned by
		* startProvisionedVpnProfileSession.
		* The key of the session that experienced this event, as a {@code String}.
		*
		* @hide
		* This is the same key that was returned by {@link #startProvisionedVpnProfileSession}.
		*/
		public static final String EXTRA_SESSION_KEY = "android.net.extra.SESSION_KEY";

		/**
		* Extra for the Network object that was the underlying network at the time of the failure, or
		* null if none.
		* The network that was underlying the VPN when the event occurred, as a {@link Network}.
		*
		* @hide
		* This extra will be null if there was no underlying network at the time of the event.
		*/
		public static final String EXTRA_UNDERLYING_NETWORK = "android.net.extra.UNDERLYING_NETWORK";

		/**
		* The NetworkCapabilities of the underlying network.
		* The {@link NetworkCapabilities} of the underlying network when the event occurred.
		*
		* @hide
		* This extra will be null if there was no underlying network at the time of the event.
		*/
		public static final String EXTRA_UNDERLYING_NETWORK_CAPABILITIES =
		"android.net.extra.UNDERLYING_NETWORK_CAPABILITIES";

		/**
		* The LinkProperties of the underlying network.
		* The {@link LinkProperties} of the underlying network when the event occurred.
		*
		* @hide
		* This extra will be null if there was no underlying network at the time of the event.
		*/
		public static final String EXTRA_UNDERLYING_LINK_PROPERTIES =
		"android.net.extra.UNDERLYING_LINK_PROPERTIES";

		/**
		* A long timestamp with SystemClock.elapsedRealtime base for when the event happened.
		* A {@code long} timestamp containing the time at which the event occurred.
		*
		* @hide
		* This is a number of milliseconds since the epoch, suitable to be compared with
		* {@link java.lang.System#currentTimeMillis}.
		*/
		public static final String EXTRA_TIMESTAMP = "android.net.extra.TIMESTAMP";

		/**
		* Extra for the error type. This is ERROR_NOT_RECOVERABLE or ERROR_RECOVERABLE.
		* Extra for the error class, as an {@code int}.
		*
		* @hide
		* This is always either {@link #ERROR_CLASS_NOT_RECOVERABLE} or
		* {@link #ERROR_CLASS_RECOVERABLE}. This extra is only populated for error categories.
		*/
		public static final String EXTRA_ERROR_TYPE = "android.net.extra.ERROR_TYPE";
		public static final String EXTRA_ERROR_CLASS = "android.net.extra.ERROR_CLASS";

		/**
		* Extra for the error code. The value will be 0 for CATEGORY_ERROR_USER_DEACTIVATED, one of
		* ERROR_CODE_NETWORK_* for ERROR_CATEGORY_NETWORK or one of values defined in
		* IkeProtocolException#ErrorType for CATEGORY_ERROR_IKE.
		* Extra for an error code, as an {@code int}.
		*
		* @hide
		* <ul>
		* <li>For {@link #CATEGORY_EVENT_NETWORK_ERROR}, this is one of the
		* {@code ERROR_CODE_NETWORK_*} constants.
		* <li>For {@link #CATEGORY_EVENT_IKE_ERROR}, this is one of values defined in
		* {@link android.net.ipsec.ike.exceptions.IkeProtocolException}.ERROR_TYPE_*.
		* </ul>
		* For non-error categories, this extra is not populated.
		*/
		public static final String EXTRA_ERROR_CODE = "android.net.extra.ERROR_CODE";

		/**
		* This error is fatal, e.g. the VPN was disabled or configuration error. The stack will not
		* retry connection.
		* {@link #EXTRA_ERROR_CLASS} coding for a non-recoverable error.
		*
		* @hide
		* This error is fatal, e.g. configuration error. The stack will not retry connection.
		*/
		public static final int ERROR_NOT_RECOVERABLE = 1;
		public static final int ERROR_CLASS_NOT_RECOVERABLE = 1;

		/**
		* The stack experienced an error but will retry with exponential backoff, e.g. network timeout.
		* {@link #EXTRA_ERROR_CLASS} coding for a recoverable error.
		*
		* @hide
		* The stack experienced an error but will retry with exponential backoff, e.g. network timeout.
		*/
		public static final int ERROR_RECOVERABLE = 2;
		public static final int ERROR_CLASS_RECOVERABLE = 2;

		/**
		* An error code to indicate that there was an UnknownHostException.
		* An {@link #EXTRA_ERROR_CODE} for {@link #CATEGORY_EVENT_NETWORK_ERROR} to indicate that the
		* network host isn't known.
		*
		* @hide
		* This happens when domain name resolution could not resolve an IP address for the
		* specified host. {@see java.net.UnknownHostException}
		*/
		public static final int ERROR_CODE_NETWORK_UNKNOWN_HOST = 0;

		/**
		* An error code to indicate that there is a SocketTimeoutException.
		* An {@link #EXTRA_ERROR_CODE} for {@link #CATEGORY_EVENT_NETWORK_ERROR} indicating a timeout.
		*
		* @hide
		* For Ikev2 VPNs, this happens typically after a retransmission failure.
		* {@see android.net.ipsec.ike.exceptions.IkeTimeoutException}
		*/
		public static final int ERROR_CODE_NETWORK_TIMEOUT = 1;
		public static final int ERROR_CODE_NETWORK_PROTOCOL_TIMEOUT = 1;

		/**
		* An error code to indicate the connection was reset. (e.g. SocketException)
		* An {@link #EXTRA_ERROR_CODE} for {@link #CATEGORY_EVENT_NETWORK_ERROR} indicating that
		* network connectivity was lost.
		*
		* @hide
		* The most common reason for this error is that the underlying network was disconnected,
		* {@see android.net.ipsec.ike.exceptions.IkeNetworkLostException}.
		*/
		public static final int ERROR_CODE_NETWORK_RESET = 2;
		public static final int ERROR_CODE_NETWORK_LOST = 2;

		/**
		* An error code to indicate that there is an IOException.
		* An {@link #EXTRA_ERROR_CODE} for {@link #CATEGORY_EVENT_NETWORK_ERROR} indicating an
		* input/output error.
		*
		* @hide
		* This code happens when reading or writing to sockets on the underlying networks was
		* terminated by an I/O error. {@see IOException}.
		*/
		public static final int ERROR_CODE_NETWORK_IO = 3;