WebViewClient.java revision ddcea3d21645bb3037703c84807dae077aae62ce 
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 that there have been an excessive number of
82     * HTTP redirects. As the host application if it would like to continue
83     * trying to load the resource. The default behavior is to send the cancel
84     * message.
85     *
86     * @param view The WebView that is initiating the callback.
87     * @param cancelMsg The message to send if the host wants to cancel
88     * @param continueMsg The message to send if the host wants to continue
89     */
90    public void onTooManyRedirects(WebView view, Message cancelMsg,
91            Message continueMsg) {
92        cancelMsg.sendToTarget();
93    }
94
95    // These ints must match up to the hidden values in EventHandler.
96    /** Generic error */
97    public static final int ERROR_UNKNOWN = -1;
98    /** Server or proxy hostname lookup failed */
99    public static final int ERROR_HOST_LOOKUP = -2;
100    /** Unsupported authentication scheme (not basic or digest) */
101    public static final int ERROR_UNSUPPORTED_AUTH_SCHEME = -3;
102    /** User authentication failed on server */
103    public static final int ERROR_AUTHENTICATION = -4;
104    /** User authentication failed on proxy */
105    public static final int ERROR_PROXY_AUTHENTICATION = -5;
106    /** Failed to connect to the server */
107    public static final int ERROR_CONNECT = -6;
108    /** Failed to read or write to the server */
109    public static final int ERROR_IO = -7;
110    /** Connection timed out */
111    public static final int ERROR_TIMEOUT = -8;
112    /** Too many redirects */
113    public static final int ERROR_REDIRECT_LOOP = -9;
114    /** Unsupported URI scheme */
115    public static final int ERROR_UNSUPPORTED_SCHEME = -10;
116    /** Failed to perform SSL handshake */
117    public static final int ERROR_FAILED_SSL_HANDSHAKE = -11;
118    /** Malformed URL */
119    public static final int ERROR_BAD_URL = -12;
120    /** Generic file error */
121    public static final int ERROR_FILE = -13;
122    /** File not found */
123    public static final int ERROR_FILE_NOT_FOUND = -14;
124    /** Too many requests during this load */
125    public static final int ERROR_TOO_MANY_REQUESTS = -15;
126
127    /**
128     * Report an error to the host application. These errors are unrecoverable
129     * (i.e. the main resource is unavailable). The errorCode parameter
130     * corresponds to one of the ERROR_* constants.
131     * @param view The WebView that is initiating the callback.
132     * @param errorCode The error code corresponding to an ERROR_* value.
133     * @param description A String describing the error.
134     * @param failingUrl The url that failed to load.
135     */
136    public void onReceivedError(WebView view, int errorCode,
137            String description, String failingUrl) {
138    }
139
140    /**
141     * As the host application if the browser should resend data as the
142     * requested page was a result of a POST. The default is to not resend the
143     * data.
144     *
145     * @param view The WebView that is initiating the callback.
146     * @param dontResend The message to send if the browser should not resend
147     * @param resend The message to send if the browser should resend data
148     */
149    public void onFormResubmission(WebView view, Message dontResend,
150            Message resend) {
151        dontResend.sendToTarget();
152    }
153
154    /**
155     * Notify the host application to update its visited links database.
156     *
157     * @param view The WebView that is initiating the callback.
158     * @param url The url being visited.
159     * @param isReload True if this url is being reloaded.
160     */
161    public void doUpdateVisitedHistory(WebView view, String url,
162            boolean isReload) {
163    }
164
165    /**
166     * Notify the host application to handle a ssl certificate error request
167     * (display the error to the user and ask whether to proceed or not). The
168     * host application has to call either handler.cancel() or handler.proceed()
169     * as the connection is suspended and waiting for the response. The default
170     * behavior is to cancel the load.
171     *
172     * @param view The WebView that is initiating the callback.
173     * @param handler An SslErrorHandler object that will handle the user's
174     *            response.
175     * @param error The SSL error object.
176     */
177    public void onReceivedSslError(WebView view, SslErrorHandler handler,
178            SslError error) {
179        handler.cancel();
180    }
181
182    /**
183     * Notify the host application to handle an authentication request. The
184     * default behavior is to cancel the request.
185     *
186     * @param view The WebView that is initiating the callback.
187     * @param handler The HttpAuthHandler that will handle the user's response.
188     * @param host The host requiring authentication.
189     * @param realm A description to help store user credentials for future
190     *            visits.
191     */
192    public void onReceivedHttpAuthRequest(WebView view,
193            HttpAuthHandler handler, String host, String realm) {
194        handler.cancel();
195    }
196
197    /**
198     * Give the host application a chance to handle the key event synchronously.
199     * e.g. menu shortcut key events need to be filtered this way. If return
200     * true, WebView will not handle the key event. If return false, WebView
201     * will always handle the key event, so none of the super in the view chain
202     * will see the key event. The default behavior returns false.
203     *
204     * @param view The WebView that is initiating the callback.
205     * @param event The key event.
206     * @return True if the host application wants to handle the key event
207     *         itself, otherwise return false
208     */
209    public boolean shouldOverrideKeyEvent(WebView view, KeyEvent event) {
210        return false;
211    }
212
213    /**
214     * Notify the host application that a key was not handled by the WebView.
215     * Except system keys, WebView always consumes the keys in the normal flow
216     * or if shouldOverrideKeyEvent returns true. This is called asynchronously
217     * from where the key is dispatched. It gives the host application an chance
218     * to handle the unhandled key events.
219     *
220     * @param view The WebView that is initiating the callback.
221     * @param event The key event.
222     */
223    public void onUnhandledKeyEvent(WebView view, KeyEvent event) {
224    }
225
226    /**
227     * Notify the host application that the scale applied to the WebView has
228     * changed.
229     *
230     * @param view he WebView that is initiating the callback.
231     * @param oldScale The old scale factor
232     * @param newScale The new scale factor
233     */
234    public void onScaleChanged(WebView view, float oldScale, float newScale) {
235    }
236}
237