[/ 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_streams Serializer Stream Operations] Message oriented stream operations provide for limited control. Sophisticated algorithms may need to do more, such as: * Send the header first, and the body later. * Set chunk extensions or trailers using a chunk decorator. * Send a message incrementally: bounded work in each I/O cycle. * Use a series of caller-provided buffers to represent the body. These tasks may be performed by using the serializer stream interfaces. To use these interfaces, first construct a __serializer__ object with the message to be sent. The serializer type has this declaration: [http_snippet_9] The choices for template types must match the message passed on construction. This code creates an HTTP response and the corresponding serializer: [http_snippet_10] The function [link beast.ref.http__make_serializer `make_serializer`] is provided to simplify creation of variables: [http_snippet_11] The stream operations which work on serializers are: [table Serializer Stream Operations [[Name][Description]] [[ [link beast.ref.http__write.overload1 [*write]] ][ Send everything in a __serializer__ to a __SyncWriteStream__. ]] [[ [link beast.ref.http__async_write.overload1 [*async_write]] ][ Send everything in a __serializer__ asynchronously to an __AsyncWriteStream__. ]] [[ [link beast.ref.http__write_header.overload1 [*write_header]] ][ Send only the header from a __serializer__ to a __SyncWriteStream__. ]] [[ [link beast.ref.http__async_write_header [*async_write_header]] ][ Send only the header from a __serializer__ asynchronously to an __AsyncWriteStream__. ]] [[ [link beast.ref.http__write_some.overload1 [*write_some]] ][ Send part of a __serializer__ to a __SyncWriteStream__. ]] [[ [link beast.ref.http__async_write_some [*async_write_some]] ][ Send part of a __serializer__ asynchronously to an __AsyncWriteStream__. ]] ] Here is an example of using a serializer to send a message on a stream synchronously. This performs the same operation as calling `write(stream, m)`: [http_snippet_12] [heading Chunk Decorators] When the message used to construct the serializer indicates the chunked transfer encoding, the serializer will automatically generate the proper encoding in the output buffers. __rfc7230__ defines additional fields called the [@https://tools.ietf.org/html/rfc7230#section-4.1.1 chunk extensions] in chunks with body octets, and the [@https://tools.ietf.org/html/rfc7230#section-4.1.2 chunked trailer part] for the final chunk. Applications that wish to emit chunk extensions and trailers may instantiate the serializer with a "chunk decorator" type, and pass an instance of the type upon construction. This decorator is a function object which, when invoked with a __ConstBufferSequence__, returns a [link beast.ref.string_view `string_view`] containing either the extensions or the trailer. For chunks containing body data, the passed buffer will contain one or more corresponding body octets. The decorator may use this information as needed. For example, to compute a digest on the data and store it as a chunk extension. For the trailers, the serializer will invoke the decorator with a buffer sequence of size zero. Or more specifically, with an object of type [@http://www.boost.org/doc/html/boost_asio/reference/null_buffers.html `boost::asio::null_buffers`]. For body chunks the string returned by the decorator must follow the [@https://tools.ietf.org/html/rfc7230#section-4.1.1 correct syntax] for the entire chunk extension. For the trailer, the returned string should consist of zero or more lines ending in a CRLF and containing a field name/value pair in the format prescribed by __rfc7230__. It is the responsibility of the decorator to manage returned string buffers. The implementation guarantees it will not reference previous strings after subsequent calls. Here, we declare a decorator which sets an extension variable `x` equal to the size of the chunk in bytes, and returns a single trailer field: [http_snippet_17] [endsect]