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.SystemApi;
20 import android.net.WebAddress;
21 
22 /**
23  * Manages the cookies used by an application's {@link WebView} instances.
24  * Cookies are manipulated according to RFC2109.
25  */
26 public abstract class CookieManager {
27 
28     @Override
clone()29     protected Object clone() throws CloneNotSupportedException {
30         throw new CloneNotSupportedException("doesn't implement Cloneable");
31     }
32 
33     /**
34      * Gets the singleton CookieManager instance. If this method is used
35      * before the application instantiates a {@link WebView} instance,
36      * {@link CookieSyncManager#createInstance CookieSyncManager.createInstance(Context)}
37      * must be called first.
38      *
39      * @return the singleton CookieManager instance
40      */
getInstance()41     public static synchronized CookieManager getInstance() {
42         return WebViewFactory.getProvider().getCookieManager();
43     }
44 
45     /**
46      * Sets whether the application's {@link WebView} instances should send and
47      * accept cookies.
48      * By default this is set to true and the WebView accepts cookies.
49      * <p>
50      * When this is true
51      * {@link CookieManager#setAcceptThirdPartyCookies setAcceptThirdPartyCookies} and
52      * {@link CookieManager#setAcceptFileSchemeCookies setAcceptFileSchemeCookies}
53      * can be used to control the policy for those specific types of cookie.
54      *
55      * @param accept whether {@link WebView} instances should send and accept
56      *               cookies
57      */
setAcceptCookie(boolean accept)58     public abstract void setAcceptCookie(boolean accept);
59 
60     /**
61      * Gets whether the application's {@link WebView} instances send and accept
62      * cookies.
63      *
64      * @return true if {@link WebView} instances send and accept cookies
65      */
acceptCookie()66     public abstract boolean acceptCookie();
67 
68    /**
69      * Sets whether the {@link WebView} should allow third party cookies to be set.
70      * Allowing third party cookies is a per WebView policy and can be set
71      * differently on different WebView instances.
72      * <p>
73      * Apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below
74      * default to allowing third party cookies. Apps targeting
75      * {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later default to disallowing
76      * third party cookies.
77      *
78      * @param webview the {@link WebView} instance to set the cookie policy on
79      * @param accept whether the {@link WebView} instance should accept
80      *               third party cookies
81      */
setAcceptThirdPartyCookies(WebView webview, boolean accept)82     public abstract void setAcceptThirdPartyCookies(WebView webview, boolean accept);
83 
84     /**
85      * Gets whether the {@link WebView} should allow third party cookies to be set.
86      *
87      * @param webview the {@link WebView} instance to get the cookie policy for
88      * @return true if the {@link WebView} accepts third party cookies
89      */
acceptThirdPartyCookies(WebView webview)90     public abstract boolean acceptThirdPartyCookies(WebView webview);
91 
92     /**
93      * Sets a cookie for the given URL. Any existing cookie with the same host,
94      * path and name will be replaced with the new cookie. The cookie being set
95      * will be ignored if it is expired.
96      *
97      * @param url the URL for which the cookie is to be set
98      * @param value the cookie as a string, using the format of the 'Set-Cookie'
99      *              HTTP response header
100      */
setCookie(String url, String value)101     public abstract void setCookie(String url, String value);
102 
103     /**
104      * Sets a cookie for the given URL. Any existing cookie with the same host,
105      * path and name will be replaced with the new cookie. The cookie being set
106      * will be ignored if it is expired.
107      * <p>
108      * This method is asynchronous.
109      * If a {@link ValueCallback} is provided,
110      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
111      * thread's {@link android.os.Looper} once the operation is complete.
112      * The value provided to the callback indicates whether the cookie was set successfully.
113      * You can pass {@code null} as the callback if you don't need to know when the operation
114      * completes or whether it succeeded, and in this case it is safe to call the method from a
115      * thread without a Looper.
116      *
117      * @param url the URL for which the cookie is to be set
118      * @param value the cookie as a string, using the format of the 'Set-Cookie'
119      *              HTTP response header
120      * @param callback a callback to be executed when the cookie has been set
121      */
setCookie(String url, String value, ValueCallback<Boolean> callback)122     public abstract void setCookie(String url, String value, ValueCallback<Boolean> callback);
123 
124     /**
125      * Gets the cookies for the given URL.
126      *
127      * @param url the URL for which the cookies are requested
128      * @return value the cookies as a string, using the format of the 'Cookie'
129      *               HTTP request header
130      */
getCookie(String url)131     public abstract String getCookie(String url);
132 
133     /**
134      * See {@link #getCookie(String)}.
135      *
136      * @param url the URL for which the cookies are requested
137      * @param privateBrowsing whether to use the private browsing cookie jar
138      * @return value the cookies as a string, using the format of the 'Cookie'
139      *               HTTP request header
140      * @hide Used by Browser and by WebViewProvider implementations.
141      */
142     @SystemApi
getCookie(String url, boolean privateBrowsing)143     public abstract String getCookie(String url, boolean privateBrowsing);
144 
145     /**
146      * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http
147      * request header.
148      *
149      * @param uri the WebAddress for which the cookies are requested
150      * @return value the cookies as a string, using the format of the 'Cookie'
151      *               HTTP request header
152      * @hide Used by RequestHandle and by WebViewProvider implementations.
153      */
154     @SystemApi
getCookie(WebAddress uri)155     public synchronized String getCookie(WebAddress uri) {
156         return getCookie(uri.toString());
157     }
158 
159     /**
160      * Removes all session cookies, which are cookies without an expiration
161      * date.
162      * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead.
163      */
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(ValueCallback<Boolean> callback)180     public abstract void removeSessionCookies(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(ValueCallback<Boolean> callback)202     public abstract void removeAllCookies(ValueCallback<Boolean> callback);
203 
204     /**
205      * Gets whether there are stored cookies.
206      *
207      * @return 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 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