1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section Message Stream Operations] 11 12Beast provides synchronous and asynchronous algorithms to parse and 13serialize HTTP/1 wire format messages on streams. These functions form 14the message-oriented stream interface: 15 16[table Message Stream Operations 17[[Name][Description]] 18[[ 19 [link beast.ref.boost__beast__http__read.overload3 [*read]] 20][ 21 Read a __message__ from a __SyncReadStream__. 22]] 23[[ 24 [link beast.ref.boost__beast__http__async_read.overload2 [*async_read]] 25][ 26 Read a __message__ from an __AsyncReadStream__. 27]] 28[[ 29 [link beast.ref.boost__beast__http__write.overload1 [*write]] 30][ 31 Write a __message__ to a __SyncWriteStream__. 32]] 33[[ 34 [link beast.ref.boost__beast__http__async_write [*async_write]] 35][ 36 Write a __message__ to an __AsyncWriteStream__. 37]] 38] 39 40All synchronous stream operations come in two varieties. One which throws 41an exception upon error, and another which accepts as the last parameter an 42argument of type [link beast.ref.boost__beast__error_code `error_code&`]. If an error 43occurs this argument will be set to contain the error code. 44 45 46 47[heading Reading] 48 49Because a serialized header is not length-prefixed, algorithms which 50parse messages from a stream may read past the end of a message for 51efficiency. To hold this surplus data, all stream read operations use 52a passed-in __DynamicBuffer__ which must be persisted between calls 53until the end of stream is reached or the stream object is destroyed. 54Each read operation may consume bytes remaining in the buffer, and 55leave behind new bytes. In this example we declare the buffer and a 56message variable, then read a complete HTTP request synchronously: 57 58[http_snippet_4] 59 60This example uses __flat_buffer__. Beast's __basic_parser__ is 61optimized for structured HTTP data located in a single contiguous 62(['flat]) memory buffer. When not using a flat buffer the implementation 63may perform an additional memory allocations to restructure the input 64into a single buffer for parsing. 65 66[tip 67 Other Implementations of __DynamicBuffer__ may avoid parser 68 memory allocation by always returning buffer sequences of 69 length one. 70] 71 72Messages may also be read asynchronously. When performing asynchronous 73stream read operations the stream, buffer, and message variables must 74remain valid until the operation has completed. Beast asynchronous 75initiation functions use Asio's completion handler model. This call 76reads a message asynchronously and reports the error code upon 77completion. The handler is called with the error, set to any that 78occurs, and the number of bytes parsed. This number may be used to 79measure the relative amount of work performed, or it may be ignored 80as this example shows. 81 82[http_snippet_5] 83 84If a read stream algorithm cannot complete its operation without exceeding 85the maximum specified size of the dynamic buffer provided, the error 86[link beast.ref.boost__beast__http__error `buffer_overflow`] 87is returned. This is one technique which may be used to impose a limit on 88the maximum size of an HTTP message header for protection from buffer 89overflow attacks. The following code will print the error message: 90 91[http_snippet_6] 92 93 94 95[heading Writing] 96 97A set of free functions allow serialization of an entire HTTP message to 98a stream. This example constructs and sends an HTTP response: 99 100[http_snippet_7] 101 102The asynchronous version could be used instead: 103 104[http_snippet_8] 105 106The completion handler is called with the number of bytes written to the 107stream, which includes protocol specific data such as the delimiters in 108the header and line endings. The number may be used to measure the amount 109of data transferred, or it may be ignored as in the example. 110 111[endsect] 112