Merge "Merge "Docs -- Revised method descriptions of... (f683400e) · Commits · e / os / android_frameworks_base

core/java/android/webkit/SslErrorHandler.java

+28 −12

Original line number	Diff line number	Diff line
		@@ -20,11 +20,15 @@ import android.annotation.SystemApi;
		import android.os.Handler;

		/**
		* Represents a request for handling an SSL error. Instances of this class are
		* created by the WebView and passed to
		* {@link WebViewClient#onReceivedSslError}. The host application must call
		* either {@link #proceed} or {@link #cancel} to set the WebView's response
		* to the request.
		* Represents a request for handling an SSL error.
		*
		* <p>A {@link WebView} creates an instance of this class. The instance is
		* passed to {@link WebViewClient#onReceivedSslError(WebView, SslErrorHandler,
		* SslError)}.
		*
		* <p>The host application must call {@link #cancel()} or, contrary to secure
		* web communication standards, {@link #proceed()} to provide the web view's
		* response to the request.
		*/
		public class SslErrorHandler extends Handler {

		@@ -35,17 +39,29 @@ public class SslErrorHandler extends Handler {
		public SslErrorHandler() {}

		/**
		* Proceed with the SSL certificate.
		* <p>
		* It is not recommended to proceed past SSL errors and this method should
		* generally not be used; see {@link WebViewClient#onReceivedSslError} for
		* more information.
		* Instructs the {@code WebView} that encountered the SSL certificate error
		* to ignore the error and continue communicating with the server.
		*
		* <p class="warning"><b>Warning:</b> When an SSL error occurs, the host
		* application should always call {@link #cancel()} rather than
		* {@code proceed()} because an invalid SSL certificate means the connection
		* is not secure.
		*
		* @see WebViewClient#onReceivedSslError(WebView, SslErrorHandler,
		* SslError)
		*/
		public void proceed() {}

		/**
		* Cancel this request and all pending requests for the WebView that had
		* the error.
		* Instructs the {@code WebView} that encountered the SSL certificate error
		* to terminate communication with the server. Cancels the current server
		* request and all pending requests for the {@code WebView}.
		*
		* <p>The host application must call this method to prevent a resource from
		* loading when an SSL certificate is invalid.
		*
		* @see WebViewClient#onReceivedSslError(WebView, SslErrorHandler,
		* SslError)
		*/
		public void cancel() {}
		}

core/java/android/webkit/WebViewClient.java

+26 −22

Original line number	Diff line number	Diff line
		@@ -382,30 +382,34 @@ public class WebViewClient {
		}

		/**
		* Notify the host application that an SSL error occurred while loading a
		* resource. The host application must call either {@link SslErrorHandler#cancel} or
		* {@link SslErrorHandler#proceed}. Note that the decision may be retained for use in
		* response to future SSL errors. The default behavior is to cancel the
		* load.
		* <p>
		* This API is only called for recoverable SSL certificate errors. In the case of
		* non-recoverable errors (such as when the server fails the client), WebView will call {@link
		* #onReceivedError(WebView, WebResourceRequest, WebResourceError)} with {@link
		* #ERROR_FAILED_SSL_HANDSHAKE}.
		* <p>
		* Applications are advised not to prompt the user about SSL errors, as
		* the user is unlikely to be able to make an informed security decision
		* and WebView does not provide any UI for showing the details of the
		* Notifies the host application that an SSL error occurred while loading a
		* resource. The host application must call either
		* {@link SslErrorHandler#cancel()} or {@link SslErrorHandler#proceed()}.
		*
		* <p class="warning"><b>Warning:</b> Application overrides of this method
		* can be used to display custom error pages or to silently log issues, but
		* the host application should always call {@code SslErrorHandler#cancel()}
		* and never proceed past errors.
		*
		* <p class="note"><b>Note:</b> Do not prompt the user about SSL errors.
		* Users are unlikely to be able to make an informed security decision, and
		* {@code WebView} does not provide a UI for showing the details of the
		* error in a meaningful way.
		* <p>
		* Application overrides of this method may display custom error pages or
		* silently log issues, but it is strongly recommended to always call
		* {@link SslErrorHandler#cancel} and never allow proceeding past errors.
		*
		* @param view The WebView that is initiating the callback.
		* @param handler An {@link SslErrorHandler} that will handle the user's
		* response.
		* @param error The SSL error object.
		* <p>The decision to call {@code proceed()} or {@code cancel()} may be
		* retained to facilitate responses to future SSL errors. The default
		* behavior is to cancel the resource loading process.
		*
		* <p>This API is called only for recoverable SSL certificate errors. For
		* non-recoverable errors (such as when the server fails the client), the
		* {@code WebView} calls {@link #onReceivedError(WebView,
		* WebResourceRequest, WebResourceError) onReceivedError(WebView,
		* WebResourceRequest, WebResourceError)} with the
		* {@link #ERROR_FAILED_SSL_HANDSHAKE} argument.
		*
		* @param view {@code WebView} that initiated the callback.
		* @param handler {@link SslErrorHandler} that handles the user's response.
		* @param error SSL error object.
		*/
		public void onReceivedSslError(WebView view, SslErrorHandler handler,
		SslError error) {