gi-soup-3.0.3: Libsoup bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Soup.Structs.Cookie

Description

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.

Synopsis

Exported types

newtype Cookie Source #

Memory-managed wrapper type.

Constructors

Cookie (ManagedPtr Cookie) 

Instances

Instances details
Eq Cookie Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

Methods

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

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

GBoxed Cookie Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

ManagedPtrNewtype Cookie Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

Methods

toManagedPtr :: Cookie -> ManagedPtr Cookie

TypedObject Cookie Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

Methods

glibType :: IO GType

HasParentTypes Cookie Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

IsGValue (Maybe Cookie) Source #

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

Instance details

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 Source # 
Instance details

Defined in GI.Soup.Structs.Cookie

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

Methods

appliesToUri

cookieAppliesToUri Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Cookie

Returns: a copy of cookie

Copies cookie.

domainMatches

cookieDomainMatches Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m () 

Frees cookie.

getDomain

cookieGetDomain Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's domain

Gets cookie's domain.

getExpires

cookieGetExpires Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Bool

Returns: cookie's HttpOnly attribute

Gets cookie's HttpOnly attribute.

getName

cookieGetName Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's name

Gets cookie's name.

getPath

cookieGetPath Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's path

Gets cookie's path.

getSameSitePolicy

cookieGetSameSitePolicy Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m SameSitePolicy

Returns: a SameSitePolicy

Returns the same-site policy for this cookie.

getSecure

cookieGetSecure Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Bool

Returns: cookie's secure attribute

Gets cookie's secure attribute.

getValue

cookieGetValue Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> m Text

Returns: cookie's value

Gets cookie's value.

new

cookieNew Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> Text

domain: the new domain

-> m () 

Sets cookie's domain to domain.

setExpires

cookieSetExpires Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> Text

name: the new name

-> m () 

Sets cookie's name to name.

setPath

cookieSetPath Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> Text

path: the new path

-> m () 

Sets cookie's path to path.

setSameSitePolicy

cookieSetSameSitePolicy Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Cookie

cookie: a Cookie

-> Text

value: the new value

-> m () 

Sets cookie's value to value.

toCookieHeader

cookieToCookieHeader Source #

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 Source #

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.