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 synchronized 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      */
removeSessionCookie()161     public abstract void removeSessionCookie();
162 
163     /**
164      * Removes all session cookies, which are cookies without an expiration
165      * date.
166      * <p>
167      * This method is asynchronous.
168      * If a {@link ValueCallback} is provided,
169      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
170      * thread's {@link android.os.Looper} once the operation is complete.
171      * The value provided to the callback indicates whether any cookies were removed.
172      * You can pass {@code null} as the callback if you don't need to know when the operation
173      * completes or whether any cookie were removed, and in this case it is safe to call the
174      * method from a thread without a Looper.
175      * @param callback a callback which is executed when the session cookies have been removed
176      */
removeSessionCookies(ValueCallback<Boolean> callback)177     public abstract void removeSessionCookies(ValueCallback<Boolean> callback);
178 
179     /**
180      * Removes all cookies.
181      * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead.
182      */
183     @Deprecated
removeAllCookie()184     public abstract void removeAllCookie();
185 
186     /**
187      * Removes all cookies.
188      * <p>
189      * This method is asynchronous.
190      * If a {@link ValueCallback} is provided,
191      * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
192      * thread's {@link android.os.Looper} once the operation is complete.
193      * The value provided to the callback indicates whether any cookies were removed.
194      * You can pass {@code null} as the callback if you don't need to know when the operation
195      * completes or whether any cookies were removed, and in this case it is safe to call the
196      * method from a thread without a Looper.
197      * @param callback a callback which is executed when the cookies have been removed
198      */
removeAllCookies(ValueCallback<Boolean> callback)199     public abstract void removeAllCookies(ValueCallback<Boolean> callback);
200 
201     /**
202      * Gets whether there are stored cookies.
203      *
204      * @return true if there are stored cookies
205      */
hasCookies()206     public abstract boolean hasCookies();
207 
208     /**
209      * See {@link #hasCookies()}.
210      *
211      * @param privateBrowsing whether to use the private browsing cookie jar
212      * @hide Used by Browser and WebViewProvider implementations.
213      */
214     @SystemApi
hasCookies(boolean privateBrowsing)215     public abstract boolean hasCookies(boolean privateBrowsing);
216 
217     /**
218      * Removes all expired cookies.
219      * @deprecated The WebView handles removing expired cookies automatically.
220      */
221     @Deprecated
removeExpiredCookie()222     public abstract void removeExpiredCookie();
223 
224     /**
225      * Ensures all cookies currently accessible through the getCookie API are
226      * written to persistent storage.
227      * This call will block the caller until it is done and may perform I/O.
228      */
flush()229     public abstract void flush();
230 
231     /**
232      * Gets whether the application's {@link WebView} instances send and accept
233      * cookies for file scheme URLs.
234      *
235      * @return true if {@link WebView} instances send and accept cookies for
236      *         file scheme URLs
237      */
238     // Static for backward compatibility.
allowFileSchemeCookies()239     public static boolean allowFileSchemeCookies() {
240         return getInstance().allowFileSchemeCookiesImpl();
241     }
242 
243     /**
244      * Implements {@link #allowFileSchemeCookies()}.
245      *
246      * @hide Only for use by WebViewProvider implementations
247      */
248     @SystemApi
allowFileSchemeCookiesImpl()249     protected abstract boolean allowFileSchemeCookiesImpl();
250 
251     /**
252      * Sets whether the application's {@link WebView} instances should send and
253      * accept cookies for file scheme URLs.
254      * Use of cookies with file scheme URLs is potentially insecure and turned
255      * off by default.
256      * Do not use this feature unless you can be sure that no unintentional
257      * sharing of cookie data can take place.
258      * <p>
259      * Note that calls to this method will have no effect if made after a
260      * {@link WebView} or CookieManager instance has been created.
261      */
262     // Static for backward compatibility.
setAcceptFileSchemeCookies(boolean accept)263     public static void setAcceptFileSchemeCookies(boolean accept) {
264         getInstance().setAcceptFileSchemeCookiesImpl(accept);
265     }
266 
267     /**
268      * Implements {@link #setAcceptFileSchemeCookies(boolean)}.
269      *
270      * @hide Only for use by WebViewProvider implementations
271      */
272     @SystemApi
setAcceptFileSchemeCookiesImpl(boolean accept)273     protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept);
274 }
275