summaryrefslogtreecommitdiff
path: root/boost/beast/http/write.hpp
diff options
context:
space:
mode:
Diffstat (limited to 'boost/beast/http/write.hpp')
-rw-r--r--boost/beast/http/write.hpp569
1 files changed, 569 insertions, 0 deletions
diff --git a/boost/beast/http/write.hpp b/boost/beast/http/write.hpp
new file mode 100644
index 0000000000..755ed0b94b
--- /dev/null
+++ b/boost/beast/http/write.hpp
@@ -0,0 +1,569 @@
+//
+// Copyright (c) 2016-2017 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
+//
+
+#ifndef BOOST_BEAST_HTTP_WRITE_HPP
+#define BOOST_BEAST_HTTP_WRITE_HPP
+
+#include <boost/beast/core/detail/config.hpp>
+#include <boost/beast/core/buffers_cat.hpp>
+#include <boost/beast/core/buffers_suffix.hpp>
+#include <boost/beast/core/multi_buffer.hpp>
+#include <boost/beast/http/message.hpp>
+#include <boost/beast/http/serializer.hpp>
+#include <boost/beast/http/detail/chunk_encode.hpp>
+#include <boost/beast/core/error.hpp>
+#include <boost/beast/core/string.hpp>
+#include <boost/asio/async_result.hpp>
+#include <iosfwd>
+#include <limits>
+#include <memory>
+#include <type_traits>
+#include <utility>
+
+namespace boost {
+namespace beast {
+namespace http {
+
+/** Write part of a message to a stream using a serializer.
+
+ This function is used to write part of a message to a stream using
+ a caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li One or more bytes have been transferred.
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs on the stream.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ The amount of data actually transferred is controlled by the behavior
+ of the underlying stream, subject to the buffer size limit of the
+ serializer obtained or set through a call to @ref serializer::limit.
+ Setting a limit and performing bounded work helps applications set
+ reasonable timeouts. It also allows application-level flow control
+ to function correctly. For example when using a TCP/IP based
+ stream.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @return The number of bytes written to the stream.
+
+ @throws system_error Thrown on failure.
+
+ @see serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write_some(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr);
+
+/** Write part of a message to a stream using a serializer.
+
+ This function is used to write part of a message to a stream using
+ a caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li One or more bytes have been transferred.
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs on the stream.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ The amount of data actually transferred is controlled by the behavior
+ of the underlying stream, subject to the buffer size limit of the
+ serializer obtained or set through a call to @ref serializer::limit.
+ Setting a limit and performing bounded work helps applications set
+ reasonable timeouts. It also allows application-level flow control
+ to function correctly. For example when using a TCP/IP based
+ stream.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @param ec Set to indicate what error occurred, if any.
+
+ @return The number of bytes written to the stream.
+
+ @see @ref async_write_some, @ref serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write_some(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ error_code& ec);
+
+/** Write part of a message to a stream asynchronously using a serializer.
+
+ This function is used to write part of a message to a stream
+ asynchronously using a caller-provided HTTP/1 serializer. The function
+ call always returns immediately. The asynchronous operation will continue
+ until one of the following conditions is true:
+
+ @li One or more bytes have been transferred.
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs on the stream.
+
+ This operation is implemented in terms of zero or more calls to the stream's
+ `async_write_some` function, and is known as a <em>composed operation</em>.
+ The program must ensure that the stream performs no other writes
+ until this operation completes.
+
+ The amount of data actually transferred is controlled by the behavior
+ of the underlying stream, subject to the buffer size limit of the
+ serializer obtained or set through a call to @ref serializer::limit.
+ Setting a limit and performing bounded work helps applications set
+ reasonable timeouts. It also allows application-level flow control
+ to function correctly. For example when using a TCP/IP based
+ stream.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b AsyncWriteStream concept.
+
+ @param sr The serializer to use.
+ The object must remain valid at least until the
+ handler is called; ownership is not transferred.
+
+ @param handler The handler to be called when the operation
+ completes. Copies will be made of the handler as required.
+ The equivalent function signature of the handler must be:
+ @code void handler(
+ error_code const& error, // result of operation
+ std::size_t bytes_transferred // the number of bytes written to the stream
+ ); @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `boost::asio::io_context::post`.
+
+ @see @ref serializer
+*/
+template<
+ class AsyncWriteStream,
+ bool isRequest, class Body, class Fields,
+ class WriteHandler>
+BOOST_ASIO_INITFN_RESULT_TYPE(
+ WriteHandler, void(error_code, std::size_t))
+async_write_some(
+ AsyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ WriteHandler&& handler);
+
+//------------------------------------------------------------------------------
+
+/** Write a header to a stream using a serializer.
+
+ This function is used to write a header to a stream using a
+ caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li The function @ref serializer::is_header_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @return The number of bytes written to the stream.
+
+ @throws system_error Thrown on failure.
+
+ @note The implementation will call @ref serializer::split with
+ the value `true` on the serializer passed in.
+
+ @see @ref serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write_header(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr);
+
+/** Write a header to a stream using a serializer.
+
+ This function is used to write a header to a stream using a
+ caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li The function @ref serializer::is_header_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @param ec Set to indicate what error occurred, if any.
+
+ @return The number of bytes written to the stream.
+
+ @note The implementation will call @ref serializer::split with
+ the value `true` on the serializer passed in.
+
+ @see @ref serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write_header(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ error_code& ec);
+
+/** Write a header to a stream asynchronously using a serializer.
+
+ This function is used to write a header to a stream asynchronously
+ using a caller-provided HTTP/1 serializer. The function call always
+ returns immediately. The asynchronous operation will continue until
+ one of the following conditions is true:
+
+ @li The function @ref serializer::is_header_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of zero or more calls to the stream's
+ `async_write_some` function, and is known as a <em>composed operation</em>.
+ The program must ensure that the stream performs no other writes
+ until this operation completes.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b AsyncWriteStream concept.
+
+ @param sr The serializer to use.
+ The object must remain valid at least until the
+ handler is called; ownership is not transferred.
+
+ @param handler The handler to be called when the operation
+ completes. Copies will be made of the handler as required.
+ The equivalent function signature of the handler must be:
+ @code void handler(
+ error_code const& error, // result of operation
+ std::size_t bytes_transferred // the number of bytes written to the stream
+ ); @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `boost::asio::io_context::post`.
+
+ @note The implementation will call @ref serializer::split with
+ the value `true` on the serializer passed in.
+
+ @see @ref serializer
+*/
+template<
+ class AsyncWriteStream,
+ bool isRequest, class Body, class Fields,
+ class WriteHandler>
+BOOST_ASIO_INITFN_RESULT_TYPE(
+ WriteHandler, void(error_code, std::size_t))
+async_write_header(
+ AsyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ WriteHandler&& handler);
+
+//------------------------------------------------------------------------------
+
+/** Write a complete message to a stream using a serializer.
+
+ This function is used to write a complete message to a stream using
+ a caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @return The number of bytes written to the stream.
+
+ @throws system_error Thrown on failure.
+
+ @see @ref serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr);
+
+/** Write a complete message to a stream using a serializer.
+
+ This function is used to write a complete message to a stream using
+ a caller-provided HTTP/1 serializer. The call will block until one
+ of the following conditions is true:
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls
+ to the stream's `write_some` function.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param sr The serializer to use.
+
+ @param ec Set to the error, if any occurred.
+
+ @return The number of bytes written to the stream.
+
+ @see @ref serializer
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write(
+ SyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ error_code& ec);
+
+/** Write a complete message to a stream asynchronously using a serializer.
+
+ This function is used to write a complete message to a stream
+ asynchronously using a caller-provided HTTP/1 serializer. The
+ function call always returns immediately. The asynchronous
+ operation will continue until one of the following conditions is true:
+
+ @li The function @ref serializer::is_done returns `true`
+
+ @li An error occurs.
+
+ This operation is implemented in terms of zero or more calls to the stream's
+ `async_write_some` function, and is known as a <em>composed operation</em>.
+ The program must ensure that the stream performs no other writes
+ until this operation completes.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b AsyncWriteStream concept.
+
+ @param sr The serializer to use.
+ The object must remain valid at least until the
+ handler is called; ownership is not transferred.
+
+ @param handler The handler to be called when the operation
+ completes. Copies will be made of the handler as required.
+ The equivalent function signature of the handler must be:
+ @code void handler(
+ error_code const& error, // result of operation
+ std::size_t bytes_transferred // the number of bytes written to the stream
+ ); @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `boost::asio::io_context::post`.
+
+ @see @ref serializer
+*/
+template<
+ class AsyncWriteStream,
+ bool isRequest, class Body, class Fields,
+ class WriteHandler>
+BOOST_ASIO_INITFN_RESULT_TYPE(
+ WriteHandler, void(error_code, std::size_t))
+async_write(
+ AsyncWriteStream& stream,
+ serializer<isRequest, Body, Fields>& sr,
+ WriteHandler&& handler);
+
+//------------------------------------------------------------------------------
+
+/** Write a complete message to a stream.
+
+ This function is used to write a complete message to a stream using
+ HTTP/1. The call will block until one of the following conditions is true:
+
+ @li The entire message is written.
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls to the stream's
+ `write_some` function. The algorithm will use a temporary @ref serializer
+ with an empty chunk decorator to produce buffers.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param msg The message to write.
+
+ @return The number of bytes written to the stream.
+
+ @throws system_error Thrown on failure.
+
+ @see @ref message
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write(
+ SyncWriteStream& stream,
+ message<isRequest, Body, Fields> const& msg);
+
+/** Write a complete message to a stream.
+
+ This function is used to write a complete message to a stream using
+ HTTP/1. The call will block until one of the following conditions is true:
+
+ @li The entire message is written.
+
+ @li An error occurs.
+
+ This operation is implemented in terms of one or more calls to the stream's
+ `write_some` function. The algorithm will use a temporary @ref serializer
+ with an empty chunk decorator to produce buffers.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b SyncWriteStream concept.
+
+ @param msg The message to write.
+
+ @param ec Set to the error, if any occurred.
+
+ @return The number of bytes written to the stream.
+
+ @see @ref message
+*/
+template<
+ class SyncWriteStream,
+ bool isRequest, class Body, class Fields>
+std::size_t
+write(
+ SyncWriteStream& stream,
+ message<isRequest, Body, Fields> const& msg,
+ error_code& ec);
+
+/** Write a complete message to a stream asynchronously.
+
+ This function is used to write a complete message to a stream asynchronously
+ using HTTP/1. The function call always returns immediately. The asynchronous
+ operation will continue until one of the following conditions is true:
+
+ @li The entire message is written.
+
+ @li An error occurs.
+
+ This operation is implemented in terms of zero or more calls to the stream's
+ `async_write_some` function, and is known as a <em>composed operation</em>.
+ The program must ensure that the stream performs no other writes
+ until this operation completes. The algorithm will use a temporary
+ @ref serializer with an empty chunk decorator to produce buffers.
+
+ @param stream The stream to which the data is to be written.
+ The type must support the @b AsyncWriteStream concept.
+
+ @param msg The message to write.
+ The object must remain valid at least until the
+ handler is called; ownership is not transferred.
+
+ @param handler The handler to be called when the operation
+ completes. Copies will be made of the handler as required.
+ The equivalent function signature of the handler must be:
+ @code void handler(
+ error_code const& error, // result of operation
+ std::size_t bytes_transferred // the number of bytes written to the stream
+ ); @endcode
+ Regardless of whether the asynchronous operation completes
+ immediately or not, the handler will not be invoked from within
+ this function. Invocation of the handler will be performed in a
+ manner equivalent to using `boost::asio::io_context::post`.
+
+ @see @ref message
+*/
+template<
+ class AsyncWriteStream,
+ bool isRequest, class Body, class Fields,
+ class WriteHandler>
+BOOST_ASIO_INITFN_RESULT_TYPE(
+ WriteHandler, void(error_code, std::size_t))
+async_write(
+ AsyncWriteStream& stream,
+ message<isRequest, Body, Fields>& msg,
+ WriteHandler&& handler);
+
+//------------------------------------------------------------------------------
+
+/** Serialize an HTTP/1 header to a `std::ostream`.
+
+ The function converts the header to its HTTP/1 serialized
+ representation and stores the result in the output stream.
+
+ @param os The output stream to write to.
+
+ @param msg The message fields to write.
+*/
+template<bool isRequest, class Fields>
+std::ostream&
+operator<<(std::ostream& os,
+ header<isRequest, Fields> const& msg);
+
+/** Serialize an HTTP/1 message to a `std::ostream`.
+
+ The function converts the message to its HTTP/1 serialized
+ representation and stores the result in the output stream.
+
+ The implementation will automatically perform chunk encoding if
+ the contents of the message indicate that chunk encoding is required.
+
+ @param os The output stream to write to.
+
+ @param msg The message to write.
+*/
+template<bool isRequest, class Body, class Fields>
+std::ostream&
+operator<<(std::ostream& os,
+ message<isRequest, Body, Fields> const& msg);
+
+} // http
+} // beast
+} // boost
+
+#include <boost/beast/http/impl/write.ipp>
+
+#endif