Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
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
).
Synopsis
- newtype MessageBody = MessageBody (ManagedPtr MessageBody)
- newZeroMessageBody :: MonadIO m => m MessageBody
- noMessageBody :: Maybe MessageBody
- messageBodyAppend :: (HasCallStack, MonadIO m) => MessageBody -> ByteString -> m ()
- messageBodyAppendBuffer :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- messageBodyComplete :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyFlatten :: (HasCallStack, MonadIO m) => MessageBody -> m Buffer
- messageBodyFree :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyGetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> m Bool
- messageBodyGetChunk :: (HasCallStack, MonadIO m) => MessageBody -> Int64 -> m (Maybe Buffer)
- messageBodyGotChunk :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- messageBodyNew :: (HasCallStack, MonadIO m) => m MessageBody
- messageBodySetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> Bool -> m ()
- messageBodyTruncate :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyWroteChunk :: (HasCallStack, MonadIO m) => MessageBody -> Buffer -> m ()
- clearMessageBodyData :: MonadIO m => MessageBody -> m ()
- getMessageBodyData :: MonadIO m => MessageBody -> m (Maybe Text)
- setMessageBodyData :: MonadIO m => MessageBody -> CString -> m ()
- getMessageBodyLength :: MonadIO m => MessageBody -> m Int64
- setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m ()
Exported types
newtype MessageBody Source #
Memory-managed wrapper type.
Instances
BoxedObject MessageBody Source # | |
Defined in GI.Soup.Structs.MessageBody boxedType :: MessageBody -> IO GType # | |
tag ~ AttrSet => Constructible MessageBody tag Source # | |
Defined in GI.Soup.Structs.MessageBody new :: MonadIO m => (ManagedPtr MessageBody -> MessageBody) -> [AttrOp MessageBody tag] -> m MessageBody # |
newZeroMessageBody :: MonadIO m => m MessageBody Source #
Construct a MessageBody
struct initialized to zero.
noMessageBody :: Maybe MessageBody Source #
A convenience alias for Nothing
:: Maybe
MessageBody
.
Methods
append
:: (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
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
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Tags body
as being complete; Call this when using chunked encoding
after you have appended the last chunk.
flatten
:: (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
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Frees body
. You will not normally need to use this, as
Message
frees its associated message bodies automatically.
getAccumulate
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
:: (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
:: (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
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
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Deletes all of the data in body
.
wroteChunk
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
the data
clearMessageBodyData :: MonadIO m => MessageBody -> m () Source #
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) Source #
Get the value of the “data
” field.
When overloading is enabled, this is equivalent to
get
messageBody #data
setMessageBodyData :: MonadIO m => MessageBody -> CString -> m () Source #
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 Source #
Get the value of the “length
” field.
When overloading is enabled, this is equivalent to
get
messageBody #length
setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m () Source #
Set the value of the “length
” field.
When overloading is enabled, this is equivalent to
set
messageBody [ #length:=
value ]