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 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 * 105 * @param url the URL for which the cookie is to be set 106 * @param value the cookie as a string, using the format of the 'Set-Cookie' 107 * HTTP response header 108 */ setCookie(String url, String value)109 public abstract void setCookie(String url, String value); 110 111 /** 112 * Sets a cookie for the given URL. Any existing cookie with the same host, 113 * path and name will be replaced with the new cookie. The cookie being set 114 * will be ignored if it is expired. 115 * <p> 116 * This method is asynchronous. 117 * If a {@link ValueCallback} is provided, 118 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 119 * thread's {@link android.os.Looper} once the operation is complete. 120 * The value provided to the callback indicates whether the cookie was set successfully. 121 * You can pass {@code null} as the callback if you don't need to know when the operation 122 * completes or whether it succeeded, and in this case it is safe to call the method from a 123 * thread without a Looper. 124 * 125 * @param url the URL for which the cookie is to be set 126 * @param value the cookie as a string, using the format of the 'Set-Cookie' 127 * HTTP response header 128 * @param callback a callback to be executed when the cookie has been set 129 */ setCookie(String url, String value, @Nullable ValueCallback<Boolean> callback)130 public abstract void setCookie(String url, String value, @Nullable ValueCallback<Boolean> 131 callback); 132 133 /** 134 * Gets the cookies for the given URL. 135 * 136 * @param url the URL for which the cookies are requested 137 * @return value the cookies as a string, using the format of the 'Cookie' 138 * HTTP request header 139 */ getCookie(String url)140 public abstract String getCookie(String url); 141 142 /** 143 * See {@link #getCookie(String)}. 144 * 145 * @param url the URL for which the cookies are requested 146 * @param privateBrowsing whether to use the private browsing cookie jar 147 * @return value the cookies as a string, using the format of the 'Cookie' 148 * HTTP request header 149 * @hide Used by Browser and by WebViewProvider implementations. 150 */ 151 @SystemApi getCookie(String url, boolean privateBrowsing)152 public abstract String getCookie(String url, boolean privateBrowsing); 153 154 /** 155 * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http 156 * request header. 157 * 158 * @param uri the WebAddress for which the cookies are requested 159 * @return value the cookies as a string, using the format of the 'Cookie' 160 * HTTP request header 161 * @hide Used by RequestHandle and by WebViewProvider implementations. 162 */ 163 @SystemApi getCookie(WebAddress uri)164 public synchronized String getCookie(WebAddress uri) { 165 return getCookie(uri.toString()); 166 } 167 168 /** 169 * Removes all session cookies, which are cookies without an expiration 170 * date. 171 * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead. 172 */ 173 @Deprecated removeSessionCookie()174 public abstract void removeSessionCookie(); 175 176 /** 177 * Removes all session cookies, which are cookies without an expiration 178 * date. 179 * <p> 180 * This method is asynchronous. 181 * If a {@link ValueCallback} is provided, 182 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 183 * thread's {@link android.os.Looper} once the operation is complete. 184 * The value provided to the callback indicates whether any cookies were removed. 185 * You can pass {@code null} as the callback if you don't need to know when the operation 186 * completes or whether any cookie were removed, and in this case it is safe to call the 187 * method from a thread without a Looper. 188 * @param callback a callback which is executed when the session cookies have been removed 189 */ removeSessionCookies(@ullable ValueCallback<Boolean> callback)190 public abstract void removeSessionCookies(@Nullable ValueCallback<Boolean> callback); 191 192 /** 193 * Removes all cookies. 194 * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead. 195 */ 196 @Deprecated removeAllCookie()197 public abstract void removeAllCookie(); 198 199 /** 200 * Removes all cookies. 201 * <p> 202 * This method is asynchronous. 203 * If a {@link ValueCallback} is provided, 204 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 205 * thread's {@link android.os.Looper} once the operation is complete. 206 * The value provided to the callback indicates whether any cookies were removed. 207 * You can pass {@code null} as the callback if you don't need to know when the operation 208 * completes or whether any cookies were removed, and in this case it is safe to call the 209 * method from a thread without a Looper. 210 * @param callback a callback which is executed when the cookies have been removed 211 */ removeAllCookies(@ullable ValueCallback<Boolean> callback)212 public abstract void removeAllCookies(@Nullable ValueCallback<Boolean> callback); 213 214 /** 215 * Gets whether there are stored cookies. 216 * 217 * @return {@code true} if there are stored cookies 218 */ hasCookies()219 public abstract boolean hasCookies(); 220 221 /** 222 * See {@link #hasCookies()}. 223 * 224 * @param privateBrowsing whether to use the private browsing cookie jar 225 * @hide Used by Browser and WebViewProvider implementations. 226 */ 227 @SystemApi hasCookies(boolean privateBrowsing)228 public abstract boolean hasCookies(boolean privateBrowsing); 229 230 /** 231 * Removes all expired cookies. 232 * @deprecated The WebView handles removing expired cookies automatically. 233 */ 234 @Deprecated removeExpiredCookie()235 public abstract void removeExpiredCookie(); 236 237 /** 238 * Ensures all cookies currently accessible through the getCookie API are 239 * written to persistent storage. 240 * This call will block the caller until it is done and may perform I/O. 241 */ flush()242 public abstract void flush(); 243 244 /** 245 * Gets whether the application's {@link WebView} instances send and accept 246 * cookies for file scheme URLs. 247 * 248 * @return {@code true} if {@link WebView} instances send and accept cookies for 249 * file scheme URLs 250 */ 251 // Static for backward compatibility. allowFileSchemeCookies()252 public static boolean allowFileSchemeCookies() { 253 return getInstance().allowFileSchemeCookiesImpl(); 254 } 255 256 /** 257 * Implements {@link #allowFileSchemeCookies()}. 258 * 259 * @hide Only for use by WebViewProvider implementations 260 */ 261 @SystemApi allowFileSchemeCookiesImpl()262 protected abstract boolean allowFileSchemeCookiesImpl(); 263 264 /** 265 * Sets whether the application's {@link WebView} instances should send and 266 * accept cookies for file scheme URLs. 267 * Use of cookies with file scheme URLs is potentially insecure and turned 268 * off by default. 269 * Do not use this feature unless you can be sure that no unintentional 270 * sharing of cookie data can take place. 271 * <p> 272 * Note that calls to this method will have no effect if made after a 273 * {@link WebView} or CookieManager instance has been created. 274 */ 275 // Static for backward compatibility. setAcceptFileSchemeCookies(boolean accept)276 public static void setAcceptFileSchemeCookies(boolean accept) { 277 getInstance().setAcceptFileSchemeCookiesImpl(accept); 278 } 279 280 /** 281 * Implements {@link #setAcceptFileSchemeCookies(boolean)}. 282 * 283 * @hide Only for use by WebViewProvider implementations 284 */ 285 @SystemApi setAcceptFileSchemeCookiesImpl(boolean accept)286 protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept); 287 } 288