gi-soup-2.4.14: Libsoup bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Soup.Objects.Message

Contents

Description

Represents an HTTP message being sent or received.

statusCode will normally be a Status value, eg, StatusOk, though of course it might actually be an unknown status code. reasonPhrase is the actual text returned from the server, which may or may not correspond to the "standard" description of statusCode. At any rate, it is almost certainly not localized, and not very descriptive even if it is in the user's language; you should not use reasonPhrase in user-visible messages. Rather, you should look at statusCode, and determine an end-user-appropriate message based on that and on what you were trying to do.

As described in the MessageBody documentation, the requestBody and responseBody <literal>data</literal> fields will not necessarily be filled in at all times. When the body fields are filled in, they will be terminated with a '\0' byte (which is not included in the <literal>length</literal>), so you can use them as ordinary C strings (assuming that you know that the body doesn't have any other '\0' bytes).

For a client-side Message, requestBody's <literal>data</literal> is usually filled in right before libsoup writes the request to the network, but you should not count on this; use messageBodyFlatten if you want to ensure that <literal>data</literal> is filled in. If you are not using Request to read the response, then responseBody's <literal>data</literal> will be filled in before Message::finished is emitted. (If you are using Request, then the message body is not accumulated by default, so responseBody's <literal>data</literal> will always be Nothing.)

For a server-side Message, requestBody's data will be filled in before Message::got_body is emitted.

To prevent the data field from being filled in at all (eg, if you are handling the data from a Message::got_chunk, and so don't need to see it all at the end), call messageBodySetAccumulate on responseBody or requestBody as appropriate, passing False.

Synopsis

Exported types

Methods

contentSniffed

messageContentSniffed :: (HasCallStack, MonadIO m, IsMessage a) => a -> Text -> Map (Ptr ()) (Ptr ()) -> m () Source #

No description available in the introspection data.

disableFeature

messageDisableFeature Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> GType

featureType: the GType of a SessionFeature

-> m () 

This disables the actions of SessionFeature<!-- -->s with the given featureType (or a subclass of that type) on msg, so that msg is processed as though the feature(s) hadn't been added to the session. Eg, passing SOUP_TYPE_CONTENT_SNIFFER for featureType will disable Content-Type sniffing on the message.

You must call this before queueing msg on a session; calling it on a message that has already been queued is undefined. In particular, you cannot call this on a message that is being requeued after a redirect or authentication.

Since: 2.28

finished

messageFinished :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

getAddress

messageGetAddress Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m Address

Returns: the address msg's URI points to

Gets the address msg's URI points to. After first setting the URI on a message, this will be unresolved, although the message's session will resolve it before sending the message.

Since: 2.26

getFirstParty

messageGetFirstParty Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m URI

Returns: the msg's first party URI

Gets msg's first-party URI

Since: 2.30

getFlags

messageGetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m [MessageFlags]

Returns: the flags

Gets the flags on msg

getHttpVersion

messageGetHttpVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m HTTPVersion

Returns: the HTTP version

Gets the HTTP version of msg. This is the minimum of the version from the request and the version from the response.

getHttpsStatus

messageGetHttpsStatus Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m (Bool, TlsCertificate, [TlsCertificateFlags])

Returns: True if msg used/attempted https, False if not

If msg is using https (or attempted to use https but got StatusSslFailed), this retrieves the TlsCertificate associated with its connection, and the TlsCertificateFlags showing what problems, if any, have been found with that certificate.

<note><para>This is only meaningful with messages processed by a Session and is not useful for messages received by a Server</para></note>

Since: 2.34

getPriority

messageGetPriority Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m MessagePriority

Returns: the priority of the message.

Retrieves the MessagePriority. If not set this value defaults to SOUP_MESSAGE_PRIORITY_NORMAL.

Since: 2.44

getSoupRequest

messageGetSoupRequest Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m Request

Returns: msg's associated Request

If msg is associated with a Request, this returns that request. Otherwise it returns Nothing.

Since: 2.42

getUri

messageGetUri Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m URI

Returns: the URI msg is targeted for.

Gets msg's URI

gotBody

messageGotBody :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

gotChunk

messageGotChunk :: (HasCallStack, MonadIO m, IsMessage a) => a -> Buffer -> m () Source #

No description available in the introspection data.

gotHeaders

messageGotHeaders :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

gotInformational

messageGotInformational :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

isKeepalive

messageIsKeepalive Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> m Bool

Returns: True or False.

Determines whether or not msg's connection can be kept alive for further requests after processing msg, based on the HTTP version, Connection header, etc.

new

messageNew Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Text

method: the HTTP method for the created request

-> Text

uriString: the destination endpoint (as a string)

-> m (Maybe Message)

Returns: the new Message (or Nothing if uri could not be parsed).

Creates a new empty Message, which will connect to uri

newFromUri

messageNewFromUri Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> Text

method: the HTTP method for the created request

-> URI

uri: the destination endpoint (as a URI)

-> m Message

Returns: the new Message

Creates a new empty Message, which will connect to uri

restarted

messageRestarted :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

setChunkAllocator

messageSetChunkAllocator Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> ChunkAllocator

allocator: the chunk allocator callback

-> m () 

Deprecated: Request provides a much simpler API that lets youread the response directly into your own buffers without needing tomess with callbacks, pausing/unpausing, etc.

Sets an alternate chunk-allocation function to use when reading msg's body when using the traditional (ie, non-Request<!-- -->-based) API. Every time data is available to read, libsoup will call allocator, which should return a Buffer. (See ChunkAllocator for additional details.) Libsoup will then read data from the network into that buffer, and update the buffer's <literal>length</literal> to indicate how much data it read.

Generally, a custom chunk allocator would be used in conjunction with messageBodySetAccumulate False and Message::got_chunk, as part of a strategy to avoid unnecessary copying of data. However, you cannot assume that every call to the allocator will be followed by a call to your Message::got_chunk handler; if an I/O error occurs, then the buffer will be unreffed without ever having been used. If your buffer-allocation strategy requires special cleanup, use bufferNewWithOwner rather than doing the cleanup from the Message::got_chunk handler.

The other thing to remember when using non-accumulating message bodies is that the buffer passed to the Message::got_chunk handler will be unreffed after the handler returns, just as it would be in the non-custom-allocated case. If you want to hand the chunk data off to some other part of your program to use later, you'll need to ref the Buffer (or its owner, in the bufferNewWithOwner case) to ensure that the data remains valid.

setFirstParty

messageSetFirstParty Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> URI

firstParty: the URI for the msg's first party

-> m () 

Sets firstParty as the main document URI for msg. For details of when and how this is used refer to the documentation for CookieJarAcceptPolicy.

Since: 2.30

setFlags

messageSetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> [MessageFlags]

flags: a set of MessageFlags values

-> m () 

Sets the specified flags on msg.

setHttpVersion

messageSetHttpVersion Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> HTTPVersion

version: the HTTP version

-> m () 

Sets the HTTP version on msg. The default version is HTTPVersionHttp11. Setting it to HTTPVersionHttp10 will prevent certain functionality from being used.

setPriority

messageSetPriority Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> MessagePriority

priority: the MessagePriority

-> m () 

Sets the priority of a message. Note that this won't have any effect unless used before the message is added to the session's message processing queue.

The message will be placed just before any other previously added message with lower priority (messages with the same priority are processed on a FIFO basis).

Setting priorities does not currently work with SessionSync (or with synchronous messages on a plain Session) because in the synchronous/blocking case, priority ends up being determined semi-randomly by thread scheduling.

Since: 2.44

setRedirect

messageSetRedirect Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> Word32

statusCode: a 3xx status code

-> Text

redirectUri: the URI to redirect msg to

-> m () 

Sets msg's status_code to statusCode and adds a Location header pointing to redirectUri. Use this from a Server when you want to redirect the client to another URI.

redirectUri can be a relative URI, in which case it is interpreted relative to msg's current URI. In particular, if redirectUri is just a path, it will replace the path <emphasis>and query</emphasis> of msg's URI.

Since: 2.38

setRequest

messageSetRequest Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: the message

-> Maybe Text

contentType: MIME Content-Type of the body

-> MemoryUse

reqUse: a MemoryUse describing how to handle reqBody

-> Maybe ByteString

reqBody: a data buffer containing the body of the message request.

-> m () 

Convenience function to set the request body of a Message. If contentType is Nothing, the request body must be empty as well.

setResponse

messageSetResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: the message

-> Maybe Text

contentType: MIME Content-Type of the body

-> MemoryUse

respUse: a MemoryUse describing how to handle respBody

-> Maybe ByteString

respBody: a data buffer containing the body of the message response.

-> m () 

Convenience function to set the response body of a Message. If contentType is Nothing, the response body must be empty as well.

setStatus

messageSetStatus Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> Word32

statusCode: an HTTP status code

-> m () 

Sets msg's status code to statusCode. If statusCode is a known value, it will also set msg's reason_phrase.

setStatusFull

messageSetStatusFull Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> Word32

statusCode: an HTTP status code

-> Text

reasonPhrase: a description of the status

-> m () 

Sets msg's status code and reason phrase.

setUri

messageSetUri Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a) 
=> a

msg: a Message

-> URI

uri: the new URI

-> m () 

Sets msg's URI to uri. If msg has already been sent and you want to re-send it with the new URI, you need to call sessionRequeueMessage.

starting

messageStarting :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

wroteBody

messageWroteBody :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

wroteBodyData

messageWroteBodyData :: (HasCallStack, MonadIO m, IsMessage a) => a -> Buffer -> m () Source #

No description available in the introspection data.

wroteChunk

messageWroteChunk :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

wroteHeaders

messageWroteHeaders :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

wroteInformational

messageWroteInformational :: (HasCallStack, MonadIO m, IsMessage a) => a -> m () Source #

No description available in the introspection data.

Properties

firstParty

setMessageFirstParty :: (MonadIO m, IsMessage o) => o -> URI -> m () Source #

flags

httpVersion

method

setMessageMethod :: (MonadIO m, IsMessage o) => o -> Text -> m () Source #

priority

reasonPhrase

requestBody

requestBodyData

requestHeaders

responseBody

responseBodyData

responseHeaders

serverSide

statusCode

tlsCertificate

tlsErrors

uri

setMessageUri :: (MonadIO m, IsMessage o) => o -> URI -> m () Source #

Signals

contentSniffed

finished

type C_MessageFinishedCallback = Ptr () -> Ptr () -> IO () Source #

gotBody

type C_MessageGotBodyCallback = Ptr () -> Ptr () -> IO () Source #

gotChunk

gotHeaders

gotInformational

networkEvent

restarted

starting

type C_MessageStartingCallback = Ptr () -> Ptr () -> IO () Source #

wroteBody

wroteBodyData

wroteChunk

wroteHeaders

wroteInformational