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
17package android.webkit;
18
19import android.annotation.SystemApi;
20import 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 */
26public abstract class CookieManager {
27
28    @Override
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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
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
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    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     */
177    public abstract void removeSessionCookies(ValueCallback<Boolean> callback);
178
179    /**
180     * Removes all cookies.
181     * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead.
182     */
183    @Deprecated
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     */
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     */
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
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
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     */
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.
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
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.
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
273    protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept);
274}
275