WebViewClient.java revision 1feb11f511af25aa5d62d073d970071d16985661
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.webkit; 18 19import android.graphics.Bitmap; 20import android.net.http.SslError; 21import android.os.Message; 22import android.view.InputEvent; 23import android.view.KeyEvent; 24import android.view.ViewRootImpl; 25 26import java.security.Principal; 27 28public class WebViewClient { 29 30 /** 31 * Give the host application a chance to take over the control when a new 32 * url is about to be loaded in the current WebView. If WebViewClient is not 33 * provided, by default WebView will ask Activity Manager to choose the 34 * proper handler for the url. If WebViewClient is provided, return true 35 * means the host application handles the url, while return false means the 36 * current WebView handles the url. 37 * This method is not called for requests using the POST "method". 38 * 39 * @param view The WebView that is initiating the callback. 40 * @param url The url to be loaded. 41 * @return True if the host application wants to leave the current WebView 42 * and handle the url itself, otherwise return false. 43 */ 44 public boolean shouldOverrideUrlLoading(WebView view, String url) { 45 return false; 46 } 47 48 /** 49 * Notify the host application that a page has started loading. This method 50 * is called once for each main frame load so a page with iframes or 51 * framesets will call onPageStarted one time for the main frame. This also 52 * means that onPageStarted will not be called when the contents of an 53 * embedded frame changes, i.e. clicking a link whose target is an iframe. 54 * 55 * @param view The WebView that is initiating the callback. 56 * @param url The url to be loaded. 57 * @param favicon The favicon for this page if it already exists in the 58 * database. 59 */ 60 public void onPageStarted(WebView view, String url, Bitmap favicon) { 61 } 62 63 /** 64 * Notify the host application that a page has finished loading. This method 65 * is called only for main frame. When onPageFinished() is called, the 66 * rendering picture may not be updated yet. To get the notification for the 67 * new Picture, use {@link WebView.PictureListener#onNewPicture}. 68 * 69 * @param view The WebView that is initiating the callback. 70 * @param url The url of the page. 71 */ 72 public void onPageFinished(WebView view, String url) { 73 } 74 75 /** 76 * Notify the host application that the WebView will load the resource 77 * specified by the given url. 78 * 79 * @param view The WebView that is initiating the callback. 80 * @param url The url of the resource the WebView will load. 81 */ 82 public void onLoadResource(WebView view, String url) { 83 } 84 85 /** 86 * Notify the host application of a resource request and allow the 87 * application to return the data. If the return value is null, the WebView 88 * will continue to load the resource as usual. Otherwise, the return 89 * response and data will be used. NOTE: This method is called on a thread 90 * other than the UI thread so clients should exercise caution 91 * when accessing private data or the view system. 92 * 93 * @param view The {@link android.webkit.WebView} that is requesting the 94 * resource. 95 * @param url The raw url of the resource. 96 * @return A {@link android.webkit.WebResourceResponse} containing the 97 * response information or null if the WebView should load the 98 * resource itself. 99 */ 100 public WebResourceResponse shouldInterceptRequest(WebView view, 101 String url) { 102 return null; 103 } 104 105 /** 106 * Notify the host application that there have been an excessive number of 107 * HTTP redirects. As the host application if it would like to continue 108 * trying to load the resource. The default behavior is to send the cancel 109 * message. 110 * 111 * @param view The WebView that is initiating the callback. 112 * @param cancelMsg The message to send if the host wants to cancel 113 * @param continueMsg The message to send if the host wants to continue 114 * @deprecated This method is no longer called. When the WebView encounters 115 * a redirect loop, it will cancel the load. 116 */ 117 @Deprecated 118 public void onTooManyRedirects(WebView view, Message cancelMsg, 119 Message continueMsg) { 120 cancelMsg.sendToTarget(); 121 } 122 123 // These ints must match up to the hidden values in EventHandler. 124 /** Generic error */ 125 public static final int ERROR_UNKNOWN = -1; 126 /** Server or proxy hostname lookup failed */ 127 public static final int ERROR_HOST_LOOKUP = -2; 128 /** Unsupported authentication scheme (not basic or digest) */ 129 public static final int ERROR_UNSUPPORTED_AUTH_SCHEME = -3; 130 /** User authentication failed on server */ 131 public static final int ERROR_AUTHENTICATION = -4; 132 /** User authentication failed on proxy */ 133 public static final int ERROR_PROXY_AUTHENTICATION = -5; 134 /** Failed to connect to the server */ 135 public static final int ERROR_CONNECT = -6; 136 /** Failed to read or write to the server */ 137 public static final int ERROR_IO = -7; 138 /** Connection timed out */ 139 public static final int ERROR_TIMEOUT = -8; 140 /** Too many redirects */ 141 public static final int ERROR_REDIRECT_LOOP = -9; 142 /** Unsupported URI scheme */ 143 public static final int ERROR_UNSUPPORTED_SCHEME = -10; 144 /** Failed to perform SSL handshake */ 145 public static final int ERROR_FAILED_SSL_HANDSHAKE = -11; 146 /** Malformed URL */ 147 public static final int ERROR_BAD_URL = -12; 148 /** Generic file error */ 149 public static final int ERROR_FILE = -13; 150 /** File not found */ 151 public static final int ERROR_FILE_NOT_FOUND = -14; 152 /** Too many requests during this load */ 153 public static final int ERROR_TOO_MANY_REQUESTS = -15; 154 155 /** 156 * Report an error to the host application. These errors are unrecoverable 157 * (i.e. the main resource is unavailable). The errorCode parameter 158 * corresponds to one of the ERROR_* constants. 159 * @param view The WebView that is initiating the callback. 160 * @param errorCode The error code corresponding to an ERROR_* value. 161 * @param description A String describing the error. 162 * @param failingUrl The url that failed to load. 163 */ 164 public void onReceivedError(WebView view, int errorCode, 165 String description, String failingUrl) { 166 } 167 168 /** 169 * As the host application if the browser should resend data as the 170 * requested page was a result of a POST. The default is to not resend the 171 * data. 172 * 173 * @param view The WebView that is initiating the callback. 174 * @param dontResend The message to send if the browser should not resend 175 * @param resend The message to send if the browser should resend data 176 */ 177 public void onFormResubmission(WebView view, Message dontResend, 178 Message resend) { 179 dontResend.sendToTarget(); 180 } 181 182 /** 183 * Notify the host application to update its visited links database. 184 * 185 * @param view The WebView that is initiating the callback. 186 * @param url The url being visited. 187 * @param isReload True if this url is being reloaded. 188 */ 189 public void doUpdateVisitedHistory(WebView view, String url, 190 boolean isReload) { 191 } 192 193 /** 194 * Notify the host application that an SSL error occurred while loading a 195 * resource. The host application must call either handler.cancel() or 196 * handler.proceed(). Note that the decision may be retained for use in 197 * response to future SSL errors. The default behavior is to cancel the 198 * load. 199 * 200 * @param view The WebView that is initiating the callback. 201 * @param handler An SslErrorHandler object that will handle the user's 202 * response. 203 * @param error The SSL error object. 204 */ 205 public void onReceivedSslError(WebView view, SslErrorHandler handler, 206 SslError error) { 207 handler.cancel(); 208 } 209 210 /** 211 * Notify the host application to handle a SSL client certificate 212 * request. The host application is responsible for showing the UI 213 * if desired and providing the keys. There are three ways to 214 * respond: proceed(), cancel() or ignore(). Webview remembers the 215 * response if proceed() or cancel() is called and does not 216 * call onReceivedClientCertRequest() again for the same host and port 217 * pair. Webview does not remember the response if ignore() is called. 218 * 219 * This method is called on the UI thread. During the callback, the 220 * connection is suspended. 221 * 222 * The default behavior is to cancel, returning no client certificate. 223 * 224 * @param view The WebView that is initiating the callback 225 * @param request An instance of a {@link ClientCertRequest} 226 * 227 * TODO(sgurun) unhide 228 * @hide 229 */ 230 public void onReceivedClientCertRequest(WebView view, ClientCertRequest request) { 231 request.cancel(); 232 } 233 234 /** 235 * Notifies the host application that the WebView received an HTTP 236 * authentication request. The host application can use the supplied 237 * {@link HttpAuthHandler} to set the WebView's response to the request. 238 * The default behavior is to cancel the request. 239 * 240 * @param view the WebView that is initiating the callback 241 * @param handler the HttpAuthHandler used to set the WebView's response 242 * @param host the host requiring authentication 243 * @param realm the realm for which authentication is required 244 * @see WebView#getHttpAuthUsernamePassword 245 */ 246 public void onReceivedHttpAuthRequest(WebView view, 247 HttpAuthHandler handler, String host, String realm) { 248 handler.cancel(); 249 } 250 251 /** 252 * Give the host application a chance to handle the key event synchronously. 253 * e.g. menu shortcut key events need to be filtered this way. If return 254 * true, WebView will not handle the key event. If return false, WebView 255 * will always handle the key event, so none of the super in the view chain 256 * will see the key event. The default behavior returns false. 257 * 258 * @param view The WebView that is initiating the callback. 259 * @param event The key event. 260 * @return True if the host application wants to handle the key event 261 * itself, otherwise return false 262 */ 263 public boolean shouldOverrideKeyEvent(WebView view, KeyEvent event) { 264 return false; 265 } 266 267 /** 268 * Notify the host application that a key was not handled by the WebView. 269 * Except system keys, WebView always consumes the keys in the normal flow 270 * or if shouldOverrideKeyEvent returns true. This is called asynchronously 271 * from where the key is dispatched. It gives the host application a chance 272 * to handle the unhandled key events. 273 * 274 * @param view The WebView that is initiating the callback. 275 * @param event The key event. 276 * @deprecated This method is subsumed by the more generic onUnhandledInputEvent. 277 */ 278 @Deprecated 279 public void onUnhandledKeyEvent(WebView view, KeyEvent event) { 280 onUnhandledInputEventInternal(view, event); 281 } 282 283 /** 284 * Notify the host application that a input event was not handled by the WebView. 285 * Except system keys, WebView always consumes input events in the normal flow 286 * or if shouldOverrideKeyEvent returns true. This is called asynchronously 287 * from where the event is dispatched. It gives the host application a chance 288 * to handle the unhandled input events. 289 * 290 * Note that if the event is a {@link android.view.MotionEvent}, then it's lifetime is only 291 * that of the function call. If the WebViewClient wishes to use the event beyond that, then it 292 * <i>must</i> create a copy of the event. 293 * 294 * It is the responsibility of overriders of this method to call 295 * {@link #onUnhandledKeyEvent(WebView, KeyEvent)} 296 * when appropriate if they wish to continue receiving events through it. 297 * 298 * @param view The WebView that is initiating the callback. 299 * @param event The input event. 300 */ 301 public void onUnhandledInputEvent(WebView view, InputEvent event) { 302 if (event instanceof KeyEvent) { 303 onUnhandledKeyEvent(view, (KeyEvent) event); 304 return; 305 } 306 onUnhandledInputEventInternal(view, event); 307 } 308 309 private void onUnhandledInputEventInternal(WebView view, InputEvent event) { 310 ViewRootImpl root = view.getViewRootImpl(); 311 if (root != null) { 312 root.dispatchUnhandledInputEvent(event); 313 } 314 } 315 316 /** 317 * Notify the host application that the scale applied to the WebView has 318 * changed. 319 * 320 * @param view he WebView that is initiating the callback. 321 * @param oldScale The old scale factor 322 * @param newScale The new scale factor 323 */ 324 public void onScaleChanged(WebView view, float oldScale, float newScale) { 325 } 326 327 /** 328 * Notify the host application that a request to automatically log in the 329 * user has been processed. 330 * @param view The WebView requesting the login. 331 * @param realm The account realm used to look up accounts. 332 * @param account An optional account. If not null, the account should be 333 * checked against accounts on the device. If it is a valid 334 * account, it should be used to log in the user. 335 * @param args Authenticator specific arguments used to log in the user. 336 */ 337 public void onReceivedLoginRequest(WebView view, String realm, 338 String account, String args) { 339 } 340} 341