1 /*
2  * Copyright (C) 2006 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.annotation.SystemApi;
21 import android.net.WebAddress;
22 
23 /**
24  * Manages the cookies used by an application's {@link WebView} instances.
25  * Cookies are manipulated according to RFC2109.
26  */
27 public abstract class CookieManager {
28 
29     @Override
clone()30     protected Object clone() throws CloneNotSupportedException {
31         throw new CloneNotSupportedException("doesn't implement Cloneable");
32     }
33 
34     /**
35      * Gets the singleton CookieManager instance.
36      *
37      * @return the singleton CookieManager instance
38      */
getInstance()39     public static CookieManager getInstance() {
40         return WebViewFactory.getProvider().getCookieManager();
41     }
42 
43     /**
44      * Sets whether the application's {@link WebView} instances should send and
45      * accept cookies.
46      * By default this is set to {@code true} and the WebView accepts cookies.
47      * <p>
48      * When this is {@code true}
49      * {@link CookieManager#setAcceptThirdPartyCookies setAcceptThirdPartyCookies} and
50      * {@link CookieManager#setAcceptFileSchemeCookies setAcceptFileSchemeCookies}
51      * can be used to control the policy for those specific types of cookie.
52      *
53      * @param accept whether {@link WebView} instances should send and accept
54      *               cookies
55      */
setAcceptCookie(boolean accept)56     public abstract void setAcceptCookie(boolean accept);
57 
58     /**
59      * Gets whether the application's {@link WebView} instances send and accept
60      * cookies.
61      *
62      * @return {@code true} if {@link WebView} instances send and accept cookies
63      */
acceptCookie()64     public abstract boolean acceptCookie();
65 
66    /**
67      * Sets whether the {@link WebView} should allow third party cookies to be set.
68      * Allowing third party cookies is a per WebView policy and can be set
69      * differently on different WebView instances.
70      * <p>
71      * Apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below
72      * default to allowing third party cookies. Apps targeting
73      * {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later default to disallowing
74      * third party cookies.
75      *
76      * @param webview the {@link WebView} instance to set the cookie policy on
77      * @param accept whether the {@link WebView} instance should accept
78      *               third party cookies
79      */
setAcceptThirdPartyCookies(WebView webview, boolean accept)80     public abstract void setAcceptThirdPartyCookies(WebView webview, boolean accept);
81 
82     /**
83      * Gets whether the {@link WebView} should allow third party cookies to be set.
84      *
85      * @param webview the {@link WebView} instance to get the cookie policy for
86      * @return {@code true} if the {@link WebView} accepts third party cookies
87      */
acceptThirdPartyCookies(WebView webview)88     public abstract boolean acceptThirdPartyCookies(WebView webview);
89 
90     /**
91      * Sets a cookie for the given URL. Any existing cookie with the same host,
92      * path and name will be replaced with the new cookie. The cookie being set
93      * will be ignored if it is expired.
94      *
95      * @param url the URL for which the cookie is to be set
96      * @param value the cookie as a string, using the format of the 'Set-Cookie'
97      *              HTTP response header
98      */
setCookie(String url, String value)99     public abstract void setCookie(String url, String value);
100 
101     /**
102      * Sets a cookie for the given URL. Any existing cookie with the same host,
103      * path and name will be replaced with the new cookie. The cookie being set
104      * will be ignored if it is expired.
105      * <p>
106      * This method is asynchronous.
107      * If a {@link ValueCallback} is provided,
108      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
109      * thread's {@link android.os.Looper} once the operation is complete.
110      * The value provided to the callback indicates whether the cookie was set successfully.
111      * You can pass {@code null} as the callback if you don't need to know when the operation
112      * completes or whether it succeeded, and in this case it is safe to call the method from a
113      * thread without a Looper.
114      *
115      * @param url the URL for which the cookie is to be set
116      * @param value the cookie as a string, using the format of the 'Set-Cookie'
117      *              HTTP response header
118      * @param callback a callback to be executed when the cookie has been set
119      */
setCookie(String url, String value, @Nullable ValueCallback<Boolean> callback)120     public abstract void setCookie(String url, String value, @Nullable ValueCallback<Boolean>
121             callback);
122 
123     /**
124      * Gets the cookies for the given URL.
125      *
126      * @param url the URL for which the cookies are requested
127      * @return value the cookies as a string, using the format of the 'Cookie'
128      *               HTTP request header
129      */
getCookie(String url)130     public abstract String getCookie(String url);
131 
132     /**
133      * See {@link #getCookie(String)}.
134      *
135      * @param url the URL for which the cookies are requested
136      * @param privateBrowsing whether to use the private browsing cookie jar
137      * @return value the cookies as a string, using the format of the 'Cookie'
138      *               HTTP request header
139      * @hide Used by Browser and by WebViewProvider implementations.
140      */
141     @SystemApi
getCookie(String url, boolean privateBrowsing)142     public abstract String getCookie(String url, boolean privateBrowsing);
143 
144     /**
145      * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http
146      * request header.
147      *
148      * @param uri the WebAddress for which the cookies are requested
149      * @return value the cookies as a string, using the format of the 'Cookie'
150      *               HTTP request header
151      * @hide Used by RequestHandle and by WebViewProvider implementations.
152      */
153     @SystemApi
getCookie(WebAddress uri)154     public synchronized String getCookie(WebAddress uri) {
155         return getCookie(uri.toString());
156     }
157 
158     /**
159      * Removes all session cookies, which are cookies without an expiration
160      * date.
161      * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead.
162      */
163     @Deprecated
removeSessionCookie()164     public abstract void removeSessionCookie();
165 
166     /**
167      * Removes all session cookies, which are cookies without an expiration
168      * date.
169      * <p>
170      * This method is asynchronous.
171      * If a {@link ValueCallback} is provided,
172      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
173      * thread's {@link android.os.Looper} once the operation is complete.
174      * The value provided to the callback indicates whether any cookies were removed.
175      * You can pass {@code null} as the callback if you don't need to know when the operation
176      * completes or whether any cookie were removed, and in this case it is safe to call the
177      * method from a thread without a Looper.
178      * @param callback a callback which is executed when the session cookies have been removed
179      */
removeSessionCookies(@ullable ValueCallback<Boolean> callback)180     public abstract void removeSessionCookies(@Nullable ValueCallback<Boolean> callback);
181 
182     /**
183      * Removes all cookies.
184      * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead.
185      */
186     @Deprecated
removeAllCookie()187     public abstract void removeAllCookie();
188 
189     /**
190      * Removes all cookies.
191      * <p>
192      * This method is asynchronous.
193      * If a {@link ValueCallback} is provided,
194      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
195      * thread's {@link android.os.Looper} once the operation is complete.
196      * The value provided to the callback indicates whether any cookies were removed.
197      * You can pass {@code null} as the callback if you don't need to know when the operation
198      * completes or whether any cookies were removed, and in this case it is safe to call the
199      * method from a thread without a Looper.
200      * @param callback a callback which is executed when the cookies have been removed
201      */
removeAllCookies(@ullable ValueCallback<Boolean> callback)202     public abstract void removeAllCookies(@Nullable ValueCallback<Boolean> callback);
203 
204     /**
205      * Gets whether there are stored cookies.
206      *
207      * @return {@code true} if there are stored cookies
208      */
hasCookies()209     public abstract boolean hasCookies();
210 
211     /**
212      * See {@link #hasCookies()}.
213      *
214      * @param privateBrowsing whether to use the private browsing cookie jar
215      * @hide Used by Browser and WebViewProvider implementations.
216      */
217     @SystemApi
hasCookies(boolean privateBrowsing)218     public abstract boolean hasCookies(boolean privateBrowsing);
219 
220     /**
221      * Removes all expired cookies.
222      * @deprecated The WebView handles removing expired cookies automatically.
223      */
224     @Deprecated
removeExpiredCookie()225     public abstract void removeExpiredCookie();
226 
227     /**
228      * Ensures all cookies currently accessible through the getCookie API are
229      * written to persistent storage.
230      * This call will block the caller until it is done and may perform I/O.
231      */
flush()232     public abstract void flush();
233 
234     /**
235      * Gets whether the application's {@link WebView} instances send and accept
236      * cookies for file scheme URLs.
237      *
238      * @return {@code true} if {@link WebView} instances send and accept cookies for
239      *         file scheme URLs
240      */
241     // Static for backward compatibility.
allowFileSchemeCookies()242     public static boolean allowFileSchemeCookies() {
243         return getInstance().allowFileSchemeCookiesImpl();
244     }
245 
246     /**
247      * Implements {@link #allowFileSchemeCookies()}.
248      *
249      * @hide Only for use by WebViewProvider implementations
250      */
251     @SystemApi
allowFileSchemeCookiesImpl()252     protected abstract boolean allowFileSchemeCookiesImpl();
253 
254     /**
255      * Sets whether the application's {@link WebView} instances should send and
256      * accept cookies for file scheme URLs.
257      * Use of cookies with file scheme URLs is potentially insecure and turned
258      * off by default.
259      * Do not use this feature unless you can be sure that no unintentional
260      * sharing of cookie data can take place.
261      * <p>
262      * Note that calls to this method will have no effect if made after a
263      * {@link WebView} or CookieManager instance has been created.
264      */
265     // Static for backward compatibility.
setAcceptFileSchemeCookies(boolean accept)266     public static void setAcceptFileSchemeCookies(boolean accept) {
267         getInstance().setAcceptFileSchemeCookiesImpl(accept);
268     }
269 
270     /**
271      * Implements {@link #setAcceptFileSchemeCookies(boolean)}.
272      *
273      * @hide Only for use by WebViewProvider implementations
274      */
275     @SystemApi
setAcceptFileSchemeCookiesImpl(boolean accept)276     protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept);
277 }
278