forked from boostorg/beast
59 lines
2.6 KiB
Plaintext
59 lines
2.6 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2017 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)
|
|
]
|
|
|
|
[section:serializer_buffers Buffer-Oriented Serializing]
|
|
|
|
In extreme cases, users may wish to create an instance of __serializer__
|
|
and invoke its methods directly instead of using the provided stream
|
|
algorithms. This could be useful for implementing algorithms on streams
|
|
whose interface does not conform to __Stream__. For example, a
|
|
[@https://github.com/libuv/libuv *libuv* socket].
|
|
The serializer interface is interactive; the caller invokes it repeatedly to
|
|
produce buffers until all of the buffers have been generated. Then the
|
|
serializer is destroyed.
|
|
|
|
After the serializer is created, the buffers are produced by first calling
|
|
[link beast.ref.http__serializer.get `serializer::get`]
|
|
to obtain a buffer sequence, and then calling
|
|
[link beast.ref.http__serializer.consume `serializer::consume`]
|
|
to indicate how many bytes in the buffer sequence were consumed.
|
|
This advanced the internal state of the serializer and prepares the
|
|
next set of buffers for delivery.
|
|
[link beast.ref.http__serializer.get `serializer::get`]
|
|
takes an error code parameter and invokes a visitor argument with the
|
|
error code and buffer of unspecified type. In C++14 this is easily
|
|
expressed with a generic lambda. The function
|
|
[link beast.ref.http__serializer.is_done `serializer::is_done`]
|
|
will return `true` when all the buffers have been produced. This C++14
|
|
example prints the buffers to standard output:
|
|
|
|
[http_snippet_14]
|
|
|
|
Generic lambda expressions are only available in C++14 or later. A functor
|
|
with a templated function call operator is necessary to use C++11 as shown:
|
|
|
|
[http_snippet_15]
|
|
|
|
[heading Split Serialization]
|
|
|
|
In some cases, such as the handling of the
|
|
[@https://tools.ietf.org/html/rfc7231#section-5.1.1 Expect: 100-continue]
|
|
field, it may be desired to first serialize the header, perform some other
|
|
action, and then continue with serialization of the body. This is
|
|
accomplished by calling
|
|
[link beast.ref.http__serializer.split `serializer::split`]
|
|
with a boolean indicating that when buffers are produced, the last buffer
|
|
containing serialized header octets will not contain any octets corresponding
|
|
to the body. The function
|
|
[link beast.ref.http__serializer.is_header_done `serializer::is_header_done`]
|
|
informs the caller whether the header has completed serialization. In this
|
|
C++14 example we print the header first, followed by the body:
|
|
|
|
[http_snippet_16]
|
|
|
|
[endsect]
|