Java tutorial
/* * Copyright (C) 2008 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.webkit; import android.annotation.IntDef; import android.annotation.Nullable; import android.graphics.Bitmap; import android.net.http.SslError; import android.os.Message; import android.view.InputEvent; import android.view.KeyEvent; import android.view.ViewRootImpl; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; public class WebViewClient { /** * Give the host application a chance to take control when a URL is about to be loaded in the * current WebView. If a WebViewClient is not provided, by default WebView will ask Activity * Manager to choose the proper handler for the URL. If a WebViewClient is provided, returning * {@code true} causes the current WebView to abort loading the URL, while returning * {@code false} causes the WebView to continue loading the URL as usual. * * <p class="note"><b>Note:</b> Do not call {@link WebView#loadUrl(String)} with the same * URL and then return {@code true}. This unnecessarily cancels the current load and starts a * new load with the same URL. The correct way to continue loading a given URL is to simply * return {@code false}, without calling {@link WebView#loadUrl(String)}. * * <p class="note"><b>Note:</b> This method is not called for POST requests. * * <p class="note"><b>Note:</b> This method may be called for subframes and with non-HTTP(S) * schemes; calling {@link WebView#loadUrl(String)} with such a URL will fail. * * @param view The WebView that is initiating the callback. * @param url The URL to be loaded. * @return {@code true} to cancel the current load, otherwise return {@code false}. * @deprecated Use {@link #shouldOverrideUrlLoading(WebView, WebResourceRequest) * shouldOverrideUrlLoading(WebView, WebResourceRequest)} instead. */ @Deprecated public boolean shouldOverrideUrlLoading(WebView view, String url) { return false; } /** * Give the host application a chance to take control when a URL is about to be loaded in the * current WebView. If a WebViewClient is not provided, by default WebView will ask Activity * Manager to choose the proper handler for the URL. If a WebViewClient is provided, returning * {@code true} causes the current WebView to abort loading the URL, while returning * {@code false} causes the WebView to continue loading the URL as usual. * * <p class="note"><b>Note:</b> Do not call {@link WebView#loadUrl(String)} with the request's * URL and then return {@code true}. This unnecessarily cancels the current load and starts a * new load with the same URL. The correct way to continue loading a given URL is to simply * return {@code false}, without calling {@link WebView#loadUrl(String)}. * * <p class="note"><b>Note:</b> This method is not called for POST requests. * * <p class="note"><b>Note:</b> This method may be called for subframes and with non-HTTP(S) * schemes; calling {@link WebView#loadUrl(String)} with such a URL will fail. * * @param view The WebView that is initiating the callback. * @param request Object containing the details of the request. * @return {@code true} to cancel the current load, otherwise return {@code false}. */ public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) { return shouldOverrideUrlLoading(view, request.getUrl().toString()); } /** * Notify the host application that a page has started loading. This method * is called once for each main frame load so a page with iframes or * framesets will call onPageStarted one time for the main frame. This also * means that onPageStarted will not be called when the contents of an * embedded frame changes, i.e. clicking a link whose target is an iframe, * it will also not be called for fragment navigations (navigations to * #fragment_id). * * @param view The WebView that is initiating the callback. * @param url The url to be loaded. * @param favicon The favicon for this page if it already exists in the * database. */ public void onPageStarted(WebView view, String url, Bitmap favicon) { } /** * Notify the host application that a page has finished loading. This method * is called only for main frame. Receiving an {@code onPageFinished()} callback does not * guarantee that the next frame drawn by WebView will reflect the state of the DOM at this * point. In order to be notified that the current DOM state is ready to be rendered, request a * visual state callback with {@link WebView#postVisualStateCallback} and wait for the supplied * callback to be triggered. * * @param view The WebView that is initiating the callback. * @param url The url of the page. */ public void onPageFinished(WebView view, String url) { } /** * Notify the host application that the WebView will load the resource * specified by the given url. * * @param view The WebView that is initiating the callback. * @param url The url of the resource the WebView will load. */ public void onLoadResource(WebView view, String url) { } /** * Notify the host application that {@link android.webkit.WebView} content left over from * previous page navigations will no longer be drawn. * * <p>This callback can be used to determine the point at which it is safe to make a recycled * {@link android.webkit.WebView} visible, ensuring that no stale content is shown. It is called * at the earliest point at which it can be guaranteed that {@link WebView#onDraw} will no * longer draw any content from previous navigations. The next draw will display either the * {@link WebView#setBackgroundColor background color} of the {@link WebView}, or some of the * contents of the newly loaded page. * * <p>This method is called when the body of the HTTP response has started loading, is reflected * in the DOM, and will be visible in subsequent draws. This callback occurs early in the * document loading process, and as such you should expect that linked resources (for example, * CSS and images) may not be available. * * <p>For more fine-grained notification of visual state updates, see {@link * WebView#postVisualStateCallback}. * * <p>Please note that all the conditions and recommendations applicable to * {@link WebView#postVisualStateCallback} also apply to this API. * * <p>This callback is only called for main frame navigations. * * @param view The {@link android.webkit.WebView} for which the navigation occurred. * @param url The URL corresponding to the page navigation that triggered this callback. */ public void onPageCommitVisible(WebView view, String url) { } /** * Notify the host application of a resource request and allow the * application to return the data. If the return value is {@code null}, the WebView * will continue to load the resource as usual. Otherwise, the return * response and data will be used. * * <p>This callback is invoked for a variety of URL schemes (e.g., {@code http(s):}, {@code * data:}, {@code file:}, etc.), not only those schemes which send requests over the network. * This is not called for {@code javascript:} URLs, {@code blob:} URLs, or for assets accessed * via {@code file:///android_asset/} or {@code file:///android_res/} URLs. * * <p>In the case of redirects, this is only called for the initial resource URL, not any * subsequent redirect URLs. * * <p class="note"><b>Note:</b> This method is called on a thread * other than the UI thread so clients should exercise caution * when accessing private data or the view system. * * <p class="note"><b>Note:</b> When Safe Browsing is enabled, these URLs still undergo Safe * Browsing checks. If this is undesired, whitelist the URL with {@link * WebView#setSafeBrowsingWhitelist} or ignore the warning with {@link #onSafeBrowsingHit}. * * @param view The {@link android.webkit.WebView} that is requesting the * resource. * @param url The raw url of the resource. * @return A {@link android.webkit.WebResourceResponse} containing the * response information or {@code null} if the WebView should load the * resource itself. * @deprecated Use {@link #shouldInterceptRequest(WebView, WebResourceRequest) * shouldInterceptRequest(WebView, WebResourceRequest)} instead. */ @Deprecated @Nullable public WebResourceResponse shouldInterceptRequest(WebView view, String url) { return null; } /** * Notify the host application of a resource request and allow the * application to return the data. If the return value is {@code null}, the WebView * will continue to load the resource as usual. Otherwise, the return * response and data will be used. * * <p>This callback is invoked for a variety of URL schemes (e.g., {@code http(s):}, {@code * data:}, {@code file:}, etc.), not only those schemes which send requests over the network. * This is not called for {@code javascript:} URLs, {@code blob:} URLs, or for assets accessed * via {@code file:///android_asset/} or {@code file:///android_res/} URLs. * * <p>In the case of redirects, this is only called for the initial resource URL, not any * subsequent redirect URLs. * * <p class="note"><b>Note:</b> This method is called on a thread * other than the UI thread so clients should exercise caution * when accessing private data or the view system. * * <p class="note"><b>Note:</b> When Safe Browsing is enabled, these URLs still undergo Safe * Browsing checks. If this is undesired, whitelist the URL with {@link * WebView#setSafeBrowsingWhitelist} or ignore the warning with {@link #onSafeBrowsingHit}. * * @param view The {@link android.webkit.WebView} that is requesting the * resource. * @param request Object containing the details of the request. * @return A {@link android.webkit.WebResourceResponse} containing the * response information or {@code null} if the WebView should load the * resource itself. */ @Nullable public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) { return shouldInterceptRequest(view, request.getUrl().toString()); } /** * Notify the host application that there have been an excessive number of * HTTP redirects. As the host application if it would like to continue * trying to load the resource. The default behavior is to send the cancel * message. * * @param view The WebView that is initiating the callback. * @param cancelMsg The message to send if the host wants to cancel * @param continueMsg The message to send if the host wants to continue * @deprecated This method is no longer called. When the WebView encounters * a redirect loop, it will cancel the load. */ @Deprecated public void onTooManyRedirects(WebView view, Message cancelMsg, Message continueMsg) { cancelMsg.sendToTarget(); } // These ints must match up to the hidden values in EventHandler. /** Generic error */ public static final int ERROR_UNKNOWN = -1; /** Server or proxy hostname lookup failed */ public static final int ERROR_HOST_LOOKUP = -2; /** Unsupported authentication scheme (not basic or digest) */ public static final int ERROR_UNSUPPORTED_AUTH_SCHEME = -3; /** User authentication failed on server */ public static final int ERROR_AUTHENTICATION = -4; /** User authentication failed on proxy */ public static final int ERROR_PROXY_AUTHENTICATION = -5; /** Failed to connect to the server */ public static final int ERROR_CONNECT = -6; /** Failed to read or write to the server */ public static final int ERROR_IO = -7; /** Connection timed out */ public static final int ERROR_TIMEOUT = -8; /** Too many redirects */ public static final int ERROR_REDIRECT_LOOP = -9; /** Unsupported URI scheme */ public static final int ERROR_UNSUPPORTED_SCHEME = -10; /** Failed to perform SSL handshake */ public static final int ERROR_FAILED_SSL_HANDSHAKE = -11; /** Malformed URL */ public static final int ERROR_BAD_URL = -12; /** Generic file error */ public static final int ERROR_FILE = -13; /** File not found */ public static final int ERROR_FILE_NOT_FOUND = -14; /** Too many requests during this load */ public static final int ERROR_TOO_MANY_REQUESTS = -15; /** Resource load was canceled by Safe Browsing */ public static final int ERROR_UNSAFE_RESOURCE = -16; /** @hide */ @IntDef(prefix = { "SAFE_BROWSING_THREAT_" }, value = { SAFE_BROWSING_THREAT_UNKNOWN, SAFE_BROWSING_THREAT_MALWARE, SAFE_BROWSING_THREAT_PHISHING, SAFE_BROWSING_THREAT_UNWANTED_SOFTWARE }) @Retention(RetentionPolicy.SOURCE) public @interface SafeBrowsingThreat { } /** The resource was blocked for an unknown reason */ public static final int SAFE_BROWSING_THREAT_UNKNOWN = 0; /** The resource was blocked because it contains malware */ public static final int SAFE_BROWSING_THREAT_MALWARE = 1; /** The resource was blocked because it contains deceptive content */ public static final int SAFE_BROWSING_THREAT_PHISHING = 2; /** The resource was blocked because it contains unwanted software */ public static final int SAFE_BROWSING_THREAT_UNWANTED_SOFTWARE = 3; /** * Report an error to the host application. These errors are unrecoverable * (i.e. the main resource is unavailable). The {@code errorCode} parameter * corresponds to one of the {@code ERROR_*} constants. * @param view The WebView that is initiating the callback. * @param errorCode The error code corresponding to an ERROR_* value. * @param description A String describing the error. * @param failingUrl The url that failed to load. * @deprecated Use {@link #onReceivedError(WebView, WebResourceRequest, WebResourceError) * onReceivedError(WebView, WebResourceRequest, WebResourceError)} instead. */ @Deprecated public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) { } /** * Report web resource loading error to the host application. These errors usually indicate * inability to connect to the server. Note that unlike the deprecated version of the callback, * the new version will be called for any resource (iframe, image, etc.), not just for the main * page. Thus, it is recommended to perform minimum required work in this callback. * @param view The WebView that is initiating the callback. * @param request The originating request. * @param error Information about the error occurred. */ public void onReceivedError(WebView view, WebResourceRequest request, WebResourceError error) { if (request.isForMainFrame()) { onReceivedError(view, error.getErrorCode(), error.getDescription().toString(), request.getUrl().toString()); } } /** * Notify the host application that an HTTP error has been received from the server while * loading a resource. HTTP errors have status codes >= 400. This callback will be called * for any resource (iframe, image, etc.), not just for the main page. Thus, it is recommended * to perform minimum required work in this callback. Note that the content of the server * response may not be provided within the {@code errorResponse} parameter. * @param view The WebView that is initiating the callback. * @param request The originating request. * @param errorResponse Information about the error occurred. */ public void onReceivedHttpError(WebView view, WebResourceRequest request, WebResourceResponse errorResponse) { } /** * As the host application if the browser should resend data as the * requested page was a result of a POST. The default is to not resend the * data. * * @param view The WebView that is initiating the callback. * @param dontResend The message to send if the browser should not resend * @param resend The message to send if the browser should resend data */ public void onFormResubmission(WebView view, Message dontResend, Message resend) { dontResend.sendToTarget(); } /** * Notify the host application to update its visited links database. * * @param view The WebView that is initiating the callback. * @param url The url being visited. * @param isReload {@code true} if this url is being reloaded. */ public void doUpdateVisitedHistory(WebView view, String url, boolean isReload) { } /** * 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 * 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. */ public void onReceivedSslError(WebView view, SslErrorHandler handler, SslError error) { handler.cancel(); } /** * Notify the host application to handle a SSL client certificate request. The host application * is responsible for showing the UI if desired and providing the keys. There are three ways to * respond: {@link ClientCertRequest#proceed}, {@link ClientCertRequest#cancel}, or {@link * ClientCertRequest#ignore}. Webview stores the response in memory (for the life of the * application) if {@link ClientCertRequest#proceed} or {@link ClientCertRequest#cancel} is * called and does not call {@code onReceivedClientCertRequest()} again for the same host and * port pair. Webview does not store the response if {@link ClientCertRequest#ignore} * is called. Note that, multiple layers in chromium network stack might be * caching the responses, so the behavior for ignore is only a best case * effort. * * This method is called on the UI thread. During the callback, the * connection is suspended. * * For most use cases, the application program should implement the * {@link android.security.KeyChainAliasCallback} interface and pass it to * {@link android.security.KeyChain#choosePrivateKeyAlias} to start an * activity for the user to choose the proper alias. The keychain activity will * provide the alias through the callback method in the implemented interface. Next * the application should create an async task to call * {@link android.security.KeyChain#getPrivateKey} to receive the key. * * An example implementation of client certificates can be seen at * <A href="https://android.googlesource.com/platform/packages/apps/Browser/+/android-5.1.1_r1/src/com/android/browser/Tab.java"> * AOSP Browser</a> * * The default behavior is to cancel, returning no client certificate. * * @param view The WebView that is initiating the callback * @param request An instance of a {@link ClientCertRequest} * */ public void onReceivedClientCertRequest(WebView view, ClientCertRequest request) { request.cancel(); } /** * Notifies the host application that the WebView received an HTTP * authentication request. The host application can use the supplied * {@link HttpAuthHandler} to set the WebView's response to the request. * The default behavior is to cancel the request. * * @param view the WebView that is initiating the callback * @param handler the HttpAuthHandler used to set the WebView's response * @param host the host requiring authentication * @param realm the realm for which authentication is required * @see WebView#getHttpAuthUsernamePassword */ public void onReceivedHttpAuthRequest(WebView view, HttpAuthHandler handler, String host, String realm) { handler.cancel(); } /** * Give the host application a chance to handle the key event synchronously. * e.g. menu shortcut key events need to be filtered this way. If return * true, WebView will not handle the key event. If return {@code false}, WebView * will always handle the key event, so none of the super in the view chain * will see the key event. The default behavior returns {@code false}. * * @param view The WebView that is initiating the callback. * @param event The key event. * @return {@code true} if the host application wants to handle the key event * itself, otherwise return {@code false} */ public boolean shouldOverrideKeyEvent(WebView view, KeyEvent event) { return false; } /** * Notify the host application that a key was not handled by the WebView. * Except system keys, WebView always consumes the keys in the normal flow * or if {@link #shouldOverrideKeyEvent} returns {@code true}. This is called asynchronously * from where the key is dispatched. It gives the host application a chance * to handle the unhandled key events. * * @param view The WebView that is initiating the callback. * @param event The key event. */ public void onUnhandledKeyEvent(WebView view, KeyEvent event) { onUnhandledInputEventInternal(view, event); } /** * Notify the host application that a input event was not handled by the WebView. * Except system keys, WebView always consumes input events in the normal flow * or if {@link #shouldOverrideKeyEvent} returns {@code true}. This is called asynchronously * from where the event is dispatched. It gives the host application a chance * to handle the unhandled input events. * * Note that if the event is a {@link android.view.MotionEvent}, then it's lifetime is only * that of the function call. If the WebViewClient wishes to use the event beyond that, then it * <i>must</i> create a copy of the event. * * It is the responsibility of overriders of this method to call * {@link #onUnhandledKeyEvent(WebView, KeyEvent)} * when appropriate if they wish to continue receiving events through it. * * @param view The WebView that is initiating the callback. * @param event The input event. * @removed */ public void onUnhandledInputEvent(WebView view, InputEvent event) { if (event instanceof KeyEvent) { onUnhandledKeyEvent(view, (KeyEvent) event); return; } onUnhandledInputEventInternal(view, event); } private void onUnhandledInputEventInternal(WebView view, InputEvent event) { ViewRootImpl root = view.getViewRootImpl(); if (root != null) { root.dispatchUnhandledInputEvent(event); } } /** * Notify the host application that the scale applied to the WebView has * changed. * * @param view The WebView that is initiating the callback. * @param oldScale The old scale factor * @param newScale The new scale factor */ public void onScaleChanged(WebView view, float oldScale, float newScale) { } /** * Notify the host application that a request to automatically log in the * user has been processed. * @param view The WebView requesting the login. * @param realm The account realm used to look up accounts. * @param account An optional account. If not {@code null}, the account should be * checked against accounts on the device. If it is a valid * account, it should be used to log in the user. * @param args Authenticator specific arguments used to log in the user. */ public void onReceivedLoginRequest(WebView view, String realm, @Nullable String account, String args) { } /** * Notify host application that the given WebView's render process has exited. * * Multiple WebView instances may be associated with a single render process; * onRenderProcessGone will be called for each WebView that was affected. * The application's implementation of this callback should only attempt to * clean up the specific WebView given as a parameter, and should not assume * that other WebView instances are affected. * * The given WebView can't be used, and should be removed from the view hierarchy, * all references to it should be cleaned up, e.g any references in the Activity * or other classes saved using {@link android.view.View#findViewById} and similar calls, etc. * * To cause an render process crash for test purpose, the application can * call {@code loadUrl("chrome://crash")} on the WebView. Note that multiple WebView * instances may be affected if they share a render process, not just the * specific WebView which loaded chrome://crash. * * @param view The WebView which needs to be cleaned up. * @param detail the reason why it exited. * @return {@code true} if the host application handled the situation that process has * exited, otherwise, application will crash if render process crashed, * or be killed if render process was killed by the system. */ public boolean onRenderProcessGone(WebView view, RenderProcessGoneDetail detail) { return false; } /** * Notify the host application that a loading URL has been flagged by Safe Browsing. * * The application must invoke the callback to indicate the preferred response. The default * behavior is to show an interstitial to the user, with the reporting checkbox visible. * * If the application needs to show its own custom interstitial UI, the callback can be invoked * asynchronously with {@link SafeBrowsingResponse#backToSafety} or {@link * SafeBrowsingResponse#proceed}, depending on user response. * * @param view The WebView that hit the malicious resource. * @param request Object containing the details of the request. * @param threatType The reason the resource was caught by Safe Browsing, corresponding to a * {@code SAFE_BROWSING_THREAT_*} value. * @param callback Applications must invoke one of the callback methods. */ public void onSafeBrowsingHit(WebView view, WebResourceRequest request, @SafeBrowsingThreat int threatType, SafeBrowsingResponse callback) { callback.showInterstitial(/* allowReporting */ true); } }