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