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