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 Buffer-Oriented Serializing] 11[block'''<?dbhtml stop-chunking?>'''] 12 13An instance of __serializer__ can be invoked directly, without using 14the provided stream operations. This could be useful for implementing 15algorithms on objects whose interface does not conform to __Stream__. 16For example, a 17[@https://github.com/libuv/libuv *libuv* socket]. 18The serializer interface is interactive; the caller invokes it repeatedly 19to produce buffers until all of the serialized octets have been generated. 20Then the serializer is destroyed. 21 22To obtain the serialized next buffer sequence, call 23[link beast.ref.boost__beast__http__serializer.next `serializer::next`]. 24Then, call 25[link beast.ref.boost__beast__http__serializer.consume `serializer::consume`] 26to indicate the number of bytes consumed. This updates the next 27set of buffers to be returned, if any. 28`serializer::next` takes an error code parameter and invokes a visitor 29argument with the error code and buffer of unspecified type. In C++14 30this is easily expressed with a generic lambda. The function 31[link beast.ref.boost__beast__http__serializer.is_done `serializer::is_done`] 32will return `true` when all the buffers have been produced. This C++14 33example prints the buffers to standard output: 34 35[http_snippet_14] 36 37Generic lambda expressions are only available in C++14 or later. A functor 38with a templated function call operator is necessary to use C++11 as shown: 39 40[http_snippet_15] 41 42[heading Split Serialization] 43 44In some cases, such as the handling of the 45[@https://tools.ietf.org/html/rfc7231#section-5.1.1 Expect: 100-continue] 46field, it may be desired to first serialize the header, perform some other 47action, and then continue with serialization of the body. This is 48accomplished by calling 49[link beast.ref.boost__beast__http__serializer.split `serializer::split`] 50with a boolean indicating that when buffers are produced, the last buffer 51containing serialized header octets will not contain any octets corresponding 52to the body. The function 53[link beast.ref.boost__beast__http__serializer.is_header_done `serializer::is_header_done`] 54informs the caller whether the header been serialized fully. In this 55C++14 example we print the header first, followed by the body: 56 57[http_snippet_16] 58 59 60 61[section:write_to_std_ostream Write To std::ostream __example__] 62 63The standard library provides the type `std::ostream` for performing high 64level write operations on character streams. The variable `std::cout` is 65based on this output stream. This example uses the buffer oriented interface 66of __serializer__ to write an HTTP message to a `std::ostream`: 67 68[example_http_write_ostream] 69 70[tip 71 Serializing to a `std::ostream` could be implemented using an alternate 72 strategy: adapt the `std::ostream` interface to a __SyncWriteStream__, 73 enabling use with the library's existing stream algorithms. This is 74 left as an exercise for the reader. 75] 76 77[endsect] 78 79 80 81[endsect] 82