Line data    Source code

       1             : //
       2             : // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.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/CPPAlliance/http_proto
       8             : //
       9             : 
      10             : #ifndef BOOST_HTTP_PROTO_SOURCE_HPP
      11             : #define BOOST_HTTP_PROTO_SOURCE_HPP
      12             : 
      13             : #include <boost/http_proto/detail/config.hpp>
      14             : #include <boost/http_proto/buffer.hpp>
      15             : #include <boost/http_proto/error_types.hpp>
      16             : #include <boost/http_proto/string_view.hpp>
      17             : 
      18             : namespace boost {
      19             : namespace http_proto {
      20             : 
      21             : /** A source of body data
      22             : */
      23             : struct BOOST_SYMBOL_VISIBLE
      24          12 :     source
      25             : {
      26             :     /** A function to reserve a buffer
      27             : 
      28             :         This function object may be called
      29             :         up to one time to reserve intermediate
      30             :         storage.
      31             :     */
      32             :     struct BOOST_SYMBOL_VISIBLE
      33           6 :         reserve_fn
      34             :     {
      35             :         /** Return a buffer of at least n bytes.
      36             : 
      37             :             This function reserves space for
      38             :             a buffer of at least `n` bytes in
      39             :             size. If there is insufficient space
      40             :             available, an exception is thrown.
      41             :             Undefined behavior results if this
      42             :             function is invoked more than once.
      43             : 
      44             :             @par Exceptions
      45             :             Calls to allocate may throw.
      46             : 
      47             :             @param n The size of the buffer.
      48             :         */
      49             :         BOOST_HTTP_PROTO_DECL
      50             :         virtual
      51             :         void*
      52             :         operator()(
      53             :             std::size_t n) const = 0;
      54             : 
      55             :     protected:
      56             :         virtual ~reserve_fn() = 0;
      57             :     };
      58             : 
      59             :     /** The results of reading from the source.
      60             :     */
      61             :     struct results
      62             :     {
      63             :         error_code ec;
      64             :         std::size_t bytes = 0;
      65             :         bool more = false;
      66             :     };
      67             : 
      68             :     /** Destructor
      69             :     */
      70             :     BOOST_HTTP_PROTO_DECL
      71             :     virtual
      72             :     ~source() = 0;
      73             : 
      74             :     /** Called to allow the source to reserve memory.
      75             : 
      76             :         This function is invoked once before
      77             :         serialization begins to give the source
      78             :         an opportunity to reserve temporary
      79             :         storage. The default implementation
      80             :         does nothing.
      81             :         <br>
      82             :         The `reserve` function object only
      83             :         remains valid until `maybe_reserve`
      84             :         returns.
      85             : 
      86             :         @param limit The maximum number of bytes
      87             :         which may be reserved.
      88             : 
      89             :         @param reserve A function object to
      90             :         invoke up to one time in order to
      91             :         obtain a buffer.
      92             :     */
      93             :     BOOST_HTTP_PROTO_DECL
      94             :     virtual
      95             :     void
      96             :     maybe_reserve(
      97             :         std::size_t limit,
      98             :         reserve_fn const& reserve);
      99             : 
     100             :     /** Called when more data is required
     101             : 
     102             :         This function is invoked when more data
     103             :         is required. The subclass should place
     104             :         zero or more bytes into the buffers
     105             :         referenced by `dest`, and return a
     106             :         `results` value with the members set
     107             :         appropriately.
     108             :         <br>
     109             :         Partial success is possible.
     110             :     */
     111             :     virtual
     112             :     results
     113             :     read(
     114             :         mutable_buffers_pair dest) = 0;
     115             : };
     116             : 
     117             : /** Metafunction which determines if T is a source
     118             : 
     119             :     @see
     120             :         @ref source.
     121             : */
     122             : #ifdef BOOST_HTTP_PROTO_DOCS
     123             : template<class T>
     124             : using is_source = __see_below__;
     125             : #else
     126             : template<class T>
     127             : using is_source =
     128             :     std::is_convertible<
     129             :         typename std::decay<T>::type*,
     130             :         source*>;
     131             : #endif
     132             : 
     133             : } // http_proto
     134             : } // boost
     135             : 
     136             : #endif