1 /*
2  * Copyright (C) 2007 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.annotation.Nullable;
20 import android.content.Context;
21 
22 /**
23  * This class allows developers to determine whether any WebView used in the
24  * application has stored any of the following types of browsing data and
25  * to clear any such stored data for all WebViews in the application.
26  * <ul>
27  *  <li>Username/password pairs for web forms</li>
28  *  <li>HTTP authentication username/password pairs</li>
29  *  <li>Data entered into text fields (e.g. for autocomplete suggestions)</li>
30  * </ul>
31  */
32 public abstract class WebViewDatabase {
33     /**
34      * @deprecated This class should not be constructed by applications, use {@link
35      * #getInstance(Context)} instead to fetch the singleton instance.
36      */
37     // TODO(ntfschr): mark this as @SystemApi after a year.
38     @Deprecated
WebViewDatabase()39     public WebViewDatabase() {}
40 
41     /**
42      * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}
43      */
44     protected static final String LOGTAG = "webviewdatabase";
45 
getInstance(Context context)46     public static WebViewDatabase getInstance(Context context) {
47         return WebViewFactory.getProvider().getWebViewDatabase(context);
48     }
49 
50     /**
51      * Gets whether there are any saved username/password pairs for web forms.
52      * Note that these are unrelated to HTTP authentication credentials.
53      *
54      * @return {@code true} if there are any saved username/password pairs
55      * @see WebView#savePassword
56      * @see #clearUsernamePassword
57      * @deprecated Saving passwords in WebView will not be supported in future versions.
58      */
59     @Deprecated
hasUsernamePassword()60     public abstract boolean hasUsernamePassword();
61 
62     /**
63      * Clears any saved username/password pairs for web forms.
64      * Note that these are unrelated to HTTP authentication credentials.
65      *
66      * @see WebView#savePassword
67      * @see #hasUsernamePassword
68      * @deprecated Saving passwords in WebView will not be supported in future versions.
69      */
70     @Deprecated
clearUsernamePassword()71     public abstract void clearUsernamePassword();
72 
73     /**
74      * Gets whether there are any saved credentials for HTTP authentication.
75      *
76      * @return whether there are any saved credentials
77      * @see #getHttpAuthUsernamePassword
78      * @see #setHttpAuthUsernamePassword
79      * @see #clearHttpAuthUsernamePassword
80      */
hasHttpAuthUsernamePassword()81     public abstract boolean hasHttpAuthUsernamePassword();
82 
83     /**
84      * Clears any saved credentials for HTTP authentication. This method only clears the username
85      * and password stored in WebViewDatabase instance. The username and password are not read from
86      * the {@link WebViewDatabase} during {@link WebViewClient#onReceivedHttpAuthRequest}. It is up
87      * to the app to do this or not.
88      * <p>
89      * The username and password used for http authentication might be cached in the network stack
90      * itself, and are not cleared when this method is called.  WebView does not provide a special
91      * mechanism to clear HTTP authentication for implementing client logout. The client logout
92      * mechanism should be implemented by the Web site designer (such as server sending a HTTP 401
93      * for invalidating credentials).
94      *
95      * @see #getHttpAuthUsernamePassword
96      * @see #setHttpAuthUsernamePassword
97      * @see #hasHttpAuthUsernamePassword
98      */
clearHttpAuthUsernamePassword()99     public abstract void clearHttpAuthUsernamePassword();
100 
101     /**
102      * Stores HTTP authentication credentials for a given host and realm to the {@link WebViewDatabase}
103      * instance.
104      * <p>
105      * To use HTTP authentication, the embedder application has to implement
106      * {@link WebViewClient#onReceivedHttpAuthRequest}, and call {@link HttpAuthHandler#proceed}
107      * with the correct username and password.
108      * <p>
109      * The embedder app can get the username and password any way it chooses, and does not have to
110      * use {@link WebViewDatabase}.
111      * <p>
112      * Notes:
113      * <li>
114      * {@link WebViewDatabase} is provided only as a convenience to store and retrieve http
115      * authentication credentials. WebView does not read from it during HTTP authentication.
116      * </li>
117      * <li>
118      * WebView does not provide a special mechanism to clear HTTP authentication credentials for
119      * implementing client logout. The client logout mechanism should be implemented by the Web site
120      * designer (such as server sending a HTTP 401 for invalidating credentials).
121      * </li>
122      *
123      * @param host the host to which the credentials apply
124      * @param realm the realm to which the credentials apply
125      * @param username the username
126      * @param password the password
127      * @see #getHttpAuthUsernamePassword
128      * @see #hasHttpAuthUsernamePassword
129      * @see #clearHttpAuthUsernamePassword
130      */
setHttpAuthUsernamePassword(String host, String realm, String username, String password)131     public abstract void setHttpAuthUsernamePassword(String host, String realm,
132             String username, String password);
133 
134    /**
135      * Retrieves HTTP authentication credentials for a given host and realm from the {@link
136      * WebViewDatabase} instance.
137      *
138      * @param host the host to which the credentials apply
139      * @param realm the realm to which the credentials apply
140      * @return the credentials as a String array, if found. The first element
141      *         is the username and the second element is the password. {@code null} if
142      *         no credentials are found.
143      * @see #setHttpAuthUsernamePassword
144      * @see #hasHttpAuthUsernamePassword
145      * @see #clearHttpAuthUsernamePassword
146      */
147     @Nullable
getHttpAuthUsernamePassword(String host, String realm)148     public abstract String[] getHttpAuthUsernamePassword(String host, String realm);
149 
150     /**
151      * Gets whether there is any saved data for web forms.
152      *
153      * @return whether there is any saved data for web forms
154      * @see #clearFormData
155      */
156     @Deprecated
hasFormData()157     public abstract boolean hasFormData();
158 
159     /**
160      * Clears any saved data for web forms.
161      *
162      * @see #hasFormData
163      */
164     @Deprecated
clearFormData()165     public abstract void clearFormData();
166 }
167