boost/beast/http/write.hpp
//
// 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
//
#ifndef BOOST_BEAST_HTTP_WRITE_HPP
#define BOOST_BEAST_HTTP_WRITE_HPP
#include <boost/beast/core/detail/config.hpp>
#include <boost/beast/http/message.hpp>
#include <boost/beast/http/serializer.hpp>
#include <boost/beast/http/type_traits.hpp>
#include <boost/beast/http/detail/chunk_encode.hpp>
#include <boost/beast/core/error.hpp>
#include <boost/beast/core/stream_traits.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 <em>SyncWriteStream</em> 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 <em>SyncWriteStream</em> 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 async_write_some, 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 <em>AsyncWriteStream</em> 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 completion handler to invoke when the operation
completes. The implementation takes ownership of the handler by
performing a decay-copy. 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
If the handler has an associated immediate executor,
an immediate completion will be dispatched to it.
Otherwise, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `net::post`.
@par Per-Operation Cancellation
This asynchronous operation supports cancellation for the following
net::cancellation_type values:
@li @c net::cancellation_type::terminal
if the `stream` also supports terminal cancellation, `terminal`
cancellation leaves the stream in an undefined state, so that only
closing it is guaranteed to succeed.
@see serializer
*/
template<
class AsyncWriteStream,
bool isRequest, class Body, class Fields,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write_some(
AsyncWriteStream& stream,
serializer<isRequest, Body, Fields>& sr,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>{});
//------------------------------------------------------------------------------
/** 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 <em>SyncWriteStream</em> 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 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 <em>SyncWriteStream</em> 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 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 <em>AsyncWriteStream</em> 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 completion handler to invoke when the operation
completes. The implementation takes ownership of the handler by
performing a decay-copy. 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
If the handler has an associated immediate executor,
an immediate completion will be dispatched to it.
Otherwise, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `net::post`.
@note The implementation will call @ref serializer::split with
the value `true` on the serializer passed in.
@par Per-Operation Cancellation
This asynchronous operation supports cancellation for the following
net::cancellation_type values:
@li @c net::cancellation_type::terminal
if the `stream` also supports terminal cancellation, `terminal`
cancellation leaves the stream in an undefined state, so that only
closing it is guaranteed to succeed.
@see serializer
*/
template<
class AsyncWriteStream,
bool isRequest, class Body, class Fields,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write_header(
AsyncWriteStream& stream,
serializer<isRequest, Body, Fields>& sr,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>{});
//------------------------------------------------------------------------------
/** 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 <em>SyncWriteStream</em> 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(
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 <em>SyncWriteStream</em> 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 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 <em>AsyncWriteStream</em> 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 completion handler to invoke when the operation
completes. The implementation takes ownership of the handler by
performing a decay-copy. 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
If the handler has an associated immediate executor,
an immediate completion will be dispatched to it.
Otherwise, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `net::post`.
@par Per-Operation Cancellation
This asynchronous operation supports cancellation for the following
net::cancellation_type values:
@li @c net::cancellation_type::terminal
if the `stream` also supports terminal cancellation, `terminal`
cancellation leaves the stream in an undefined state, so that only
closing it is guaranteed to succeed.
@see serializer
*/
template<
class AsyncWriteStream,
bool isRequest, class Body, class Fields,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write(
AsyncWriteStream& stream,
serializer<isRequest, Body, Fields>& sr,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>{});
//------------------------------------------------------------------------------
/** 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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `true`.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> concept.
@param msg The message to write.
@return The number of bytes written to the stream.
@throws system_error Thrown on failure.
@see message
*/
template<
class SyncWriteStream,
bool isRequest, class Body, class Fields>
#if BOOST_BEAST_DOXYGEN
std::size_t
#else
typename std::enable_if<
is_mutable_body_writer<Body>::value,
std::size_t>::type
#endif
write(
SyncWriteStream& stream,
message<isRequest, Body, Fields>& 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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `false`.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> concept.
@param msg The message to write.
@return The number of bytes written to the stream.
@throws system_error Thrown on failure.
@see message
*/
template<
class SyncWriteStream,
bool isRequest, class Body, class Fields>
#if BOOST_BEAST_DOXYGEN
std::size_t
#else
typename std::enable_if<
! is_mutable_body_writer<Body>::value,
std::size_t>::type
#endif
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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `true`.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> 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 message
*/
template<
class SyncWriteStream,
bool isRequest, class Body, class Fields>
#if BOOST_BEAST_DOXYGEN
std::size_t
#else
typename std::enable_if<
is_mutable_body_writer<Body>::value,
std::size_t>::type
#endif
write(
SyncWriteStream& stream,
message<isRequest, Body, Fields>& msg,
error_code& ec);
/** 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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `false`.
@param stream The stream to which the data is to be written.
The type must support the <em>SyncWriteStream</em> 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 message
*/
template<
class SyncWriteStream,
bool isRequest, class Body, class Fields>
#if BOOST_BEAST_DOXYGEN
std::size_t
#else
typename std::enable_if<
! is_mutable_body_writer<Body>::value,
std::size_t>::type
#endif
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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `true`.
@param stream The stream to which the data is to be written.
The type must support the <em>AsyncWriteStream</em> 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 completion handler to invoke when the operation
completes. The implementation takes ownership of the handler by
performing a decay-copy. 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
If the handler has an associated immediate executor,
an immediate completion will be dispatched to it.
Otherwise, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `net::post`.
@par Per-Operation Cancellation
This asynchronous operation supports cancellation for the following
net::cancellation_type values:
@li @c net::cancellation_type::terminal
if the `stream` also supports terminal cancellation, `terminal`
cancellation leaves the stream in an undefined state, so that only
closing it is guaranteed to succeed.
@see message
*/
template<
class AsyncWriteStream,
bool isRequest, class Body, class Fields,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write(
AsyncWriteStream& stream,
message<isRequest, Body, Fields>& msg,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>{}
#ifndef BOOST_BEAST_DOXYGEN
, typename std::enable_if<
is_mutable_body_writer<Body>::value>::type* = 0
#endif
);
/** 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.
@note This function only participates in overload resolution
if @ref is_mutable_body_writer for <em>Body</em> returns `false`.
@param stream The stream to which the data is to be written.
The type must support the <em>AsyncWriteStream</em> 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 completion handler to invoke when the operation
completes. The implementation takes ownership of the handler by
performing a decay-copy. 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
If the handler has an associated immediate executor,
an immediate completion will be dispatched to it.
Otherwise, the handler will not be invoked from within
this function. Invocation of the handler will be performed in a
manner equivalent to using `net::post`.
@par Per-Operation Cancellation
This asynchronous operation supports cancellation for the following
net::cancellation_type values:
@li @c net::cancellation_type::terminal
if the `stream` also supports terminal cancellation, `terminal`
cancellation leaves the stream in an undefined state, so that only
closing it is guaranteed to succeed.
@see message
*/
template<
class AsyncWriteStream,
bool isRequest, class Body, class Fields,
BOOST_BEAST_ASYNC_TPARAM2 WriteHandler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>>
BOOST_BEAST_ASYNC_RESULT2(WriteHandler)
async_write(
AsyncWriteStream& stream,
message<isRequest, Body, Fields> const& msg,
WriteHandler&& handler =
net::default_completion_token_t<
executor_type<AsyncWriteStream>>{}
#ifndef BOOST_BEAST_DOXYGEN
, typename std::enable_if<
! is_mutable_body_writer<Body>::value>::type* = 0
#endif
);
//------------------------------------------------------------------------------
/** 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.hpp>
#endif