From 80ca9a59610811ef17a8a2958adf62116e7133b5 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Wed, 7 Jun 2017 04:36:45 -0700 Subject: [PATCH] Body documentation work --- CHANGELOG.md | 1 + doc/concept/Body.qbk | 42 +++++++++++++++++++++++++++++----- doc/concept/BodyReader.qbk | 46 +++++++------------------------------- doc/concept/BodyWriter.qbk | 18 +++++++-------- 4 files changed, 53 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e710f910..4db8d055 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Version 50 * Use field in basic_parser * Tidy up basic_fields, header, and field concepts * Fields concept work +* Body documentation work API Changes: diff --git a/doc/concept/Body.qbk b/doc/concept/Body.qbk index 6a9f6e4c..1b52b451 100644 --- a/doc/concept/Body.qbk +++ b/doc/concept/Body.qbk @@ -15,6 +15,9 @@ In this table: * `X` is a type meeting the requirements of [*Body]. +* `m` is a value of type `message` where `b` is a `bool` value + and `F` is a type meeting the requirements of [*Fields]. + [table Body requirements [[expression] [type] [semantics, pre/post-conditions]] [ @@ -25,8 +28,7 @@ In this table: If this is not movable or not copyable, the containing message will be not movable or not copyable. ] -] -[ +][ [`X::writer`] [] [ @@ -36,8 +38,7 @@ In this table: this type to obtain buffers into which parsed body octets are placed. ] -] -[ +][ [`X::reader`] [] [ @@ -46,8 +47,17 @@ In this table: constructs an object of this type to obtain buffers representing the message body for serialization. ] -] -[ +][ + [`X::size(m)`] + [`std::uint64_t`] + [ + If present, returns the serialized size of `m.body` not including + any chunked transfer encoding. When this function is provided, + [link beast.ref.http__message.prepare `message::prepare`] + will automatically set the content length field based on the + value. Otherwise, the chunked transfer encoding will be set. + ] +][ [`is_body`] [`std::true_type`] [ @@ -57,4 +67,24 @@ In this table: ] ] +Exemplar: +``` +struct body +{ + using value_type = implementation_defined; + + /// The algorithm used for extracting buffers + class reader; + + /// The algorithm used for inserting buffers + class writer; + + /// Returns the body's payload size + template + static + std::uint64_t + size(message const& m); +} +``` + [endsect] diff --git a/doc/concept/BodyReader.qbk b/doc/concept/BodyReader.qbk index 10cbb6bb..89907f17 100644 --- a/doc/concept/BodyReader.qbk +++ b/doc/concept/BodyReader.qbk @@ -45,8 +45,7 @@ In this table: A type which meets the requirements of __ConstBufferSequence__. This is the type of buffer returned by `X::get`. ] -] -[ +][ [`X::is_deferred`] [] [ @@ -62,16 +61,14 @@ In this table: latency experienced by the remote host when expecting to read the HTTP header. ] -] -[ +][ [`X(m);`] [] [ Constructible from `m`. The lifetime of `m` is guaranteed to end no earlier than after the `X` is destroyed. ] -] -[ +][ [`a.init(ec)`] [] [ @@ -79,23 +76,7 @@ In this table: error code in `ec`, 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. - This function must be `noexcept`. - ] -] -[ +][ [`a.get(ec)`] [`R`] [ @@ -110,8 +91,7 @@ In this table: or `false` if the buffer returned on this call is the last buffer representing the body. ] -] -[ +][ [`is_body_reader`] [`std::true_type`] [ @@ -122,9 +102,9 @@ In this table: ] [note - Definitions for required [*BodyReader] member functions should - be declared inline so the generated code can become part of the - implementation. + Definitions for required [*BodyReader] member functions may + be declared inline so the generated code can become part of + the implementation. ] Exemplar: @@ -160,16 +140,6 @@ public: 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::uint64_t - content_length(); - /** Returns the next buffer in the body. @li If the return value is `boost::none` (unseated optional) and diff --git a/doc/concept/BodyWriter.qbk b/doc/concept/BodyWriter.qbk index 514379af..e7ff49d1 100644 --- a/doc/concept/BodyWriter.qbk +++ b/doc/concept/BodyWriter.qbk @@ -49,8 +49,7 @@ In the table below: will be called the complete header is stored in `m`, and before parsing body octets for messages indicating that a body is present. ] -] -[ +][ [`a.init(length,ec)`] [] [ @@ -61,8 +60,7 @@ In the table below: [*BodyWriter] may use this information to optimize allocation. If `ec` is set, the error will be propagated to the caller. ] -] -[ +][ [`a.put(b,ec)`] [] [ @@ -70,16 +68,14 @@ In the table below: into the body representation. If `ec` is set, the error will be propagated to the caller. ] -] -[ +][ [`a.finish(ec)`] [] [ This function is called when no more body octets are remaining. If `ec` is set, the error will be propagated to the caller. ] -] -[ +][ [`is_body_writer`] [`std::true_type`] [ @@ -88,9 +84,11 @@ In the table below: ] ] ] + [note - Definitions for required [*BodyWriter] member functions should be declared - inline so the generated code can become part of the implementation. + Definitions for required [*BodyReader] member functions may + be declared inline so the generated code can become part of + the implementation. ] Exemplar: