mirror of
https://github.com/XRPLF/rippled.git
synced 2025-11-19 10:35:50 +00:00
6d8c73cc52
* Concepts split up into individual files * Function definitions moved to .ipp files * Add more tests to fill gaps in coverage * Fix documentation Xsl
374 lines
10 KiB
Plaintext
374 lines
10 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2016 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:Body Body]
|
|
|
|
In this table:
|
|
|
|
* `X` is a type meeting the requirements of [*`Body`].
|
|
|
|
[table Body requirements
|
|
[[operation] [type] [semantics, pre/post-conditions]]
|
|
[
|
|
[`X::value_type`]
|
|
[]
|
|
[
|
|
The type of the `message::body` member.
|
|
If this is not movable or not copyable, the containing message
|
|
will be not movable or not copyable.
|
|
]
|
|
]
|
|
[
|
|
[`X:value_type{}`]
|
|
[]
|
|
[`DefaultConstructible`]
|
|
]
|
|
[
|
|
[`Body::reader`]
|
|
[]
|
|
[
|
|
If present, a type meeting the requirements of
|
|
[link beast.types.Reader [*`Reader`]].
|
|
Provides an implementation to parse the body.
|
|
]
|
|
]
|
|
[
|
|
[`Body::writer`]
|
|
[]
|
|
[
|
|
If present, a type meeting the requirements of
|
|
[link beast.types.Writer [*`Writer`]].
|
|
Provides an implementation to serialize the body.
|
|
]
|
|
]
|
|
]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:BufferSequence BufferSequence]
|
|
|
|
A `BufferSequence` is a type meeting either of the following requirements:
|
|
|
|
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/ConstBufferSequence.html [*`ConstBufferSequence`]]
|
|
* [@http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/MutableBufferSequence.html [*`MutableBufferSequence`]]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:Field Field]
|
|
|
|
A [*`Field`] represents a single HTTP header field/value pair.
|
|
|
|
In this table:
|
|
|
|
* `X` denotes a type meeting the requirements of [*`Field`].
|
|
* `a` denotes a value of type `X`.
|
|
|
|
[table Field requirements
|
|
|
|
[[operation][type][semantics, pre/post-conditions]]
|
|
[
|
|
[`a.name()`]
|
|
[`boost::string_ref`]
|
|
[
|
|
This function returns a value implicitly convertible to
|
|
`boost::string_ref` containing the case-insensitve field
|
|
name, without leading or trailing white space.
|
|
]
|
|
]
|
|
[
|
|
[`a.value()`]
|
|
[`boost::string_ref`]
|
|
[
|
|
This function returns a value implicitly convertible to
|
|
`boost::string_ref` containing the value for the field. The
|
|
value is considered canonical if there is no leading or
|
|
trailing whitespace.
|
|
]
|
|
]
|
|
]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:FieldSequence FieldSequence]
|
|
|
|
A [*`FieldSequence`] is an iterable container whose value type meets
|
|
the requirements of [link beast.types.Field [*`Field`]].
|
|
|
|
In this table:
|
|
|
|
* `X` denotes a type that meets the requirements of [*`FieldSequence`].
|
|
|
|
* `a` is a value of type `X`.
|
|
|
|
[table FieldSequence requirements
|
|
[[operation][type][semantics, pre/post-conditions]]
|
|
[
|
|
[`X::value_type`]
|
|
[]
|
|
[
|
|
A type that meets the requirements of `Field`.
|
|
]
|
|
]
|
|
[
|
|
[`X::const_iterator`]
|
|
[]
|
|
[
|
|
A type that meets the requirements of `ForwardIterator`.
|
|
]
|
|
]
|
|
[
|
|
[`a.begin()`]
|
|
[`X::const_iterator`]
|
|
[
|
|
Returns an iterator to the beginning of the field sequence.
|
|
]
|
|
]
|
|
[
|
|
[`a.end()`]
|
|
[`X::const_iterator`]
|
|
[
|
|
Returns an iterator to the end of the field sequence.
|
|
]
|
|
]
|
|
]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:Reader Reader]
|
|
|
|
Parser implementations will construct the corresponding `reader` object
|
|
during the parse. This customization point allows the Body to determine
|
|
the strategy for storing incoming message body data.
|
|
|
|
In this table:
|
|
|
|
* `X` denotes a type meeting the requirements of [*`Reader`].
|
|
|
|
* `a` denotes a value of type `X`.
|
|
|
|
* `p` is any pointer.
|
|
|
|
* `n` is a value convertible to `std::size_t`.
|
|
|
|
* `ec` is a value of type `error_code&`.
|
|
|
|
* `m` denotes a value of type `message const&` where
|
|
`std::is_same<decltype(m.body), Body::value_type>:value == true`
|
|
|
|
|
|
[table Reader requirements
|
|
[[operation] [type] [semantics, pre/post-conditions]]
|
|
[
|
|
[`X a(m);`]
|
|
[]
|
|
[
|
|
`a` is constructible from `m`. The lifetime of `m` is
|
|
guaranteed to end no earlier than after `a` is destroyed.
|
|
]
|
|
]
|
|
[
|
|
[`a.write(p, n, ec)`]
|
|
[`void`]
|
|
[
|
|
Deserializes the input sequence into the body.
|
|
If `ec` is set, the deserialization is aborted and the error
|
|
is returned to the caller.
|
|
]
|
|
]
|
|
]
|
|
|
|
[note Definitions for required `Reader` member functions should be declared
|
|
inline so the generated code becomes part of the implementation. ]
|
|
|
|
[endsect]
|
|
|
|
|
|
|
|
[section:Writer Writer]
|
|
|
|
A `Writer` serializes the message body. The implementation creates an instance
|
|
of this type when serializing a message, and calls into it zero or more times
|
|
to provide buffers containing the data. The interface of `Writer` is intended
|
|
to allow serialization in these scenarios:
|
|
|
|
* A body that does not entirely fit in memory.
|
|
* A body produced incrementally from coroutine output.
|
|
* A body represented by zero or more buffers already in memory.
|
|
* A body as a series of buffers when the content size is not known ahead of time.
|
|
* Body data generated on demand from other threads.
|
|
* Body data computed algorithmically.
|
|
|
|
In this table:
|
|
|
|
* `X` denotes a type meeting the requirements of `Writer`.
|
|
|
|
* `a` denotes a value of type `X`.
|
|
|
|
* `m` denotes a value of type `message const&` where
|
|
`std::is_same<decltype(m.body), Body::value_type>:value == true`.
|
|
|
|
* `rc` is an object of type [link beast.ref.http__resume_context resume_context].
|
|
|
|
* `ec` is a value of type `error_code&`.
|
|
|
|
* `wf` is a [*write function]: a function object of unspecified type provided
|
|
by the implementation which accepts any value meeting the requirements
|
|
of `ConstBufferSequence` as its single parameter.
|
|
|
|
[table Writer requirements
|
|
[[operation] [type] [semantics, pre/post-conditions]]
|
|
[
|
|
[`X a(m);`]
|
|
[]
|
|
[
|
|
`a` is constructible from `m`. The lifetime of `m` is
|
|
guaranteed to end no earlier than after `a` is destroyed.
|
|
]
|
|
]
|
|
[
|
|
[`a.init(ec)`]
|
|
[`void`]
|
|
[
|
|
Called immediately after construction.
|
|
If `ec` is set, the serialization is aborted and the error
|
|
is propagated to the caller.
|
|
]
|
|
]
|
|
[
|
|
[`a.content_length()`]
|
|
[`std::uint64_t`]
|
|
[
|
|
If this member is present, it is called after initialization
|
|
and before calls to provide buffers. The serialized message will
|
|
have the Content-Length field set to the value returned from
|
|
this function. If this member is absent, the serialized message
|
|
body will be chunk-encoded for HTTP versions 1.1 and later, else
|
|
the serialized message body will be sent unmodified, with the
|
|
error `boost::asio::error::eof` returned to the caller, to notify
|
|
they should close the connection to indicate the end of the message.
|
|
]
|
|
]
|
|
[
|
|
[`a(rc, ec, wf)`]
|
|
[`boost::tribool`]
|
|
[
|
|
Called repeatedly after `init` succeeds.
|
|
`wf` is a function object which takes as its single parameter,
|
|
any value meeting the requirements of `ConstBufferSequence`.
|
|
Buffers provided by the `writer` to this [*write function] must
|
|
remain valid until the next member function of `writer` is
|
|
invoked (which may be the destructor). This function returns `true`
|
|
to indicate all message body data has been written, or `false`
|
|
if there is more body data. If the return value is
|
|
`boost::indeterminate`, the implementation will suspend the operation
|
|
until the writer invokes `rc`. It is the writers responsibility when
|
|
returning `boost::indeterminate`, to acquire ownership of the
|
|
`resume_context` via move construction and eventually call it or else
|
|
undefined behavior results.
|
|
]
|
|
]
|
|
]
|
|
|
|
[note Definitions for required `Writer` member functions should be declared
|
|
inline so the generated code becomes part of the implementation. ]
|
|
|
|
Exemplar:
|
|
```
|
|
struct writer
|
|
{
|
|
public:
|
|
/** Construct the writer.
|
|
|
|
The msg object is guaranteed to exist for the lifetime of the writer.
|
|
|
|
Exceptions:
|
|
No-throw guarantee.
|
|
|
|
@param msg The message whose body is to be written.
|
|
*/
|
|
template<bool isRequest, class Body, class Headers>
|
|
explicit
|
|
writer(message<isRequest, Body, Headers> const& msg);
|
|
|
|
/** Initialize the writer.
|
|
|
|
Called once immediately after construction.
|
|
The writer can perform initialization which may fail.
|
|
|
|
@param ec Contains the error code if any errors occur.
|
|
*/
|
|
void
|
|
init(error_code& ec);
|
|
|
|
/** Returns the content length.
|
|
|
|
If this member is present, the implementation will set the
|
|
Content-Length field accordingly. If absent, the implementation will
|
|
use chunk-encoding or terminate the connection to indicate the end
|
|
of the message.
|
|
*/
|
|
std::size_t
|
|
content_length() const;
|
|
|
|
/** Write zero or one buffer representing the message body.
|
|
|
|
Postconditions:
|
|
|
|
If return value is `true`:
|
|
* Callee does not take ownership of resume.
|
|
* Callee made zero or one calls to `write`.
|
|
* There is no more data remaining to write.
|
|
|
|
If return value is `false`:
|
|
* Callee does not take ownership of resume.
|
|
* Callee made one call to `write`.
|
|
|
|
If return value is boost::indeterminate:
|
|
* Callee takes ownership of `resume`.
|
|
* Caller suspends the write operation
|
|
until `resume` is invoked.
|
|
|
|
When the caller takes ownership of resume, the
|
|
asynchronous operation will not complete until the
|
|
caller destroys the object.
|
|
|
|
@param resume A functor to call to resume the write operation
|
|
after the writer has returned boost::indeterminate.
|
|
|
|
@param ec Set to indicate an error. This will cause an
|
|
asynchronous write operation to complete with the error.
|
|
|
|
@param write A functor the writer will call to provide the next
|
|
set of buffers. Ownership of the buffers is not transferred,
|
|
the writer must guarantee that the buffers remain valid until the
|
|
next member function is invoked, which may be the destructor.
|
|
|
|
@return `true` if there is data, `false` when done,
|
|
boost::indeterminate to suspend.
|
|
|
|
@note Undefined behavior if the callee takes ownership
|
|
of resume but does not return boost::indeterminate.
|
|
*/
|
|
template<class WriteFunction>
|
|
boost::tribool
|
|
operator()(resume_context&&, error_code&, WriteFunction&& write);
|
|
};
|
|
```
|
|
|
|
[endsect]
|
|
|