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