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 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    @Deprecated
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     */
178    public abstract void removeSessionCookies(ValueCallback<Boolean> callback);
179
180    /**
181     * Removes all cookies.
182     * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead.
183     */
184    @Deprecated
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     */
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     */
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
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
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     */
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.
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
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.
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
274    protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept);
275}
276