Exit Zen
10
string ID 10
type: section title
English
Message Stream Operations
25/250 · 25
2
string ID 12
type: paragraph
English
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:
177/1770 · 177
16
string ID 16
type: table title
English
Message Stream Operations
25/250 · 25
4
string ID 16
type: table cell
English
Name
4/100 · 4
5
string ID 16
type: table cell
English
Description
11/110 · 11
6
string ID 16
type: table cell
English
[link beast.ref.boost__beast__http__read.overload3 [*read]]
59/590 · 59
7
string ID 16
type: table cell
English
Read a __message__ from a __SyncReadStream__.
45/450 · 45
8
string ID 16
type: table cell
English
[link beast.ref.boost__beast__http__async_read.overload2 [*async_read]]
71/710 · 71
9
string ID 16
type: table cell
English
Read a __message__ from an __AsyncReadStream__.
47/470 · 47
10
string ID 16
type: table cell
English
[link beast.ref.boost__beast__http__write.overload1 [*write]]
61/610 · 61
11
string ID 16
type: table cell
English
Write a __message__ to a __SyncWriteStream__.
45/450 · 45
12
string ID 16
type: table cell
English
[link beast.ref.boost__beast__http__async_write [*async_write]]
63/630 · 63
13
string ID 16
type: table cell
English
Write a __message__ to an __AsyncWriteStream__.
47/470 · 47
14
string ID 40
type: paragraph
English
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.
295/2950 · 295
15
string ID 47
type: heading
English
Reading
7/100 · 7
16
string ID 49
type: paragraph
English
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:
546/5460 · 546
17
string ID 60
type: paragraph
English
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.
305/3050 · 305
18
string ID 67
type: paragraph
English
Other Implementations of __DynamicBuffer__ may avoid parser
59/590 · 59
19
string ID 72
type: paragraph
English
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.
562/5620 · 562
20
string ID 84
type: paragraph
English
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:
415/4150 · 415