Struct soup::Cookie

pub struct Cookie { /* private fields */ }

Implements HTTP cookies, as described by RFC 6265.

To have a Session handle cookies for your appliction automatically, use a CookieJar.

@name and @value will be set for all cookies. If the cookie is generated from a string that appears to have no name, then @name will be the empty string.

@domain and @path give the host or domain, and path within that host/domain, to restrict this cookie to. If @domain starts with “.”, that indicates a domain (which matches the string after the “.”, or any hostname that has @domain as a suffix). Otherwise, it is a hostname and must match exactly.

@expires will be non-None if the cookie uses either the original “expires” attribute, or the newer “max-age” attribute. If @expires is None, it indicates that neither “expires” nor “max-age” was specified, and the cookie expires at the end of the session.

If @http_only is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks.

Implementations

impl Cookie

pub fn as_ptr(&self) -> *mut SoupCookie

Return the inner pointer to the underlying C value.

pub unsafe fn from_glib_ptr_borrow<'a>( ptr: *const *const SoupCookie ) -> &'a Self

Borrows the underlying C value.

pub unsafe fn from_glib_ptr_borrow_mut<'a>( ptr: *mut *mut SoupCookie ) -> &'a mut Self

Borrows the underlying C value mutably.

impl Cookie

pub fn new( name: &str, value: &str, domain: &str, path: &str, max_age: i32 ) -> Cookie

Creates a new #SoupCookie with the given attributes.

Use set_secure() and set_http_only() if you need to set those attributes on the returned cookie.

If @domain starts with “.”, that indicates a domain (which matches the string after the “.”, or any hostname that has @domain as a suffix). Otherwise, it is a hostname and must match exactly.

@max_age is used to set the “expires” attribute on the cookie; pass -1 to not include the attribute (indicating that the cookie expires with the current session), 0 for an already-expired cookie, or a lifetime in seconds. You can use the constants SOUP_COOKIE_MAX_AGE_ONE_HOUR, SOUP_COOKIE_MAX_AGE_ONE_DAY, SOUP_COOKIE_MAX_AGE_ONE_WEEK and SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (If you really care about setting the exact time that the cookie will expire, use set_expires().)

As of version 3.4.0 the default value of a cookie’s same-site-policy is SameSitePolicy::Lax.

name

cookie name

value

cookie value

domain

cookie domain or hostname

path

cookie path, or None

max_age

max age of the cookie, or -1 for a session cookie

Returns

a new #SoupCookie.

pub fn applies_to_uri(&mut self, uri: &Uri) -> bool

Tests if @self should be sent to @uri.

(At the moment, this does not check that @self’s domain matches @uri, because it assumes that the caller has already done that. But don’t rely on that; it may change in the future.)

uri

a #GUri

Returns

true if @self should be sent to @uri, false if not

pub fn domain_matches(&mut self, host: &str) -> bool

Checks if the @self’s domain and @host match.

The domains match if @self should be sent when making a request to @host, or that @self should be accepted when receiving a response from @host.

host

a URI

Returns

true if the domains match, false otherwise

pub fn domain(&mut self) -> Option<GString>

Gets @self’s domain.

Returns

@self’s domain

pub fn expires(&mut self) -> Option<DateTime>

Gets @self’s expiration time.

Returns

@self’s expiration time, which is owned by @self and should not be modified or freed.

pub fn is_http_only(&mut self) -> bool

Gets @self’s HttpOnly attribute.

Returns

@self’s HttpOnly attribute

pub fn name(&mut self) -> Option<GString>

Gets @self’s name.

Returns

@self’s name

pub fn path(&mut self) -> Option<GString>

Gets @self’s path.

Returns

@self’s path

pub fn same_site_policy(&mut self) -> SameSitePolicy

Returns the same-site policy for this cookie.

Returns

a #SoupSameSitePolicy

pub fn is_secure(&mut self) -> bool

Gets @self’s secure attribute.

Returns

@self’s secure attribute

pub fn value(&mut self) -> Option<GString>

Gets @self’s value.

Returns

@self’s value

pub fn set_domain(&mut self, domain: &str)

Sets @self’s domain to @domain.

domain

the new domain

pub fn set_expires(&mut self, expires: &DateTime)

Sets @self’s expiration time to @expires.

If @expires is None, @self will be a session cookie and will expire at the end of the client’s session.

(This sets the same property as set_max_age().)

expires

the new expiration time, or None

pub fn set_http_only(&mut self, http_only: bool)

Sets @self’s HttpOnly attribute to @http_only.

If true, @self will be marked as “http only”, meaning it should not be exposed to web page scripts or other untrusted code.

http_only

the new value for the HttpOnly attribute

pub fn set_max_age(&mut self, max_age: i32)

Sets @self’s max age to @max_age.

If @max_age is -1, the cookie is a session cookie, and will expire at the end of the client’s session. Otherwise, it is the number of seconds until the cookie expires. You can use the constants SOUP_COOKIE_MAX_AGE_ONE_HOUR, SOUP_COOKIE_MAX_AGE_ONE_DAY, SOUP_COOKIE_MAX_AGE_ONE_WEEK and SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (A value of 0 indicates that the cookie should be considered already-expired.)

This sets the same property as set_expires().

max_age

the new max age

pub fn set_name(&mut self, name: &str)

Sets @self’s name to @name.

name

the new name

pub fn set_path(&mut self, path: &str)

Sets @self’s path to @path.

path

the new path

pub fn set_same_site_policy(&mut self, policy: SameSitePolicy)

When used in conjunction with CookieJarExt::cookie_list_with_same_site_info() this sets the policy of when this cookie should be exposed.

policy

a #SoupSameSitePolicy

pub fn set_secure(&mut self, secure: bool)

Sets @self’s secure attribute to @secure.

If true, @self will only be transmitted from the client to the server over secure (https) connections.

secure

the new value for the secure attribute

pub fn set_value(&mut self, value: &str)

Sets @self’s value to @value.

value

the new value

pub fn to_cookie_header(&mut self) -> Option<GString>

Serializes @self in the format used by the Cookie header (ie, for returning a cookie from a Session to a server).

Returns

the header

pub fn to_set_cookie_header(&mut self) -> Option<GString>

Serializes @self in the format used by the Set-Cookie header.

i.e. for sending a cookie from a Server to a client.

Returns

the header

pub fn parse(header: &str, origin: Option<&Uri>) -> Option<Cookie>

Parses @header and returns a #SoupCookie.

If @header contains multiple cookies, only the first one will be parsed.

If @header does not have “path” or “domain” attributes, they will be defaulted from @origin. If @origin is None, path will default to “/”, but domain will be left as None. Note that this is not a valid state for a #SoupCookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

As of version 3.4.0 the default value of a cookie’s same-site-policy is SameSitePolicy::Lax.

header

a cookie string (eg, the value of a Set-Cookie header)

origin

origin of the cookie

Returns

a new #SoupCookie, or None if it could not be parsed, or contained an illegal “domain” attribute for a cookie originating from @origin.

Trait Implementations

impl Clone for Cookie

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cookie

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Cookie> for Value

fn from(o: Cookie) -> Self

Converts to this type from the input type.

impl HasParamSpec for Cookie

type ParamSpec = ParamSpecBoxed

type SetValue = Cookie

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, Cookie>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Cookie

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Cookie

fn cmp(&self, other: &Cookie) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Cookie

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Cookie

fn partial_cmp(&self, other: &Cookie) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Cookie

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Cookie