Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
MessageBody
represents the request or response body of a
[classmessage
].
Note that while length
always reflects the full length of the
message body, data
is normally Nothing
, and will only be filled in
after [methodmessageBody
.flatten] is called. For client-side
messages, this automatically happens for the response body after it
has been fully read. 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
- messageBodyAppend :: (HasCallStack, MonadIO m) => MessageBody -> ByteString -> m ()
- messageBodyAppendBytes :: (HasCallStack, MonadIO m) => MessageBody -> Bytes -> m ()
- messageBodyComplete :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyFlatten :: (HasCallStack, MonadIO m) => MessageBody -> m Bytes
- messageBodyGetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> m Bool
- messageBodyGetChunk :: (HasCallStack, MonadIO m) => MessageBody -> Int64 -> m (Maybe Bytes)
- messageBodyGotChunk :: (HasCallStack, MonadIO m) => MessageBody -> Bytes -> m ()
- messageBodyNew :: (HasCallStack, MonadIO m) => m MessageBody
- messageBodyRef :: (HasCallStack, MonadIO m) => MessageBody -> m MessageBody
- messageBodySetAccumulate :: (HasCallStack, MonadIO m) => MessageBody -> Bool -> m ()
- messageBodyTruncate :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyUnref :: (HasCallStack, MonadIO m) => MessageBody -> m ()
- messageBodyWroteChunk :: (HasCallStack, MonadIO m) => MessageBody -> Bytes -> m ()
- getMessageBodyLength :: MonadIO m => MessageBody -> m Int64
- setMessageBodyLength :: MonadIO m => MessageBody -> Int64 -> m ()
Exported types
newtype MessageBody Source #
Memory-managed wrapper type.
MessageBody (ManagedPtr MessageBody) |
Instances
newZeroMessageBody :: MonadIO m => m MessageBody Source #
Construct a MessageBody
struct initialized to zero.
Methods
Click to display all available methods, including inherited ones
Methods
appendBytes, append, complete, flatten, gotChunk, ref, truncate, unref, wroteChunk.
Getters
Setters
append
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> ByteString |
|
-> m () |
Appends length
bytes from data
to body
.
This function is exactly equivalent to [methodmessageBody
.append]
with MemoryUseTake
as second argument; it exists mainly for
convenience and simplifying language bindings.
appendBytes
messageBodyAppendBytes Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Bytes |
|
-> m () |
Appends the data from buffer
to body
.
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 Bytes | Returns: a |
Fills in body
's data field with a buffer containing all of the
data in body
.
Adds an additional \0
byte not counted by body
's
length field.
getAccumulate
messageBodyGetAccumulate Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m Bool | Returns: the accumulate flag for |
Gets the accumulate flag on body
.
See [methodmessageBody
.set_accumulate. for details.
getChunk
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Int64 |
|
-> m (Maybe Bytes) | Returns: a |
Gets a [structgLib
.Bytes] 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
[methodmessageBody
.get_chunk] 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
[methodmessageBody
.complete] has been called or not; if it has,
then [methodmessageBody
.get_chunk] will return a 0-length chunk
(indicating the end of body
). If it has not, then
[methodmessageBody
.get_chunk] will return Nothing
(indicating that
body
may still potentially have more data, but that data is not
currently available).
gotChunk
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Bytes |
|
-> m () |
Handles the MessageBody
part of receiving a chunk of data from
the network.
Normally this means appending chunk
to body
, exactly as with
[methodmessageBody
.append_bytes], 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.
new
:: (HasCallStack, MonadIO m) | |
=> m MessageBody | Returns: a new |
Creates a new MessageBody
.
- class
message
- uses this internally; you will not normally need to call it yourself.
ref
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m MessageBody | Returns: the passed in |
Atomically increments the reference count of body
by one.
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.
If you set the flag to False
on the [classmessage
] 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
[classmessage
] 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.
truncate
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Deletes all of the data in body
.
unref
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> m () |
Atomically decrements the reference count of body
by one.
When the reference count reaches zero, the resources allocated by
body
are freed
wroteChunk
messageBodyWroteChunk Source #
:: (HasCallStack, MonadIO m) | |
=> MessageBody |
|
-> Bytes |
|
-> 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.
Properties
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 ]