File: BodyReader.qbk

package info (click to toggle)
boost1.88 1.88.0-1
  • links: PTS, VCS
  • area: main
  • in suites: trixie
  • size: 576,932 kB
  • sloc: cpp: 4,149,234; xml: 136,789; ansic: 35,092; python: 33,910; asm: 5,698; sh: 4,604; ada: 1,681; makefile: 1,633; pascal: 1,139; perl: 1,124; sql: 640; yacc: 478; ruby: 271; java: 77; lisp: 24; csh: 6
file content (119 lines) | stat: -rw-r--r-- 4,358 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
[/
    Copyright (c) 2016-2019 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)

    Official repository: https://github.com/boostorg/beast
]

[section:BodyReader BodyReader]

A [*BodyReader] provides an online algorithm to transfer a series of zero
or more buffers containing parsed body octets into a message container. The
__parser__ creates an instance of this type when needed, and calls into
it zero or more times to transfer buffers. The interface of [*BodyReader]
is intended to allow the conversion of buffers into these scenarios for
representation:

* Storing a body in a dynamic buffer
* Storing a body in a user defined container with a custom allocator
* Transformation of incoming body data before storage, for example
  to compress it first.
* Saving body data to a file

[heading Associated Types]

* [link beast.ref.boost__beast__http__is_body_reader `is_body_reader`]
* __Body__

[heading Requirements]

[warning
    These requirements may undergo non-backward compatible
    changes in subsequent versions.
]

In this table:

* `R` denotes a type meeting the requirements of [*BodyReader].
* `B` denotes a __Body__ where
      `std::is_same<R, B::reader>::value == true`.
* `a` denotes a value of type `R`.
* `b` is an object whose type meets the requirements of __ConstBufferSequence__
* `h` denotes a value of type `header<isRequest, Fields>&`.
* `v` denotes a value of type `Body::value_type&`.
* `n` is a value of type `boost::optional<std::uint64_t>`.
* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].

[table Valid expressions
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
[
    [`R{h,v};`]
    []
    [
        Constructible from `h` and `v`. The lifetime of `h` and `v`
        is guaranteed to end no earlier than after the `R` is destroyed.
        The reader shall not access the contents of `h` or `v` before
        the first call to `init`, permitting lazy construction of the
        message.
    ]
][
    [`a.init(n, ec)`]
    []
    [
        Called once to fully initialize the object before any calls to
        `put`. The message body is valid before entering this function,
        and remains valid until the reader is destroyed.
        The value of `n` will be set to the content length of the
        body if known, otherwise `n` will be equal to `boost::none`.
        Implementations of [*BodyReader] may use this information to
        optimize allocation.

        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`a.put(b,ec)`]
    [`std::size_t`]
    [
        This function is called to append some or all of the buffers
        specified by `b` into the body representation. The number of
        bytes inserted from `b` is returned. If the number of bytes
        inserted is less than the total input, the remainder of the
        input will be presented in the next call to `put`.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`a.finish(ec)`]
    []
    [
        This function is called when no more body octets are remaining.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`is_body_reader<B>`]
    [`std::true_type`]
    [
        An alias for `std::true_type` for `B`, otherwise an alias
        for `std::false_type`.
    ]
]]

[heading Exemplar]

[concept_BodyReader]

[heading Models]

* [link beast.ref.boost__beast__http__basic_dynamic_body.reader `basic_dynamic_body::reader`]
* [link beast.ref.boost__beast__http__basic_file_body__reader `basic_file_body::reader`]
* [link beast.ref.boost__beast__http__basic_string_body.reader `basic_string_body::reader`]
* [link beast.ref.boost__beast__http__buffer_body.reader `buffer_body::reader`]
* [link beast.ref.boost__beast__http__empty_body.reader `empty_body::reader`]
* [link beast.ref.boost__beast__http__span_body.reader `span_body::reader`]
* [link beast.ref.boost__beast__http__vector_body.reader `vector_body::reader`]

[endsect]