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