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