GI.Soup.Structs.Cookie

Implements HTTP cookies, as described by RFC 6265.

To have a [classsession] handle cookies for your appliction automatically, use a [classcookieJar].

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-Nothing if the cookie uses either the original "expires" attribute, or the newer "max-age" attribute. If expires is Nothing, it indicates that neither "expires" nor "max-age" was specified, and the cookie expires at the end of the session.

If httpOnly 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.

Exported types

newtype Cookie

Memory-managed wrapper type.

Constructors

Cookie (ManagedPtr Cookie)

Instances

Eq Cookie

Defined in GI.Soup.Structs.Cookie

Methods

(==) :: Cookie -> Cookie -> Bool

(/=) :: Cookie -> Cookie -> Bool

GBoxed Cookie

Defined in GI.Soup.Structs.Cookie

ManagedPtrNewtype Cookie

Defined in GI.Soup.Structs.Cookie

Methods

toManagedPtr :: Cookie -> ManagedPtr Cookie

TypedObject Cookie

Defined in GI.Soup.Structs.Cookie

Methods

glibType :: IO GType

HasParentTypes Cookie

Defined in GI.Soup.Structs.Cookie

IsGValue (Maybe Cookie)

Convert Cookie to and from GValue. See toGValue and fromGValue.

Defined in GI.Soup.Structs.Cookie

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Cookie -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Cookie)

type ParentTypes Cookie

Defined in GI.Soup.Structs.Cookie

type ParentTypes Cookie = '[] :: [Type]

Methods

Click to display all available methods, including inherited ones

Methods

appliesToUri, copy, domainMatches, equal, free, toCookieHeader, toSetCookieHeader.

Getters

getDomain, getExpires, getHttpOnly, getName, getPath, getSameSitePolicy, getSecure, getValue.

Setters

setDomain, setExpires, setHttpOnly, setMaxAge, setName, setPath, setSameSitePolicy, setSecure, setValue.

appliesToUri

cookieAppliesToUri

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Uri

uri: a Uri

-> m Bool

Returns: True if cookie should be sent to uri, False if not

Tests if cookie should be sent to uri.

(At the moment, this does not check that cookie'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.)

copy

cookieCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Cookie

Returns: a copy of cookie

Copies cookie.

domainMatches

cookieDomainMatches

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Text

host: a URI

-> m Bool

Returns: True if the domains match, False otherwise

Checks if the cookie's domain and host match.

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

equal

cookieEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie1: a Cookie

-> Cookie

cookie2: a Cookie

-> m Bool

Returns: whether the cookies are equal.

Tests if cookie1 and cookie2 are equal.

Note that currently, this does not check that the cookie domains match. This may change in the future.

free

cookieFree

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m ()

Frees cookie.

getDomain

cookieGetDomain

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's domain

Gets cookie's domain.

getExpires

cookieGetExpires

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a DateTime

-> m (Maybe DateTime)

Returns: cookie's expiration time, which is owned by cookie and should not be modified or freed.

Gets cookie's expiration time.

getHttpOnly

cookieGetHttpOnly

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Bool

Returns: cookie's HttpOnly attribute

Gets cookie's HttpOnly attribute.

getName

cookieGetName

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's name

Gets cookie's name.

getPath

cookieGetPath

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's path

Gets cookie's path.

getSameSitePolicy

cookieGetSameSitePolicy

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m SameSitePolicy

Returns: a SameSitePolicy

Returns the same-site policy for this cookie.

getSecure

cookieGetSecure

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Bool

Returns: cookie's secure attribute

Gets cookie's secure attribute.

getValue

cookieGetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's value

Gets cookie's value.

new

cookieNew

Arguments

:: (HasCallStack, MonadIO m)

=> Text

name: cookie name

-> Text

value: cookie value

-> Text

domain: cookie domain or hostname

-> Text

path: cookie path, or Nothing

-> Int32

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

-> m Cookie

Returns: a new Cookie.

Creates a new Cookie with the given attributes.

Use [methodcookie.set_secure] and [methodcookie.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.

maxAge 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 COOKIE_MAX_AGE_ONE_HOUR, COOKIE_MAX_AGE_ONE_DAY, COOKIE_MAX_AGE_ONE_WEEK and 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 [methodcookie.set_expires].)

As of version 3.4.0 the default value of a cookie's same-site-policy is SameSitePolicyLax.

parse

cookieParse

Arguments

:: (HasCallStack, MonadIO m)

=> Text

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

-> Maybe Uri

origin: origin of the cookie

-> m (Maybe Cookie)

Returns: a new Cookie, or Nothing if it could not be parsed, or contained an illegal "domain" attribute for a cookie originating from origin.

Parses header and returns a Cookie.

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 Nothing, path will default to "/", but domain will be left as Nothing. Note that this is not a valid state for a Cookie, 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 SameSitePolicyLax.

setDomain

cookieSetDomain

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Text

domain: the new domain

-> m ()

Sets cookie's domain to domain.

setExpires

cookieSetExpires

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> DateTime

expires: the new expiration time, or Nothing

-> m ()

Sets cookie's expiration time to expires.

If expires is Nothing, cookie will be a session cookie and will expire at the end of the client's session.

(This sets the same property as [methodcookie.set_max_age].)

setHttpOnly

cookieSetHttpOnly

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Bool

httpOnly: the new value for the HttpOnly attribute

-> m ()

Sets cookie's HttpOnly attribute to httpOnly.

If True, cookie will be marked as "http only", meaning it should not be exposed to web page scripts or other untrusted code.

setMaxAge

cookieSetMaxAge

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Int32

maxAge: the new max age

-> m ()

Sets cookie's max age to maxAge.

If maxAge 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 COOKIE_MAX_AGE_ONE_HOUR, COOKIE_MAX_AGE_ONE_DAY, COOKIE_MAX_AGE_ONE_WEEK and 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 [methodcookie.set_expires].

setName

cookieSetName

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Text

name: the new name

-> m ()

Sets cookie's name to name.

setPath

cookieSetPath

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Text

path: the new path

-> m ()

Sets cookie's path to path.

setSameSitePolicy

cookieSetSameSitePolicy

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> SameSitePolicy

policy: a SameSitePolicy

-> m ()

When used in conjunction with [methodcookieJar.get_cookie_list_with_same_site_info] this sets the policy of when this cookie should be exposed.

setSecure

cookieSetSecure

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Bool

secure: the new value for the secure attribute

-> m ()

Sets cookie's secure attribute to secure.

If True, cookie will only be transmitted from the client to the server over secure (https) connections.

setValue

cookieSetValue

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> Text

value: the new value

-> m ()

Sets cookie's value to value.

toCookieHeader

cookieToCookieHeader

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: the header

Serializes cookie in the format used by the Cookie header (ie, for returning a cookie from a [classsession] to a server).

toSetCookieHeader

cookieToSetCookieHeader

Arguments

:: (HasCallStack, MonadIO m)

=> Cookie

cookie: a Cookie

-> m Text

Returns: the header

Serializes cookie in the format used by the Set-Cookie header.

i.e. for sending a cookie from a [classserver] to a client.