The user agent object handles cookies automatically, accepting cookies from the server, and including cookies in subsequent requests. The following properties limit the size of the user agent's cookie jar.
x::http::cookiejar::cookiebytesmaxMaximum combined size of the cookie's name and value (default is 4096 bytes).
x::http::cookiejar::domainmaxMaximum number of cookies accepted for the same domain (default is a maximum of 50 cookies per domain).
These limits come from RFC 6265. There is no fixed limit to the maximum total number of cookies. The per-domain limit gets applied to the domain's public suffix, using the public suffix list.
The cookie jar belongs to each user agent object. Once the user agent object goes out of scope and gets destroyed, all the cookies get lost (unless they are saved and loaded, as described below). Each user agent object has its own individual cookie jar.
Saving and loading cookie jars.
#include <x/http/cookiejar.H> x::http::useragent ua(x::http::useragent::create()); try { ua->jar()->load("cookies.txt"); } catch (const x::exception &e) { } // ... ua->jar()->save("cookies.txt");
jar() returns the user agent's cookie jar.
It's not a particularly interesting object, except for its
save() and load()
methods. Note that save() saves only
persistent, unexpired cookies. Session cookies, and expired cookies,
do not get saved.
save() and load()
use the YAML file format, and it's necessary to
link with the YAML
library to use these methods.
It is possible to iterate over the contents of the cookie jar:
auto jar=ua->jar(); for (x::http::cookie cookie:*jar) { // ... }
The cookie jar object implements begin() and
end() that are suitable for range iteration.
They return a
x::http::cookiejar::base::iterator that
dereferences an
x::http::cookie.
Note that the iterator's *()
operator returns an rvalue.
The iterators can iterate over recently-expired cookies. An
expired cookie does not get automatically removed from the cookie jar,
however it no longer gets sent to the server, and it does not get
save()d, either.
iterators hold a read lock on the cookie jar object, as long as they remain in scope. This will prevent the cookie jar's user agent object from processing HTTP requests. Other threads will block, until the iterators go out of scope and get destroyed.