1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section:BodyReader BodyReader] 11 12A [*BodyReader] provides an online algorithm to transfer a series of zero 13or more buffers containing parsed body octets into a message container. The 14__parser__ creates an instance of this type when needed, and calls into 15it zero or more times to transfer buffers. The interface of [*BodyReader] 16is intended to allow the conversion of buffers into these scenarios for 17representation: 18 19* Storing a body in a dynamic buffer 20* Storing a body in a user defined container with a custom allocator 21* Transformation of incoming body data before storage, for example 22 to compress it first. 23* Saving body data to a file 24 25[heading Associated Types] 26 27* [link beast.ref.boost__beast__http__is_body_reader `is_body_reader`] 28* __Body__ 29 30[heading Requirements] 31 32[warning 33 These requirements may undergo non-backward compatible 34 changes in subsequent versions. 35] 36 37In this table: 38 39* `R` denotes a type meeting the requirements of [*BodyReader]. 40* `B` denotes a __Body__ where 41 `std::is_same<R, B::reader>::value == true`. 42* `a` denotes a value of type `R`. 43* `b` is an object whose type meets the requirements of __ConstBufferSequence__ 44* `h` denotes a value of type `header<isRequest, Fields>&`. 45* `v` denotes a value of type `Body::value_type&`. 46* `n` is a value of type `boost::optional<std::uint64_t>`. 47* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`]. 48 49[table Valid expressions 50[[Expression] [Type] [Semantics, Pre/Post-conditions]] 51[ 52 [`R{h,v};`] 53 [] 54 [ 55 Constructible from `h` and `v`. The lifetime of `h` and `v` 56 is guaranteed to end no earlier than after the `R` is destroyed. 57 The reader shall not access the contents of `h` or `v` before 58 the first call to `init`, permitting lazy construction of the 59 message. 60 ] 61][ 62 [`a.init(n, ec)`] 63 [] 64 [ 65 Called once to fully initialize the object before any calls to 66 `put`. The message body is valid before entering this function, 67 and remains valid until the reader is destroyed. 68 The value of `n` will be set to the content length of the 69 body if known, otherwise `n` will be equal to `boost::none`. 70 Implementations of [*BodyReader] may use this information to 71 optimize allocation. 72 73 The function will ensure that `!ec` is `true` if there was 74 no error or set to the appropriate error code if there was one. 75 ] 76][ 77 [`a.put(b,ec)`] 78 [`std::size_t`] 79 [ 80 This function is called to append some or all of the buffers 81 specified by `b` into the body representation. The number of 82 bytes inserted from `b` is returned. If the number of bytes 83 inserted is less than the total input, the remainder of the 84 input will be presented in the next call to `put`. 85 The function will ensure that `!ec` is `true` if there was 86 no error or set to the appropriate error code if there was one. 87 ] 88][ 89 [`a.finish(ec)`] 90 [] 91 [ 92 This function is called when no more body octets are remaining. 93 The function will ensure that `!ec` is `true` if there was 94 no error or set to the appropriate error code if there was one. 95 ] 96][ 97 [`is_body_reader<B>`] 98 [`std::true_type`] 99 [ 100 An alias for `std::true_type` for `B`, otherwise an alias 101 for `std::false_type`. 102 ] 103]] 104 105[heading Exemplar] 106 107[concept_BodyReader] 108 109[heading Models] 110 111* [link beast.ref.boost__beast__http__basic_dynamic_body.reader `basic_dynamic_body::reader`] 112* [link beast.ref.boost__beast__http__basic_file_body__reader `basic_file_body::reader`] 113* [link beast.ref.boost__beast__http__basic_string_body.reader `basic_string_body::reader`] 114* [link beast.ref.boost__beast__http__buffer_body.reader `buffer_body::reader`] 115* [link beast.ref.boost__beast__http__empty_body.reader `empty_body::reader`] 116* [link beast.ref.boost__beast__http__span_body.reader `span_body::reader`] 117* [link beast.ref.boost__beast__http__vector_body.reader `vector_body::reader`] 118 119[endsect] 120