1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // Brought to you by number 42. 6 7 #ifndef NET_COOKIES_COOKIE_STORE_H_ 8 #define NET_COOKIES_COOKIE_STORE_H_ 9 10 #include <stdint.h> 11 12 #include <memory> 13 #include <optional> 14 #include <string> 15 #include <vector> 16 17 #include "base/functional/callback_forward.h" 18 #include "net/base/net_export.h" 19 #include "net/cookies/canonical_cookie.h" 20 #include "net/cookies/cookie_access_delegate.h" 21 #include "net/cookies/cookie_access_result.h" 22 #include "net/cookies/cookie_deletion_info.h" 23 #include "net/cookies/cookie_options.h" 24 #include "net/cookies/cookie_partition_key_collection.h" 25 26 class GURL; 27 28 namespace net { 29 30 class CookieChangeDispatcher; 31 32 // An interface for storing and retrieving cookies. Implementations are not 33 // thread safe, as with most other net classes. All methods must be invoked on 34 // the network thread, and all callbacks will be called there. 35 // 36 // All async functions may either invoke the callback asynchronously, or they 37 // may be invoked immediately (prior to return of the asynchronous function). 38 // Destroying the CookieStore will cancel pending async callbacks. 39 class NET_EXPORT CookieStore { 40 public: 41 // Callback definitions. 42 using GetCookieListCallback = 43 base::OnceCallback<void(const CookieAccessResultList& included_cookies, 44 const CookieAccessResultList& excluded_list)>; 45 using GetAllCookiesCallback = 46 base::OnceCallback<void(const CookieList& cookies)>; 47 // |access_semantics_list| is guaranteed to the same length as |cookies|. 48 using GetAllCookiesWithAccessSemanticsCallback = base::OnceCallback<void( 49 const CookieList& cookies, 50 const std::vector<CookieAccessSemantics>& access_semantics_list)>; 51 using SetCookiesCallback = 52 base::OnceCallback<void(CookieAccessResult access_result)>; 53 using DeleteCallback = base::OnceCallback<void(uint32_t num_deleted)>; 54 using DeletePredicate = 55 base::RepeatingCallback<bool(const CanonicalCookie& cookie)>; 56 using SetCookieableSchemesCallback = base::OnceCallback<void(bool success)>; 57 58 CookieStore(); 59 virtual ~CookieStore(); 60 61 // Set the cookie on the cookie store. |cookie.IsCanonical()| must 62 // be true. |source_url| denotes the url of the resource setting this. 63 // 64 // |options| is used to determine the context the operation is run in, and 65 // which cookies it can alter (e.g. http only, or same site). 66 // 67 // The current time will be used in place of a null creation time. 68 // 69 // |cookie_access_result| is an optional input status, to allow for status 70 // chaining from callers. It helps callers provide the status of a 71 // canonical cookie that may have warnings associated with it. 72 virtual void SetCanonicalCookieAsync( 73 std::unique_ptr<CanonicalCookie> cookie, 74 const GURL& source_url, 75 const CookieOptions& options, 76 SetCookiesCallback callback, 77 std::optional<CookieAccessResult> cookie_access_result = 78 std::nullopt) = 0; 79 80 // Obtains a CookieList for the given |url| and |options|. The returned 81 // cookies are passed into |callback|, ordered by longest path, then earliest 82 // creation date. 83 // To get all the cookies for a URL, use this method with an all-inclusive 84 // |options|. 85 // If |cookie_partition_key_collection| is not empty, then this function will 86 // return the partitioned cookies for that URL whose partition keys are in the 87 // cookie_partition_key_collection *in addition to* the unpartitioned cookies 88 // for that URL. 89 virtual void GetCookieListWithOptionsAsync( 90 const GURL& url, 91 const CookieOptions& options, 92 const CookiePartitionKeyCollection& cookie_partition_key_collection, 93 GetCookieListCallback callback) = 0; 94 95 // Returns all the cookies, for use in management UI, etc. This does not mark 96 // the cookies as having been accessed. The returned cookies are ordered by 97 // longest path, then by earliest creation date. 98 virtual void GetAllCookiesAsync(GetAllCookiesCallback callback) = 0; 99 100 // Returns all the cookies, for use in management UI, etc. This does not mark 101 // the cookies as having been accessed. The returned cookies are ordered by 102 // longest path, then by earliest creation date. 103 // Additionally returns a vector of CookieAccessSemantics values for the 104 // returned cookies, which will be the same length as the vector of returned 105 // cookies. This vector will either contain all CookieAccessSemantics::UNKNOWN 106 // (if the default implementation is used), or each entry in the 107 // vector of CookieAccessSemantics will indicate the access semantics 108 // applicable to the cookie at the same index in the returned CookieList. 109 virtual void GetAllCookiesWithAccessSemanticsAsync( 110 GetAllCookiesWithAccessSemanticsCallback callback); 111 112 // Deletes one specific cookie. |cookie| must have been returned by a previous 113 // query on this CookieStore. Invokes |callback| with 1 if a cookie was 114 // deleted, 0 otherwise. 115 virtual void DeleteCanonicalCookieAsync(const CanonicalCookie& cookie, 116 DeleteCallback callback) = 0; 117 118 // Deletes all of the cookies that have a creation_date matching 119 // |creation_range|. See CookieDeletionInfo::TimeRange::Matches(). 120 // Calls |callback| with the number of cookies deleted. 121 virtual void DeleteAllCreatedInTimeRangeAsync( 122 const CookieDeletionInfo::TimeRange& creation_range, 123 DeleteCallback callback) = 0; 124 125 // Deletes all of the cookies matching |delete_info|. This includes all 126 // http_only and secure cookies. Avoid deleting cookies that could leave 127 // websites with a partial set of visible cookies. 128 // Calls |callback| with the number of cookies deleted. 129 virtual void DeleteAllMatchingInfoAsync(CookieDeletionInfo delete_info, 130 DeleteCallback callback) = 0; 131 132 // Deletes all cookies without expiration data. 133 virtual void DeleteSessionCookiesAsync(DeleteCallback callback) = 0; 134 135 // Deletes all cookies where |predicate| returns true. 136 // Calls |callback| with the number of cookies deleted. 137 virtual void DeleteMatchingCookiesAsync(DeletePredicate predicate, 138 DeleteCallback callback) = 0; 139 140 // Deletes all cookies in the store. 141 void DeleteAllAsync(DeleteCallback callback); 142 143 // Flush the backing store (if any) to disk and post the given callback when 144 // done. 145 virtual void FlushStore(base::OnceClosure callback) = 0; 146 147 // Protects session cookies from deletion on shutdown, if the underlying 148 // CookieStore implemention is currently configured to store them to disk. 149 // Otherwise, does nothing. SetForceKeepSessionState()150 virtual void SetForceKeepSessionState() {} 151 152 // The interface used to observe changes to this CookieStore's contents. 153 virtual CookieChangeDispatcher& GetChangeDispatcher() = 0; 154 155 // Resets the list of cookieable schemes to the supplied schemes. Does nothing 156 // (and returns false) if called after first use of the instance (i.e. after 157 // the instance initialization process). Otherwise, this returns true to 158 // indicate success. CookieStores which do not support modifying cookieable 159 // schemes will always return false. 160 virtual void SetCookieableSchemes(const std::vector<std::string>& schemes, 161 SetCookieableSchemesCallback callback) = 0; 162 163 // Transfer ownership of a CookieAccessDelegate. 164 void SetCookieAccessDelegate(std::unique_ptr<CookieAccessDelegate> delegate); 165 166 // This may be null if no delegate has been set yet, or the delegate has been 167 // reset to null. cookie_access_delegate()168 const CookieAccessDelegate* cookie_access_delegate() const { 169 return cookie_access_delegate_.get(); 170 } 171 172 // Returns a boolean indicating whether the cookie `site` has any cookie 173 // in another partition other than the `cookie_partition_key` supplied. 174 // Will return nullopt if cookies have not finished loading. 175 // If the partition key is null, the method assumes it is because partitioned 176 // cookies are disabled. 177 virtual std::optional<bool> SiteHasCookieInOtherPartition( 178 const net::SchemefulSite& site, 179 const std::optional<CookiePartitionKey>& cookie_partition_key) const; 180 181 private: 182 // Used to determine whether a particular cookie should be subject to legacy 183 // or non-legacy access semantics. 184 std::unique_ptr<CookieAccessDelegate> cookie_access_delegate_; 185 }; 186 187 } // namespace net 188 189 #endif // NET_COOKIES_COOKIE_STORE_H_ 190