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