112 lines
3.9 KiB
Plaintext
112 lines
3.9 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
|
|
Official repository: https://github.com/boostorg/beast
|
|
]
|
|
|
|
[section Message Stream Operations]
|
|
|
|
Beast provides synchronous and asynchronous algorithms to parse and
|
|
serialize HTTP/1 wire format messages on streams. These functions form
|
|
the message-oriented stream interface:
|
|
|
|
[table Message Stream Operations
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__read.overload3 [*read]]
|
|
][
|
|
Read a __message__ from a __SyncReadStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__async_read.overload2 [*async_read]]
|
|
][
|
|
Read a __message__ from an __AsyncReadStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__write.overload1 [*write]]
|
|
][
|
|
Write a __message__ to a __SyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__http__async_write [*async_write]]
|
|
][
|
|
Write a __message__ to an __AsyncWriteStream__.
|
|
]]
|
|
]
|
|
|
|
All synchronous stream operations come in two varieties. One which throws
|
|
an exception upon error, and another which accepts as the last parameter an
|
|
argument of type [link beast.ref.boost__beast__error_code `error_code&`]. If an error
|
|
occurs this argument will be set to contain the error code.
|
|
|
|
|
|
|
|
[heading Reading]
|
|
|
|
Because a serialized header is not length-prefixed, algorithms which
|
|
parse messages from a stream may read past the end of a message for
|
|
efficiency. To hold this surplus data, all stream read operations use
|
|
a passed-in __DynamicBuffer__ which must be persisted between calls
|
|
until the end of stream is reached or the stream object is destroyed.
|
|
Each read operation may consume bytes remaining in the buffer, and
|
|
leave behind new bytes. In this example we declare the buffer and a
|
|
message variable, then read a complete HTTP request synchronously:
|
|
|
|
[http_snippet_4]
|
|
|
|
This example uses __flat_buffer__. Beast's __basic_parser__ is
|
|
optimized for structured HTTP data located in a single contiguous
|
|
(['flat]) memory buffer. When not using a flat buffer the implementation
|
|
may perform an additional memory allocations to restructure the input
|
|
into a single buffer for parsing.
|
|
|
|
[tip
|
|
Other Implementations of __DynamicBuffer__ may avoid parser
|
|
memory allocation by always returning buffer sequences of
|
|
length one.
|
|
]
|
|
|
|
Messages may also be read asynchronously. When performing asynchronous
|
|
stream read operations the stream, buffer, and message variables must
|
|
remain valid until the operation has completed. Beast asynchronous
|
|
initiation functions use Asio's completion handler model. This call
|
|
reads a message asynchronously and reports the error code upon
|
|
completion. The handler is called with the error, set to any that
|
|
occurs, and the number of bytes parsed. This number may be used to
|
|
measure the relative amount of work performed, or it may be ignored
|
|
as this example shows.
|
|
|
|
[http_snippet_5]
|
|
|
|
If a read stream algorithm cannot complete its operation without exceeding
|
|
the maximum specified size of the dynamic buffer provided, the error
|
|
[link beast.ref.boost__beast__http__error `buffer_overflow`]
|
|
is returned. This is one technique which may be used to impose a limit on
|
|
the maximum size of an HTTP message header for protection from buffer
|
|
overflow attacks. The following code will print the error message:
|
|
|
|
[http_snippet_6]
|
|
|
|
|
|
|
|
[heading Writing]
|
|
|
|
A set of free functions allow serialization of an entire HTTP message to
|
|
a stream. This example constructs and sends an HTTP response:
|
|
|
|
[http_snippet_7]
|
|
|
|
The asynchronous version could be used instead:
|
|
|
|
[http_snippet_8]
|
|
|
|
The completion handler is called with the number of bytes written to the
|
|
stream, which includes protocol specific data such as the delimiters in
|
|
the header and line endings. The number may be used to measure the amount
|
|
of data transferred, or it may be ignored as in the example.
|
|
|
|
[endsect]
|