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 that an SSL error occurred while loading a
190     * resource. The host application must call either handler.cancel() or
191     * handler.proceed(). Note that the decision may be retained for use in
192     * response to future SSL errors. The default behavior is to cancel the
193     * 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 that an SSL error occurred while loading a
207     * resource, but the WebView but chose to proceed anyway based on a
208     * decision retained from a previous response to onReceivedSslError().
209     * @hide
210     */
211    public void onProceededAfterSslError(WebView view, SslError error) {
212    }
213
214    /**
215     * Notify the host application to handle a SSL client certificate
216     * request (display the request to the user and ask whether to
217     * proceed with a client certificate or not). The host application
218     * has to call either handler.cancel() or handler.proceed() as the
219     * connection is suspended and waiting for the response. The
220     * default behavior is to cancel, returning no client certificate.
221     *
222     * @param view The WebView that is initiating the callback.
223     * @param handler An ClientCertRequestHandler object that will
224     *            handle the user's response.
225     * @param host_and_port The host and port of the requesting server.
226     *
227     * @hide
228     */
229    public void onReceivedClientCertRequest(WebView view,
230            ClientCertRequestHandler handler, String host_and_port) {
231        handler.cancel();
232    }
233
234    /**
235     * Notify the host application to handle an authentication request. The
236     * default behavior is to cancel the request.
237     *
238     * @param view The WebView that is initiating the callback.
239     * @param handler The HttpAuthHandler that will handle the user's response.
240     * @param host The host requiring authentication.
241     * @param realm A description to help store user credentials for future
242     *            visits.
243     */
244    public void onReceivedHttpAuthRequest(WebView view,
245            HttpAuthHandler handler, String host, String realm) {
246        handler.cancel();
247    }
248
249    /**
250     * Give the host application a chance to handle the key event synchronously.
251     * e.g. menu shortcut key events need to be filtered this way. If return
252     * true, WebView will not handle the key event. If return false, WebView
253     * will always handle the key event, so none of the super in the view chain
254     * will see the key event. The default behavior returns false.
255     *
256     * @param view The WebView that is initiating the callback.
257     * @param event The key event.
258     * @return True if the host application wants to handle the key event
259     *         itself, otherwise return false
260     */
261    public boolean shouldOverrideKeyEvent(WebView view, KeyEvent event) {
262        return false;
263    }
264
265    /**
266     * Notify the host application that a key was not handled by the WebView.
267     * Except system keys, WebView always consumes the keys in the normal flow
268     * or if shouldOverrideKeyEvent returns true. This is called asynchronously
269     * from where the key is dispatched. It gives the host application an chance
270     * to handle the unhandled key events.
271     *
272     * @param view The WebView that is initiating the callback.
273     * @param event The key event.
274     */
275    public void onUnhandledKeyEvent(WebView view, KeyEvent event) {
276    }
277
278    /**
279     * Notify the host application that the scale applied to the WebView has
280     * changed.
281     *
282     * @param view he WebView that is initiating the callback.
283     * @param oldScale The old scale factor
284     * @param newScale The new scale factor
285     */
286    public void onScaleChanged(WebView view, float oldScale, float newScale) {
287    }
288
289    /**
290     * Notify the host application that a request to automatically log in the
291     * user has been processed.
292     * @param view The WebView requesting the login.
293     * @param realm The account realm used to look up accounts.
294     * @param account An optional account. If not null, the account should be
295     *                checked against accounts on the device. If it is a valid
296     *                account, it should be used to log in the user.
297     * @param args Authenticator specific arguments used to log in the user.
298     */
299    public void onReceivedLoginRequest(WebView view, String realm,
300            String account, String args) {
301    }
302}
303