GI.Soup.Structs.MessageBody

A Message request or response body.

Note that while length always reflects the full length of the message body, data is normally Nothing, and will only be filled in after messageBodyFlatten is called. For client-side messages, this automatically happens for the response body after it has been fully read, unless you set the MessageFlagsOverwriteChunks flags. Likewise, for server-side messages, the request body is automatically filled in after being read.

As an added bonus, when data is filled in, it is always terminated with a '\0' byte (which is not reflected in length).

Exported types

newtype MessageBody

Memory-managed wrapper type.

Constructors

MessageBody (ManagedPtr MessageBody)

Instances

BoxedObject MessageBody

Defined in GI.Soup.Structs.MessageBody

Methods

boxedType :: MessageBody -> IO GType

tag ~ AttrSet => Constructible MessageBody tag

Defined in GI.Soup.Structs.MessageBody

Methods

new :: MonadIO m => (ManagedPtr MessageBody -> MessageBody) -> [AttrOp MessageBody tag] -> m MessageBody

newZeroMessageBody :: MonadIO m => m MessageBody

Construct a MessageBody struct initialized to zero.

noMessageBody :: Maybe MessageBody

A convenience alias for Nothing :: Maybe MessageBody.

Methods

append

messageBodyAppend

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> ByteString

data: data to append

-> m ()

Appends length bytes from data to body.

This function is exactly equivalent to soup_message_body_append() with MemoryUseTake as second argument; it exists mainly for convenience and simplifying language bindings.

Since: 2.32

appendBuffer

messageBodyAppendBuffer

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> Buffer

buffer: a Buffer

-> m ()

Appends the data from buffer to body. (MessageBody uses SoupBuffers internally, so this is normally a constant-time operation that doesn't actually require copying the data in buffer.)

complete

messageBodyComplete

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> m ()

Tags body as being complete; Call this when using chunked encoding after you have appended the last chunk.

flatten

messageBodyFlatten

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> m Buffer

Returns: a Buffer containing the same data as body. (You must free this buffer if you do not want it.)

Fills in body's data field with a buffer containing all of the data in body (plus an additional '\0' byte not counted by body's length field).

free

messageBodyFree

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> m ()

Frees body. You will not normally need to use this, as Message frees its associated message bodies automatically.

getAccumulate

messageBodyGetAccumulate

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> m Bool

Returns: the accumulate flag for body.

Gets the accumulate flag on body; see messageBodySetAccumulate for details.

Since: 2.24

getChunk

messageBodyGetChunk

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> Int64

offset: an offset

-> m (Maybe Buffer)

Returns: a Buffer, or Nothing.

Gets a Buffer containing data from body starting at offset. The size of the returned chunk is unspecified. You can iterate through the entire body by first calling messageBodyGetChunk with an offset of 0, and then on each successive call, increment the offset by the length of the previously-returned chunk.

If offset is greater than or equal to the total length of body, then the return value depends on whether or not messageBodyComplete has been called or not; if it has, then messageBodyGetChunk will return a 0-length chunk (indicating the end of body). If it has not, then messageBodyGetChunk will return Nothing (indicating that body may still potentially have more data, but that data is not currently available).

gotChunk

messageBodyGotChunk

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> Buffer

chunk: a Buffer received from the network

-> m ()

Handles the MessageBody part of receiving a chunk of data from the network. Normally this means appending chunk to body, exactly as with messageBodyAppendBuffer, but if you have set body's accumulate flag to False, then that will not happen.

This is a low-level method which you should not normally need to use.

Since: 2.24

new

messageBodyNew

Arguments

:: (HasCallStack, MonadIO m)

=> m MessageBody

Returns: a new MessageBody.

Creates a new MessageBody. Message uses this internally; you will not normally need to call it yourself.

setAccumulate

messageBodySetAccumulate

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> Bool

accumulate: whether or not to accumulate body chunks in body

-> m ()

Sets or clears the accumulate flag on body. (The default value is True.) If set to False, body's data field will not be filled in after the body is fully sent/received, and the chunks that make up body may be discarded when they are no longer needed.

In particular, if you set this flag to False on an "incoming" message body (that is, the Message:response_body of a client-side message, or Message:request_body of a server-side message), this will cause each chunk of the body to be discarded after its corresponding Message::got_chunk signal is emitted. (This is equivalent to setting the deprecated MessageFlagsOverwriteChunks flag on the message.)

If you set this flag to False on the Message:response_body of a server-side message, it will cause each chunk of the body to be discarded after its corresponding Message::wrote_chunk signal is emitted.

If you set the flag to False on the Message:request_body of a client-side message, it will block the accumulation of chunks into body's data field, but it will not normally cause the chunks to be discarded after being written like in the server-side Message:response_body case, because the request body needs to be kept around in case the request needs to be sent a second time due to redirection or authentication. However, if you set the MessageFlagsCanRebuild flag on the message, then the chunks will be discarded, and you will be responsible for recreating the request body after the Message::restarted signal is emitted.

Since: 2.24

truncate

messageBodyTruncate

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> m ()

Deletes all of the data in body.

wroteChunk

messageBodyWroteChunk

Arguments

:: (HasCallStack, MonadIO m)

=> MessageBody

body: a MessageBody

-> Buffer

chunk: a Buffer returned from messageBodyGetChunk

-> m ()

Handles the MessageBody part of writing a chunk of data to the network. Normally this is a no-op, but if you have set body's accumulate flag to False, then this will cause chunk to be discarded to free up memory.

This is a low-level method which you should not need to use, and there are further restrictions on its proper use which are not documented here.

Since: 2.24

Properties

data

the data

clearMessageBodyData :: MonadIO m => MessageBody -> m ()

Set the value of the “data” field to Nothing. When overloading is enabled, this is equivalent to

clear #data

getMessageBodyData :: MonadIO m => MessageBody -> m (Maybe Text)

Get the value of the “data” field. When overloading is enabled, this is equivalent to

get messageBody #data

setMessageBodyData :: MonadIO m => MessageBody -> CString -> m ()

Set the value of the “data” field. When overloading is enabled, this is equivalent to

set messageBody [ #data := value ]

length

length of data

getMessageBodyLength :: MonadIO m => MessageBody -> m Int64

Get the value of the “length” field. When overloading is enabled, this is equivalent to

get messageBody #length

setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m ()

Set the value of the “length” field. When overloading is enabled, this is equivalent to

set messageBody [ #length := value ]