Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
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
).
- newtype MessageBody = MessageBody (ManagedPtr MessageBody)
- newZeroMessageBody :: MonadIO m => m MessageBody
- noMessageBody :: Maybe MessageBody
- data MessageBodyAppendMethodInfo
- messageBodyAppend :: (HasCallStack, MonadIO m) => MessageBody -> ByteString -> m ()
- data MessageBodyAppendBufferMethodInfo
- messageBodyAppendBuffer :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- data MessageBodyCompleteMethodInfo
- messageBodyComplete :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- data MessageBodyFlattenMethodInfo
- messageBodyFlatten :: (HasCallStack, MonadIO m) => MessageBody -> m Buffer
- data MessageBodyFreeMethodInfo
- messageBodyFree :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- data MessageBodyGetAccumulateMethodInfo
- messageBodyGetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> m Bool
- data MessageBodyGetChunkMethodInfo
- messageBodyGetChunk :: (HasCallStack, MonadIO m) => MessageBody -> Int64 -> m (Maybe Buffer)
- data MessageBodyGotChunkMethodInfo
- messageBodyGotChunk :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- messageBodyNew :: (HasCallStack, MonadIO m) => m MessageBody
- data MessageBodySetAccumulateMethodInfo
- messageBodySetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> Bool -> m ()
- data MessageBodyTruncateMethodInfo
- messageBodyTruncate :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- data MessageBodyWroteChunkMethodInfo
- messageBodyWroteChunk :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- clearMessageBodyData :: MonadIO m => MessageBody -> m ()
- getMessageBodyData :: MonadIO m => MessageBody -> m (Maybe Text)
- messageBody_data :: AttrLabelProxy "data"
- setMessageBodyData :: MonadIO m => MessageBody -> CString -> m ()
- getMessageBodyLength :: MonadIO m => MessageBody -> m Int64
- messageBody_length :: AttrLabelProxy "length"
- setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m ()
Exported types
newtype MessageBody Source #
newZeroMessageBody :: MonadIO m => m MessageBody Source #
Construct a MessageBody
struct initialized to zero.
Methods
append
data MessageBodyAppendMethodInfo Source #
((~) * signature (ByteString -> m ()), MonadIO m) => MethodInfo * MessageBodyAppendMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> ByteString |
|
-> 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
data MessageBodyAppendBufferMethodInfo Source #
((~) * signature (Buffer -> m ()), MonadIO m) => MethodInfo * MessageBodyAppendBufferMethodInfo MessageBody signature Source # | |
messageBodyAppendBuffer Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> 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
data MessageBodyCompleteMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * MessageBodyCompleteMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Tags body
as being complete; Call this when using chunked encoding
after you have appended the last chunk.
flatten
data MessageBodyFlattenMethodInfo Source #
((~) * signature (m Buffer), MonadIO m) => MethodInfo * MessageBodyFlattenMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m Buffer | Returns: a |
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
data MessageBodyFreeMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * MessageBodyFreeMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Frees body
. You will not normally need to use this, as
Message
frees its associated message bodies automatically.
getAccumulate
data MessageBodyGetAccumulateMethodInfo Source #
((~) * signature (m Bool), MonadIO m) => MethodInfo * MessageBodyGetAccumulateMethodInfo MessageBody signature Source # | |
messageBodyGetAccumulate Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m Bool | Returns: the accumulate flag for |
Gets the accumulate flag on body
; see
messageBodySetAccumulate
for details.
Since: 2.24
getChunk
data MessageBodyGetChunkMethodInfo Source #
((~) * signature (Int64 -> m (Maybe Buffer)), MonadIO m) => MethodInfo * MessageBodyGetChunkMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Int64 |
|
-> m (Maybe Buffer) |
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
data MessageBodyGotChunkMethodInfo Source #
((~) * signature (Buffer -> m ()), MonadIO m) => MethodInfo * MessageBodyGotChunkMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Buffer |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> m MessageBody | Returns: a new |
Creates a new MessageBody
. Message
uses this internally; you
will not normally need to call it yourself.
setAccumulate
data MessageBodySetAccumulateMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m) => MethodInfo * MessageBodySetAccumulateMethodInfo MessageBody signature Source # | |
messageBodySetAccumulate Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Bool |
|
-> 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
data MessageBodyTruncateMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * MessageBodyTruncateMethodInfo MessageBody signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Deletes all of the data in body
.
wroteChunk
data MessageBodyWroteChunkMethodInfo Source #
((~) * signature (Buffer -> m ()), MonadIO m) => MethodInfo * MessageBodyWroteChunkMethodInfo MessageBody signature Source # | |
messageBodyWroteChunk Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Buffer |
|
-> 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
clearMessageBodyData :: MonadIO m => MessageBody -> m () Source #
getMessageBodyData :: MonadIO m => MessageBody -> m (Maybe Text) Source #
messageBody_data :: AttrLabelProxy "data" Source #
setMessageBodyData :: MonadIO m => MessageBody -> CString -> m () Source #
length
getMessageBodyLength :: MonadIO m => MessageBody -> m Int64 Source #
messageBody_length :: AttrLabelProxy "length" Source #
setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m () Source #