Files
boost_beast/doc/5_08_custom_body.qbk
T

155 lines
4.7 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 Custom Body Types]
[block'''<?dbhtml stop-chunking?>''']
User-defined types are possible for the message body, where the type meets the
__Body__ requirements. This simplified class declaration
shows the customization points available to user-defined body types:
```
/// Defines a Body type
struct body
{
/// This determines the type of the `message::body` member
using value_type = ...;
/// An optional function, returns the body's payload size
static
std::uint64_t
size(value_type const& v);
/// The algorithm used for extracting buffers
class reader;
/// The algorithm used for inserting buffers
class writer;
}
```
The meaning of the nested types is as follows
[table Body Type Members
[[Name][Description]]
[
[`value_type`]
[
Determines the type of the
[link beast.ref.beast__http__message.body `message::body`]
member.
]
][
[`reader`]
[
An optional nested type meeting the requirements of __BodyReader__,
which provides the algorithm for converting the body representation
to a forward range of buffer sequences.
If present this body type may be used with a __serializer__.
]
][
[`writer`]
[
An optional nested type meeting the requirements of __BodyWriter__,
which provides the algorithm for storing a forward range of buffer
sequences in the body representation.
If present, this body type may be used with a __parser__.
]
]
]
[heading Value Type]
The `value_type` nested type allows the body to define the declaration of
the body type as it appears in the message. This can be any type. For
example, a body's value type may specify `std::vector<char>` or even
`std::list<std::string>`. A custom body may even set the value type to
something that is not a container for body octets, such as a
[@http://www.boost.org/libs/filesystem/doc/reference.html#class-path `boost::filesystem::path`].
Or, a more structured container may be chosen. This declares a body's
value type as a JSON tree structure produced from a
[@http://www.boost.org/doc/html/property_tree/parsers.html#property_tree.parsers.json_parser `json_parser`]:
```
#include <boost/property_tree/ptree.hpp>
#include <boost/property_tree/json_parser.hpp>
struct Body
{
using value_type = boost::property_tree::ptree;
class reader;
class writer;
// Optional member
static
std::uint64_t
size(value_type const&);
};
```
As long as a suitable reader or writer is available to provide the
algorithm for transferring buffers in and out of the value type,
those bodies may be serialized or parsed.
[section File Body]
Use of the flexible __Body__ concept customization point enables authors to
preserve the self-contained nature of the __message__ object while allowing
domain specific behaviors. Common operations for HTTP servers include sending
responses which deliver file contents, and allowing for file uploads. In this
example we build the `file_body` type which supports both reading and writing
to a file on the file system.
First we declare the type with its nested types:
[example_http_file_body_1]
We will start with the definition of the `value_type`. Our strategy
will be to store the open file handle directly in the message
container through the `value_type` field. To use this body it will
be necessary to call `msg.body.open()` with the file first. This
ensures that the file exists throughout the operation and prevent
the race condition where the file is removed from the file system
in between calls.
[example_http_file_body_2]
Our implementation of __BodyReader__ will contain a small buffer
from which the file contents are read. The buffer is provided to
the implementation on each call until everything has been read in.
[example_http_file_body_3]
And here are the definitions for the functions we have declared:
[example_http_file_body_4]
Files can be read now, and the next step is to allow writing to files
by implementing the __BodyWriter__. The style is similar to the reader,
except that buffers are incoming instead of outgoing. Here's the
declaration:
[example_http_file_body_5]
Finally, here is the implementation of the writer member functions:
[example_http_file_body_6]
We have created a full featured body type capable of reading and
writing files on the filesystem, integrating seamlessly with the
HTTP algorithms and message container. Source code for this body
type, and HTTP servers that use it, are available in the examples
directory.
[endsect]
[endsect]