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