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.Nullable; 20 import android.annotation.SystemApi; 21 import android.net.WebAddress; 22 23 /** 24 * Manages the cookies used by an application's {@link WebView} instances. 25 * <p> 26 * CookieManager represents cookies as strings in the same format as the 27 * HTTP {@code Cookie} and {@code Set-Cookie} header fields (defined in 28 * <a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03">RFC6265bis</a>). 29 */ 30 public abstract class CookieManager { 31 /** 32 * @deprecated This class should not be constructed by applications, use {@link #getInstance} 33 * instead to fetch the singleton instance. 34 */ 35 // TODO(ntfschr): mark this as @SystemApi after a year. 36 @Deprecated CookieManager()37 public CookieManager() {} 38 39 @Override clone()40 protected Object clone() throws CloneNotSupportedException { 41 throw new CloneNotSupportedException("doesn't implement Cloneable"); 42 } 43 44 /** 45 * Gets the singleton CookieManager instance. 46 * 47 * @return the singleton CookieManager instance 48 */ getInstance()49 public static CookieManager getInstance() { 50 return WebViewFactory.getProvider().getCookieManager(); 51 } 52 53 /** 54 * Sets whether the application's {@link WebView} instances should send and 55 * accept cookies. 56 * By default this is set to {@code true} and the WebView accepts cookies. 57 * <p> 58 * When this is {@code true} 59 * {@link CookieManager#setAcceptThirdPartyCookies setAcceptThirdPartyCookies} and 60 * {@link CookieManager#setAcceptFileSchemeCookies setAcceptFileSchemeCookies} 61 * can be used to control the policy for those specific types of cookie. 62 * 63 * @param accept whether {@link WebView} instances should send and accept 64 * cookies 65 */ setAcceptCookie(boolean accept)66 public abstract void setAcceptCookie(boolean accept); 67 68 /** 69 * Gets whether the application's {@link WebView} instances send and accept 70 * cookies. 71 * 72 * @return {@code true} if {@link WebView} instances send and accept cookies 73 */ acceptCookie()74 public abstract boolean acceptCookie(); 75 76 /** 77 * Sets whether the {@link WebView} should allow third party cookies to be set. 78 * Allowing third party cookies is a per WebView policy and can be set 79 * differently on different WebView instances. 80 * <p> 81 * Apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below 82 * default to allowing third party cookies. Apps targeting 83 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later default to disallowing 84 * third party cookies. 85 * 86 * @param webview the {@link WebView} instance to set the cookie policy on 87 * @param accept whether the {@link WebView} instance should accept 88 * third party cookies 89 */ setAcceptThirdPartyCookies(WebView webview, boolean accept)90 public abstract void setAcceptThirdPartyCookies(WebView webview, boolean accept); 91 92 /** 93 * Gets whether the {@link WebView} should allow third party cookies to be set. 94 * 95 * @param webview the {@link WebView} instance to get the cookie policy for 96 * @return {@code true} if the {@link WebView} accepts third party cookies 97 */ acceptThirdPartyCookies(WebView webview)98 public abstract boolean acceptThirdPartyCookies(WebView webview); 99 100 /** 101 * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same 102 * host, path and name will be replaced with the new cookie. The cookie being set 103 * will be ignored if it is expired. To set multiple cookies, your application should invoke 104 * this method multiple times. 105 * 106 * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP response 107 * header. This is a key-value pair of the form {@code "key=value"}, optionally followed by a 108 * list of cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). 109 * For the header format and attributes supported by WebView, see the <a href= 110 * "https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie">{@code Set-Cookie} 111 * documentation on MDN</a>. 112 * 113 * <p class="note"> 114 * <b>Notes:</b> 115 * <ul> 116 * <li>If specifying a {@code value} containing the {@code "Secure"} attribute, 117 * {@code url} must use the {@code "https://"} scheme.</li> 118 * <li>if specifying a {@code value} containing the {@code "Partitioned"} 119 * attribute, the cookie will be set for the top-level partition of the 120 * {@code url}.</li> 121 * </ul> 122 * 123 * @param url the URL for which the cookie is to be set 124 * @param value the cookie as a string, using the format of the 'Set-Cookie' 125 * HTTP response header 126 */ setCookie(String url, String value)127 public abstract void setCookie(String url, String value); 128 129 /** 130 * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same 131 * host, path and name will be replaced with the new cookie. The cookie being set 132 * will be ignored if it is expired. To set multiple cookies, your application should invoke 133 * this method multiple times. 134 * 135 * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP response 136 * header. This is a key-value pair of the form {@code "key=value"}, optionally followed by a 137 * list of cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). 138 * For the header format and attributes supported by WebView, see the <a href= 139 * "https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie">{@code Set-Cookie} 140 * documentation on MDN</a>. 141 * 142 * <p>This method is asynchronous. If a {@link ValueCallback} is provided, 143 * {@link ValueCallback#onReceiveValue} will be called on the current 144 * thread's {@link android.os.Looper} once the operation is complete. 145 * The value provided to the callback indicates whether the cookie was set successfully. 146 * You can pass {@code null} as the callback if you don't need to know when the operation 147 * completes or whether it succeeded, and in this case it is safe to call the method from a 148 * thread without a Looper. 149 * 150 * <p class="note"> 151 * <b>Notes:</b> 152 * <ul> 153 * <li>If specifying a {@code value} containing the {@code "Secure"} attribute, 154 * {@code url} must use the {@code "https://"} scheme.</li> 155 * <li>if specifying a {@code value} containing the {@code "Partitioned"} 156 * attribute, the cookie will be set for the top-level partition of the 157 * {@code url}.</li> 158 * </ul> 159 * 160 * @param url the URL for which the cookie is to be set 161 * @param value the cookie as a string, using the format of the 'Set-Cookie' 162 * HTTP response header 163 * @param callback a callback to be executed when the cookie has been set 164 */ setCookie(String url, String value, @Nullable ValueCallback<Boolean> callback)165 public abstract void setCookie(String url, String value, @Nullable ValueCallback<Boolean> 166 callback); 167 168 /** 169 * Gets all the cookies for the given URL. This may return multiple key-value pairs if multiple 170 * cookies are associated with this URL, in which case each cookie will be delimited by {@code 171 * "; "} characters (semicolon followed by a space). Each key-value pair will be of the form 172 * {@code "key=value"}. 173 * 174 * <p class="note"> 175 * <b>Note:</b> Any cookies set with the {@code "Partitioned"} attribute will only be returned 176 * for the top-level partition of {@code url}. 177 * 178 * @param url the URL for which the cookies are requested 179 * @return value the cookies as a string, using the format of the 'Cookie' 180 * HTTP request header 181 */ getCookie(String url)182 public abstract String getCookie(String url); 183 184 /** 185 * See {@link #getCookie(String)}. 186 * 187 * @param url the URL for which the cookies are requested 188 * @param privateBrowsing whether to use the private browsing cookie jar 189 * @return value the cookies as a string, using the format of the 'Cookie' 190 * HTTP request header 191 * @hide Used by Browser and by WebViewProvider implementations. 192 */ 193 @SuppressWarnings("HiddenAbstractMethod") 194 @SystemApi getCookie(String url, boolean privateBrowsing)195 public abstract String getCookie(String url, boolean privateBrowsing); 196 197 /** 198 * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http 199 * request header. 200 * 201 * @param uri the WebAddress for which the cookies are requested 202 * @return value the cookies as a string, using the format of the 'Cookie' 203 * HTTP request header 204 * @hide Used by RequestHandle and by WebViewProvider implementations. 205 */ 206 @SystemApi getCookie(WebAddress uri)207 public synchronized String getCookie(WebAddress uri) { 208 return getCookie(uri.toString()); 209 } 210 211 /** 212 * Removes all session cookies, which are cookies without an expiration 213 * date. 214 * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead. 215 */ 216 @Deprecated removeSessionCookie()217 public abstract void removeSessionCookie(); 218 219 /** 220 * Removes all session cookies, which are cookies without an expiration 221 * date. 222 * <p> 223 * This method is asynchronous. 224 * If a {@link ValueCallback} is provided, 225 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 226 * thread's {@link android.os.Looper} once the operation is complete. 227 * The value provided to the callback indicates whether any cookies were removed. 228 * You can pass {@code null} as the callback if you don't need to know when the operation 229 * completes or whether any cookie were removed, and in this case it is safe to call the 230 * method from a thread without a Looper. 231 * @param callback a callback which is executed when the session cookies have been removed 232 */ removeSessionCookies(@ullable ValueCallback<Boolean> callback)233 public abstract void removeSessionCookies(@Nullable ValueCallback<Boolean> callback); 234 235 /** 236 * Removes all cookies. 237 * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead. 238 */ 239 @Deprecated removeAllCookie()240 public abstract void removeAllCookie(); 241 242 /** 243 * Removes all cookies. 244 * <p> 245 * This method is asynchronous. 246 * If a {@link ValueCallback} is provided, 247 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 248 * thread's {@link android.os.Looper} once the operation is complete. 249 * The value provided to the callback indicates whether any cookies were removed. 250 * You can pass {@code null} as the callback if you don't need to know when the operation 251 * completes or whether any cookies were removed, and in this case it is safe to call the 252 * method from a thread without a Looper. 253 * @param callback a callback which is executed when the cookies have been removed 254 */ removeAllCookies(@ullable ValueCallback<Boolean> callback)255 public abstract void removeAllCookies(@Nullable ValueCallback<Boolean> callback); 256 257 /** 258 * Gets whether there are stored cookies. 259 * 260 * @return {@code true} if there are stored cookies 261 */ hasCookies()262 public abstract boolean hasCookies(); 263 264 /** 265 * See {@link #hasCookies()}. 266 * 267 * @param privateBrowsing whether to use the private browsing cookie jar 268 * @hide Used by Browser and WebViewProvider implementations. 269 */ 270 @SuppressWarnings("HiddenAbstractMethod") 271 @SystemApi hasCookies(boolean privateBrowsing)272 public abstract boolean hasCookies(boolean privateBrowsing); 273 274 /** 275 * Removes all expired cookies. 276 * @deprecated The WebView handles removing expired cookies automatically. 277 */ 278 @Deprecated removeExpiredCookie()279 public abstract void removeExpiredCookie(); 280 281 /** 282 * Ensures all cookies currently accessible through the getCookie API are 283 * written to persistent storage. 284 * This call will block the caller until it is done and may perform I/O. 285 */ flush()286 public abstract void flush(); 287 288 /** 289 * Gets whether the application's {@link WebView} instances send and accept 290 * cookies for file scheme URLs. 291 * 292 * @return {@code true} if {@link WebView} instances send and accept cookies for 293 * file scheme URLs 294 */ 295 // Static for backward compatibility. allowFileSchemeCookies()296 public static boolean allowFileSchemeCookies() { 297 return getInstance().allowFileSchemeCookiesImpl(); 298 } 299 300 /** 301 * Implements {@link #allowFileSchemeCookies()}. 302 * 303 * @hide Only for use by WebViewProvider implementations 304 */ 305 @SuppressWarnings("HiddenAbstractMethod") 306 @SystemApi allowFileSchemeCookiesImpl()307 protected abstract boolean allowFileSchemeCookiesImpl(); 308 309 /** 310 * Sets whether the application's {@link WebView} instances should send and accept cookies for 311 * file scheme URLs. 312 * <p> 313 * Use of cookies with file scheme URLs is potentially insecure and turned off by default. All 314 * {@code file://} URLs share all their cookies, which may lead to leaking private app cookies 315 * (ex. any malicious file can access cookies previously set by other (trusted) files). 316 * <p class="note"> 317 * Loading content via {@code file://} URLs is generally discouraged. See the note in 318 * {@link WebSettings#setAllowFileAccess}. 319 * Using <a href="{@docRoot}reference/androidx/webkit/WebViewAssetLoader.html"> 320 * androidx.webkit.WebViewAssetLoader</a> to load files over {@code http(s)://} URLs allows 321 * the standard web security model to be used for setting and sharing cookies for local files. 322 * <p> 323 * Note that calls to this method will have no effect if made after calling other 324 * {@link CookieManager} APIs. 325 * 326 * @deprecated This setting is not secure, please use 327 * <a href="{@docRoot}reference/androidx/webkit/WebViewAssetLoader.html"> 328 * androidx.webkit.WebViewAssetLoader</a> instead. 329 */ 330 // Static for backward compatibility. 331 @Deprecated setAcceptFileSchemeCookies(boolean accept)332 public static void setAcceptFileSchemeCookies(boolean accept) { 333 getInstance().setAcceptFileSchemeCookiesImpl(accept); 334 } 335 336 /** 337 * Implements {@link #setAcceptFileSchemeCookies(boolean)}. 338 * 339 * @hide Only for use by WebViewProvider implementations 340 */ 341 @SuppressWarnings("HiddenAbstractMethod") 342 @SystemApi setAcceptFileSchemeCookiesImpl(boolean accept)343 protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept); 344 } 345