Update VpnService Javadoc to reflect new UX.
The major change is that consent is now "sticky" and lasts until the
user explicitly disables the VPN connection.
Bug: 17474362
Change-Id: Id4e7807e635bbfc7645741135209d46763e280f9
diff --git a/core/java/android/net/VpnService.java b/core/java/android/net/VpnService.java
index 050be40..c42791c 100644
--- a/core/java/android/net/VpnService.java
+++ b/core/java/android/net/VpnService.java
@@ -62,7 +62,8 @@
* conflict with each other. The system takes several actions to address
* these issues. Here are some key points:
* <ul>
- * <li>User action is required to create a VPN connection.</li>
+ * <li>User action is required the first time an application creates a VPN
+ * connection.</li>
* <li>There can be only one VPN connection running at the same time. The
* existing interface is deactivated when a new one is created.</li>
* <li>A system-managed notification is shown during the lifetime of a
@@ -82,8 +83,8 @@
* other methods in this class, and the right can be revoked at any time.
* Here are the general steps to create a VPN connection:
* <ol>
- * <li>When the user press the button to connect, call {@link #prepare}
- * and launch the returned intent.</li>
+ * <li>When the user presses the button to connect, call {@link #prepare}
+ * and launch the returned intent, if non-null.</li>
* <li>When the application becomes prepared, start the service.</li>
* <li>Create a tunnel to the remote server and negotiate the network
* parameters for the VPN connection.</li>
@@ -130,7 +131,8 @@
/**
* Prepare to establish a VPN connection. This method returns {@code null}
- * if the VPN application is already prepared. Otherwise, it returns an
+ * if the VPN application is already prepared or if the user has previously
+ * consented to the VPN application. Otherwise, it returns an
* {@link Intent} to a system activity. The application should launch the
* activity using {@link Activity#startActivityForResult} to get itself
* prepared. The activity may pop up a dialog to require user action, and
@@ -144,6 +146,10 @@
* it becomes prepared again, subsequent calls to other methods in this
* class will fail.
*
+ * <p>The user may disable the VPN at any time while it is activated, in
+ * which case this method will return an intent the next time it is
+ * executed to obtain the user's consent again.
+ *
* @see #onRevoke
*/
public static Intent prepare(Context context) {