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 |
- Exported types
- Methods
- append
- cleanConnectionHeaders
- clear
- foreach
- freeRanges
- getContentDisposition
- getContentLength
- getContentRange
- getContentType
- getEncoding
- getExpectations
- getHeadersType
- getList
- getOne
- getRanges
- headerContains
- headerEquals
- new
- ref
- remove
- replace
- setContentDisposition
- setContentLength
- setContentRange
- setContentType
- setEncoding
- setExpectations
- setRange
- setRanges
- unref
The HTTP message headers associated with a request or response.
Synopsis
- newtype MessageHeaders = MessageHeaders (ManagedPtr MessageHeaders)
- messageHeadersAppend :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Text -> m ()
- messageHeadersCleanConnectionHeaders :: (HasCallStack, MonadIO m) => MessageHeaders -> m ()
- messageHeadersClear :: (HasCallStack, MonadIO m) => MessageHeaders -> m ()
- messageHeadersForeach :: (HasCallStack, MonadIO m) => MessageHeaders -> MessageHeadersForeachFunc -> m ()
- messageHeadersFreeRanges :: (HasCallStack, MonadIO m) => MessageHeaders -> Range -> m ()
- messageHeadersGetContentDisposition :: (HasCallStack, MonadIO m) => MessageHeaders -> m (Bool, Text, Map Text Text)
- messageHeadersGetContentLength :: (HasCallStack, MonadIO m) => MessageHeaders -> m Int64
- messageHeadersGetContentRange :: (HasCallStack, MonadIO m) => MessageHeaders -> m (Bool, Int64, Int64, Int64)
- messageHeadersGetContentType :: (HasCallStack, MonadIO m) => MessageHeaders -> m (Maybe Text, Map Text Text)
- messageHeadersGetEncoding :: (HasCallStack, MonadIO m) => MessageHeaders -> m Encoding
- messageHeadersGetExpectations :: (HasCallStack, MonadIO m) => MessageHeaders -> m [Expectation]
- messageHeadersGetHeadersType :: (HasCallStack, MonadIO m) => MessageHeaders -> m MessageHeadersType
- messageHeadersGetList :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> m (Maybe Text)
- messageHeadersGetOne :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> m (Maybe Text)
- messageHeadersGetRanges :: (HasCallStack, MonadIO m) => MessageHeaders -> Int64 -> m (Bool, [Range])
- messageHeadersHeaderContains :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Text -> m Bool
- messageHeadersHeaderEquals :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Text -> m Bool
- messageHeadersNew :: (HasCallStack, MonadIO m) => MessageHeadersType -> m MessageHeaders
- messageHeadersRef :: (HasCallStack, MonadIO m) => MessageHeaders -> m MessageHeaders
- messageHeadersRemove :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> m ()
- messageHeadersReplace :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Text -> m ()
- messageHeadersSetContentDisposition :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Maybe (Map Text Text) -> m ()
- messageHeadersSetContentLength :: (HasCallStack, MonadIO m) => MessageHeaders -> Int64 -> m ()
- messageHeadersSetContentRange :: (HasCallStack, MonadIO m) => MessageHeaders -> Int64 -> Int64 -> Int64 -> m ()
- messageHeadersSetContentType :: (HasCallStack, MonadIO m) => MessageHeaders -> Text -> Maybe (Map Text Text) -> m ()
- messageHeadersSetEncoding :: (HasCallStack, MonadIO m) => MessageHeaders -> Encoding -> m ()
- messageHeadersSetExpectations :: (HasCallStack, MonadIO m) => MessageHeaders -> [Expectation] -> m ()
- messageHeadersSetRange :: (HasCallStack, MonadIO m) => MessageHeaders -> Int64 -> Int64 -> m ()
- messageHeadersSetRanges :: (HasCallStack, MonadIO m) => MessageHeaders -> Range -> Int32 -> m ()
- messageHeadersUnref :: (HasCallStack, MonadIO m) => MessageHeaders -> m ()
Exported types
newtype MessageHeaders Source #
Memory-managed wrapper type.
MessageHeaders (ManagedPtr MessageHeaders) |
Instances
Eq MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders (==) :: MessageHeaders -> MessageHeaders -> Bool # (/=) :: MessageHeaders -> MessageHeaders -> Bool # | |
GBoxed MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders | |
ManagedPtrNewtype MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders toManagedPtr :: MessageHeaders -> ManagedPtr MessageHeaders | |
TypedObject MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders | |
HasParentTypes MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders | |
IsGValue (Maybe MessageHeaders) Source # | Convert |
Defined in GI.Soup.Structs.MessageHeaders gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe MessageHeaders -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe MessageHeaders) | |
type ParentTypes MessageHeaders Source # | |
Defined in GI.Soup.Structs.MessageHeaders |
Methods
Click to display all available methods, including inherited ones
Methods
append, cleanConnectionHeaders, clear, foreach, freeRanges, headerContains, headerEquals, ref, remove, replace, unref.
Getters
getContentDisposition, getContentLength, getContentRange, getContentType, getEncoding, getExpectations, getHeadersType, getList, getOne, getRanges.
Setters
setContentDisposition, setContentLength, setContentRange, setContentType, setEncoding, setExpectations, setRange, setRanges.
append
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Text |
|
-> m () |
Appends a new header with name name
and value value
to hdrs
.
(If there is an existing header with name name
, then this creates a second
one, which is only allowed for list-valued headers; see also
[methodmessageHeaders
.replace].)
The caller is expected to make sure that name
and value
are
syntactically correct.
cleanConnectionHeaders
messageHeadersCleanConnectionHeaders Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m () |
Removes all the headers listed in the Connection header.
clear
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m () |
Clears hdrs
.
foreach
messageHeadersForeach Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> MessageHeadersForeachFunc |
|
-> m () |
Calls func
once for each header value in hdrs
.
Beware that unlike [methodmessageHeaders
.get_list], this processes the
headers in exactly the way they were added, rather than
concatenating multiple same-named headers into a single value.
(This is intentional; it ensures that if you call
[methodmessageHeaders
.append] multiple times with the same name,
then the I/O code will output multiple copies of the header when
sending the message to the remote implementation, which may be
required for interoperability in some cases.)
You may not modify the headers from func
.
freeRanges
messageHeadersFreeRanges Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Range |
|
-> m () |
Frees the array of ranges returned from [methodmessageHeaders
.get_ranges].
getContentDisposition
messageHeadersGetContentDisposition Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m (Bool, Text, Map Text Text) | Returns: |
Looks up the "Content-Disposition" header in hdrs
, parses it, and
returns its value in *disposition
and *params
.
params
can be Nothing
if you are only interested in the disposition-type.
In HTTP, the most common use of this header is to set a
disposition-type of "attachment", to suggest to the browser that a
response should be saved to disk rather than displayed in the
browser. If params
contains a "filename" parameter, this is a
suggestion of a filename to use. (If the parameter value in the
header contains an absolute or relative path, libsoup will truncate
it down to just the final path component, so you do not need to
test this yourself.)
Content-Disposition is also used in "multipart/form-data", however
this is handled automatically by [structmultipart
] and the associated
form methods.
getContentLength
messageHeadersGetContentLength Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m Int64 | Returns: the message body length declared by |
Gets the message body length that hdrs
declare.
This will only be non-0 if [methodmessageHeaders
.get_encoding] returns
EncodingContentLength
.
getContentRange
messageHeadersGetContentRange Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m (Bool, Int64, Int64, Int64) | Returns: |
Parses hdrs
's Content-Range header and returns it in start
,
end
, and totalLength
. If the total length field in the header
was specified as "*", then totalLength
will be set to -1.
getContentType
messageHeadersGetContentType Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m (Maybe Text, Map Text Text) | Returns: a string with the value of the
"Content-Type" header or |
Looks up the "Content-Type" header in hdrs
, parses it, and returns
its value in *contentType
and *params
.
params
can be Nothing
if you are only interested in the content type itself.
getEncoding
messageHeadersGetEncoding Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m Encoding | Returns: the encoding declared by |
Gets the message body encoding that hdrs
declare.
This may not always correspond to the encoding used on the wire; eg, a HEAD response may declare a Content-Length or Transfer-Encoding, but it will never actually include a body.
getExpectations
messageHeadersGetExpectations Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m [Expectation] | Returns: the contents of |
Gets the expectations declared by hdrs
's "Expect" header.
Currently this will either be ExpectationContinue
or
ExpectationUnrecognized
.
getHeadersType
messageHeadersGetHeadersType Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m MessageHeadersType | Returns: the header's type. |
Gets the type of headers.
getList
messageHeadersGetList Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> m (Maybe Text) | Returns: the header's value or |
Gets the value of header name
in hdrs
.
Use this for headers whose values are comma-delimited lists, and which are
therefore allowed to appear multiple times in the headers. For
non-list-valued headers, use [methodmessageHeaders
.get_one].
If name
appears multiple times in hdrs
,
[methodmessageHeaders
.get_list] will concatenate all of the values
together, separated by commas. This is sometimes awkward to parse
(eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal
with it anyway, because the HTTP spec explicitly states that this
transformation is allowed, and so an upstream proxy could do the
same thing.
getOne
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> m (Maybe Text) | Returns: the header's value or |
Gets the value of header name
in hdrs
.
Use this for headers whose values are *not* comma-delimited lists, and which
therefore can only appear at most once in the headers. For list-valued
headers, use [methodmessageHeaders
.get_list].
If hdrs
does erroneously contain multiple copies of the header, it
is not defined which one will be returned. (Ideally, it will return
whichever one makes libsoup most compatible with other HTTP
implementations.)
getRanges
messageHeadersGetRanges Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Int64 |
|
-> m (Bool, [Range]) | Returns: |
Parses hdrs
's Range header and returns an array of the requested
byte ranges.
The returned array must be freed with [methodmessageHeaders
.free_ranges].
If totalLength
is non-0, its value will be used to adjust the
returned ranges to have explicit start and end values, and the
returned ranges will be sorted and non-overlapping. If
totalLength
is 0, then some ranges may have an end value of -1,
as described under [structrange
], and some of the ranges may be
redundant.
Beware that even if given a totalLength
, this function does not
check that the ranges are satisfiable.
Server
has built-in handling for range requests. If your
server handler returns a StatusOk
response containing the
complete response body (rather than pausing the message and
returning some of the response body later), and there is a Range
header in the request, then libsoup will automatically convert the
response to a StatusPartialContent
response containing only
the range(s) requested by the client.
The only time you need to process the Range header yourself is if either you need to stream the response body rather than returning it all at once, or you do not already have the complete response body available, and only want to generate the parts that were actually requested by the client.
headerContains
messageHeadersHeaderContains Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Text |
|
-> m Bool | Returns: |
Checks whether the list-valued header name
is present in hdrs
,
and contains a case-insensitive match for token
.
(If name
is present in hdrs
, then this is equivalent to calling
[funcheaderContains
] on its value.)
headerEquals
messageHeadersHeaderEquals Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Text |
|
-> m Bool | Returns: |
Checks whether the header name
is present in hdrs
and is
(case-insensitively) equal to value
.
new
:: (HasCallStack, MonadIO m) | |
=> MessageHeadersType |
|
-> m MessageHeaders | Returns: a new |
Creates a MessageHeaders
.
([classmessage
] does this automatically for its own headers. You would only
need to use this method if you are manually parsing or generating message
headers.)
ref
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m MessageHeaders | Returns: the passed in |
Atomically increments the reference count of hdrs
by one.
remove
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> m () |
Removes name
from hdrs
.
If there are multiple values for name
, they are all removed.
replace
messageHeadersReplace Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Text |
|
-> m () |
Replaces the value of the header name
in hdrs
with value
.
See also [methodmessageHeaders
.append].
The caller is expected to make sure that name
and value
are
syntactically correct.
setContentDisposition
messageHeadersSetContentDisposition Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Maybe (Map Text Text) |
|
-> m () |
Sets the "Content-Disposition" header in hdrs
to disposition
,
optionally with additional parameters specified in params
.
See [methodmessageHeaders
.get_content_disposition] for a discussion
of how Content-Disposition is used in HTTP.
setContentLength
messageHeadersSetContentLength Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Int64 |
|
-> m () |
Sets the message body length that hdrs
will declare, and sets
hdrs
's encoding to EncodingContentLength
.
You do not normally need to call this; if hdrs
is set to use
Content-Length encoding, libsoup will automatically set its
Content-Length header for you immediately before sending the
headers. One situation in which this method is useful is when
generating the response to a HEAD request; Calling
[methodmessageHeaders
.set_content_length] allows you to put the
correct content length into the response without needing to waste
memory by filling in a response body which won't actually be sent.
setContentRange
messageHeadersSetContentRange Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Int64 |
|
-> Int64 |
|
-> Int64 |
|
-> m () |
Sets hdrs
's Content-Range header according to the given values.
(Note that totalLength
is the total length of the entire resource
that this is a range of, not simply end
- start
+ 1.)
- class
server
- has built-in handling for range requests, and you do not normally need to call this function youself. See
- method
messageHeaders
.get_ranges - for more details.
setContentType
messageHeadersSetContentType Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Text |
|
-> Maybe (Map Text Text) |
|
-> m () |
Sets the "Content-Type" header in hdrs
to contentType
.
Accepts additional parameters specified in params
.
setEncoding
messageHeadersSetEncoding Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Encoding |
|
-> m () |
Sets the message body encoding that hdrs
will declare.
In particular, you should use this if you are going to send a request or response in chunked encoding.
setExpectations
messageHeadersSetExpectations Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> [Expectation] |
|
-> m () |
Sets hdrs
's "Expect" header according to expectations
.
Currently ExpectationContinue
is the only known expectation
value. You should set this value on a request if you are sending a
large message body (eg, via POST or PUT), and want to give the
server a chance to reject the request after seeing just the headers
(eg, because it will require authentication before allowing you to
post, or because you're POSTing to a URL that doesn't exist). This
saves you from having to transmit the large request body when the
server is just going to ignore it anyway.
setRange
messageHeadersSetRange Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Int64 |
|
-> Int64 |
|
-> m () |
Sets hdrs
's Range header to request the indicated range.
start
and end
are interpreted as in a [structrange
].
If you need to request multiple ranges, use
[methodmessageHeaders
.set_ranges].
setRanges
messageHeadersSetRanges Source #
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> Range |
|
-> Int32 |
|
-> m () |
Sets hdrs
's Range header to request the indicated ranges.
If you only want to request a single range, you can use
[methodmessageHeaders
.set_range].
unref
:: (HasCallStack, MonadIO m) | |
=> MessageHeaders |
|
-> m () |
Atomically decrements the reference count of hdrs
by one.
When the reference count reaches zero, the resources allocated by
hdrs
are freed