GI.Soup.Structs.MessageHeaders

The HTTP message headers associated with a request or response.

Exported types

newtype MessageHeaders

Memory-managed wrapper type.

Constructors

MessageHeaders (ManagedPtr MessageHeaders)

Instances

Eq MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

Methods

(==) :: MessageHeaders -> MessageHeaders -> Bool

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

GBoxed MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

ManagedPtrNewtype MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

Methods

toManagedPtr :: MessageHeaders -> ManagedPtr MessageHeaders

TypedObject MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

Methods

glibType :: IO GType

HasParentTypes MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

IsGValue (Maybe MessageHeaders)

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

Defined in GI.Soup.Structs.MessageHeaders

Methods

gvalueGType_ :: IO GType

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

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

type ParentTypes MessageHeaders

Defined in GI.Soup.Structs.MessageHeaders

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

Methods

Click to display all available methods, including inherited ones

Methods

append, cleanConnectionHeaders, clear, foreach, free, freeRanges, get, headerContains, headerEquals, remove, replace.

Getters

getContentDisposition, getContentLength, getContentRange, getContentType, getEncoding, getExpectations, getHeadersType, getList, getOne, getRanges.

Setters

setContentDisposition, setContentLength, setContentRange, setContentType, setEncoding, setExpectations, setRange, setRanges.

append

messageHeadersAppend

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: the header name to add

-> Text

value: the new value of name

-> 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 messageHeadersReplace.)

The caller is expected to make sure that name and value are syntactically correct.

cleanConnectionHeaders

messageHeadersCleanConnectionHeaders

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m ()

Removes all the headers listed in the Connection header.

Since: 2.36

clear

messageHeadersClear

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m ()

Clears hdrs.

foreach

messageHeadersForeach

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> MessageHeadersForeachFunc

func: callback function to run for each header

-> m ()

Calls func once for each header value in hdrs.

Beware that unlike messageHeadersGet, 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 messageHeadersAppend 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.

free

messageHeadersFree

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m ()

Frees hdrs.

freeRanges

messageHeadersFreeRanges

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Range

ranges: an array of Range

-> m ()

Frees the array of ranges returned from messageHeadersGetRanges.

Since: 2.26

get

messageHeadersGet

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: header name

-> m (Maybe Text)

Returns: as with messageHeadersGetList.

Deprecated: Use messageHeadersGetOne ormessageHeadersGetList instead.

Gets the value of header name in hdrs.

This method was supposed to work correctly for both single-valued and list-valued headers, but because some HTTP clients/servers mistakenly send multiple copies of headers that are supposed to be single-valued, it sometimes returns incorrect results. To fix this, the methods messageHeadersGetOne and messageHeadersGetList were introduced, so callers can explicitly state which behavior they are expecting.

getContentDisposition

messageHeadersGetContentDisposition

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m (Bool, Text, Map Text Text)

Returns: True if hdrs contains a "Content-Disposition" header, False if not (in which case *disposition and *params will be unchanged).

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 Multipart and the associated form methods.

Since: 2.26

getContentLength

messageHeadersGetContentLength

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m Int64

Returns: the message body length declared by hdrs.

Gets the message body length that hdrs declare. This will only be non-0 if messageHeadersGetEncoding returns EncodingContentLength.

getContentRange

messageHeadersGetContentRange

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m (Bool, Int64, Int64, Int64)

Returns: True if hdrs contained a "Content-Range" header containing a byte range which could be parsed, False otherwise.

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.

Since: 2.26

getContentType

messageHeadersGetContentType

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m (Maybe Text, Map Text Text)

Returns: a string with the value of the "Content-Type" header or Nothing if hdrs does not contain that header or it cannot be parsed (in which case *params will be unchanged).

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.

Since: 2.26

getEncoding

messageHeadersGetEncoding

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m Encoding

Returns: the encoding declared by hdrs.

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

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m [Expectation]

Returns: the contents of hdrs's "Expect" header

Gets the expectations declared by hdrs's "Expect" header. Currently this will either be ExpectationContinue or ExpectationUnrecognized.

getHeadersType

messageHeadersGetHeadersType

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> m MessageHeadersType

Returns: the header's type.

Gets the type of headers.

Since: 2.50

getList

messageHeadersGetList

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: header name

-> m (Maybe Text)

Returns: the header's value or Nothing if not found.

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 messageHeadersGetOne.

If name appears multiple times in hdrs, messageHeadersGetList 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.

Since: 2.28

getOne

messageHeadersGetOne

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: header name

-> m (Maybe Text)

Returns: the header's value or Nothing if not found.

Gets the value of header name in hdrs. Use this for headers whose values are <emphasis>not</emphasis> comma-delimited lists, and which therefore can only appear at most once in the headers. For list-valued headers, use messageHeadersGetList.

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.)

Since: 2.28

getRanges

messageHeadersGetRanges

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Int64

totalLength: the total_length of the response body

-> m (Bool, [Range])

Returns: True if hdrs contained a syntactically-valid "Range" header, False otherwise (in which case range and length will not be set).

Parses hdrs's Range header and returns an array of the requested byte ranges. The returned array must be freed with messageHeadersFreeRanges.

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 Range, 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.

<note><para> 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. </para></note>

Since: 2.26

headerContains

messageHeadersHeaderContains

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: header name

-> Text

token: token to look for

-> m Bool

Returns: True if the header is present and contains token, False otherwise.

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 headerContains on its value.)

Since: 2.50

headerEquals

messageHeadersHeaderEquals

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: header name

-> Text

value: expected value

-> m Bool

Returns: True if the header is present and its value is value, False otherwise.

Checks whether the header name is present in hdrs and is (case-insensitively) equal to value.

Since: 2.50

new

messageHeadersNew

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeadersType

type: the type of headers

-> m MessageHeaders

Returns: a new MessageHeaders

Creates a MessageHeaders. (tMessage does this automatically for its own headers. You would only need to use this method if you are manually parsing or generating message headers.)

remove

messageHeadersRemove

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: the header name to remove

-> m ()

Removes name from hdrs. If there are multiple values for name, they are all removed.

replace

messageHeadersReplace

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

name: the header name to replace

-> Text

value: the new value of name

-> m ()

Replaces the value of the header name in hdrs with value. (See also messageHeadersAppend.)

The caller is expected to make sure that name and value are syntactically correct.

setContentDisposition

messageHeadersSetContentDisposition

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

disposition: the disposition-type

-> Maybe (Map Text Text)

params: additional parameters, or Nothing

-> m ()

Sets the "Content-Disposition" header in hdrs to disposition, optionally with additional parameters specified in params.

See messageHeadersGetContentDisposition for a discussion of how Content-Disposition is used in HTTP.

Since: 2.26

setContentLength

messageHeadersSetContentLength

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Int64

contentLength: the message body length

-> 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 messageHeadersSetContentLength 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

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Int64

start: the start of the range

-> Int64

end: the end of the range

-> Int64

totalLength: the total length of the resource, or -1 if unknown

-> 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.)

<note><para> Server has built-in handling for range requests, and you do not normally need to call this function youself. See messageHeadersGetRanges for more details. </para></note>

Since: 2.26

setContentType

messageHeadersSetContentType

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Text

contentType: the MIME type

-> Maybe (Map Text Text)

params: additional parameters, or Nothing

-> m ()

Sets the "Content-Type" header in hdrs to contentType, optionally with additional parameters specified in params.

Since: 2.26

setEncoding

messageHeadersSetEncoding

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Encoding

encoding: a 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

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> [Expectation]

expectations: the expectations to set

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

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Int64

start: the start of the range to request

-> Int64

end: the end of the range to request

-> m ()

Sets hdrs's Range header to request the indicated range. start and end are interpreted as in a Range.

If you need to request multiple ranges, use messageHeadersSetRanges.

Since: 2.26

setRanges

messageHeadersSetRanges

Arguments

:: (HasCallStack, MonadIO m)

=> MessageHeaders

hdrs: a MessageHeaders

-> Range

ranges: an array of Range

-> Int32

length: the length of range

-> m ()

Sets hdrs's Range header to request the indicated ranges. (If you only want to request a single range, you can use messageHeadersSetRange.)

Since: 2.26