diff options
| -rw-r--r-- | core/api/current.txt | 17 | ||||
| -rw-r--r-- | core/java/android/net/VpnManager.java | 146 |
2 files changed, 112 insertions, 51 deletions
diff --git a/core/api/current.txt b/core/api/current.txt index e5ab8d9af36b..1ac30368a493 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -25603,6 +25603,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 { diff --git a/core/java/android/net/VpnManager.java b/core/java/android/net/VpnManager.java index 5aad997af8c1..779d931245c8 100644 --- a/core/java/android/net/VpnManager.java +++ b/core/java/android/net/VpnManager.java @@ -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; |