boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-08-03 06:44:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work

Browse Source
This commit is contained in:
Vinnie Falco
2017-06-23 10:52:10 -07:00
parent e5f1d4d010
commit e389b853c5
7 changed files with 133 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
doc/5_02_message.qbk
View File

@@ -11,22 +11,40 @@ Beast provides a single class template __message__ and some aliases which
model HTTP/1 and
[@https://tools.ietf.org/html/rfc7540 HTTP/2]
messages:
```
/// An HTTP message
template<
bool isRequest, // `true` for requests, `false` for responses
class Body, // Controls the container and algorithms used for the body
class Fields = fields> // The type of container to store the fields
class message;
/// A typical HTTP request
template<class Body, class Fields = fields>
using request = message<true, Body, Fields>;
/// A typical HTTP response
template<class Body, class Fields = fields>
using response = message<false, Body, Fields>;
```
[table Message
[[Name][Description]]
[[
__message__
][
```
/// An HTTP message
template<
bool isRequest, // `true` for requests, `false` for responses
class Body, // Controls the container and algorithms used for the body
class Fields = fields> // The type of container to store the fields
class message;
```
]]
[[
[link beast.ref.beast__http__request `request`]
][
```
/// A typical HTTP request
template<class Body, class Fields = fields>
using request = message<true, Body, Fields>;
```
]]
[[
[link beast.ref.beast__http__response `response`]
][
```
/// A typical HTTP response
template<class Body, class Fields = fields>
using response = message<false, Body, Fields>;
```
]]
]
The container offers value semantics including move and copy if supported
by __Body__ and __Fields__. User defined template function parameters can
@@ -42,21 +60,39 @@ As with fields, user defined body types are possible.
Sometimes it is desired to only work with a header. Beast provides a single
class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers:
```
/// An HTTP header
template<
bool isRequest, // `true` for requests, `false` for responses
class Fields = fields> // The type of container to store the fields
class header;
/// A typical HTTP request header
template<class Fields>
using request_header = header<true, Fields>;
/// A typical HTTP response header
template<class Fields>
using response_header = header<false, Fields>;
```
[table Header
[[Name][Description]]
[[
__header__
][
```
/// An HTTP header
template<
bool isRequest, // `true` for requests, `false` for responses
class Fields = fields> // The type of container to store the fields
class header;
```
]]
[[
[link beast.ref.beast__http__request_header `request_header`]
][
```
/// A typical HTTP request header
template<class Fields>
using request_header = header<true, Fields>;
```
]]
[[
[link beast.ref.beast__http__response_header `response_header`]
][
```
/// A typical HTTP response header
template<class Fields>
using response_header = header<false, Fields>;
```
]]
]
Requests and responses share the version, fields, and body but have
a few members unique to the type. This is implemented by declaring the
@@ -70,22 +106,6 @@ notable differences in members in each partial specialization:
[$images/message.png [width 730px] [height 410px]]
The template type aliases
[link beast.ref.beast__http__request `request`] and
[link beast.ref.beast__http__response `response`]
are provided for brevity. They specify __fields__ as the default for [*Fields].
```
/// A typical HTTP request
template<class Body, class Fields = fields>
using request = message<true, Body, Fields>;
/// A typical HTTP response
template<class Body, class Fields = fields>
using response = message<false, Body, Fields>;
```
[heading:body Body Types]
Beast defines the __Body__ concept, which determines both the type of

46
doc/5_04_serializer_streams.qbk
View File

@@ -19,10 +19,50 @@ at once, such as:
* 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 these declarations:
To use these interfaces, first construct a suitable object with
the message to be sent:
[http_snippet_9]
[table Serializer
[[Name][Description]]
[[
__serializer__
][
```
/// Provides buffer oriented HTTP message serialization functionality.
template<
bool isRequest,
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator
>
class serializer;
```
]]
[[
[link beast.ref.beast__http__request_serializer `request_serializer`]
][
```
/// A serializer for HTTP/1 requests
template<
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator>
using request_serializer = serializer<true, Body, Fields, ChunkDecorator>;
```
]]
[[
[link beast.ref.beast__http__response_serializer `response_serializer`]
][
```
/// A serializer for HTTP/1 responses
template<
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator>
using response_serializer = serializer<false, Body, Fields, ChunkDecorator>;
```
]]
]
The choices for template types must match the message passed on construction.
This code creates an HTTP response and the corresponding serializer:

2
doc/5_05_parser_streams.qbk
View File

@@ -24,7 +24,7 @@ associated state, by constructing a class derived from __basic_parser__.
Beast comes with the derived instance __parser__ which creates complete
__message__ objects; user-defined parsers are also possible:
[table Parser Implementations
[table Parser
[[Name][Description]]
[[
__parser__

9
doc/concept/Body.qbk
View File

@@ -71,4 +71,13 @@ In this table:
[concept_Body]
[heading Models]
* [link beast.ref.beast__http__basic_dynamic_body `basic_dynamic_body`]
* [link beast.ref.beast__http__buffer_body `buffer_body`]
* [link beast.ref.beast__http__dynamic_body `dynamic_body`]
* [link beast.ref.beast__http__empty_body `empty_body`]
* [link beast.ref.beast__http__string_body `string_body`]
* [link beast.ref.beast__http__string_view_body `string_view_body`]
[endsect]

10
doc/concept/DynamicBuffer.qbk
View File

@@ -123,4 +123,14 @@ In this table:
]
]
[heading Models]
* [link beast.ref.beast__basic_flat_buffer `basic_flat_buffer`]
* [link beast.ref.beast__basic_multi_buffer `basic_multi_buffer`]
* [link beast.ref.beast__drain_buffer `drain_buffer`]
* [link beast.ref.beast__flat_buffer `flat_buffer`]
* [link beast.ref.beast__multi_buffer `multi_buffer`]
* [link beast.ref.beast__static_buffer `static_buffer`]
* [link beast.ref.beast__static_buffer_n `static_buffer_n`]
[endsect]

5
doc/concept/Fields.qbk
View File

@@ -129,4 +129,9 @@ In this table:
[concept_Fields]
[heading Models]
* [link beast.ref.beast__http__basic_fields `basic_fields`]
* [link beast.ref.beast__http__fields `fields`]
[endsect]

36
test/http/doc_snippets.cpp
View File

@@ -324,39 +324,3 @@ struct decorator
//]
} // doc_http_snippets
namespace beast {
namespace http {
#if 0
//[http_snippet_9]
/// Provides buffer oriented HTTP message serialization functionality.
template<
bool isRequest,
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator
>
class serializer;
/// A serializer for HTTP/1 requests
template<
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator>
using request_serializer = serializer<true, Body, Fields, ChunkDecorator>;
/// A serializer for HTTP/1 responses
template<
class Body,
class Fields = fields,
class ChunkDecorator = no_chunk_decorator>
using response_serializer = serializer<false, Body, Fields, ChunkDecorator>;
//]
#endif
} // http
} // beast