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