1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Brought to you by number 42.
#ifndef NET_COOKIES_COOKIE_STORE_H_
#define NET_COOKIES_COOKIE_STORE_H_
#include <memory>
#include <string>
#include <vector>
#include "base/callback_forward.h"
#include "base/callback_list.h"
#include "base/time/time.h"
#include "net/base/net_export.h"
#include "net/cookies/canonical_cookie.h"
#include "net/cookies/cookie_options.h"
class GURL;
namespace net {
// An interface for storing and retrieving cookies. Implementations are not
// thread safe, as with most other net classes. All methods must be invoked on
// the network thread, and all callbacks will be calle there.
//
// All async functions may either invoke the callback asynchronously, or they
// may be invoked immediately (prior to return of the asynchronous function).
// Destroying the CookieStore will cancel pending async callbacks.
class NET_EXPORT CookieStore {
public:
// The publicly relevant reasons a cookie might be changed.
enum class ChangeCause {
// The cookie was inserted.
INSERTED,
// The cookie was changed directly by a consumer's action.
EXPLICIT,
// The following four values have the same meaning as EXPLICIT, but are
// being used to track down where a bug is coming from.
// TODO(nharper): Remove the following four values once the one of interest
// has been found.
EXPLICIT_DELETE_BETWEEN,
EXPLICIT_DELETE_PREDICATE,
EXPLICIT_DELETE_SINGLE,
EXPLICIT_DELETE_CANONICAL,
// The cookie was deleted, but no more details are known.
UNKNOWN_DELETION,
// The cookie was automatically removed due to an insert operation that
// overwrote it.
OVERWRITE,
// The cookie was automatically removed as it expired.
EXPIRED,
// The cookie was automatically evicted during garbage collection.
EVICTED,
// The cookie was overwritten with an already-expired expiration date.
EXPIRED_OVERWRITE
};
// Returns whether |cause| is one that could be a reason for deleting a
// cookie. This function assumes that ChangeCause::EXPLICIT is a reason for
// deletion.
static bool ChangeCauseIsDeletion(ChangeCause cause);
// Callback definitions.
typedef base::Callback<void(const CookieList& cookies)> GetCookieListCallback;
typedef base::Callback<void(const std::string& cookie)> GetCookiesCallback;
typedef base::Callback<void(bool success)> SetCookiesCallback;
typedef base::Callback<void(int num_deleted)> DeleteCallback;
typedef base::Callback<void(const CanonicalCookie& cookie, ChangeCause cause)>
CookieChangedCallback;
typedef base::CallbackList<void(const CanonicalCookie& cookie,
ChangeCause cause)>
CookieChangedCallbackList;
typedef CookieChangedCallbackList::Subscription CookieChangedSubscription;
typedef base::Callback<bool(const CanonicalCookie& cookie)> CookiePredicate;
virtual ~CookieStore();
// Returns the cookie line (e.g. "cookie1=value1; cookie2=value2") represented
// by |cookies|. The string is built in the same order as the given list.
//
// TODO(mkwst): We really should standardize on either
// 'std::vector<CanonicalCookie>' or 'std::vector<CanonicalCookie*>'.
static std::string BuildCookieLine(
const std::vector<CanonicalCookie>& cookies);
static std::string BuildCookieLine(
const std::vector<CanonicalCookie*>& cookies);
// Sets the cookies specified by |cookie_list| returned from |url|
// with options |options| in effect. Expects a cookie line, like
// "a=1; domain=b.com".
//
// Fails either if the cookie is invalid or if this is a non-HTTPONLY cookie
// and it would overwrite an existing HTTPONLY cookie.
// Returns true if the cookie is successfully set.
virtual void SetCookieWithOptionsAsync(
const GURL& url,
const std::string& cookie_line,
const CookieOptions& options,
const SetCookiesCallback& callback) = 0;
// Sets a cookie given explicit user-provided cookie attributes. The cookie
// name, value, domain, etc. are each provided as separate strings. This
// function expects each attribute to be well-formed. It will check for
// disallowed characters (e.g. the ';' character is disallowed within the
// cookie value attribute) and will return false without setting the cookie
// if such characters are found.
//
// If |creation_time| is null, it will be set to the time the cookie is set.
// If |last_access_time| is null, it be set to |creation_time|.
//
// If unable to set a cookie, will invoke |callback| with false.
virtual void SetCookieWithDetailsAsync(
const GURL& url,
const std::string& name,
const std::string& value,
const std::string& domain,
const std::string& path,
base::Time creation_time,
base::Time expiration_time,
base::Time last_access_time,
bool secure,
bool http_only,
CookieSameSite same_site,
CookiePriority priority,
const SetCookiesCallback& callback) = 0;
// TODO(???): what if the total size of all the cookies >4k, can we have a
// header that big or do we need multiple Cookie: headers?
// Note: Some sites, such as Facebook, occasionally use Cookie headers >4k.
//
// Simple interface, gets a cookie string "a=b; c=d" for the given URL.
// Gets all cookies that apply to |url| given |options|. Use options to
// access httponly cookies.
//
// The returned cookies are ordered by longest path, then earliest
// creation date.
//
// TODO(mkwst): This method is deprecated; callsites should be updated to
// use 'GetCookieListWithOptionsAsync'.
virtual void GetCookiesWithOptionsAsync(
const GURL& url,
const CookieOptions& options,
const GetCookiesCallback& callback) = 0;
// Obtains a CookieList for the given |url| and |options|. The returned
// cookies are passed into |callback|, ordered by longest path, then earliest
// creation date.
virtual void GetCookieListWithOptionsAsync(
const GURL& url,
const CookieOptions& options,
const GetCookieListCallback& callback) = 0;
// Returns all cookies associated with |url|, including http-only, and
// same-site cookies. The returned cookies are ordered by longest path, then
// by earliest creation date, and are not marked as having been accessed.
//
// TODO(mkwst): This method is deprecated, and should be removed, either by
// updating callsites to use 'GetCookieListWithOptionsAsync' with an explicit
// CookieOptions, or by changing CookieOptions' defaults.
void GetAllCookiesForURLAsync(const GURL& url,
const GetCookieListCallback& callback);
// Returns all the cookies, for use in management UI, etc. This does not mark
// the cookies as having been accessed. The returned cookies are ordered by
// longest path, then by earliest creation date.
virtual void GetAllCookiesAsync(const GetCookieListCallback& callback) = 0;
// Deletes all cookies that might apply to |url| that have |cookie_name|.
virtual void DeleteCookieAsync(const GURL& url,
const std::string& cookie_name,
const base::Closure& callback) = 0;
// Deletes one specific cookie. |cookie| must have been returned by a previous
// query on this CookieStore. Invokes |callback| with 1 if a cookie was
// deleted, 0 otherwise.
virtual void DeleteCanonicalCookieAsync(const CanonicalCookie& cookie,
const DeleteCallback& callback) = 0;
// Deletes all of the cookies that have a creation_date greater than or equal
// to |delete_begin| and less than |delete_end|
// Calls |callback| with the number of cookies deleted.
virtual void DeleteAllCreatedBetweenAsync(const base::Time& delete_begin,
const base::Time& delete_end,
const DeleteCallback& callback) = 0;
// Deletes all of the cookies that match the given predicate and that have a
// creation_date greater than or equal to |delete_begin| and smaller than
// |delete_end|. This includes all http_only and secure cookies. Avoid
// deleting cookies that could leave websites with a partial set of visible
// cookies.
// Calls |callback| with the number of cookies deleted.
virtual void DeleteAllCreatedBetweenWithPredicateAsync(
const base::Time& delete_begin,
const base::Time& delete_end,
const CookiePredicate& predicate,
const DeleteCallback& callback) = 0;
virtual void DeleteSessionCookiesAsync(const DeleteCallback&) = 0;
// Deletes all cookies in the store.
void DeleteAllAsync(const DeleteCallback& callback);
// Flush the backing store (if any) to disk and post the given callback when
// done.
virtual void FlushStore(const base::Closure& callback) = 0;
// Protects session cookies from deletion on shutdown, if the underlying
// CookieStore implemention is currently configured to store them to disk.
// Otherwise, does nothing.
virtual void SetForceKeepSessionState();
// Add a callback to be notified when the set of cookies named |name| that
// would be sent for a request to |url| changes. The returned handle is
// guaranteed not to hold a hard reference to the CookieStore object.
//
// |callback| will be called when a cookie is added or removed. |callback| is
// passed the respective |cookie| which was added to or removed from the
// cookies and a boolean indicating if the cookies was removed or not.
//
// Note that |callback| is called twice when a cookie is updated: once for
// the removal of the existing cookie and once for the adding the new cookie.
//
// Note that this method consumes memory and CPU per (url, name) pair ever
// registered that are still consumed even after all subscriptions for that
// (url, name) pair are removed. If this method ever needs to support an
// unbounded amount of such pairs, this contract needs to change and
// implementors need to be improved to not behave this way.
//
// The callback must not synchronously modify another cookie.
virtual std::unique_ptr<CookieChangedSubscription> AddCallbackForCookie(
const GURL& url,
const std::string& name,
const CookieChangedCallback& callback) = 0;
// Returns true if this cookie store is ephemeral, and false if it is backed
// by some sort of persistence layer.
// TODO(nharper): Remove this method once crbug.com/548423 has been closed.
virtual bool IsEphemeral() = 0;
void SetChannelIDServiceID(int id);
int GetChannelIDServiceID();
protected:
CookieStore();
int channel_id_service_id_;
};
} // namespace net
#endif // NET_COOKIES_COOKIE_STORE_H_
|