Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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
- newtype Cookie = Cookie (ManagedPtr Cookie)
- cookieAppliesToUri :: (HasCallStack, MonadIO m) => Cookie -> Uri -> m Bool
- cookieCopy :: (HasCallStack, MonadIO m) => Cookie -> m Cookie
- cookieDomainMatches :: (HasCallStack, MonadIO m) => Cookie -> Text -> m Bool
- cookieEqual :: (HasCallStack, MonadIO m) => Cookie -> Cookie -> m Bool
- cookieFree :: (HasCallStack, MonadIO m) => Cookie -> m ()
- cookieGetDomain :: (HasCallStack, MonadIO m) => Cookie -> m Text
- cookieGetExpires :: (HasCallStack, MonadIO m) => Cookie -> m (Maybe DateTime)
- cookieGetHttpOnly :: (HasCallStack, MonadIO m) => Cookie -> m Bool
- cookieGetName :: (HasCallStack, MonadIO m) => Cookie -> m Text
- cookieGetPath :: (HasCallStack, MonadIO m) => Cookie -> m Text
- cookieGetSameSitePolicy :: (HasCallStack, MonadIO m) => Cookie -> m SameSitePolicy
- cookieGetSecure :: (HasCallStack, MonadIO m) => Cookie -> m Bool
- cookieGetValue :: (HasCallStack, MonadIO m) => Cookie -> m Text
- cookieNew :: (HasCallStack, MonadIO m) => Text -> Text -> Text -> Text -> Int32 -> m Cookie
- cookieParse :: (HasCallStack, MonadIO m) => Text -> Maybe Uri -> m (Maybe Cookie)
- cookieSetDomain :: (HasCallStack, MonadIO m) => Cookie -> Text -> m ()
- cookieSetExpires :: (HasCallStack, MonadIO m) => Cookie -> DateTime -> m ()
- cookieSetHttpOnly :: (HasCallStack, MonadIO m) => Cookie -> Bool -> m ()
- cookieSetMaxAge :: (HasCallStack, MonadIO m) => Cookie -> Int32 -> m ()
- cookieSetName :: (HasCallStack, MonadIO m) => Cookie -> Text -> m ()
- cookieSetPath :: (HasCallStack, MonadIO m) => Cookie -> Text -> m ()
- cookieSetSameSitePolicy :: (HasCallStack, MonadIO m) => Cookie -> SameSitePolicy -> m ()
- cookieSetSecure :: (HasCallStack, MonadIO m) => Cookie -> Bool -> m ()
- cookieSetValue :: (HasCallStack, MonadIO m) => Cookie -> Text -> m ()
- cookieToCookieHeader :: (HasCallStack, MonadIO m) => Cookie -> m Text
- cookieToSetCookieHeader :: (HasCallStack, MonadIO m) => Cookie -> m Text
Exported types
Memory-managed wrapper type.
Instances
Eq Cookie Source # | |
GBoxed Cookie Source # | |
Defined in GI.Soup.Structs.Cookie | |
ManagedPtrNewtype Cookie Source # | |
Defined in GI.Soup.Structs.Cookie Methods toManagedPtr :: Cookie -> ManagedPtr Cookie | |
TypedObject Cookie Source # | |
Defined in GI.Soup.Structs.Cookie | |
HasParentTypes Cookie Source # | |
Defined in GI.Soup.Structs.Cookie | |
IsGValue (Maybe Cookie) Source # | Convert |
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 # | |
Defined in GI.Soup.Structs.Cookie |
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
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Cookie | Returns: a copy of |
Copies cookie
.
domainMatches
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m () |
Frees cookie
.
getDomain
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Text | Returns: |
Gets cookie
's domain.
getExpires
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m (Maybe DateTime) | Returns: |
Gets cookie
's expiration time.
getHttpOnly
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Bool | Returns: |
Gets cookie
's HttpOnly attribute.
getName
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Text | Returns: |
Gets cookie
's name.
getPath
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Text | Returns: |
Gets cookie
's path.
getSameSitePolicy
cookieGetSameSitePolicy Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m SameSitePolicy | Returns: a |
Returns the same-site policy for this cookie.
getSecure
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Bool | Returns: |
Gets cookie
's secure attribute.
getValue
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> m Text | Returns: |
Gets cookie
's value.
new
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Int32 |
|
-> m Cookie | Returns: a new |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Maybe Uri |
|
-> m (Maybe Cookie) | Returns: a new |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Text |
|
-> m () |
Sets cookie
's domain to domain
.
setExpires
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> DateTime |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Bool |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Int32 |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Text |
|
-> m () |
Sets cookie
's name to name
.
setPath
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Text |
|
-> m () |
Sets cookie
's path to path
.
setSameSitePolicy
cookieSetSameSitePolicy Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Bool |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Cookie |
|
-> Text |
|
-> m () |
Sets cookie
's value to value
.
toCookieHeader
Arguments
:: (HasCallStack, MonadIO m) | |
=> 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 |
|
-> 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.