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