ceph/src/boost/boost/beast/http/write.hpp

   1 //
   2 // Copyright (c) 2016-2017 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 #ifndef BOOST_BEAST_HTTP_WRITE_HPP
  11 #define BOOST_BEAST_HTTP_WRITE_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/core/buffers_cat.hpp>
  15 #include <boost/beast/core/buffers_suffix.hpp>
  16 #include <boost/beast/core/multi_buffer.hpp>
  17 #include <boost/beast/http/message.hpp>
  18 #include <boost/beast/http/serializer.hpp>
  19 #include <boost/beast/http/detail/chunk_encode.hpp>
  20 #include <boost/beast/core/error.hpp>
  21 #include <boost/beast/core/string.hpp>
  22 #include <boost/asio/async_result.hpp>
  23 #include <iosfwd>
  24 #include <limits>
  25 #include <memory>
  26 #include <type_traits>
  27 #include <utility>
  28
  29 namespace boost {
  30 namespace beast {
  31 namespace http {
  32
  33 /** Write part of a message to a stream using a serializer.
  34
  35     This function is used to write part of a message to a stream using
  36     a caller-provided HTTP/1 serializer. The call will block until one
  37     of the following conditions is true:
  38
  39     @li One or more bytes have been transferred.
  40
  41     @li The function @ref serializer::is_done returns `true`
  42
  43     @li An error occurs on the stream.
  44
  45     This operation is implemented in terms of one or more calls
  46     to the stream's `write_some` function.
  47
  48     The amount of data actually transferred is controlled by the behavior
  49     of the underlying stream, subject to the buffer size limit of the
  50     serializer obtained or set through a call to @ref serializer::limit.
  51     Setting a limit and performing bounded work helps applications set
  52     reasonable timeouts. It also allows application-level flow control
  53     to function correctly. For example when using a TCP/IP based
  54     stream.
  55
  56     @param stream The stream to which the data is to be written.
  57     The type must support the @b SyncWriteStream concept.
  58
  59     @param sr The serializer to use.
  60
  61     @return The number of bytes written to the stream.
  62
  63     @throws system_error Thrown on failure.
  64
  65     @see serializer
  66 */
  67 template<
  68     class SyncWriteStream,
  69     bool isRequest, class Body, class Fields>
  70 std::size_t
  71 write_some(
  72     SyncWriteStream& stream,
  73     serializer<isRequest, Body, Fields>& sr);
  74
  75 /** Write part of a message to a stream using a serializer.
  76
  77     This function is used to write part of a message to a stream using
  78     a caller-provided HTTP/1 serializer. The call will block until one
  79     of the following conditions is true:
  80
  81     @li One or more bytes have been transferred.
  82
  83     @li The function @ref serializer::is_done returns `true`
  84
  85     @li An error occurs on the stream.
  86
  87     This operation is implemented in terms of one or more calls
  88     to the stream's `write_some` function.
  89
  90     The amount of data actually transferred is controlled by the behavior
  91     of the underlying stream, subject to the buffer size limit of the
  92     serializer obtained or set through a call to @ref serializer::limit.
  93     Setting a limit and performing bounded work helps applications set
  94     reasonable timeouts. It also allows application-level flow control
  95     to function correctly. For example when using a TCP/IP based
  96     stream.
  97
  98     @param stream The stream to which the data is to be written.
  99     The type must support the @b SyncWriteStream concept.
 100
 101     @param sr The serializer to use.
 102
 103     @param ec Set to indicate what error occurred, if any.
 104
 105     @return The number of bytes written to the stream.
 106
 107     @see @ref async_write_some, @ref serializer
 108 */
 109 template<
 110     class SyncWriteStream,
 111     bool isRequest, class Body, class Fields>
 112 std::size_t
 113 write_some(
 114     SyncWriteStream& stream,
 115     serializer<isRequest, Body, Fields>& sr,
 116     error_code& ec);
 117
 118 /** Write part of a message to a stream asynchronously using a serializer.
 119
 120     This function is used to write part of a message to a stream
 121     asynchronously using a caller-provided HTTP/1 serializer. The function
 122     call always returns immediately. The asynchronous operation will continue
 123     until one of the following conditions is true:
 124
 125     @li One or more bytes have been transferred.
 126
 127     @li The function @ref serializer::is_done returns `true`
 128
 129     @li An error occurs on the stream.
 130
 131     This operation is implemented in terms of zero or more calls to the stream's
 132     `async_write_some` function, and is known as a <em>composed operation</em>.
 133     The program must ensure that the stream performs no other writes
 134     until this operation completes.
 135
 136     The amount of data actually transferred is controlled by the behavior
 137     of the underlying stream, subject to the buffer size limit of the
 138     serializer obtained or set through a call to @ref serializer::limit.
 139     Setting a limit and performing bounded work helps applications set
 140     reasonable timeouts. It also allows application-level flow control
 141     to function correctly. For example when using a TCP/IP based
 142     stream.
 143
 144     @param stream The stream to which the data is to be written.
 145     The type must support the @b AsyncWriteStream concept.
 146
 147     @param sr The serializer to use.
 148     The object must remain valid at least until the
 149     handler is called; ownership is not transferred.
 150
 151     @param handler The handler to be called when the operation
 152     completes. Copies will be made of the handler as required.
 153     The equivalent function signature of the handler must be:
 154     @code void handler(
 155         error_code const& error,        // result of operation
 156         std::size_t bytes_transferred   // the number of bytes written to the stream
 157     ); @endcode
 158     Regardless of whether the asynchronous operation completes
 159     immediately or not, the handler will not be invoked from within
 160     this function. Invocation of the handler will be performed in a
 161     manner equivalent to using `boost::asio::io_context::post`.
 162
 163     @see @ref serializer
 164 */
 165 template<
 166     class AsyncWriteStream,
 167     bool isRequest, class Body, class Fields,
 168     class WriteHandler>
 169 BOOST_ASIO_INITFN_RESULT_TYPE(
 170     WriteHandler, void(error_code, std::size_t))
 171 async_write_some(
 172     AsyncWriteStream& stream,
 173     serializer<isRequest, Body, Fields>& sr,
 174     WriteHandler&& handler);
 175
 176 //------------------------------------------------------------------------------
 177
 178 /** Write a header to a stream using a serializer.
 179
 180     This function is used to write a header to a stream using a
 181     caller-provided HTTP/1 serializer. The call will block until one
 182     of the following conditions is true:
 183
 184     @li The function @ref serializer::is_header_done returns `true`
 185
 186     @li An error occurs.
 187
 188     This operation is implemented in terms of one or more calls
 189     to the stream's `write_some` function.
 190
 191     @param stream The stream to which the data is to be written.
 192     The type must support the @b SyncWriteStream concept.
 193
 194     @param sr The serializer to use.
 195
 196     @return The number of bytes written to the stream.
 197
 198     @throws system_error Thrown on failure.
 199
 200     @note The implementation will call @ref serializer::split with
 201     the value `true` on the serializer passed in.
 202
 203     @see @ref serializer
 204 */
 205 template<
 206     class SyncWriteStream,
 207     bool isRequest, class Body, class Fields>
 208 std::size_t
 209 write_header(
 210     SyncWriteStream& stream,
 211     serializer<isRequest, Body, Fields>& sr);
 212
 213 /** Write a header to a stream using a serializer.
 214
 215     This function is used to write a header to a stream using a
 216     caller-provided HTTP/1 serializer. The call will block until one
 217     of the following conditions is true:
 218
 219     @li The function @ref serializer::is_header_done returns `true`
 220
 221     @li An error occurs.
 222
 223     This operation is implemented in terms of one or more calls
 224     to the stream's `write_some` function.
 225
 226     @param stream The stream to which the data is to be written.
 227     The type must support the @b SyncWriteStream concept.
 228
 229     @param sr The serializer to use.
 230
 231     @param ec Set to indicate what error occurred, if any.
 232
 233     @return The number of bytes written to the stream.
 234
 235     @note The implementation will call @ref serializer::split with
 236     the value `true` on the serializer passed in.
 237
 238     @see @ref serializer
 239 */
 240 template<
 241     class SyncWriteStream,
 242     bool isRequest, class Body, class Fields>
 243 std::size_t
 244 write_header(
 245     SyncWriteStream& stream,
 246     serializer<isRequest, Body, Fields>& sr,
 247     error_code& ec);
 248
 249 /** Write a header to a stream asynchronously using a serializer.
 250
 251     This function is used to write a header to a stream asynchronously
 252     using a caller-provided HTTP/1 serializer. The function call always
 253     returns immediately. The asynchronous operation will continue until
 254     one of the following conditions is true:
 255
 256     @li The function @ref serializer::is_header_done returns `true`
 257
 258     @li An error occurs.
 259
 260     This operation is implemented in terms of zero or more calls to the stream's
 261     `async_write_some` function, and is known as a <em>composed operation</em>.
 262     The program must ensure that the stream performs no other writes
 263     until this operation completes.
 264
 265     @param stream The stream to which the data is to be written.
 266     The type must support the @b AsyncWriteStream concept.
 267
 268     @param sr The serializer to use.
 269     The object must remain valid at least until the
 270     handler is called; ownership is not transferred.
 271
 272     @param handler The handler to be called when the operation
 273     completes. Copies will be made of the handler as required.
 274     The equivalent function signature of the handler must be:
 275     @code void handler(
 276         error_code const& error,        // result of operation
 277         std::size_t bytes_transferred   // the number of bytes written to the stream
 278     ); @endcode
 279     Regardless of whether the asynchronous operation completes
 280     immediately or not, the handler will not be invoked from within
 281     this function. Invocation of the handler will be performed in a
 282     manner equivalent to using `boost::asio::io_context::post`.
 283
 284     @note The implementation will call @ref serializer::split with
 285     the value `true` on the serializer passed in.
 286
 287     @see @ref serializer
 288 */
 289 template<
 290     class AsyncWriteStream,
 291     bool isRequest, class Body, class Fields,
 292     class WriteHandler>
 293 BOOST_ASIO_INITFN_RESULT_TYPE(
 294     WriteHandler, void(error_code, std::size_t))
 295 async_write_header(
 296     AsyncWriteStream& stream,
 297     serializer<isRequest, Body, Fields>& sr,
 298     WriteHandler&& handler);
 299
 300 //------------------------------------------------------------------------------
 301
 302 /** Write a complete message to a stream using a serializer.
 303
 304     This function is used to write a complete message to a stream using
 305     a caller-provided HTTP/1 serializer. The call will block until one
 306     of the following conditions is true:
 307
 308     @li The function @ref serializer::is_done returns `true`
 309
 310     @li An error occurs.
 311
 312     This operation is implemented in terms of one or more calls
 313     to the stream's `write_some` function.
 314
 315     @param stream The stream to which the data is to be written.
 316     The type must support the @b SyncWriteStream concept.
 317
 318     @param sr The serializer to use.
 319
 320     @return The number of bytes written to the stream.
 321
 322     @throws system_error Thrown on failure.
 323
 324     @see @ref serializer
 325 */
 326 template<
 327     class SyncWriteStream,
 328     bool isRequest, class Body, class Fields>
 329 std::size_t
 330 write(
 331     SyncWriteStream& stream,
 332     serializer<isRequest, Body, Fields>& sr);
 333
 334 /** Write a complete message to a stream using a serializer.
 335
 336     This function is used to write a complete message to a stream using
 337     a caller-provided HTTP/1 serializer. The call will block until one
 338     of the following conditions is true:
 339
 340     @li The function @ref serializer::is_done returns `true`
 341
 342     @li An error occurs.
 343
 344     This operation is implemented in terms of one or more calls
 345     to the stream's `write_some` function.
 346
 347     @param stream The stream to which the data is to be written.
 348     The type must support the @b SyncWriteStream concept.
 349
 350     @param sr The serializer to use.
 351
 352     @param ec Set to the error, if any occurred.
 353
 354     @return The number of bytes written to the stream.
 355
 356     @see @ref serializer
 357 */
 358 template<
 359     class SyncWriteStream,
 360     bool isRequest, class Body, class Fields>
 361 std::size_t
 362 write(
 363     SyncWriteStream& stream,
 364     serializer<isRequest, Body, Fields>& sr,
 365    error_code& ec);
 366
 367 /** Write a complete message to a stream asynchronously using a serializer.
 368
 369     This function is used to write a complete message to a stream
 370     asynchronously using a caller-provided HTTP/1 serializer. The
 371     function call always returns immediately. The asynchronous
 372     operation will continue until one of the following conditions is true:
 373
 374     @li The function @ref serializer::is_done returns `true`
 375
 376     @li An error occurs.
 377
 378     This operation is implemented in terms of zero or more calls to the stream's
 379     `async_write_some` function, and is known as a <em>composed operation</em>.
 380     The program must ensure that the stream performs no other writes
 381     until this operation completes.
 382
 383     @param stream The stream to which the data is to be written.
 384     The type must support the @b AsyncWriteStream concept.
 385
 386     @param sr The serializer to use.
 387     The object must remain valid at least until the
 388     handler is called; ownership is not transferred.
 389
 390     @param handler The handler to be called when the operation
 391     completes. Copies will be made of the handler as required.
 392     The equivalent function signature of the handler must be:
 393     @code void handler(
 394         error_code const& error,        // result of operation
 395         std::size_t bytes_transferred   // the number of bytes written to the stream
 396     ); @endcode
 397     Regardless of whether the asynchronous operation completes
 398     immediately or not, the handler will not be invoked from within
 399     this function. Invocation of the handler will be performed in a
 400     manner equivalent to using `boost::asio::io_context::post`.
 401
 402     @see @ref serializer
 403 */
 404 template<
 405     class AsyncWriteStream,
 406     bool isRequest, class Body, class Fields,
 407     class WriteHandler>
 408 BOOST_ASIO_INITFN_RESULT_TYPE(
 409     WriteHandler, void(error_code, std::size_t))
 410 async_write(
 411     AsyncWriteStream& stream,
 412     serializer<isRequest, Body, Fields>& sr,
 413     WriteHandler&& handler);
 414
 415 //------------------------------------------------------------------------------
 416
 417 /** Write a complete message to a stream.
 418
 419     This function is used to write a complete message to a stream using
 420     HTTP/1. The call will block until one of the following conditions is true:
 421
 422     @li The entire message is written.
 423
 424     @li An error occurs.
 425
 426     This operation is implemented in terms of one or more calls to the stream's
 427     `write_some` function. The algorithm will use a temporary @ref serializer
 428     with an empty chunk decorator to produce buffers.
 429
 430     @param stream The stream to which the data is to be written.
 431     The type must support the @b SyncWriteStream concept.
 432
 433     @param msg The message to write.
 434
 435     @return The number of bytes written to the stream.
 436
 437     @throws system_error Thrown on failure.
 438
 439     @see @ref message
 440 */
 441 template<
 442     class SyncWriteStream,
 443     bool isRequest, class Body, class Fields>
 444 std::size_t
 445 write(
 446     SyncWriteStream& stream,
 447     message<isRequest, Body, Fields> const& msg);
 448
 449 /** Write a complete message to a stream.
 450
 451     This function is used to write a complete message to a stream using
 452     HTTP/1. The call will block until one of the following conditions is true:
 453
 454     @li The entire message is written.
 455
 456     @li An error occurs.
 457
 458     This operation is implemented in terms of one or more calls to the stream's
 459     `write_some` function. The algorithm will use a temporary @ref serializer
 460     with an empty chunk decorator to produce buffers.
 461
 462     @param stream The stream to which the data is to be written.
 463     The type must support the @b SyncWriteStream concept.
 464
 465     @param msg The message to write.
 466
 467     @param ec Set to the error, if any occurred.
 468
 469     @return The number of bytes written to the stream.
 470
 471     @see @ref message
 472 */
 473 template<
 474     class SyncWriteStream,
 475     bool isRequest, class Body, class Fields>
 476 std::size_t
 477 write(
 478     SyncWriteStream& stream,
 479     message<isRequest, Body, Fields> const& msg,
 480     error_code& ec);
 481
 482 /** Write a complete message to a stream asynchronously.
 483
 484     This function is used to write a complete message to a stream asynchronously
 485     using HTTP/1. The function call always returns immediately. The asynchronous
 486     operation will continue until one of the following conditions is true:
 487
 488     @li The entire message is written.
 489
 490     @li An error occurs.
 491
 492     This operation is implemented in terms of zero or more calls to the stream's
 493     `async_write_some` function, and is known as a <em>composed operation</em>.
 494     The program must ensure that the stream performs no other writes
 495     until this operation completes. The algorithm will use a temporary
 496     @ref serializer with an empty chunk decorator to produce buffers.
 497
 498     @param stream The stream to which the data is to be written.
 499     The type must support the @b AsyncWriteStream concept.
 500
 501     @param msg The message to write.
 502     The object must remain valid at least until the
 503     handler is called; ownership is not transferred.
 504
 505     @param handler The handler to be called when the operation
 506     completes. Copies will be made of the handler as required.
 507     The equivalent function signature of the handler must be:
 508     @code void handler(
 509         error_code const& error,        // result of operation
 510         std::size_t bytes_transferred   // the number of bytes written to the stream
 511     ); @endcode
 512     Regardless of whether the asynchronous operation completes
 513     immediately or not, the handler will not be invoked from within
 514     this function. Invocation of the handler will be performed in a
 515     manner equivalent to using `boost::asio::io_context::post`.
 516
 517     @see @ref message
 518 */
 519 template<
 520     class AsyncWriteStream,
 521     bool isRequest, class Body, class Fields,
 522     class WriteHandler>
 523 BOOST_ASIO_INITFN_RESULT_TYPE(
 524     WriteHandler, void(error_code, std::size_t))
 525 async_write(
 526     AsyncWriteStream& stream,
 527     message<isRequest, Body, Fields>& msg,
 528     WriteHandler&& handler);
 529
 530 //------------------------------------------------------------------------------
 531
 532 /** Serialize an HTTP/1 header to a `std::ostream`.
 533
 534     The function converts the header to its HTTP/1 serialized
 535     representation and stores the result in the output stream.
 536
 537     @param os The output stream to write to.
 538
 539     @param msg The message fields to write.
 540 */
 541 template<bool isRequest, class Fields>
 542 std::ostream&
 543 operator<<(std::ostream& os,
 544     header<isRequest, Fields> const& msg);
 545
 546 /** Serialize an HTTP/1 message to a `std::ostream`.
 547
 548     The function converts the message to its HTTP/1 serialized
 549     representation and stores the result in the output stream.
 550
 551     The implementation will automatically perform chunk encoding if
 552     the contents of the message indicate that chunk encoding is required.
 553
 554     @param os The output stream to write to.
 555
 556     @param msg The message to write.
 557 */
 558 template<bool isRequest, class Body, class Fields>
 559 std::ostream&
 560 operator<<(std::ostream& os,
 561     message<isRequest, Body, Fields> const& msg);
 562
 563 } // http
 564 } // beast
 565 } // boost
 566
 567 #include <boost/beast/http/impl/write.ipp>
 568
 569 #endif