1[/ 2 Copyright (c) 2013-2016 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 8[section:boost__beast__allocate_stable allocate_stable] 9[indexterm1 allocate_stable] 10Allocate a temporary object to hold stable asynchronous operation state. 11[heading Synopsis] 12 13Defined in header [include_file boost/beast/core/async_base.hpp] 14 15 16 17``` 18template< 19 class State, 20 class __Handler__, 21 class __Executor1__, 22 class __Allocator__, 23 class... Args> 24State& 25allocate_stable( 26 stable_async_base< Handler, Executor1, Allocator >& base, 27 Args&&... args); 28 29``` 30 31[heading Description] 32The object will be destroyed just before the completion handler is invoked, or when the base is destroyed. 33[heading Template Parameters] 34[table [[Type][Description]] 35 [[`State`][ 36 37The type of object to allocate. 38 ]] 39] 40[heading Parameters] 41[table [[Name][Description]] 42 [[`base`][ 43 44The helper to allocate from. 45 ]] 46 [[`args`][ 47 48An optional list of parameters to forward to the constructor of the object being allocated. 49 ]] 50] 51[heading See Also] 52[link beast.ref.boost__beast__stable_async_base `stable_async_base`] 53 54 55 56Convenience header [include_file boost/beast/core.hpp] 57 58[endsect] 59[section:boost__beast__async_base async_base] 60Base class to assist writing composed operations. 61[heading Synopsis] 62 63Defined in header [include_file boost/beast/core/async_base.hpp] 64 65 66 67``` 68template< 69 class __Handler__, 70 class __Executor1__, 71 class __Allocator__ = std::allocator<void>> 72class async_base 73``` 74[heading Types] 75[table [[Name][Description]] 76 [ 77 [[link beast.ref.boost__beast__async_base.allocator_type [*allocator_type]]] 78 [ 79 The type of allocator associated with this object. 80 ] 81 ] 82 [ 83 [[link beast.ref.boost__beast__async_base.executor_type [*executor_type]]] 84 [ 85 The type of executor associated with this object. 86 ] 87 ] 88] 89[heading Member Functions] 90[table [[Name][Description]] 91 [ 92 [[link beast.ref.boost__beast__async_base.async_base [*async_base]]] 93 [ 94 Constructor. 95 96 Move Constructor. 97 ] 98 ] 99 [ 100 [[link beast.ref.boost__beast__async_base.complete [*complete]]] 101 [ 102 Invoke the final completion handler, maybe using post. 103 ] 104 ] 105 [ 106 [[link beast.ref.boost__beast__async_base.complete_now [*complete_now]]] 107 [ 108 Invoke the final completion handler. 109 ] 110 ] 111 [ 112 [[link beast.ref.boost__beast__async_base.get_allocator [*get_allocator]]] 113 [ 114 Returns the allocator associated with this object. 115 ] 116 ] 117 [ 118 [[link beast.ref.boost__beast__async_base.get_executor [*get_executor]]] 119 [ 120 Returns the executor associated with this object. 121 ] 122 ] 123 [ 124 [[link beast.ref.boost__beast__async_base.handler [*handler]]] 125 [ 126 Returns the handler associated with this object. 127 ] 128 ] 129 [ 130 [[link beast.ref.boost__beast__async_base.operator_eq_ [*operator=]]] 131 [ 132 133 ] 134 ] 135 [ 136 [[link beast.ref.boost__beast__async_base.release_handler [*release_handler]]] 137 [ 138 Returns ownership of the handler associated with this object. 139 ] 140 ] 141 [ 142 [[link beast.ref.boost__beast__async_base.async_base_dtor_ [*~async_base]]] 143 [ 144 145 ] 146 ] 147] 148 149[heading Description] 150A function object submitted to intermediate initiating functions during a composed operation may derive from this type to inherit all of the boilerplate to forward the executor, allocator, and legacy customization points associated with the completion handler invoked at the end of the composed operation. 151The composed operation must be typical; that is, associated with one executor of an I/O object, and invoking a caller-provided completion handler when the operation is finished. Classes derived from [link beast.ref.boost__beast__async_base `async_base`] will acquire these properties: 152 153* Ownership of the final completion handler provided upon construction. 154 155 156* If the final handler has an associated allocator, this allocator will be propagated to the composed operation subclass. Otherwise, the associated allocator will be the type specified in the allocator template parameter, or the default of `std::allocator<void>` if the parameter is omitted. 157 158 159* If the final handler has an associated executor, then it will be used as the executor associated with the composed operation. Otherwise, the specified `Executor1` will be the type of executor associated with the composed operation. 160 161 162* An instance of `net::executor_work_guard` for the instance of `Executor1` shall be maintained until either the final handler is invoked, or the operation base is destroyed, whichever comes first. 163 164 165* Calls to the legacy customization points `asio_handler_invoke`, `asio_handler_allocate`, `asio_handler_deallocate`, and `asio_handler_is_continuation`, which use argument-dependent lookup, will be forwarded to the legacy customization points associated with the handler. 166 167[heading Example] 168 169The following code demonstrates how [link beast.ref.boost__beast__async_base `async_base`] may be be used to assist authoring an asynchronous initiating function, by providing all of the boilerplate to manage the final completion handler in a way that maintains the allocator and executor associations: 170 171``` 172 // Asynchronously read into a buffer until the buffer is full, or an error occurs 173 template<class AsyncReadStream, class ReadHandler> 174 typename net::async_result<ReadHandler, void(error_code, std::size_t)>::return_type 175 async_read(AsyncReadStream& stream, net::mutable_buffer buffer, ReadHandler&& handler) 176 { 177 using handler_type = BOOST_ASIO_HANDLER_TYPE(ReadHandler, void(error_code, std::size_t)); 178 using base_type = async_base<handler_type, typename AsyncReadStream::executor_type>; 179 180 struct op : base_type 181 { 182 AsyncReadStream& stream_; 183 net::mutable_buffer buffer_; 184 std::size_t total_bytes_transferred_; 185 186 op( 187 AsyncReadStream& stream, 188 net::mutable_buffer buffer, 189 handler_type& handler) 190 : base_type(std::move(handler), stream.get_executor()) 191 , stream_(stream) 192 , buffer_(buffer) 193 , total_bytes_transferred_(0) 194 { 195 (*this)({}, 0, false); // start the operation 196 } 197 198 void operator()(error_code ec, std::size_t bytes_transferred, bool is_continuation = true) 199 { 200 // Adjust the count of bytes and advance our buffer 201 total_bytes_transferred_ += bytes_transferred; 202 buffer_ = buffer_ + bytes_transferred; 203 204 // Keep reading until buffer is full or an error occurs 205 if(! ec && buffer_.size() > 0) 206 return stream_.async_read_some(buffer_, std::move(*this)); 207 208 // Call the completion handler with the result. If `is_continuation` is 209 // false, which happens on the first time through this function, then 210 // `net::post` will be used to call the completion handler, otherwise 211 // the completion handler will be invoked directly. 212 213 this->complete(is_continuation, ec, total_bytes_transferred_); 214 } 215 }; 216 217 net::async_completion<ReadHandler, void(error_code, std::size_t)> init{handler}; 218 op(stream, buffer, init.completion_handler); 219 return init.result.get(); 220 } 221``` 222Data members of composed operations implemented as completion handlers do not have stable addresses, as the composed operation object is move constructed upon each call to an initiating function. For most operations this is not a problem. For complex operations requiring stable temporary storage, the class [link beast.ref.boost__beast__stable_async_base `stable_async_base`] is provided which offers additional functionality: 223 224* The free function [link beast.ref.boost__beast__allocate_stable `allocate_stable`] may be used to allocate one or more temporary objects associated with the composed operation. 225 226 227* Memory for stable temporary objects is allocated using the allocator associated with the composed operation. 228 229 230* Stable temporary objects are automatically destroyed, and the memory freed using the associated allocator, either before the final completion handler is invoked (a Networking requirement) or when the composed operation is destroyed, whichever occurs first. 231 232[heading Temporary Storage Example] 233 234The following example demonstrates how a composed operation may store a temporary object. 235 236``` 237``` 238[heading Template Parameters] 239[table [[Type][Description]] 240 [[`Handler`][ 241 242The type of the completion handler to store. This type must meet the requirements of ['CompletionHandler]. 243 ]] 244 [[`Executor1`][ 245 246The type of the executor used when the handler has no associated executor. An instance of this type must be provided upon construction. The implementation will maintain an executor work guard and a copy of this instance. 247 ]] 248 [[`Allocator`][ 249 250The allocator type to use if the handler does not have an associated allocator. If this parameter is omitted, then `std::allocator<void>` will be used. If the specified allocator is not default constructible, an instance of the type must be provided upon construction. 251 ]] 252] 253[heading See Also] 254[link beast.ref.boost__beast__stable_async_base `stable_async_base`] 255[section:allocator_type async_base::allocator_type] 256[indexterm2 allocator_type..async_base] 257The type of allocator associated with this object. 258[heading Synopsis] 259 260``` 261using allocator_type = net::associated_allocator_t< Handler, Allocator >; 262``` 263 264[heading Description] 265If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the associated allocator of the derived class will be this type. [endsect] 266[section:async_base async_base::async_base] 267[indexterm2 async_base..async_base] 268Constructor. ``` 269template< 270 class __Handler__> 271``[link beast.ref.boost__beast__async_base.async_base.overload1 async_base]``( 272 Handler&& handler, 273 Executor1 const& ex1, 274 Allocator const& alloc = Allocator()); 275 ``[''''»''' [link beast.ref.boost__beast__async_base.async_base.overload1 more...]]`` 276 277``` 278Move Constructor. ``` 279``[link beast.ref.boost__beast__async_base.async_base.overload2 async_base]``( 280 async_base&& other); 281 ``[''''»''' [link beast.ref.boost__beast__async_base.async_base.overload2 more...]]`` 282 283``[link beast.ref.boost__beast__async_base.async_base.overload3 async_base]``( 284 async_base const&); 285 ``[''''»''' [link beast.ref.boost__beast__async_base.async_base.overload3 more...]]`` 286``` 287[section:overload1 async_base::async_base (1 of 3 overloads)] 288Constructor. 289[heading Synopsis] 290``` 291template< 292 class __Handler__> 293async_base( 294 Handler&& handler, 295 Executor1 const& ex1, 296 Allocator const& alloc = Allocator()); 297``` 298 299[heading Description] 300[heading Parameters] 301[table [[Name][Description]] 302 [[`handler`][ 303 304The final completion handler. The type of this object must meet the requirements of ['CompletionHandler]. The implementation takes ownership of the handler by performing a decay-copy. 305 ]] 306 [[`ex1`][ 307 308The executor associated with the implied I/O object target of the operation. The implementation shall maintain an executor work guard for the lifetime of the operation, or until the final completion handler is invoked, whichever is shorter. 309 ]] 310 [[`alloc`][ 311 312The allocator to be associated with objects derived from this class. If `Allocator` is default-constructible, this parameter is optional and may be omitted. 313 ]] 314] 315[endsect] 316[section:overload2 async_base::async_base (2 of 3 overloads)] 317Move Constructor. 318[heading Synopsis] 319``` 320async_base( 321 async_base&& other); 322``` 323 324[heading Description] 325[endsect] 326[section:overload3 async_base::async_base (3 of 3 overloads)] 327 328[heading Synopsis] 329``` 330async_base( 331 async_base const&); 332``` 333 334[heading Description] 335[endsect] 336[endsect] 337 338[section:complete async_base::complete] 339[indexterm2 complete..async_base] 340Invoke the final completion handler, maybe using post. 341[heading Synopsis] 342``` 343template< 344 class... Args> 345void 346complete( 347 bool is_continuation, 348 Args&&... args); 349``` 350 351[heading Description] 352This invokes the final completion handler with the specified arguments forwarded. It is undefined to call either of [link beast.ref.boost__beast__async_base.complete `async_base::complete`] or [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`] more than once. 353Any temporary objects allocated with [link beast.ref.boost__beast__allocate_stable `allocate_stable`] will be automatically destroyed before the final completion handler is invoked. 354[heading Parameters] 355[table [[Name][Description]] 356 [[`is_continuation`][ 357 358If this value is `false`, then the handler will be submitted to the executor using `net::post`. Otherwise the handler will be invoked as if by calling [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`]. 359 ]] 360 [[`args`][ 361 362A list of optional parameters to invoke the handler with. The completion handler must be invocable with the parameter list, or else a compilation error will result. 363 ]] 364] 365[endsect] 366[section:complete_now async_base::complete_now] 367[indexterm2 complete_now..async_base] 368Invoke the final completion handler. 369[heading Synopsis] 370``` 371template< 372 class... Args> 373void 374complete_now( 375 Args&&... args); 376``` 377 378[heading Description] 379This invokes the final completion handler with the specified arguments forwarded. It is undefined to call either of [link beast.ref.boost__beast__async_base.complete `async_base::complete`] or [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`] more than once. 380Any temporary objects allocated with [link beast.ref.boost__beast__allocate_stable `allocate_stable`] will be automatically destroyed before the final completion handler is invoked. 381[heading Parameters] 382[table [[Name][Description]] 383 [[`args`][ 384 385A list of optional parameters to invoke the handler with. The completion handler must be invocable with the parameter list, or else a compilation error will result. 386 ]] 387] 388[endsect] 389[section:executor_type async_base::executor_type] 390[indexterm2 executor_type..async_base] 391The type of executor associated with this object. 392[heading Synopsis] 393 394``` 395using executor_type = net::associated_executor_t< Handler, Executor1 >; 396``` 397 398[heading Description] 399If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the associated executor of the derived class will be this type. [endsect] 400[section:get_allocator async_base::get_allocator] 401[indexterm2 get_allocator..async_base] 402Returns the allocator associated with this object. 403[heading Synopsis] 404``` 405allocator_type 406get_allocator() const; 407``` 408 409[heading Description] 410If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the object returned from this function will be used as the associated allocator of the derived class. [endsect] 411[section:get_executor async_base::get_executor] 412[indexterm2 get_executor..async_base] 413Returns the executor associated with this object. 414[heading Synopsis] 415``` 416executor_type 417get_executor() const; 418``` 419 420[heading Description] 421If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the object returned from this function will be used as the associated executor of the derived class. [endsect] 422[section:handler async_base::handler] 423[indexterm2 handler..async_base] 424Returns the handler associated with this object. 425[heading Synopsis] 426``` 427Handler const & 428handler() const; 429``` 430 431[heading Description] 432[endsect] 433[section:operator_eq_ async_base::operator=] 434[indexterm2 operator=..async_base] 435 436[heading Synopsis] 437``` 438async_base& 439operator=( 440 async_base const&); 441``` 442 443[heading Description] 444[endsect] 445[section:release_handler async_base::release_handler] 446[indexterm2 release_handler..async_base] 447Returns ownership of the handler associated with this object. 448[heading Synopsis] 449``` 450Handler 451release_handler(); 452``` 453 454[heading Description] 455This function is used to transfer ownership of the handler to the caller, by move-construction. After the move, the only valid operations on the base object are move construction and destruction. [endsect] 456[section:async_base_dtor_ async_base::~async_base] 457[indexterm2 ~async_base..async_base] 458 459[heading Synopsis] 460``` 461virtual 462~async_base(); 463``` 464 465[heading Description] 466[endsect] 467 468 469 470Convenience header [include_file boost/beast/core.hpp] 471 472[endsect] 473 474 475 476[section:boost__beast__async_detect_ssl async_detect_ssl] 477[indexterm1 async_detect_ssl] 478Detect a TLS/SSL handshake asynchronously on a stream. 479[heading Synopsis] 480 481Defined in header [include_file boost/beast/core/detect_ssl.hpp] 482 483 484 485``` 486template< 487 class __AsyncReadStream__, 488 class __DynamicBuffer__, 489 class __CompletionToken__ = net::default_completion_token_t<beast::executor_type<AsyncReadStream>>> 490``__deduced__`` 491async_detect_ssl( 492 AsyncReadStream& stream, 493 DynamicBuffer& buffer, 494 CompletionToken&& token = net::default_completion_token_t< beast::executor_type< AsyncReadStream >>{}); 495 496``` 497 498[heading Description] 499This function reads asynchronously from a stream to determine if a client handshake message is being received. 500This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 501 502* A TLS client opening handshake is detected, 503 504 505* The received data is invalid for a TLS client handshake, or 506 507 508* An error occurs. 509 510The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` function. The program must ensure that no other calls to `async_read_some` are performed until this operation completes. 511Bytes read from the stream will be stored in the passed dynamic buffer, which may be used to perform the TLS handshake if the detector returns true, or be otherwise consumed by the caller based on the expected protocol. 512[heading Parameters] 513[table [[Name][Description]] 514 [[`stream`][ 515 516The stream to read from. This type must meet the requirements of ['AsyncReadStream]. 517 ]] 518 [[`buffer`][ 519 520The dynamic buffer to use. This type must meet the requirements of ['DynamicBuffer]. 521 ]] 522 [[`token`][ 523 524The completion token used to determine the method used to provide the result of the asynchronous operation. If this is a completion handler, the implementation takes ownership of the handler by performing a decay-copy, and the equivalent function signature of the handler must be: 525``` 526 void handler( 527 error_code const& error, // Set to the error, if any 528 bool result // The result of the detector 529 ); 530``` 531Regardless 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 `net::post`. 532 ]] 533] 534 535 536 537Convenience header [include_file boost/beast/core.hpp] 538 539[endsect] 540[section:boost__beast__async_teardown async_teardown] 541[indexterm1 async_teardown] 542Start tearing down a `net::ssl::stream`. 543[heading Synopsis] 544 545Defined in header [include_file boost/beast/websocket/ssl.hpp] 546 547 548 549``` 550template< 551 class __AsyncStream__, 552 class TeardownHandler> 553void 554async_teardown( 555 role_type role, 556 net::ssl::stream< AsyncStream >& stream, 557 TeardownHandler&& handler); 558 559``` 560 561[heading Description] 562This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the `Stream` parameter used to consruct the socket. When `Stream` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 563[heading Parameters] 564[table [[Name][Description]] 565 [[`role`][ 566 567The role of the local endpoint 568 ]] 569 [[`stream`][ 570 571The stream to tear down. 572 ]] 573 [[`handler`][ 574 575The 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: 576``` 577 void handler( 578 error_code const& error // result of operation 579 ); 580``` 581Regardless 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 `net::post`. 582 ]] 583] 584 585 586 587Convenience header [include_file boost/beast/websocket.hpp] 588 589[endsect] 590[section:boost__beast__basic_flat_buffer basic_flat_buffer] 591A dynamic buffer providing buffer sequences of length one. 592[heading Synopsis] 593 594Defined in header [include_file boost/beast/core/flat_buffer.hpp] 595 596 597 598``` 599template< 600 class __Allocator__> 601class basic_flat_buffer 602``` 603[heading Types] 604[table [[Name][Description]] 605 [ 606 [[link beast.ref.boost__beast__basic_flat_buffer.allocator_type [*allocator_type]]] 607 [ 608 The type of allocator used. 609 ] 610 ] 611 [ 612 [[link beast.ref.boost__beast__basic_flat_buffer.const_buffers_type [*const_buffers_type]]] 613 [ 614 The ConstBufferSequence used to represent the readable bytes. 615 ] 616 ] 617 [ 618 [[link beast.ref.boost__beast__basic_flat_buffer.mutable_buffers_type [*mutable_buffers_type]]] 619 [ 620 The MutableBufferSequence used to represent the writable bytes. 621 ] 622 ] 623 [ 624 [[link beast.ref.boost__beast__basic_flat_buffer.mutable_data_type [*mutable_data_type]]] 625 [ 626 The MutableBufferSequence used to represent the readable bytes. 627 ] 628 ] 629] 630[heading Member Functions] 631[table [[Name][Description]] 632 [ 633 [[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer [*basic_flat_buffer]]] 634 [ 635 Constructor. 636 637 Move Constructor. 638 639 Copy Constructor. 640 ] 641 ] 642 [ 643 [[link beast.ref.boost__beast__basic_flat_buffer.capacity [*capacity]]] 644 [ 645 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 646 ] 647 ] 648 [ 649 [[link beast.ref.boost__beast__basic_flat_buffer.cdata [*cdata]]] 650 [ 651 Returns a constant buffer sequence representing the readable bytes. 652 ] 653 ] 654 [ 655 [[link beast.ref.boost__beast__basic_flat_buffer.clear [*clear]]] 656 [ 657 Set the size of the readable and writable bytes to zero. 658 ] 659 ] 660 [ 661 [[link beast.ref.boost__beast__basic_flat_buffer.commit [*commit]]] 662 [ 663 Append writable bytes to the readable bytes. 664 ] 665 ] 666 [ 667 [[link beast.ref.boost__beast__basic_flat_buffer.consume [*consume]]] 668 [ 669 Remove bytes from beginning of the readable bytes. 670 ] 671 ] 672 [ 673 [[link beast.ref.boost__beast__basic_flat_buffer.data [*data]]] 674 [ 675 Returns a constant buffer sequence representing the readable bytes. 676 677 Returns a mutable buffer sequence representing the readable bytes. 678 ] 679 ] 680 [ 681 [[link beast.ref.boost__beast__basic_flat_buffer.get_allocator [*get_allocator]]] 682 [ 683 Returns a copy of the allocator used. 684 ] 685 ] 686 [ 687 [[link beast.ref.boost__beast__basic_flat_buffer.max_size [*max_size]]] 688 [ 689 Set the maximum allowed capacity. 690 691 Return the maximum number of bytes, both readable and writable, that can ever be held. 692 ] 693 ] 694 [ 695 [[link beast.ref.boost__beast__basic_flat_buffer.operator_eq_ [*operator=]]] 696 [ 697 Move Assignment. 698 699 Copy Assignment. 700 701 Copy assignment. 702 ] 703 ] 704 [ 705 [[link beast.ref.boost__beast__basic_flat_buffer.prepare [*prepare]]] 706 [ 707 Returns a mutable buffer sequence representing writable bytes. 708 ] 709 ] 710 [ 711 [[link beast.ref.boost__beast__basic_flat_buffer.reserve [*reserve]]] 712 [ 713 Guarantee a minimum capacity. 714 ] 715 ] 716 [ 717 [[link beast.ref.boost__beast__basic_flat_buffer.shrink_to_fit [*shrink_to_fit]]] 718 [ 719 Reallocate the buffer to fit the readable bytes exactly. 720 ] 721 ] 722 [ 723 [[link beast.ref.boost__beast__basic_flat_buffer.size [*size]]] 724 [ 725 Returns the number of readable bytes. 726 ] 727 ] 728 [ 729 [[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer_dtor_ [*~basic_flat_buffer]]] 730 [ 731 Destructor. 732 ] 733 ] 734] 735[heading Friends] 736[table [[Name][Description]] 737 [ 738 [[link beast.ref.boost__beast__basic_flat_buffer.swap [*swap]]] 739 [ 740 Exchange two dynamic buffers. 741 ] 742 ] 743] 744 745[heading Description] 746A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 747Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 748 749* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] when `this` is non-const. 750 751 752* A configurable maximum buffer size may be set upon construction. Attempts to exceed the buffer size will throw `std::length_error`. 753 754 755* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] and [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`], will have length one. 756 757Upon construction, a maximum size for the buffer may be specified. If this limit is exceeded, the `std::length_error` exception will be thrown. 758[heading Remarks] 759This class is designed for use with algorithms that take dynamic buffers as parameters, and are optimized for the case where the input sequence or output sequence is stored in a single contiguous buffer. 760[section:allocator_type basic_flat_buffer::allocator_type] 761[indexterm2 allocator_type..basic_flat_buffer] 762The type of allocator used. 763[heading Synopsis] 764 765``` 766using allocator_type = Allocator; 767``` 768 769[heading Description] 770[endsect] 771[section:basic_flat_buffer basic_flat_buffer::basic_flat_buffer] 772[indexterm2 basic_flat_buffer..basic_flat_buffer] 773Constructor. ``` 774``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload1 basic_flat_buffer]``(); 775 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload1 more...]]`` 776 777explicit 778``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload2 basic_flat_buffer]``( 779 std::size_t limit); 780 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload2 more...]]`` 781 782explicit 783``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload3 basic_flat_buffer]``( 784 Allocator const& alloc); 785 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload3 more...]]`` 786 787``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload4 basic_flat_buffer]``( 788 std::size_t limit, 789 Allocator const& alloc); 790 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload4 more...]]`` 791 792``` 793Move Constructor. ``` 794``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload5 basic_flat_buffer]``( 795 basic_flat_buffer&& other); 796 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload5 more...]]`` 797 798``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload6 basic_flat_buffer]``( 799 basic_flat_buffer&& other, 800 Allocator const& alloc); 801 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload6 more...]]`` 802 803``` 804Copy Constructor. ``` 805``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload7 basic_flat_buffer]``( 806 basic_flat_buffer const& other); 807 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload7 more...]]`` 808 809``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload8 basic_flat_buffer]``( 810 basic_flat_buffer const& other, 811 Allocator const& alloc); 812 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload8 more...]]`` 813 814template< 815 class OtherAlloc> 816``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload9 basic_flat_buffer]``( 817 basic_flat_buffer< OtherAlloc > const& other); 818 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload9 more...]]`` 819 820template< 821 class OtherAlloc> 822``[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload10 basic_flat_buffer]``( 823 basic_flat_buffer< OtherAlloc > const& other, 824 Allocator const& alloc); 825 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer.overload10 more...]]`` 826``` 827[section:overload1 basic_flat_buffer::basic_flat_buffer (1 of 10 overloads)] 828Constructor. 829[heading Synopsis] 830``` 831basic_flat_buffer(); 832``` 833 834[heading Description] 835After construction, [link beast.ref.boost__beast__basic_flat_buffer.capacity `basic_flat_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_flat_buffer.max_size `basic_flat_buffer::max_size`] will return the largest value which may be passed to the allocator's `allocate` function. [endsect] 836[section:overload2 basic_flat_buffer::basic_flat_buffer (2 of 10 overloads)] 837Constructor. 838[heading Synopsis] 839``` 840basic_flat_buffer( 841 std::size_t limit); 842``` 843 844[heading Description] 845After construction, [link beast.ref.boost__beast__basic_flat_buffer.capacity `basic_flat_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_flat_buffer.max_size `basic_flat_buffer::max_size`] will return the specified value of `limit`. 846[heading Parameters] 847[table [[Name][Description]] 848 [[`limit`][ 849 850The desired maximum size. 851 ]] 852] 853[endsect] 854[section:overload3 basic_flat_buffer::basic_flat_buffer (3 of 10 overloads)] 855Constructor. 856[heading Synopsis] 857``` 858basic_flat_buffer( 859 Allocator const& alloc); 860``` 861 862[heading Description] 863After construction, [link beast.ref.boost__beast__basic_flat_buffer.capacity `basic_flat_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_flat_buffer.max_size `basic_flat_buffer::max_size`] will return the largest value which may be passed to the allocator's `allocate` function. 864[heading Parameters] 865[table [[Name][Description]] 866 [[`alloc`][ 867 868The allocator to use for the object. 869 ]] 870] 871[heading Exception Safety] 872 873No-throw guarantee. [endsect] 874[section:overload4 basic_flat_buffer::basic_flat_buffer (4 of 10 overloads)] 875Constructor. 876[heading Synopsis] 877``` 878basic_flat_buffer( 879 std::size_t limit, 880 Allocator const& alloc); 881``` 882 883[heading Description] 884After construction, [link beast.ref.boost__beast__basic_flat_buffer.capacity `basic_flat_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_flat_buffer.max_size `basic_flat_buffer::max_size`] will return the specified value of `limit`. 885[heading Parameters] 886[table [[Name][Description]] 887 [[`limit`][ 888 889The desired maximum size. 890 ]] 891 [[`alloc`][ 892 893The allocator to use for the object. 894 ]] 895] 896[heading Exception Safety] 897 898No-throw guarantee. [endsect] 899[section:overload5 basic_flat_buffer::basic_flat_buffer (5 of 10 overloads)] 900Move Constructor. 901[heading Synopsis] 902``` 903basic_flat_buffer( 904 basic_flat_buffer&& other); 905``` 906 907[heading Description] 908The container is constructed with the contents of `other` using move semantics. The maximum size will be the same as the moved-from object. 909Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] remain valid after the move. 910[heading Parameters] 911[table [[Name][Description]] 912 [[`other`][ 913 914The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 915 ]] 916] 917[heading Exception Safety] 918 919No-throw guarantee. [endsect] 920[section:overload6 basic_flat_buffer::basic_flat_buffer (6 of 10 overloads)] 921Move Constructor. 922[heading Synopsis] 923``` 924basic_flat_buffer( 925 basic_flat_buffer&& other, 926 Allocator const& alloc); 927``` 928 929[heading Description] 930Using `alloc` as the allocator for the new container, the contents of `other` are moved. If `alloc != other.get_allocator()`, this results in a copy. The maximum size will be the same as the moved-from object. 931Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid after the move. 932[heading Parameters] 933[table [[Name][Description]] 934 [[`other`][ 935 936The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 937 ]] 938 [[`alloc`][ 939 940The allocator to use for the object. 941 ]] 942] 943[heading Exceptions] 944[table [[Type][Thrown On]] 945 [[`std::length_error`][ 946 947if `other.size()` exceeds the maximum allocation size of `alloc`. 948 ]] 949] 950[endsect] 951[section:overload7 basic_flat_buffer::basic_flat_buffer (7 of 10 overloads)] 952Copy Constructor. 953[heading Synopsis] 954``` 955basic_flat_buffer( 956 basic_flat_buffer const& other); 957``` 958 959[heading Description] 960This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 961[heading Parameters] 962[table [[Name][Description]] 963 [[`other`][ 964 965The object to copy from. 966 ]] 967] 968[heading Exceptions] 969[table [[Type][Thrown On]] 970 [[`std::length_error`][ 971 972if `other.size()` exceeds the maximum allocation size of the allocator. 973 ]] 974] 975[endsect] 976[section:overload8 basic_flat_buffer::basic_flat_buffer (8 of 10 overloads)] 977Copy Constructor. 978[heading Synopsis] 979``` 980basic_flat_buffer( 981 basic_flat_buffer const& other, 982 Allocator const& alloc); 983``` 984 985[heading Description] 986This container is constructed with the contents of `other` using copy semantics and the specified allocator. The maximum size will be the same as the copied object. 987[heading Parameters] 988[table [[Name][Description]] 989 [[`other`][ 990 991The object to copy from. 992 ]] 993 [[`alloc`][ 994 995The allocator to use for the object. 996 ]] 997] 998[heading Exceptions] 999[table [[Type][Thrown On]] 1000 [[`std::length_error`][ 1001 1002if `other.size()` exceeds the maximum allocation size of `alloc`. 1003 ]] 1004] 1005[endsect] 1006[section:overload9 basic_flat_buffer::basic_flat_buffer (9 of 10 overloads)] 1007Copy Constructor. 1008[heading Synopsis] 1009``` 1010template< 1011 class OtherAlloc> 1012basic_flat_buffer( 1013 basic_flat_buffer< OtherAlloc > const& other); 1014``` 1015 1016[heading Description] 1017This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1018[heading Parameters] 1019[table [[Name][Description]] 1020 [[`other`][ 1021 1022The object to copy from. 1023 ]] 1024] 1025[heading Exceptions] 1026[table [[Type][Thrown On]] 1027 [[`std::length_error`][ 1028 1029if `other.size()` exceeds the maximum allocation size of the allocator. 1030 ]] 1031] 1032[endsect] 1033[section:overload10 basic_flat_buffer::basic_flat_buffer (10 of 10 overloads)] 1034Copy Constructor. 1035[heading Synopsis] 1036``` 1037template< 1038 class OtherAlloc> 1039basic_flat_buffer( 1040 basic_flat_buffer< OtherAlloc > const& other, 1041 Allocator const& alloc); 1042``` 1043 1044[heading Description] 1045This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1046[heading Parameters] 1047[table [[Name][Description]] 1048 [[`other`][ 1049 1050The object to copy from. 1051 ]] 1052 [[`alloc`][ 1053 1054The allocator to use for the object. 1055 ]] 1056] 1057[heading Exceptions] 1058[table [[Type][Thrown On]] 1059 [[`std::length_error`][ 1060 1061if `other.size()` exceeds the maximum allocation size of `alloc`. 1062 ]] 1063] 1064[endsect] 1065[endsect] 1066 1067[section:capacity basic_flat_buffer::capacity] 1068[indexterm2 capacity..basic_flat_buffer] 1069Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 1070[heading Synopsis] 1071``` 1072std::size_t 1073capacity() const; 1074``` 1075 1076[heading Description] 1077[endsect] 1078[section:cdata basic_flat_buffer::cdata] 1079[indexterm2 cdata..basic_flat_buffer] 1080Returns a constant buffer sequence representing the readable bytes. 1081[heading Synopsis] 1082``` 1083const_buffers_type 1084cdata() const; 1085``` 1086 1087[heading Description] 1088[endsect] 1089[section:clear basic_flat_buffer::clear] 1090[indexterm2 clear..basic_flat_buffer] 1091Set the size of the readable and writable bytes to zero. 1092[heading Synopsis] 1093``` 1094void 1095clear(); 1096``` 1097 1098[heading Description] 1099This clears the buffer without changing capacity. Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1100[heading Exception Safety] 1101 1102No-throw guarantee. [endsect] 1103[section:commit basic_flat_buffer::commit] 1104[indexterm2 commit..basic_flat_buffer] 1105Append writable bytes to the readable bytes. 1106[heading Synopsis] 1107``` 1108void 1109commit( 1110 std::size_t n); 1111``` 1112 1113[heading Description] 1114Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 1115All buffers sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1116[heading Parameters] 1117[table [[Name][Description]] 1118 [[`n`][ 1119 1120The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 1121 ]] 1122] 1123[heading Exception Safety] 1124 1125No-throw guarantee. [endsect] 1126[section:const_buffers_type basic_flat_buffer::const_buffers_type] 1127[indexterm2 const_buffers_type..basic_flat_buffer] 1128The ConstBufferSequence used to represent the readable bytes. 1129[heading Synopsis] 1130 1131``` 1132using const_buffers_type = net::const_buffer; 1133``` 1134 1135[heading Description] 1136[endsect] 1137[section:consume basic_flat_buffer::consume] 1138[indexterm2 consume..basic_flat_buffer] 1139Remove bytes from beginning of the readable bytes. 1140[heading Synopsis] 1141``` 1142void 1143consume( 1144 std::size_t n); 1145``` 1146 1147[heading Description] 1148Removes n bytes from the beginning of the readable bytes. 1149All buffers sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1150[heading Parameters] 1151[table [[Name][Description]] 1152 [[`n`][ 1153 1154The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 1155 ]] 1156] 1157[heading Exception Safety] 1158 1159No-throw guarantee. [endsect] 1160[section:data basic_flat_buffer::data] 1161[indexterm2 data..basic_flat_buffer] 1162Returns a constant buffer sequence representing the readable bytes. ``` 1163const_buffers_type 1164``[link beast.ref.boost__beast__basic_flat_buffer.data.overload1 data]``() const; 1165 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.data.overload1 more...]]`` 1166 1167``` 1168Returns a mutable buffer sequence representing the readable bytes. ``` 1169mutable_data_type 1170``[link beast.ref.boost__beast__basic_flat_buffer.data.overload2 data]``(); 1171 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.data.overload2 more...]]`` 1172``` 1173[section:overload1 basic_flat_buffer::data (1 of 2 overloads)] 1174Returns a constant buffer sequence representing the readable bytes. 1175[heading Synopsis] 1176``` 1177const_buffers_type 1178data() const; 1179``` 1180 1181[heading Description] 1182[endsect] 1183[section:overload2 basic_flat_buffer::data (2 of 2 overloads)] 1184Returns a mutable buffer sequence representing the readable bytes. 1185[heading Synopsis] 1186``` 1187mutable_data_type 1188data(); 1189``` 1190 1191[heading Description] 1192[endsect] 1193[endsect] 1194 1195[section:get_allocator basic_flat_buffer::get_allocator] 1196[indexterm2 get_allocator..basic_flat_buffer] 1197Returns a copy of the allocator used. 1198[heading Synopsis] 1199``` 1200allocator_type 1201get_allocator() const; 1202``` 1203 1204[heading Description] 1205[endsect] 1206[section:max_size basic_flat_buffer::max_size] 1207[indexterm2 max_size..basic_flat_buffer] 1208Set the maximum allowed capacity. ``` 1209void 1210``[link beast.ref.boost__beast__basic_flat_buffer.max_size.overload1 max_size]``( 1211 std::size_t n); 1212 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.max_size.overload1 more...]]`` 1213 1214``` 1215Return the maximum number of bytes, both readable and writable, that can ever be held. ``` 1216std::size_t 1217``[link beast.ref.boost__beast__basic_flat_buffer.max_size.overload2 max_size]``() const; 1218 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.max_size.overload2 more...]]`` 1219``` 1220[section:overload1 basic_flat_buffer::max_size (1 of 2 overloads)] 1221Set the maximum allowed capacity. 1222[heading Synopsis] 1223``` 1224void 1225max_size( 1226 std::size_t n); 1227``` 1228 1229[heading Description] 1230This function changes the currently configured upper limit on capacity to the specified value. 1231[heading Parameters] 1232[table [[Name][Description]] 1233 [[`n`][ 1234 1235The maximum number of bytes ever allowed for capacity. 1236 ]] 1237] 1238[heading Exception Safety] 1239 1240No-throw guarantee. [endsect] 1241[section:overload2 basic_flat_buffer::max_size (2 of 2 overloads)] 1242Return the maximum number of bytes, both readable and writable, that can ever be held. 1243[heading Synopsis] 1244``` 1245std::size_t 1246max_size() const; 1247``` 1248 1249[heading Description] 1250[endsect] 1251[endsect] 1252 1253[section:mutable_buffers_type basic_flat_buffer::mutable_buffers_type] 1254[indexterm2 mutable_buffers_type..basic_flat_buffer] 1255The MutableBufferSequence used to represent the writable bytes. 1256[heading Synopsis] 1257 1258``` 1259using mutable_buffers_type = net::mutable_buffer; 1260``` 1261 1262[heading Description] 1263[endsect] 1264[section:mutable_data_type basic_flat_buffer::mutable_data_type] 1265[indexterm2 mutable_data_type..basic_flat_buffer] 1266The MutableBufferSequence used to represent the readable bytes. 1267[heading Synopsis] 1268 1269``` 1270using mutable_data_type = net::mutable_buffer; 1271``` 1272 1273[heading Description] 1274[endsect] 1275[section:operator_eq_ basic_flat_buffer::operator=] 1276[indexterm2 operator=..basic_flat_buffer] 1277Move Assignment. ``` 1278basic_flat_buffer& 1279``[link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload1 operator=]``( 1280 basic_flat_buffer&& other); 1281 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload1 more...]]`` 1282 1283``` 1284Copy Assignment. ``` 1285basic_flat_buffer& 1286``[link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload2 operator=]``( 1287 basic_flat_buffer const& other); 1288 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload2 more...]]`` 1289 1290``` 1291Copy assignment. ``` 1292template< 1293 class OtherAlloc> 1294basic_flat_buffer& 1295``[link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload3 operator=]``( 1296 basic_flat_buffer< OtherAlloc > const& other); 1297 ``[''''»''' [link beast.ref.boost__beast__basic_flat_buffer.operator_eq_.overload3 more...]]`` 1298``` 1299[section:overload1 basic_flat_buffer::operator= (1 of 3 overloads)] 1300Move Assignment. 1301[heading Synopsis] 1302``` 1303basic_flat_buffer& 1304operator=( 1305 basic_flat_buffer&& other); 1306``` 1307 1308[heading Description] 1309The container is assigned with the contents of `other` using move semantics. The maximum size will be the same as the moved-from object. 1310Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] remain valid after the move. 1311[heading Parameters] 1312[table [[Name][Description]] 1313 [[`other`][ 1314 1315The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 1316 ]] 1317] 1318[heading Exception Safety] 1319 1320No-throw guarantee. [endsect] 1321[section:overload2 basic_flat_buffer::operator= (2 of 3 overloads)] 1322Copy Assignment. 1323[heading Synopsis] 1324``` 1325basic_flat_buffer& 1326operator=( 1327 basic_flat_buffer const& other); 1328``` 1329 1330[heading Description] 1331The container is assigned with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1332After the copy, `this` will have zero writable bytes. 1333[heading Parameters] 1334[table [[Name][Description]] 1335 [[`other`][ 1336 1337The object to copy from. 1338 ]] 1339] 1340[heading Exceptions] 1341[table [[Type][Thrown On]] 1342 [[`std::length_error`][ 1343 1344if `other.size()` exceeds the maximum allocation size of the allocator. 1345 ]] 1346] 1347[endsect] 1348[section:overload3 basic_flat_buffer::operator= (3 of 3 overloads)] 1349Copy assignment. 1350[heading Synopsis] 1351``` 1352template< 1353 class OtherAlloc> 1354basic_flat_buffer& 1355operator=( 1356 basic_flat_buffer< OtherAlloc > const& other); 1357``` 1358 1359[heading Description] 1360The container is assigned with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1361After the copy, `this` will have zero writable bytes. 1362[heading Parameters] 1363[table [[Name][Description]] 1364 [[`other`][ 1365 1366The object to copy from. 1367 ]] 1368] 1369[heading Exceptions] 1370[table [[Type][Thrown On]] 1371 [[`std::length_error`][ 1372 1373if `other.size()` exceeds the maximum allocation size of the allocator. 1374 ]] 1375] 1376[endsect] 1377[endsect] 1378 1379[section:prepare basic_flat_buffer::prepare] 1380[indexterm2 prepare..basic_flat_buffer] 1381Returns a mutable buffer sequence representing writable bytes. 1382[heading Synopsis] 1383``` 1384mutable_buffers_type 1385prepare( 1386 std::size_t n); 1387``` 1388 1389[heading Description] 1390Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. Memory may be reallocated as needed. 1391All buffers sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1392[heading Parameters] 1393[table [[Name][Description]] 1394 [[`n`][ 1395 1396The desired number of bytes in the returned buffer sequence. 1397 ]] 1398] 1399[heading Exceptions] 1400[table [[Type][Thrown On]] 1401 [[`std::length_error`][ 1402 1403if `size() + n` exceeds either `max_size()` or the allocator's maximum allocation size. 1404 ]] 1405] 1406[heading Exception Safety] 1407 1408Strong guarantee. [endsect] 1409[section:reserve basic_flat_buffer::reserve] 1410[indexterm2 reserve..basic_flat_buffer] 1411Guarantee a minimum capacity. 1412[heading Synopsis] 1413``` 1414void 1415reserve( 1416 std::size_t n); 1417``` 1418 1419[heading Description] 1420This function adjusts the internal storage (if necessary) to guarantee space for at least `n` bytes. 1421Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1422[heading Parameters] 1423[table [[Name][Description]] 1424 [[`n`][ 1425 1426The minimum number of byte for the new capacity. If this value is greater than the maximum size, then the maximum size will be adjusted upwards to this value. 1427 ]] 1428] 1429[heading Exception Safety] 1430 1431Basic guarantee. 1432[heading Exceptions] 1433[table [[Type][Thrown On]] 1434 [[`std::length_error`][ 1435 1436if n is larger than the maximum allocation size of the allocator. 1437 ]] 1438] 1439[endsect] 1440[section:shrink_to_fit basic_flat_buffer::shrink_to_fit] 1441[indexterm2 shrink_to_fit..basic_flat_buffer] 1442Reallocate the buffer to fit the readable bytes exactly. 1443[heading Synopsis] 1444``` 1445void 1446shrink_to_fit(); 1447``` 1448 1449[heading Description] 1450Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] or [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`] become invalid. 1451[heading Exception Safety] 1452 1453Strong guarantee. [endsect] 1454[section:size basic_flat_buffer::size] 1455[indexterm2 size..basic_flat_buffer] 1456Returns the number of readable bytes. 1457[heading Synopsis] 1458``` 1459std::size_t 1460size() const; 1461``` 1462 1463[heading Description] 1464[endsect] 1465[section:swap basic_flat_buffer::swap] 1466[indexterm2 swap..basic_flat_buffer] 1467Exchange two dynamic buffers. 1468[heading Synopsis] 1469 1470Defined in header [include_file boost/beast/core/flat_buffer.hpp] 1471 1472 1473``` 1474template< 1475 class Alloc> 1476friend void 1477swap( 1478 basic_flat_buffer< Alloc >&, 1479 basic_flat_buffer< Alloc >&); 1480``` 1481 1482[heading Description] 1483 1484 1485 1486Convenience header [include_file boost/beast/core.hpp] 1487 1488[endsect] 1489[section:basic_flat_buffer_dtor_ basic_flat_buffer::~basic_flat_buffer] 1490[indexterm2 ~basic_flat_buffer..basic_flat_buffer] 1491Destructor. 1492[heading Synopsis] 1493``` 1494~basic_flat_buffer(); 1495``` 1496 1497[heading Description] 1498[endsect] 1499 1500 1501 1502Convenience header [include_file boost/beast/core.hpp] 1503 1504[endsect] 1505 1506 1507 1508[section:boost__beast__basic_multi_buffer basic_multi_buffer] 1509A dynamic buffer providing sequences of variable length. 1510[heading Synopsis] 1511 1512Defined in header [include_file boost/beast/core/multi_buffer.hpp] 1513 1514 1515 1516``` 1517template< 1518 class __Allocator__> 1519class basic_multi_buffer 1520``` 1521[heading Types] 1522[table [[Name][Description]] 1523 [ 1524 [[link beast.ref.boost__beast__basic_multi_buffer.allocator_type [*allocator_type]]] 1525 [ 1526 The type of allocator used. 1527 ] 1528 ] 1529 [ 1530 [[link beast.ref.boost__beast__basic_multi_buffer.const_buffers_type [*const_buffers_type]]] 1531 [ 1532 The ConstBufferSequence used to represent the readable bytes. 1533 ] 1534 ] 1535 [ 1536 [[link beast.ref.boost__beast__basic_multi_buffer.mutable_buffers_type [*mutable_buffers_type]]] 1537 [ 1538 The MutableBufferSequence used to represent the writable bytes. 1539 ] 1540 ] 1541 [ 1542 [[link beast.ref.boost__beast__basic_multi_buffer.mutable_data_type [*mutable_data_type]]] 1543 [ 1544 The MutableBufferSequence used to represent the readable bytes. 1545 ] 1546 ] 1547] 1548[heading Member Functions] 1549[table [[Name][Description]] 1550 [ 1551 [[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer [*basic_multi_buffer]]] 1552 [ 1553 Constructor. 1554 1555 Move Constructor. 1556 1557 Copy Constructor. 1558 ] 1559 ] 1560 [ 1561 [[link beast.ref.boost__beast__basic_multi_buffer.capacity [*capacity]]] 1562 [ 1563 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 1564 ] 1565 ] 1566 [ 1567 [[link beast.ref.boost__beast__basic_multi_buffer.cdata [*cdata]]] 1568 [ 1569 Returns a constant buffer sequence representing the readable bytes. 1570 ] 1571 ] 1572 [ 1573 [[link beast.ref.boost__beast__basic_multi_buffer.clear [*clear]]] 1574 [ 1575 Set the size of the readable and writable bytes to zero. 1576 ] 1577 ] 1578 [ 1579 [[link beast.ref.boost__beast__basic_multi_buffer.commit [*commit]]] 1580 [ 1581 Append writable bytes to the readable bytes. 1582 ] 1583 ] 1584 [ 1585 [[link beast.ref.boost__beast__basic_multi_buffer.consume [*consume]]] 1586 [ 1587 Remove bytes from beginning of the readable bytes. 1588 ] 1589 ] 1590 [ 1591 [[link beast.ref.boost__beast__basic_multi_buffer.data [*data]]] 1592 [ 1593 Returns a constant buffer sequence representing the readable bytes. 1594 1595 Returns a mutable buffer sequence representing the readable bytes. 1596 ] 1597 ] 1598 [ 1599 [[link beast.ref.boost__beast__basic_multi_buffer.get_allocator [*get_allocator]]] 1600 [ 1601 Returns a copy of the allocator used. 1602 ] 1603 ] 1604 [ 1605 [[link beast.ref.boost__beast__basic_multi_buffer.max_size [*max_size]]] 1606 [ 1607 Set the maximum allowed capacity. 1608 1609 Return the maximum number of bytes, both readable and writable, that can ever be held. 1610 ] 1611 ] 1612 [ 1613 [[link beast.ref.boost__beast__basic_multi_buffer.operator_eq_ [*operator=]]] 1614 [ 1615 Move Assignment. 1616 1617 Copy Assignment. 1618 ] 1619 ] 1620 [ 1621 [[link beast.ref.boost__beast__basic_multi_buffer.prepare [*prepare]]] 1622 [ 1623 Returns a mutable buffer sequence representing writable bytes. 1624 ] 1625 ] 1626 [ 1627 [[link beast.ref.boost__beast__basic_multi_buffer.reserve [*reserve]]] 1628 [ 1629 Guarantee a minimum capacity. 1630 ] 1631 ] 1632 [ 1633 [[link beast.ref.boost__beast__basic_multi_buffer.shrink_to_fit [*shrink_to_fit]]] 1634 [ 1635 Reallocate the buffer to fit the readable bytes exactly. 1636 ] 1637 ] 1638 [ 1639 [[link beast.ref.boost__beast__basic_multi_buffer.size [*size]]] 1640 [ 1641 Returns the number of readable bytes. 1642 ] 1643 ] 1644 [ 1645 [[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer_dtor_ [*~basic_multi_buffer]]] 1646 [ 1647 Destructor. 1648 ] 1649 ] 1650] 1651[heading Friends] 1652[table [[Name][Description]] 1653 [ 1654 [[link beast.ref.boost__beast__basic_multi_buffer.swap [*swap]]] 1655 [ 1656 Exchange two dynamic buffers. 1657 ] 1658 ] 1659] 1660 1661[heading Description] 1662A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 1663The implementation uses a sequence of one or more byte arrays of varying sizes to represent the readable and writable bytes. Additional byte array objects are appended to the sequence to accommodate changes in the desired size. The behavior and implementation of this container is most similar to `std::deque`. 1664Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 1665 1666* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] when `this` is non-const. 1667 1668 1669* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] and [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`], may have length greater than one. 1670 1671 1672* A configurable maximum size may be set upon construction and adjusted afterwards. Calls to [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] that would exceed this size will throw `std::length_error`. 1673 1674 1675* Sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] remain valid after calls to [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] or [link beast.ref.boost__beast__basic_multi_buffer.commit `basic_multi_buffer::commit`]. 1676 1677[heading Template Parameters] 1678[table [[Type][Description]] 1679 [[`Allocator`][ 1680 1681The allocator to use for managing memory. 1682 ]] 1683] 1684[section:allocator_type basic_multi_buffer::allocator_type] 1685[indexterm2 allocator_type..basic_multi_buffer] 1686The type of allocator used. 1687[heading Synopsis] 1688 1689``` 1690using allocator_type = Allocator; 1691``` 1692 1693[heading Description] 1694[endsect] 1695[section:basic_multi_buffer basic_multi_buffer::basic_multi_buffer] 1696[indexterm2 basic_multi_buffer..basic_multi_buffer] 1697Constructor. ``` 1698``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload1 basic_multi_buffer]``(); 1699 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload1 more...]]`` 1700 1701explicit 1702``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload2 basic_multi_buffer]``( 1703 std::size_t limit); 1704 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload2 more...]]`` 1705 1706explicit 1707``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload3 basic_multi_buffer]``( 1708 Allocator const& alloc); 1709 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload3 more...]]`` 1710 1711``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload4 basic_multi_buffer]``( 1712 std::size_t limit, 1713 Allocator const& alloc); 1714 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload4 more...]]`` 1715 1716``` 1717Move Constructor. ``` 1718``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload5 basic_multi_buffer]``( 1719 basic_multi_buffer&& other); 1720 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload5 more...]]`` 1721 1722``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload6 basic_multi_buffer]``( 1723 basic_multi_buffer&& other, 1724 Allocator const& alloc); 1725 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload6 more...]]`` 1726 1727``` 1728Copy Constructor. ``` 1729``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload7 basic_multi_buffer]``( 1730 basic_multi_buffer const& other); 1731 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload7 more...]]`` 1732 1733``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload8 basic_multi_buffer]``( 1734 basic_multi_buffer const& other, 1735 Allocator const& alloc); 1736 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload8 more...]]`` 1737 1738template< 1739 class OtherAlloc> 1740``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload9 basic_multi_buffer]``( 1741 basic_multi_buffer< OtherAlloc > const& other); 1742 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload9 more...]]`` 1743 1744template< 1745 class OtherAlloc> 1746``[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload10 basic_multi_buffer]``( 1747 basic_multi_buffer< OtherAlloc > const& other, 1748 allocator_type const& alloc); 1749 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer.overload10 more...]]`` 1750``` 1751[section:overload1 basic_multi_buffer::basic_multi_buffer (1 of 10 overloads)] 1752Constructor. 1753[heading Synopsis] 1754``` 1755basic_multi_buffer(); 1756``` 1757 1758[heading Description] 1759After construction, [link beast.ref.boost__beast__basic_multi_buffer.capacity `basic_multi_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_multi_buffer.max_size `basic_multi_buffer::max_size`] will return the largest value which may be passed to the allocator's `allocate` function. [endsect] 1760[section:overload2 basic_multi_buffer::basic_multi_buffer (2 of 10 overloads)] 1761Constructor. 1762[heading Synopsis] 1763``` 1764basic_multi_buffer( 1765 std::size_t limit); 1766``` 1767 1768[heading Description] 1769After construction, [link beast.ref.boost__beast__basic_multi_buffer.capacity `basic_multi_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_multi_buffer.max_size `basic_multi_buffer::max_size`] will return the specified value of `limit`. 1770[heading Parameters] 1771[table [[Name][Description]] 1772 [[`limit`][ 1773 1774The desired maximum size. 1775 ]] 1776] 1777[endsect] 1778[section:overload3 basic_multi_buffer::basic_multi_buffer (3 of 10 overloads)] 1779Constructor. 1780[heading Synopsis] 1781``` 1782basic_multi_buffer( 1783 Allocator const& alloc); 1784``` 1785 1786[heading Description] 1787After construction, [link beast.ref.boost__beast__basic_multi_buffer.capacity `basic_multi_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_multi_buffer.max_size `basic_multi_buffer::max_size`] will return the largest value which may be passed to the allocator's `allocate` function. 1788[heading Parameters] 1789[table [[Name][Description]] 1790 [[`alloc`][ 1791 1792The allocator to use for the object. 1793 ]] 1794] 1795[heading Exception Safety] 1796 1797No-throw guarantee. [endsect] 1798[section:overload4 basic_multi_buffer::basic_multi_buffer (4 of 10 overloads)] 1799Constructor. 1800[heading Synopsis] 1801``` 1802basic_multi_buffer( 1803 std::size_t limit, 1804 Allocator const& alloc); 1805``` 1806 1807[heading Description] 1808After construction, [link beast.ref.boost__beast__basic_multi_buffer.capacity `basic_multi_buffer::capacity`] will return zero, and [link beast.ref.boost__beast__basic_multi_buffer.max_size `basic_multi_buffer::max_size`] will return the specified value of `limit`. 1809[heading Parameters] 1810[table [[Name][Description]] 1811 [[`limit`][ 1812 1813The desired maximum size. 1814 ]] 1815 [[`alloc`][ 1816 1817The allocator to use for the object. 1818 ]] 1819] 1820[heading Exception Safety] 1821 1822No-throw guarantee. [endsect] 1823[section:overload5 basic_multi_buffer::basic_multi_buffer (5 of 10 overloads)] 1824Move Constructor. 1825[heading Synopsis] 1826``` 1827basic_multi_buffer( 1828 basic_multi_buffer&& other); 1829``` 1830 1831[heading Description] 1832The container is constructed with the contents of `other` using move semantics. The maximum size will be the same as the moved-from object. 1833Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] remain valid after the move. 1834[heading Parameters] 1835[table [[Name][Description]] 1836 [[`other`][ 1837 1838The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 1839 ]] 1840] 1841[heading Exception Safety] 1842 1843No-throw guarantee. [endsect] 1844[section:overload6 basic_multi_buffer::basic_multi_buffer (6 of 10 overloads)] 1845Move Constructor. 1846[heading Synopsis] 1847``` 1848basic_multi_buffer( 1849 basic_multi_buffer&& other, 1850 Allocator const& alloc); 1851``` 1852 1853[heading Description] 1854Using `alloc` as the allocator for the new container, the contents of `other` are moved. If `alloc != other.get_allocator()`, this results in a copy. The maximum size will be the same as the moved-from object. 1855Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] become invalid after the move. 1856[heading Parameters] 1857[table [[Name][Description]] 1858 [[`other`][ 1859 1860The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 1861 ]] 1862 [[`alloc`][ 1863 1864The allocator to use for the object. 1865 ]] 1866] 1867[heading Exceptions] 1868[table [[Type][Thrown On]] 1869 [[`std::length_error`][ 1870 1871if `other.size()` exceeds the maximum allocation size of `alloc`. 1872 ]] 1873] 1874[endsect] 1875[section:overload7 basic_multi_buffer::basic_multi_buffer (7 of 10 overloads)] 1876Copy Constructor. 1877[heading Synopsis] 1878``` 1879basic_multi_buffer( 1880 basic_multi_buffer const& other); 1881``` 1882 1883[heading Description] 1884This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1885[heading Parameters] 1886[table [[Name][Description]] 1887 [[`other`][ 1888 1889The object to copy from. 1890 ]] 1891] 1892[heading Exceptions] 1893[table [[Type][Thrown On]] 1894 [[`std::length_error`][ 1895 1896if `other.size()` exceeds the maximum allocation size of the allocator. 1897 ]] 1898] 1899[endsect] 1900[section:overload8 basic_multi_buffer::basic_multi_buffer (8 of 10 overloads)] 1901Copy Constructor. 1902[heading Synopsis] 1903``` 1904basic_multi_buffer( 1905 basic_multi_buffer const& other, 1906 Allocator const& alloc); 1907``` 1908 1909[heading Description] 1910This container is constructed with the contents of `other` using copy semantics and the specified allocator. The maximum size will be the same as the copied object. 1911[heading Parameters] 1912[table [[Name][Description]] 1913 [[`other`][ 1914 1915The object to copy from. 1916 ]] 1917 [[`alloc`][ 1918 1919The allocator to use for the object. 1920 ]] 1921] 1922[heading Exceptions] 1923[table [[Type][Thrown On]] 1924 [[`std::length_error`][ 1925 1926if `other.size()` exceeds the maximum allocation size of `alloc`. 1927 ]] 1928] 1929[endsect] 1930[section:overload9 basic_multi_buffer::basic_multi_buffer (9 of 10 overloads)] 1931Copy Constructor. 1932[heading Synopsis] 1933``` 1934template< 1935 class OtherAlloc> 1936basic_multi_buffer( 1937 basic_multi_buffer< OtherAlloc > const& other); 1938``` 1939 1940[heading Description] 1941This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1942[heading Parameters] 1943[table [[Name][Description]] 1944 [[`other`][ 1945 1946The object to copy from. 1947 ]] 1948] 1949[heading Exceptions] 1950[table [[Type][Thrown On]] 1951 [[`std::length_error`][ 1952 1953if `other.size()` exceeds the maximum allocation size of the allocator. 1954 ]] 1955] 1956[endsect] 1957[section:overload10 basic_multi_buffer::basic_multi_buffer (10 of 10 overloads)] 1958Copy Constructor. 1959[heading Synopsis] 1960``` 1961template< 1962 class OtherAlloc> 1963basic_multi_buffer( 1964 basic_multi_buffer< OtherAlloc > const& other, 1965 allocator_type const& alloc); 1966``` 1967 1968[heading Description] 1969This container is constructed with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 1970[heading Parameters] 1971[table [[Name][Description]] 1972 [[`other`][ 1973 1974The object to copy from. 1975 ]] 1976 [[`alloc`][ 1977 1978The allocator to use for the object. 1979 ]] 1980] 1981[heading Exceptions] 1982[table [[Type][Thrown On]] 1983 [[`std::length_error`][ 1984 1985if `other.size()` exceeds the maximum allocation size of `alloc`. 1986 ]] 1987] 1988[endsect] 1989[endsect] 1990 1991[section:capacity basic_multi_buffer::capacity] 1992[indexterm2 capacity..basic_multi_buffer] 1993Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 1994[heading Synopsis] 1995``` 1996std::size_t 1997capacity() const; 1998``` 1999 2000[heading Description] 2001[endsect] 2002[section:cdata basic_multi_buffer::cdata] 2003[indexterm2 cdata..basic_multi_buffer] 2004Returns a constant buffer sequence representing the readable bytes. 2005[heading Synopsis] 2006``` 2007const_buffers_type 2008cdata() const; 2009``` 2010 2011[heading Description] 2012[heading Remarks] 2013The sequence may contain multiple contiguous memory regions. 2014[endsect] 2015[section:clear basic_multi_buffer::clear] 2016[indexterm2 clear..basic_multi_buffer] 2017Set the size of the readable and writable bytes to zero. 2018[heading Synopsis] 2019``` 2020void 2021clear(); 2022``` 2023 2024[heading Description] 2025This clears the buffer without changing capacity. Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] become invalid. 2026[heading Exception Safety] 2027 2028No-throw guarantee. [endsect] 2029[section:commit basic_multi_buffer::commit] 2030[indexterm2 commit..basic_multi_buffer] 2031Append writable bytes to the readable bytes. 2032[heading Synopsis] 2033``` 2034void 2035commit( 2036 size_type n); 2037``` 2038 2039[heading Description] 2040Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 2041All buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] are invalidated. Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] remain valid. 2042[heading Parameters] 2043[table [[Name][Description]] 2044 [[`n`][ 2045 2046The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 2047 ]] 2048] 2049[heading Exception Safety] 2050 2051No-throw guarantee. [endsect] 2052[section:const_buffers_type basic_multi_buffer::const_buffers_type] 2053[indexterm2 const_buffers_type..basic_multi_buffer] 2054The ConstBufferSequence used to represent the readable bytes. 2055[heading Synopsis] 2056 2057``` 2058using const_buffers_type = ``['implementation-defined]``; 2059``` 2060 2061[heading Description] 2062[endsect] 2063[section:consume basic_multi_buffer::consume] 2064[indexterm2 consume..basic_multi_buffer] 2065Remove bytes from beginning of the readable bytes. 2066[heading Synopsis] 2067``` 2068void 2069consume( 2070 size_type n); 2071``` 2072 2073[heading Description] 2074Removes n bytes from the beginning of the readable bytes. 2075All buffers sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] are invalidated. 2076[heading Parameters] 2077[table [[Name][Description]] 2078 [[`n`][ 2079 2080The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 2081 ]] 2082] 2083[heading Exception Safety] 2084 2085No-throw guarantee. [endsect] 2086[section:data basic_multi_buffer::data] 2087[indexterm2 data..basic_multi_buffer] 2088Returns a constant buffer sequence representing the readable bytes. ``` 2089const_buffers_type 2090``[link beast.ref.boost__beast__basic_multi_buffer.data.overload1 data]``() const; 2091 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.data.overload1 more...]]`` 2092 2093``` 2094Returns a mutable buffer sequence representing the readable bytes. ``` 2095mutable_data_type 2096``[link beast.ref.boost__beast__basic_multi_buffer.data.overload2 data]``(); 2097 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.data.overload2 more...]]`` 2098``` 2099[section:overload1 basic_multi_buffer::data (1 of 2 overloads)] 2100Returns a constant buffer sequence representing the readable bytes. 2101[heading Synopsis] 2102``` 2103const_buffers_type 2104data() const; 2105``` 2106 2107[heading Description] 2108[heading Remarks] 2109The sequence may contain multiple contiguous memory regions. 2110[endsect] 2111[section:overload2 basic_multi_buffer::data (2 of 2 overloads)] 2112Returns a mutable buffer sequence representing the readable bytes. 2113[heading Synopsis] 2114``` 2115mutable_data_type 2116data(); 2117``` 2118 2119[heading Description] 2120[heading Remarks] 2121The sequence may contain multiple contiguous memory regions. 2122[endsect] 2123[endsect] 2124 2125[section:get_allocator basic_multi_buffer::get_allocator] 2126[indexterm2 get_allocator..basic_multi_buffer] 2127Returns a copy of the allocator used. 2128[heading Synopsis] 2129``` 2130allocator_type 2131get_allocator() const; 2132``` 2133 2134[heading Description] 2135[endsect] 2136[section:max_size basic_multi_buffer::max_size] 2137[indexterm2 max_size..basic_multi_buffer] 2138Set the maximum allowed capacity. ``` 2139void 2140``[link beast.ref.boost__beast__basic_multi_buffer.max_size.overload1 max_size]``( 2141 std::size_t n); 2142 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.max_size.overload1 more...]]`` 2143 2144``` 2145Return the maximum number of bytes, both readable and writable, that can ever be held. ``` 2146size_type 2147``[link beast.ref.boost__beast__basic_multi_buffer.max_size.overload2 max_size]``() const; 2148 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.max_size.overload2 more...]]`` 2149``` 2150[section:overload1 basic_multi_buffer::max_size (1 of 2 overloads)] 2151Set the maximum allowed capacity. 2152[heading Synopsis] 2153``` 2154void 2155max_size( 2156 std::size_t n); 2157``` 2158 2159[heading Description] 2160This function changes the currently configured upper limit on capacity to the specified value. 2161[heading Parameters] 2162[table [[Name][Description]] 2163 [[`n`][ 2164 2165The maximum number of bytes ever allowed for capacity. 2166 ]] 2167] 2168[heading Exception Safety] 2169 2170No-throw guarantee. [endsect] 2171[section:overload2 basic_multi_buffer::max_size (2 of 2 overloads)] 2172Return the maximum number of bytes, both readable and writable, that can ever be held. 2173[heading Synopsis] 2174``` 2175size_type 2176max_size() const; 2177``` 2178 2179[heading Description] 2180[endsect] 2181[endsect] 2182 2183[section:mutable_buffers_type basic_multi_buffer::mutable_buffers_type] 2184[indexterm2 mutable_buffers_type..basic_multi_buffer] 2185The MutableBufferSequence used to represent the writable bytes. 2186[heading Synopsis] 2187 2188``` 2189using mutable_buffers_type = ``['implementation-defined]``; 2190``` 2191 2192[heading Description] 2193[endsect] 2194[section:mutable_data_type basic_multi_buffer::mutable_data_type] 2195[indexterm2 mutable_data_type..basic_multi_buffer] 2196The MutableBufferSequence used to represent the readable bytes. 2197[heading Synopsis] 2198 2199``` 2200using mutable_data_type = ``['implementation-defined]``; 2201``` 2202 2203[heading Description] 2204[endsect] 2205[section:operator_eq_ basic_multi_buffer::operator=] 2206[indexterm2 operator=..basic_multi_buffer] 2207Move Assignment. ``` 2208basic_multi_buffer& 2209``[link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload1 operator=]``( 2210 basic_multi_buffer&& other); 2211 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload1 more...]]`` 2212 2213``` 2214Copy Assignment. ``` 2215basic_multi_buffer& 2216``[link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload2 operator=]``( 2217 basic_multi_buffer const& other); 2218 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload2 more...]]`` 2219 2220template< 2221 class OtherAlloc> 2222basic_multi_buffer& 2223``[link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload3 operator=]``( 2224 basic_multi_buffer< OtherAlloc > const& other); 2225 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer.operator_eq_.overload3 more...]]`` 2226``` 2227[section:overload1 basic_multi_buffer::operator= (1 of 3 overloads)] 2228Move Assignment. 2229[heading Synopsis] 2230``` 2231basic_multi_buffer& 2232operator=( 2233 basic_multi_buffer&& other); 2234``` 2235 2236[heading Description] 2237The container is assigned with the contents of `other` using move semantics. The maximum size will be the same as the moved-from object. 2238Buffer sequences previously obtained from `other` using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] remain valid after the move. 2239[heading Parameters] 2240[table [[Name][Description]] 2241 [[`other`][ 2242 2243The object to move from. After the move, the moved-from object will have zero capacity, zero readable bytes, and zero writable bytes. 2244 ]] 2245] 2246[endsect] 2247[section:overload2 basic_multi_buffer::operator= (2 of 3 overloads)] 2248Copy Assignment. 2249[heading Synopsis] 2250``` 2251basic_multi_buffer& 2252operator=( 2253 basic_multi_buffer const& other); 2254``` 2255 2256[heading Description] 2257The container is assigned with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 2258After the copy, `this` will have zero writable bytes. 2259[heading Parameters] 2260[table [[Name][Description]] 2261 [[`other`][ 2262 2263The object to copy from. 2264 ]] 2265] 2266[heading Exceptions] 2267[table [[Type][Thrown On]] 2268 [[`std::length_error`][ 2269 2270if `other.size()` exceeds the maximum allocation size of the allocator. 2271 ]] 2272] 2273[endsect] 2274[section:overload3 basic_multi_buffer::operator= (3 of 3 overloads)] 2275Copy Assignment. 2276[heading Synopsis] 2277``` 2278template< 2279 class OtherAlloc> 2280basic_multi_buffer& 2281operator=( 2282 basic_multi_buffer< OtherAlloc > const& other); 2283``` 2284 2285[heading Description] 2286The container is assigned with the contents of `other` using copy semantics. The maximum size will be the same as the copied object. 2287After the copy, `this` will have zero writable bytes. 2288[heading Parameters] 2289[table [[Name][Description]] 2290 [[`other`][ 2291 2292The object to copy from. 2293 ]] 2294] 2295[heading Exceptions] 2296[table [[Type][Thrown On]] 2297 [[`std::length_error`][ 2298 2299if `other.size()` exceeds the maximum allocation size of the allocator. 2300 ]] 2301] 2302[endsect] 2303[endsect] 2304 2305[section:prepare basic_multi_buffer::prepare] 2306[indexterm2 prepare..basic_multi_buffer] 2307Returns a mutable buffer sequence representing writable bytes. 2308[heading Synopsis] 2309``` 2310mutable_buffers_type 2311prepare( 2312 size_type n); 2313``` 2314 2315[heading Description] 2316Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. Memory may be reallocated as needed. 2317All buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] are invalidated. Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] remain valid. 2318[heading Parameters] 2319[table [[Name][Description]] 2320 [[`n`][ 2321 2322The desired number of bytes in the returned buffer sequence. 2323 ]] 2324] 2325[heading Exceptions] 2326[table [[Type][Thrown On]] 2327 [[`std::length_error`][ 2328 2329if `size() + n` exceeds `max_size()`. 2330 ]] 2331] 2332[heading Exception Safety] 2333 2334Strong guarantee. [endsect] 2335[section:reserve basic_multi_buffer::reserve] 2336[indexterm2 reserve..basic_multi_buffer] 2337Guarantee a minimum capacity. 2338[heading Synopsis] 2339``` 2340void 2341reserve( 2342 std::size_t n); 2343``` 2344 2345[heading Description] 2346This function adjusts the internal storage (if necessary) to guarantee space for at least `n` bytes. 2347Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] remain valid, while buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] become invalid. 2348[heading Parameters] 2349[table [[Name][Description]] 2350 [[`n`][ 2351 2352The minimum number of byte for the new capacity. If this value is greater than the maximum size, then the maximum size will be adjusted upwards to this value. 2353 ]] 2354] 2355[heading Exceptions] 2356[table [[Type][Thrown On]] 2357 [[`std::length_error`][ 2358 2359if n is larger than the maximum allocation size of the allocator. 2360 ]] 2361] 2362[heading Exception Safety] 2363 2364Strong guarantee. [endsect] 2365[section:shrink_to_fit basic_multi_buffer::shrink_to_fit] 2366[indexterm2 shrink_to_fit..basic_multi_buffer] 2367Reallocate the buffer to fit the readable bytes exactly. 2368[heading Synopsis] 2369``` 2370void 2371shrink_to_fit(); 2372``` 2373 2374[heading Description] 2375Buffer sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] or [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] become invalid. 2376[heading Exception Safety] 2377 2378Strong guarantee. [endsect] 2379[section:size basic_multi_buffer::size] 2380[indexterm2 size..basic_multi_buffer] 2381Returns the number of readable bytes. 2382[heading Synopsis] 2383``` 2384size_type 2385size() const; 2386``` 2387 2388[heading Description] 2389[endsect] 2390[section:swap basic_multi_buffer::swap] 2391[indexterm2 swap..basic_multi_buffer] 2392Exchange two dynamic buffers. 2393[heading Synopsis] 2394 2395Defined in header [include_file boost/beast/core/multi_buffer.hpp] 2396 2397 2398``` 2399template< 2400 class Alloc> 2401friend void 2402swap( 2403 basic_multi_buffer< Alloc >& lhs, 2404 basic_multi_buffer< Alloc >& rhs); 2405``` 2406 2407[heading Description] 2408 2409 2410 2411Convenience header [include_file boost/beast/core.hpp] 2412 2413[endsect] 2414[section:basic_multi_buffer_dtor_ basic_multi_buffer::~basic_multi_buffer] 2415[indexterm2 ~basic_multi_buffer..basic_multi_buffer] 2416Destructor. 2417[heading Synopsis] 2418``` 2419~basic_multi_buffer(); 2420``` 2421 2422[heading Description] 2423[endsect] 2424 2425 2426 2427Convenience header [include_file boost/beast/core.hpp] 2428 2429[endsect] 2430 2431 2432 2433[section:boost__beast__basic_multi_buffer__element basic_multi_buffer::element] 2434 2435[heading Synopsis] 2436 2437Defined in header [include_file boost/beast/core/multi_buffer.hpp] 2438 2439 2440 2441``` 2442class element : 2443 public boost::intrusive::list_base_hook< boost::intrusive::link_mode< boost::intrusive::normal_link > > 2444``` 2445[heading Member Functions] 2446[table [[Name][Description]] 2447 [ 2448 [[link beast.ref.boost__beast__basic_multi_buffer__element.data [*data]]] 2449 [ 2450 2451 ] 2452 ] 2453 [ 2454 [[link beast.ref.boost__beast__basic_multi_buffer__element.element [*element]]] 2455 [ 2456 2457 ] 2458 ] 2459 [ 2460 [[link beast.ref.boost__beast__basic_multi_buffer__element.size [*size]]] 2461 [ 2462 2463 ] 2464 ] 2465] 2466 2467[heading Description] 2468[section:data basic_multi_buffer::element::data] 2469[indexterm2 data..basic_multi_buffer::element] 2470 2471[heading Synopsis] 2472``` 2473char* 2474data() const; 2475``` 2476 2477[heading Description] 2478[endsect] 2479[section:element basic_multi_buffer::element::element] 2480[indexterm2 element..basic_multi_buffer::element] 2481``` 2482``[link beast.ref.boost__beast__basic_multi_buffer__element.element.overload1 element]``( 2483 element const&); 2484 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer__element.element.overload1 more...]]`` 2485 2486explicit 2487``[link beast.ref.boost__beast__basic_multi_buffer__element.element.overload2 element]``( 2488 size_type n); 2489 ``[''''»''' [link beast.ref.boost__beast__basic_multi_buffer__element.element.overload2 more...]]`` 2490``` 2491[section:overload1 basic_multi_buffer::element::element (1 of 2 overloads)] 2492 2493[heading Synopsis] 2494``` 2495element( 2496 element const&); 2497``` 2498 2499[heading Description] 2500[endsect] 2501[section:overload2 basic_multi_buffer::element::element (2 of 2 overloads)] 2502 2503[heading Synopsis] 2504``` 2505element( 2506 size_type n); 2507``` 2508 2509[heading Description] 2510[endsect] 2511[endsect] 2512 2513[section:size basic_multi_buffer::element::size] 2514[indexterm2 size..basic_multi_buffer::element] 2515 2516[heading Synopsis] 2517``` 2518size_type 2519size() const; 2520``` 2521 2522[heading Description] 2523[endsect] 2524 2525 2526 2527Convenience header [include_file boost/beast/core.hpp] 2528 2529[endsect] 2530 2531 2532 2533[section:boost__beast__basic_multi_buffer__readable_bytes basic_multi_buffer::readable_bytes] 2534 2535[heading Synopsis] 2536 2537Defined in header [include_file boost/beast/core/multi_buffer.hpp] 2538 2539 2540 2541``` 2542template< 2543 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 2544class readable_bytes 2545``` 2546 2547[heading Description] 2548 2549 2550 2551Convenience header [include_file boost/beast/core.hpp] 2552 2553[endsect] 2554 2555 2556 2557[section:boost__beast__basic_stream basic_stream] 2558A stream socket wrapper with timeouts, an executor, and a rate limit policy. 2559[heading Synopsis] 2560 2561Defined in header [include_file boost/beast/core/basic_stream.hpp] 2562 2563 2564 2565``` 2566template< 2567 class __Protocol__, 2568 class __Executor__ = net::executor, 2569 class __RatePolicy__ = unlimited_rate_policy> 2570class basic_stream 2571``` 2572[heading Types] 2573[table [[Name][Description]] 2574 [ 2575 [[link beast.ref.boost__beast__basic_stream__rebind_executor [*rebind_executor]]] 2576 [ 2577 Rebinds the stream type to another executor. 2578 ] 2579 ] 2580 [ 2581 [[link beast.ref.boost__beast__basic_stream.endpoint_type [*endpoint_type]]] 2582 [ 2583 The endpoint type. 2584 ] 2585 ] 2586 [ 2587 [[link beast.ref.boost__beast__basic_stream.executor_type [*executor_type]]] 2588 [ 2589 The type of the executor associated with the stream. 2590 ] 2591 ] 2592 [ 2593 [[link beast.ref.boost__beast__basic_stream.protocol_type [*protocol_type]]] 2594 [ 2595 The protocol type. 2596 ] 2597 ] 2598 [ 2599 [[link beast.ref.boost__beast__basic_stream.socket_type [*socket_type]]] 2600 [ 2601 The type of the underlying socket. 2602 ] 2603 ] 2604] 2605[heading Member Functions] 2606[table [[Name][Description]] 2607 [ 2608 [[link beast.ref.boost__beast__basic_stream.async_connect [*async_connect]]] 2609 [ 2610 Connect the stream to the specified endpoint asynchronously. 2611 2612 Establishes a connection by trying each endpoint in a sequence asynchronously. 2613 ] 2614 ] 2615 [ 2616 [[link beast.ref.boost__beast__basic_stream.async_read_some [*async_read_some]]] 2617 [ 2618 Read some data asynchronously. 2619 ] 2620 ] 2621 [ 2622 [[link beast.ref.boost__beast__basic_stream.async_write_some [*async_write_some]]] 2623 [ 2624 Write some data asynchronously. 2625 ] 2626 ] 2627 [ 2628 [[link beast.ref.boost__beast__basic_stream.basic_stream [*basic_stream]]] 2629 [ 2630 Constructor. 2631 2632 Move constructor. 2633 ] 2634 ] 2635 [ 2636 [[link beast.ref.boost__beast__basic_stream.cancel [*cancel]]] 2637 [ 2638 Cancel all asynchronous operations associated with the socket. 2639 ] 2640 ] 2641 [ 2642 [[link beast.ref.boost__beast__basic_stream.close [*close]]] 2643 [ 2644 Close the timed stream. 2645 ] 2646 ] 2647 [ 2648 [[link beast.ref.boost__beast__basic_stream.connect [*connect]]] 2649 [ 2650 Connect the stream to the specified endpoint. 2651 2652 Establishes a connection by trying each endpoint in a sequence. 2653 ] 2654 ] 2655 [ 2656 [[link beast.ref.boost__beast__basic_stream.expires_after [*expires_after]]] 2657 [ 2658 Set the timeout for the next logical operation. 2659 ] 2660 ] 2661 [ 2662 [[link beast.ref.boost__beast__basic_stream.expires_at [*expires_at]]] 2663 [ 2664 Set the timeout for the next logical operation. 2665 ] 2666 ] 2667 [ 2668 [[link beast.ref.boost__beast__basic_stream.expires_never [*expires_never]]] 2669 [ 2670 Disable the timeout for the next logical operation. 2671 ] 2672 ] 2673 [ 2674 [[link beast.ref.boost__beast__basic_stream.get_executor [*get_executor]]] 2675 [ 2676 Get the executor associated with the object. 2677 ] 2678 ] 2679 [ 2680 [[link beast.ref.boost__beast__basic_stream.operator_eq_ [*operator=]]] 2681 [ 2682 Move assignment (deleted). 2683 ] 2684 ] 2685 [ 2686 [[link beast.ref.boost__beast__basic_stream.rate_policy [*rate_policy]]] 2687 [ 2688 Returns the rate policy associated with the object. 2689 ] 2690 ] 2691 [ 2692 [[link beast.ref.boost__beast__basic_stream.read_some [*read_some]]] 2693 [ 2694 Read some data. 2695 ] 2696 ] 2697 [ 2698 [[link beast.ref.boost__beast__basic_stream.release_socket [*release_socket]]] 2699 [ 2700 Release ownership of the underlying socket. 2701 ] 2702 ] 2703 [ 2704 [[link beast.ref.boost__beast__basic_stream.socket [*socket]]] 2705 [ 2706 Return a reference to the underlying socket. 2707 ] 2708 ] 2709 [ 2710 [[link beast.ref.boost__beast__basic_stream.write_some [*write_some]]] 2711 [ 2712 Write some data. 2713 ] 2714 ] 2715 [ 2716 [[link beast.ref.boost__beast__basic_stream.basic_stream_dtor_ [*~basic_stream]]] 2717 [ 2718 Destructor. 2719 ] 2720 ] 2721] 2722 2723[heading Description] 2724This stream wraps a `net::basic_stream_socket` to provide the following features: 2725 2726* An ['Executor] may be associated with the stream, which will be used to invoke any completion handlers which do not already have an associated executor. This achieves support for [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 2727 2728 2729* Timeouts may be specified for each logical asynchronous operation performing any reading, writing, or connecting. 2730 2731 2732* A ['RatePolicy] may be associated with the stream, to implement rate limiting through the policy's interface. 2733 2734Although the stream supports multiple concurrent outstanding asynchronous operations, the stream object is not thread-safe. The caller is responsible for ensuring that the stream is accessed from only one thread at a time. This includes the times when the stream, and its underlying socket, are accessed by the networking implementation. To meet this thread safety requirement, all asynchronous operations must be performed by the stream within the same implicit strand (only one thread `net::io_context::run`) or within the same explicit strand, such as an instance of `net::strand`. 2735Completion handlers with explicit associated executors (such as those arising from use of `net::bind_executor`) will be invoked by the stream using the associated executor. Otherwise, the completion handler will be invoked by the executor associated with the stream upon construction. The type of executor used with this stream must meet the following requirements: 2736 2737* Function objects submitted to the executor shall never run concurrently with each other. 2738 2739The executor type `net::strand` meets these requirements. Use of a strand as the executor in the stream class template offers an additional notational convenience: the strand does not need to be specified in each individual initiating function call. 2740Unlike other stream wrappers, the underlying socket is accessed through the [link beast.ref.boost__beast__basic_stream.socket `basic_stream::socket`] member function instead of `next_layer`. This causes the [link beast.ref.boost__beast__basic_stream `basic_stream`] to be returned in calls to [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]. 2741[heading Usage] 2742 2743To use this stream declare an instance of the class. Then, before each logical operation for which a timeout is desired, call [link beast.ref.boost__beast__basic_stream.expires_after `basic_stream::expires_after`] with a duration, or call [link beast.ref.boost__beast__basic_stream.expires_at `basic_stream::expires_at`] with a time point. Alternatively, call [link beast.ref.boost__beast__basic_stream.expires_never `basic_stream::expires_never`] to disable the timeout for subsequent logical operations. A logical operation is any series of one or more direct or indirect calls to the timeout stream's asynchronous read, asynchronous write, or asynchronous connect functions. 2744When a timeout is set and a mixed operation is performed (one that includes both reads and writes, for example) the timeout applies to all of the intermediate asynchronous operations used in the enclosing operation. This allows timeouts to be applied to stream algorithms which were not written specifically to allow for timeouts, when those algorithms are passed a timeout stream with a timeout set. 2745When a timeout occurs the socket will be closed, canceling any pending I/O operations. The completion handlers for these canceled operations will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 2746[heading Examples] 2747 2748This function reads an HTTP request with a timeout, then sends the HTTP response with a different timeout. 2749 2750``` 2751 void process_http_1 (tcp_stream& stream, net::yield_context yield) 2752 { 2753 flat_buffer buffer; 2754 http::request<http::empty_body> req; 2755 2756 // Read the request, with a 15 second timeout 2757 stream.expires_after(std::chrono::seconds(15)); 2758 http::async_read(stream, buffer, req, yield); 2759 2760 // Calculate the response 2761 http::response<http::string_body> res = make_response(req); 2762 2763 // Send the response, with a 30 second timeout. 2764 stream.expires_after (std::chrono::seconds(30)); 2765 http::async_write (stream, res, yield); 2766 } 2767``` 2768The example above could be expressed using a single timeout with a simple modification. The function that follows first reads an HTTP request then sends the HTTP response, with a single timeout that applies to the entire combined operation of reading and writing: 2769 2770``` 2771 void process_http_2 (tcp_stream& stream, net::yield_context yield) 2772 { 2773 flat_buffer buffer; 2774 http::request<http::empty_body> req; 2775 2776 // Require that the read and write combined take no longer than 30 seconds 2777 stream.expires_after(std::chrono::seconds(30)); 2778 2779 http::async_read(stream, buffer, req, yield); 2780 2781 http::response<http::string_body> res = make_response(req); 2782 http::async_write (stream, res, yield); 2783 } 2784``` 2785Some stream algorithms, such as `ssl::stream::async_handshake` perform both reads and writes. A timeout set before calling the initiating function of such composite stream algorithms will apply to the entire composite operation. For example, a timeout may be set on performing the SSL handshake thusly: 2786 2787``` 2788 void do_ssl_handshake (net::ssl::stream<tcp_stream>& stream, net::yield_context yield) 2789 { 2790 // Require that the SSL handshake take no longer than 10 seconds 2791 stream.expires_after(std::chrono::seconds(10)); 2792 2793 stream.async_handshake(net::ssl::stream_base::client, yield); 2794 } 2795``` 2796[heading Blocking I/O] 2797 2798Synchronous functions behave identically as that of the wrapped `net::basic_stream_socket`. Timeouts are not available when performing blocking calls. 2799[heading Template Parameters] 2800[table [[Type][Description]] 2801 [[`Protocol`][ 2802 2803A type meeting the requirements of ['Protocol] representing the protocol the protocol to use for the basic stream socket. A common choice is `net::ip::tcp`. 2804 ]] 2805 [[`Executor`][ 2806 2807A type meeting the requirements of ['Executor] to be used for submitting all completion handlers which do not already have an associated executor. If this type is omitted, the default of `net::executor` will be used. 2808 ]] 2809] 2810[heading Thread Safety] 2811['Distinct objects]: Safe. 2812 2813['Shared objects]: Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 2814[heading See Also] 2815 2816 2817* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 2818 2819[section:async_connect basic_stream::async_connect] 2820[indexterm2 async_connect..basic_stream] 2821Connect the stream to the specified endpoint asynchronously. ``` 2822template< 2823 class __ConnectHandler__ = net::default_completion_token_t<executor_type>> 2824``__deduced__`` 2825``[link beast.ref.boost__beast__basic_stream.async_connect.overload1 async_connect]``( 2826 endpoint_type const& ep, 2827 ConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2828 ``[''''»''' [link beast.ref.boost__beast__basic_stream.async_connect.overload1 more...]]`` 2829 2830``` 2831Establishes a connection by trying each endpoint in a sequence asynchronously. ``` 2832template< 2833 class __EndpointSequence__, 2834 class __RangeConnectHandler__ = net::default_completion_token_t<executor_type>> 2835``__deduced__`` 2836``[link beast.ref.boost__beast__basic_stream.async_connect.overload2 async_connect]``( 2837 EndpointSequence const& endpoints, 2838 RangeConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2839 ``[''''»''' [link beast.ref.boost__beast__basic_stream.async_connect.overload2 more...]]`` 2840 2841template< 2842 class __EndpointSequence__, 2843 class __ConnectCondition__, 2844 class __RangeConnectHandler__ = net::default_completion_token_t<executor_type>> 2845``__deduced__`` 2846``[link beast.ref.boost__beast__basic_stream.async_connect.overload3 async_connect]``( 2847 EndpointSequence const& endpoints, 2848 ConnectCondition connect_condition, 2849 RangeConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2850 ``[''''»''' [link beast.ref.boost__beast__basic_stream.async_connect.overload3 more...]]`` 2851 2852template< 2853 class Iterator, 2854 class __IteratorConnectHandler__ = net::default_completion_token_t<executor_type>> 2855``__deduced__`` 2856``[link beast.ref.boost__beast__basic_stream.async_connect.overload4 async_connect]``( 2857 Iterator begin, 2858 Iterator end, 2859 IteratorConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2860 ``[''''»''' [link beast.ref.boost__beast__basic_stream.async_connect.overload4 more...]]`` 2861 2862template< 2863 class Iterator, 2864 class __ConnectCondition__, 2865 class __IteratorConnectHandler__ = net::default_completion_token_t<executor_type>> 2866``__deduced__`` 2867``[link beast.ref.boost__beast__basic_stream.async_connect.overload5 async_connect]``( 2868 Iterator begin, 2869 Iterator end, 2870 ConnectCondition connect_condition, 2871 IteratorConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2872 ``[''''»''' [link beast.ref.boost__beast__basic_stream.async_connect.overload5 more...]]`` 2873``` 2874[section:overload1 basic_stream::async_connect (1 of 5 overloads)] 2875Connect the stream to the specified endpoint asynchronously. 2876[heading Synopsis] 2877``` 2878template< 2879 class __ConnectHandler__ = net::default_completion_token_t<executor_type>> 2880``__deduced__`` 2881async_connect( 2882 endpoint_type const& ep, 2883 ConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2884``` 2885 2886[heading Description] 2887This function is used to asynchronously connect the underlying socket to the specified remote endpoint. The function call always returns immediately. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 2888If the timeout timer expires while the operation is outstanding, the operation will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 2889[heading Parameters] 2890[table [[Name][Description]] 2891 [[`ep`][ 2892 2893The remote endpoint to which the underlying socket will be connected. Copies will be made of the endpoint object as required. 2894 ]] 2895 [[`handler`][ 2896 2897The 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: 2898``` 2899 void handler( 2900 error_code ec // Result of operation 2901 ); 2902``` 2903Regardless 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 `net::post`. 2904 ]] 2905] 2906[heading See Also] 2907[link beast.ref.boost__beast__basic_stream.async_connect `basic_stream::async_connect`] 2908[endsect] 2909[section:overload2 basic_stream::async_connect (2 of 5 overloads)] 2910Establishes a connection by trying each endpoint in a sequence asynchronously. 2911[heading Synopsis] 2912``` 2913template< 2914 class __EndpointSequence__, 2915 class __RangeConnectHandler__ = net::default_completion_token_t<executor_type>> 2916``__deduced__`` 2917async_connect( 2918 EndpointSequence const& endpoints, 2919 RangeConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2920``` 2921 2922[heading Description] 2923This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 2924The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the underlying socket's `async_connect` function. 2925If the timeout timer expires while the operation is outstanding, the current connection attempt will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 2926[heading Parameters] 2927[table [[Name][Description]] 2928 [[`endpoints`][ 2929 2930A sequence of endpoints. This this object must meet the requirements of ['EndpointSequence]. 2931 ]] 2932 [[`handler`][ 2933 2934The 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: 2935``` 2936 void handler( 2937 // Result of operation. if the sequence is empty, set to 2938 // net::error::not_found. Otherwise, contains the 2939 // error from the last connection attempt. 2940 error_code const& error, 2941 2942 // On success, the successfully connected endpoint. 2943 // Otherwise, a default-constructed endpoint. 2944 typename Protocol::endpoint const& endpoint 2945 ); 2946``` 2947Regardless 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 `net::post`. 2948 ]] 2949] 2950[endsect] 2951[section:overload3 basic_stream::async_connect (3 of 5 overloads)] 2952Establishes a connection by trying each endpoint in a sequence asynchronously. 2953[heading Synopsis] 2954``` 2955template< 2956 class __EndpointSequence__, 2957 class __ConnectCondition__, 2958 class __RangeConnectHandler__ = net::default_completion_token_t<executor_type>> 2959``__deduced__`` 2960async_connect( 2961 EndpointSequence const& endpoints, 2962 ConnectCondition connect_condition, 2963 RangeConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 2964``` 2965 2966[heading Description] 2967This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 2968The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the underlying socket's `async_connect` function. 2969If the timeout timer expires while the operation is outstanding, the current connection attempt will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 2970[heading Parameters] 2971[table [[Name][Description]] 2972 [[`endpoints`][ 2973 2974A sequence of endpoints. This this object must meet the requirements of ['EndpointSequence]. 2975 ]] 2976 [[`connect_condition`][ 2977 2978A function object that is called prior to each connection attempt. The signature of the function object must be: 2979``` 2980 bool connect_condition( 2981 error_code const& ec, 2982 typename Protocol::endpoint const& next); 2983``` 2984The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped. 2985 ]] 2986 [[`handler`][ 2987 2988The 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: 2989``` 2990 void handler( 2991 // Result of operation. if the sequence is empty, set to 2992 // net::error::not_found. Otherwise, contains the 2993 // error from the last connection attempt. 2994 error_code const& error, 2995 2996 // On success, the successfully connected endpoint. 2997 // Otherwise, a default-constructed endpoint. 2998 typename Protocol::endpoint const& endpoint 2999 ); 3000``` 3001Regardless 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 `net::post`. 3002 ]] 3003] 3004[heading Example] 3005The following connect condition function object can be used to output information about the individual connection attempts: 3006``` 3007 struct my_connect_condition 3008 { 3009 bool operator()( 3010 error_code const& ec, 3011 net::ip::tcp::endpoint const& next) 3012 { 3013 if (ec) 3014 std::cout << "Error: " << ec.message() << std::endl; 3015 std::cout << "Trying: " << next << std::endl; 3016 return true; 3017 } 3018 }; 3019``` 3020[endsect] 3021[section:overload4 basic_stream::async_connect (4 of 5 overloads)] 3022Establishes a connection by trying each endpoint in a sequence asynchronously. 3023[heading Synopsis] 3024``` 3025template< 3026 class Iterator, 3027 class __IteratorConnectHandler__ = net::default_completion_token_t<executor_type>> 3028``__deduced__`` 3029async_connect( 3030 Iterator begin, 3031 Iterator end, 3032 IteratorConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 3033``` 3034 3035[heading Description] 3036This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3037The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the underlying socket's `async_connect` function. 3038If the timeout timer expires while the operation is outstanding, the current connection attempt will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 3039[heading Parameters] 3040[table [[Name][Description]] 3041 [[`begin`][ 3042 3043An iterator pointing to the start of a sequence of endpoints. 3044 ]] 3045 [[`end`][ 3046 3047An iterator pointing to the end of a sequence of endpoints. 3048 ]] 3049 [[`handler`][ 3050 3051The 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: 3052``` 3053 void handler( 3054 // Result of operation. if the sequence is empty, set to 3055 // net::error::not_found. Otherwise, contains the 3056 // error from the last connection attempt. 3057 error_code const& error, 3058 3059 // On success, an iterator denoting the successfully 3060 // connected endpoint. Otherwise, the end iterator. 3061 Iterator iterator 3062 ); 3063``` 3064Regardless 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 `net::post`. 3065 ]] 3066] 3067[endsect] 3068[section:overload5 basic_stream::async_connect (5 of 5 overloads)] 3069Establishes a connection by trying each endpoint in a sequence asynchronously. 3070[heading Synopsis] 3071``` 3072template< 3073 class Iterator, 3074 class __ConnectCondition__, 3075 class __IteratorConnectHandler__ = net::default_completion_token_t<executor_type>> 3076``__deduced__`` 3077async_connect( 3078 Iterator begin, 3079 Iterator end, 3080 ConnectCondition connect_condition, 3081 IteratorConnectHandler&& handler = net::default_completion_token_t< executor_type >{}); 3082``` 3083 3084[heading Description] 3085This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the underlying socket's `async_connect` function. 3086If the timeout timer expires while the operation is outstanding, the current connection attempt will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 3087[heading Parameters] 3088[table [[Name][Description]] 3089 [[`begin`][ 3090 3091An iterator pointing to the start of a sequence of endpoints. 3092 ]] 3093 [[`end`][ 3094 3095An iterator pointing to the end of a sequence of endpoints. 3096 ]] 3097 [[`connect_condition`][ 3098 3099A function object that is called prior to each connection attempt. The signature of the function object must be: 3100``` 3101 bool connect_condition( 3102 error_code const& ec, 3103 Iterator next); 3104``` 3105 3106 ]] 3107 [[`handler`][ 3108 3109The 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: 3110``` 3111 void handler( 3112 // Result of operation. if the sequence is empty, set to 3113 // net::error::not_found. Otherwise, contains the 3114 // error from the last connection attempt. 3115 error_code const& error, 3116 3117 // On success, an iterator denoting the successfully 3118 // connected endpoint. Otherwise, the end iterator. 3119 Iterator iterator 3120 ); 3121``` 3122Regardless 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 `net::post`. 3123 ]] 3124] 3125[endsect] 3126[endsect] 3127 3128[section:async_read_some basic_stream::async_read_some] 3129[indexterm2 async_read_some..basic_stream] 3130Read some data asynchronously. 3131[heading Synopsis] 3132``` 3133template< 3134 class __MutableBufferSequence__, 3135 class __ReadHandler__ = net::default_completion_token_t<executor_type>> 3136``__deduced__`` 3137async_read_some( 3138 MutableBufferSequence const& buffers, 3139 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 3140``` 3141 3142[heading Description] 3143This function is used to asynchronously read data from the stream. 3144This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 3145 3146* One or more bytes are read from the stream. 3147 3148 3149* An error occurs. 3150 3151The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__basic_stream.read_some `basic_stream::read_some`] or [link beast.ref.boost__beast__basic_stream.async_read_some `basic_stream::async_read_some`] are performed until this operation completes. 3152If the timeout timer expires while the operation is outstanding, the operation will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 3153[heading Parameters] 3154[table [[Name][Description]] 3155 [[`buffers`][ 3156 3157The buffers into which the data will be read. If the size of the buffers is zero bytes, the operation always completes immediately with no error. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. 3158 ]] 3159 [[`handler`][ 3160 3161The 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: 3162``` 3163 void handler( 3164 error_code error, // Result of operation. 3165 std::size_t bytes_transferred // Number of bytes read. 3166 ); 3167``` 3168Regardless 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 `net::post`. 3169 ]] 3170] 3171[heading Remarks] 3172The `async_read_some` operation may not receive all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. 3173[endsect] 3174[section:async_write_some basic_stream::async_write_some] 3175[indexterm2 async_write_some..basic_stream] 3176Write some data asynchronously. 3177[heading Synopsis] 3178``` 3179template< 3180 class __ConstBufferSequence__, 3181 class __WriteHandler__ = net::default_completion_token_t<Executor>> 3182``__deduced__`` 3183async_write_some( 3184 ConstBufferSequence const& buffers, 3185 WriteHandler&& handler = net::default_completion_token_t< Executor >{}); 3186``` 3187 3188[heading Description] 3189This function is used to asynchronously write data to the underlying socket. 3190This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 3191 3192* One or more bytes are written to the stream. 3193 3194 3195* An error occurs. 3196 3197The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__basic_stream.async_write_some `basic_stream::async_write_some`] are performed until this operation completes. 3198If the timeout timer expires while the operation is outstanding, the operation will be canceled and the completion handler will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 3199[heading Parameters] 3200[table [[Name][Description]] 3201 [[`buffers`][ 3202 3203The buffers from which the data will be written. If the size of the buffers is zero bytes, the operation always completes immediately with no error. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. 3204 ]] 3205 [[`handler`][ 3206 3207The 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: 3208``` 3209 void handler( 3210 error_code error, // Result of operation. 3211 std::size_t bytes_transferred // Number of bytes written. 3212 ); 3213``` 3214Regardless 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 `net::post`. 3215 ]] 3216] 3217[heading Remarks] 3218The `async_write_some` operation may not transmit all of the requested number of bytes. Consider using the function `net::async_write` if you need to ensure that the requested amount of data is sent before the asynchronous operation completes. 3219[endsect] 3220[section:basic_stream basic_stream::basic_stream] 3221[indexterm2 basic_stream..basic_stream] 3222Constructor. ``` 3223template< 3224 class... Args> 3225explicit 3226``[link beast.ref.boost__beast__basic_stream.basic_stream.overload1 basic_stream]``( 3227 Args&&... args); 3228 ``[''''»''' [link beast.ref.boost__beast__basic_stream.basic_stream.overload1 more...]]`` 3229 3230template< 3231 class RatePolicy_, 3232 class... Args> 3233explicit 3234``[link beast.ref.boost__beast__basic_stream.basic_stream.overload2 basic_stream]``( 3235 RatePolicy_&& policy, 3236 Args&&... args); 3237 ``[''''»''' [link beast.ref.boost__beast__basic_stream.basic_stream.overload2 more...]]`` 3238 3239``` 3240Move constructor. ``` 3241``[link beast.ref.boost__beast__basic_stream.basic_stream.overload3 basic_stream]``( 3242 basic_stream&& other); 3243 ``[''''»''' [link beast.ref.boost__beast__basic_stream.basic_stream.overload3 more...]]`` 3244``` 3245[section:overload1 basic_stream::basic_stream (1 of 3 overloads)] 3246Constructor. 3247[heading Synopsis] 3248``` 3249template< 3250 class... Args> 3251basic_stream( 3252 Args&&... args); 3253``` 3254 3255[heading Description] 3256This constructor creates the stream by forwarding all arguments to the underlying socket. The socket then needs to be open and connected or accepted before data can be sent or received on it. 3257[heading Parameters] 3258[table [[Name][Description]] 3259 [[`args`][ 3260 3261A list of parameters forwarded to the constructor of the underlying socket. 3262 ]] 3263] 3264[endsect] 3265[section:overload2 basic_stream::basic_stream (2 of 3 overloads)] 3266Constructor. 3267[heading Synopsis] 3268``` 3269template< 3270 class RatePolicy_, 3271 class... Args> 3272basic_stream( 3273 RatePolicy_&& policy, 3274 Args&&... args); 3275``` 3276 3277[heading Description] 3278This constructor creates the stream with the specified rate policy, and forwards all remaining arguments to the underlying socket. The socket then needs to be open and connected or accepted before data can be sent or received on it. 3279[heading Parameters] 3280[table [[Name][Description]] 3281 [[`policy`][ 3282 3283The rate policy object to use. The stream will take ownership of this object by decay-copy. 3284 ]] 3285 [[`args`][ 3286 3287A list of parameters forwarded to the constructor of the underlying socket. 3288 ]] 3289] 3290[endsect] 3291[section:overload3 basic_stream::basic_stream (3 of 3 overloads)] 3292Move constructor. 3293[heading Synopsis] 3294``` 3295basic_stream( 3296 basic_stream&& other); 3297``` 3298 3299[heading Description] 3300[heading Parameters] 3301[table [[Name][Description]] 3302 [[`other`][ 3303 3304The other object from which the move will occur. 3305 ]] 3306] 3307[heading Remarks] 3308Following the move, the moved-from object is in the same state as if newly constructed. 3309[endsect] 3310[endsect] 3311 3312[section:cancel basic_stream::cancel] 3313[indexterm2 cancel..basic_stream] 3314Cancel all asynchronous operations associated with the socket. 3315[heading Synopsis] 3316``` 3317void 3318cancel(); 3319``` 3320 3321[heading Description] 3322This function causes all outstanding asynchronous connect, read, and write operations to finish immediately. Completion handlers for cancelled operations will receive the error `net::error::operation_aborted`. Completion handlers not yet invoked whose operations have completed, will receive the error corresponding to the result of the operation (which may indicate success). [endsect] 3323[section:close basic_stream::close] 3324[indexterm2 close..basic_stream] 3325Close the timed stream. 3326[heading Synopsis] 3327``` 3328void 3329close(); 3330``` 3331 3332[heading Description] 3333This cancels all of the outstanding asynchronous operations as if by calling [link beast.ref.boost__beast__basic_stream.cancel `basic_stream::cancel`], and closes the underlying socket. [endsect] 3334[section:connect basic_stream::connect] 3335[indexterm2 connect..basic_stream] 3336Connect the stream to the specified endpoint. ``` 3337void 3338``[link beast.ref.boost__beast__basic_stream.connect.overload1 connect]``( 3339 endpoint_type const& ep); 3340 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload1 more...]]`` 3341 3342void 3343``[link beast.ref.boost__beast__basic_stream.connect.overload2 connect]``( 3344 endpoint_type const& ep, 3345 error_code& ec); 3346 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload2 more...]]`` 3347 3348``` 3349Establishes a connection by trying each endpoint in a sequence. ``` 3350template< 3351 class __EndpointSequence__> 3352Protocol::endpoint 3353``[link beast.ref.boost__beast__basic_stream.connect.overload3 connect]``( 3354 EndpointSequence const& endpoints); 3355 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload3 more...]]`` 3356 3357template< 3358 class __EndpointSequence__> 3359Protocol::endpoint 3360``[link beast.ref.boost__beast__basic_stream.connect.overload4 connect]``( 3361 EndpointSequence const& endpoints, 3362 error_code& ec); 3363 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload4 more...]]`` 3364 3365template< 3366 class Iterator> 3367Iterator 3368``[link beast.ref.boost__beast__basic_stream.connect.overload5 connect]``( 3369 Iterator begin, 3370 Iterator end); 3371 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload5 more...]]`` 3372 3373template< 3374 class Iterator> 3375Iterator 3376``[link beast.ref.boost__beast__basic_stream.connect.overload6 connect]``( 3377 Iterator begin, 3378 Iterator end, 3379 error_code& ec); 3380 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload6 more...]]`` 3381 3382template< 3383 class __EndpointSequence__, 3384 class __ConnectCondition__> 3385Protocol::endpoint 3386``[link beast.ref.boost__beast__basic_stream.connect.overload7 connect]``( 3387 EndpointSequence const& endpoints, 3388 ConnectCondition connect_condition); 3389 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload7 more...]]`` 3390 3391template< 3392 class __EndpointSequence__, 3393 class __ConnectCondition__> 3394Protocol::endpoint 3395``[link beast.ref.boost__beast__basic_stream.connect.overload8 connect]``( 3396 EndpointSequence const& endpoints, 3397 ConnectCondition connect_condition, 3398 error_code& ec); 3399 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload8 more...]]`` 3400 3401template< 3402 class Iterator, 3403 class __ConnectCondition__> 3404Iterator 3405``[link beast.ref.boost__beast__basic_stream.connect.overload9 connect]``( 3406 Iterator begin, 3407 Iterator end, 3408 ConnectCondition connect_condition); 3409 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload9 more...]]`` 3410 3411template< 3412 class Iterator, 3413 class __ConnectCondition__> 3414Iterator 3415``[link beast.ref.boost__beast__basic_stream.connect.overload10 connect]``( 3416 Iterator begin, 3417 Iterator end, 3418 ConnectCondition connect_condition, 3419 error_code& ec); 3420 ``[''''»''' [link beast.ref.boost__beast__basic_stream.connect.overload10 more...]]`` 3421``` 3422[section:overload1 basic_stream::connect (1 of 10 overloads)] 3423Connect the stream to the specified endpoint. 3424[heading Synopsis] 3425``` 3426void 3427connect( 3428 endpoint_type const& ep); 3429``` 3430 3431[heading Description] 3432This function is used to connect the underlying socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3433[heading Parameters] 3434[table [[Name][Description]] 3435 [[`ep`][ 3436 3437The remote endpoint to connect to. 3438 ]] 3439] 3440[heading Exceptions] 3441[table [[Type][Thrown On]] 3442 [[`system_error`][ 3443 3444Thrown on failure. 3445 ]] 3446] 3447[heading See Also] 3448[link beast.ref.boost__beast__basic_stream.connect `basic_stream::connect`] 3449[endsect] 3450[section:overload2 basic_stream::connect (2 of 10 overloads)] 3451Connect the stream to the specified endpoint. 3452[heading Synopsis] 3453``` 3454void 3455connect( 3456 endpoint_type const& ep, 3457 error_code& ec); 3458``` 3459 3460[heading Description] 3461This function is used to connect the underlying socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3462[heading Parameters] 3463[table [[Name][Description]] 3464 [[`ep`][ 3465 3466The remote endpoint to connect to. 3467 ]] 3468 [[`ec`][ 3469 3470Set to indicate what error occurred, if any. 3471 ]] 3472] 3473[heading See Also] 3474[link beast.ref.boost__beast__basic_stream.connect `basic_stream::connect`] 3475[endsect] 3476[section:overload3 basic_stream::connect (3 of 10 overloads)] 3477Establishes a connection by trying each endpoint in a sequence. 3478[heading Synopsis] 3479``` 3480template< 3481 class __EndpointSequence__> 3482Protocol::endpoint 3483connect( 3484 EndpointSequence const& endpoints); 3485``` 3486 3487[heading Description] 3488This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3489The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3490[heading Parameters] 3491[table [[Name][Description]] 3492 [[`endpoints`][ 3493 3494A sequence of endpoints. 3495 ]] 3496] 3497[heading Return Value] 3498The successfully connected endpoint. 3499[heading Exceptions] 3500[table [[Type][Thrown On]] 3501 [[`system_error`][ 3502 3503Thrown on failure. If the sequence is empty, the associated error code is `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3504 ]] 3505] 3506[endsect] 3507[section:overload4 basic_stream::connect (4 of 10 overloads)] 3508Establishes a connection by trying each endpoint in a sequence. 3509[heading Synopsis] 3510``` 3511template< 3512 class __EndpointSequence__> 3513Protocol::endpoint 3514connect( 3515 EndpointSequence const& endpoints, 3516 error_code& ec); 3517``` 3518 3519[heading Description] 3520This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3521The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3522[heading Parameters] 3523[table [[Name][Description]] 3524 [[`endpoints`][ 3525 3526A sequence of endpoints. 3527 ]] 3528 [[`ec`][ 3529 3530Set to indicate what error occurred, if any. If the sequence is empty, set to `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3531 ]] 3532] 3533[heading Return Value] 3534On success, the successfully connected endpoint. Otherwise, a default-constructed endpoint. 3535[endsect] 3536[section:overload5 basic_stream::connect (5 of 10 overloads)] 3537Establishes a connection by trying each endpoint in a sequence. 3538[heading Synopsis] 3539``` 3540template< 3541 class Iterator> 3542Iterator 3543connect( 3544 Iterator begin, 3545 Iterator end); 3546``` 3547 3548[heading Description] 3549This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3550The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3551[heading Parameters] 3552[table [[Name][Description]] 3553 [[`begin`][ 3554 3555An iterator pointing to the start of a sequence of endpoints. 3556 ]] 3557 [[`end`][ 3558 3559An iterator pointing to the end of a sequence of endpoints. 3560 ]] 3561] 3562[heading Return Value] 3563An iterator denoting the successfully connected endpoint. 3564[heading Exceptions] 3565[table [[Type][Thrown On]] 3566 [[`system_error`][ 3567 3568Thrown on failure. If the sequence is empty, the associated error code is `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3569 ]] 3570] 3571[endsect] 3572[section:overload6 basic_stream::connect (6 of 10 overloads)] 3573Establishes a connection by trying each endpoint in a sequence. 3574[heading Synopsis] 3575``` 3576template< 3577 class Iterator> 3578Iterator 3579connect( 3580 Iterator begin, 3581 Iterator end, 3582 error_code& ec); 3583``` 3584 3585[heading Description] 3586This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3587The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3588[heading Parameters] 3589[table [[Name][Description]] 3590 [[`begin`][ 3591 3592An iterator pointing to the start of a sequence of endpoints. 3593 ]] 3594 [[`end`][ 3595 3596An iterator pointing to the end of a sequence of endpoints. 3597 ]] 3598 [[`ec`][ 3599 3600Set to indicate what error occurred, if any. If the sequence is empty, set to boost::asio::error::not\_found. Otherwise, contains the error from the last connection attempt. 3601 ]] 3602] 3603[heading Return Value] 3604On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator. 3605[endsect] 3606[section:overload7 basic_stream::connect (7 of 10 overloads)] 3607Establishes a connection by trying each endpoint in a sequence. 3608[heading Synopsis] 3609``` 3610template< 3611 class __EndpointSequence__, 3612 class __ConnectCondition__> 3613Protocol::endpoint 3614connect( 3615 EndpointSequence const& endpoints, 3616 ConnectCondition connect_condition); 3617``` 3618 3619[heading Description] 3620This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3621The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3622[heading Parameters] 3623[table [[Name][Description]] 3624 [[`endpoints`][ 3625 3626A sequence of endpoints. 3627 ]] 3628 [[`connect_condition`][ 3629 3630A function object that is called prior to each connection attempt. The signature of the function object must be: 3631``` 3632 bool connect_condition( 3633 error_code const& ec, 3634 typename Protocol::endpoint const& next); 3635``` 3636The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped. 3637 ]] 3638] 3639[heading Return Value] 3640The successfully connected endpoint. 3641[heading Exceptions] 3642[table [[Type][Thrown On]] 3643 [[`boost::system::system_error`][ 3644 3645Thrown on failure. If the sequence is empty, the associated error code is `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3646 ]] 3647] 3648[endsect] 3649[section:overload8 basic_stream::connect (8 of 10 overloads)] 3650Establishes a connection by trying each endpoint in a sequence. 3651[heading Synopsis] 3652``` 3653template< 3654 class __EndpointSequence__, 3655 class __ConnectCondition__> 3656Protocol::endpoint 3657connect( 3658 EndpointSequence const& endpoints, 3659 ConnectCondition connect_condition, 3660 error_code& ec); 3661``` 3662 3663[heading Description] 3664This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3665The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3666[heading Parameters] 3667[table [[Name][Description]] 3668 [[`endpoints`][ 3669 3670A sequence of endpoints. 3671 ]] 3672 [[`connect_condition`][ 3673 3674A function object that is called prior to each connection attempt. The signature of the function object must be: 3675``` 3676 bool connect_condition( 3677 error_code const& ec, 3678 typename Protocol::endpoint const& next); 3679``` 3680The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped. 3681 ]] 3682 [[`ec`][ 3683 3684Set to indicate what error occurred, if any. If the sequence is empty, set to `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3685 ]] 3686] 3687[heading Return Value] 3688On success, the successfully connected endpoint. Otherwise, a default-constructed endpoint. 3689[endsect] 3690[section:overload9 basic_stream::connect (9 of 10 overloads)] 3691Establishes a connection by trying each endpoint in a sequence. 3692[heading Synopsis] 3693``` 3694template< 3695 class Iterator, 3696 class __ConnectCondition__> 3697Iterator 3698connect( 3699 Iterator begin, 3700 Iterator end, 3701 ConnectCondition connect_condition); 3702``` 3703 3704[heading Description] 3705This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3706The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3707[heading Parameters] 3708[table [[Name][Description]] 3709 [[`begin`][ 3710 3711An iterator pointing to the start of a sequence of endpoints. 3712 ]] 3713 [[`end`][ 3714 3715An iterator pointing to the end of a sequence of endpoints. 3716 ]] 3717 [[`connect_condition`][ 3718 3719A function object that is called prior to each connection attempt. The signature of the function object must be: 3720``` 3721 bool connect_condition( 3722 error_code const& ec, 3723 typename Protocol::endpoint const& next); 3724``` 3725The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped. 3726 ]] 3727] 3728[heading Return Value] 3729An iterator denoting the successfully connected endpoint. 3730[heading Exceptions] 3731[table [[Type][Thrown On]] 3732 [[`boost::system::system_error`][ 3733 3734Thrown on failure. If the sequence is empty, the associated `error_code` is `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3735 ]] 3736] 3737[endsect] 3738[section:overload10 basic_stream::connect (10 of 10 overloads)] 3739Establishes a connection by trying each endpoint in a sequence. 3740[heading Synopsis] 3741``` 3742template< 3743 class Iterator, 3744 class __ConnectCondition__> 3745Iterator 3746connect( 3747 Iterator begin, 3748 Iterator end, 3749 ConnectCondition connect_condition, 3750 error_code& ec); 3751``` 3752 3753[heading Description] 3754This function attempts to connect the stream to one of a sequence of endpoints by trying each endpoint until a connection is successfully established. The underlying socket is automatically opened if needed. An automatically opened socket is not returned to the closed state upon failure. 3755The algorithm, known as a ['composed operation], is implemented in terms of calls to the underlying socket's `connect` function. 3756[heading Parameters] 3757[table [[Name][Description]] 3758 [[`begin`][ 3759 3760An iterator pointing to the start of a sequence of endpoints. 3761 ]] 3762 [[`end`][ 3763 3764An iterator pointing to the end of a sequence of endpoints. 3765 ]] 3766 [[`connect_condition`][ 3767 3768A function object that is called prior to each connection attempt. The signature of the function object must be: 3769``` 3770 bool connect_condition( 3771 error_code const& ec, 3772 typename Protocol::endpoint const& next); 3773``` 3774The `ec` parameter contains the result from the most recent connect operation. Before the first connection attempt, `ec` is always set to indicate success. The `next` parameter is the next endpoint to be tried. The function object should return true if the next endpoint should be tried, and false if it should be skipped. 3775 ]] 3776 [[`ec`][ 3777 3778Set to indicate what error occurred, if any. If the sequence is empty, set to `net::error::not_found`. Otherwise, contains the error from the last connection attempt. 3779 ]] 3780] 3781[heading Return Value] 3782On success, an iterator denoting the successfully connected endpoint. Otherwise, the end iterator. 3783[endsect] 3784[endsect] 3785 3786[section:endpoint_type basic_stream::endpoint_type] 3787[indexterm2 endpoint_type..basic_stream] 3788The endpoint type. 3789[heading Synopsis] 3790 3791``` 3792using endpoint_type = typename Protocol::endpoint; 3793``` 3794 3795[heading Description] 3796[endsect] 3797[section:executor_type basic_stream::executor_type] 3798[indexterm2 executor_type..basic_stream] 3799The type of the executor associated with the stream. 3800[heading Synopsis] 3801 3802``` 3803using executor_type = beast::executor_type< socket_type >; 3804``` 3805 3806[heading Description] 3807This will be the type of executor used to invoke completion handlers which do not have an explicit associated executor. [endsect] 3808[section:expires_after basic_stream::expires_after] 3809[indexterm2 expires_after..basic_stream] 3810Set the timeout for the next logical operation. 3811[heading Synopsis] 3812``` 3813void 3814expires_after( 3815 std::chrono::nanoseconds expiry_time); 3816``` 3817 3818[heading Description] 3819This sets either the read timer, the write timer, or both timers to expire after the specified amount of time has elapsed. If a timer expires when the corresponding asynchronous operation is outstanding, the stream will be closed and any outstanding operations will complete with the error [link beast.ref.boost__beast__error `timeout`]. Otherwise, if the timer expires while no operations are outstanding, and the expiraton is not set again, the next operation will time out immediately. 3820The timer applies collectively to any asynchronous reads or writes initiated after the expiration is set, until the expiration is set again. A call to [link beast.ref.boost__beast__basic_stream.async_connect `basic_stream::async_connect`] counts as both a read and a write. 3821[heading Parameters] 3822[table [[Name][Description]] 3823 [[`expiry_time`][ 3824 3825The amount of time after which a logical operation should be considered timed out. 3826 ]] 3827] 3828[endsect] 3829[section:expires_at basic_stream::expires_at] 3830[indexterm2 expires_at..basic_stream] 3831Set the timeout for the next logical operation. 3832[heading Synopsis] 3833``` 3834void 3835expires_at( 3836 net::steady_timer::time_point expiry_time); 3837``` 3838 3839[heading Description] 3840This sets either the read timer, the write timer, or both timers to expire at the specified time point. If a timer expires when the corresponding asynchronous operation is outstanding, the stream will be closed and any outstanding operations will complete with the error [link beast.ref.boost__beast__error `timeout`]. Otherwise, if the timer expires while no operations are outstanding, and the expiraton is not set again, the next operation will time out immediately. 3841The timer applies collectively to any asynchronous reads or writes initiated after the expiration is set, until the expiration is set again. A call to [link beast.ref.boost__beast__basic_stream.async_connect `basic_stream::async_connect`] counts as both a read and a write. 3842[heading Parameters] 3843[table [[Name][Description]] 3844 [[`expiry_time`][ 3845 3846The time point after which a logical operation should be considered timed out. 3847 ]] 3848] 3849[endsect] 3850[section:expires_never basic_stream::expires_never] 3851[indexterm2 expires_never..basic_stream] 3852Disable the timeout for the next logical operation. 3853[heading Synopsis] 3854``` 3855void 3856expires_never(); 3857``` 3858 3859[heading Description] 3860[endsect] 3861[section:get_executor basic_stream::get_executor] 3862[indexterm2 get_executor..basic_stream] 3863Get the executor associated with the object. 3864[heading Synopsis] 3865``` 3866executor_type 3867get_executor(); 3868``` 3869 3870[heading Description] 3871This function may be used to obtain the executor object that the stream uses to dispatch completion handlers without an assocaited executor. 3872[heading Return Value] 3873A copy of the executor that stream will use to dispatch handlers. 3874[endsect] 3875[section:operator_eq_ basic_stream::operator=] 3876[indexterm2 operator=..basic_stream] 3877Move assignment (deleted). 3878[heading Synopsis] 3879``` 3880basic_stream& 3881operator=( 3882 basic_stream&&); 3883``` 3884 3885[heading Description] 3886[endsect] 3887[section:protocol_type basic_stream::protocol_type] 3888[indexterm2 protocol_type..basic_stream] 3889The protocol type. 3890[heading Synopsis] 3891 3892``` 3893using protocol_type = Protocol; 3894``` 3895 3896[heading Description] 3897[endsect] 3898[section:rate_policy basic_stream::rate_policy] 3899[indexterm2 rate_policy..basic_stream] 3900Returns the rate policy associated with the object. ``` 3901RatePolicy& 3902``[link beast.ref.boost__beast__basic_stream.rate_policy.overload1 rate_policy]``(); 3903 ``[''''»''' [link beast.ref.boost__beast__basic_stream.rate_policy.overload1 more...]]`` 3904 3905RatePolicy const & 3906``[link beast.ref.boost__beast__basic_stream.rate_policy.overload2 rate_policy]``() const; 3907 ``[''''»''' [link beast.ref.boost__beast__basic_stream.rate_policy.overload2 more...]]`` 3908``` 3909[section:overload1 basic_stream::rate_policy (1 of 2 overloads)] 3910Returns the rate policy associated with the object. 3911[heading Synopsis] 3912``` 3913RatePolicy& 3914rate_policy(); 3915``` 3916 3917[heading Description] 3918[endsect] 3919[section:overload2 basic_stream::rate_policy (2 of 2 overloads)] 3920Returns the rate policy associated with the object. 3921[heading Synopsis] 3922``` 3923RatePolicy const & 3924rate_policy() const; 3925``` 3926 3927[heading Description] 3928[endsect] 3929[endsect] 3930 3931[section:read_some basic_stream::read_some] 3932[indexterm2 read_some..basic_stream] 3933Read some data. ``` 3934template< 3935 class __MutableBufferSequence__> 3936std::size_t 3937``[link beast.ref.boost__beast__basic_stream.read_some.overload1 read_some]``( 3938 MutableBufferSequence const& buffers); 3939 ``[''''»''' [link beast.ref.boost__beast__basic_stream.read_some.overload1 more...]]`` 3940 3941template< 3942 class __MutableBufferSequence__> 3943std::size_t 3944``[link beast.ref.boost__beast__basic_stream.read_some.overload2 read_some]``( 3945 MutableBufferSequence const& buffers, 3946 error_code& ec); 3947 ``[''''»''' [link beast.ref.boost__beast__basic_stream.read_some.overload2 more...]]`` 3948``` 3949[section:overload1 basic_stream::read_some (1 of 2 overloads)] 3950Read some data. 3951[heading Synopsis] 3952``` 3953template< 3954 class __MutableBufferSequence__> 3955std::size_t 3956read_some( 3957 MutableBufferSequence const& buffers); 3958``` 3959 3960[heading Description] 3961This function is used to read some data from the stream. 3962The call blocks until one of the following is true: 3963 3964* One or more bytes are read from the stream. 3965 3966 3967* An error occurs. 3968 3969[heading Parameters] 3970[table [[Name][Description]] 3971 [[`buffers`][ 3972 3973The buffers into which the data will be read. If the size of the buffers is zero bytes, the call always returns immediately with no error. 3974 ]] 3975] 3976[heading Return Value] 3977The number of bytes read. 3978[heading Exceptions] 3979[table [[Type][Thrown On]] 3980 [[`system_error`][ 3981 3982Thrown on failure. 3983 ]] 3984] 3985[heading Remarks] 3986The `read_some` operation may not receive all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 3987[endsect] 3988[section:overload2 basic_stream::read_some (2 of 2 overloads)] 3989Read some data. 3990[heading Synopsis] 3991``` 3992template< 3993 class __MutableBufferSequence__> 3994std::size_t 3995read_some( 3996 MutableBufferSequence const& buffers, 3997 error_code& ec); 3998``` 3999 4000[heading Description] 4001This function is used to read some data from the underlying socket. 4002The call blocks until one of the following is true: 4003 4004* One or more bytes are read from the stream. 4005 4006 4007* An error occurs. 4008 4009[heading Parameters] 4010[table [[Name][Description]] 4011 [[`buffers`][ 4012 4013The buffers into which the data will be read. If the size of the buffers is zero bytes, the call always returns immediately with no error. 4014 ]] 4015 [[`ec`][ 4016 4017Set to indicate what error occurred, if any. 4018 ]] 4019] 4020[heading Return Value] 4021The number of bytes read. 4022[heading Remarks] 4023The `read_some` operation may not receive all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 4024[endsect] 4025[endsect] 4026 4027[section:release_socket basic_stream::release_socket] 4028[indexterm2 release_socket..basic_stream] 4029Release ownership of the underlying socket. 4030[heading Synopsis] 4031``` 4032socket_type 4033release_socket(); 4034``` 4035 4036[heading Description] 4037This function causes all outstanding asynchronous connect, read, and write operations to be canceled as if by a call to [link beast.ref.boost__beast__basic_stream.cancel `basic_stream::cancel`]. Ownership of the underlying socket is then transferred to the caller. [endsect] 4038[section:socket basic_stream::socket] 4039[indexterm2 socket..basic_stream] 4040Return a reference to the underlying socket. ``` 4041socket_type& 4042``[link beast.ref.boost__beast__basic_stream.socket.overload1 socket]``(); 4043 ``[''''»''' [link beast.ref.boost__beast__basic_stream.socket.overload1 more...]]`` 4044 4045socket_type const & 4046``[link beast.ref.boost__beast__basic_stream.socket.overload2 socket]``() const; 4047 ``[''''»''' [link beast.ref.boost__beast__basic_stream.socket.overload2 more...]]`` 4048``` 4049[section:overload1 basic_stream::socket (1 of 2 overloads)] 4050Return a reference to the underlying socket. 4051[heading Synopsis] 4052``` 4053socket_type& 4054socket(); 4055``` 4056 4057[heading Description] 4058[endsect] 4059[section:overload2 basic_stream::socket (2 of 2 overloads)] 4060Return a reference to the underlying socket. 4061[heading Synopsis] 4062``` 4063socket_type const & 4064socket() const; 4065``` 4066 4067[heading Description] 4068[endsect] 4069[endsect] 4070 4071[section:socket_type basic_stream::socket_type] 4072[indexterm2 socket_type..basic_stream] 4073The type of the underlying socket. 4074[heading Synopsis] 4075 4076``` 4077using socket_type = net::basic_stream_socket< Protocol, Executor >; 4078``` 4079 4080[heading Description] 4081[endsect] 4082[section:write_some basic_stream::write_some] 4083[indexterm2 write_some..basic_stream] 4084Write some data. ``` 4085template< 4086 class __ConstBufferSequence__> 4087std::size_t 4088``[link beast.ref.boost__beast__basic_stream.write_some.overload1 write_some]``( 4089 ConstBufferSequence const& buffers); 4090 ``[''''»''' [link beast.ref.boost__beast__basic_stream.write_some.overload1 more...]]`` 4091 4092template< 4093 class __ConstBufferSequence__> 4094std::size_t 4095``[link beast.ref.boost__beast__basic_stream.write_some.overload2 write_some]``( 4096 ConstBufferSequence const& buffers, 4097 error_code& ec); 4098 ``[''''»''' [link beast.ref.boost__beast__basic_stream.write_some.overload2 more...]]`` 4099``` 4100[section:overload1 basic_stream::write_some (1 of 2 overloads)] 4101Write some data. 4102[heading Synopsis] 4103``` 4104template< 4105 class __ConstBufferSequence__> 4106std::size_t 4107write_some( 4108 ConstBufferSequence const& buffers); 4109``` 4110 4111[heading Description] 4112This function is used to write some data to the stream. 4113The call blocks until one of the following is true: 4114 4115* One or more bytes are written to the stream. 4116 4117 4118* An error occurs. 4119 4120[heading Parameters] 4121[table [[Name][Description]] 4122 [[`buffers`][ 4123 4124The buffers from which the data will be written. If the size of the buffers is zero bytes, the call always returns immediately with no error. 4125 ]] 4126] 4127[heading Return Value] 4128The number of bytes written. 4129[heading Exceptions] 4130[table [[Type][Thrown On]] 4131 [[`system_error`][ 4132 4133Thrown on failure. 4134 ]] 4135] 4136[heading Remarks] 4137The `write_some` operation may not transmit all of the requested number of bytes. Consider using the function `net::write` if you need to ensure that the requested amount of data is written before the blocking operation completes. 4138[endsect] 4139[section:overload2 basic_stream::write_some (2 of 2 overloads)] 4140Write some data. 4141[heading Synopsis] 4142``` 4143template< 4144 class __ConstBufferSequence__> 4145std::size_t 4146write_some( 4147 ConstBufferSequence const& buffers, 4148 error_code& ec); 4149``` 4150 4151[heading Description] 4152This function is used to write some data to the stream. 4153The call blocks until one of the following is true: 4154 4155* One or more bytes are written to the stream. 4156 4157 4158* An error occurs. 4159 4160[heading Parameters] 4161[table [[Name][Description]] 4162 [[`buffers`][ 4163 4164The buffers from which the data will be written. If the size of the buffers is zero bytes, the call always returns immediately with no error. 4165 ]] 4166 [[`ec`][ 4167 4168Set to indicate what error occurred, if any. 4169 ]] 4170] 4171[heading Return Value] 4172The number of bytes written. 4173[heading Exceptions] 4174[table [[Type][Thrown On]] 4175 [[`system_error`][ 4176 4177Thrown on failure. 4178 ]] 4179] 4180[heading Remarks] 4181The `write_some` operation may not transmit all of the requested number of bytes. Consider using the function `net::write` if you need to ensure that the requested amount of data is written before the blocking operation completes. 4182[endsect] 4183[endsect] 4184 4185[section:basic_stream_dtor_ basic_stream::~basic_stream] 4186[indexterm2 ~basic_stream..basic_stream] 4187Destructor. 4188[heading Synopsis] 4189``` 4190~basic_stream(); 4191``` 4192 4193[heading Description] 4194This function destroys the stream, cancelling any outstanding asynchronous operations associated with the socket as if by calling cancel. [endsect] 4195 4196 4197 4198Convenience header [include_file boost/beast/core.hpp] 4199 4200[endsect] 4201 4202 4203 4204[section:boost__beast__basic_stream__impl_type basic_stream::impl_type] 4205 4206[heading Synopsis] 4207 4208Defined in header [include_file boost/beast/core/basic_stream.hpp] 4209 4210 4211 4212``` 4213struct impl_type : 4214 public boost::enable_shared_from_this< impl_type >, 4215 public boost::empty_value< RatePolicy > 4216``` 4217[heading Member Functions] 4218[table [[Name][Description]] 4219 [ 4220 [[link beast.ref.boost__beast__basic_stream__impl_type.close [*close]]] 4221 [ 4222 4223 ] 4224 ] 4225 [ 4226 [[link beast.ref.boost__beast__basic_stream__impl_type.ex [*ex]]] 4227 [ 4228 4229 ] 4230 ] 4231 [ 4232 [[link beast.ref.boost__beast__basic_stream__impl_type.impl_type [*impl_type]]] 4233 [ 4234 4235 ] 4236 ] 4237 [ 4238 [[link beast.ref.boost__beast__basic_stream__impl_type.on_timer [*on_timer]]] 4239 [ 4240 4241 ] 4242 ] 4243 [ 4244 [[link beast.ref.boost__beast__basic_stream__impl_type.operator_eq_ [*operator=]]] 4245 [ 4246 4247 ] 4248 ] 4249 [ 4250 [[link beast.ref.boost__beast__basic_stream__impl_type.policy [*policy]]] 4251 [ 4252 4253 ] 4254 ] 4255 [ 4256 [[link beast.ref.boost__beast__basic_stream__impl_type.reset [*reset]]] 4257 [ 4258 4259 ] 4260 ] 4261] 4262[heading Data Members] 4263[table [[Name][Description]] 4264 [ 4265 [[link beast.ref.boost__beast__basic_stream__impl_type.read [*read]]] 4266 [ 4267 4268 ] 4269 ] 4270 [ 4271 [[link beast.ref.boost__beast__basic_stream__impl_type.socket [*socket]]] 4272 [ 4273 4274 ] 4275 ] 4276 [ 4277 [[link beast.ref.boost__beast__basic_stream__impl_type.timer [*timer]]] 4278 [ 4279 4280 ] 4281 ] 4282 [ 4283 [[link beast.ref.boost__beast__basic_stream__impl_type.waiting [*waiting]]] 4284 [ 4285 4286 ] 4287 ] 4288 [ 4289 [[link beast.ref.boost__beast__basic_stream__impl_type.write [*write]]] 4290 [ 4291 4292 ] 4293 ] 4294] 4295 4296[heading Description] 4297[section:close basic_stream::impl_type::close] 4298[indexterm2 close..basic_stream::impl_type] 4299 4300[heading Synopsis] 4301``` 4302void 4303close(); 4304``` 4305 4306[heading Description] 4307[endsect] 4308[section:ex basic_stream::impl_type::ex] 4309[indexterm2 ex..basic_stream::impl_type] 4310 4311[heading Synopsis] 4312``` 4313beast::executor_type< socket_type > 4314ex(); 4315``` 4316 4317[heading Description] 4318[endsect] 4319[section:impl_type basic_stream::impl_type::impl_type] 4320[indexterm2 impl_type..basic_stream::impl_type] 4321``` 4322``[link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload1 impl_type]``( 4323 impl_type&&); 4324 ``[''''»''' [link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload1 more...]]`` 4325 4326template< 4327 class... Args> 4328explicit 4329``[link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload2 impl_type]``( 4330 std::false_type, 4331 Args&& ...); 4332 ``[''''»''' [link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload2 more...]]`` 4333 4334template< 4335 class RatePolicy_, 4336 class... Args> 4337explicit 4338``[link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload3 impl_type]``( 4339 std::true_type, 4340 RatePolicy_&& policy, 4341 Args&& ...); 4342 ``[''''»''' [link beast.ref.boost__beast__basic_stream__impl_type.impl_type.overload3 more...]]`` 4343``` 4344[section:overload1 basic_stream::impl_type::impl_type (1 of 3 overloads)] 4345 4346[heading Synopsis] 4347``` 4348impl_type( 4349 impl_type&&); 4350``` 4351 4352[heading Description] 4353[endsect] 4354[section:overload2 basic_stream::impl_type::impl_type (2 of 3 overloads)] 4355 4356[heading Synopsis] 4357``` 4358template< 4359 class... Args> 4360impl_type( 4361 std::false_type, 4362 Args&& ...); 4363``` 4364 4365[heading Description] 4366[endsect] 4367[section:overload3 basic_stream::impl_type::impl_type (3 of 3 overloads)] 4368 4369[heading Synopsis] 4370``` 4371template< 4372 class RatePolicy_, 4373 class... Args> 4374impl_type( 4375 std::true_type, 4376 RatePolicy_&& policy, 4377 Args&& ...); 4378``` 4379 4380[heading Description] 4381[endsect] 4382[endsect] 4383 4384[section:on_timer basic_stream::impl_type::on_timer] 4385[indexterm2 on_timer..basic_stream::impl_type] 4386 4387[heading Synopsis] 4388``` 4389template< 4390 class __Executor2__> 4391void 4392on_timer( 4393 Executor2 const& ex2); 4394``` 4395 4396[heading Description] 4397[endsect] 4398[section:operator_eq_ basic_stream::impl_type::operator=] 4399[indexterm2 operator=..basic_stream::impl_type] 4400 4401[heading Synopsis] 4402``` 4403impl_type& 4404operator=( 4405 impl_type&&); 4406``` 4407 4408[heading Description] 4409[endsect] 4410[section:policy basic_stream::impl_type::policy] 4411[indexterm2 policy..basic_stream::impl_type] 4412``` 4413RatePolicy& 4414``[link beast.ref.boost__beast__basic_stream__impl_type.policy.overload1 policy]``(); 4415 ``[''''»''' [link beast.ref.boost__beast__basic_stream__impl_type.policy.overload1 more...]]`` 4416 4417RatePolicy const & 4418``[link beast.ref.boost__beast__basic_stream__impl_type.policy.overload2 policy]``() const; 4419 ``[''''»''' [link beast.ref.boost__beast__basic_stream__impl_type.policy.overload2 more...]]`` 4420``` 4421[section:overload1 basic_stream::impl_type::policy (1 of 2 overloads)] 4422 4423[heading Synopsis] 4424``` 4425RatePolicy& 4426policy(); 4427``` 4428 4429[heading Description] 4430[endsect] 4431[section:overload2 basic_stream::impl_type::policy (2 of 2 overloads)] 4432 4433[heading Synopsis] 4434``` 4435RatePolicy const & 4436policy() const; 4437``` 4438 4439[heading Description] 4440[endsect] 4441[endsect] 4442 4443[section:read basic_stream::impl_type::read] 4444[indexterm2 read..basic_stream::impl_type] 4445 4446[heading Synopsis] 4447``` 4448op_state read; 4449``` 4450 4451[heading Description] 4452[endsect] 4453[section:reset basic_stream::impl_type::reset] 4454[indexterm2 reset..basic_stream::impl_type] 4455 4456[heading Synopsis] 4457``` 4458void 4459reset(); 4460``` 4461 4462[heading Description] 4463[endsect] 4464[section:socket basic_stream::impl_type::socket] 4465[indexterm2 socket..basic_stream::impl_type] 4466 4467[heading Synopsis] 4468``` 4469net::basic_stream_socket< Protocol, Executor > socket; 4470``` 4471 4472[heading Description] 4473[endsect] 4474[section:timer basic_stream::impl_type::timer] 4475[indexterm2 timer..basic_stream::impl_type] 4476 4477[heading Synopsis] 4478``` 4479net::steady_timer timer; 4480``` 4481 4482[heading Description] 4483[endsect] 4484[section:waiting basic_stream::impl_type::waiting] 4485[indexterm2 waiting..basic_stream::impl_type] 4486 4487[heading Synopsis] 4488``` 4489int waiting = 0; 4490``` 4491 4492[heading Description] 4493[endsect] 4494[section:write basic_stream::impl_type::write] 4495[indexterm2 write..basic_stream::impl_type] 4496 4497[heading Synopsis] 4498``` 4499op_state write; 4500``` 4501 4502[heading Description] 4503[endsect] 4504 4505 4506 4507Convenience header [include_file boost/beast/core.hpp] 4508 4509[endsect] 4510 4511 4512 4513[section:boost__beast__basic_stream__rebind_executor basic_stream::rebind_executor] 4514Rebinds the stream type to another executor. 4515[heading Synopsis] 4516 4517Defined in header [include_file boost/beast/core/basic_stream.hpp] 4518 4519 4520 4521``` 4522template< 4523 class __Executor1__> 4524struct rebind_executor 4525``` 4526[heading Types] 4527[table [[Name][Description]] 4528 [ 4529 [[link beast.ref.boost__beast__basic_stream__rebind_executor.other [*other]]] 4530 [ 4531 The stream type when rebound to the specified executor. 4532 ] 4533 ] 4534] 4535 4536[heading Description] 4537[section:other basic_stream::rebind_executor::other] 4538[indexterm2 other..basic_stream::rebind_executor] 4539The stream type when rebound to the specified executor. 4540[heading Synopsis] 4541 4542``` 4543using other = basic_stream< Protocol, Executor1, RatePolicy >; 4544``` 4545[heading Types] 4546[table [[Name][Description]] 4547 [ 4548 [[link beast.ref.boost__beast__basic_stream__rebind_executor [*rebind_executor]]] 4549 [ 4550 Rebinds the stream type to another executor. 4551 ] 4552 ] 4553 [ 4554 [[link beast.ref.boost__beast__basic_stream.endpoint_type [*endpoint_type]]] 4555 [ 4556 The endpoint type. 4557 ] 4558 ] 4559 [ 4560 [[link beast.ref.boost__beast__basic_stream.executor_type [*executor_type]]] 4561 [ 4562 The type of the executor associated with the stream. 4563 ] 4564 ] 4565 [ 4566 [[link beast.ref.boost__beast__basic_stream.protocol_type [*protocol_type]]] 4567 [ 4568 The protocol type. 4569 ] 4570 ] 4571 [ 4572 [[link beast.ref.boost__beast__basic_stream.socket_type [*socket_type]]] 4573 [ 4574 The type of the underlying socket. 4575 ] 4576 ] 4577] 4578[heading Member Functions] 4579[table [[Name][Description]] 4580 [ 4581 [[link beast.ref.boost__beast__basic_stream.async_connect [*async_connect]]] 4582 [ 4583 Connect the stream to the specified endpoint asynchronously. 4584 4585 Establishes a connection by trying each endpoint in a sequence asynchronously. 4586 ] 4587 ] 4588 [ 4589 [[link beast.ref.boost__beast__basic_stream.async_read_some [*async_read_some]]] 4590 [ 4591 Read some data asynchronously. 4592 ] 4593 ] 4594 [ 4595 [[link beast.ref.boost__beast__basic_stream.async_write_some [*async_write_some]]] 4596 [ 4597 Write some data asynchronously. 4598 ] 4599 ] 4600 [ 4601 [[link beast.ref.boost__beast__basic_stream.basic_stream [*basic_stream]]] 4602 [ 4603 Constructor. 4604 4605 Move constructor. 4606 ] 4607 ] 4608 [ 4609 [[link beast.ref.boost__beast__basic_stream.cancel [*cancel]]] 4610 [ 4611 Cancel all asynchronous operations associated with the socket. 4612 ] 4613 ] 4614 [ 4615 [[link beast.ref.boost__beast__basic_stream.close [*close]]] 4616 [ 4617 Close the timed stream. 4618 ] 4619 ] 4620 [ 4621 [[link beast.ref.boost__beast__basic_stream.connect [*connect]]] 4622 [ 4623 Connect the stream to the specified endpoint. 4624 4625 Establishes a connection by trying each endpoint in a sequence. 4626 ] 4627 ] 4628 [ 4629 [[link beast.ref.boost__beast__basic_stream.expires_after [*expires_after]]] 4630 [ 4631 Set the timeout for the next logical operation. 4632 ] 4633 ] 4634 [ 4635 [[link beast.ref.boost__beast__basic_stream.expires_at [*expires_at]]] 4636 [ 4637 Set the timeout for the next logical operation. 4638 ] 4639 ] 4640 [ 4641 [[link beast.ref.boost__beast__basic_stream.expires_never [*expires_never]]] 4642 [ 4643 Disable the timeout for the next logical operation. 4644 ] 4645 ] 4646 [ 4647 [[link beast.ref.boost__beast__basic_stream.get_executor [*get_executor]]] 4648 [ 4649 Get the executor associated with the object. 4650 ] 4651 ] 4652 [ 4653 [[link beast.ref.boost__beast__basic_stream.operator_eq_ [*operator=]]] 4654 [ 4655 Move assignment (deleted). 4656 ] 4657 ] 4658 [ 4659 [[link beast.ref.boost__beast__basic_stream.rate_policy [*rate_policy]]] 4660 [ 4661 Returns the rate policy associated with the object. 4662 ] 4663 ] 4664 [ 4665 [[link beast.ref.boost__beast__basic_stream.read_some [*read_some]]] 4666 [ 4667 Read some data. 4668 ] 4669 ] 4670 [ 4671 [[link beast.ref.boost__beast__basic_stream.release_socket [*release_socket]]] 4672 [ 4673 Release ownership of the underlying socket. 4674 ] 4675 ] 4676 [ 4677 [[link beast.ref.boost__beast__basic_stream.socket [*socket]]] 4678 [ 4679 Return a reference to the underlying socket. 4680 ] 4681 ] 4682 [ 4683 [[link beast.ref.boost__beast__basic_stream.write_some [*write_some]]] 4684 [ 4685 Write some data. 4686 ] 4687 ] 4688 [ 4689 [[link beast.ref.boost__beast__basic_stream.basic_stream_dtor_ [*~basic_stream]]] 4690 [ 4691 Destructor. 4692 ] 4693 ] 4694] 4695This stream wraps a `net::basic_stream_socket` to provide the following features: 4696 4697* An ['Executor] may be associated with the stream, which will be used to invoke any completion handlers which do not already have an associated executor. This achieves support for [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 4698 4699 4700* Timeouts may be specified for each logical asynchronous operation performing any reading, writing, or connecting. 4701 4702 4703* A ['RatePolicy] may be associated with the stream, to implement rate limiting through the policy's interface. 4704 4705Although the stream supports multiple concurrent outstanding asynchronous operations, the stream object is not thread-safe. The caller is responsible for ensuring that the stream is accessed from only one thread at a time. This includes the times when the stream, and its underlying socket, are accessed by the networking implementation. To meet this thread safety requirement, all asynchronous operations must be performed by the stream within the same implicit strand (only one thread `net::io_context::run`) or within the same explicit strand, such as an instance of `net::strand`. 4706Completion handlers with explicit associated executors (such as those arising from use of `net::bind_executor`) will be invoked by the stream using the associated executor. Otherwise, the completion handler will be invoked by the executor associated with the stream upon construction. The type of executor used with this stream must meet the following requirements: 4707 4708* Function objects submitted to the executor shall never run concurrently with each other. 4709 4710The executor type `net::strand` meets these requirements. Use of a strand as the executor in the stream class template offers an additional notational convenience: the strand does not need to be specified in each individual initiating function call. 4711Unlike other stream wrappers, the underlying socket is accessed through the [link beast.ref.boost__beast__basic_stream.socket `basic_stream::socket`] member function instead of `next_layer`. This causes the [link beast.ref.boost__beast__basic_stream `basic_stream`] to be returned in calls to [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]. 4712[heading Usage] 4713 4714To use this stream declare an instance of the class. Then, before each logical operation for which a timeout is desired, call [link beast.ref.boost__beast__basic_stream.expires_after `basic_stream::expires_after`] with a duration, or call [link beast.ref.boost__beast__basic_stream.expires_at `basic_stream::expires_at`] with a time point. Alternatively, call [link beast.ref.boost__beast__basic_stream.expires_never `basic_stream::expires_never`] to disable the timeout for subsequent logical operations. A logical operation is any series of one or more direct or indirect calls to the timeout stream's asynchronous read, asynchronous write, or asynchronous connect functions. 4715When a timeout is set and a mixed operation is performed (one that includes both reads and writes, for example) the timeout applies to all of the intermediate asynchronous operations used in the enclosing operation. This allows timeouts to be applied to stream algorithms which were not written specifically to allow for timeouts, when those algorithms are passed a timeout stream with a timeout set. 4716When a timeout occurs the socket will be closed, canceling any pending I/O operations. The completion handlers for these canceled operations will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 4717[heading Examples] 4718 4719This function reads an HTTP request with a timeout, then sends the HTTP response with a different timeout. 4720 4721``` 4722 void process_http_1 (tcp_stream& stream, net::yield_context yield) 4723 { 4724 flat_buffer buffer; 4725 http::request<http::empty_body> req; 4726 4727 // Read the request, with a 15 second timeout 4728 stream.expires_after(std::chrono::seconds(15)); 4729 http::async_read(stream, buffer, req, yield); 4730 4731 // Calculate the response 4732 http::response<http::string_body> res = make_response(req); 4733 4734 // Send the response, with a 30 second timeout. 4735 stream.expires_after (std::chrono::seconds(30)); 4736 http::async_write (stream, res, yield); 4737 } 4738``` 4739The example above could be expressed using a single timeout with a simple modification. The function that follows first reads an HTTP request then sends the HTTP response, with a single timeout that applies to the entire combined operation of reading and writing: 4740 4741``` 4742 void process_http_2 (tcp_stream& stream, net::yield_context yield) 4743 { 4744 flat_buffer buffer; 4745 http::request<http::empty_body> req; 4746 4747 // Require that the read and write combined take no longer than 30 seconds 4748 stream.expires_after(std::chrono::seconds(30)); 4749 4750 http::async_read(stream, buffer, req, yield); 4751 4752 http::response<http::string_body> res = make_response(req); 4753 http::async_write (stream, res, yield); 4754 } 4755``` 4756Some stream algorithms, such as `ssl::stream::async_handshake` perform both reads and writes. A timeout set before calling the initiating function of such composite stream algorithms will apply to the entire composite operation. For example, a timeout may be set on performing the SSL handshake thusly: 4757 4758``` 4759 void do_ssl_handshake (net::ssl::stream<tcp_stream>& stream, net::yield_context yield) 4760 { 4761 // Require that the SSL handshake take no longer than 10 seconds 4762 stream.expires_after(std::chrono::seconds(10)); 4763 4764 stream.async_handshake(net::ssl::stream_base::client, yield); 4765 } 4766``` 4767[heading Blocking I/O] 4768 4769Synchronous functions behave identically as that of the wrapped `net::basic_stream_socket`. Timeouts are not available when performing blocking calls. 4770[heading Template Parameters] 4771[table [[Type][Description]] 4772 [[`Protocol`][ 4773 4774A type meeting the requirements of ['Protocol] representing the protocol the protocol to use for the basic stream socket. A common choice is `net::ip::tcp`. 4775 ]] 4776 [[`Executor`][ 4777 4778A type meeting the requirements of ['Executor] to be used for submitting all completion handlers which do not already have an associated executor. If this type is omitted, the default of `net::executor` will be used. 4779 ]] 4780] 4781[heading Thread Safety] 4782['Distinct objects]: Safe. 4783 4784['Shared objects]: Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 4785[heading See Also] 4786 4787 4788* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 4789 4790 4791[heading Description] 4792[endsect] 4793 4794 4795 4796Convenience header [include_file boost/beast/core.hpp] 4797 4798[endsect] 4799 4800 4801 4802[section:boost__beast__basic_stream__timeout_handler basic_stream::timeout_handler] 4803 4804[heading Synopsis] 4805 4806Defined in header [include_file boost/beast/core/basic_stream.hpp] 4807 4808 4809 4810``` 4811template< 4812 class __Executor2__> 4813struct timeout_handler 4814``` 4815 4816[heading Description] 4817 4818 4819 4820Convenience header [include_file boost/beast/core.hpp] 4821 4822[endsect] 4823 4824 4825 4826[section:boost__beast__basic_string_view basic_string_view] 4827[indexterm1 basic_string_view] 4828The type of `basic_string_view` used by the library. 4829[heading Synopsis] 4830 4831Defined in header [include_file boost/beast/core/string_type.hpp] 4832 4833 4834 4835``` 4836template< 4837 class CharT, 4838 class Traits> 4839using basic_string_view = boost::basic_string_view< CharT, Traits >; 4840``` 4841 4842[heading Description] 4843 4844 4845 4846Convenience header [include_file boost/beast/core.hpp] 4847 4848[endsect] 4849[section:boost__beast__beast_close_socket beast_close_socket] 4850[indexterm1 beast_close_socket] 4851Default socket close function. 4852[heading Synopsis] 4853 4854Defined in header [include_file boost/beast/core/stream_traits.hpp] 4855 4856 4857 4858``` 4859template< 4860 class __Protocol__, 4861 class __Executor__> 4862void 4863beast_close_socket( 4864 net::basic_socket< Protocol, Executor >& sock); 4865 4866``` 4867 4868[heading Description] 4869This function is not meant to be called directly. Instead, it is called automatically when using [link beast.ref.boost__beast__close_socket `close_socket`]. To enable closure of user-defined types or classes derived from a particular user-defined type, this function should be overloaded in the corresponding namespace for the type in question. 4870[heading See Also] 4871[link beast.ref.boost__beast__close_socket `close_socket`] 4872 4873 4874 4875Convenience header [include_file boost/beast/core.hpp] 4876 4877[endsect] 4878[section:boost__beast__bind_front_handler bind_front_handler] 4879[indexterm1 bind_front_handler] 4880Bind parameters to a completion handler, creating a new handler. 4881[heading Synopsis] 4882 4883Defined in header [include_file boost/beast/core/bind_handler.hpp] 4884 4885 4886 4887``` 4888template< 4889 class __Handler__, 4890 class... Args> 4891``['implementation-defined]`` 4892bind_front_handler( 4893 Handler&& handler, 4894 Args&&... args); 4895 4896``` 4897 4898[heading Description] 4899This function creates a new handler which, when invoked, calls the original handler with the list of bound arguments. Any parameters passed in the invocation will be forwarded in the parameter list after the bound arguments. 4900The passed handler and arguments are forwarded into the returned handler, whose associated allocator and associated executor will will be the same as those of the original handler. 4901[heading Example] 4902 4903This function posts the invocation of the specified completion handler with bound arguments: 4904 4905``` 4906 template <class AsyncReadStream, class ReadHandler> 4907 void 4908 signal_eof (AsyncReadStream& stream, ReadHandler&& handler) 4909 { 4910 net::post( 4911 stream.get_executor(), 4912 bind_front_handler (std::forward<ReadHandler> (handler), 4913 net::error::eof, 0)); 4914 } 4915``` 4916[heading Parameters] 4917[table [[Name][Description]] 4918 [[`handler`][ 4919 4920The handler to wrap. The implementation takes ownership of the handler by performing a decay-copy. 4921 ]] 4922 [[`args`][ 4923 4924A list of arguments to bind to the handler. The arguments are forwarded into the returned object. 4925 ]] 4926] 4927 4928 4929 4930Convenience header [include_file boost/beast/core.hpp] 4931 4932[endsect] 4933[section:boost__beast__bind_handler bind_handler] 4934[indexterm1 bind_handler] 4935Bind parameters to a completion handler, creating a new handler. 4936[heading Synopsis] 4937 4938Defined in header [include_file boost/beast/core/bind_handler.hpp] 4939 4940 4941 4942``` 4943template< 4944 class __Handler__, 4945 class... Args> 4946``['implementation-defined]`` 4947bind_handler( 4948 Handler&& handler, 4949 Args&&... args); 4950 4951``` 4952 4953[heading Description] 4954This function creates a new handler which, when invoked, calls the original handler with the list of bound arguments. Any parameters passed in the invocation will be substituted for placeholders present in the list of bound arguments. Parameters which are not matched to placeholders are silently discarded. 4955The passed handler and arguments are forwarded into the returned handler, whose associated allocator and associated executor will will be the same as those of the original handler. 4956[heading Example] 4957 4958This function posts the invocation of the specified completion handler with bound arguments: 4959 4960``` 4961 template <class AsyncReadStream, class ReadHandler> 4962 void 4963 signal_aborted (AsyncReadStream& stream, ReadHandler&& handler) 4964 { 4965 net::post( 4966 stream.get_executor(), 4967 bind_handler (std::forward <ReadHandler> (handler), 4968 net::error::operation_aborted, 0)); 4969 } 4970``` 4971[heading Parameters] 4972[table [[Name][Description]] 4973 [[`handler`][ 4974 4975The handler to wrap. The implementation takes ownership of the handler by performing a decay-copy. 4976 ]] 4977 [[`args`][ 4978 4979A list of arguments to bind to the handler. The arguments are forwarded into the returned object. These arguments may include placeholders, which will operate in a fashion identical to a call to `std::bind`. 4980 ]] 4981] 4982 4983 4984 4985Convenience header [include_file boost/beast/core.hpp] 4986 4987[endsect] 4988[section:boost__beast__buffer_bytes buffer_bytes] 4989[indexterm1 buffer_bytes] 4990Return the total number of bytes in a buffer or buffer sequence. 4991[heading Synopsis] 4992 4993Defined in header [include_file boost/beast/core/buffer_traits.hpp] 4994 4995 4996 4997``` 4998template< 4999 class __BufferSequence__> 5000std::size_t 5001buffer_bytes( 5002 BufferSequence const& buffers); 5003 5004``` 5005 5006[heading Description] 5007This function returns the total number of bytes in a buffer, buffer sequence, or object convertible to a buffer. Specifically it may be passed: 5008 5009* A ['ConstBufferSequence] or ['MutableBufferSequence] 5010 5011 5012* A `net::const_buffer` or `net::mutable_buffer` 5013 5014 5015* An object convertible to `net::const_buffer` 5016 5017This function is designed as an easier-to-use replacement for `net::buffer_size`. It recognizes customization points found through argument-dependent lookup. The call `beast::buffer_bytes(b)` is equivalent to performing: 5018``` 5019 using namespace net; 5020 buffer_bytes(b); 5021``` 5022In addition this handles types which are convertible to `net::const_buffer`; these are not handled by `net::buffer_size`. 5023[heading Parameters] 5024[table [[Name][Description]] 5025 [[`buffers`][ 5026 5027The buffer or buffer sequence to calculate the size of. 5028 ]] 5029] 5030[heading Return Value] 5031The total number of bytes in the buffer or sequence. 5032 5033 5034 5035Convenience header [include_file boost/beast/core.hpp] 5036 5037[endsect] 5038[section:boost__beast__buffered_read_stream buffered_read_stream] 5039A ['Stream] with attached ['DynamicBuffer] to buffer reads. 5040[heading Synopsis] 5041 5042Defined in header [include_file boost/beast/core/buffered_read_stream.hpp] 5043 5044 5045 5046``` 5047template< 5048 class __Stream__, 5049 class __DynamicBuffer__> 5050class buffered_read_stream 5051``` 5052[heading Types] 5053[table [[Name][Description]] 5054 [ 5055 [[link beast.ref.boost__beast__buffered_read_stream.buffer_type [*buffer_type]]] 5056 [ 5057 The type of the internal buffer. 5058 ] 5059 ] 5060 [ 5061 [[link beast.ref.boost__beast__buffered_read_stream.executor_type [*executor_type]]] 5062 [ 5063 5064 ] 5065 ] 5066 [ 5067 [[link beast.ref.boost__beast__buffered_read_stream.next_layer_type [*next_layer_type]]] 5068 [ 5069 The type of the next layer. 5070 ] 5071 ] 5072] 5073[heading Member Functions] 5074[table [[Name][Description]] 5075 [ 5076 [[link beast.ref.boost__beast__buffered_read_stream.async_read_some [*async_read_some]]] 5077 [ 5078 Start an asynchronous read. 5079 ] 5080 ] 5081 [ 5082 [[link beast.ref.boost__beast__buffered_read_stream.async_write_some [*async_write_some]]] 5083 [ 5084 Start an asynchronous write. 5085 ] 5086 ] 5087 [ 5088 [[link beast.ref.boost__beast__buffered_read_stream.buffer [*buffer]]] 5089 [ 5090 Access the internal buffer. 5091 ] 5092 ] 5093 [ 5094 [[link beast.ref.boost__beast__buffered_read_stream.buffered_read_stream [*buffered_read_stream]]] 5095 [ 5096 Move constructor. 5097 5098 Construct the wrapping stream. 5099 ] 5100 ] 5101 [ 5102 [[link beast.ref.boost__beast__buffered_read_stream.capacity [*capacity]]] 5103 [ 5104 Set the maximum buffer size. 5105 ] 5106 ] 5107 [ 5108 [[link beast.ref.boost__beast__buffered_read_stream.get_executor [*get_executor]]] 5109 [ 5110 Get the executor associated with the object. 5111 ] 5112 ] 5113 [ 5114 [[link beast.ref.boost__beast__buffered_read_stream.next_layer [*next_layer]]] 5115 [ 5116 Get a reference to the next layer. 5117 5118 Get a const reference to the next layer. 5119 ] 5120 ] 5121 [ 5122 [[link beast.ref.boost__beast__buffered_read_stream.operator_eq_ [*operator=]]] 5123 [ 5124 Move assignment. 5125 ] 5126 ] 5127 [ 5128 [[link beast.ref.boost__beast__buffered_read_stream.read_some [*read_some]]] 5129 [ 5130 Read some data from the stream. 5131 ] 5132 ] 5133 [ 5134 [[link beast.ref.boost__beast__buffered_read_stream.write_some [*write_some]]] 5135 [ 5136 Write some data to the stream. 5137 ] 5138 ] 5139] 5140 5141[heading Description] 5142This wraps a ['Stream] implementation so that calls to write are passed through to the underlying stream, while calls to read will first consume the input sequence stored in a ['DynamicBuffer] which is part of the object. 5143The use-case for this class is different than that of the `net::buffered_read_stream`. It is designed to facilitate the use of `net::read_until`, and to allow buffers acquired during detection of handshakes to be made transparently available to callers. A hypothetical implementation of the buffered version of `net::ssl::stream::async_handshake` could make use of this wrapper. 5144Uses: 5145 5146* Transparently leave untouched input acquired in calls to `net::read_until` behind for subsequent callers. 5147 5148 5149* "Preload" a stream with handshake input data acquired from other sources. 5150 5151Example: 5152``` 5153 // Process the next HTTP header on the stream, 5154 // leaving excess bytes behind for the next call. 5155 // 5156 template<class Stream, class DynamicBuffer> 5157 void process_http_message( 5158 buffered_read_stream<Stream, DynamicBuffer>& stream) 5159 { 5160 // Read up to and including the end of the HTTP 5161 // header, leaving the sequence in the stream's 5162 // buffer. read_until may read past the end of the 5163 // headers; the return value will include only the 5164 // part up to the end of the delimiter. 5165 // 5166 std::size_t bytes_transferred = 5167 net::read_until( 5168 stream.next_layer(), stream.buffer(), "\r\n\r\n"); 5169 5170 // Use buffers_prefix() to limit the input 5171 // sequence to only the data up to and including 5172 // the trailing "\r\n\r\n". 5173 // 5174 auto header_buffers = buffers_prefix( 5175 bytes_transferred, stream.buffer().data()); 5176 5177 ... 5178 5179 // Discard the portion of the input corresponding 5180 // to the HTTP headers. 5181 // 5182 stream.buffer().consume(bytes_transferred); 5183 5184 // Everything we read from the stream 5185 // is part of the content-body. 5186 } 5187``` 5188[heading Template Parameters] 5189[table [[Type][Description]] 5190 [[`Stream`][ 5191 5192The type of stream to wrap. 5193 ]] 5194 [[`DynamicBuffer`][ 5195 5196The type of stream buffer to use. 5197 ]] 5198] 5199[section:async_read_some buffered_read_stream::async_read_some] 5200[indexterm2 async_read_some..buffered_read_stream] 5201Start an asynchronous read. 5202[heading Synopsis] 5203``` 5204template< 5205 class __MutableBufferSequence__, 5206 class __ReadHandler__ = net::default_completion_token_t<executor_type>> 5207``__deduced__`` 5208async_read_some( 5209 MutableBufferSequence const& buffers, 5210 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 5211``` 5212 5213[heading Description] 5214This function is used to asynchronously read data from the stream. The function call always returns immediately. 5215[heading Parameters] 5216[table [[Name][Description]] 5217 [[`buffers`][ 5218 5219One or more buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. 5220 ]] 5221 [[`handler`][ 5222 5223The 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: 5224``` 5225 void handler( 5226 error_code const& error, // result of operation 5227 std::size_t bytes_transferred // number of bytes transferred 5228 ); 5229``` 5230 5231 ]] 5232] 5233Regardless 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 `net::post`. [endsect] 5234[section:async_write_some buffered_read_stream::async_write_some] 5235[indexterm2 async_write_some..buffered_read_stream] 5236Start an asynchronous write. 5237[heading Synopsis] 5238``` 5239template< 5240 class __ConstBufferSequence__, 5241 class __WriteHandler__ = net::default_completion_token_t<executor_type>> 5242``__deduced__`` 5243async_write_some( 5244 ConstBufferSequence const& buffers, 5245 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 5246``` 5247 5248[heading Description] 5249This function is used to asynchronously write data from the stream. The function call always returns immediately. 5250[heading Parameters] 5251[table [[Name][Description]] 5252 [[`buffers`][ 5253 5254One or more data buffers to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called. 5255 ]] 5256 [[`handler`][ 5257 5258The 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: 5259``` 5260 void handler( 5261 error_code const& error, // result of operation 5262 std::size_t bytes_transferred // number of bytes transferred 5263 ); 5264``` 5265Regardless 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 `net::post`. 5266 ]] 5267] 5268[endsect] 5269[section:buffer buffered_read_stream::buffer] 5270[indexterm2 buffer..buffered_read_stream] 5271Access the internal buffer. ``` 5272DynamicBuffer& 5273``[link beast.ref.boost__beast__buffered_read_stream.buffer.overload1 buffer]``(); 5274 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.buffer.overload1 more...]]`` 5275 5276DynamicBuffer const & 5277``[link beast.ref.boost__beast__buffered_read_stream.buffer.overload2 buffer]``() const; 5278 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.buffer.overload2 more...]]`` 5279``` 5280[section:overload1 buffered_read_stream::buffer (1 of 2 overloads)] 5281Access the internal buffer. 5282[heading Synopsis] 5283``` 5284DynamicBuffer& 5285buffer(); 5286``` 5287 5288[heading Description] 5289The internal buffer is returned. It is possible for the caller to break invariants with this function. For example, by causing the internal buffer size to increase beyond the caller defined maximum. [endsect] 5290[section:overload2 buffered_read_stream::buffer (2 of 2 overloads)] 5291Access the internal buffer. 5292[heading Synopsis] 5293``` 5294DynamicBuffer const & 5295buffer() const; 5296``` 5297 5298[heading Description] 5299[endsect] 5300[endsect] 5301 5302[section:buffer_type buffered_read_stream::buffer_type] 5303[indexterm2 buffer_type..buffered_read_stream] 5304The type of the internal buffer. 5305[heading Synopsis] 5306 5307``` 5308using buffer_type = DynamicBuffer; 5309``` 5310 5311[heading Description] 5312[endsect] 5313[section:buffered_read_stream buffered_read_stream::buffered_read_stream] 5314[indexterm2 buffered_read_stream..buffered_read_stream] 5315Move constructor. ``` 5316``[link beast.ref.boost__beast__buffered_read_stream.buffered_read_stream.overload1 buffered_read_stream]``( 5317 buffered_read_stream&&); 5318 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.buffered_read_stream.overload1 more...]]`` 5319 5320``` 5321Construct the wrapping stream. ``` 5322template< 5323 class... Args> 5324explicit 5325``[link beast.ref.boost__beast__buffered_read_stream.buffered_read_stream.overload2 buffered_read_stream]``( 5326 Args&&... args); 5327 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.buffered_read_stream.overload2 more...]]`` 5328``` 5329[section:overload1 buffered_read_stream::buffered_read_stream (1 of 2 overloads)] 5330Move constructor. 5331[heading Synopsis] 5332``` 5333buffered_read_stream( 5334 buffered_read_stream&&); 5335``` 5336 5337[heading Description] 5338[heading Remarks] 5339The behavior of move assignment on or from streams with active or pending operations is undefined. 5340[endsect] 5341[section:overload2 buffered_read_stream::buffered_read_stream (2 of 2 overloads)] 5342Construct the wrapping stream. 5343[heading Synopsis] 5344``` 5345template< 5346 class... Args> 5347buffered_read_stream( 5348 Args&&... args); 5349``` 5350 5351[heading Description] 5352[heading Parameters] 5353[table [[Name][Description]] 5354 [[`args`][ 5355 5356Parameters forwarded to the `Stream` constructor. 5357 ]] 5358] 5359[endsect] 5360[endsect] 5361 5362[section:capacity buffered_read_stream::capacity] 5363[indexterm2 capacity..buffered_read_stream] 5364Set the maximum buffer size. 5365[heading Synopsis] 5366``` 5367void 5368capacity( 5369 std::size_t size); 5370``` 5371 5372[heading Description] 5373This changes the maximum size of the internal buffer used to hold read data. No bytes are discarded by this call. If the buffer size is set to zero, no more data will be buffered. 5374Thread safety: The caller is responsible for making sure the call is made from the same implicit or explicit strand. 5375[heading Parameters] 5376[table [[Name][Description]] 5377 [[`size`][ 5378 5379The number of bytes in the read buffer. 5380 ]] 5381] 5382[heading Remarks] 5383This is a soft limit. If the new maximum size is smaller than the amount of data in the buffer, no bytes are discarded. 5384[endsect] 5385[section:executor_type buffered_read_stream::executor_type] 5386[indexterm2 executor_type..buffered_read_stream] 5387 5388[heading Synopsis] 5389 5390``` 5391using executor_type = beast::executor_type< next_layer_type >; 5392``` 5393 5394[heading Description] 5395[endsect] 5396[section:get_executor buffered_read_stream::get_executor] 5397[indexterm2 get_executor..buffered_read_stream] 5398Get the executor associated with the object. 5399[heading Synopsis] 5400``` 5401executor_type 5402get_executor(); 5403``` 5404 5405[heading Description] 5406This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations. 5407[heading Return Value] 5408A copy of the executor that stream will use to dispatch handlers. 5409[endsect] 5410[section:next_layer buffered_read_stream::next_layer] 5411[indexterm2 next_layer..buffered_read_stream] 5412Get a reference to the next layer. ``` 5413next_layer_type& 5414``[link beast.ref.boost__beast__buffered_read_stream.next_layer.overload1 next_layer]``(); 5415 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.next_layer.overload1 more...]]`` 5416 5417``` 5418Get a const reference to the next layer. ``` 5419next_layer_type const & 5420``[link beast.ref.boost__beast__buffered_read_stream.next_layer.overload2 next_layer]``() const; 5421 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.next_layer.overload2 more...]]`` 5422``` 5423[section:overload1 buffered_read_stream::next_layer (1 of 2 overloads)] 5424Get a reference to the next layer. 5425[heading Synopsis] 5426``` 5427next_layer_type& 5428next_layer(); 5429``` 5430 5431[heading Description] 5432[endsect] 5433[section:overload2 buffered_read_stream::next_layer (2 of 2 overloads)] 5434Get a const reference to the next layer. 5435[heading Synopsis] 5436``` 5437next_layer_type const & 5438next_layer() const; 5439``` 5440 5441[heading Description] 5442[endsect] 5443[endsect] 5444 5445[section:next_layer_type buffered_read_stream::next_layer_type] 5446[indexterm2 next_layer_type..buffered_read_stream] 5447The type of the next layer. 5448[heading Synopsis] 5449 5450``` 5451using next_layer_type = typename std::remove_reference< Stream >::type; 5452``` 5453 5454[heading Description] 5455[endsect] 5456[section:operator_eq_ buffered_read_stream::operator=] 5457[indexterm2 operator=..buffered_read_stream] 5458Move assignment. 5459[heading Synopsis] 5460``` 5461buffered_read_stream& 5462operator=( 5463 buffered_read_stream&&); 5464``` 5465 5466[heading Description] 5467[heading Remarks] 5468The behavior of move assignment on or from streams with active or pending operations is undefined. 5469[endsect] 5470[section:read_some buffered_read_stream::read_some] 5471[indexterm2 read_some..buffered_read_stream] 5472Read some data from the stream. ``` 5473template< 5474 class __MutableBufferSequence__> 5475std::size_t 5476``[link beast.ref.boost__beast__buffered_read_stream.read_some.overload1 read_some]``( 5477 MutableBufferSequence const& buffers); 5478 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.read_some.overload1 more...]]`` 5479 5480template< 5481 class __MutableBufferSequence__> 5482std::size_t 5483``[link beast.ref.boost__beast__buffered_read_stream.read_some.overload2 read_some]``( 5484 MutableBufferSequence const& buffers, 5485 error_code& ec); 5486 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.read_some.overload2 more...]]`` 5487``` 5488[section:overload1 buffered_read_stream::read_some (1 of 2 overloads)] 5489Read some data from the stream. 5490[heading Synopsis] 5491``` 5492template< 5493 class __MutableBufferSequence__> 5494std::size_t 5495read_some( 5496 MutableBufferSequence const& buffers); 5497``` 5498 5499[heading Description] 5500This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 5501[heading Parameters] 5502[table [[Name][Description]] 5503 [[`buffers`][ 5504 5505One or more buffers into which the data will be read. 5506 ]] 5507] 5508[heading Return Value] 5509The number of bytes read. 5510[heading Exceptions] 5511[table [[Type][Thrown On]] 5512 [[`system_error`][ 5513 5514Thrown on failure. 5515 ]] 5516] 5517[endsect] 5518[section:overload2 buffered_read_stream::read_some (2 of 2 overloads)] 5519Read some data from the stream. 5520[heading Synopsis] 5521``` 5522template< 5523 class __MutableBufferSequence__> 5524std::size_t 5525read_some( 5526 MutableBufferSequence const& buffers, 5527 error_code& ec); 5528``` 5529 5530[heading Description] 5531This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 5532[heading Parameters] 5533[table [[Name][Description]] 5534 [[`buffers`][ 5535 5536One or more buffers into which the data will be read. 5537 ]] 5538 [[`ec`][ 5539 5540Set to the error, if any occurred. 5541 ]] 5542] 5543[heading Return Value] 5544The number of bytes read, or 0 on error. 5545[endsect] 5546[endsect] 5547 5548[section:write_some buffered_read_stream::write_some] 5549[indexterm2 write_some..buffered_read_stream] 5550Write some data to the stream. ``` 5551template< 5552 class __ConstBufferSequence__> 5553std::size_t 5554``[link beast.ref.boost__beast__buffered_read_stream.write_some.overload1 write_some]``( 5555 ConstBufferSequence const& buffers); 5556 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.write_some.overload1 more...]]`` 5557 5558template< 5559 class __ConstBufferSequence__> 5560std::size_t 5561``[link beast.ref.boost__beast__buffered_read_stream.write_some.overload2 write_some]``( 5562 ConstBufferSequence const& buffers, 5563 error_code& ec); 5564 ``[''''»''' [link beast.ref.boost__beast__buffered_read_stream.write_some.overload2 more...]]`` 5565``` 5566[section:overload1 buffered_read_stream::write_some (1 of 2 overloads)] 5567Write some data to the stream. 5568[heading Synopsis] 5569``` 5570template< 5571 class __ConstBufferSequence__> 5572std::size_t 5573write_some( 5574 ConstBufferSequence const& buffers); 5575``` 5576 5577[heading Description] 5578This function is used to write data to the stream. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs. 5579[heading Parameters] 5580[table [[Name][Description]] 5581 [[`buffers`][ 5582 5583One or more data buffers to be written to the stream. 5584 ]] 5585] 5586[heading Return Value] 5587The number of bytes written. 5588[heading Exceptions] 5589[table [[Type][Thrown On]] 5590 [[`system_error`][ 5591 5592Thrown on failure. 5593 ]] 5594] 5595[endsect] 5596[section:overload2 buffered_read_stream::write_some (2 of 2 overloads)] 5597Write some data to the stream. 5598[heading Synopsis] 5599``` 5600template< 5601 class __ConstBufferSequence__> 5602std::size_t 5603write_some( 5604 ConstBufferSequence const& buffers, 5605 error_code& ec); 5606``` 5607 5608[heading Description] 5609This function is used to write data to the stream. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs. 5610[heading Parameters] 5611[table [[Name][Description]] 5612 [[`buffers`][ 5613 5614One or more data buffers to be written to the stream. 5615 ]] 5616 [[`ec`][ 5617 5618Set to the error, if any occurred. 5619 ]] 5620] 5621[heading Return Value] 5622The number of bytes written. 5623[endsect] 5624[endsect] 5625 5626 5627 5628 5629Convenience header [include_file boost/beast/core.hpp] 5630 5631[endsect] 5632 5633 5634 5635[section:boost__beast__buffers buffers] 5636[indexterm1 buffers] 5637 5638[heading Synopsis] 5639 5640Defined in header [include_file boost/beast/core/ostream.hpp] 5641 5642 5643 5644``` 5645template< 5646 class T> 5647void 5648buffers( 5649 T const&); 5650 5651``` 5652 5653[heading Description] 5654 5655 5656 5657Convenience header [include_file boost/beast/core.hpp] 5658 5659[endsect] 5660[section:boost__beast__buffers_adaptor buffers_adaptor] 5661Adapts a ['MutableBufferSequence] into a ['DynamicBuffer]. 5662[heading Synopsis] 5663 5664Defined in header [include_file boost/beast/core/buffers_adaptor.hpp] 5665 5666 5667 5668``` 5669template< 5670 class __MutableBufferSequence__> 5671class buffers_adaptor 5672``` 5673[heading Types] 5674[table [[Name][Description]] 5675 [ 5676 [[link beast.ref.boost__beast__buffers_adaptor.const_buffers_type [*const_buffers_type]]] 5677 [ 5678 The ConstBufferSequence used to represent the readable bytes. 5679 ] 5680 ] 5681 [ 5682 [[link beast.ref.boost__beast__buffers_adaptor.mutable_buffers_type [*mutable_buffers_type]]] 5683 [ 5684 The MutableBufferSequence used to represent the writable bytes. 5685 ] 5686 ] 5687 [ 5688 [[link beast.ref.boost__beast__buffers_adaptor.mutable_data_type [*mutable_data_type]]] 5689 [ 5690 The MutableBufferSequence used to represent the readable bytes. 5691 ] 5692 ] 5693 [ 5694 [[link beast.ref.boost__beast__buffers_adaptor.value_type [*value_type]]] 5695 [ 5696 The type of the underlying mutable buffer sequence. 5697 ] 5698 ] 5699] 5700[heading Member Functions] 5701[table [[Name][Description]] 5702 [ 5703 [[link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor [*buffers_adaptor]]] 5704 [ 5705 Construct a buffers adaptor. 5706 5707 Constructor. 5708 5709 Copy Constructor. 5710 ] 5711 ] 5712 [ 5713 [[link beast.ref.boost__beast__buffers_adaptor.capacity [*capacity]]] 5714 [ 5715 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 5716 ] 5717 ] 5718 [ 5719 [[link beast.ref.boost__beast__buffers_adaptor.cdata [*cdata]]] 5720 [ 5721 Returns a constant buffer sequence representing the readable bytes. 5722 ] 5723 ] 5724 [ 5725 [[link beast.ref.boost__beast__buffers_adaptor.commit [*commit]]] 5726 [ 5727 Append writable bytes to the readable bytes. 5728 ] 5729 ] 5730 [ 5731 [[link beast.ref.boost__beast__buffers_adaptor.consume [*consume]]] 5732 [ 5733 Remove bytes from beginning of the readable bytes. 5734 ] 5735 ] 5736 [ 5737 [[link beast.ref.boost__beast__buffers_adaptor.data [*data]]] 5738 [ 5739 Returns a constant buffer sequence representing the readable bytes. 5740 5741 Returns a mutable buffer sequence representing the readable bytes. 5742 ] 5743 ] 5744 [ 5745 [[link beast.ref.boost__beast__buffers_adaptor.max_size [*max_size]]] 5746 [ 5747 Return the maximum number of bytes, both readable and writable, that can ever be held. 5748 ] 5749 ] 5750 [ 5751 [[link beast.ref.boost__beast__buffers_adaptor.operator_eq_ [*operator=]]] 5752 [ 5753 Copy Assignment. 5754 ] 5755 ] 5756 [ 5757 [[link beast.ref.boost__beast__buffers_adaptor.prepare [*prepare]]] 5758 [ 5759 Returns a mutable buffer sequence representing writable bytes. 5760 ] 5761 ] 5762 [ 5763 [[link beast.ref.boost__beast__buffers_adaptor.size [*size]]] 5764 [ 5765 Returns the number of readable bytes. 5766 ] 5767 ] 5768 [ 5769 [[link beast.ref.boost__beast__buffers_adaptor.value [*value]]] 5770 [ 5771 Returns the original mutable buffer sequence. 5772 ] 5773 ] 5774] 5775 5776[heading Description] 5777This class wraps a ['MutableBufferSequence] to meet the requirements of ['DynamicBuffer]. Upon construction the input and output sequences are empty. A copy of the mutable buffer sequence object is stored; however, ownership of the underlying memory is not transferred. The caller is responsible for making sure that referenced memory remains valid for the duration of any operations. 5778The size of the mutable buffer sequence determines the maximum number of bytes which may be prepared and committed. 5779[heading Template Parameters] 5780[table [[Type][Description]] 5781 [[`MutableBufferSequence`][ 5782 5783The type of mutable buffer sequence to adapt. 5784 ]] 5785] 5786[section:buffers_adaptor buffers_adaptor::buffers_adaptor] 5787[indexterm2 buffers_adaptor..buffers_adaptor] 5788Construct a buffers adaptor. ``` 5789explicit 5790``[link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload1 buffers_adaptor]``( 5791 MutableBufferSequence const& buffers); 5792 ``[''''»''' [link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload1 more...]]`` 5793 5794``` 5795Constructor. ``` 5796template< 5797 class... Args> 5798explicit 5799``[link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload2 buffers_adaptor]``( 5800 boost::in_place_init_t, 5801 Args&&... args); 5802 ``[''''»''' [link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload2 more...]]`` 5803 5804``` 5805Copy Constructor. ``` 5806``[link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload3 buffers_adaptor]``( 5807 buffers_adaptor const& other); 5808 ``[''''»''' [link beast.ref.boost__beast__buffers_adaptor.buffers_adaptor.overload3 more...]]`` 5809``` 5810[section:overload1 buffers_adaptor::buffers_adaptor (1 of 3 overloads)] 5811Construct a buffers adaptor. 5812[heading Synopsis] 5813``` 5814buffers_adaptor( 5815 MutableBufferSequence const& buffers); 5816``` 5817 5818[heading Description] 5819[heading Parameters] 5820[table [[Name][Description]] 5821 [[`buffers`][ 5822 5823The mutable buffer sequence to wrap. A copy of the object will be made, but ownership of the memory is not transferred. 5824 ]] 5825] 5826[endsect] 5827[section:overload2 buffers_adaptor::buffers_adaptor (2 of 3 overloads)] 5828Constructor. 5829[heading Synopsis] 5830``` 5831template< 5832 class... Args> 5833buffers_adaptor( 5834 boost::in_place_init_t, 5835 Args&&... args); 5836``` 5837 5838[heading Description] 5839This constructs the buffer adaptor in-place from a list of arguments. 5840[heading Parameters] 5841[table [[Name][Description]] 5842 [[`args`][ 5843 5844Arguments forwarded to the buffers constructor. 5845 ]] 5846] 5847[endsect] 5848[section:overload3 buffers_adaptor::buffers_adaptor (3 of 3 overloads)] 5849Copy Constructor. 5850[heading Synopsis] 5851``` 5852buffers_adaptor( 5853 buffers_adaptor const& other); 5854``` 5855 5856[heading Description] 5857[endsect] 5858[endsect] 5859 5860[section:capacity buffers_adaptor::capacity] 5861[indexterm2 capacity..buffers_adaptor] 5862Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 5863[heading Synopsis] 5864``` 5865std::size_t 5866capacity() const; 5867``` 5868 5869[heading Description] 5870[endsect] 5871[section:cdata buffers_adaptor::cdata] 5872[indexterm2 cdata..buffers_adaptor] 5873Returns a constant buffer sequence representing the readable bytes. 5874[heading Synopsis] 5875``` 5876const_buffers_type 5877cdata() const; 5878``` 5879 5880[heading Description] 5881[endsect] 5882[section:commit buffers_adaptor::commit] 5883[indexterm2 commit..buffers_adaptor] 5884Append writable bytes to the readable bytes. 5885[heading Synopsis] 5886``` 5887void 5888commit( 5889 std::size_t n); 5890``` 5891 5892[heading Description] 5893Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 5894All buffer sequences previously obtained using [link beast.ref.boost__beast__buffers_adaptor.prepare `buffers_adaptor::prepare`] are invalidated. Buffer sequences previously obtained using [link beast.ref.boost__beast__buffers_adaptor.data `buffers_adaptor::data`] remain valid. 5895[heading Parameters] 5896[table [[Name][Description]] 5897 [[`n`][ 5898 5899The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 5900 ]] 5901] 5902[heading Exception Safety] 5903 5904No-throw guarantee. [endsect] 5905[section:const_buffers_type buffers_adaptor::const_buffers_type] 5906[indexterm2 const_buffers_type..buffers_adaptor] 5907The ConstBufferSequence used to represent the readable bytes. 5908[heading Synopsis] 5909 5910``` 5911using const_buffers_type = ``['implementation-defined]``; 5912``` 5913 5914[heading Description] 5915[endsect] 5916[section:consume buffers_adaptor::consume] 5917[indexterm2 consume..buffers_adaptor] 5918Remove bytes from beginning of the readable bytes. 5919[heading Synopsis] 5920``` 5921void 5922consume( 5923 std::size_t n); 5924``` 5925 5926[heading Description] 5927Removes n bytes from the beginning of the readable bytes. 5928All buffers sequences previously obtained using [link beast.ref.boost__beast__buffers_adaptor.data `buffers_adaptor::data`] or [link beast.ref.boost__beast__buffers_adaptor.prepare `buffers_adaptor::prepare`] are invalidated. 5929[heading Parameters] 5930[table [[Name][Description]] 5931 [[`n`][ 5932 5933The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 5934 ]] 5935] 5936[heading Exception Safety] 5937 5938No-throw guarantee. [endsect] 5939[section:data buffers_adaptor::data] 5940[indexterm2 data..buffers_adaptor] 5941Returns a constant buffer sequence representing the readable bytes. ``` 5942const_buffers_type 5943``[link beast.ref.boost__beast__buffers_adaptor.data.overload1 data]``() const; 5944 ``[''''»''' [link beast.ref.boost__beast__buffers_adaptor.data.overload1 more...]]`` 5945 5946``` 5947Returns a mutable buffer sequence representing the readable bytes. ``` 5948mutable_data_type 5949``[link beast.ref.boost__beast__buffers_adaptor.data.overload2 data]``(); 5950 ``[''''»''' [link beast.ref.boost__beast__buffers_adaptor.data.overload2 more...]]`` 5951``` 5952[section:overload1 buffers_adaptor::data (1 of 2 overloads)] 5953Returns a constant buffer sequence representing the readable bytes. 5954[heading Synopsis] 5955``` 5956const_buffers_type 5957data() const; 5958``` 5959 5960[heading Description] 5961[endsect] 5962[section:overload2 buffers_adaptor::data (2 of 2 overloads)] 5963Returns a mutable buffer sequence representing the readable bytes. 5964[heading Synopsis] 5965``` 5966mutable_data_type 5967data(); 5968``` 5969 5970[heading Description] 5971[endsect] 5972[endsect] 5973 5974[section:max_size buffers_adaptor::max_size] 5975[indexterm2 max_size..buffers_adaptor] 5976Return the maximum number of bytes, both readable and writable, that can ever be held. 5977[heading Synopsis] 5978``` 5979std::size_t 5980max_size() const; 5981``` 5982 5983[heading Description] 5984[endsect] 5985[section:mutable_buffers_type buffers_adaptor::mutable_buffers_type] 5986[indexterm2 mutable_buffers_type..buffers_adaptor] 5987The MutableBufferSequence used to represent the writable bytes. 5988[heading Synopsis] 5989 5990``` 5991using mutable_buffers_type = ``['implementation-defined]``; 5992``` 5993 5994[heading Description] 5995[endsect] 5996[section:mutable_data_type buffers_adaptor::mutable_data_type] 5997[indexterm2 mutable_data_type..buffers_adaptor] 5998The MutableBufferSequence used to represent the readable bytes. 5999[heading Synopsis] 6000 6001``` 6002using mutable_data_type = ``['implementation-defined]``; 6003``` 6004 6005[heading Description] 6006[endsect] 6007[section:operator_eq_ buffers_adaptor::operator=] 6008[indexterm2 operator=..buffers_adaptor] 6009Copy Assignment. 6010[heading Synopsis] 6011``` 6012buffers_adaptor& 6013operator=( 6014 buffers_adaptor const&); 6015``` 6016 6017[heading Description] 6018[endsect] 6019[section:prepare buffers_adaptor::prepare] 6020[indexterm2 prepare..buffers_adaptor] 6021Returns a mutable buffer sequence representing writable bytes. 6022[heading Synopsis] 6023``` 6024mutable_buffers_type 6025prepare( 6026 std::size_t n); 6027``` 6028 6029[heading Description] 6030Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. This function does not allocate memory. Instead, the storage comes from the underlying mutable buffer sequence. 6031All buffer sequences previously obtained using [link beast.ref.boost__beast__buffers_adaptor.prepare `buffers_adaptor::prepare`] are invalidated. Buffer sequences previously obtained using [link beast.ref.boost__beast__buffers_adaptor.data `buffers_adaptor::data`] remain valid. 6032[heading Parameters] 6033[table [[Name][Description]] 6034 [[`n`][ 6035 6036The desired number of bytes in the returned buffer sequence. 6037 ]] 6038] 6039[heading Exceptions] 6040[table [[Type][Thrown On]] 6041 [[`std::length_error`][ 6042 6043if `size() + n` exceeds `max_size()`. 6044 ]] 6045] 6046[heading Exception Safety] 6047 6048Strong guarantee. [endsect] 6049[section:size buffers_adaptor::size] 6050[indexterm2 size..buffers_adaptor] 6051Returns the number of readable bytes. 6052[heading Synopsis] 6053``` 6054std::size_t 6055size() const; 6056``` 6057 6058[heading Description] 6059[endsect] 6060[section:value buffers_adaptor::value] 6061[indexterm2 value..buffers_adaptor] 6062Returns the original mutable buffer sequence. 6063[heading Synopsis] 6064``` 6065value_type const & 6066value() const; 6067``` 6068 6069[heading Description] 6070[endsect] 6071[section:value_type buffers_adaptor::value_type] 6072[indexterm2 value_type..buffers_adaptor] 6073The type of the underlying mutable buffer sequence. 6074[heading Synopsis] 6075 6076``` 6077using value_type = MutableBufferSequence; 6078``` 6079 6080[heading Description] 6081[endsect] 6082 6083 6084 6085Convenience header [include_file boost/beast/core.hpp] 6086 6087[endsect] 6088 6089 6090 6091[section:boost__beast__buffers_adaptor__readable_bytes buffers_adaptor::readable_bytes] 6092 6093[heading Synopsis] 6094 6095Defined in header [include_file boost/beast/core/buffers_adaptor.hpp] 6096 6097 6098 6099``` 6100template< 6101 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 6102class readable_bytes 6103``` 6104 6105[heading Description] 6106 6107 6108 6109Convenience header [include_file boost/beast/core.hpp] 6110 6111[endsect] 6112 6113 6114 6115[section:boost__beast__buffers_cat buffers_cat] 6116[indexterm1 buffers_cat] 6117Concatenate 1 or more buffer sequences. 6118[heading Synopsis] 6119 6120Defined in header [include_file boost/beast/core/buffers_cat.hpp] 6121 6122 6123 6124``` 6125template< 6126 class... __BufferSequence__> 6127buffers_cat_view< BufferSequence... > 6128buffers_cat( 6129 BufferSequence const&... buffers); 6130 6131``` 6132 6133[heading Description] 6134This function returns a constant or mutable buffer sequence which, when iterated, efficiently concatenates the input buffer sequences. Copies of the arguments passed will be made; however, the returned object does not take ownership of the underlying memory. The application is still responsible for managing the lifetime of the referenced memory. [heading Parameters] 6135[table [[Name][Description]] 6136 [[`buffers`][ 6137 6138The list of buffer sequences to concatenate. 6139 ]] 6140] 6141[heading Return Value] 6142A new buffer sequence that represents the concatenation of the input buffer sequences. This buffer sequence will be a ['MutableBufferSequence] if each of the passed buffer sequences is also a ['MutableBufferSequence]; otherwise the returned buffer sequence will be a ['ConstBufferSequence]. 6143[heading See Also] 6144[link beast.ref.boost__beast__buffers_cat_view `buffers_cat_view`] 6145 6146 6147 6148Convenience header [include_file boost/beast/core.hpp] 6149 6150[endsect] 6151[section:boost__beast__buffers_cat_view buffers_cat_view] 6152A buffer sequence representing a concatenation of buffer sequences. 6153[heading Synopsis] 6154 6155Defined in header [include_file boost/beast/core/buffers_cat.hpp] 6156 6157 6158 6159``` 6160template< 6161 class... Buffers> 6162class buffers_cat_view 6163``` 6164[heading Types] 6165[table [[Name][Description]] 6166 [ 6167 [[link beast.ref.boost__beast__buffers_cat_view.value_type [*value_type]]] 6168 [ 6169 The type of buffer returned when dereferencing an iterator. 6170 ] 6171 ] 6172] 6173[heading Member Functions] 6174[table [[Name][Description]] 6175 [ 6176 [[link beast.ref.boost__beast__buffers_cat_view.begin [*begin]]] 6177 [ 6178 Returns an iterator to the first buffer in the sequence. 6179 ] 6180 ] 6181 [ 6182 [[link beast.ref.boost__beast__buffers_cat_view.buffers_cat_view [*buffers_cat_view]]] 6183 [ 6184 Copy Constructor. 6185 6186 Constructor. 6187 ] 6188 ] 6189 [ 6190 [[link beast.ref.boost__beast__buffers_cat_view.end [*end]]] 6191 [ 6192 Returns an iterator to one past the last buffer in the sequence. 6193 ] 6194 ] 6195 [ 6196 [[link beast.ref.boost__beast__buffers_cat_view.operator_eq_ [*operator=]]] 6197 [ 6198 Copy Assignment. 6199 ] 6200 ] 6201] 6202 6203[heading Description] 6204[heading See Also] 6205[link beast.ref.boost__beast__buffers_cat `buffers_cat`] 6206[section:begin buffers_cat_view::begin] 6207[indexterm2 begin..buffers_cat_view] 6208Returns an iterator to the first buffer in the sequence. 6209[heading Synopsis] 6210``` 6211const_iterator 6212begin() const; 6213``` 6214 6215[heading Description] 6216[endsect] 6217[section:buffers_cat_view buffers_cat_view::buffers_cat_view] 6218[indexterm2 buffers_cat_view..buffers_cat_view] 6219Copy Constructor. ``` 6220``[link beast.ref.boost__beast__buffers_cat_view.buffers_cat_view.overload1 buffers_cat_view]``( 6221 buffers_cat_view const&); 6222 ``[''''»''' [link beast.ref.boost__beast__buffers_cat_view.buffers_cat_view.overload1 more...]]`` 6223 6224``` 6225Constructor. ``` 6226explicit 6227``[link beast.ref.boost__beast__buffers_cat_view.buffers_cat_view.overload2 buffers_cat_view]``( 6228 Buffers const&... buffers); 6229 ``[''''»''' [link beast.ref.boost__beast__buffers_cat_view.buffers_cat_view.overload2 more...]]`` 6230``` 6231[section:overload1 buffers_cat_view::buffers_cat_view (1 of 2 overloads)] 6232Copy Constructor. 6233[heading Synopsis] 6234``` 6235buffers_cat_view( 6236 buffers_cat_view const&); 6237``` 6238 6239[heading Description] 6240[endsect] 6241[section:overload2 buffers_cat_view::buffers_cat_view (2 of 2 overloads)] 6242Constructor. 6243[heading Synopsis] 6244``` 6245buffers_cat_view( 6246 Buffers const&... buffers); 6247``` 6248 6249[heading Description] 6250[heading Parameters] 6251[table [[Name][Description]] 6252 [[`buffers`][ 6253 6254The list of buffer sequences to concatenate. Copies of the arguments will be maintained for the lifetime of the concatenated sequence; however, the ownership of the memory buffers themselves is not transferred. 6255 ]] 6256] 6257[endsect] 6258[endsect] 6259 6260[section:end buffers_cat_view::end] 6261[indexterm2 end..buffers_cat_view] 6262Returns an iterator to one past the last buffer in the sequence. 6263[heading Synopsis] 6264``` 6265const_iterator 6266end() const; 6267``` 6268 6269[heading Description] 6270[endsect] 6271[section:operator_eq_ buffers_cat_view::operator=] 6272[indexterm2 operator=..buffers_cat_view] 6273Copy Assignment. 6274[heading Synopsis] 6275``` 6276buffers_cat_view& 6277operator=( 6278 buffers_cat_view const&); 6279``` 6280 6281[heading Description] 6282[endsect] 6283[section:value_type buffers_cat_view::value_type] 6284[indexterm2 value_type..buffers_cat_view] 6285The type of buffer returned when dereferencing an iterator. 6286[heading Synopsis] 6287 6288``` 6289using value_type = ``['see-below]``; 6290``` 6291 6292[heading Description] 6293If every buffer sequence in the view is a ['MutableBufferSequence], then `value_type` will be `net::mutable_buffer`. Otherwise, `value_type` will be `net::const_buffer`. [endsect] 6294 6295 6296 6297Convenience header [include_file boost/beast/core.hpp] 6298 6299[endsect] 6300 6301 6302 6303[section:boost__beast__buffers_front buffers_front] 6304[indexterm1 buffers_front] 6305Returns the first buffer in a buffer sequence. 6306[heading Synopsis] 6307 6308Defined in header [include_file boost/beast/core/buffers_prefix.hpp] 6309 6310 6311 6312``` 6313template< 6314 class __BufferSequence__> 6315buffers_type< BufferSequence > 6316buffers_front( 6317 BufferSequence const& buffers); 6318 6319``` 6320 6321[heading Description] 6322This returns the first buffer in the buffer sequence. If the buffer sequence is an empty range, the returned buffer will have a zero buffer size. 6323[heading Parameters] 6324[table [[Name][Description]] 6325 [[`buffers`][ 6326 6327The buffer sequence. If the sequence is mutable, the returned buffer sequence will also be mutable. Otherwise, the returned buffer sequence will be constant. 6328 ]] 6329] 6330 6331 6332 6333Convenience header [include_file boost/beast/core.hpp] 6334 6335[endsect] 6336[section:boost__beast__buffers_iterator_type buffers_iterator_type] 6337[indexterm1 buffers_iterator_type] 6338Type alias for the iterator type of a buffer sequence type. 6339[heading Synopsis] 6340 6341Defined in header [include_file boost/beast/core/buffer_traits.hpp] 6342 6343 6344 6345``` 6346template< 6347 class __BufferSequence__> 6348using buffers_iterator_type = ``['see-below]``; 6349``` 6350 6351[heading Description] 6352This metafunction is used to determine the type of iterator used by a particular buffer sequence. 6353[heading Template Parameters] 6354[table [[Type][Description]] 6355 [[`T`][ 6356 6357The buffer sequence type to use. The resulting type alias will be equal to the iterator type used by the buffer sequence. 6358 ]] 6359] 6360 6361 6362 6363Convenience header [include_file boost/beast/core.hpp] 6364 6365[endsect] 6366[section:boost__beast__buffers_prefix buffers_prefix] 6367[indexterm1 buffers_prefix] 6368Returns a prefix of a constant or mutable buffer sequence. 6369[heading Synopsis] 6370 6371Defined in header [include_file boost/beast/core/buffers_prefix.hpp] 6372 6373 6374 6375``` 6376template< 6377 class __BufferSequence__> 6378buffers_prefix_view< BufferSequence > 6379buffers_prefix( 6380 std::size_t size, 6381 BufferSequence const& buffers); 6382 6383``` 6384 6385[heading Description] 6386The returned buffer sequence points to the same memory as the passed buffer sequence, but with a size that is equal to or smaller. No memory allocations are performed; the resulting sequence is calculated as a lazy range. 6387[heading Parameters] 6388[table [[Name][Description]] 6389 [[`size`][ 6390 6391The maximum size of the returned buffer sequence in bytes. If this is greater than or equal to the size of the passed buffer sequence, the result will have the same size as the original buffer sequence. 6392 ]] 6393 [[`buffers`][ 6394 6395An object whose type meets the requirements of ['BufferSequence]. The returned value will maintain a copy of the passed buffers for its lifetime; however, ownership of the underlying memory is not transferred. 6396 ]] 6397] 6398[heading Return Value] 6399A constant buffer sequence that represents the prefix of the original buffer sequence. If the original buffer sequence also meets the requirements of ['MutableBufferSequence], then the returned value will also be a mutable buffer sequence. 6400 6401 6402 6403Convenience header [include_file boost/beast/core.hpp] 6404 6405[endsect] 6406[section:boost__beast__buffers_prefix_view buffers_prefix_view] 6407A buffer sequence adaptor that shortens the sequence size. 6408[heading Synopsis] 6409 6410Defined in header [include_file boost/beast/core/buffers_prefix.hpp] 6411 6412 6413 6414``` 6415template< 6416 class __BufferSequence__> 6417class buffers_prefix_view 6418``` 6419[heading Types] 6420[table [[Name][Description]] 6421 [ 6422 [[link beast.ref.boost__beast__buffers_prefix_view.const_iterator [*const_iterator]]] 6423 [ 6424 A bidirectional iterator type that may be used to read elements. 6425 ] 6426 ] 6427 [ 6428 [[link beast.ref.boost__beast__buffers_prefix_view.value_type [*value_type]]] 6429 [ 6430 The type for each element in the list of buffers. 6431 ] 6432 ] 6433] 6434[heading Member Functions] 6435[table [[Name][Description]] 6436 [ 6437 [[link beast.ref.boost__beast__buffers_prefix_view.begin [*begin]]] 6438 [ 6439 Returns an iterator to the first buffer in the sequence. 6440 ] 6441 ] 6442 [ 6443 [[link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view [*buffers_prefix_view]]] 6444 [ 6445 Copy Constructor. 6446 6447 Construct a buffer sequence prefix. 6448 6449 Construct a buffer sequence prefix in-place. 6450 ] 6451 ] 6452 [ 6453 [[link beast.ref.boost__beast__buffers_prefix_view.end [*end]]] 6454 [ 6455 Returns an iterator to one past the last buffer in the sequence. 6456 ] 6457 ] 6458 [ 6459 [[link beast.ref.boost__beast__buffers_prefix_view.operator_eq_ [*operator=]]] 6460 [ 6461 Copy Assignment. 6462 ] 6463 ] 6464] 6465 6466[heading Description] 6467The class adapts a buffer sequence to efficiently represent a shorter subset of the original list of buffers starting with the first byte of the original sequence. 6468[heading Template Parameters] 6469[table [[Type][Description]] 6470 [[`BufferSequence`][ 6471 6472The buffer sequence to adapt. 6473 ]] 6474] 6475[section:begin buffers_prefix_view::begin] 6476[indexterm2 begin..buffers_prefix_view] 6477Returns an iterator to the first buffer in the sequence. 6478[heading Synopsis] 6479``` 6480const_iterator 6481begin() const; 6482``` 6483 6484[heading Description] 6485[endsect] 6486[section:buffers_prefix_view buffers_prefix_view::buffers_prefix_view] 6487[indexterm2 buffers_prefix_view..buffers_prefix_view] 6488Copy Constructor. ``` 6489``[link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload1 buffers_prefix_view]``( 6490 buffers_prefix_view const&); 6491 ``[''''»''' [link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload1 more...]]`` 6492 6493``` 6494Construct a buffer sequence prefix. ``` 6495``[link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload2 buffers_prefix_view]``( 6496 std::size_t size, 6497 BufferSequence const& buffers); 6498 ``[''''»''' [link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload2 more...]]`` 6499 6500``` 6501Construct a buffer sequence prefix in-place. ``` 6502template< 6503 class... Args> 6504``[link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload3 buffers_prefix_view]``( 6505 std::size_t size, 6506 boost::in_place_init_t, 6507 Args&&... args); 6508 ``[''''»''' [link beast.ref.boost__beast__buffers_prefix_view.buffers_prefix_view.overload3 more...]]`` 6509``` 6510[section:overload1 buffers_prefix_view::buffers_prefix_view (1 of 3 overloads)] 6511Copy Constructor. 6512[heading Synopsis] 6513``` 6514buffers_prefix_view( 6515 buffers_prefix_view const&); 6516``` 6517 6518[heading Description] 6519[endsect] 6520[section:overload2 buffers_prefix_view::buffers_prefix_view (2 of 3 overloads)] 6521Construct a buffer sequence prefix. 6522[heading Synopsis] 6523``` 6524buffers_prefix_view( 6525 std::size_t size, 6526 BufferSequence const& buffers); 6527``` 6528 6529[heading Description] 6530[heading Parameters] 6531[table [[Name][Description]] 6532 [[`size`][ 6533 6534The maximum number of bytes in the prefix. If this is larger than the size of passed buffers, the resulting sequence will represent the entire input sequence. 6535 ]] 6536 [[`buffers`][ 6537 6538The buffer sequence to adapt. A copy of the sequence will be made, but ownership of the underlying memory is not transferred. The copy is maintained for the lifetime of the view. 6539 ]] 6540] 6541[endsect] 6542[section:overload3 buffers_prefix_view::buffers_prefix_view (3 of 3 overloads)] 6543Construct a buffer sequence prefix in-place. 6544[heading Synopsis] 6545``` 6546template< 6547 class... Args> 6548buffers_prefix_view( 6549 std::size_t size, 6550 boost::in_place_init_t, 6551 Args&&... args); 6552``` 6553 6554[heading Description] 6555[heading Parameters] 6556[table [[Name][Description]] 6557 [[`size`][ 6558 6559The maximum number of bytes in the prefix. If this is larger than the size of passed buffers, the resulting sequence will represent the entire input sequence. 6560 ]] 6561 [[`args`][ 6562 6563Arguments forwarded to the contained buffer's constructor. 6564 ]] 6565] 6566[endsect] 6567[endsect] 6568 6569[section:const_iterator buffers_prefix_view::const_iterator] 6570[indexterm2 const_iterator..buffers_prefix_view] 6571A bidirectional iterator type that may be used to read elements. 6572[heading Synopsis] 6573 6574``` 6575using const_iterator = ``['implementation-defined]``; 6576``` 6577 6578[heading Description] 6579[endsect] 6580[section:end buffers_prefix_view::end] 6581[indexterm2 end..buffers_prefix_view] 6582Returns an iterator to one past the last buffer in the sequence. 6583[heading Synopsis] 6584``` 6585const_iterator 6586end() const; 6587``` 6588 6589[heading Description] 6590[endsect] 6591[section:operator_eq_ buffers_prefix_view::operator=] 6592[indexterm2 operator=..buffers_prefix_view] 6593Copy Assignment. 6594[heading Synopsis] 6595``` 6596buffers_prefix_view& 6597operator=( 6598 buffers_prefix_view const&); 6599``` 6600 6601[heading Description] 6602[endsect] 6603[section:value_type buffers_prefix_view::value_type] 6604[indexterm2 value_type..buffers_prefix_view] 6605The type for each element in the list of buffers. 6606[heading Synopsis] 6607 6608``` 6609using value_type = ``['see-below]``; 6610``` 6611 6612[heading Description] 6613If the type `BufferSequence` meets the requirements of ['MutableBufferSequence], then `value_type` is `net::mutable_buffer`. Otherwise, `value_type` is `net::const_buffer`. 6614[heading See Also] 6615[link beast.ref.boost__beast__buffers_type `buffers_type`] 6616[endsect] 6617 6618 6619 6620Convenience header [include_file boost/beast/core.hpp] 6621 6622[endsect] 6623 6624 6625 6626[section:boost__beast__buffers_range buffers_range] 6627[indexterm1 buffers_range] 6628Returns an iterable range representing a buffer sequence. 6629[heading Synopsis] 6630 6631Defined in header [include_file boost/beast/core/buffers_range.hpp] 6632 6633 6634 6635``` 6636template< 6637 class __BufferSequence__> 6638``['implementation-defined]`` 6639buffers_range( 6640 BufferSequence const& buffers); 6641 6642``` 6643 6644[heading Description] 6645This function returns an iterable range representing the passed buffer sequence. The values obtained when iterating the range will be `net::const_buffer`, unless the underlying buffer sequence is a ['MutableBufferSequence], in which case the value obtained when iterating will be a `net::mutable_buffer`. 6646[heading Example] 6647 6648The following function returns the total number of bytes in the specified buffer sequence. A copy of the buffer sequence is maintained for the lifetime of the range object: 6649 6650``` 6651 template <class BufferSequence> 6652 std::size_t buffer_sequence_size (BufferSequence const& buffers) 6653 { 6654 std::size_t size = 0; 6655 for (auto const buffer : buffers_range (buffers)) 6656 size += buffer.size(); 6657 return size; 6658 } 6659``` 6660[heading Parameters] 6661[table [[Name][Description]] 6662 [[`buffers`][ 6663 6664The buffer sequence to adapt into a range. The range object returned from this function will contain a copy of the passed buffer sequence. 6665 ]] 6666] 6667[heading Return Value] 6668An object of unspecified type which meets the requirements of ['ConstBufferSequence]. If `buffers` is a mutable buffer sequence, the returned object will also meet the requirements of ['MutableBufferSequence]. 6669[heading See Also] 6670[link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`] 6671 6672 6673 6674Convenience header [include_file boost/beast/core.hpp] 6675 6676[endsect] 6677[section:boost__beast__buffers_range_ref buffers_range_ref] 6678[indexterm1 buffers_range_ref] 6679Returns an iterable range representing a buffer sequence. 6680[heading Synopsis] 6681 6682Defined in header [include_file boost/beast/core/buffers_range.hpp] 6683 6684 6685 6686``` 6687template< 6688 class __BufferSequence__> 6689``['implementation-defined]`` 6690buffers_range_ref( 6691 BufferSequence const& buffers); 6692 6693``` 6694 6695[heading Description] 6696This function returns an iterable range representing the passed buffer sequence. The values obtained when iterating the range will be `net::const_buffer`, unless the underlying buffer sequence is a ['MutableBufferSequence], in which case the value obtained when iterating will be a `net::mutable_buffer`. 6697[heading Example] 6698 6699The following function returns the total number of bytes in the specified buffer sequence. A reference to the original buffers is maintained for the lifetime of the range object: 6700 6701``` 6702 template <class BufferSequence> 6703 std::size_t buffer_sequence_size_ref (BufferSequence const& buffers) 6704 { 6705 std::size_t size = 0; 6706 for (auto const buffer : buffers_range_ref (buffers)) 6707 size += buffer.size(); 6708 return size; 6709 } 6710``` 6711[heading Parameters] 6712[table [[Name][Description]] 6713 [[`buffers`][ 6714 6715The buffer sequence to adapt into a range. The range returned from this function will maintain a reference to these buffers. The application is responsible for ensuring that the lifetime of the referenced buffers extends until the range object is destroyed. 6716 ]] 6717] 6718[heading Return Value] 6719An object of unspecified type which meets the requirements of ['ConstBufferSequence]. If `buffers` is a mutable buffer sequence, the returned object will also meet the requirements of ['MutableBufferSequence]. 6720[heading See Also] 6721[link beast.ref.boost__beast__buffers_range `buffers_range`] 6722 6723 6724 6725Convenience header [include_file boost/beast/core.hpp] 6726 6727[endsect] 6728[section:boost__beast__buffers_suffix buffers_suffix] 6729Adaptor to progressively trim the front of a ['BufferSequence]. 6730[heading Synopsis] 6731 6732Defined in header [include_file boost/beast/core/buffers_suffix.hpp] 6733 6734 6735 6736``` 6737template< 6738 class __BufferSequence__> 6739class buffers_suffix 6740``` 6741[heading Types] 6742[table [[Name][Description]] 6743 [ 6744 [[link beast.ref.boost__beast__buffers_suffix.const_iterator [*const_iterator]]] 6745 [ 6746 A bidirectional iterator type that may be used to read elements. 6747 ] 6748 ] 6749 [ 6750 [[link beast.ref.boost__beast__buffers_suffix.value_type [*value_type]]] 6751 [ 6752 The type for each element in the list of buffers. 6753 ] 6754 ] 6755] 6756[heading Member Functions] 6757[table [[Name][Description]] 6758 [ 6759 [[link beast.ref.boost__beast__buffers_suffix.begin [*begin]]] 6760 [ 6761 Get a bidirectional iterator to the first element. 6762 ] 6763 ] 6764 [ 6765 [[link beast.ref.boost__beast__buffers_suffix.buffers_suffix [*buffers_suffix]]] 6766 [ 6767 Constructor. 6768 6769 Copy Constructor. 6770 ] 6771 ] 6772 [ 6773 [[link beast.ref.boost__beast__buffers_suffix.consume [*consume]]] 6774 [ 6775 Remove bytes from the beginning of the sequence. 6776 ] 6777 ] 6778 [ 6779 [[link beast.ref.boost__beast__buffers_suffix.end [*end]]] 6780 [ 6781 Get a bidirectional iterator to one past the last element. 6782 ] 6783 ] 6784 [ 6785 [[link beast.ref.boost__beast__buffers_suffix.operator_eq_ [*operator=]]] 6786 [ 6787 Copy Assignment. 6788 ] 6789 ] 6790] 6791 6792[heading Description] 6793This adaptor wraps a buffer sequence to create a new sequence which may be incrementally consumed. Bytes consumed are removed from the front of the buffer. The underlying memory is not changed, instead the adaptor efficiently iterates through a subset of the buffers wrapped. 6794The wrapped buffer is not modified, a copy is made instead. Ownership of the underlying memory is not transferred, the application is still responsible for managing its lifetime. 6795[heading Template Parameters] 6796[table [[Type][Description]] 6797 [[`BufferSequence`][ 6798 6799The buffer sequence to wrap. 6800 ]] 6801] 6802[heading Example] 6803 6804This function writes the entire contents of a buffer sequence to the specified stream. 6805 6806``` 6807 template<class SyncWriteStream, class ConstBufferSequence> 6808 void send(SyncWriteStream& stream, ConstBufferSequence const& buffers) 6809 { 6810 buffers_suffix<ConstBufferSequence> bs{buffers}; 6811 while(buffer_bytes(bs) > 0) 6812 bs.consume(stream.write_some(bs)); 6813 } 6814``` 6815[section:begin buffers_suffix::begin] 6816[indexterm2 begin..buffers_suffix] 6817Get a bidirectional iterator to the first element. 6818[heading Synopsis] 6819``` 6820const_iterator 6821begin() const; 6822``` 6823 6824[heading Description] 6825[endsect] 6826[section:buffers_suffix buffers_suffix::buffers_suffix] 6827[indexterm2 buffers_suffix..buffers_suffix] 6828Constructor. ``` 6829``[link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload1 buffers_suffix]``(); 6830 ``[''''»''' [link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload1 more...]]`` 6831 6832``` 6833Copy Constructor. ``` 6834``[link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload2 buffers_suffix]``( 6835 buffers_suffix const&); 6836 ``[''''»''' [link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload2 more...]]`` 6837 6838explicit 6839``[link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload3 buffers_suffix]``( 6840 BufferSequence const& buffers); 6841 ``[''''»''' [link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload3 more...]]`` 6842 6843template< 6844 class... Args> 6845explicit 6846``[link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload4 buffers_suffix]``( 6847 boost::in_place_init_t, 6848 Args&&... args); 6849 ``[''''»''' [link beast.ref.boost__beast__buffers_suffix.buffers_suffix.overload4 more...]]`` 6850``` 6851[section:overload1 buffers_suffix::buffers_suffix (1 of 4 overloads)] 6852Constructor. 6853[heading Synopsis] 6854``` 6855buffers_suffix(); 6856``` 6857 6858[heading Description] 6859[endsect] 6860[section:overload2 buffers_suffix::buffers_suffix (2 of 4 overloads)] 6861Copy Constructor. 6862[heading Synopsis] 6863``` 6864buffers_suffix( 6865 buffers_suffix const&); 6866``` 6867 6868[heading Description] 6869[endsect] 6870[section:overload3 buffers_suffix::buffers_suffix (3 of 4 overloads)] 6871Constructor. 6872[heading Synopsis] 6873``` 6874buffers_suffix( 6875 BufferSequence const& buffers); 6876``` 6877 6878[heading Description] 6879A copy of the buffer sequence is made. Ownership of the underlying memory is not transferred or copied. [endsect] 6880[section:overload4 buffers_suffix::buffers_suffix (4 of 4 overloads)] 6881Constructor. 6882[heading Synopsis] 6883``` 6884template< 6885 class... Args> 6886buffers_suffix( 6887 boost::in_place_init_t, 6888 Args&&... args); 6889``` 6890 6891[heading Description] 6892This constructs the buffer sequence in-place from a list of arguments. 6893[heading Parameters] 6894[table [[Name][Description]] 6895 [[`args`][ 6896 6897Arguments forwarded to the buffers constructor. 6898 ]] 6899] 6900[endsect] 6901[endsect] 6902 6903[section:const_iterator buffers_suffix::const_iterator] 6904[indexterm2 const_iterator..buffers_suffix] 6905A bidirectional iterator type that may be used to read elements. 6906[heading Synopsis] 6907 6908``` 6909using const_iterator = ``['implementation-defined]``; 6910``` 6911 6912[heading Description] 6913[endsect] 6914[section:consume buffers_suffix::consume] 6915[indexterm2 consume..buffers_suffix] 6916Remove bytes from the beginning of the sequence. 6917[heading Synopsis] 6918``` 6919void 6920consume( 6921 std::size_t amount); 6922``` 6923 6924[heading Description] 6925[heading Parameters] 6926[table [[Name][Description]] 6927 [[`amount`][ 6928 6929The number of bytes to remove. If this is larger than the number of bytes remaining, all the bytes remaining are removed. 6930 ]] 6931] 6932[endsect] 6933[section:end buffers_suffix::end] 6934[indexterm2 end..buffers_suffix] 6935Get a bidirectional iterator to one past the last element. 6936[heading Synopsis] 6937``` 6938const_iterator 6939end() const; 6940``` 6941 6942[heading Description] 6943[endsect] 6944[section:operator_eq_ buffers_suffix::operator=] 6945[indexterm2 operator=..buffers_suffix] 6946Copy Assignment. 6947[heading Synopsis] 6948``` 6949buffers_suffix& 6950operator=( 6951 buffers_suffix const&); 6952``` 6953 6954[heading Description] 6955[endsect] 6956[section:value_type buffers_suffix::value_type] 6957[indexterm2 value_type..buffers_suffix] 6958The type for each element in the list of buffers. 6959[heading Synopsis] 6960 6961``` 6962using value_type = ``['see-below]``; 6963``` 6964 6965[heading Description] 6966If ['BufferSequence] meets the requirements of ['MutableBufferSequence], then this type will be `net::mutable_buffer`, otherwise this type will be `net::const_buffer`. [endsect] 6967 6968 6969 6970Convenience header [include_file boost/beast/core.hpp] 6971 6972[endsect] 6973 6974 6975 6976[section:boost__beast__buffers_to_string buffers_to_string] 6977[indexterm1 buffers_to_string] 6978Return a string representing the contents of a buffer sequence. 6979[heading Synopsis] 6980 6981Defined in header [include_file boost/beast/core/buffers_to_string.hpp] 6982 6983 6984 6985``` 6986template< 6987 class __ConstBufferSequence__> 6988std::string 6989buffers_to_string( 6990 ConstBufferSequence const& buffers); 6991 6992``` 6993 6994[heading Description] 6995This function returns a string representing an entire buffer sequence. Nulls and unprintable characters in the buffer sequence are inserted to the resulting string as-is. No character conversions are performed. 6996[heading Parameters] 6997[table [[Name][Description]] 6998 [[`buffers`][ 6999 7000The buffer sequence to convert 7001 ]] 7002] 7003[heading Example] 7004 7005This function writes a buffer sequence converted to a string to `std::cout`. 7006 7007``` 7008 template<class ConstBufferSequence> 7009 void print(ConstBufferSequence const& buffers) 7010 { 7011 std::cout << buffers_to_string(buffers) << std::endl; 7012 } 7013``` 7014 7015 7016 7017Convenience header [include_file boost/beast/core.hpp] 7018 7019[endsect] 7020[section:boost__beast__buffers_type buffers_type] 7021[indexterm1 buffers_type] 7022Type alias for the underlying buffer type of a list of buffer sequence types. 7023[heading Synopsis] 7024 7025Defined in header [include_file boost/beast/core/buffer_traits.hpp] 7026 7027 7028 7029``` 7030template< 7031 class... __BufferSequence__> 7032using buffers_type = ``['see-below]``; 7033``` 7034 7035[heading Description] 7036This metafunction is used to determine the underlying buffer type for a list of buffer sequence. The equivalent type of the alias will vary depending on the template type argument: 7037 7038* If every type in the list is a ['MutableBufferSequence], the resulting type alias will be `net::mutable_buffer`, otherwise 7039 7040 7041* The resulting type alias will be `net::const_buffer`. 7042 7043[heading Example] 7044The following code returns the first buffer in a buffer sequence, or generates a compilation error if the argument is not a buffer sequence: 7045``` 7046 template <class BufferSequence> 7047 buffers_type <BufferSequence> 7048 buffers_front (BufferSequence const& buffers) 7049 { 7050 static_assert( 7051 net::is_const_buffer_sequence<BufferSequence>::value, 7052 "BufferSequence type requirements not met"); 7053 auto const first = net::buffer_sequence_begin (buffers); 7054 if (first == net::buffer_sequence_end (buffers)) 7055 return {}; 7056 return *first; 7057 } 7058``` 7059[heading Template Parameters] 7060[table [[Type][Description]] 7061 [[`BufferSequence`][ 7062 7063A list of zero or more types to check. If this list is empty, the resulting type alias will be `net::mutable_buffer`. 7064 ]] 7065] 7066 7067 7068 7069Convenience header [include_file boost/beast/core.hpp] 7070 7071[endsect] 7072[section:boost__beast__close_socket close_socket] 7073[indexterm1 close_socket] 7074Close a socket or socket-like object. 7075[heading Synopsis] 7076 7077Defined in header [include_file boost/beast/core/stream_traits.hpp] 7078 7079 7080 7081``` 7082template< 7083 class Socket> 7084void 7085close_socket( 7086 Socket& sock); 7087 7088``` 7089 7090[heading Description] 7091This function attempts to close an object representing a socket. In this context, a socket is an object for which an unqualified call to the function `void beast_close_socket(Socket&)` is well-defined. The function `beast_close_socket` is a ['customization point], allowing user-defined types to provide an algorithm for performing the close operation by overloading this function for the type in question. 7092Since the customization point is a function call, the normal rules for finding the correct overload are applied including the rules for argument-dependent lookup ("ADL"). This permits classes derived from a type for which a customization is provided to inherit the customization point. 7093An overload for the networking class template `net::basic_socket` is provided, which implements the close algorithm for all socket-like objects (hence the name of this customization point). When used in conjunction with [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`], a generic algorithm operating on a layered stream can perform a closure of the underlying socket without knowing the exact list of concrete types. 7094[heading Example 1] 7095The following generic function synchronously sends a message on the stream, then closes the socket. 7096``` 7097 template <class WriteStream> 7098 void hello_and_close (WriteStream& stream) 7099 { 7100 net::write(stream, net::const_buffer("Hello, world!", 13)); 7101 close_socket(get_lowest_layer(stream)); 7102 } 7103``` 7104To enable closure of user defined types, it is necessary to provide an overload of the function `beast_close_socket` for the type. 7105[heading Example 2] 7106The following code declares a user-defined type which contains a private socket, and provides an overload of the customization point which closes the private socket. 7107``` 7108 class my_socket 7109 { 7110 net::ip::tcp::socket sock_; 7111 7112 public: 7113 my_socket(net::io_context& ioc) 7114 : sock_(ioc) 7115 { 7116 } 7117 7118 friend void beast_close_socket(my_socket& s) 7119 { 7120 error_code ec; 7121 s.sock_.close(ec); 7122 // ignore the error 7123 } 7124 }; 7125``` 7126[heading Parameters] 7127[table [[Name][Description]] 7128 [[`sock`][ 7129 7130The socket to close. If the customization point is not defined for the type of this object, or one of its base classes, then a compiler error results. 7131 ]] 7132] 7133[heading See Also] 7134[link beast.ref.boost__beast__beast_close_socket `beast_close_socket`] 7135 7136 7137 7138Convenience header [include_file boost/beast/core.hpp] 7139 7140[endsect] 7141[section:boost__beast__condition condition] 7142[indexterm1 condition] 7143Error conditions corresponding to sets of library error codes. 7144[heading Synopsis] 7145 7146Defined in header [include_file boost/beast/core/error.hpp] 7147 7148 7149``` 7150enum condition 7151``` 7152 7153[indexterm2 timeout..condition] 7154[heading Values] 7155[table [[Name][Description]] 7156 [[[^timeout]][The operation timed out. 7157 7158This error indicates that an operation took took too long. 7159 ]] 7160] 7161 7162[heading Description] 7163 7164 7165 7166Convenience header [include_file boost/beast/core.hpp] 7167 7168[endsect] 7169[section:boost__beast__detect_ssl detect_ssl] 7170[indexterm1 detect_ssl] 7171Detect a TLS client handshake on a stream. 7172[heading Synopsis] 7173 7174Defined in header [include_file boost/beast/core/detect_ssl.hpp] 7175 7176 7177 7178``` 7179template< 7180 class __SyncReadStream__, 7181 class __DynamicBuffer__> 7182bool 7183detect_ssl( 7184 SyncReadStream& stream, 7185 DynamicBuffer& buffer, 7186 error_code& ec); 7187 7188``` 7189 7190[heading Description] 7191This function reads from a stream to determine if a client handshake message is being received. 7192The call blocks until one of the following is true: 7193 7194* A TLS client opening handshake is detected, 7195 7196 7197* The received data is invalid for a TLS client handshake, or 7198 7199 7200* An error occurs. 7201 7202The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` function. 7203Bytes read from the stream will be stored in the passed dynamic buffer, which may be used to perform the TLS handshake if the detector returns true, or be otherwise consumed by the caller based on the expected protocol. 7204[heading Parameters] 7205[table [[Name][Description]] 7206 [[`stream`][ 7207 7208The stream to read from. This type must meet the requirements of ['SyncReadStream]. 7209 ]] 7210 [[`buffer`][ 7211 7212The dynamic buffer to use. This type must meet the requirements of ['DynamicBuffer]. 7213 ]] 7214 [[`ec`][ 7215 7216Set to the error if any occurred. 7217 ]] 7218] 7219[heading Return Value] 7220`true` if the buffer contains a TLS client handshake and no error occurred, otherwise `false`. 7221 7222 7223 7224Convenience header [include_file boost/beast/core.hpp] 7225 7226[endsect] 7227[section:boost__beast__errc errc] 7228[indexterm1 errc] 7229The set of constants used for cross-platform error codes. 7230[heading Synopsis] 7231 7232Defined in header [include_file boost/beast/core/error.hpp] 7233 7234 7235``` 7236enum errc 7237``` 7238 7239[heading Description] 7240 7241 7242 7243Convenience header [include_file boost/beast/core.hpp] 7244 7245[endsect] 7246[section:boost__beast__error error] 7247[indexterm1 error] 7248Error codes returned from library operations. 7249[heading Synopsis] 7250 7251Defined in header [include_file boost/beast/core/error.hpp] 7252 7253 7254``` 7255enum error 7256``` 7257 7258[indexterm2 timeout..error] 7259[heading Values] 7260[table [[Name][Description]] 7261 [[[^timeout]][The socket was closed due to a timeout. 7262 7263This error indicates that a socket was closed due to a 7264a timeout detected during an operation. 7265 7266Error codes with this value will compare equal to @ref condition::timeout. 7267 ]] 7268] 7269 7270[heading Description] 7271 7272 7273 7274Convenience header [include_file boost/beast/core.hpp] 7275 7276[endsect] 7277[section:boost__beast__error_category error_category] 7278[indexterm1 error_category] 7279The type of error category used by the library. 7280[heading Synopsis] 7281 7282Defined in header [include_file boost/beast/core/error.hpp] 7283 7284 7285 7286``` 7287using error_category = boost::system::error_category; 7288``` 7289 7290[heading Description] 7291 7292 7293 7294Convenience header [include_file boost/beast/core.hpp] 7295 7296[endsect] 7297[section:boost__beast__error_code error_code] 7298[indexterm1 error_code] 7299The type of error code used by the library. 7300[heading Synopsis] 7301 7302Defined in header [include_file boost/beast/core/error.hpp] 7303 7304 7305 7306``` 7307using error_code = boost::system::error_code; 7308``` 7309 7310[heading Description] 7311 7312 7313 7314Convenience header [include_file boost/beast/core.hpp] 7315 7316[endsect] 7317[section:boost__beast__error_condition error_condition] 7318[indexterm1 error_condition] 7319The type of error condition used by the library. 7320[heading Synopsis] 7321 7322Defined in header [include_file boost/beast/core/error.hpp] 7323 7324 7325 7326``` 7327using error_condition = boost::system::error_condition; 7328``` 7329 7330[heading Description] 7331 7332 7333 7334Convenience header [include_file boost/beast/core.hpp] 7335 7336[endsect] 7337[section:boost__beast__executor_type executor_type] 7338[indexterm1 executor_type] 7339A trait to determine the return type of get\_executor. 7340[heading Synopsis] 7341 7342Defined in header [include_file boost/beast/core/stream_traits.hpp] 7343 7344 7345 7346``` 7347template< 7348 class T> 7349using executor_type = ``['see-below]``; 7350``` 7351 7352[heading Description] 7353This type alias will be the type of values returned by by calling member `get_exector` on an object of type `T&`. 7354[heading Parameters] 7355[table [[Name][Description]] 7356 [[`T`][ 7357 7358The type to query 7359 ]] 7360] 7361[heading Return Value] 7362The type of values returned from `get_executor`. 7363 7364 7365 7366Convenience header [include_file boost/beast/core.hpp] 7367 7368[endsect] 7369[section:boost__beast__file file] 7370An implementation of File. 7371[heading Synopsis] 7372 7373Defined in header [include_file boost/beast/core/file.hpp] 7374 7375 7376 7377``` 7378struct file : 7379 public file_stdio 7380``` 7381[heading Types] 7382[table [[Name][Description]] 7383 [ 7384 [[link beast.ref.boost__beast__file.native_handle_type [*native_handle_type]]] 7385 [ 7386 The type of the underlying file handle. 7387 ] 7388 ] 7389] 7390[heading Member Functions] 7391[table [[Name][Description]] 7392 [ 7393 [[link beast.ref.boost__beast__file.close [*close]]] 7394 [ 7395 Close the file if open. 7396 ] 7397 ] 7398 [ 7399 [[link beast.ref.boost__beast__file.is_open [*is_open]]] 7400 [ 7401 Returns true if the file is open. 7402 ] 7403 ] 7404 [ 7405 [[link beast.ref.boost__beast__file.native_handle [*native_handle]]] 7406 [ 7407 Returns the native handle associated with the file. 7408 7409 Set the native handle associated with the file. 7410 ] 7411 ] 7412 [ 7413 [[link beast.ref.boost__beast__file.open [*open]]] 7414 [ 7415 Open a file at the given path with the specified mode. 7416 ] 7417 ] 7418 [ 7419 [[link beast.ref.boost__beast__file.pos [*pos]]] 7420 [ 7421 Return the current position in the open file. 7422 ] 7423 ] 7424 [ 7425 [[link beast.ref.boost__beast__file.read [*read]]] 7426 [ 7427 Read from the open file. 7428 ] 7429 ] 7430 [ 7431 [[link beast.ref.boost__beast__file.seek [*seek]]] 7432 [ 7433 Adjust the current position in the open file. 7434 ] 7435 ] 7436 [ 7437 [[link beast.ref.boost__beast__file.size [*size]]] 7438 [ 7439 Return the size of the open file. 7440 ] 7441 ] 7442 [ 7443 [[link beast.ref.boost__beast__file.write [*write]]] 7444 [ 7445 Write to the open file. 7446 ] 7447 ] 7448] 7449 7450[heading Description] 7451This alias is set to the best available implementation of ['File] given the platform and build settings. [section:close file::close] 7452(Inherited from `file_stdio`) 7453 7454[indexterm2 close..file] 7455Close the file if open. 7456[heading Synopsis] 7457``` 7458void 7459close( 7460 error_code& ec); 7461``` 7462 7463[heading Description] 7464[heading Parameters] 7465[table [[Name][Description]] 7466 [[`ec`][ 7467 7468Set to the error, if any occurred. 7469 ]] 7470] 7471[endsect] 7472[section:is_open file::is_open] 7473(Inherited from `file_stdio`) 7474 7475[indexterm2 is_open..file] 7476Returns `true` if the file is open. 7477[heading Synopsis] 7478``` 7479bool 7480is_open() const; 7481``` 7482 7483[heading Description] 7484[endsect] 7485[section:native_handle file::native_handle] 7486[indexterm2 native_handle..file] 7487Returns the native handle associated with the file. ``` 7488FILE* 7489``[link beast.ref.boost__beast__file.native_handle.overload1 native_handle]``() const; 7490 ``[''''»''' [link beast.ref.boost__beast__file.native_handle.overload1 more...]]`` 7491 7492``` 7493Set the native handle associated with the file. ``` 7494void 7495``[link beast.ref.boost__beast__file.native_handle.overload2 native_handle]``( 7496 FILE* f); 7497 ``[''''»''' [link beast.ref.boost__beast__file.native_handle.overload2 more...]]`` 7498``` 7499[section:overload1 file::native_handle (1 of 2 overloads)] 7500(Inherited from `file_stdio`) 7501 7502Returns the native handle associated with the file. 7503[heading Synopsis] 7504``` 7505FILE* 7506native_handle() const; 7507``` 7508 7509[heading Description] 7510[endsect] 7511[section:overload2 file::native_handle (2 of 2 overloads)] 7512(Inherited from `file_stdio`) 7513 7514Set the native handle associated with the file. 7515[heading Synopsis] 7516``` 7517void 7518native_handle( 7519 FILE* f); 7520``` 7521 7522[heading Description] 7523If the file is open it is first closed. 7524[heading Parameters] 7525[table [[Name][Description]] 7526 [[`f`][ 7527 7528The native file handle to assign. 7529 ]] 7530] 7531[endsect] 7532[endsect] 7533 7534[section:native_handle_type file::native_handle_type] 7535(Inherited from `file_stdio`) 7536 7537[indexterm2 native_handle_type..file] 7538The type of the underlying file handle. 7539[heading Synopsis] 7540 7541``` 7542using native_handle_type = FILE*; 7543``` 7544 7545[heading Description] 7546This is platform-specific. [endsect] 7547[section:open file::open] 7548(Inherited from `file_stdio`) 7549 7550[indexterm2 open..file] 7551Open a file at the given path with the specified mode. 7552[heading Synopsis] 7553``` 7554void 7555open( 7556 char const* path, 7557 file_mode mode, 7558 error_code& ec); 7559``` 7560 7561[heading Description] 7562[heading Parameters] 7563[table [[Name][Description]] 7564 [[`path`][ 7565 7566The utf-8 encoded path to the file 7567 ]] 7568 [[`mode`][ 7569 7570The file mode to use 7571 ]] 7572 [[`ec`][ 7573 7574Set to the error, if any occurred 7575 ]] 7576] 7577[endsect] 7578[section:pos file::pos] 7579(Inherited from `file_stdio`) 7580 7581[indexterm2 pos..file] 7582Return the current position in the open file. 7583[heading Synopsis] 7584``` 7585std::uint64_t 7586pos( 7587 error_code& ec) const; 7588``` 7589 7590[heading Description] 7591[heading Parameters] 7592[table [[Name][Description]] 7593 [[`ec`][ 7594 7595Set to the error, if any occurred 7596 ]] 7597] 7598[heading Return Value] 7599The offset in bytes from the beginning of the file 7600[endsect] 7601[section:read file::read] 7602(Inherited from `file_stdio`) 7603 7604[indexterm2 read..file] 7605Read from the open file. 7606[heading Synopsis] 7607``` 7608std::size_t 7609read( 7610 void* buffer, 7611 std::size_t n, 7612 error_code& ec) const; 7613``` 7614 7615[heading Description] 7616[heading Parameters] 7617[table [[Name][Description]] 7618 [[`buffer`][ 7619 7620The buffer for storing the result of the read 7621 ]] 7622 [[`n`][ 7623 7624The number of bytes to read 7625 ]] 7626 [[`ec`][ 7627 7628Set to the error, if any occurred 7629 ]] 7630] 7631[endsect] 7632[section:seek file::seek] 7633(Inherited from `file_stdio`) 7634 7635[indexterm2 seek..file] 7636Adjust the current position in the open file. 7637[heading Synopsis] 7638``` 7639void 7640seek( 7641 std::uint64_t offset, 7642 error_code& ec); 7643``` 7644 7645[heading Description] 7646[heading Parameters] 7647[table [[Name][Description]] 7648 [[`offset`][ 7649 7650The offset in bytes from the beginning of the file 7651 ]] 7652 [[`ec`][ 7653 7654Set to the error, if any occurred 7655 ]] 7656] 7657[endsect] 7658[section:size file::size] 7659(Inherited from `file_stdio`) 7660 7661[indexterm2 size..file] 7662Return the size of the open file. 7663[heading Synopsis] 7664``` 7665std::uint64_t 7666size( 7667 error_code& ec) const; 7668``` 7669 7670[heading Description] 7671[heading Parameters] 7672[table [[Name][Description]] 7673 [[`ec`][ 7674 7675Set to the error, if any occurred 7676 ]] 7677] 7678[heading Return Value] 7679The size in bytes 7680[endsect] 7681[section:write file::write] 7682(Inherited from `file_stdio`) 7683 7684[indexterm2 write..file] 7685Write to the open file. 7686[heading Synopsis] 7687``` 7688std::size_t 7689write( 7690 void const* buffer, 7691 std::size_t n, 7692 error_code& ec); 7693``` 7694 7695[heading Description] 7696[heading Parameters] 7697[table [[Name][Description]] 7698 [[`buffer`][ 7699 7700The buffer holding the data to write 7701 ]] 7702 [[`n`][ 7703 7704The number of bytes to write 7705 ]] 7706 [[`ec`][ 7707 7708Set to the error, if any occurred 7709 ]] 7710] 7711[endsect] 7712 7713 7714 7715Convenience header [include_file boost/beast/core.hpp] 7716 7717[endsect] 7718 7719 7720 7721[section:boost__beast__file_mode file_mode] 7722[indexterm1 file_mode] 7723File open modes. 7724[heading Synopsis] 7725 7726Defined in header [include_file boost/beast/core/file_base.hpp] 7727 7728 7729``` 7730enum file_mode 7731``` 7732 7733[indexterm2 read..file_mode] 7734[indexterm2 scan..file_mode] 7735[indexterm2 write..file_mode] 7736[indexterm2 write_new..file_mode] 7737[indexterm2 write_existing..file_mode] 7738[indexterm2 append..file_mode] 7739[indexterm2 append_existing..file_mode] 7740[heading Values] 7741[table [[Name][Description]] 7742 [[[^read]][Random read-only access to an existing file. 7743 7744]] 7745 [[[^scan]][Sequential read-only access to an existing file. 7746 7747]] 7748 [[[^write]][Random reading and writing to a new or truncated file. 7749 7750This mode permits random-access reading and writing 7751for the specified file. If the file does not exist 7752prior to the function call, it is created with an 7753initial size of zero bytes. Otherwise if the file 7754already exists, the size is truncated to zero bytes. 7755 ]] 7756 [[[^write_new]][Random reading and writing to a new file only. 7757 7758This mode permits random-access reading and writing 7759for the specified file. The file will be created with 7760an initial size of zero bytes. If the file already exists 7761prior to the function call, an error is returned and 7762no file is opened. 7763 ]] 7764 [[[^write_existing]][Random write-only access to existing file. 7765 7766If the file does not exist, an error is generated. 7767 ]] 7768 [[[^append]][Appending to a new or truncated file. 7769 7770The current file position shall be set to the end of 7771the file prior to each write. 7772 7773@li If the file does not exist, it is created. 7774 7775@li If the file exists, it is truncated to 7776zero size upon opening. 7777 ]] 7778 [[[^append_existing]][Appending to an existing file. 7779 7780The current file position shall be set to the end of 7781the file prior to each write. 7782 7783If the file does not exist, an error is generated. 7784 ]] 7785] 7786 7787[heading Description] 7788These modes are used when opening files using instances of the ['File] concept. 7789[heading See Also] 7790[link beast.ref.boost__beast__file_stdio `file_stdio`] 7791 7792 7793 7794Convenience header [include_file boost/beast/core.hpp] 7795 7796[endsect] 7797[section:boost__beast__file_posix file_posix] 7798An implementation of File for POSIX systems. 7799[heading Synopsis] 7800 7801Defined in header [include_file boost/beast/core/file_posix.hpp] 7802 7803 7804 7805``` 7806class file_posix 7807``` 7808[heading Types] 7809[table [[Name][Description]] 7810 [ 7811 [[link beast.ref.boost__beast__file_posix.native_handle_type [*native_handle_type]]] 7812 [ 7813 The type of the underlying file handle. 7814 ] 7815 ] 7816] 7817[heading Member Functions] 7818[table [[Name][Description]] 7819 [ 7820 [[link beast.ref.boost__beast__file_posix.close [*close]]] 7821 [ 7822 Close the file if open. 7823 ] 7824 ] 7825 [ 7826 [[link beast.ref.boost__beast__file_posix.file_posix [*file_posix]]] 7827 [ 7828 Constructor. 7829 ] 7830 ] 7831 [ 7832 [[link beast.ref.boost__beast__file_posix.is_open [*is_open]]] 7833 [ 7834 Returns true if the file is open. 7835 ] 7836 ] 7837 [ 7838 [[link beast.ref.boost__beast__file_posix.native_handle [*native_handle]]] 7839 [ 7840 Returns the native handle associated with the file. 7841 7842 Set the native handle associated with the file. 7843 ] 7844 ] 7845 [ 7846 [[link beast.ref.boost__beast__file_posix.open [*open]]] 7847 [ 7848 Open a file at the given path with the specified mode. 7849 ] 7850 ] 7851 [ 7852 [[link beast.ref.boost__beast__file_posix.operator_eq_ [*operator=]]] 7853 [ 7854 Assignment. 7855 ] 7856 ] 7857 [ 7858 [[link beast.ref.boost__beast__file_posix.pos [*pos]]] 7859 [ 7860 Return the current position in the open file. 7861 ] 7862 ] 7863 [ 7864 [[link beast.ref.boost__beast__file_posix.read [*read]]] 7865 [ 7866 Read from the open file. 7867 ] 7868 ] 7869 [ 7870 [[link beast.ref.boost__beast__file_posix.seek [*seek]]] 7871 [ 7872 Adjust the current position in the open file. 7873 ] 7874 ] 7875 [ 7876 [[link beast.ref.boost__beast__file_posix.size [*size]]] 7877 [ 7878 Return the size of the open file. 7879 ] 7880 ] 7881 [ 7882 [[link beast.ref.boost__beast__file_posix.write [*write]]] 7883 [ 7884 Write to the open file. 7885 ] 7886 ] 7887 [ 7888 [[link beast.ref.boost__beast__file_posix.file_posix_dtor_ [*~file_posix]]] 7889 [ 7890 Destructor. 7891 ] 7892 ] 7893] 7894 7895[heading Description] 7896This class implements a ['File] using POSIX interfaces. [section:close file_posix::close] 7897[indexterm2 close..file_posix] 7898Close the file if open. 7899[heading Synopsis] 7900``` 7901void 7902close( 7903 error_code& ec); 7904``` 7905 7906[heading Description] 7907[heading Parameters] 7908[table [[Name][Description]] 7909 [[`ec`][ 7910 7911Set to the error, if any occurred. 7912 ]] 7913] 7914[endsect] 7915[section:file_posix file_posix::file_posix] 7916[indexterm2 file_posix..file_posix] 7917Constructor. ``` 7918``[link beast.ref.boost__beast__file_posix.file_posix.overload1 file_posix]``(); 7919 ``[''''»''' [link beast.ref.boost__beast__file_posix.file_posix.overload1 more...]]`` 7920 7921``[link beast.ref.boost__beast__file_posix.file_posix.overload2 file_posix]``( 7922 file_posix&& other); 7923 ``[''''»''' [link beast.ref.boost__beast__file_posix.file_posix.overload2 more...]]`` 7924``` 7925[section:overload1 file_posix::file_posix (1 of 2 overloads)] 7926Constructor. 7927[heading Synopsis] 7928``` 7929file_posix(); 7930``` 7931 7932[heading Description] 7933There is no open file initially. [endsect] 7934[section:overload2 file_posix::file_posix (2 of 2 overloads)] 7935Constructor. 7936[heading Synopsis] 7937``` 7938file_posix( 7939 file_posix&& other); 7940``` 7941 7942[heading Description] 7943The moved-from object behaves as if default constructed. [endsect] 7944[endsect] 7945 7946[section:is_open file_posix::is_open] 7947[indexterm2 is_open..file_posix] 7948Returns `true` if the file is open. 7949[heading Synopsis] 7950``` 7951bool 7952is_open() const; 7953``` 7954 7955[heading Description] 7956[endsect] 7957[section:native_handle file_posix::native_handle] 7958[indexterm2 native_handle..file_posix] 7959Returns the native handle associated with the file. ``` 7960native_handle_type 7961``[link beast.ref.boost__beast__file_posix.native_handle.overload1 native_handle]``() const; 7962 ``[''''»''' [link beast.ref.boost__beast__file_posix.native_handle.overload1 more...]]`` 7963 7964``` 7965Set the native handle associated with the file. ``` 7966void 7967``[link beast.ref.boost__beast__file_posix.native_handle.overload2 native_handle]``( 7968 native_handle_type fd); 7969 ``[''''»''' [link beast.ref.boost__beast__file_posix.native_handle.overload2 more...]]`` 7970``` 7971[section:overload1 file_posix::native_handle (1 of 2 overloads)] 7972Returns the native handle associated with the file. 7973[heading Synopsis] 7974``` 7975native_handle_type 7976native_handle() const; 7977``` 7978 7979[heading Description] 7980[endsect] 7981[section:overload2 file_posix::native_handle (2 of 2 overloads)] 7982Set the native handle associated with the file. 7983[heading Synopsis] 7984``` 7985void 7986native_handle( 7987 native_handle_type fd); 7988``` 7989 7990[heading Description] 7991If the file is open it is first closed. 7992[heading Parameters] 7993[table [[Name][Description]] 7994 [[`fd`][ 7995 7996The native file handle to assign. 7997 ]] 7998] 7999[endsect] 8000[endsect] 8001 8002[section:native_handle_type file_posix::native_handle_type] 8003[indexterm2 native_handle_type..file_posix] 8004The type of the underlying file handle. 8005[heading Synopsis] 8006 8007``` 8008using native_handle_type = int; 8009``` 8010 8011[heading Description] 8012This is platform-specific. [endsect] 8013[section:open file_posix::open] 8014[indexterm2 open..file_posix] 8015Open a file at the given path with the specified mode. 8016[heading Synopsis] 8017``` 8018void 8019open( 8020 char const* path, 8021 file_mode mode, 8022 error_code& ec); 8023``` 8024 8025[heading Description] 8026[heading Parameters] 8027[table [[Name][Description]] 8028 [[`path`][ 8029 8030The utf-8 encoded path to the file 8031 ]] 8032 [[`mode`][ 8033 8034The file mode to use 8035 ]] 8036 [[`ec`][ 8037 8038Set to the error, if any occurred 8039 ]] 8040] 8041[endsect] 8042[section:operator_eq_ file_posix::operator=] 8043[indexterm2 operator=..file_posix] 8044Assignment. 8045[heading Synopsis] 8046``` 8047file_posix& 8048operator=( 8049 file_posix&& other); 8050``` 8051 8052[heading Description] 8053The moved-from object behaves as if default constructed. [endsect] 8054[section:pos file_posix::pos] 8055[indexterm2 pos..file_posix] 8056Return the current position in the open file. 8057[heading Synopsis] 8058``` 8059std::uint64_t 8060pos( 8061 error_code& ec) const; 8062``` 8063 8064[heading Description] 8065[heading Parameters] 8066[table [[Name][Description]] 8067 [[`ec`][ 8068 8069Set to the error, if any occurred 8070 ]] 8071] 8072[heading Return Value] 8073The offset in bytes from the beginning of the file 8074[endsect] 8075[section:read file_posix::read] 8076[indexterm2 read..file_posix] 8077Read from the open file. 8078[heading Synopsis] 8079``` 8080std::size_t 8081read( 8082 void* buffer, 8083 std::size_t n, 8084 error_code& ec) const; 8085``` 8086 8087[heading Description] 8088[heading Parameters] 8089[table [[Name][Description]] 8090 [[`buffer`][ 8091 8092The buffer for storing the result of the read 8093 ]] 8094 [[`n`][ 8095 8096The number of bytes to read 8097 ]] 8098 [[`ec`][ 8099 8100Set to the error, if any occurred 8101 ]] 8102] 8103[endsect] 8104[section:seek file_posix::seek] 8105[indexterm2 seek..file_posix] 8106Adjust the current position in the open file. 8107[heading Synopsis] 8108``` 8109void 8110seek( 8111 std::uint64_t offset, 8112 error_code& ec); 8113``` 8114 8115[heading Description] 8116[heading Parameters] 8117[table [[Name][Description]] 8118 [[`offset`][ 8119 8120The offset in bytes from the beginning of the file 8121 ]] 8122 [[`ec`][ 8123 8124Set to the error, if any occurred 8125 ]] 8126] 8127[endsect] 8128[section:size file_posix::size] 8129[indexterm2 size..file_posix] 8130Return the size of the open file. 8131[heading Synopsis] 8132``` 8133std::uint64_t 8134size( 8135 error_code& ec) const; 8136``` 8137 8138[heading Description] 8139[heading Parameters] 8140[table [[Name][Description]] 8141 [[`ec`][ 8142 8143Set to the error, if any occurred 8144 ]] 8145] 8146[heading Return Value] 8147The size in bytes 8148[endsect] 8149[section:write file_posix::write] 8150[indexterm2 write..file_posix] 8151Write to the open file. 8152[heading Synopsis] 8153``` 8154std::size_t 8155write( 8156 void const* buffer, 8157 std::size_t n, 8158 error_code& ec); 8159``` 8160 8161[heading Description] 8162[heading Parameters] 8163[table [[Name][Description]] 8164 [[`buffer`][ 8165 8166The buffer holding the data to write 8167 ]] 8168 [[`n`][ 8169 8170The number of bytes to write 8171 ]] 8172 [[`ec`][ 8173 8174Set to the error, if any occurred 8175 ]] 8176] 8177[endsect] 8178[section:file_posix_dtor_ file_posix::~file_posix] 8179[indexterm2 ~file_posix..file_posix] 8180Destructor. 8181[heading Synopsis] 8182``` 8183~file_posix(); 8184``` 8185 8186[heading Description] 8187If the file is open it is first closed. [endsect] 8188 8189 8190 8191Convenience header [include_file boost/beast/core.hpp] 8192 8193[endsect] 8194 8195 8196 8197[section:boost__beast__file_stdio file_stdio] 8198An implementation of File which uses cstdio. 8199[heading Synopsis] 8200 8201Defined in header [include_file boost/beast/core/file_stdio.hpp] 8202 8203 8204 8205``` 8206class file_stdio 8207``` 8208[heading Types] 8209[table [[Name][Description]] 8210 [ 8211 [[link beast.ref.boost__beast__file_stdio.native_handle_type [*native_handle_type]]] 8212 [ 8213 The type of the underlying file handle. 8214 ] 8215 ] 8216] 8217[heading Member Functions] 8218[table [[Name][Description]] 8219 [ 8220 [[link beast.ref.boost__beast__file_stdio.close [*close]]] 8221 [ 8222 Close the file if open. 8223 ] 8224 ] 8225 [ 8226 [[link beast.ref.boost__beast__file_stdio.file_stdio [*file_stdio]]] 8227 [ 8228 Constructor. 8229 ] 8230 ] 8231 [ 8232 [[link beast.ref.boost__beast__file_stdio.is_open [*is_open]]] 8233 [ 8234 Returns true if the file is open. 8235 ] 8236 ] 8237 [ 8238 [[link beast.ref.boost__beast__file_stdio.native_handle [*native_handle]]] 8239 [ 8240 Returns the native handle associated with the file. 8241 8242 Set the native handle associated with the file. 8243 ] 8244 ] 8245 [ 8246 [[link beast.ref.boost__beast__file_stdio.open [*open]]] 8247 [ 8248 Open a file at the given path with the specified mode. 8249 ] 8250 ] 8251 [ 8252 [[link beast.ref.boost__beast__file_stdio.operator_eq_ [*operator=]]] 8253 [ 8254 Assignment. 8255 ] 8256 ] 8257 [ 8258 [[link beast.ref.boost__beast__file_stdio.pos [*pos]]] 8259 [ 8260 Return the current position in the open file. 8261 ] 8262 ] 8263 [ 8264 [[link beast.ref.boost__beast__file_stdio.read [*read]]] 8265 [ 8266 Read from the open file. 8267 ] 8268 ] 8269 [ 8270 [[link beast.ref.boost__beast__file_stdio.seek [*seek]]] 8271 [ 8272 Adjust the current position in the open file. 8273 ] 8274 ] 8275 [ 8276 [[link beast.ref.boost__beast__file_stdio.size [*size]]] 8277 [ 8278 Return the size of the open file. 8279 ] 8280 ] 8281 [ 8282 [[link beast.ref.boost__beast__file_stdio.write [*write]]] 8283 [ 8284 Write to the open file. 8285 ] 8286 ] 8287 [ 8288 [[link beast.ref.boost__beast__file_stdio.file_stdio_dtor_ [*~file_stdio]]] 8289 [ 8290 Destructor. 8291 ] 8292 ] 8293] 8294 8295[heading Description] 8296This class implements a file using the interfaces present in the C++ Standard Library, in `<stdio>`. [section:close file_stdio::close] 8297[indexterm2 close..file_stdio] 8298Close the file if open. 8299[heading Synopsis] 8300``` 8301void 8302close( 8303 error_code& ec); 8304``` 8305 8306[heading Description] 8307[heading Parameters] 8308[table [[Name][Description]] 8309 [[`ec`][ 8310 8311Set to the error, if any occurred. 8312 ]] 8313] 8314[endsect] 8315[section:file_stdio file_stdio::file_stdio] 8316[indexterm2 file_stdio..file_stdio] 8317Constructor. ``` 8318``[link beast.ref.boost__beast__file_stdio.file_stdio.overload1 file_stdio]``(); 8319 ``[''''»''' [link beast.ref.boost__beast__file_stdio.file_stdio.overload1 more...]]`` 8320 8321``[link beast.ref.boost__beast__file_stdio.file_stdio.overload2 file_stdio]``( 8322 file_stdio&& other); 8323 ``[''''»''' [link beast.ref.boost__beast__file_stdio.file_stdio.overload2 more...]]`` 8324``` 8325[section:overload1 file_stdio::file_stdio (1 of 2 overloads)] 8326Constructor. 8327[heading Synopsis] 8328``` 8329file_stdio(); 8330``` 8331 8332[heading Description] 8333There is no open file initially. [endsect] 8334[section:overload2 file_stdio::file_stdio (2 of 2 overloads)] 8335Constructor. 8336[heading Synopsis] 8337``` 8338file_stdio( 8339 file_stdio&& other); 8340``` 8341 8342[heading Description] 8343The moved-from object behaves as if default constructed. [endsect] 8344[endsect] 8345 8346[section:is_open file_stdio::is_open] 8347[indexterm2 is_open..file_stdio] 8348Returns `true` if the file is open. 8349[heading Synopsis] 8350``` 8351bool 8352is_open() const; 8353``` 8354 8355[heading Description] 8356[endsect] 8357[section:native_handle file_stdio::native_handle] 8358[indexterm2 native_handle..file_stdio] 8359Returns the native handle associated with the file. ``` 8360FILE* 8361``[link beast.ref.boost__beast__file_stdio.native_handle.overload1 native_handle]``() const; 8362 ``[''''»''' [link beast.ref.boost__beast__file_stdio.native_handle.overload1 more...]]`` 8363 8364``` 8365Set the native handle associated with the file. ``` 8366void 8367``[link beast.ref.boost__beast__file_stdio.native_handle.overload2 native_handle]``( 8368 FILE* f); 8369 ``[''''»''' [link beast.ref.boost__beast__file_stdio.native_handle.overload2 more...]]`` 8370``` 8371[section:overload1 file_stdio::native_handle (1 of 2 overloads)] 8372Returns the native handle associated with the file. 8373[heading Synopsis] 8374``` 8375FILE* 8376native_handle() const; 8377``` 8378 8379[heading Description] 8380[endsect] 8381[section:overload2 file_stdio::native_handle (2 of 2 overloads)] 8382Set the native handle associated with the file. 8383[heading Synopsis] 8384``` 8385void 8386native_handle( 8387 FILE* f); 8388``` 8389 8390[heading Description] 8391If the file is open it is first closed. 8392[heading Parameters] 8393[table [[Name][Description]] 8394 [[`f`][ 8395 8396The native file handle to assign. 8397 ]] 8398] 8399[endsect] 8400[endsect] 8401 8402[section:native_handle_type file_stdio::native_handle_type] 8403[indexterm2 native_handle_type..file_stdio] 8404The type of the underlying file handle. 8405[heading Synopsis] 8406 8407``` 8408using native_handle_type = FILE*; 8409``` 8410 8411[heading Description] 8412This is platform-specific. [endsect] 8413[section:open file_stdio::open] 8414[indexterm2 open..file_stdio] 8415Open a file at the given path with the specified mode. 8416[heading Synopsis] 8417``` 8418void 8419open( 8420 char const* path, 8421 file_mode mode, 8422 error_code& ec); 8423``` 8424 8425[heading Description] 8426[heading Parameters] 8427[table [[Name][Description]] 8428 [[`path`][ 8429 8430The utf-8 encoded path to the file 8431 ]] 8432 [[`mode`][ 8433 8434The file mode to use 8435 ]] 8436 [[`ec`][ 8437 8438Set to the error, if any occurred 8439 ]] 8440] 8441[endsect] 8442[section:operator_eq_ file_stdio::operator=] 8443[indexterm2 operator=..file_stdio] 8444Assignment. 8445[heading Synopsis] 8446``` 8447file_stdio& 8448operator=( 8449 file_stdio&& other); 8450``` 8451 8452[heading Description] 8453The moved-from object behaves as if default constructed. [endsect] 8454[section:pos file_stdio::pos] 8455[indexterm2 pos..file_stdio] 8456Return the current position in the open file. 8457[heading Synopsis] 8458``` 8459std::uint64_t 8460pos( 8461 error_code& ec) const; 8462``` 8463 8464[heading Description] 8465[heading Parameters] 8466[table [[Name][Description]] 8467 [[`ec`][ 8468 8469Set to the error, if any occurred 8470 ]] 8471] 8472[heading Return Value] 8473The offset in bytes from the beginning of the file 8474[endsect] 8475[section:read file_stdio::read] 8476[indexterm2 read..file_stdio] 8477Read from the open file. 8478[heading Synopsis] 8479``` 8480std::size_t 8481read( 8482 void* buffer, 8483 std::size_t n, 8484 error_code& ec) const; 8485``` 8486 8487[heading Description] 8488[heading Parameters] 8489[table [[Name][Description]] 8490 [[`buffer`][ 8491 8492The buffer for storing the result of the read 8493 ]] 8494 [[`n`][ 8495 8496The number of bytes to read 8497 ]] 8498 [[`ec`][ 8499 8500Set to the error, if any occurred 8501 ]] 8502] 8503[endsect] 8504[section:seek file_stdio::seek] 8505[indexterm2 seek..file_stdio] 8506Adjust the current position in the open file. 8507[heading Synopsis] 8508``` 8509void 8510seek( 8511 std::uint64_t offset, 8512 error_code& ec); 8513``` 8514 8515[heading Description] 8516[heading Parameters] 8517[table [[Name][Description]] 8518 [[`offset`][ 8519 8520The offset in bytes from the beginning of the file 8521 ]] 8522 [[`ec`][ 8523 8524Set to the error, if any occurred 8525 ]] 8526] 8527[endsect] 8528[section:size file_stdio::size] 8529[indexterm2 size..file_stdio] 8530Return the size of the open file. 8531[heading Synopsis] 8532``` 8533std::uint64_t 8534size( 8535 error_code& ec) const; 8536``` 8537 8538[heading Description] 8539[heading Parameters] 8540[table [[Name][Description]] 8541 [[`ec`][ 8542 8543Set to the error, if any occurred 8544 ]] 8545] 8546[heading Return Value] 8547The size in bytes 8548[endsect] 8549[section:write file_stdio::write] 8550[indexterm2 write..file_stdio] 8551Write to the open file. 8552[heading Synopsis] 8553``` 8554std::size_t 8555write( 8556 void const* buffer, 8557 std::size_t n, 8558 error_code& ec); 8559``` 8560 8561[heading Description] 8562[heading Parameters] 8563[table [[Name][Description]] 8564 [[`buffer`][ 8565 8566The buffer holding the data to write 8567 ]] 8568 [[`n`][ 8569 8570The number of bytes to write 8571 ]] 8572 [[`ec`][ 8573 8574Set to the error, if any occurred 8575 ]] 8576] 8577[endsect] 8578[section:file_stdio_dtor_ file_stdio::~file_stdio] 8579[indexterm2 ~file_stdio..file_stdio] 8580Destructor. 8581[heading Synopsis] 8582``` 8583~file_stdio(); 8584``` 8585 8586[heading Description] 8587If the file is open it is first closed. [endsect] 8588 8589 8590 8591Convenience header [include_file boost/beast/core.hpp] 8592 8593[endsect] 8594 8595 8596 8597[section:boost__beast__file_win32 file_win32] 8598An implementation of File for Win32. 8599[heading Synopsis] 8600 8601Defined in header [include_file boost/beast/core/file_win32.hpp] 8602 8603 8604 8605``` 8606class file_win32 8607``` 8608[heading Types] 8609[table [[Name][Description]] 8610 [ 8611 [[link beast.ref.boost__beast__file_win32.native_handle_type [*native_handle_type]]] 8612 [ 8613 The type of the underlying file handle. 8614 ] 8615 ] 8616] 8617[heading Member Functions] 8618[table [[Name][Description]] 8619 [ 8620 [[link beast.ref.boost__beast__file_win32.close [*close]]] 8621 [ 8622 Close the file if open. 8623 ] 8624 ] 8625 [ 8626 [[link beast.ref.boost__beast__file_win32.file_win32 [*file_win32]]] 8627 [ 8628 Constructor. 8629 ] 8630 ] 8631 [ 8632 [[link beast.ref.boost__beast__file_win32.is_open [*is_open]]] 8633 [ 8634 Returns true if the file is open. 8635 ] 8636 ] 8637 [ 8638 [[link beast.ref.boost__beast__file_win32.native_handle [*native_handle]]] 8639 [ 8640 Returns the native handle associated with the file. 8641 8642 Set the native handle associated with the file. 8643 ] 8644 ] 8645 [ 8646 [[link beast.ref.boost__beast__file_win32.open [*open]]] 8647 [ 8648 Open a file at the given path with the specified mode. 8649 ] 8650 ] 8651 [ 8652 [[link beast.ref.boost__beast__file_win32.operator_eq_ [*operator=]]] 8653 [ 8654 Assignment. 8655 ] 8656 ] 8657 [ 8658 [[link beast.ref.boost__beast__file_win32.pos [*pos]]] 8659 [ 8660 Return the current position in the open file. 8661 ] 8662 ] 8663 [ 8664 [[link beast.ref.boost__beast__file_win32.read [*read]]] 8665 [ 8666 Read from the open file. 8667 ] 8668 ] 8669 [ 8670 [[link beast.ref.boost__beast__file_win32.seek [*seek]]] 8671 [ 8672 Adjust the current position in the open file. 8673 ] 8674 ] 8675 [ 8676 [[link beast.ref.boost__beast__file_win32.size [*size]]] 8677 [ 8678 Return the size of the open file. 8679 ] 8680 ] 8681 [ 8682 [[link beast.ref.boost__beast__file_win32.write [*write]]] 8683 [ 8684 Write to the open file. 8685 ] 8686 ] 8687 [ 8688 [[link beast.ref.boost__beast__file_win32.file_win32_dtor_ [*~file_win32]]] 8689 [ 8690 Destructor. 8691 ] 8692 ] 8693] 8694 8695[heading Description] 8696This class implements a ['File] using Win32 native interfaces. [section:close file_win32::close] 8697[indexterm2 close..file_win32] 8698Close the file if open. 8699[heading Synopsis] 8700``` 8701void 8702close( 8703 error_code& ec); 8704``` 8705 8706[heading Description] 8707[heading Parameters] 8708[table [[Name][Description]] 8709 [[`ec`][ 8710 8711Set to the error, if any occurred. 8712 ]] 8713] 8714[endsect] 8715[section:file_win32 file_win32::file_win32] 8716[indexterm2 file_win32..file_win32] 8717Constructor. ``` 8718``[link beast.ref.boost__beast__file_win32.file_win32.overload1 file_win32]``(); 8719 ``[''''»''' [link beast.ref.boost__beast__file_win32.file_win32.overload1 more...]]`` 8720 8721``[link beast.ref.boost__beast__file_win32.file_win32.overload2 file_win32]``( 8722 file_win32&& other); 8723 ``[''''»''' [link beast.ref.boost__beast__file_win32.file_win32.overload2 more...]]`` 8724``` 8725[section:overload1 file_win32::file_win32 (1 of 2 overloads)] 8726Constructor. 8727[heading Synopsis] 8728``` 8729file_win32(); 8730``` 8731 8732[heading Description] 8733There is no open file initially. [endsect] 8734[section:overload2 file_win32::file_win32 (2 of 2 overloads)] 8735Constructor. 8736[heading Synopsis] 8737``` 8738file_win32( 8739 file_win32&& other); 8740``` 8741 8742[heading Description] 8743The moved-from object behaves as if default constructed. [endsect] 8744[endsect] 8745 8746[section:is_open file_win32::is_open] 8747[indexterm2 is_open..file_win32] 8748Returns `true` if the file is open. 8749[heading Synopsis] 8750``` 8751bool 8752is_open() const; 8753``` 8754 8755[heading Description] 8756[endsect] 8757[section:native_handle file_win32::native_handle] 8758[indexterm2 native_handle..file_win32] 8759Returns the native handle associated with the file. ``` 8760native_handle_type 8761``[link beast.ref.boost__beast__file_win32.native_handle.overload1 native_handle]``(); 8762 ``[''''»''' [link beast.ref.boost__beast__file_win32.native_handle.overload1 more...]]`` 8763 8764``` 8765Set the native handle associated with the file. ``` 8766void 8767``[link beast.ref.boost__beast__file_win32.native_handle.overload2 native_handle]``( 8768 native_handle_type h); 8769 ``[''''»''' [link beast.ref.boost__beast__file_win32.native_handle.overload2 more...]]`` 8770``` 8771[section:overload1 file_win32::native_handle (1 of 2 overloads)] 8772Returns the native handle associated with the file. 8773[heading Synopsis] 8774``` 8775native_handle_type 8776native_handle(); 8777``` 8778 8779[heading Description] 8780[endsect] 8781[section:overload2 file_win32::native_handle (2 of 2 overloads)] 8782Set the native handle associated with the file. 8783[heading Synopsis] 8784``` 8785void 8786native_handle( 8787 native_handle_type h); 8788``` 8789 8790[heading Description] 8791If the file is open it is first closed. 8792[heading Parameters] 8793[table [[Name][Description]] 8794 [[`h`][ 8795 8796The native file handle to assign. 8797 ]] 8798] 8799[endsect] 8800[endsect] 8801 8802[section:native_handle_type file_win32::native_handle_type] 8803[indexterm2 native_handle_type..file_win32] 8804The type of the underlying file handle. 8805[heading Synopsis] 8806 8807``` 8808using native_handle_type = HANDLE; 8809``` 8810 8811[heading Description] 8812This is platform-specific. [endsect] 8813[section:open file_win32::open] 8814[indexterm2 open..file_win32] 8815Open a file at the given path with the specified mode. 8816[heading Synopsis] 8817``` 8818void 8819open( 8820 char const* path, 8821 file_mode mode, 8822 error_code& ec); 8823``` 8824 8825[heading Description] 8826[heading Parameters] 8827[table [[Name][Description]] 8828 [[`path`][ 8829 8830The utf-8 encoded path to the file 8831 ]] 8832 [[`mode`][ 8833 8834The file mode to use 8835 ]] 8836 [[`ec`][ 8837 8838Set to the error, if any occurred 8839 ]] 8840] 8841[endsect] 8842[section:operator_eq_ file_win32::operator=] 8843[indexterm2 operator=..file_win32] 8844Assignment. 8845[heading Synopsis] 8846``` 8847file_win32& 8848operator=( 8849 file_win32&& other); 8850``` 8851 8852[heading Description] 8853The moved-from object behaves as if default constructed. [endsect] 8854[section:pos file_win32::pos] 8855[indexterm2 pos..file_win32] 8856Return the current position in the open file. 8857[heading Synopsis] 8858``` 8859std::uint64_t 8860pos( 8861 error_code& ec); 8862``` 8863 8864[heading Description] 8865[heading Parameters] 8866[table [[Name][Description]] 8867 [[`ec`][ 8868 8869Set to the error, if any occurred 8870 ]] 8871] 8872[heading Return Value] 8873The offset in bytes from the beginning of the file 8874[endsect] 8875[section:read file_win32::read] 8876[indexterm2 read..file_win32] 8877Read from the open file. 8878[heading Synopsis] 8879``` 8880std::size_t 8881read( 8882 void* buffer, 8883 std::size_t n, 8884 error_code& ec); 8885``` 8886 8887[heading Description] 8888[heading Parameters] 8889[table [[Name][Description]] 8890 [[`buffer`][ 8891 8892The buffer for storing the result of the read 8893 ]] 8894 [[`n`][ 8895 8896The number of bytes to read 8897 ]] 8898 [[`ec`][ 8899 8900Set to the error, if any occurred 8901 ]] 8902] 8903[endsect] 8904[section:seek file_win32::seek] 8905[indexterm2 seek..file_win32] 8906Adjust the current position in the open file. 8907[heading Synopsis] 8908``` 8909void 8910seek( 8911 std::uint64_t offset, 8912 error_code& ec); 8913``` 8914 8915[heading Description] 8916[heading Parameters] 8917[table [[Name][Description]] 8918 [[`offset`][ 8919 8920The offset in bytes from the beginning of the file 8921 ]] 8922 [[`ec`][ 8923 8924Set to the error, if any occurred 8925 ]] 8926] 8927[endsect] 8928[section:size file_win32::size] 8929[indexterm2 size..file_win32] 8930Return the size of the open file. 8931[heading Synopsis] 8932``` 8933std::uint64_t 8934size( 8935 error_code& ec) const; 8936``` 8937 8938[heading Description] 8939[heading Parameters] 8940[table [[Name][Description]] 8941 [[`ec`][ 8942 8943Set to the error, if any occurred 8944 ]] 8945] 8946[heading Return Value] 8947The size in bytes 8948[endsect] 8949[section:write file_win32::write] 8950[indexterm2 write..file_win32] 8951Write to the open file. 8952[heading Synopsis] 8953``` 8954std::size_t 8955write( 8956 void const* buffer, 8957 std::size_t n, 8958 error_code& ec); 8959``` 8960 8961[heading Description] 8962[heading Parameters] 8963[table [[Name][Description]] 8964 [[`buffer`][ 8965 8966The buffer holding the data to write 8967 ]] 8968 [[`n`][ 8969 8970The number of bytes to write 8971 ]] 8972 [[`ec`][ 8973 8974Set to the error, if any occurred 8975 ]] 8976] 8977[endsect] 8978[section:file_win32_dtor_ file_win32::~file_win32] 8979[indexterm2 ~file_win32..file_win32] 8980Destructor. 8981[heading Synopsis] 8982``` 8983~file_win32(); 8984``` 8985 8986[heading Description] 8987If the file is open it is first closed. [endsect] 8988 8989 8990 8991Convenience header [include_file boost/beast/core.hpp] 8992 8993[endsect] 8994 8995 8996 8997[section:boost__beast__flat_buffer flat_buffer] 8998[indexterm1 flat_buffer] 8999A flat buffer which uses the default allocator. 9000[heading Synopsis] 9001 9002Defined in header [include_file boost/beast/core/flat_buffer.hpp] 9003 9004 9005 9006``` 9007using flat_buffer = basic_flat_buffer< std::allocator< char > >; 9008``` 9009[heading Types] 9010[table [[Name][Description]] 9011 [ 9012 [[link beast.ref.boost__beast__basic_flat_buffer.allocator_type [*allocator_type]]] 9013 [ 9014 The type of allocator used. 9015 ] 9016 ] 9017 [ 9018 [[link beast.ref.boost__beast__basic_flat_buffer.const_buffers_type [*const_buffers_type]]] 9019 [ 9020 The ConstBufferSequence used to represent the readable bytes. 9021 ] 9022 ] 9023 [ 9024 [[link beast.ref.boost__beast__basic_flat_buffer.mutable_buffers_type [*mutable_buffers_type]]] 9025 [ 9026 The MutableBufferSequence used to represent the writable bytes. 9027 ] 9028 ] 9029 [ 9030 [[link beast.ref.boost__beast__basic_flat_buffer.mutable_data_type [*mutable_data_type]]] 9031 [ 9032 The MutableBufferSequence used to represent the readable bytes. 9033 ] 9034 ] 9035] 9036[heading Member Functions] 9037[table [[Name][Description]] 9038 [ 9039 [[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer [*basic_flat_buffer]]] 9040 [ 9041 Constructor. 9042 9043 Move Constructor. 9044 9045 Copy Constructor. 9046 ] 9047 ] 9048 [ 9049 [[link beast.ref.boost__beast__basic_flat_buffer.capacity [*capacity]]] 9050 [ 9051 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 9052 ] 9053 ] 9054 [ 9055 [[link beast.ref.boost__beast__basic_flat_buffer.cdata [*cdata]]] 9056 [ 9057 Returns a constant buffer sequence representing the readable bytes. 9058 ] 9059 ] 9060 [ 9061 [[link beast.ref.boost__beast__basic_flat_buffer.clear [*clear]]] 9062 [ 9063 Set the size of the readable and writable bytes to zero. 9064 ] 9065 ] 9066 [ 9067 [[link beast.ref.boost__beast__basic_flat_buffer.commit [*commit]]] 9068 [ 9069 Append writable bytes to the readable bytes. 9070 ] 9071 ] 9072 [ 9073 [[link beast.ref.boost__beast__basic_flat_buffer.consume [*consume]]] 9074 [ 9075 Remove bytes from beginning of the readable bytes. 9076 ] 9077 ] 9078 [ 9079 [[link beast.ref.boost__beast__basic_flat_buffer.data [*data]]] 9080 [ 9081 Returns a constant buffer sequence representing the readable bytes. 9082 9083 Returns a mutable buffer sequence representing the readable bytes. 9084 ] 9085 ] 9086 [ 9087 [[link beast.ref.boost__beast__basic_flat_buffer.get_allocator [*get_allocator]]] 9088 [ 9089 Returns a copy of the allocator used. 9090 ] 9091 ] 9092 [ 9093 [[link beast.ref.boost__beast__basic_flat_buffer.max_size [*max_size]]] 9094 [ 9095 Set the maximum allowed capacity. 9096 9097 Return the maximum number of bytes, both readable and writable, that can ever be held. 9098 ] 9099 ] 9100 [ 9101 [[link beast.ref.boost__beast__basic_flat_buffer.operator_eq_ [*operator=]]] 9102 [ 9103 Move Assignment. 9104 9105 Copy Assignment. 9106 9107 Copy assignment. 9108 ] 9109 ] 9110 [ 9111 [[link beast.ref.boost__beast__basic_flat_buffer.prepare [*prepare]]] 9112 [ 9113 Returns a mutable buffer sequence representing writable bytes. 9114 ] 9115 ] 9116 [ 9117 [[link beast.ref.boost__beast__basic_flat_buffer.reserve [*reserve]]] 9118 [ 9119 Guarantee a minimum capacity. 9120 ] 9121 ] 9122 [ 9123 [[link beast.ref.boost__beast__basic_flat_buffer.shrink_to_fit [*shrink_to_fit]]] 9124 [ 9125 Reallocate the buffer to fit the readable bytes exactly. 9126 ] 9127 ] 9128 [ 9129 [[link beast.ref.boost__beast__basic_flat_buffer.size [*size]]] 9130 [ 9131 Returns the number of readable bytes. 9132 ] 9133 ] 9134 [ 9135 [[link beast.ref.boost__beast__basic_flat_buffer.basic_flat_buffer_dtor_ [*~basic_flat_buffer]]] 9136 [ 9137 Destructor. 9138 ] 9139 ] 9140] 9141[heading Friends] 9142[table [[Name][Description]] 9143 [ 9144 [[link beast.ref.boost__beast__basic_flat_buffer.swap [*swap]]] 9145 [ 9146 Exchange two dynamic buffers. 9147 ] 9148 ] 9149] 9150A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 9151Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 9152 9153* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] when `this` is non-const. 9154 9155 9156* A configurable maximum buffer size may be set upon construction. Attempts to exceed the buffer size will throw `std::length_error`. 9157 9158 9159* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__basic_flat_buffer.data `basic_flat_buffer::data`] and [link beast.ref.boost__beast__basic_flat_buffer.prepare `basic_flat_buffer::prepare`], will have length one. 9160 9161Upon construction, a maximum size for the buffer may be specified. If this limit is exceeded, the `std::length_error` exception will be thrown. 9162[heading Remarks] 9163This class is designed for use with algorithms that take dynamic buffers as parameters, and are optimized for the case where the input sequence or output sequence is stored in a single contiguous buffer. 9164 9165[heading Description] 9166 9167 9168 9169Convenience header [include_file boost/beast/core.hpp] 9170 9171[endsect] 9172[section:boost__beast__flat_static_buffer flat_static_buffer] 9173A ['DynamicBuffer] with a fixed size internal buffer. 9174[heading Synopsis] 9175 9176Defined in header [include_file boost/beast/core/flat_static_buffer.hpp] 9177 9178 9179 9180``` 9181template< 9182 std::size_t N> 9183class flat_static_buffer : 9184 public flat_static_buffer_base 9185``` 9186[heading Types] 9187[table [[Name][Description]] 9188 [ 9189 [[link beast.ref.boost__beast__flat_static_buffer.const_buffers_type [*const_buffers_type]]] 9190 [ 9191 The ConstBufferSequence used to represent the readable bytes. 9192 ] 9193 ] 9194 [ 9195 [[link beast.ref.boost__beast__flat_static_buffer.mutable_buffers_type [*mutable_buffers_type]]] 9196 [ 9197 The MutableBufferSequence used to represent the writable bytes. 9198 ] 9199 ] 9200 [ 9201 [[link beast.ref.boost__beast__flat_static_buffer.mutable_data_type [*mutable_data_type]]] 9202 [ 9203 The MutableBufferSequence used to represent the readable bytes. 9204 ] 9205 ] 9206] 9207[heading Member Functions] 9208[table [[Name][Description]] 9209 [ 9210 [[link beast.ref.boost__beast__flat_static_buffer.base [*base]]] 9211 [ 9212 Returns the flat_static_buffer_base portion of this object. 9213 ] 9214 ] 9215 [ 9216 [[link beast.ref.boost__beast__flat_static_buffer.capacity [*capacity]]] 9217 [ 9218 Return the maximum sum of input and output sizes that can be held without an allocation. 9219 ] 9220 ] 9221 [ 9222 [[link beast.ref.boost__beast__flat_static_buffer.cdata [*cdata]]] 9223 [ 9224 Returns a constant buffer sequence representing the readable bytes. 9225 ] 9226 ] 9227 [ 9228 [[link beast.ref.boost__beast__flat_static_buffer.clear [*clear]]] 9229 [ 9230 Clear the readable and writable bytes to zero. 9231 ] 9232 ] 9233 [ 9234 [[link beast.ref.boost__beast__flat_static_buffer.commit [*commit]]] 9235 [ 9236 Append writable bytes to the readable bytes. 9237 ] 9238 ] 9239 [ 9240 [[link beast.ref.boost__beast__flat_static_buffer.consume [*consume]]] 9241 [ 9242 Remove bytes from beginning of the readable bytes. 9243 ] 9244 ] 9245 [ 9246 [[link beast.ref.boost__beast__flat_static_buffer.data [*data]]] 9247 [ 9248 Returns a constant buffer sequence representing the readable bytes. 9249 9250 Returns a mutable buffer sequence representing the readable bytes. 9251 ] 9252 ] 9253 [ 9254 [[link beast.ref.boost__beast__flat_static_buffer.flat_static_buffer [*flat_static_buffer]]] 9255 [ 9256 Constructor. 9257 ] 9258 ] 9259 [ 9260 [[link beast.ref.boost__beast__flat_static_buffer.max_size [*max_size]]] 9261 [ 9262 Return the maximum sum of the input and output sequence sizes. 9263 ] 9264 ] 9265 [ 9266 [[link beast.ref.boost__beast__flat_static_buffer.operator_eq_ [*operator=]]] 9267 [ 9268 Assignment. 9269 ] 9270 ] 9271 [ 9272 [[link beast.ref.boost__beast__flat_static_buffer.prepare [*prepare]]] 9273 [ 9274 Returns a mutable buffer sequence representing writable bytes. 9275 ] 9276 ] 9277 [ 9278 [[link beast.ref.boost__beast__flat_static_buffer.size [*size]]] 9279 [ 9280 Returns the number of readable bytes. 9281 ] 9282 ] 9283] 9284[heading Protected Member Functions] 9285[table [[Name][Description]] 9286 [ 9287 [[link beast.ref.boost__beast__flat_static_buffer.reset [*reset]]] 9288 [ 9289 Reset the pointed-to buffer. 9290 ] 9291 ] 9292] 9293 9294[heading Description] 9295Buffer sequences returned by [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] and [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] will always be of length one. This implements a dynamic buffer using no memory allocations. 9296[heading Template Parameters] 9297[table [[Type][Description]] 9298 [[`N`][ 9299 9300The number of bytes in the internal buffer. 9301 ]] 9302] 9303[heading Remarks] 9304To reduce the number of template instantiations when passing objects of this type in a deduced context, the signature of the receiving function should use [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] instead. 9305[heading See Also] 9306[link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] 9307[section:base flat_static_buffer::base] 9308[indexterm2 base..flat_static_buffer] 9309Returns the [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] portion of this object. ``` 9310flat_static_buffer_base& 9311``[link beast.ref.boost__beast__flat_static_buffer.base.overload1 base]``(); 9312 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.base.overload1 more...]]`` 9313 9314flat_static_buffer_base const & 9315``[link beast.ref.boost__beast__flat_static_buffer.base.overload2 base]``() const; 9316 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.base.overload2 more...]]`` 9317``` 9318[section:overload1 flat_static_buffer::base (1 of 2 overloads)] 9319Returns the [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] portion of this object. 9320[heading Synopsis] 9321``` 9322flat_static_buffer_base& 9323base(); 9324``` 9325 9326[heading Description] 9327[endsect] 9328[section:overload2 flat_static_buffer::base (2 of 2 overloads)] 9329Returns the [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] portion of this object. 9330[heading Synopsis] 9331``` 9332flat_static_buffer_base const & 9333base() const; 9334``` 9335 9336[heading Description] 9337[endsect] 9338[endsect] 9339 9340[section:capacity flat_static_buffer::capacity] 9341[indexterm2 capacity..flat_static_buffer] 9342Return the maximum sum of input and output sizes that can be held without an allocation. 9343[heading Synopsis] 9344``` 9345std::size_t constexpr 9346capacity() const; 9347``` 9348 9349[heading Description] 9350[endsect] 9351[section:cdata flat_static_buffer::cdata] 9352[indexterm2 cdata..flat_static_buffer] 9353Returns a constant buffer sequence representing the readable bytes. 9354[heading Synopsis] 9355``` 9356const_buffers_type 9357cdata() const; 9358``` 9359 9360[heading Description] 9361[endsect] 9362[section:clear flat_static_buffer::clear] 9363[indexterm2 clear..flat_static_buffer] 9364Clear the readable and writable bytes to zero. 9365[heading Synopsis] 9366``` 9367void 9368clear(); 9369``` 9370 9371[heading Description] 9372This function causes the readable and writable bytes to become empty. The capacity is not changed. 9373Buffer sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] become invalid. 9374[heading Exception Safety] 9375 9376No-throw guarantee. [endsect] 9377[section:commit flat_static_buffer::commit] 9378[indexterm2 commit..flat_static_buffer] 9379Append writable bytes to the readable bytes. 9380[heading Synopsis] 9381``` 9382void 9383commit( 9384 std::size_t n); 9385``` 9386 9387[heading Description] 9388Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 9389All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9390[heading Parameters] 9391[table [[Name][Description]] 9392 [[`n`][ 9393 9394The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 9395 ]] 9396] 9397[heading Exception Safety] 9398 9399No-throw guarantee. [endsect] 9400[section:const_buffers_type flat_static_buffer::const_buffers_type] 9401[indexterm2 const_buffers_type..flat_static_buffer] 9402The ConstBufferSequence used to represent the readable bytes. 9403[heading Synopsis] 9404 9405``` 9406using const_buffers_type = net::const_buffer; 9407``` 9408 9409[heading Description] 9410[endsect] 9411[section:consume flat_static_buffer::consume] 9412[indexterm2 consume..flat_static_buffer] 9413Remove bytes from beginning of the readable bytes. 9414[heading Synopsis] 9415``` 9416void 9417consume( 9418 std::size_t n); 9419``` 9420 9421[heading Description] 9422Removes n bytes from the beginning of the readable bytes. 9423All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9424[heading Parameters] 9425[table [[Name][Description]] 9426 [[`n`][ 9427 9428The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 9429 ]] 9430] 9431[heading Exception Safety] 9432 9433No-throw guarantee. [endsect] 9434[section:data flat_static_buffer::data] 9435[indexterm2 data..flat_static_buffer] 9436Returns a constant buffer sequence representing the readable bytes. ``` 9437const_buffers_type 9438``[link beast.ref.boost__beast__flat_static_buffer.data.overload1 data]``() const; 9439 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.data.overload1 more...]]`` 9440 9441``` 9442Returns a mutable buffer sequence representing the readable bytes. ``` 9443mutable_data_type 9444``[link beast.ref.boost__beast__flat_static_buffer.data.overload2 data]``(); 9445 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.data.overload2 more...]]`` 9446``` 9447[section:overload1 flat_static_buffer::data (1 of 2 overloads)] 9448Returns a constant buffer sequence representing the readable bytes. 9449[heading Synopsis] 9450``` 9451const_buffers_type 9452data() const; 9453``` 9454 9455[heading Description] 9456[endsect] 9457[section:overload2 flat_static_buffer::data (2 of 2 overloads)] 9458Returns a mutable buffer sequence representing the readable bytes. 9459[heading Synopsis] 9460``` 9461mutable_data_type 9462data(); 9463``` 9464 9465[heading Description] 9466[endsect] 9467[endsect] 9468 9469[section:flat_static_buffer flat_static_buffer::flat_static_buffer] 9470[indexterm2 flat_static_buffer..flat_static_buffer] 9471Constructor. ``` 9472``[link beast.ref.boost__beast__flat_static_buffer.flat_static_buffer.overload1 flat_static_buffer]``( 9473 flat_static_buffer const&); 9474 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.flat_static_buffer.overload1 more...]]`` 9475 9476``[link beast.ref.boost__beast__flat_static_buffer.flat_static_buffer.overload2 flat_static_buffer]``(); 9477 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer.flat_static_buffer.overload2 more...]]`` 9478``` 9479[section:overload1 flat_static_buffer::flat_static_buffer (1 of 2 overloads)] 9480Constructor. 9481[heading Synopsis] 9482``` 9483flat_static_buffer( 9484 flat_static_buffer const&); 9485``` 9486 9487[heading Description] 9488[endsect] 9489[section:overload2 flat_static_buffer::flat_static_buffer (2 of 2 overloads)] 9490Constructor. 9491[heading Synopsis] 9492``` 9493flat_static_buffer(); 9494``` 9495 9496[heading Description] 9497[endsect] 9498[endsect] 9499 9500[section:max_size flat_static_buffer::max_size] 9501[indexterm2 max_size..flat_static_buffer] 9502Return the maximum sum of the input and output sequence sizes. 9503[heading Synopsis] 9504``` 9505std::size_t constexpr 9506max_size() const; 9507``` 9508 9509[heading Description] 9510[endsect] 9511[section:mutable_buffers_type flat_static_buffer::mutable_buffers_type] 9512[indexterm2 mutable_buffers_type..flat_static_buffer] 9513The MutableBufferSequence used to represent the writable bytes. 9514[heading Synopsis] 9515 9516``` 9517using mutable_buffers_type = net::mutable_buffer; 9518``` 9519 9520[heading Description] 9521[endsect] 9522[section:mutable_data_type flat_static_buffer::mutable_data_type] 9523[indexterm2 mutable_data_type..flat_static_buffer] 9524The MutableBufferSequence used to represent the readable bytes. 9525[heading Synopsis] 9526 9527``` 9528using mutable_data_type = net::mutable_buffer; 9529``` 9530 9531[heading Description] 9532[endsect] 9533[section:operator_eq_ flat_static_buffer::operator=] 9534[indexterm2 operator=..flat_static_buffer] 9535Assignment. 9536[heading Synopsis] 9537``` 9538flat_static_buffer& 9539operator=( 9540 flat_static_buffer const&); 9541``` 9542 9543[heading Description] 9544[endsect] 9545[section:prepare flat_static_buffer::prepare] 9546[indexterm2 prepare..flat_static_buffer] 9547Returns a mutable buffer sequence representing writable bytes. 9548[heading Synopsis] 9549``` 9550mutable_buffers_type 9551prepare( 9552 std::size_t n); 9553``` 9554 9555[heading Description] 9556Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. 9557All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9558[heading Parameters] 9559[table [[Name][Description]] 9560 [[`n`][ 9561 9562The desired number of bytes in the returned buffer sequence. 9563 ]] 9564] 9565[heading Exceptions] 9566[table [[Type][Thrown On]] 9567 [[`std::length_error`][ 9568 9569if `size() + n` exceeds `max_size()`. 9570 ]] 9571] 9572[heading Exception Safety] 9573 9574Strong guarantee. [endsect] 9575[section:reset flat_static_buffer::reset] 9576[indexterm2 reset..flat_static_buffer] 9577Reset the pointed-to buffer. 9578[heading Synopsis] 9579``` 9580void 9581reset( 9582 void* p, 9583 std::size_t n); 9584``` 9585 9586[heading Description] 9587This function resets the internal state to the buffer provided. All input and output sequences are invalidated. This function allows the derived class to construct its members before initializing the static buffer. 9588[heading Parameters] 9589[table [[Name][Description]] 9590 [[`p`][ 9591 9592A pointer to valid storage of at least `n` bytes. 9593 ]] 9594 [[`n`][ 9595 9596The number of valid bytes pointed to by `p`. 9597 ]] 9598] 9599[heading Exception Safety] 9600 9601No-throw guarantee. [endsect] 9602[section:size flat_static_buffer::size] 9603[indexterm2 size..flat_static_buffer] 9604Returns the number of readable bytes. 9605[heading Synopsis] 9606``` 9607std::size_t 9608size() const; 9609``` 9610 9611[heading Description] 9612[endsect] 9613 9614 9615 9616Convenience header [include_file boost/beast/core.hpp] 9617 9618[endsect] 9619 9620 9621 9622[section:boost__beast__flat_static_buffer_base flat_static_buffer_base] 9623A dynamic buffer using a fixed size internal buffer. 9624[heading Synopsis] 9625 9626Defined in header [include_file boost/beast/core/flat_static_buffer.hpp] 9627 9628 9629 9630``` 9631class flat_static_buffer_base 9632``` 9633[heading Types] 9634[table [[Name][Description]] 9635 [ 9636 [[link beast.ref.boost__beast__flat_static_buffer_base.const_buffers_type [*const_buffers_type]]] 9637 [ 9638 The ConstBufferSequence used to represent the readable bytes. 9639 ] 9640 ] 9641 [ 9642 [[link beast.ref.boost__beast__flat_static_buffer_base.mutable_buffers_type [*mutable_buffers_type]]] 9643 [ 9644 The MutableBufferSequence used to represent the writable bytes. 9645 ] 9646 ] 9647 [ 9648 [[link beast.ref.boost__beast__flat_static_buffer_base.mutable_data_type [*mutable_data_type]]] 9649 [ 9650 The MutableBufferSequence used to represent the readable bytes. 9651 ] 9652 ] 9653] 9654[heading Member Functions] 9655[table [[Name][Description]] 9656 [ 9657 [[link beast.ref.boost__beast__flat_static_buffer_base.capacity [*capacity]]] 9658 [ 9659 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 9660 ] 9661 ] 9662 [ 9663 [[link beast.ref.boost__beast__flat_static_buffer_base.cdata [*cdata]]] 9664 [ 9665 Returns a constant buffer sequence representing the readable bytes. 9666 ] 9667 ] 9668 [ 9669 [[link beast.ref.boost__beast__flat_static_buffer_base.clear [*clear]]] 9670 [ 9671 Clear the readable and writable bytes to zero. 9672 ] 9673 ] 9674 [ 9675 [[link beast.ref.boost__beast__flat_static_buffer_base.commit [*commit]]] 9676 [ 9677 Append writable bytes to the readable bytes. 9678 ] 9679 ] 9680 [ 9681 [[link beast.ref.boost__beast__flat_static_buffer_base.consume [*consume]]] 9682 [ 9683 Remove bytes from beginning of the readable bytes. 9684 ] 9685 ] 9686 [ 9687 [[link beast.ref.boost__beast__flat_static_buffer_base.data [*data]]] 9688 [ 9689 Returns a constant buffer sequence representing the readable bytes. 9690 9691 Returns a mutable buffer sequence representing the readable bytes. 9692 ] 9693 ] 9694 [ 9695 [[link beast.ref.boost__beast__flat_static_buffer_base.flat_static_buffer_base [*flat_static_buffer_base]]] 9696 [ 9697 Constructor. 9698 ] 9699 ] 9700 [ 9701 [[link beast.ref.boost__beast__flat_static_buffer_base.max_size [*max_size]]] 9702 [ 9703 Return the maximum number of bytes, both readable and writable, that can ever be held. 9704 ] 9705 ] 9706 [ 9707 [[link beast.ref.boost__beast__flat_static_buffer_base.prepare [*prepare]]] 9708 [ 9709 Returns a mutable buffer sequence representing writable bytes. 9710 ] 9711 ] 9712 [ 9713 [[link beast.ref.boost__beast__flat_static_buffer_base.size [*size]]] 9714 [ 9715 Returns the number of readable bytes. 9716 ] 9717 ] 9718] 9719[heading Protected Member Functions] 9720[table [[Name][Description]] 9721 [ 9722 [[link beast.ref.boost__beast__flat_static_buffer_base.flat_static_buffer_base [*flat_static_buffer_base]]] 9723 [ 9724 Constructor. 9725 ] 9726 ] 9727 [ 9728 [[link beast.ref.boost__beast__flat_static_buffer_base.reset [*reset]]] 9729 [ 9730 Reset the pointed-to buffer. 9731 ] 9732 ] 9733] 9734 9735[heading Description] 9736A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 9737Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 9738 9739* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] when `this` is non-const. 9740 9741 9742* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] and [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`], will have length one. 9743 9744 9745* Ownership of the underlying storage belongs to the derived class. 9746 9747[heading Remarks] 9748Variables are usually declared using the template class [link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]; however, to reduce the number of template instantiations, objects should be passed `flat_static_buffer_base&`. 9749[heading See Also] 9750[link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`] 9751[section:capacity flat_static_buffer_base::capacity] 9752[indexterm2 capacity..flat_static_buffer_base] 9753Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 9754[heading Synopsis] 9755``` 9756std::size_t 9757capacity() const; 9758``` 9759 9760[heading Description] 9761[endsect] 9762[section:cdata flat_static_buffer_base::cdata] 9763[indexterm2 cdata..flat_static_buffer_base] 9764Returns a constant buffer sequence representing the readable bytes. 9765[heading Synopsis] 9766``` 9767const_buffers_type 9768cdata() const; 9769``` 9770 9771[heading Description] 9772[endsect] 9773[section:clear flat_static_buffer_base::clear] 9774[indexterm2 clear..flat_static_buffer_base] 9775Clear the readable and writable bytes to zero. 9776[heading Synopsis] 9777``` 9778void 9779clear(); 9780``` 9781 9782[heading Description] 9783This function causes the readable and writable bytes to become empty. The capacity is not changed. 9784Buffer sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] become invalid. 9785[heading Exception Safety] 9786 9787No-throw guarantee. [endsect] 9788[section:commit flat_static_buffer_base::commit] 9789[indexterm2 commit..flat_static_buffer_base] 9790Append writable bytes to the readable bytes. 9791[heading Synopsis] 9792``` 9793void 9794commit( 9795 std::size_t n); 9796``` 9797 9798[heading Description] 9799Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 9800All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9801[heading Parameters] 9802[table [[Name][Description]] 9803 [[`n`][ 9804 9805The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 9806 ]] 9807] 9808[heading Exception Safety] 9809 9810No-throw guarantee. [endsect] 9811[section:const_buffers_type flat_static_buffer_base::const_buffers_type] 9812[indexterm2 const_buffers_type..flat_static_buffer_base] 9813The ConstBufferSequence used to represent the readable bytes. 9814[heading Synopsis] 9815 9816``` 9817using const_buffers_type = net::const_buffer; 9818``` 9819 9820[heading Description] 9821[endsect] 9822[section:consume flat_static_buffer_base::consume] 9823[indexterm2 consume..flat_static_buffer_base] 9824Remove bytes from beginning of the readable bytes. 9825[heading Synopsis] 9826``` 9827void 9828consume( 9829 std::size_t n); 9830``` 9831 9832[heading Description] 9833Removes n bytes from the beginning of the readable bytes. 9834All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9835[heading Parameters] 9836[table [[Name][Description]] 9837 [[`n`][ 9838 9839The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 9840 ]] 9841] 9842[heading Exception Safety] 9843 9844No-throw guarantee. [endsect] 9845[section:data flat_static_buffer_base::data] 9846[indexterm2 data..flat_static_buffer_base] 9847Returns a constant buffer sequence representing the readable bytes. ``` 9848const_buffers_type 9849``[link beast.ref.boost__beast__flat_static_buffer_base.data.overload1 data]``() const; 9850 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer_base.data.overload1 more...]]`` 9851 9852``` 9853Returns a mutable buffer sequence representing the readable bytes. ``` 9854mutable_data_type 9855``[link beast.ref.boost__beast__flat_static_buffer_base.data.overload2 data]``(); 9856 ``[''''»''' [link beast.ref.boost__beast__flat_static_buffer_base.data.overload2 more...]]`` 9857``` 9858[section:overload1 flat_static_buffer_base::data (1 of 2 overloads)] 9859Returns a constant buffer sequence representing the readable bytes. 9860[heading Synopsis] 9861``` 9862const_buffers_type 9863data() const; 9864``` 9865 9866[heading Description] 9867[endsect] 9868[section:overload2 flat_static_buffer_base::data (2 of 2 overloads)] 9869Returns a mutable buffer sequence representing the readable bytes. 9870[heading Synopsis] 9871``` 9872mutable_data_type 9873data(); 9874``` 9875 9876[heading Description] 9877[endsect] 9878[endsect] 9879 9880[section:flat_static_buffer_base flat_static_buffer_base::flat_static_buffer_base] 9881[indexterm2 flat_static_buffer_base..flat_static_buffer_base] 9882Constructor. 9883[heading Synopsis] 9884``` 9885flat_static_buffer_base( 9886 void* p, 9887 std::size_t n); 9888``` 9889 9890[heading Description] 9891This creates a dynamic buffer using the provided storage area. 9892[heading Parameters] 9893[table [[Name][Description]] 9894 [[`p`][ 9895 9896A pointer to valid storage of at least `n` bytes. 9897 ]] 9898 [[`n`][ 9899 9900The number of valid bytes pointed to by `p`. 9901 ]] 9902] 9903[endsect] 9904[section:flat_static_buffer_base flat_static_buffer_base::flat_static_buffer_base] 9905[indexterm2 flat_static_buffer_base..flat_static_buffer_base] 9906Constructor. 9907[heading Synopsis] 9908``` 9909flat_static_buffer_base(); 9910``` 9911 9912[heading Description] 9913The buffer will be in an undefined state. It is necessary for the derived class to call [link beast.ref.boost__beast__flat_static_buffer.reset `flat_static_buffer::reset`] with a pointer and size in order to initialize the object. [endsect] 9914[section:max_size flat_static_buffer_base::max_size] 9915[indexterm2 max_size..flat_static_buffer_base] 9916Return the maximum number of bytes, both readable and writable, that can ever be held. 9917[heading Synopsis] 9918``` 9919std::size_t 9920max_size() const; 9921``` 9922 9923[heading Description] 9924[endsect] 9925[section:mutable_buffers_type flat_static_buffer_base::mutable_buffers_type] 9926[indexterm2 mutable_buffers_type..flat_static_buffer_base] 9927The MutableBufferSequence used to represent the writable bytes. 9928[heading Synopsis] 9929 9930``` 9931using mutable_buffers_type = net::mutable_buffer; 9932``` 9933 9934[heading Description] 9935[endsect] 9936[section:mutable_data_type flat_static_buffer_base::mutable_data_type] 9937[indexterm2 mutable_data_type..flat_static_buffer_base] 9938The MutableBufferSequence used to represent the readable bytes. 9939[heading Synopsis] 9940 9941``` 9942using mutable_data_type = net::mutable_buffer; 9943``` 9944 9945[heading Description] 9946[endsect] 9947[section:prepare flat_static_buffer_base::prepare] 9948[indexterm2 prepare..flat_static_buffer_base] 9949Returns a mutable buffer sequence representing writable bytes. 9950[heading Synopsis] 9951``` 9952mutable_buffers_type 9953prepare( 9954 std::size_t n); 9955``` 9956 9957[heading Description] 9958Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. 9959All buffers sequences previously obtained using [link beast.ref.boost__beast__flat_static_buffer.data `flat_static_buffer::data`] or [link beast.ref.boost__beast__flat_static_buffer.prepare `flat_static_buffer::prepare`] are invalidated. 9960[heading Parameters] 9961[table [[Name][Description]] 9962 [[`n`][ 9963 9964The desired number of bytes in the returned buffer sequence. 9965 ]] 9966] 9967[heading Exceptions] 9968[table [[Type][Thrown On]] 9969 [[`std::length_error`][ 9970 9971if `size() + n` exceeds `max_size()`. 9972 ]] 9973] 9974[heading Exception Safety] 9975 9976Strong guarantee. [endsect] 9977[section:reset flat_static_buffer_base::reset] 9978[indexterm2 reset..flat_static_buffer_base] 9979Reset the pointed-to buffer. 9980[heading Synopsis] 9981``` 9982void 9983reset( 9984 void* p, 9985 std::size_t n); 9986``` 9987 9988[heading Description] 9989This function resets the internal state to the buffer provided. All input and output sequences are invalidated. This function allows the derived class to construct its members before initializing the static buffer. 9990[heading Parameters] 9991[table [[Name][Description]] 9992 [[`p`][ 9993 9994A pointer to valid storage of at least `n` bytes. 9995 ]] 9996 [[`n`][ 9997 9998The number of valid bytes pointed to by `p`. 9999 ]] 10000] 10001[heading Exception Safety] 10002 10003No-throw guarantee. [endsect] 10004[section:size flat_static_buffer_base::size] 10005[indexterm2 size..flat_static_buffer_base] 10006Returns the number of readable bytes. 10007[heading Synopsis] 10008``` 10009std::size_t 10010size() const; 10011``` 10012 10013[heading Description] 10014[endsect] 10015 10016 10017 10018Convenience header [include_file boost/beast/core.hpp] 10019 10020[endsect] 10021 10022 10023 10024[section:boost__beast__flat_stream flat_stream] 10025Stream wrapper to improve write performance. 10026[heading Synopsis] 10027 10028Defined in header [include_file boost/beast/core/flat_stream.hpp] 10029 10030 10031 10032``` 10033template< 10034 class NextLayer> 10035class flat_stream 10036``` 10037[heading Types] 10038[table [[Name][Description]] 10039 [ 10040 [[link beast.ref.boost__beast__flat_stream.executor_type [*executor_type]]] 10041 [ 10042 The type of the executor associated with the object. 10043 ] 10044 ] 10045 [ 10046 [[link beast.ref.boost__beast__flat_stream.next_layer_type [*next_layer_type]]] 10047 [ 10048 The type of the next layer. 10049 ] 10050 ] 10051] 10052[heading Member Functions] 10053[table [[Name][Description]] 10054 [ 10055 [[link beast.ref.boost__beast__flat_stream.async_read_some [*async_read_some]]] 10056 [ 10057 Start an asynchronous read. 10058 ] 10059 ] 10060 [ 10061 [[link beast.ref.boost__beast__flat_stream.async_write_some [*async_write_some]]] 10062 [ 10063 Start an asynchronous write. 10064 ] 10065 ] 10066 [ 10067 [[link beast.ref.boost__beast__flat_stream.flat_stream [*flat_stream]]] 10068 [ 10069 10070 10071 Constructor. 10072 ] 10073 ] 10074 [ 10075 [[link beast.ref.boost__beast__flat_stream.get_executor [*get_executor]]] 10076 [ 10077 Get the executor associated with the object. 10078 ] 10079 ] 10080 [ 10081 [[link beast.ref.boost__beast__flat_stream.next_layer [*next_layer]]] 10082 [ 10083 Get a reference to the next layer. 10084 ] 10085 ] 10086 [ 10087 [[link beast.ref.boost__beast__flat_stream.operator_eq_ [*operator=]]] 10088 [ 10089 10090 ] 10091 ] 10092 [ 10093 [[link beast.ref.boost__beast__flat_stream.read_some [*read_some]]] 10094 [ 10095 Read some data from the stream. 10096 ] 10097 ] 10098 [ 10099 [[link beast.ref.boost__beast__flat_stream.write_some [*write_some]]] 10100 [ 10101 Write some data to the stream. 10102 ] 10103 ] 10104 [ 10105 [[link beast.ref.boost__beast__flat_stream.flat_stream_dtor_ [*~flat_stream]]] 10106 [ 10107 Destructor. 10108 ] 10109 ] 10110] 10111 10112[heading Description] 10113This wrapper flattens writes for buffer sequences having length greater than 1 and total size below a predefined amount, using a dynamic memory allocation. It is primarily designed to overcome a performance limitation of the current version of `net::ssl::stream`, which does not use OpenSSL's scatter/gather interface for its low-level read some and write some operations. 10114It is normally not necessary to use this class directly if you are already using [link beast.ref.boost__beast__ssl_stream `ssl_stream`]. The following examples shows how to use this class with the ssl stream that comes with networking: 10115[heading Example] 10116 10117To use the [link beast.ref.boost__beast__flat_stream `flat_stream`] template with SSL streams, declare a variable of the correct type. Parameters passed to the constructor will be forwarded to the next layer's constructor: 10118 10119``` 10120 flat_stream<net::ssl::stream<ip::tcp::socket>> fs{ioc, ctx}; 10121``` 10122Alternatively you can write 10123``` 10124 ssl::stream<ip::tcp::socket> ss{ioc, ctx}; 10125 flat_stream<net::ssl::stream<ip::tcp::socket>&> fs{ss}; 10126``` 10127The resulting stream may be passed to any stream algorithms which operate on synchronous or asynchronous read or write streams, examples include: 10128 10129* `net::read`, `net::async_read` 10130 10131 10132* `net::write`, `net::async_write` 10133 10134 10135* `net::read_until`, `net::async_read_until` 10136 10137The stream may also be used as a template parameter in other stream wrappers, such as for websocket: 10138``` 10139 websocket::stream<flat_stream<net::ssl::stream<ip::tcp::socket>>> ws{ioc, ctx}; 10140``` 10141[heading Template Parameters] 10142[table [[Type][Description]] 10143 [[`NextLayer`][ 10144 10145The type representing the next layer, to which data will be read and written during operations. For synchronous operations, the type must support the [*SyncStream] concept. For asynchronous operations, the type must support the [*AsyncStream] concept. This type will usually be some variation of `net::ssl::stream`. 10146 ]] 10147] 10148[heading Concepts] 10149 10150* SyncStream 10151* AsyncStream 10152 10153 10154[heading See Also] 10155 10156* [@https://github.com/boostorg/asio/issues/100 https://github.com/boostorg/asio/issues/100] 10157* [@https://github.com/boostorg/beast/issues/1108 https://github.com/boostorg/beast/issues/1108] 10158* [@https://stackoverflow.com/questions/38198638/openssl-ssl-write-from-multiple-buffers-ssl-writev https://stackoverflow.com/questions/38198638/openssl-ssl-write-from-multiple-buffers-ssl-writev] 10159* [@https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast https://stackoverflow.com/questions/50026167/performance-drop-on-port-from-beast-1-0-0-b66-to-boost-1-67-0-beast] 10160 10161 10162[section:async_read_some flat_stream::async_read_some] 10163[indexterm2 async_read_some..flat_stream] 10164Start an asynchronous read. 10165[heading Synopsis] 10166``` 10167template< 10168 class __MutableBufferSequence__, 10169 class __ReadHandler__ = net::default_completion_token_t<executor_type>> 10170``__deduced__`` 10171async_read_some( 10172 MutableBufferSequence const& buffers, 10173 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 10174``` 10175 10176[heading Description] 10177This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately. 10178[heading Parameters] 10179[table [[Name][Description]] 10180 [[`buffers`][ 10181 10182The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 10183 ]] 10184 [[`handler`][ 10185 10186The 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: 10187``` 10188 void handler( 10189 error_code const& error, // Result of operation. 10190 std::size_t bytes_transferred // Number of bytes read. 10191 ); 10192``` 10193Regardless 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 `net::post`. 10194 ]] 10195] 10196[heading Remarks] 10197The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. 10198[endsect] 10199[section:async_write_some flat_stream::async_write_some] 10200[indexterm2 async_write_some..flat_stream] 10201Start an asynchronous write. 10202[heading Synopsis] 10203``` 10204template< 10205 class __ConstBufferSequence__, 10206 class __WriteHandler__ = net::default_completion_token_t<executor_type>> 10207``__deduced__`` 10208async_write_some( 10209 ConstBufferSequence const& buffers, 10210 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 10211``` 10212 10213[heading Description] 10214This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately. 10215[heading Parameters] 10216[table [[Name][Description]] 10217 [[`buffers`][ 10218 10219The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 10220 ]] 10221 [[`handler`][ 10222 10223The 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: 10224``` 10225 void handler( 10226 error_code const& ec, // Result of operation. 10227 std::size_t bytes_transferred // Number of bytes written. 10228 ); 10229``` 10230 10231 ]] 10232] 10233Regardless 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 `net::post`. 10234[heading Remarks] 10235The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need to ensure that all data is written before the asynchronous operation completes. 10236[endsect] 10237[section:executor_type flat_stream::executor_type] 10238[indexterm2 executor_type..flat_stream] 10239The type of the executor associated with the object. 10240[heading Synopsis] 10241 10242``` 10243using executor_type = beast::executor_type< next_layer_type >; 10244``` 10245 10246[heading Description] 10247[endsect] 10248[section:flat_stream flat_stream::flat_stream] 10249[indexterm2 flat_stream..flat_stream] 10250``` 10251``[link beast.ref.boost__beast__flat_stream.flat_stream.overload1 flat_stream]``( 10252 flat_stream&&); 10253 ``[''''»''' [link beast.ref.boost__beast__flat_stream.flat_stream.overload1 more...]]`` 10254 10255``[link beast.ref.boost__beast__flat_stream.flat_stream.overload2 flat_stream]``( 10256 flat_stream const&); 10257 ``[''''»''' [link beast.ref.boost__beast__flat_stream.flat_stream.overload2 more...]]`` 10258 10259``` 10260Constructor. ``` 10261template< 10262 class... Args> 10263explicit 10264``[link beast.ref.boost__beast__flat_stream.flat_stream.overload3 flat_stream]``( 10265 Args&&... args); 10266 ``[''''»''' [link beast.ref.boost__beast__flat_stream.flat_stream.overload3 more...]]`` 10267``` 10268[section:overload1 flat_stream::flat_stream (1 of 3 overloads)] 10269 10270[heading Synopsis] 10271``` 10272flat_stream( 10273 flat_stream&&); 10274``` 10275 10276[heading Description] 10277[endsect] 10278[section:overload2 flat_stream::flat_stream (2 of 3 overloads)] 10279 10280[heading Synopsis] 10281``` 10282flat_stream( 10283 flat_stream const&); 10284``` 10285 10286[heading Description] 10287[endsect] 10288[section:overload3 flat_stream::flat_stream (3 of 3 overloads)] 10289Constructor. 10290[heading Synopsis] 10291``` 10292template< 10293 class... Args> 10294flat_stream( 10295 Args&&... args); 10296``` 10297 10298[heading Description] 10299Arguments, if any, are forwarded to the next layer's constructor. [endsect] 10300[endsect] 10301 10302[section:get_executor flat_stream::get_executor] 10303[indexterm2 get_executor..flat_stream] 10304Get the executor associated with the object. 10305[heading Synopsis] 10306``` 10307executor_type 10308get_executor(); 10309``` 10310 10311[heading Description] 10312This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations. 10313[heading Return Value] 10314A copy of the executor that stream will use to dispatch handlers. 10315[endsect] 10316[section:next_layer flat_stream::next_layer] 10317[indexterm2 next_layer..flat_stream] 10318Get a reference to the next layer. ``` 10319next_layer_type& 10320``[link beast.ref.boost__beast__flat_stream.next_layer.overload1 next_layer]``(); 10321 ``[''''»''' [link beast.ref.boost__beast__flat_stream.next_layer.overload1 more...]]`` 10322 10323next_layer_type const & 10324``[link beast.ref.boost__beast__flat_stream.next_layer.overload2 next_layer]``() const; 10325 ``[''''»''' [link beast.ref.boost__beast__flat_stream.next_layer.overload2 more...]]`` 10326``` 10327[section:overload1 flat_stream::next_layer (1 of 2 overloads)] 10328Get a reference to the next layer. 10329[heading Synopsis] 10330``` 10331next_layer_type& 10332next_layer(); 10333``` 10334 10335[heading Description] 10336This function returns a reference to the next layer in a stack of stream layers. 10337[heading Return Value] 10338A reference to the next layer in the stack of stream layers. 10339[endsect] 10340[section:overload2 flat_stream::next_layer (2 of 2 overloads)] 10341Get a reference to the next layer. 10342[heading Synopsis] 10343``` 10344next_layer_type const & 10345next_layer() const; 10346``` 10347 10348[heading Description] 10349This function returns a reference to the next layer in a stack of stream layers. 10350[heading Return Value] 10351A reference to the next layer in the stack of stream layers. 10352[endsect] 10353[endsect] 10354 10355[section:next_layer_type flat_stream::next_layer_type] 10356[indexterm2 next_layer_type..flat_stream] 10357The type of the next layer. 10358[heading Synopsis] 10359 10360``` 10361using next_layer_type = typename std::remove_reference< NextLayer >::type; 10362``` 10363 10364[heading Description] 10365[endsect] 10366[section:operator_eq_ flat_stream::operator=] 10367[indexterm2 operator=..flat_stream] 10368``` 10369flat_stream& 10370``[link beast.ref.boost__beast__flat_stream.operator_eq_.overload1 operator=]``( 10371 flat_stream&&); 10372 ``[''''»''' [link beast.ref.boost__beast__flat_stream.operator_eq_.overload1 more...]]`` 10373 10374flat_stream& 10375``[link beast.ref.boost__beast__flat_stream.operator_eq_.overload2 operator=]``( 10376 flat_stream const&); 10377 ``[''''»''' [link beast.ref.boost__beast__flat_stream.operator_eq_.overload2 more...]]`` 10378``` 10379[section:overload1 flat_stream::operator= (1 of 2 overloads)] 10380 10381[heading Synopsis] 10382``` 10383flat_stream& 10384operator=( 10385 flat_stream&&); 10386``` 10387 10388[heading Description] 10389[endsect] 10390[section:overload2 flat_stream::operator= (2 of 2 overloads)] 10391 10392[heading Synopsis] 10393``` 10394flat_stream& 10395operator=( 10396 flat_stream const&); 10397``` 10398 10399[heading Description] 10400[endsect] 10401[endsect] 10402 10403[section:read_some flat_stream::read_some] 10404[indexterm2 read_some..flat_stream] 10405Read some data from the stream. ``` 10406template< 10407 class __MutableBufferSequence__> 10408std::size_t 10409``[link beast.ref.boost__beast__flat_stream.read_some.overload1 read_some]``( 10410 MutableBufferSequence const& buffers); 10411 ``[''''»''' [link beast.ref.boost__beast__flat_stream.read_some.overload1 more...]]`` 10412 10413template< 10414 class __MutableBufferSequence__> 10415std::size_t 10416``[link beast.ref.boost__beast__flat_stream.read_some.overload2 read_some]``( 10417 MutableBufferSequence const& buffers, 10418 error_code& ec); 10419 ``[''''»''' [link beast.ref.boost__beast__flat_stream.read_some.overload2 more...]]`` 10420``` 10421[section:overload1 flat_stream::read_some (1 of 2 overloads)] 10422Read some data from the stream. 10423[heading Synopsis] 10424``` 10425template< 10426 class __MutableBufferSequence__> 10427std::size_t 10428read_some( 10429 MutableBufferSequence const& buffers); 10430``` 10431 10432[heading Description] 10433This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 10434[heading Parameters] 10435[table [[Name][Description]] 10436 [[`buffers`][ 10437 10438The buffers into which the data will be read. 10439 ]] 10440] 10441[heading Return Value] 10442The number of bytes read. 10443[heading Exceptions] 10444[table [[Type][Thrown On]] 10445 [[`boost::system::system_error`][ 10446 10447Thrown on failure. 10448 ]] 10449] 10450[heading Remarks] 10451The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 10452[endsect] 10453[section:overload2 flat_stream::read_some (2 of 2 overloads)] 10454Read some data from the stream. 10455[heading Synopsis] 10456``` 10457template< 10458 class __MutableBufferSequence__> 10459std::size_t 10460read_some( 10461 MutableBufferSequence const& buffers, 10462 error_code& ec); 10463``` 10464 10465[heading Description] 10466This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 10467[heading Parameters] 10468[table [[Name][Description]] 10469 [[`buffers`][ 10470 10471The buffers into which the data will be read. 10472 ]] 10473 [[`ec`][ 10474 10475Set to indicate what error occurred, if any. 10476 ]] 10477] 10478[heading Return Value] 10479The number of bytes read. 10480[heading Remarks] 10481The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 10482[endsect] 10483[endsect] 10484 10485[section:write_some flat_stream::write_some] 10486[indexterm2 write_some..flat_stream] 10487Write some data to the stream. ``` 10488template< 10489 class __ConstBufferSequence__> 10490std::size_t 10491``[link beast.ref.boost__beast__flat_stream.write_some.overload1 write_some]``( 10492 ConstBufferSequence const& buffers); 10493 ``[''''»''' [link beast.ref.boost__beast__flat_stream.write_some.overload1 more...]]`` 10494 10495template< 10496 class __ConstBufferSequence__> 10497std::size_t 10498``[link beast.ref.boost__beast__flat_stream.write_some.overload2 write_some]``( 10499 ConstBufferSequence const& buffers, 10500 error_code& ec); 10501 ``[''''»''' [link beast.ref.boost__beast__flat_stream.write_some.overload2 more...]]`` 10502``` 10503[section:overload1 flat_stream::write_some (1 of 2 overloads)] 10504Write some data to the stream. 10505[heading Synopsis] 10506``` 10507template< 10508 class __ConstBufferSequence__> 10509std::size_t 10510write_some( 10511 ConstBufferSequence const& buffers); 10512``` 10513 10514[heading Description] 10515This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 10516[heading Parameters] 10517[table [[Name][Description]] 10518 [[`buffers`][ 10519 10520The data to be written. 10521 ]] 10522] 10523[heading Return Value] 10524The number of bytes written. 10525[heading Exceptions] 10526[table [[Type][Thrown On]] 10527 [[`boost::system::system_error`][ 10528 10529Thrown on failure. 10530 ]] 10531] 10532[heading Remarks] 10533The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 10534[endsect] 10535[section:overload2 flat_stream::write_some (2 of 2 overloads)] 10536Write some data to the stream. 10537[heading Synopsis] 10538``` 10539template< 10540 class __ConstBufferSequence__> 10541std::size_t 10542write_some( 10543 ConstBufferSequence const& buffers, 10544 error_code& ec); 10545``` 10546 10547[heading Description] 10548This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 10549[heading Parameters] 10550[table [[Name][Description]] 10551 [[`buffers`][ 10552 10553The data to be written. 10554 ]] 10555 [[`ec`][ 10556 10557Set to indicate what error occurred, if any. 10558 ]] 10559] 10560[heading Return Value] 10561The number of bytes written. 10562[heading Remarks] 10563The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 10564[endsect] 10565[endsect] 10566 10567[section:flat_stream_dtor_ flat_stream::~flat_stream] 10568[indexterm2 ~flat_stream..flat_stream] 10569Destructor. 10570[heading Synopsis] 10571``` 10572~flat_stream(); 10573``` 10574 10575[heading Description] 10576The treatment of pending operations will be the same as that of the next layer. [endsect] 10577 10578 10579 10580Convenience header [include_file boost/beast/core.hpp] 10581 10582[endsect] 10583 10584 10585 10586[section:boost__beast__generic_category generic_category] 10587[indexterm1 generic_category] 10588A function to return the generic error category used by the library. 10589[heading Synopsis] 10590 10591Defined in header [include_file boost/beast/core/error.hpp] 10592 10593 10594 10595``` 10596error_category const & 10597generic_category(); 10598 10599``` 10600 10601[heading Description] 10602 10603 10604 10605Convenience header [include_file boost/beast/core.hpp] 10606 10607[endsect] 10608[section:boost__beast__get_lowest_layer get_lowest_layer] 10609[indexterm1 get_lowest_layer] 10610Return the lowest layer in a stack of stream layers. 10611[heading Synopsis] 10612 10613Defined in header [include_file boost/beast/core/stream_traits.hpp] 10614 10615 10616 10617``` 10618template< 10619 class T> 10620lowest_layer_type< T >& 10621get_lowest_layer( 10622 T& t); 10623 10624``` 10625 10626[heading Description] 10627If `t.next_layer()` is well-defined, returns `get_lowest_layer(t.next_layer())`. Otherwise, it returns `t`. 10628A stream layer is an object of class type which wraps another object through composition, and meets some or all of the named requirements of the wrapped type while optionally changing behavior. Examples of stream layers include `net::ssl::stream` or [link beast.ref.boost__beast__websocket__stream `websocket::stream`]. The owner of a stream layer can interact directly with the wrapper, by passing it to stream algorithms. Or, the owner can obtain a reference to the wrapped object by calling `next_layer()` and accessing its members. This is necessary when it is desired to access functionality in the next layer which is not available in the wrapper. For example, [link beast.ref.boost__beast__websocket__stream `websocket::stream`] permits reading and writing, but in order to establish the underlying connection, members of the wrapped stream (such as `connect`) must be invoked directly. 10629Usually the last object in the chain of composition is the concrete socket object (for example, a `net::basic_socket` or a class derived from it). The function [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`] exists to easily obtain the concrete socket when it is desired to perform an action that is not prescribed by a named requirement, such as changing a socket option, cancelling all pending asynchronous I/O, or closing the socket (perhaps by using [link beast.ref.boost__beast__close_socket `close_socket`]). 10630[heading Example] 10631 10632``` 10633 // Set non-blocking mode on a stack of stream 10634 // layers with a regular socket at the lowest layer. 10635 template <class Stream> 10636 void set_non_blocking (Stream& stream) 10637 { 10638 error_code ec; 10639 // A compile error here means your lowest layer is not the right type! 10640 get_lowest_layer(stream).non_blocking(true, ec); 10641 if(ec) 10642 throw system_error{ec}; 10643 } 10644``` 10645[heading Parameters] 10646[table [[Name][Description]] 10647 [[`t`][ 10648 10649The layer in a stack of layered objects for which the lowest layer is returned. 10650 ]] 10651] 10652[heading See Also] 10653[link beast.ref.boost__beast__close_socket `close_socket`], [link beast.ref.boost__beast__lowest_layer_type `lowest_layer_type`] 10654 10655 10656 10657Convenience header [include_file boost/beast/core.hpp] 10658 10659[endsect] 10660[section:boost__beast__has_get_executor has_get_executor] 10661[indexterm1 has_get_executor] 10662Determine if `T` has the `get_executor` member function. 10663[heading Synopsis] 10664 10665Defined in header [include_file boost/beast/core/stream_traits.hpp] 10666 10667 10668 10669``` 10670template< 10671 class T> 10672using has_get_executor = ``['see-below]``; 10673``` 10674 10675[heading Description] 10676Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` has the member function with the correct signature, else type will be `std::false_type`. 10677[heading Example] 10678 10679Use with tag dispatching: 10680 10681``` 10682 template<class T> 10683 void maybe_hello(T const& t, std::true_type) 10684 { 10685 net::post( 10686 t.get_executor(), 10687 [] 10688 { 10689 std::cout << "Hello, world!" << std::endl; 10690 }); 10691 } 10692 10693 template<class T> 10694 void maybe_hello(T const&, std::false_type) 10695 { 10696 // T does not have get_executor 10697 } 10698 10699 template<class T> 10700 void maybe_hello(T const& t) 10701 { 10702 maybe_hello(t, has_get_executor<T>{}); 10703 } 10704``` 10705Use with `static_assert`: 10706 10707``` 10708 struct stream 10709 { 10710 using executor_type = net::io_context::executor_type; 10711 executor_type get_executor() noexcept; 10712 }; 10713 10714 static_assert(has_get_executor<stream>::value, "Missing get_executor member"); 10715``` 10716 10717 10718 10719Convenience header [include_file boost/beast/core.hpp] 10720 10721[endsect] 10722[section:boost__beast__http__async_read http::async_read] 10723[indexterm1 http::async_read] 10724Read a complete message asynchronously from a stream using a parser. ``` 10725template< 10726 class __AsyncReadStream__, 10727 class __DynamicBuffer__, 10728 bool isRequest, 10729 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 10730``__deduced__`` 10731``[link beast.ref.boost__beast__http__async_read.overload1 async_read]``( 10732 AsyncReadStream& stream, 10733 DynamicBuffer& buffer, 10734 basic_parser< isRequest >& parser, 10735 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 10736 ``[''''»''' [link beast.ref.boost__beast__http__async_read.overload1 more...]]`` 10737 10738``` 10739Read a complete message asynchronously from a stream. ``` 10740template< 10741 class __AsyncReadStream__, 10742 class __DynamicBuffer__, 10743 bool isRequest, 10744 class __Body__, 10745 class __Allocator__, 10746 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 10747``__deduced__`` 10748``[link beast.ref.boost__beast__http__async_read.overload2 async_read]``( 10749 AsyncReadStream& stream, 10750 DynamicBuffer& buffer, 10751 message< isRequest, Body, basic_fields< Allocator >>& msg, 10752 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 10753 ``[''''»''' [link beast.ref.boost__beast__http__async_read.overload2 more...]]`` 10754``` 10755[section:overload1 http::async_read (1 of 2 overloads)] 10756Read a complete message asynchronously from a stream using a parser. 10757[heading Synopsis] 10758 10759Defined in header [include_file boost/beast/http/read.hpp] 10760 10761 10762 10763``` 10764template< 10765 class __AsyncReadStream__, 10766 class __DynamicBuffer__, 10767 bool isRequest, 10768 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 10769``__deduced__`` 10770async_read( 10771 AsyncReadStream& stream, 10772 DynamicBuffer& buffer, 10773 basic_parser< isRequest >& parser, 10774 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 10775 10776``` 10777 10778[heading Description] 10779This function is used to asynchronously read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 10780 10781* [link beast.ref.boost__beast__http__basic_parser.is_done `http::basic_parser::is_done`] returns `true` 10782 10783 10784* An error occurs. 10785 10786This operation is implemented in terms of zero or more calls to the next layer's `async_read_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other reads until this operation completes. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 10787If the end of file error is received while reading from the stream, then the error returned from this function will be: 10788 10789* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 10790 10791 10792* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 10793 10794 10795* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 10796 10797[heading Parameters] 10798[table [[Name][Description]] 10799 [[`stream`][ 10800 10801The stream from which the data is to be read. The type must meet the ['AsyncReadStream] requirements. 10802 ]] 10803 [[`buffer`][ 10804 10805Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. The object must remain valid at least until the handler is called; ownership is not transferred. 10806 ]] 10807 [[`parser`][ 10808 10809The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. 10810 ]] 10811 [[`handler`][ 10812 10813The 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: 10814``` 10815 void handler( 10816 error_code const& error, // result of operation 10817 std::size_t bytes_transferred // the total number of bytes transferred from the stream 10818 ); 10819``` 10820Regardless 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 `net::post`. 10821 ]] 10822] 10823[heading Remarks] 10824The completion handler will receive as a parameter the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 10825 10826 10827 10828Convenience header [include_file boost/beast/http.hpp] 10829 10830[endsect] 10831[section:overload2 http::async_read (2 of 2 overloads)] 10832Read a complete message asynchronously from a stream. 10833[heading Synopsis] 10834 10835Defined in header [include_file boost/beast/http/read.hpp] 10836 10837 10838 10839``` 10840template< 10841 class __AsyncReadStream__, 10842 class __DynamicBuffer__, 10843 bool isRequest, 10844 class __Body__, 10845 class __Allocator__, 10846 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 10847``__deduced__`` 10848async_read( 10849 AsyncReadStream& stream, 10850 DynamicBuffer& buffer, 10851 message< isRequest, Body, basic_fields< Allocator >>& msg, 10852 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 10853 10854``` 10855 10856[heading Description] 10857This function is used to asynchronously read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__message `http::message`]. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 10858 10859* The entire message is read in. 10860 10861 10862* An error occurs. 10863 10864This operation is implemented in terms of zero or more calls to the next layer's `async_read_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other reads until this operation completes. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 10865If the end of file error is received while reading from the stream, then the error returned from this function will be: 10866 10867* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 10868 10869 10870* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 10871 10872 10873* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 10874 10875[heading Parameters] 10876[table [[Name][Description]] 10877 [[`stream`][ 10878 10879The stream from which the data is to be read. The type must meet the ['AsyncReadStream] requirements. 10880 ]] 10881 [[`buffer`][ 10882 10883Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. The object must remain valid at least until the handler is called; ownership is not transferred. 10884 ]] 10885 [[`msg`][ 10886 10887The container in which to store the message contents. This message container should not have previous contents, otherwise the behavior is undefined. The type must be meet the ['MoveAssignable] and ['MoveConstructible] requirements. The object must remain valid at least until the handler is called; ownership is not transferred. 10888 ]] 10889 [[`handler`][ 10890 10891The 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: 10892``` 10893 void handler( 10894 error_code const& error, // result of operation 10895 std::size_t bytes_transferred // the total number of bytes transferred from the stream 10896 ); 10897``` 10898Regardless 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 `net::post`. 10899 ]] 10900] 10901[heading Remarks] 10902The completion handler will receive as a parameter the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 10903 10904 10905 10906Convenience header [include_file boost/beast/http.hpp] 10907 10908[endsect] 10909[endsect] 10910 10911 10912 10913[section:boost__beast__http__async_read_header http::async_read_header] 10914[indexterm1 http::async_read_header] 10915Read a complete message header asynchronously from a stream using a parser. 10916[heading Synopsis] 10917 10918Defined in header [include_file boost/beast/http/read.hpp] 10919 10920 10921 10922``` 10923template< 10924 class __AsyncReadStream__, 10925 class __DynamicBuffer__, 10926 bool isRequest, 10927 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 10928``__deduced__`` 10929async_read_header( 10930 AsyncReadStream& stream, 10931 DynamicBuffer& buffer, 10932 basic_parser< isRequest >& parser, 10933 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 10934 10935``` 10936 10937[heading Description] 10938This function is used to asynchronously read a complete message header from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 10939 10940* [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] returns `true` 10941 10942 10943* An error occurs. 10944 10945This operation is implemented in terms of zero or more calls to the next layer's `async_read_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other reads until this operation completes. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 10946If the end of file error is received while reading from the stream, then the error returned from this function will be: 10947 10948* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 10949 10950 10951* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 10952 10953 10954* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 10955 10956[heading Parameters] 10957[table [[Name][Description]] 10958 [[`stream`][ 10959 10960The stream from which the data is to be read. The type must meet the ['AsyncReadStream] requirements. 10961 ]] 10962 [[`buffer`][ 10963 10964Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. The object must remain valid at least until the handler is called; ownership is not transferred. 10965 ]] 10966 [[`parser`][ 10967 10968The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. 10969 ]] 10970 [[`handler`][ 10971 10972The 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: 10973``` 10974 void handler( 10975 error_code const& error, // result of operation 10976 std::size_t bytes_transferred // the total number of bytes transferred from the stream 10977 ); 10978``` 10979Regardless 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 `net::post`. 10980 ]] 10981] 10982[heading Remarks] 10983The completion handler will receive as a parameter the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `false` on the parser passed in. 10984 10985 10986 10987Convenience header [include_file boost/beast/http.hpp] 10988 10989[endsect] 10990[section:boost__beast__http__async_read_some http::async_read_some] 10991[indexterm1 http::async_read_some] 10992Read part of a message asynchronously from a stream using a parser. 10993[heading Synopsis] 10994 10995Defined in header [include_file boost/beast/http/read.hpp] 10996 10997 10998 10999``` 11000template< 11001 class __AsyncReadStream__, 11002 class __DynamicBuffer__, 11003 bool isRequest, 11004 class __ReadHandler__ = net::default_completion_token_t< executor_type<AsyncReadStream>>> 11005``__deduced__`` 11006async_read_some( 11007 AsyncReadStream& stream, 11008 DynamicBuffer& buffer, 11009 basic_parser< isRequest >& parser, 11010 ReadHandler&& handler = net::default_completion_token_t< executor_type< AsyncReadStream >>{}); 11011 11012``` 11013 11014[heading Description] 11015This function is used to asynchronously read part of a message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 11016 11017* A call to [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] with a non-empty buffer sequence is successful. 11018 11019 11020* An error occurs. 11021 11022This operation is implemented in terms of zero or more calls to the next layer's `async_read_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other reads until this operation completes. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 11023If the end of file error is received while reading from the stream, then the error returned from this function will be: 11024 11025* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 11026 11027 11028* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 11029 11030 11031* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 11032 11033[heading Parameters] 11034[table [[Name][Description]] 11035 [[`stream`][ 11036 11037The stream from which the data is to be read. The type must meet the ['AsyncReadStream] requirements. 11038 ]] 11039 [[`buffer`][ 11040 11041Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. The object must remain valid at least until the handler is called; ownership is not transferred. 11042 ]] 11043 [[`parser`][ 11044 11045The parser to use. The object must remain valid at least until the handler is called; ownership is not transferred. 11046 ]] 11047 [[`handler`][ 11048 11049The 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: 11050``` 11051 void handler( 11052 error_code const& error, // result of operation 11053 std::size_t bytes_transferred // the total number of bytes transferred from the stream 11054 ); 11055``` 11056Regardless 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 `net::post`. 11057 ]] 11058] 11059[heading Remarks] 11060The completion handler will receive as a parameter the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. 11061 11062 11063 11064Convenience header [include_file boost/beast/http.hpp] 11065 11066[endsect] 11067[section:boost__beast__http__async_write http::async_write] 11068[indexterm1 http::async_write] 11069Write a complete message to a stream asynchronously using a serializer. ``` 11070template< 11071 class __AsyncWriteStream__, 11072 bool isRequest, 11073 class __Body__, 11074 class __Fields__, 11075 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11076``__deduced__`` 11077``[link beast.ref.boost__beast__http__async_write.overload1 async_write]``( 11078 AsyncWriteStream& stream, 11079 serializer< isRequest, Body, Fields >& sr, 11080 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11081 ``[''''»''' [link beast.ref.boost__beast__http__async_write.overload1 more...]]`` 11082 11083``` 11084Write a complete message to a stream asynchronously. ``` 11085template< 11086 class __AsyncWriteStream__, 11087 bool isRequest, 11088 class __Body__, 11089 class __Fields__, 11090 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11091``__deduced__`` 11092``[link beast.ref.boost__beast__http__async_write.overload2 async_write]``( 11093 AsyncWriteStream& stream, 11094 message< isRequest, Body, Fields >& msg, 11095 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11096 ``[''''»''' [link beast.ref.boost__beast__http__async_write.overload2 more...]]`` 11097 11098template< 11099 class __AsyncWriteStream__, 11100 bool isRequest, 11101 class __Body__, 11102 class __Fields__, 11103 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11104``__deduced__`` 11105``[link beast.ref.boost__beast__http__async_write.overload3 async_write]``( 11106 AsyncWriteStream& stream, 11107 message< isRequest, Body, Fields > const& msg, 11108 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11109 ``[''''»''' [link beast.ref.boost__beast__http__async_write.overload3 more...]]`` 11110``` 11111[section:overload1 http::async_write (1 of 3 overloads)] 11112Write a complete message to a stream asynchronously using a serializer. 11113[heading Synopsis] 11114 11115Defined in header [include_file boost/beast/http/write.hpp] 11116 11117 11118 11119``` 11120template< 11121 class __AsyncWriteStream__, 11122 bool isRequest, 11123 class __Body__, 11124 class __Fields__, 11125 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11126``__deduced__`` 11127async_write( 11128 AsyncWriteStream& stream, 11129 serializer< isRequest, Body, Fields >& sr, 11130 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11131 11132``` 11133 11134[heading Description] 11135This 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: 11136 11137* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 11138 11139 11140* An error occurs. 11141 11142This operation is implemented in terms of zero or more calls to the stream's `async_write_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other writes until this operation completes. 11143[heading Parameters] 11144[table [[Name][Description]] 11145 [[`stream`][ 11146 11147The stream to which the data is to be written. The type must support the ['AsyncWriteStream] concept. 11148 ]] 11149 [[`sr`][ 11150 11151The serializer to use. The object must remain valid at least until the handler is called; ownership is not transferred. 11152 ]] 11153 [[`handler`][ 11154 11155The 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: 11156``` 11157 void handler( 11158 error_code const& error, // result of operation 11159 std::size_t bytes_transferred // the number of bytes written to the stream 11160 ); 11161``` 11162Regardless 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 `net::post`. 11163 ]] 11164] 11165[heading See Also] 11166[link beast.ref.boost__beast__http__serializer `http::serializer`] 11167 11168 11169 11170Convenience header [include_file boost/beast/http.hpp] 11171 11172[endsect] 11173[section:overload2 http::async_write (2 of 3 overloads)] 11174Write a complete message to a stream asynchronously. 11175[heading Synopsis] 11176 11177Defined in header [include_file boost/beast/http/write.hpp] 11178 11179 11180 11181``` 11182template< 11183 class __AsyncWriteStream__, 11184 bool isRequest, 11185 class __Body__, 11186 class __Fields__, 11187 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11188``__deduced__`` 11189async_write( 11190 AsyncWriteStream& stream, 11191 message< isRequest, Body, Fields >& msg, 11192 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11193 11194``` 11195 11196[heading Description] 11197This 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: 11198 11199* The entire message is written. 11200 11201 11202* An error occurs. 11203 11204This operation is implemented in terms of zero or more calls to the stream's `async_write_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other writes until this operation completes. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 11205[heading Remarks] 11206This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `true`. 11207[heading Parameters] 11208[table [[Name][Description]] 11209 [[`stream`][ 11210 11211The stream to which the data is to be written. The type must support the ['AsyncWriteStream] concept. 11212 ]] 11213 [[`msg`][ 11214 11215The message to write. The object must remain valid at least until the handler is called; ownership is not transferred. 11216 ]] 11217 [[`handler`][ 11218 11219The 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: 11220``` 11221 void handler( 11222 error_code const& error, // result of operation 11223 std::size_t bytes_transferred // the number of bytes written to the stream 11224 ); 11225``` 11226Regardless 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 `net::post`. 11227 ]] 11228] 11229[heading See Also] 11230[link beast.ref.boost__beast__http__message `http::message`] 11231 11232 11233 11234Convenience header [include_file boost/beast/http.hpp] 11235 11236[endsect] 11237[section:overload3 http::async_write (3 of 3 overloads)] 11238Write a complete message to a stream asynchronously. 11239[heading Synopsis] 11240 11241Defined in header [include_file boost/beast/http/write.hpp] 11242 11243 11244 11245``` 11246template< 11247 class __AsyncWriteStream__, 11248 bool isRequest, 11249 class __Body__, 11250 class __Fields__, 11251 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11252``__deduced__`` 11253async_write( 11254 AsyncWriteStream& stream, 11255 message< isRequest, Body, Fields > const& msg, 11256 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11257 11258``` 11259 11260[heading Description] 11261This 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: 11262 11263* The entire message is written. 11264 11265 11266* An error occurs. 11267 11268This operation is implemented in terms of zero or more calls to the stream's `async_write_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other writes until this operation completes. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 11269[heading Remarks] 11270This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `false`. 11271[heading Parameters] 11272[table [[Name][Description]] 11273 [[`stream`][ 11274 11275The stream to which the data is to be written. The type must support the ['AsyncWriteStream] concept. 11276 ]] 11277 [[`msg`][ 11278 11279The message to write. The object must remain valid at least until the handler is called; ownership is not transferred. 11280 ]] 11281 [[`handler`][ 11282 11283The 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: 11284``` 11285 void handler( 11286 error_code const& error, // result of operation 11287 std::size_t bytes_transferred // the number of bytes written to the stream 11288 ); 11289``` 11290Regardless 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 `net::post`. 11291 ]] 11292] 11293[heading See Also] 11294[link beast.ref.boost__beast__http__message `http::message`] 11295 11296 11297 11298Convenience header [include_file boost/beast/http.hpp] 11299 11300[endsect] 11301[endsect] 11302 11303 11304 11305[section:boost__beast__http__async_write_header http::async_write_header] 11306[indexterm1 http::async_write_header] 11307Write a header to a stream asynchronously using a serializer. 11308[heading Synopsis] 11309 11310Defined in header [include_file boost/beast/http/write.hpp] 11311 11312 11313 11314``` 11315template< 11316 class __AsyncWriteStream__, 11317 bool isRequest, 11318 class __Body__, 11319 class __Fields__, 11320 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11321``__deduced__`` 11322async_write_header( 11323 AsyncWriteStream& stream, 11324 serializer< isRequest, Body, Fields >& sr, 11325 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11326 11327``` 11328 11329[heading Description] 11330This 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: 11331 11332* The function [link beast.ref.boost__beast__http__serializer.is_header_done `http::serializer::is_header_done`] returns `true` 11333 11334 11335* An error occurs. 11336 11337This operation is implemented in terms of zero or more calls to the stream's `async_write_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other writes until this operation completes. 11338[heading Parameters] 11339[table [[Name][Description]] 11340 [[`stream`][ 11341 11342The stream to which the data is to be written. The type must support the ['AsyncWriteStream] concept. 11343 ]] 11344 [[`sr`][ 11345 11346The serializer to use. The object must remain valid at least until the handler is called; ownership is not transferred. 11347 ]] 11348 [[`handler`][ 11349 11350The 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: 11351``` 11352 void handler( 11353 error_code const& error, // result of operation 11354 std::size_t bytes_transferred // the number of bytes written to the stream 11355 ); 11356``` 11357Regardless 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 `net::post`. 11358 ]] 11359] 11360[heading Remarks] 11361The implementation will call [link beast.ref.boost__beast__http__serializer.split `http::serializer::split`] with the value `true` on the serializer passed in. 11362[heading See Also] 11363[link beast.ref.boost__beast__http__serializer `http::serializer`] 11364 11365 11366 11367Convenience header [include_file boost/beast/http.hpp] 11368 11369[endsect] 11370[section:boost__beast__http__async_write_some http::async_write_some] 11371[indexterm1 http::async_write_some] 11372Write part of a message to a stream asynchronously using a serializer. 11373[heading Synopsis] 11374 11375Defined in header [include_file boost/beast/http/write.hpp] 11376 11377 11378 11379``` 11380template< 11381 class __AsyncWriteStream__, 11382 bool isRequest, 11383 class __Body__, 11384 class __Fields__, 11385 class __WriteHandler__ = net::default_completion_token_t< executor_type<AsyncWriteStream>>> 11386``__deduced__`` 11387async_write_some( 11388 AsyncWriteStream& stream, 11389 serializer< isRequest, Body, Fields >& sr, 11390 WriteHandler&& handler = net::default_completion_token_t< executor_type< AsyncWriteStream >>{}); 11391 11392``` 11393 11394[heading Description] 11395This 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: 11396 11397* One or more bytes have been transferred. 11398 11399 11400* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 11401 11402 11403* An error occurs on the stream. 11404 11405This operation is implemented in terms of zero or more calls to the stream's `async_write_some` function, and is known as a ['composed operation]. The program must ensure that the stream performs no other writes until this operation completes. 11406The 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 [link beast.ref.boost__beast__http__serializer.limit `http::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. 11407[heading Parameters] 11408[table [[Name][Description]] 11409 [[`stream`][ 11410 11411The stream to which the data is to be written. The type must support the ['AsyncWriteStream] concept. 11412 ]] 11413 [[`sr`][ 11414 11415The serializer to use. The object must remain valid at least until the handler is called; ownership is not transferred. 11416 ]] 11417 [[`handler`][ 11418 11419The 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: 11420``` 11421 void handler( 11422 error_code const& error, // result of operation 11423 std::size_t bytes_transferred // the number of bytes written to the stream 11424 ); 11425``` 11426Regardless 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 `net::post`. 11427 ]] 11428] 11429[heading See Also] 11430[link beast.ref.boost__beast__http__serializer `http::serializer`] 11431 11432 11433 11434Convenience header [include_file boost/beast/http.hpp] 11435 11436[endsect] 11437[section:boost__beast__http__basic_chunk_extensions http::basic_chunk_extensions] 11438A set of chunk extensions. 11439[heading Synopsis] 11440 11441Defined in header [include_file boost/beast/http/chunk_encode.hpp] 11442 11443 11444 11445``` 11446template< 11447 class __Allocator__> 11448class basic_chunk_extensions 11449``` 11450[heading Types] 11451[table [[Name][Description]] 11452 [ 11453 [[link beast.ref.boost__beast__http__basic_chunk_extensions.value_type [*value_type]]] 11454 [ 11455 The type of value when iterating. 11456 ] 11457 ] 11458] 11459[heading Member Functions] 11460[table [[Name][Description]] 11461 [ 11462 [[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions [*basic_chunk_extensions]]] 11463 [ 11464 Constructor. 11465 ] 11466 ] 11467 [ 11468 [[link beast.ref.boost__beast__http__basic_chunk_extensions.begin [*begin]]] 11469 [ 11470 11471 ] 11472 ] 11473 [ 11474 [[link beast.ref.boost__beast__http__basic_chunk_extensions.clear [*clear]]] 11475 [ 11476 Clear the chunk extensions. 11477 ] 11478 ] 11479 [ 11480 [[link beast.ref.boost__beast__http__basic_chunk_extensions.end [*end]]] 11481 [ 11482 11483 ] 11484 ] 11485 [ 11486 [[link beast.ref.boost__beast__http__basic_chunk_extensions.insert [*insert]]] 11487 [ 11488 Insert an extension name with an empty value. 11489 11490 Insert an extension value. 11491 ] 11492 ] 11493 [ 11494 [[link beast.ref.boost__beast__http__basic_chunk_extensions.parse [*parse]]] 11495 [ 11496 Parse a set of chunk extensions. 11497 ] 11498 ] 11499 [ 11500 [[link beast.ref.boost__beast__http__basic_chunk_extensions.str [*str]]] 11501 [ 11502 Return the serialized representation of the chunk extension. 11503 ] 11504 ] 11505] 11506 11507[heading Description] 11508This container stores a set of chunk extensions suited for use with [link beast.ref.boost__beast__http__chunk_header `http::chunk_header`] and [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`]. The container may be iterated to access the extensions in their structured form. 11509Meets the requirements of ChunkExtensions [section:basic_chunk_extensions http::basic_chunk_extensions::basic_chunk_extensions] 11510[indexterm2 basic_chunk_extensions..http::basic_chunk_extensions] 11511Constructor. ``` 11512``[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload1 basic_chunk_extensions]``(); 11513 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload1 more...]]`` 11514 11515``[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload2 basic_chunk_extensions]``( 11516 basic_chunk_extensions&&); 11517 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload2 more...]]`` 11518 11519``[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload3 basic_chunk_extensions]``( 11520 basic_chunk_extensions const&); 11521 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload3 more...]]`` 11522 11523explicit 11524``[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload4 basic_chunk_extensions]``( 11525 Allocator const& allocator); 11526 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions.overload4 more...]]`` 11527``` 11528[section:overload1 http::basic_chunk_extensions::basic_chunk_extensions (1 of 4 overloads)] 11529Constructor. 11530[heading Synopsis] 11531``` 11532basic_chunk_extensions(); 11533``` 11534 11535[heading Description] 11536[endsect] 11537[section:overload2 http::basic_chunk_extensions::basic_chunk_extensions (2 of 4 overloads)] 11538Constructor. 11539[heading Synopsis] 11540``` 11541basic_chunk_extensions( 11542 basic_chunk_extensions&&); 11543``` 11544 11545[heading Description] 11546[endsect] 11547[section:overload3 http::basic_chunk_extensions::basic_chunk_extensions (3 of 4 overloads)] 11548Constructor. 11549[heading Synopsis] 11550``` 11551basic_chunk_extensions( 11552 basic_chunk_extensions const&); 11553``` 11554 11555[heading Description] 11556[endsect] 11557[section:overload4 http::basic_chunk_extensions::basic_chunk_extensions (4 of 4 overloads)] 11558Constructor. 11559[heading Synopsis] 11560``` 11561basic_chunk_extensions( 11562 Allocator const& allocator); 11563``` 11564 11565[heading Description] 11566[heading Parameters] 11567[table [[Name][Description]] 11568 [[`allocator`][ 11569 11570The allocator to use for storing the serialized extension 11571 ]] 11572] 11573[endsect] 11574[endsect] 11575 11576[section:begin http::basic_chunk_extensions::begin] 11577[indexterm2 begin..http::basic_chunk_extensions] 11578 11579[heading Synopsis] 11580``` 11581const_iterator 11582begin() const; 11583``` 11584 11585[heading Description] 11586[endsect] 11587[section:clear http::basic_chunk_extensions::clear] 11588[indexterm2 clear..http::basic_chunk_extensions] 11589Clear the chunk extensions. 11590[heading Synopsis] 11591``` 11592void 11593clear(); 11594``` 11595 11596[heading Description] 11597This preserves the capacity of the internal string used to hold the serialized representation. [endsect] 11598[section:end http::basic_chunk_extensions::end] 11599[indexterm2 end..http::basic_chunk_extensions] 11600 11601[heading Synopsis] 11602``` 11603const_iterator 11604end() const; 11605``` 11606 11607[heading Description] 11608[endsect] 11609[section:insert http::basic_chunk_extensions::insert] 11610[indexterm2 insert..http::basic_chunk_extensions] 11611Insert an extension name with an empty value. ``` 11612void 11613``[link beast.ref.boost__beast__http__basic_chunk_extensions.insert.overload1 insert]``( 11614 string_view name); 11615 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.insert.overload1 more...]]`` 11616 11617``` 11618Insert an extension value. ``` 11619void 11620``[link beast.ref.boost__beast__http__basic_chunk_extensions.insert.overload2 insert]``( 11621 string_view name, 11622 string_view value); 11623 ``[''''»''' [link beast.ref.boost__beast__http__basic_chunk_extensions.insert.overload2 more...]]`` 11624``` 11625[section:overload1 http::basic_chunk_extensions::insert (1 of 2 overloads)] 11626Insert an extension name with an empty value. 11627[heading Synopsis] 11628``` 11629void 11630insert( 11631 string_view name); 11632``` 11633 11634[heading Description] 11635[heading Parameters] 11636[table [[Name][Description]] 11637 [[`name`][ 11638 11639The name of the extension 11640 ]] 11641] 11642[endsect] 11643[section:overload2 http::basic_chunk_extensions::insert (2 of 2 overloads)] 11644Insert an extension value. 11645[heading Synopsis] 11646``` 11647void 11648insert( 11649 string_view name, 11650 string_view value); 11651``` 11652 11653[heading Description] 11654[heading Parameters] 11655[table [[Name][Description]] 11656 [[`name`][ 11657 11658The name of the extension 11659 ]] 11660 [[`value`][ 11661 11662The value to insert. Depending on the contents, the serialized extension may use a quoted string. 11663 ]] 11664] 11665[endsect] 11666[endsect] 11667 11668[section:parse http::basic_chunk_extensions::parse] 11669[indexterm2 parse..http::basic_chunk_extensions] 11670Parse a set of chunk extensions. 11671[heading Synopsis] 11672``` 11673void 11674parse( 11675 string_view s, 11676 error_code& ec); 11677``` 11678 11679[heading Description] 11680Any previous extensions will be cleared [endsect] 11681[section:str http::basic_chunk_extensions::str] 11682[indexterm2 str..http::basic_chunk_extensions] 11683Return the serialized representation of the chunk extension. 11684[heading Synopsis] 11685``` 11686string_view 11687str() const; 11688``` 11689 11690[heading Description] 11691[endsect] 11692[section:value_type http::basic_chunk_extensions::value_type] 11693[indexterm2 value_type..http::basic_chunk_extensions] 11694The type of value when iterating. 11695[heading Synopsis] 11696 11697``` 11698using value_type = std::pair< string_view, string_view >; 11699``` 11700 11701[heading Description] 11702The first element of the pair is the name, and the second element is the value which may be empty. The value is stored in its raw representation, without quotes or escapes. [endsect] 11703 11704 11705 11706Convenience header [include_file boost/beast/http.hpp] 11707 11708[endsect] 11709 11710 11711 11712[section:boost__beast__http__basic_dynamic_body http::basic_dynamic_body] 11713A ['Body] using a ['DynamicBuffer] 11714[heading Synopsis] 11715 11716Defined in header [include_file boost/beast/http/basic_dynamic_body.hpp] 11717 11718 11719 11720``` 11721template< 11722 class __DynamicBuffer__> 11723struct basic_dynamic_body 11724``` 11725[heading Types] 11726[table [[Name][Description]] 11727 [ 11728 [[link beast.ref.boost__beast__http__basic_dynamic_body.reader [*reader]]] 11729 [ 11730 The algorithm for parsing the body. 11731 ] 11732 ] 11733 [ 11734 [[link beast.ref.boost__beast__http__basic_dynamic_body.value_type [*value_type]]] 11735 [ 11736 The type of container used for the body. 11737 ] 11738 ] 11739 [ 11740 [[link beast.ref.boost__beast__http__basic_dynamic_body.writer [*writer]]] 11741 [ 11742 The algorithm for serializing the body. 11743 ] 11744 ] 11745] 11746[heading Member Functions] 11747[table [[Name][Description]] 11748 [ 11749 [[link beast.ref.boost__beast__http__basic_dynamic_body.size [*size]]] 11750 [ 11751 Returns the payload size of the body. 11752 ] 11753 ] 11754] 11755 11756[heading Description] 11757This body uses a ['DynamicBuffer] as a memory-based container for holding message payloads. Messages using this body type may be serialized and parsed. [section:reader http::basic_dynamic_body::reader] 11758[indexterm2 reader..http::basic_dynamic_body] 11759The algorithm for parsing the body. 11760[heading Synopsis] 11761 11762``` 11763using reader = ``['implementation-defined]``; 11764``` 11765 11766[heading Description] 11767Meets the requirements of ['BodyReader]. [endsect] 11768[section:size http::basic_dynamic_body::size] 11769[indexterm2 size..http::basic_dynamic_body] 11770Returns the payload size of the body. 11771[heading Synopsis] 11772``` 11773static 11774std::uint64_t 11775size( 11776 value_type const& v); 11777``` 11778 11779[heading Description] 11780When this body is used with [link beast.ref.boost__beast__http__message.prepare_payload `http::message::prepare_payload`], the Content-Length will be set to the payload size, and any chunked Transfer-Encoding will be removed. [endsect] 11781[section:value_type http::basic_dynamic_body::value_type] 11782[indexterm2 value_type..http::basic_dynamic_body] 11783The type of container used for the body. 11784[heading Synopsis] 11785 11786``` 11787using value_type = DynamicBuffer; 11788``` 11789 11790[heading Description] 11791This determines the type of [link beast.ref.boost__beast__http__message.body `http::message::body`] when this body type is used with a message container. [endsect] 11792[section:writer http::basic_dynamic_body::writer] 11793[indexterm2 writer..http::basic_dynamic_body] 11794The algorithm for serializing the body. 11795[heading Synopsis] 11796 11797``` 11798using writer = ``['implementation-defined]``; 11799``` 11800 11801[heading Description] 11802Meets the requirements of ['BodyWriter]. [endsect] 11803 11804 11805 11806Convenience header [include_file boost/beast/http.hpp] 11807 11808[endsect] 11809 11810 11811 11812[section:boost__beast__http__basic_fields http::basic_fields] 11813A container for storing HTTP header fields. 11814[heading Synopsis] 11815 11816Defined in header [include_file boost/beast/http/fields.hpp] 11817 11818 11819 11820``` 11821template< 11822 class __Allocator__> 11823class basic_fields 11824``` 11825[heading Types] 11826[table [[Name][Description]] 11827 [ 11828 [[link beast.ref.boost__beast__http__basic_fields.allocator_type [*allocator_type]]] 11829 [ 11830 The type of allocator used. 11831 ] 11832 ] 11833 [ 11834 [[link beast.ref.boost__beast__http__basic_fields__value_type [*value_type]]] 11835 [ 11836 The type of element used to represent a field. 11837 ] 11838 ] 11839 [ 11840 [[link beast.ref.boost__beast__http__basic_fields.const_iterator [*const_iterator]]] 11841 [ 11842 A constant iterator to the field sequence. 11843 ] 11844 ] 11845 [ 11846 [[link beast.ref.boost__beast__http__basic_fields.iterator [*iterator]]] 11847 [ 11848 A constant iterator to the field sequence. 11849 ] 11850 ] 11851 [ 11852 [[link beast.ref.boost__beast__http__basic_fields.key_compare [*key_compare]]] 11853 [ 11854 A strictly less predicate for comparing keys, using a case-insensitive comparison. 11855 ] 11856 ] 11857 [ 11858 [[link beast.ref.boost__beast__http__basic_fields.writer [*writer]]] 11859 [ 11860 The algorithm used to serialize the header. 11861 ] 11862 ] 11863] 11864[heading Member Functions] 11865[table [[Name][Description]] 11866 [ 11867 [[link beast.ref.boost__beast__http__basic_fields.at [*at]]] 11868 [ 11869 Returns the value for a field, or throws an exception. 11870 ] 11871 ] 11872 [ 11873 [[link beast.ref.boost__beast__http__basic_fields.basic_fields [*basic_fields]]] 11874 [ 11875 Constructor. 11876 11877 Move constructor. 11878 11879 Copy constructor. 11880 ] 11881 ] 11882 [ 11883 [[link beast.ref.boost__beast__http__basic_fields.begin [*begin]]] 11884 [ 11885 Return a const iterator to the beginning of the field sequence. 11886 ] 11887 ] 11888 [ 11889 [[link beast.ref.boost__beast__http__basic_fields.cbegin [*cbegin]]] 11890 [ 11891 Return a const iterator to the beginning of the field sequence. 11892 ] 11893 ] 11894 [ 11895 [[link beast.ref.boost__beast__http__basic_fields.cend [*cend]]] 11896 [ 11897 Return a const iterator to the end of the field sequence. 11898 ] 11899 ] 11900 [ 11901 [[link beast.ref.boost__beast__http__basic_fields.clear [*clear]]] 11902 [ 11903 Remove all fields from the container. 11904 ] 11905 ] 11906 [ 11907 [[link beast.ref.boost__beast__http__basic_fields.count [*count]]] 11908 [ 11909 Return the number of fields with the specified name. 11910 ] 11911 ] 11912 [ 11913 [[link beast.ref.boost__beast__http__basic_fields.end [*end]]] 11914 [ 11915 Return a const iterator to the end of the field sequence. 11916 ] 11917 ] 11918 [ 11919 [[link beast.ref.boost__beast__http__basic_fields.equal_range [*equal_range]]] 11920 [ 11921 Returns a range of iterators to the fields with the specified name. 11922 ] 11923 ] 11924 [ 11925 [[link beast.ref.boost__beast__http__basic_fields.erase [*erase]]] 11926 [ 11927 Remove a field. 11928 11929 Remove all fields with the specified name. 11930 ] 11931 ] 11932 [ 11933 [[link beast.ref.boost__beast__http__basic_fields.find [*find]]] 11934 [ 11935 Returns an iterator to the case-insensitive matching field. 11936 11937 Returns an iterator to the case-insensitive matching field name. 11938 ] 11939 ] 11940 [ 11941 [[link beast.ref.boost__beast__http__basic_fields.get_allocator [*get_allocator]]] 11942 [ 11943 Return a copy of the allocator associated with the container. 11944 ] 11945 ] 11946 [ 11947 [[link beast.ref.boost__beast__http__basic_fields.insert [*insert]]] 11948 [ 11949 Insert a field. 11950 ] 11951 ] 11952 [ 11953 [[link beast.ref.boost__beast__http__basic_fields.key_comp [*key_comp]]] 11954 [ 11955 Returns a copy of the key comparison function. 11956 ] 11957 ] 11958 [ 11959 [[link beast.ref.boost__beast__http__basic_fields.operator_eq_ [*operator=]]] 11960 [ 11961 Move assignment. 11962 11963 Copy assignment. 11964 ] 11965 ] 11966 [ 11967 [[link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_ [*operator\[\]]]] 11968 [ 11969 Returns the value for a field, or "" if it does not exist. 11970 11971 Returns the value for a case-insensitive matching header, or "" if it does not exist. 11972 ] 11973 ] 11974 [ 11975 [[link beast.ref.boost__beast__http__basic_fields.set [*set]]] 11976 [ 11977 Set a field value, removing any other instances of that field. 11978 ] 11979 ] 11980 [ 11981 [[link beast.ref.boost__beast__http__basic_fields.swap [*swap]]] 11982 [ 11983 Return a buffer sequence representing the trailers. 11984 ] 11985 ] 11986 [ 11987 [[link beast.ref.boost__beast__http__basic_fields.basic_fields_dtor_ [*~basic_fields]]] 11988 [ 11989 Destructor. 11990 ] 11991 ] 11992] 11993[heading Protected Member Functions] 11994[table [[Name][Description]] 11995 [ 11996 [[link beast.ref.boost__beast__http__basic_fields.get_chunked_impl [*get_chunked_impl]]] 11997 [ 11998 Returns the chunked Transfer-Encoding setting. 11999 ] 12000 ] 12001 [ 12002 [[link beast.ref.boost__beast__http__basic_fields.get_keep_alive_impl [*get_keep_alive_impl]]] 12003 [ 12004 Returns the keep-alive setting. 12005 ] 12006 ] 12007 [ 12008 [[link beast.ref.boost__beast__http__basic_fields.get_method_impl [*get_method_impl]]] 12009 [ 12010 Returns the request-method string. 12011 ] 12012 ] 12013 [ 12014 [[link beast.ref.boost__beast__http__basic_fields.get_reason_impl [*get_reason_impl]]] 12015 [ 12016 Returns the response reason-phrase string. 12017 ] 12018 ] 12019 [ 12020 [[link beast.ref.boost__beast__http__basic_fields.get_target_impl [*get_target_impl]]] 12021 [ 12022 Returns the request-target string. 12023 ] 12024 ] 12025 [ 12026 [[link beast.ref.boost__beast__http__basic_fields.has_content_length_impl [*has_content_length_impl]]] 12027 [ 12028 Returns true if the Content-Length field is present. 12029 ] 12030 ] 12031 [ 12032 [[link beast.ref.boost__beast__http__basic_fields.set_chunked_impl [*set_chunked_impl]]] 12033 [ 12034 Adjusts the chunked Transfer-Encoding value. 12035 ] 12036 ] 12037 [ 12038 [[link beast.ref.boost__beast__http__basic_fields.set_content_length_impl [*set_content_length_impl]]] 12039 [ 12040 Sets or clears the Content-Length field. 12041 ] 12042 ] 12043 [ 12044 [[link beast.ref.boost__beast__http__basic_fields.set_keep_alive_impl [*set_keep_alive_impl]]] 12045 [ 12046 Adjusts the Connection field. 12047 ] 12048 ] 12049 [ 12050 [[link beast.ref.boost__beast__http__basic_fields.set_method_impl [*set_method_impl]]] 12051 [ 12052 Set or clear the method string. 12053 ] 12054 ] 12055 [ 12056 [[link beast.ref.boost__beast__http__basic_fields.set_reason_impl [*set_reason_impl]]] 12057 [ 12058 Set or clear the reason string. 12059 ] 12060 ] 12061 [ 12062 [[link beast.ref.boost__beast__http__basic_fields.set_target_impl [*set_target_impl]]] 12063 [ 12064 Set or clear the target string. 12065 ] 12066 ] 12067] 12068[heading Friends] 12069[table [[Name][Description]] 12070 [ 12071 [[link beast.ref.boost__beast__http__basic_fields.swap [*swap]]] 12072 [ 12073 Swap two field containers. 12074 ] 12075 ] 12076] 12077 12078[heading Description] 12079This container is designed to store the field value pairs that make up the fields and trailers in an HTTP message. Objects of this type are iterable, with each element holding the field name and field value. 12080Field names are stored as-is, but comparisons are case-insensitive. The container behaves as a `std::multiset`; there will be a separate value for each occurrence of the same field name. When the container is iterated the fields are presented in the order of insertion, with fields having the same name following each other consecutively. 12081Meets the requirements of ['Fields] 12082[heading Template Parameters] 12083[table [[Type][Description]] 12084 [[`Allocator`][ 12085 12086The allocator to use. 12087 ]] 12088] 12089[section:allocator_type http::basic_fields::allocator_type] 12090[indexterm2 allocator_type..http::basic_fields] 12091The type of allocator used. 12092[heading Synopsis] 12093 12094``` 12095using allocator_type = Allocator; 12096``` 12097 12098[heading Description] 12099[endsect] 12100[section:at http::basic_fields::at] 12101[indexterm2 at..http::basic_fields] 12102Returns the value for a field, or throws an exception. ``` 12103string_view const 12104``[link beast.ref.boost__beast__http__basic_fields.at.overload1 at]``( 12105 field name) const; 12106 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.at.overload1 more...]]`` 12107 12108string_view const 12109``[link beast.ref.boost__beast__http__basic_fields.at.overload2 at]``( 12110 string_view name) const; 12111 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.at.overload2 more...]]`` 12112``` 12113[section:overload1 http::basic_fields::at (1 of 2 overloads)] 12114Returns the value for a field, or throws an exception. 12115[heading Synopsis] 12116``` 12117string_view const 12118at( 12119 field name) const; 12120``` 12121 12122[heading Description] 12123If more than one field with the specified name exists, the first field defined by insertion order is returned. 12124[heading Parameters] 12125[table [[Name][Description]] 12126 [[`name`][ 12127 12128The name of the field. 12129 ]] 12130] 12131[heading Return Value] 12132The field value. 12133[heading Exceptions] 12134[table [[Type][Thrown On]] 12135 [[`std::out_of_range`][ 12136 12137if the field is not found. 12138 ]] 12139] 12140[endsect] 12141[section:overload2 http::basic_fields::at (2 of 2 overloads)] 12142Returns the value for a field, or throws an exception. 12143[heading Synopsis] 12144``` 12145string_view const 12146at( 12147 string_view name) const; 12148``` 12149 12150[heading Description] 12151If more than one field with the specified name exists, the first field defined by insertion order is returned. 12152[heading Parameters] 12153[table [[Name][Description]] 12154 [[`name`][ 12155 12156The name of the field. 12157 ]] 12158] 12159[heading Return Value] 12160The field value. 12161[heading Exceptions] 12162[table [[Type][Thrown On]] 12163 [[`std::out_of_range`][ 12164 12165if the field is not found. 12166 ]] 12167] 12168[endsect] 12169[endsect] 12170 12171[section:basic_fields http::basic_fields::basic_fields] 12172[indexterm2 basic_fields..http::basic_fields] 12173Constructor. ``` 12174``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload1 basic_fields]``(); 12175 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload1 more...]]`` 12176 12177explicit 12178``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload2 basic_fields]``( 12179 Allocator const& alloc); 12180 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload2 more...]]`` 12181 12182``` 12183Move constructor. ``` 12184``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload3 basic_fields]``( 12185 basic_fields&&); 12186 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload3 more...]]`` 12187 12188``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload4 basic_fields]``( 12189 basic_fields&&, 12190 Allocator const& alloc); 12191 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload4 more...]]`` 12192 12193``` 12194Copy constructor. ``` 12195``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload5 basic_fields]``( 12196 basic_fields const&); 12197 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload5 more...]]`` 12198 12199``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload6 basic_fields]``( 12200 basic_fields const&, 12201 Allocator const& alloc); 12202 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload6 more...]]`` 12203 12204template< 12205 class OtherAlloc> 12206``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload7 basic_fields]``( 12207 basic_fields< OtherAlloc > const&); 12208 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload7 more...]]`` 12209 12210template< 12211 class OtherAlloc> 12212``[link beast.ref.boost__beast__http__basic_fields.basic_fields.overload8 basic_fields]``( 12213 basic_fields< OtherAlloc > const&, 12214 Allocator const& alloc); 12215 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.basic_fields.overload8 more...]]`` 12216``` 12217[section:overload1 http::basic_fields::basic_fields (1 of 8 overloads)] 12218Constructor. 12219[heading Synopsis] 12220``` 12221basic_fields(); 12222``` 12223 12224[heading Description] 12225[endsect] 12226[section:overload2 http::basic_fields::basic_fields (2 of 8 overloads)] 12227Constructor. 12228[heading Synopsis] 12229``` 12230basic_fields( 12231 Allocator const& alloc); 12232``` 12233 12234[heading Description] 12235[heading Parameters] 12236[table [[Name][Description]] 12237 [[`alloc`][ 12238 12239The allocator to use. 12240 ]] 12241] 12242[endsect] 12243[section:overload3 http::basic_fields::basic_fields (3 of 8 overloads)] 12244Move constructor. 12245[heading Synopsis] 12246``` 12247basic_fields( 12248 basic_fields&&); 12249``` 12250 12251[heading Description] 12252The state of the moved-from object is as if constructed using the same allocator. [endsect] 12253[section:overload4 http::basic_fields::basic_fields (4 of 8 overloads)] 12254Move constructor. 12255[heading Synopsis] 12256``` 12257basic_fields( 12258 basic_fields&&, 12259 Allocator const& alloc); 12260``` 12261 12262[heading Description] 12263The state of the moved-from object is as if constructed using the same allocator. 12264[heading Parameters] 12265[table [[Name][Description]] 12266 [[`alloc`][ 12267 12268The allocator to use. 12269 ]] 12270] 12271[endsect] 12272[section:overload5 http::basic_fields::basic_fields (5 of 8 overloads)] 12273Copy constructor. 12274[heading Synopsis] 12275``` 12276basic_fields( 12277 basic_fields const&); 12278``` 12279 12280[heading Description] 12281[endsect] 12282[section:overload6 http::basic_fields::basic_fields (6 of 8 overloads)] 12283Copy constructor. 12284[heading Synopsis] 12285``` 12286basic_fields( 12287 basic_fields const&, 12288 Allocator const& alloc); 12289``` 12290 12291[heading Description] 12292[heading Parameters] 12293[table [[Name][Description]] 12294 [[`alloc`][ 12295 12296The allocator to use. 12297 ]] 12298] 12299[endsect] 12300[section:overload7 http::basic_fields::basic_fields (7 of 8 overloads)] 12301Copy constructor. 12302[heading Synopsis] 12303``` 12304template< 12305 class OtherAlloc> 12306basic_fields( 12307 basic_fields< OtherAlloc > const&); 12308``` 12309 12310[heading Description] 12311[endsect] 12312[section:overload8 http::basic_fields::basic_fields (8 of 8 overloads)] 12313Copy constructor. 12314[heading Synopsis] 12315``` 12316template< 12317 class OtherAlloc> 12318basic_fields( 12319 basic_fields< OtherAlloc > const&, 12320 Allocator const& alloc); 12321``` 12322 12323[heading Description] 12324[heading Parameters] 12325[table [[Name][Description]] 12326 [[`alloc`][ 12327 12328The allocator to use. 12329 ]] 12330] 12331[endsect] 12332[endsect] 12333 12334[section:begin http::basic_fields::begin] 12335[indexterm2 begin..http::basic_fields] 12336Return a const iterator to the beginning of the field sequence. 12337[heading Synopsis] 12338``` 12339const_iterator 12340begin() const; 12341``` 12342 12343[heading Description] 12344[endsect] 12345[section:cbegin http::basic_fields::cbegin] 12346[indexterm2 cbegin..http::basic_fields] 12347Return a const iterator to the beginning of the field sequence. 12348[heading Synopsis] 12349``` 12350const_iterator 12351cbegin() const; 12352``` 12353 12354[heading Description] 12355[endsect] 12356[section:cend http::basic_fields::cend] 12357[indexterm2 cend..http::basic_fields] 12358Return a const iterator to the end of the field sequence. 12359[heading Synopsis] 12360``` 12361const_iterator 12362cend() const; 12363``` 12364 12365[heading Description] 12366[endsect] 12367[section:clear http::basic_fields::clear] 12368[indexterm2 clear..http::basic_fields] 12369Remove all fields from the container. 12370[heading Synopsis] 12371``` 12372void 12373clear(); 12374``` 12375 12376[heading Description] 12377All references, pointers, or iterators referring to contained elements are invalidated. All past-the-end iterators are also invalidated. 12378[heading Postconditions:] 12379 12380``` 12381 std::distance(this->begin(), this->end()) == 0 12382``` 12383[endsect] 12384[section:const_iterator http::basic_fields::const_iterator] 12385[indexterm2 const_iterator..http::basic_fields] 12386A constant iterator to the field sequence. 12387[heading Synopsis] 12388 12389``` 12390using const_iterator = ``['implementation-defined]``; 12391``` 12392 12393[heading Description] 12394[endsect] 12395[section:count http::basic_fields::count] 12396[indexterm2 count..http::basic_fields] 12397Return the number of fields with the specified name. ``` 12398std::size_t 12399``[link beast.ref.boost__beast__http__basic_fields.count.overload1 count]``( 12400 field name) const; 12401 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.count.overload1 more...]]`` 12402 12403std::size_t 12404``[link beast.ref.boost__beast__http__basic_fields.count.overload2 count]``( 12405 string_view name) const; 12406 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.count.overload2 more...]]`` 12407``` 12408[section:overload1 http::basic_fields::count (1 of 2 overloads)] 12409Return the number of fields with the specified name. 12410[heading Synopsis] 12411``` 12412std::size_t 12413count( 12414 field name) const; 12415``` 12416 12417[heading Description] 12418[heading Parameters] 12419[table [[Name][Description]] 12420 [[`name`][ 12421 12422The field name. 12423 ]] 12424] 12425[endsect] 12426[section:overload2 http::basic_fields::count (2 of 2 overloads)] 12427Return the number of fields with the specified name. 12428[heading Synopsis] 12429``` 12430std::size_t 12431count( 12432 string_view name) const; 12433``` 12434 12435[heading Description] 12436[heading Parameters] 12437[table [[Name][Description]] 12438 [[`name`][ 12439 12440The field name. 12441 ]] 12442] 12443[endsect] 12444[endsect] 12445 12446[section:end http::basic_fields::end] 12447[indexterm2 end..http::basic_fields] 12448Return a const iterator to the end of the field sequence. 12449[heading Synopsis] 12450``` 12451const_iterator 12452end() const; 12453``` 12454 12455[heading Description] 12456[endsect] 12457[section:equal_range http::basic_fields::equal_range] 12458[indexterm2 equal_range..http::basic_fields] 12459Returns a range of iterators to the fields with the specified name. ``` 12460std::pair< const_iterator, const_iterator > 12461``[link beast.ref.boost__beast__http__basic_fields.equal_range.overload1 equal_range]``( 12462 field name) const; 12463 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.equal_range.overload1 more...]]`` 12464 12465std::pair< const_iterator, const_iterator > 12466``[link beast.ref.boost__beast__http__basic_fields.equal_range.overload2 equal_range]``( 12467 string_view name) const; 12468 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.equal_range.overload2 more...]]`` 12469``` 12470[section:overload1 http::basic_fields::equal_range (1 of 2 overloads)] 12471Returns a range of iterators to the fields with the specified name. 12472[heading Synopsis] 12473``` 12474std::pair< const_iterator, const_iterator > 12475equal_range( 12476 field name) const; 12477``` 12478 12479[heading Description] 12480[heading Parameters] 12481[table [[Name][Description]] 12482 [[`name`][ 12483 12484The field name. 12485 ]] 12486] 12487[heading Return Value] 12488A range of iterators to fields with the same name, otherwise an empty range. 12489[endsect] 12490[section:overload2 http::basic_fields::equal_range (2 of 2 overloads)] 12491Returns a range of iterators to the fields with the specified name. 12492[heading Synopsis] 12493``` 12494std::pair< const_iterator, const_iterator > 12495equal_range( 12496 string_view name) const; 12497``` 12498 12499[heading Description] 12500[heading Parameters] 12501[table [[Name][Description]] 12502 [[`name`][ 12503 12504The field name. 12505 ]] 12506] 12507[heading Return Value] 12508A range of iterators to fields with the same name, otherwise an empty range. 12509[endsect] 12510[endsect] 12511 12512[section:erase http::basic_fields::erase] 12513[indexterm2 erase..http::basic_fields] 12514Remove a field. ``` 12515const_iterator 12516``[link beast.ref.boost__beast__http__basic_fields.erase.overload1 erase]``( 12517 const_iterator pos); 12518 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.erase.overload1 more...]]`` 12519 12520``` 12521Remove all fields with the specified name. ``` 12522std::size_t 12523``[link beast.ref.boost__beast__http__basic_fields.erase.overload2 erase]``( 12524 field name); 12525 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.erase.overload2 more...]]`` 12526 12527std::size_t 12528``[link beast.ref.boost__beast__http__basic_fields.erase.overload3 erase]``( 12529 string_view name); 12530 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.erase.overload3 more...]]`` 12531``` 12532[section:overload1 http::basic_fields::erase (1 of 3 overloads)] 12533Remove a field. 12534[heading Synopsis] 12535``` 12536const_iterator 12537erase( 12538 const_iterator pos); 12539``` 12540 12541[heading Description] 12542References and iterators to the erased elements are invalidated. Other references and iterators are not affected. 12543[heading Parameters] 12544[table [[Name][Description]] 12545 [[`pos`][ 12546 12547An iterator to the element to remove. 12548 ]] 12549] 12550[heading Return Value] 12551An iterator following the last removed element. If the iterator refers to the last element, the [link beast.ref.boost__beast__http__basic_fields.end `http::basic_fields::end()`] iterator is returned. 12552[endsect] 12553[section:overload2 http::basic_fields::erase (2 of 3 overloads)] 12554Remove all fields with the specified name. 12555[heading Synopsis] 12556``` 12557std::size_t 12558erase( 12559 field name); 12560``` 12561 12562[heading Description] 12563All fields with the same field name are erased from the container. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. 12564[heading Parameters] 12565[table [[Name][Description]] 12566 [[`name`][ 12567 12568The field name. 12569 ]] 12570] 12571[heading Return Value] 12572The number of fields removed. 12573[endsect] 12574[section:overload3 http::basic_fields::erase (3 of 3 overloads)] 12575Remove all fields with the specified name. 12576[heading Synopsis] 12577``` 12578std::size_t 12579erase( 12580 string_view name); 12581``` 12582 12583[heading Description] 12584All fields with the same field name are erased from the container. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. 12585[heading Parameters] 12586[table [[Name][Description]] 12587 [[`name`][ 12588 12589The field name. 12590 ]] 12591] 12592[heading Return Value] 12593The number of fields removed. 12594[endsect] 12595[endsect] 12596 12597[section:find http::basic_fields::find] 12598[indexterm2 find..http::basic_fields] 12599Returns an iterator to the case-insensitive matching field. ``` 12600const_iterator 12601``[link beast.ref.boost__beast__http__basic_fields.find.overload1 find]``( 12602 field name) const; 12603 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.find.overload1 more...]]`` 12604 12605``` 12606Returns an iterator to the case-insensitive matching field name. ``` 12607const_iterator 12608``[link beast.ref.boost__beast__http__basic_fields.find.overload2 find]``( 12609 string_view name) const; 12610 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.find.overload2 more...]]`` 12611``` 12612[section:overload1 http::basic_fields::find (1 of 2 overloads)] 12613Returns an iterator to the case-insensitive matching field. 12614[heading Synopsis] 12615``` 12616const_iterator 12617find( 12618 field name) const; 12619``` 12620 12621[heading Description] 12622If more than one field with the specified name exists, the first field defined by insertion order is returned. 12623[heading Parameters] 12624[table [[Name][Description]] 12625 [[`name`][ 12626 12627The field name. 12628 ]] 12629] 12630[heading Return Value] 12631An iterator to the matching field, or `end()` if no match was found. 12632[endsect] 12633[section:overload2 http::basic_fields::find (2 of 2 overloads)] 12634Returns an iterator to the case-insensitive matching field name. 12635[heading Synopsis] 12636``` 12637const_iterator 12638find( 12639 string_view name) const; 12640``` 12641 12642[heading Description] 12643If more than one field with the specified name exists, the first field defined by insertion order is returned. 12644[heading Parameters] 12645[table [[Name][Description]] 12646 [[`name`][ 12647 12648The field name. 12649 ]] 12650] 12651[heading Return Value] 12652An iterator to the matching field, or `end()` if no match was found. 12653[endsect] 12654[endsect] 12655 12656[section:get_allocator http::basic_fields::get_allocator] 12657[indexterm2 get_allocator..http::basic_fields] 12658Return a copy of the allocator associated with the container. 12659[heading Synopsis] 12660``` 12661allocator_type 12662get_allocator() const; 12663``` 12664 12665[heading Description] 12666[endsect] 12667[section:get_chunked_impl http::basic_fields::get_chunked_impl] 12668[indexterm2 get_chunked_impl..http::basic_fields] 12669Returns the chunked Transfer-Encoding setting. 12670[heading Synopsis] 12671``` 12672bool 12673get_chunked_impl() const; 12674``` 12675 12676[heading Description] 12677[endsect] 12678[section:get_keep_alive_impl http::basic_fields::get_keep_alive_impl] 12679[indexterm2 get_keep_alive_impl..http::basic_fields] 12680Returns the keep-alive setting. 12681[heading Synopsis] 12682``` 12683bool 12684get_keep_alive_impl( 12685 unsigned version) const; 12686``` 12687 12688[heading Description] 12689[endsect] 12690[section:get_method_impl http::basic_fields::get_method_impl] 12691[indexterm2 get_method_impl..http::basic_fields] 12692Returns the request-method string. 12693[heading Synopsis] 12694``` 12695string_view 12696get_method_impl() const; 12697``` 12698 12699[heading Description] 12700[heading Remarks] 12701Only called for requests. 12702[endsect] 12703[section:get_reason_impl http::basic_fields::get_reason_impl] 12704[indexterm2 get_reason_impl..http::basic_fields] 12705Returns the response reason-phrase string. 12706[heading Synopsis] 12707``` 12708string_view 12709get_reason_impl() const; 12710``` 12711 12712[heading Description] 12713[heading Remarks] 12714Only called for responses. 12715[endsect] 12716[section:get_target_impl http::basic_fields::get_target_impl] 12717[indexterm2 get_target_impl..http::basic_fields] 12718Returns the request-target string. 12719[heading Synopsis] 12720``` 12721string_view 12722get_target_impl() const; 12723``` 12724 12725[heading Description] 12726[heading Remarks] 12727Only called for requests. 12728[endsect] 12729[section:has_content_length_impl http::basic_fields::has_content_length_impl] 12730[indexterm2 has_content_length_impl..http::basic_fields] 12731Returns `true` if the Content-Length field is present. 12732[heading Synopsis] 12733``` 12734bool 12735has_content_length_impl() const; 12736``` 12737 12738[heading Description] 12739[endsect] 12740[section:insert http::basic_fields::insert] 12741[indexterm2 insert..http::basic_fields] 12742Insert a field. ``` 12743void 12744``[link beast.ref.boost__beast__http__basic_fields.insert.overload1 insert]``( 12745 field name, 12746 string_param const& value); 12747 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.insert.overload1 more...]]`` 12748 12749void 12750``[link beast.ref.boost__beast__http__basic_fields.insert.overload2 insert]``( 12751 string_view name, 12752 string_param const& value); 12753 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.insert.overload2 more...]]`` 12754 12755void 12756``[link beast.ref.boost__beast__http__basic_fields.insert.overload3 insert]``( 12757 field name, 12758 string_view name_string, 12759 string_param const& value); 12760 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.insert.overload3 more...]]`` 12761``` 12762[section:overload1 http::basic_fields::insert (1 of 3 overloads)] 12763Insert a field. 12764[heading Synopsis] 12765``` 12766void 12767insert( 12768 field name, 12769 string_param const& value); 12770``` 12771 12772[heading Description] 12773If one or more fields with the same name already exist, the new field will be inserted after the last field with the matching name, in serialization order. 12774[heading Parameters] 12775[table [[Name][Description]] 12776 [[`name`][ 12777 12778The field name. 12779 ]] 12780 [[`value`][ 12781 12782The value of the field, as a [link beast.ref.boost__beast__string_param `string_param`] 12783 ]] 12784] 12785[endsect] 12786[section:overload2 http::basic_fields::insert (2 of 3 overloads)] 12787Insert a field. 12788[heading Synopsis] 12789``` 12790void 12791insert( 12792 string_view name, 12793 string_param const& value); 12794``` 12795 12796[heading Description] 12797If one or more fields with the same name already exist, the new field will be inserted after the last field with the matching name, in serialization order. 12798[heading Parameters] 12799[table [[Name][Description]] 12800 [[`name`][ 12801 12802The field name. 12803 ]] 12804 [[`value`][ 12805 12806The value of the field, as a [link beast.ref.boost__beast__string_param `string_param`] 12807 ]] 12808] 12809[endsect] 12810[section:overload3 http::basic_fields::insert (3 of 3 overloads)] 12811Insert a field. 12812[heading Synopsis] 12813``` 12814void 12815insert( 12816 field name, 12817 string_view name_string, 12818 string_param const& value); 12819``` 12820 12821[heading Description] 12822If one or more fields with the same name already exist, the new field will be inserted after the last field with the matching name, in serialization order. 12823[heading Parameters] 12824[table [[Name][Description]] 12825 [[`name`][ 12826 12827The field name. 12828 ]] 12829 [[`name_string`][ 12830 12831The literal text corresponding to the field name. If `name != field::unknown`, then this value must be equal to `to_string(name)` using a case-insensitive comparison, otherwise the behavior is undefined. 12832 ]] 12833 [[`value`][ 12834 12835The value of the field, as a [link beast.ref.boost__beast__string_param `string_param`] 12836 ]] 12837] 12838[endsect] 12839[endsect] 12840 12841[section:iterator http::basic_fields::iterator] 12842[indexterm2 iterator..http::basic_fields] 12843A constant iterator to the field sequence. 12844[heading Synopsis] 12845 12846``` 12847using iterator = const_iterator; 12848``` 12849 12850[heading Description] 12851[endsect] 12852[section:key_comp http::basic_fields::key_comp] 12853[indexterm2 key_comp..http::basic_fields] 12854Returns a copy of the key comparison function. 12855[heading Synopsis] 12856``` 12857key_compare 12858key_comp() const; 12859``` 12860 12861[heading Description] 12862[endsect] 12863[section:key_compare http::basic_fields::key_compare] 12864[indexterm2 key_compare..http::basic_fields] 12865A strictly less predicate for comparing keys, using a case-insensitive comparison. 12866[heading Synopsis] 12867 12868``` 12869using key_compare = ``['implementation-defined]``; 12870``` 12871 12872[heading Description] 12873The case-comparison operation is defined only for low-ASCII characters. [endsect] 12874[section:operator_eq_ http::basic_fields::operator=] 12875[indexterm2 operator=..http::basic_fields] 12876Move assignment. ``` 12877basic_fields& 12878``[link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload1 operator=]``( 12879 basic_fields&&); 12880 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload1 more...]]`` 12881 12882``` 12883Copy assignment. ``` 12884basic_fields& 12885``[link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload2 operator=]``( 12886 basic_fields const&); 12887 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload2 more...]]`` 12888 12889template< 12890 class OtherAlloc> 12891basic_fields& 12892``[link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload3 operator=]``( 12893 basic_fields< OtherAlloc > const&); 12894 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.operator_eq_.overload3 more...]]`` 12895``` 12896[section:overload1 http::basic_fields::operator= (1 of 3 overloads)] 12897Move assignment. 12898[heading Synopsis] 12899``` 12900basic_fields& 12901operator=( 12902 basic_fields&&); 12903``` 12904 12905[heading Description] 12906The state of the moved-from object is as if constructed using the same allocator. [endsect] 12907[section:overload2 http::basic_fields::operator= (2 of 3 overloads)] 12908Copy assignment. 12909[heading Synopsis] 12910``` 12911basic_fields& 12912operator=( 12913 basic_fields const&); 12914``` 12915 12916[heading Description] 12917[endsect] 12918[section:overload3 http::basic_fields::operator= (3 of 3 overloads)] 12919Copy assignment. 12920[heading Synopsis] 12921``` 12922template< 12923 class OtherAlloc> 12924basic_fields& 12925operator=( 12926 basic_fields< OtherAlloc > const&); 12927``` 12928 12929[heading Description] 12930[endsect] 12931[endsect] 12932 12933[section:operator_lb__rb_ http::basic_fields::operator\[\]] 12934[indexterm2 operator\[\]..http::basic_fields] 12935Returns the value for a field, or `""` if it does not exist. ``` 12936string_view const 12937``[link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_.overload1 operator[]]``( 12938 field name) const; 12939 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_.overload1 more...]]`` 12940 12941``` 12942Returns the value for a case-insensitive matching header, or `""` if it does not exist. ``` 12943string_view const 12944``[link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_.overload2 operator[]]``( 12945 string_view name) const; 12946 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_.overload2 more...]]`` 12947``` 12948[section:overload1 http::basic_fields::operator\[\] (1 of 2 overloads)] 12949Returns the value for a field, or `""` if it does not exist. 12950[heading Synopsis] 12951``` 12952string_view const 12953operator[]( 12954 field name) const; 12955``` 12956 12957[heading Description] 12958If more than one field with the specified name exists, the first field defined by insertion order is returned. 12959[heading Parameters] 12960[table [[Name][Description]] 12961 [[`name`][ 12962 12963The name of the field. 12964 ]] 12965] 12966[endsect] 12967[section:overload2 http::basic_fields::operator\[\] (2 of 2 overloads)] 12968Returns the value for a case-insensitive matching header, or `""` if it does not exist. 12969[heading Synopsis] 12970``` 12971string_view const 12972operator[]( 12973 string_view name) const; 12974``` 12975 12976[heading Description] 12977If more than one field with the specified name exists, the first field defined by insertion order is returned. 12978[heading Parameters] 12979[table [[Name][Description]] 12980 [[`name`][ 12981 12982The name of the field. 12983 ]] 12984] 12985[endsect] 12986[endsect] 12987 12988[section:set http::basic_fields::set] 12989[indexterm2 set..http::basic_fields] 12990Set a field value, removing any other instances of that field. ``` 12991void 12992``[link beast.ref.boost__beast__http__basic_fields.set.overload1 set]``( 12993 field name, 12994 string_param const& value); 12995 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.set.overload1 more...]]`` 12996 12997void 12998``[link beast.ref.boost__beast__http__basic_fields.set.overload2 set]``( 12999 string_view name, 13000 string_param const& value); 13001 ``[''''»''' [link beast.ref.boost__beast__http__basic_fields.set.overload2 more...]]`` 13002``` 13003[section:overload1 http::basic_fields::set (1 of 2 overloads)] 13004Set a field value, removing any other instances of that field. 13005[heading Synopsis] 13006``` 13007void 13008set( 13009 field name, 13010 string_param const& value); 13011``` 13012 13013[heading Description] 13014First removes any values with matching field names, then inserts the new field value. 13015[heading Parameters] 13016[table [[Name][Description]] 13017 [[`name`][ 13018 13019The field name. 13020 ]] 13021 [[`value`][ 13022 13023The value of the field, as a [link beast.ref.boost__beast__string_param `string_param`] 13024 ]] 13025] 13026[heading Return Value] 13027The field value. 13028[endsect] 13029[section:overload2 http::basic_fields::set (2 of 2 overloads)] 13030Set a field value, removing any other instances of that field. 13031[heading Synopsis] 13032``` 13033void 13034set( 13035 string_view name, 13036 string_param const& value); 13037``` 13038 13039[heading Description] 13040First removes any values with matching field names, then inserts the new field value. 13041[heading Parameters] 13042[table [[Name][Description]] 13043 [[`name`][ 13044 13045The field name. 13046 ]] 13047 [[`value`][ 13048 13049The value of the field, as a [link beast.ref.boost__beast__string_param `string_param`] 13050 ]] 13051] 13052[endsect] 13053[endsect] 13054 13055[section:set_chunked_impl http::basic_fields::set_chunked_impl] 13056[indexterm2 set_chunked_impl..http::basic_fields] 13057Adjusts the chunked Transfer-Encoding value. 13058[heading Synopsis] 13059``` 13060void 13061set_chunked_impl( 13062 bool value); 13063``` 13064 13065[heading Description] 13066[endsect] 13067[section:set_content_length_impl http::basic_fields::set_content_length_impl] 13068[indexterm2 set_content_length_impl..http::basic_fields] 13069Sets or clears the Content-Length field. 13070[heading Synopsis] 13071``` 13072void 13073set_content_length_impl( 13074 boost::optional< std::uint64_t > const& value); 13075``` 13076 13077[heading Description] 13078[endsect] 13079[section:set_keep_alive_impl http::basic_fields::set_keep_alive_impl] 13080[indexterm2 set_keep_alive_impl..http::basic_fields] 13081Adjusts the Connection field. 13082[heading Synopsis] 13083``` 13084void 13085set_keep_alive_impl( 13086 unsigned version, 13087 bool keep_alive); 13088``` 13089 13090[heading Description] 13091[endsect] 13092[section:set_method_impl http::basic_fields::set_method_impl] 13093[indexterm2 set_method_impl..http::basic_fields] 13094Set or clear the method string. 13095[heading Synopsis] 13096``` 13097void 13098set_method_impl( 13099 string_view s); 13100``` 13101 13102[heading Description] 13103[heading Remarks] 13104Only called for requests. 13105[endsect] 13106[section:set_reason_impl http::basic_fields::set_reason_impl] 13107[indexterm2 set_reason_impl..http::basic_fields] 13108Set or clear the reason string. 13109[heading Synopsis] 13110``` 13111void 13112set_reason_impl( 13113 string_view s); 13114``` 13115 13116[heading Description] 13117[heading Remarks] 13118Only called for responses. 13119[endsect] 13120[section:set_target_impl http::basic_fields::set_target_impl] 13121[indexterm2 set_target_impl..http::basic_fields] 13122Set or clear the target string. 13123[heading Synopsis] 13124``` 13125void 13126set_target_impl( 13127 string_view s); 13128``` 13129 13130[heading Description] 13131[heading Remarks] 13132Only called for requests. 13133[endsect] 13134[section:swap http::basic_fields::swap] 13135[indexterm2 swap..http::basic_fields] 13136Swap two field containers. 13137[heading Synopsis] 13138 13139Defined in header [include_file boost/beast/http/fields.hpp] 13140 13141 13142``` 13143template< 13144 class Alloc> 13145friend void 13146swap( 13147 basic_fields< Alloc >& lhs, 13148 basic_fields< Alloc >& rhs); 13149``` 13150 13151[heading Description] 13152 13153 13154 13155Convenience header [include_file boost/beast/http.hpp] 13156 13157[endsect] 13158[section:swap http::basic_fields::swap] 13159[indexterm2 swap..http::basic_fields] 13160Return a buffer sequence representing the trailers. 13161[heading Synopsis] 13162``` 13163void 13164swap( 13165 basic_fields& other); 13166``` 13167 13168[heading Description] 13169This function returns a buffer sequence holding the serialized representation of the trailer fields promised in the Accept field. Before calling this function the Accept field must contain the exact trailer fields desired. Each field must also exist.Swap this container with another [endsect] 13170[section:writer http::basic_fields::writer] 13171[indexterm2 writer..http::basic_fields] 13172The algorithm used to serialize the header. 13173[heading Synopsis] 13174 13175``` 13176using writer = ``['implementation-defined]``; 13177``` 13178 13179[heading Description] 13180[endsect] 13181[section:basic_fields_dtor_ http::basic_fields::~basic_fields] 13182[indexterm2 ~basic_fields..http::basic_fields] 13183Destructor. 13184[heading Synopsis] 13185``` 13186~basic_fields(); 13187``` 13188 13189[heading Description] 13190[endsect] 13191 13192 13193 13194Convenience header [include_file boost/beast/http.hpp] 13195 13196[endsect] 13197 13198 13199 13200[section:boost__beast__http__basic_fields__element http::basic_fields::element] 13201 13202[heading Synopsis] 13203 13204Defined in header [include_file boost/beast/http/fields.hpp] 13205 13206 13207 13208``` 13209struct element : 13210 public boost::intrusive::list_base_hook< boost::intrusive::link_mode< boost::intrusive::normal_link > >, 13211 public boost::intrusive::set_base_hook< boost::intrusive::link_mode< boost::intrusive::normal_link > >, 13212 public http::basic_fields< Allocator >::value_type 13213``` 13214[heading Member Functions] 13215[table [[Name][Description]] 13216 [ 13217 [[link beast.ref.boost__beast__http__basic_fields__element.element [*element]]] 13218 [ 13219 13220 ] 13221 ] 13222 [ 13223 [[link beast.ref.boost__beast__http__basic_fields__element.name [*name]]] 13224 [ 13225 Returns the field enum, which can be field::unknown. 13226 ] 13227 ] 13228 [ 13229 [[link beast.ref.boost__beast__http__basic_fields__element.name_string [*name_string]]] 13230 [ 13231 Returns the field name as a string. 13232 ] 13233 ] 13234 [ 13235 [[link beast.ref.boost__beast__http__basic_fields__element.value [*value]]] 13236 [ 13237 Returns the value of the field. 13238 ] 13239 ] 13240] 13241 13242[heading Description] 13243[section:element http::basic_fields::element::element] 13244[indexterm2 element..http::basic_fields::element] 13245 13246[heading Synopsis] 13247``` 13248element( 13249 field name, 13250 string_view sname, 13251 string_view value); 13252``` 13253 13254[heading Description] 13255[endsect] 13256[section:name http::basic_fields::element::name] 13257(Inherited from `http::basic_fields`) 13258 13259[indexterm2 name..http::basic_fields::element] 13260Returns the field enum, which can be [link beast.ref.boost__beast__http__field `http::unknown`]. 13261[heading Synopsis] 13262``` 13263field 13264name() const; 13265``` 13266 13267[heading Description] 13268[endsect] 13269[section:name_string http::basic_fields::element::name_string] 13270(Inherited from `http::basic_fields`) 13271 13272[indexterm2 name_string..http::basic_fields::element] 13273Returns the field name as a string. 13274[heading Synopsis] 13275``` 13276string_view const 13277name_string() const; 13278``` 13279 13280[heading Description] 13281[endsect] 13282[section:value http::basic_fields::element::value] 13283(Inherited from `http::basic_fields`) 13284 13285[indexterm2 value..http::basic_fields::element] 13286Returns the value of the field. 13287[heading Synopsis] 13288``` 13289string_view const 13290value() const; 13291``` 13292 13293[heading Description] 13294[endsect] 13295 13296 13297 13298Convenience header [include_file boost/beast/http.hpp] 13299 13300[endsect] 13301 13302 13303 13304[section:boost__beast__http__basic_fields__value_type http::basic_fields::value_type] 13305The type of element used to represent a field. 13306[heading Synopsis] 13307 13308Defined in header [include_file boost/beast/http/fields.hpp] 13309 13310 13311 13312``` 13313class value_type 13314``` 13315[heading Member Functions] 13316[table [[Name][Description]] 13317 [ 13318 [[link beast.ref.boost__beast__http__basic_fields__value_type.name [*name]]] 13319 [ 13320 Returns the field enum, which can be field::unknown. 13321 ] 13322 ] 13323 [ 13324 [[link beast.ref.boost__beast__http__basic_fields__value_type.name_string [*name_string]]] 13325 [ 13326 Returns the field name as a string. 13327 ] 13328 ] 13329 [ 13330 [[link beast.ref.boost__beast__http__basic_fields__value_type.operator_eq_ [*operator=]]] 13331 [ 13332 Assignment (deleted) 13333 ] 13334 ] 13335 [ 13336 [[link beast.ref.boost__beast__http__basic_fields__value_type.value [*value]]] 13337 [ 13338 Returns the value of the field. 13339 ] 13340 ] 13341 [ 13342 [[link beast.ref.boost__beast__http__basic_fields__value_type.value_type [*value_type]]] 13343 [ 13344 Constructor (deleted) 13345 ] 13346 ] 13347] 13348[heading Protected Member Functions] 13349[table [[Name][Description]] 13350 [ 13351 [[link beast.ref.boost__beast__http__basic_fields__value_type.value_type [*value_type]]] 13352 [ 13353 13354 ] 13355 ] 13356] 13357 13358[heading Description] 13359[section:name http::basic_fields::value_type::name] 13360[indexterm2 name..http::basic_fields::value_type] 13361Returns the field enum, which can be [link beast.ref.boost__beast__http__field `http::unknown`]. 13362[heading Synopsis] 13363``` 13364field 13365name() const; 13366``` 13367 13368[heading Description] 13369[endsect] 13370[section:name_string http::basic_fields::value_type::name_string] 13371[indexterm2 name_string..http::basic_fields::value_type] 13372Returns the field name as a string. 13373[heading Synopsis] 13374``` 13375string_view const 13376name_string() const; 13377``` 13378 13379[heading Description] 13380[endsect] 13381[section:operator_eq_ http::basic_fields::value_type::operator=] 13382[indexterm2 operator=..http::basic_fields::value_type] 13383Assignment (deleted) 13384[heading Synopsis] 13385``` 13386value_type& 13387operator=( 13388 value_type const&); 13389``` 13390 13391[heading Description] 13392[endsect] 13393[section:value http::basic_fields::value_type::value] 13394[indexterm2 value..http::basic_fields::value_type] 13395Returns the value of the field. 13396[heading Synopsis] 13397``` 13398string_view const 13399value() const; 13400``` 13401 13402[heading Description] 13403[endsect] 13404[section:value_type http::basic_fields::value_type::value_type] 13405[indexterm2 value_type..http::basic_fields::value_type] 13406 13407[heading Synopsis] 13408``` 13409value_type( 13410 field name, 13411 string_view sname, 13412 string_view value); 13413``` 13414 13415[heading Description] 13416[endsect] 13417[section:value_type http::basic_fields::value_type::value_type] 13418[indexterm2 value_type..http::basic_fields::value_type] 13419Constructor (deleted) 13420[heading Synopsis] 13421``` 13422value_type( 13423 value_type const&); 13424``` 13425 13426[heading Description] 13427[endsect] 13428 13429 13430 13431Convenience header [include_file boost/beast/http.hpp] 13432 13433[endsect] 13434 13435 13436 13437[section:boost__beast__http__basic_file_body http::basic_file_body] 13438A message body represented by a file on the filesystem. 13439[heading Synopsis] 13440 13441Defined in header [include_file boost/beast/http/basic_file_body.hpp] 13442 13443 13444 13445``` 13446template< 13447 class File> 13448struct basic_file_body 13449``` 13450[heading Types] 13451[table [[Name][Description]] 13452 [ 13453 [[link beast.ref.boost__beast__http__basic_file_body__reader [*reader]]] 13454 [ 13455 Algorithm for storing buffers when parsing. 13456 ] 13457 ] 13458 [ 13459 [[link beast.ref.boost__beast__http__basic_file_body__value_type [*value_type]]] 13460 [ 13461 The type of the message::body member. 13462 ] 13463 ] 13464 [ 13465 [[link beast.ref.boost__beast__http__basic_file_body__writer [*writer]]] 13466 [ 13467 Algorithm for retrieving buffers when serializing. 13468 ] 13469 ] 13470 [ 13471 [[link beast.ref.boost__beast__http__basic_file_body.file_type [*file_type]]] 13472 [ 13473 The type of File this body uses. 13474 ] 13475 ] 13476] 13477[heading Member Functions] 13478[table [[Name][Description]] 13479 [ 13480 [[link beast.ref.boost__beast__http__basic_file_body.size [*size]]] 13481 [ 13482 Returns the size of the body. 13483 ] 13484 ] 13485] 13486 13487[heading Description] 13488Messages with this type have bodies represented by a file on the file system. When parsing a message using this body type, the data is stored in the file pointed to by the path, which must be writable. When serializing, the implementation will read the file and present those octets as the body content. This may be used to serve content from a directory as part of a web service. 13489[heading Template Parameters] 13490[table [[Type][Description]] 13491 [[`File`][ 13492 13493The implementation to use for accessing files. This type must meet the requirements of ['File]. 13494 ]] 13495] 13496[section:file_type http::basic_file_body::file_type] 13497[indexterm2 file_type..http::basic_file_body] 13498The type of File this body uses. 13499[heading Synopsis] 13500 13501``` 13502using file_type = File; 13503``` 13504 13505[heading Description] 13506[endsect] 13507[section:size http::basic_file_body::size] 13508[indexterm2 size..http::basic_file_body] 13509Returns the size of the body. 13510[heading Synopsis] 13511``` 13512static 13513std::uint64_t 13514size( 13515 value_type const& body); 13516``` 13517 13518[heading Description] 13519[heading Parameters] 13520[table [[Name][Description]] 13521 [[`body`][ 13522 13523The file body to use 13524 ]] 13525] 13526[endsect] 13527 13528 13529 13530Convenience header [include_file boost/beast/http.hpp] 13531 13532[endsect] 13533 13534 13535 13536[section:boost__beast__http__basic_file_body__reader http::basic_file_body::reader] 13537Algorithm for storing buffers when parsing. 13538[heading Synopsis] 13539 13540Defined in header [include_file boost/beast/http/basic_file_body.hpp] 13541 13542 13543 13544``` 13545class reader 13546``` 13547[heading Member Functions] 13548[table [[Name][Description]] 13549 [ 13550 [[link beast.ref.boost__beast__http__basic_file_body__reader.finish [*finish]]] 13551 [ 13552 13553 ] 13554 ] 13555 [ 13556 [[link beast.ref.boost__beast__http__basic_file_body__reader.init [*init]]] 13557 [ 13558 13559 ] 13560 ] 13561 [ 13562 [[link beast.ref.boost__beast__http__basic_file_body__reader.put [*put]]] 13563 [ 13564 13565 ] 13566 ] 13567 [ 13568 [[link beast.ref.boost__beast__http__basic_file_body__reader.reader [*reader]]] 13569 [ 13570 13571 ] 13572 ] 13573] 13574 13575[heading Description] 13576Objects of this type are created during parsing to store incoming buffers representing the body. [section:finish http::basic_file_body::reader::finish] 13577[indexterm2 finish..http::basic_file_body::reader] 13578 13579[heading Synopsis] 13580``` 13581void 13582finish( 13583 error_code& ec); 13584``` 13585 13586[heading Description] 13587[endsect] 13588[section:init http::basic_file_body::reader::init] 13589[indexterm2 init..http::basic_file_body::reader] 13590 13591[heading Synopsis] 13592``` 13593void 13594init( 13595 boost::optional< std::uint64_t > const&, 13596 error_code& ec); 13597``` 13598 13599[heading Description] 13600[endsect] 13601[section:put http::basic_file_body::reader::put] 13602[indexterm2 put..http::basic_file_body::reader] 13603 13604[heading Synopsis] 13605``` 13606template< 13607 class __ConstBufferSequence__> 13608std::size_t 13609put( 13610 ConstBufferSequence const& buffers, 13611 error_code& ec); 13612``` 13613 13614[heading Description] 13615[endsect] 13616[section:reader http::basic_file_body::reader::reader] 13617[indexterm2 reader..http::basic_file_body::reader] 13618 13619[heading Synopsis] 13620``` 13621template< 13622 bool isRequest, 13623 class __Fields__> 13624reader( 13625 header< isRequest, Fields >& h, 13626 value_type& b); 13627``` 13628 13629[heading Description] 13630[endsect] 13631 13632 13633 13634Convenience header [include_file boost/beast/http.hpp] 13635 13636[endsect] 13637 13638 13639 13640[section:boost__beast__http__basic_file_body__value_type http::basic_file_body::value_type] 13641The type of the [link beast.ref.boost__beast__http__message.body `http::message::body`] member. 13642[heading Synopsis] 13643 13644Defined in header [include_file boost/beast/http/basic_file_body.hpp] 13645 13646 13647 13648``` 13649class value_type 13650``` 13651[heading Member Functions] 13652[table [[Name][Description]] 13653 [ 13654 [[link beast.ref.boost__beast__http__basic_file_body__value_type.close [*close]]] 13655 [ 13656 Close the file if open. 13657 ] 13658 ] 13659 [ 13660 [[link beast.ref.boost__beast__http__basic_file_body__value_type.is_open [*is_open]]] 13661 [ 13662 Returns true if the file is open. 13663 ] 13664 ] 13665 [ 13666 [[link beast.ref.boost__beast__http__basic_file_body__value_type.open [*open]]] 13667 [ 13668 Open a file at the given path with the specified mode. 13669 ] 13670 ] 13671 [ 13672 [[link beast.ref.boost__beast__http__basic_file_body__value_type.operator_eq_ [*operator=]]] 13673 [ 13674 Move assignment. 13675 ] 13676 ] 13677 [ 13678 [[link beast.ref.boost__beast__http__basic_file_body__value_type.reset [*reset]]] 13679 [ 13680 Set the open file. 13681 ] 13682 ] 13683 [ 13684 [[link beast.ref.boost__beast__http__basic_file_body__value_type.size [*size]]] 13685 [ 13686 Returns the size of the file if open. 13687 ] 13688 ] 13689 [ 13690 [[link beast.ref.boost__beast__http__basic_file_body__value_type.value_type [*value_type]]] 13691 [ 13692 Constructor. 13693 ] 13694 ] 13695 [ 13696 [[link beast.ref.boost__beast__http__basic_file_body__value_type.value_type_dtor_ [*~value_type]]] 13697 [ 13698 Destructor. 13699 ] 13700 ] 13701] 13702[heading Friends] 13703[table [[Name][Description]] 13704 [ 13705 [[link beast.ref.boost__beast__http__basic_file_body__value_type.basic_file_body [*basic_file_body]]] 13706 [ 13707 13708 ] 13709 ] 13710] 13711 13712[heading Description] 13713Messages declared using `basic_file_body` will have this type for the body member. This rich class interface allow the file to be opened with the file handle maintained directly in the object, which is attached to the message. [section:basic_file_body http::basic_file_body::value_type::basic_file_body] 13714[indexterm2 basic_file_body..http::basic_file_body::value_type] 13715 13716[heading Synopsis] 13717 13718Defined in header [include_file boost/beast/http/basic_file_body.hpp] 13719 13720 13721``` 13722friend struct 13723basic_file_body(); 13724``` 13725 13726[heading Description] 13727 13728 13729 13730Convenience header [include_file boost/beast/http.hpp] 13731 13732[endsect] 13733[section:close http::basic_file_body::value_type::close] 13734[indexterm2 close..http::basic_file_body::value_type] 13735Close the file if open. 13736[heading Synopsis] 13737``` 13738void 13739close(); 13740``` 13741 13742[heading Description] 13743[endsect] 13744[section:is_open http::basic_file_body::value_type::is_open] 13745[indexterm2 is_open..http::basic_file_body::value_type] 13746Returns `true` if the file is open. 13747[heading Synopsis] 13748``` 13749bool 13750is_open() const; 13751``` 13752 13753[heading Description] 13754[endsect] 13755[section:open http::basic_file_body::value_type::open] 13756[indexterm2 open..http::basic_file_body::value_type] 13757Open a file at the given path with the specified mode. 13758[heading Synopsis] 13759``` 13760void 13761open( 13762 char const* path, 13763 file_mode mode, 13764 error_code& ec); 13765``` 13766 13767[heading Description] 13768[heading Parameters] 13769[table [[Name][Description]] 13770 [[`path`][ 13771 13772The utf-8 encoded path to the file 13773 ]] 13774 [[`mode`][ 13775 13776The file mode to use 13777 ]] 13778 [[`ec`][ 13779 13780Set to the error, if any occurred 13781 ]] 13782] 13783[endsect] 13784[section:operator_eq_ http::basic_file_body::value_type::operator=] 13785[indexterm2 operator=..http::basic_file_body::value_type] 13786Move assignment. 13787[heading Synopsis] 13788``` 13789value_type& 13790operator=( 13791 value_type&& other); 13792``` 13793 13794[heading Description] 13795[endsect] 13796[section:reset http::basic_file_body::value_type::reset] 13797[indexterm2 reset..http::basic_file_body::value_type] 13798Set the open file. 13799[heading Synopsis] 13800``` 13801void 13802reset( 13803 File&& file, 13804 error_code& ec); 13805``` 13806 13807[heading Description] 13808This function is used to set the open file. Any previously set file will be closed. 13809[heading Parameters] 13810[table [[Name][Description]] 13811 [[`file`][ 13812 13813The file to set. The file must be open or else an error occurs 13814 ]] 13815 [[`ec`][ 13816 13817Set to the error, if any occurred 13818 ]] 13819] 13820[endsect] 13821[section:size http::basic_file_body::value_type::size] 13822[indexterm2 size..http::basic_file_body::value_type] 13823Returns the size of the file if open. 13824[heading Synopsis] 13825``` 13826std::uint64_t 13827size() const; 13828``` 13829 13830[heading Description] 13831[endsect] 13832[section:value_type http::basic_file_body::value_type::value_type] 13833[indexterm2 value_type..http::basic_file_body::value_type] 13834Constructor. ``` 13835``[link beast.ref.boost__beast__http__basic_file_body__value_type.value_type.overload1 value_type]``(); 13836 ``[''''»''' [link beast.ref.boost__beast__http__basic_file_body__value_type.value_type.overload1 more...]]`` 13837 13838``[link beast.ref.boost__beast__http__basic_file_body__value_type.value_type.overload2 value_type]``( 13839 value_type&& other); 13840 ``[''''»''' [link beast.ref.boost__beast__http__basic_file_body__value_type.value_type.overload2 more...]]`` 13841``` 13842[section:overload1 http::basic_file_body::value_type::value_type (1 of 2 overloads)] 13843Constructor. 13844[heading Synopsis] 13845``` 13846value_type(); 13847``` 13848 13849[heading Description] 13850[endsect] 13851[section:overload2 http::basic_file_body::value_type::value_type (2 of 2 overloads)] 13852Constructor. 13853[heading Synopsis] 13854``` 13855value_type( 13856 value_type&& other); 13857``` 13858 13859[heading Description] 13860[endsect] 13861[endsect] 13862 13863[section:value_type_dtor_ http::basic_file_body::value_type::~value_type] 13864[indexterm2 ~value_type..http::basic_file_body::value_type] 13865Destructor. 13866[heading Synopsis] 13867``` 13868~value_type(); 13869``` 13870 13871[heading Description] 13872If the file is open, it is closed first. [endsect] 13873 13874 13875 13876Convenience header [include_file boost/beast/http.hpp] 13877 13878[endsect] 13879 13880 13881 13882[section:boost__beast__http__basic_file_body__writer http::basic_file_body::writer] 13883Algorithm for retrieving buffers when serializing. 13884[heading Synopsis] 13885 13886Defined in header [include_file boost/beast/http/basic_file_body.hpp] 13887 13888 13889 13890``` 13891class writer 13892``` 13893[heading Types] 13894[table [[Name][Description]] 13895 [ 13896 [[link beast.ref.boost__beast__http__basic_file_body__writer.const_buffers_type [*const_buffers_type]]] 13897 [ 13898 13899 ] 13900 ] 13901] 13902[heading Member Functions] 13903[table [[Name][Description]] 13904 [ 13905 [[link beast.ref.boost__beast__http__basic_file_body__writer.get [*get]]] 13906 [ 13907 13908 ] 13909 ] 13910 [ 13911 [[link beast.ref.boost__beast__http__basic_file_body__writer.init [*init]]] 13912 [ 13913 13914 ] 13915 ] 13916 [ 13917 [[link beast.ref.boost__beast__http__basic_file_body__writer.writer [*writer]]] 13918 [ 13919 13920 ] 13921 ] 13922] 13923 13924[heading Description] 13925Objects of this type are created during serialization to extract the buffers representing the body. [section:const_buffers_type http::basic_file_body::writer::const_buffers_type] 13926[indexterm2 const_buffers_type..http::basic_file_body::writer] 13927 13928[heading Synopsis] 13929 13930``` 13931using const_buffers_type = net::const_buffer; 13932``` 13933 13934[heading Description] 13935[endsect] 13936[section:get http::basic_file_body::writer::get] 13937[indexterm2 get..http::basic_file_body::writer] 13938 13939[heading Synopsis] 13940``` 13941boost::optional< std::pair< const_buffers_type, bool > > 13942get( 13943 error_code& ec); 13944``` 13945 13946[heading Description] 13947[endsect] 13948[section:init http::basic_file_body::writer::init] 13949[indexterm2 init..http::basic_file_body::writer] 13950 13951[heading Synopsis] 13952``` 13953void 13954init( 13955 error_code& ec); 13956``` 13957 13958[heading Description] 13959[endsect] 13960[section:writer http::basic_file_body::writer::writer] 13961[indexterm2 writer..http::basic_file_body::writer] 13962 13963[heading Synopsis] 13964``` 13965template< 13966 bool isRequest, 13967 class __Fields__> 13968writer( 13969 header< isRequest, Fields >& h, 13970 value_type& b); 13971``` 13972 13973[heading Description] 13974[endsect] 13975 13976 13977 13978Convenience header [include_file boost/beast/http.hpp] 13979 13980[endsect] 13981 13982 13983 13984[section:boost__beast__http__basic_parser http::basic_parser] 13985A parser for decoding HTTP/1 wire format messages. 13986[heading Synopsis] 13987 13988Defined in header [include_file boost/beast/http/basic_parser.hpp] 13989 13990 13991 13992``` 13993template< 13994 bool isRequest> 13995class basic_parser : 13996 private basic_parser_base 13997``` 13998[heading Types] 13999[table [[Name][Description]] 14000 [ 14001 [[link beast.ref.boost__beast__http__basic_parser.is_request [*is_request]]] 14002 [ 14003 true if this parser parses requests, false for responses. 14004 ] 14005 ] 14006] 14007[heading Member Functions] 14008[table [[Name][Description]] 14009 [ 14010 [[link beast.ref.boost__beast__http__basic_parser.basic_parser [*basic_parser]]] 14011 [ 14012 Copy constructor. 14013 ] 14014 ] 14015 [ 14016 [[link beast.ref.boost__beast__http__basic_parser.body_limit [*body_limit]]] 14017 [ 14018 Set the limit on the payload body. 14019 ] 14020 ] 14021 [ 14022 [[link beast.ref.boost__beast__http__basic_parser.chunked [*chunked]]] 14023 [ 14024 Returns true if the last value for Transfer-Encoding is "chunked". 14025 ] 14026 ] 14027 [ 14028 [[link beast.ref.boost__beast__http__basic_parser.content_length [*content_length]]] 14029 [ 14030 Returns the optional value of Content-Length if known. 14031 ] 14032 ] 14033 [ 14034 [[link beast.ref.boost__beast__http__basic_parser.content_length_remaining [*content_length_remaining]]] 14035 [ 14036 Returns the remaining content length if known. 14037 ] 14038 ] 14039 [ 14040 [[link beast.ref.boost__beast__http__basic_parser.eager [*eager]]] 14041 [ 14042 Returns true if the eager parse option is set. 14043 14044 Set the eager parse option. 14045 ] 14046 ] 14047 [ 14048 [[link beast.ref.boost__beast__http__basic_parser.got_some [*got_some]]] 14049 [ 14050 Returns true if the parser has received at least one byte of input. 14051 ] 14052 ] 14053 [ 14054 [[link beast.ref.boost__beast__http__basic_parser.header_limit [*header_limit]]] 14055 [ 14056 Set a limit on the total size of the header. 14057 ] 14058 ] 14059 [ 14060 [[link beast.ref.boost__beast__http__basic_parser.is_done [*is_done]]] 14061 [ 14062 Returns true if the message is complete. 14063 ] 14064 ] 14065 [ 14066 [[link beast.ref.boost__beast__http__basic_parser.is_header_done [*is_header_done]]] 14067 [ 14068 Returns true if a the parser has produced the full header. 14069 ] 14070 ] 14071 [ 14072 [[link beast.ref.boost__beast__http__basic_parser.keep_alive [*keep_alive]]] 14073 [ 14074 Returns true if the message has keep-alive connection semantics. 14075 ] 14076 ] 14077 [ 14078 [[link beast.ref.boost__beast__http__basic_parser.need_eof [*need_eof]]] 14079 [ 14080 Returns true if the message semantics require an end of file. 14081 ] 14082 ] 14083 [ 14084 [[link beast.ref.boost__beast__http__basic_parser.operator_eq_ [*operator=]]] 14085 [ 14086 Copy assignment. 14087 ] 14088 ] 14089 [ 14090 [[link beast.ref.boost__beast__http__basic_parser.put [*put]]] 14091 [ 14092 Write a buffer sequence to the parser. 14093 ] 14094 ] 14095 [ 14096 [[link beast.ref.boost__beast__http__basic_parser.put_eof [*put_eof]]] 14097 [ 14098 Inform the parser that the end of stream was reached. 14099 ] 14100 ] 14101 [ 14102 [[link beast.ref.boost__beast__http__basic_parser.skip [*skip]]] 14103 [ 14104 Returns true if the skip parse option is set. 14105 14106 Set the skip parse option. 14107 ] 14108 ] 14109 [ 14110 [[link beast.ref.boost__beast__http__basic_parser.upgrade [*upgrade]]] 14111 [ 14112 Returns true if the message is an upgrade message. 14113 ] 14114 ] 14115 [ 14116 [[link beast.ref.boost__beast__http__basic_parser.basic_parser_dtor_ [*~basic_parser]]] 14117 [ 14118 Destructor. 14119 ] 14120 ] 14121] 14122[heading Protected Member Functions] 14123[table [[Name][Description]] 14124 [ 14125 [[link beast.ref.boost__beast__http__basic_parser.basic_parser [*basic_parser]]] 14126 [ 14127 Default constructor. 14128 14129 Move constructor. 14130 ] 14131 ] 14132 [ 14133 [[link beast.ref.boost__beast__http__basic_parser.on_body_impl [*on_body_impl]]] 14134 [ 14135 Called each time additional data is received representing the content body. 14136 ] 14137 ] 14138 [ 14139 [[link beast.ref.boost__beast__http__basic_parser.on_body_init_impl [*on_body_init_impl]]] 14140 [ 14141 Called once before the body is processed. 14142 ] 14143 ] 14144 [ 14145 [[link beast.ref.boost__beast__http__basic_parser.on_chunk_body_impl [*on_chunk_body_impl]]] 14146 [ 14147 Called each time additional data is received representing part of a body chunk. 14148 ] 14149 ] 14150 [ 14151 [[link beast.ref.boost__beast__http__basic_parser.on_chunk_header_impl [*on_chunk_header_impl]]] 14152 [ 14153 Called each time a new chunk header of a chunk encoded body is received. 14154 ] 14155 ] 14156 [ 14157 [[link beast.ref.boost__beast__http__basic_parser.on_field_impl [*on_field_impl]]] 14158 [ 14159 Called once for each complete field in the HTTP header. 14160 ] 14161 ] 14162 [ 14163 [[link beast.ref.boost__beast__http__basic_parser.on_finish_impl [*on_finish_impl]]] 14164 [ 14165 Called once when the complete message is received. 14166 ] 14167 ] 14168 [ 14169 [[link beast.ref.boost__beast__http__basic_parser.on_header_impl [*on_header_impl]]] 14170 [ 14171 Called once after the complete HTTP header is received. 14172 ] 14173 ] 14174 [ 14175 [[link beast.ref.boost__beast__http__basic_parser.on_request_impl [*on_request_impl]]] 14176 [ 14177 Called after receiving the request-line. 14178 ] 14179 ] 14180 [ 14181 [[link beast.ref.boost__beast__http__basic_parser.on_response_impl [*on_response_impl]]] 14182 [ 14183 Called after receiving the status-line. 14184 ] 14185 ] 14186 [ 14187 [[link beast.ref.boost__beast__http__basic_parser.operator_eq_ [*operator=]]] 14188 [ 14189 Move assignment. 14190 ] 14191 ] 14192] 14193 14194[heading Description] 14195This parser is designed to efficiently parse messages in the HTTP/1 wire format. It allocates no memory when input is presented as a single contiguous buffer, and uses minimal state. It will handle chunked encoding and it understands the semantics of the Connection, Content-Length, and Upgrade fields. The parser is optimized for the case where the input buffer sequence consists of a single contiguous buffer. The [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`] class is provided, which guarantees that the input sequence of the stream buffer will be represented by exactly one contiguous buffer. To ensure the optimum performance of the parser, use [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`] with HTTP algorithms such as [link beast.ref.boost__beast__http__read `http::read`], [link beast.ref.boost__beast__http__read_some `http::read_some`], [link beast.ref.boost__beast__http__async_read `http::async_read`], and [link beast.ref.boost__beast__http__async_read_some `http::async_read_some`]. Alternatively, the caller may use custom techniques to ensure that the structured portion of the HTTP message (header or chunk header) is contained in a linear buffer. 14196The interface to the parser uses virtual member functions. To use this class, derive your type from [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. When bytes are presented, the implementation will make a series of zero or more calls to virtual functions, which the derived class must implement. 14197Every virtual function must be provided by the derived class, or else a compilation error will be generated. The implementation will make sure that `ec` is clear before each virtual function is invoked. If a virtual function sets an error, it is propagated out of the parser to the caller. 14198[heading Template Parameters] 14199[table [[Type][Description]] 14200 [[`isRequest`][ 14201 14202A `bool` indicating whether the parser will be presented with request or response message. 14203 ]] 14204] 14205[heading Remarks] 14206If the parser encounters a field value with obs-fold longer than 4 kilobytes in length, an error is generated. 14207[section:basic_parser http::basic_parser::basic_parser] 14208[indexterm2 basic_parser..http::basic_parser] 14209Default constructor. ``` 14210``[link beast.ref.boost__beast__http__basic_parser.basic_parser.overload1 basic_parser]``(); 14211 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.basic_parser.overload1 more...]]`` 14212 14213``` 14214Move constructor. ``` 14215``[link beast.ref.boost__beast__http__basic_parser.basic_parser.overload2 basic_parser]``( 14216 basic_parser&&); 14217 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.basic_parser.overload2 more...]]`` 14218``` 14219[section:overload1 http::basic_parser::basic_parser (1 of 2 overloads)] 14220Default constructor. 14221[heading Synopsis] 14222``` 14223basic_parser(); 14224``` 14225 14226[heading Description] 14227[endsect] 14228[section:overload2 http::basic_parser::basic_parser (2 of 2 overloads)] 14229Move constructor. 14230[heading Synopsis] 14231``` 14232basic_parser( 14233 basic_parser&&); 14234``` 14235 14236[heading Description] 14237[heading Remarks] 14238 14239After the move, the only valid operation on the moved-from object is destruction. [endsect] 14240[endsect] 14241 14242[section:basic_parser http::basic_parser::basic_parser] 14243[indexterm2 basic_parser..http::basic_parser] 14244Copy constructor. 14245[heading Synopsis] 14246``` 14247basic_parser( 14248 basic_parser const&); 14249``` 14250 14251[heading Description] 14252[endsect] 14253[section:body_limit http::basic_parser::body_limit] 14254[indexterm2 body_limit..http::basic_parser] 14255Set the limit on the payload body. 14256[heading Synopsis] 14257``` 14258void 14259body_limit( 14260 std::uint64_t v); 14261``` 14262 14263[heading Description] 14264This function sets the maximum allowed size of the payload body, before any encodings except chunked have been removed. Depending on the message semantics, one of these cases will apply: 14265 14266* The Content-Length is specified and exceeds the limit. In this case the result [link beast.ref.boost__beast__http__error `http::body_limit`] is returned immediately after the header is parsed. 14267 14268 14269* The Content-Length is unspecified and the chunked encoding is not specified as the last encoding. In this case the end of message is determined by the end of file indicator on the associated stream or input source. If a sufficient number of body payload octets are presented to the parser to exceed the configured limit, the parse fails with the result [link beast.ref.boost__beast__http__error `http::body_limit`] 14270 14271 14272* The Transfer-Encoding specifies the chunked encoding as the last encoding. In this case, when the number of payload body octets produced by removing the chunked encoding exceeds the configured limit, the parse fails with the result [link beast.ref.boost__beast__http__error `http::body_limit`]. 14273 14274Setting the limit after any body octets have been parsed results in undefined behavior. 14275The default limit is 1MB for requests and 8MB for responses. 14276[heading Parameters] 14277[table [[Name][Description]] 14278 [[`v`][ 14279 14280The payload body limit to set 14281 ]] 14282] 14283[endsect] 14284[section:chunked http::basic_parser::chunked] 14285[indexterm2 chunked..http::basic_parser] 14286Returns `true` if the last value for Transfer-Encoding is "chunked". 14287[heading Synopsis] 14288``` 14289bool 14290chunked() const; 14291``` 14292 14293[heading Description] 14294[heading Remarks] 14295The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 14296[endsect] 14297[section:content_length http::basic_parser::content_length] 14298[indexterm2 content_length..http::basic_parser] 14299Returns the optional value of Content-Length if known. 14300[heading Synopsis] 14301``` 14302boost::optional< std::uint64_t > 14303content_length() const; 14304``` 14305 14306[heading Description] 14307[heading Remarks] 14308The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 14309[endsect] 14310[section:content_length_remaining http::basic_parser::content_length_remaining] 14311[indexterm2 content_length_remaining..http::basic_parser] 14312Returns the remaining content length if known. 14313[heading Synopsis] 14314``` 14315boost::optional< std::uint64_t > 14316content_length_remaining() const; 14317``` 14318 14319[heading Description] 14320If the message header specifies a Content-Length, the return value will be the number of bytes remaining in the payload body have not yet been parsed. 14321[heading Remarks] 14322The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 14323[endsect] 14324[section:eager http::basic_parser::eager] 14325[indexterm2 eager..http::basic_parser] 14326Returns `true` if the eager parse option is set. ``` 14327bool 14328``[link beast.ref.boost__beast__http__basic_parser.eager.overload1 eager]``() const; 14329 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.eager.overload1 more...]]`` 14330 14331``` 14332Set the eager parse option. ``` 14333void 14334``[link beast.ref.boost__beast__http__basic_parser.eager.overload2 eager]``( 14335 bool v); 14336 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.eager.overload2 more...]]`` 14337``` 14338[section:overload1 http::basic_parser::eager (1 of 2 overloads)] 14339Returns `true` if the eager parse option is set. 14340[heading Synopsis] 14341``` 14342bool 14343eager() const; 14344``` 14345 14346[heading Description] 14347[endsect] 14348[section:overload2 http::basic_parser::eager (2 of 2 overloads)] 14349Set the eager parse option. 14350[heading Synopsis] 14351``` 14352void 14353eager( 14354 bool v); 14355``` 14356 14357[heading Description] 14358Normally the parser returns after successfully parsing a structured element (header, chunk header, or chunk body) even if there are octets remaining in the input. This is necessary when attempting to parse the header first, or when the caller wants to inspect information which may be invalidated by subsequent parsing, such as a chunk extension. The `eager` option controls whether the parser keeps going after parsing structured element if there are octets remaining in the buffer and no error occurs. This option is automatically set or cleared during certain stream operations to improve performance with no change in functionality. 14359The default setting is `false`. 14360[heading Parameters] 14361[table [[Name][Description]] 14362 [[`v`][ 14363 14364`true` to set the eager parse option or `false` to disable it. 14365 ]] 14366] 14367[endsect] 14368[endsect] 14369 14370[section:got_some http::basic_parser::got_some] 14371[indexterm2 got_some..http::basic_parser] 14372Returns `true` if the parser has received at least one byte of input. 14373[heading Synopsis] 14374``` 14375bool 14376got_some() const; 14377``` 14378 14379[heading Description] 14380[endsect] 14381[section:header_limit http::basic_parser::header_limit] 14382[indexterm2 header_limit..http::basic_parser] 14383Set a limit on the total size of the header. 14384[heading Synopsis] 14385``` 14386void 14387header_limit( 14388 std::uint32_t v); 14389``` 14390 14391[heading Description] 14392This function sets the maximum allowed size of the header including all field name, value, and delimiter characters and also including the CRLF sequences in the serialized input. If the end of the header is not found within the limit of the header size, the error [link beast.ref.boost__beast__http__error `http::header_limit`] is returned by [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`]. 14393Setting the limit after any header octets have been parsed results in undefined behavior. [endsect] 14394[section:is_done http::basic_parser::is_done] 14395[indexterm2 is_done..http::basic_parser] 14396Returns `true` if the message is complete. 14397[heading Synopsis] 14398``` 14399bool 14400is_done() const; 14401``` 14402 14403[heading Description] 14404The message is complete after the full header is prduced and one of the following is true: 14405 14406* The skip body option was set. 14407 14408 14409* The semantics of the message indicate there is no body. 14410 14411 14412* The semantics of the message indicate a body is expected, and the entire body was parsed. 14413 14414[endsect] 14415[section:is_header_done http::basic_parser::is_header_done] 14416[indexterm2 is_header_done..http::basic_parser] 14417Returns `true` if a the parser has produced the full header. 14418[heading Synopsis] 14419``` 14420bool 14421is_header_done() const; 14422``` 14423 14424[heading Description] 14425[endsect] 14426[section:is_request http::basic_parser::is_request] 14427[indexterm2 is_request..http::basic_parser] 14428`true` if this parser parses requests, `false` for responses. 14429[heading Synopsis] 14430 14431``` 14432using is_request = std::integral_constant< bool, isRequest >; 14433``` 14434 14435[heading Description] 14436[endsect] 14437[section:keep_alive http::basic_parser::keep_alive] 14438[indexterm2 keep_alive..http::basic_parser] 14439Returns `true` if the message has keep-alive connection semantics. 14440[heading Synopsis] 14441``` 14442bool 14443keep_alive() const; 14444``` 14445 14446[heading Description] 14447This function always returns `false` if [link beast.ref.boost__beast__http__basic_parser.need_eof `http::basic_parser::need_eof`] would return `false`. 14448[heading Remarks] 14449The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 14450[endsect] 14451[section:need_eof http::basic_parser::need_eof] 14452[indexterm2 need_eof..http::basic_parser] 14453Returns `true` if the message semantics require an end of file. 14454[heading Synopsis] 14455``` 14456bool 14457need_eof() const; 14458``` 14459 14460[heading Description] 14461Depending on the contents of the header, the parser may require and end of file notification to know where the end of the body lies. If this function returns `true` it will be necessary to call [link beast.ref.boost__beast__http__basic_parser.put_eof `http::basic_parser::put_eof`] when there will never be additional data from the input. [endsect] 14462[section:on_body_impl http::basic_parser::on_body_impl] 14463[indexterm2 on_body_impl..http::basic_parser] 14464Called each time additional data is received representing the content body. 14465[heading Synopsis] 14466``` 14467std::size_t 14468on_body_impl( 14469 string_view body, 14470 error_code& ec); 14471``` 14472 14473[heading Description] 14474This virtual function is invoked for each piece of the body which is received while parsing of a message. This function is only used when no chunked transfer encoding is present. 14475[heading Parameters] 14476[table [[Name][Description]] 14477 [[`body`][ 14478 14479A string holding the additional body contents. This may contain nulls or unprintable characters. 14480 ]] 14481 [[`ec`][ 14482 14483An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14484 ]] 14485] 14486[heading See Also] 14487[link beast.ref.boost__beast__http__basic_parser.on_chunk_body_impl `http::basic_parser::on_chunk_body_impl`] 14488[endsect] 14489[section:on_body_init_impl http::basic_parser::on_body_init_impl] 14490[indexterm2 on_body_init_impl..http::basic_parser] 14491Called once before the body is processed. 14492[heading Synopsis] 14493``` 14494void 14495on_body_init_impl( 14496 boost::optional< std::uint64_t > const& content_length, 14497 error_code& ec); 14498``` 14499 14500[heading Description] 14501This virtual function is invoked once, before the content body is processed (but after the complete header is received). 14502[heading Parameters] 14503[table [[Name][Description]] 14504 [[`content_length`][ 14505 14506A value representing the content length in bytes if the length is known (this can include a zero length). Otherwise, the value will be `boost::none`. 14507 ]] 14508 [[`ec`][ 14509 14510An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14511 ]] 14512] 14513[endsect] 14514[section:on_chunk_body_impl http::basic_parser::on_chunk_body_impl] 14515[indexterm2 on_chunk_body_impl..http::basic_parser] 14516Called each time additional data is received representing part of a body chunk. 14517[heading Synopsis] 14518``` 14519std::size_t 14520on_chunk_body_impl( 14521 std::uint64_t remain, 14522 string_view body, 14523 error_code& ec); 14524``` 14525 14526[heading Description] 14527This virtual function is invoked for each piece of the body which is received while parsing of a message. This function is only used when no chunked transfer encoding is present. 14528[heading Parameters] 14529[table [[Name][Description]] 14530 [[`remain`][ 14531 14532The number of bytes remaining in this chunk. This includes the contents of passed `body`. If this value is zero, then this represents the final chunk. 14533 ]] 14534 [[`body`][ 14535 14536A string holding the additional body contents. This may contain nulls or unprintable characters. 14537 ]] 14538 [[`ec`][ 14539 14540An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14541 ]] 14542] 14543[heading Return Value] 14544This function should return the number of bytes actually consumed from the `body` value. Any bytes that are not consumed on this call will be presented in a subsequent call. 14545[heading See Also] 14546[link beast.ref.boost__beast__http__basic_parser.on_body_impl `http::basic_parser::on_body_impl`] 14547[endsect] 14548[section:on_chunk_header_impl http::basic_parser::on_chunk_header_impl] 14549[indexterm2 on_chunk_header_impl..http::basic_parser] 14550Called each time a new chunk header of a chunk encoded body is received. 14551[heading Synopsis] 14552``` 14553void 14554on_chunk_header_impl( 14555 std::uint64_t size, 14556 string_view extensions, 14557 error_code& ec); 14558``` 14559 14560[heading Description] 14561This function is invoked each time a new chunk header is received. The function is only used when the chunked transfer encoding is present. 14562[heading Parameters] 14563[table [[Name][Description]] 14564 [[`size`][ 14565 14566The size of this chunk, in bytes. 14567 ]] 14568 [[`extensions`][ 14569 14570A string containing the entire chunk extensions. This may be empty, indicating no extensions are present. 14571 ]] 14572 [[`ec`][ 14573 14574An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14575 ]] 14576] 14577[endsect] 14578[section:on_field_impl http::basic_parser::on_field_impl] 14579[indexterm2 on_field_impl..http::basic_parser] 14580Called once for each complete field in the HTTP header. 14581[heading Synopsis] 14582``` 14583void 14584on_field_impl( 14585 field name, 14586 string_view name_string, 14587 string_view value, 14588 error_code& ec); 14589``` 14590 14591[heading Description] 14592This virtual function is invoked for each field that is received while parsing an HTTP message. 14593[heading Parameters] 14594[table [[Name][Description]] 14595 [[`name`][ 14596 14597The known field enum value. If the name of the field is not recognized, this value will be [link beast.ref.boost__beast__http__field `http::unknown`]. 14598 ]] 14599 [[`name_string`][ 14600 14601The exact name of the field as received from the input, represented as a string. 14602 ]] 14603 [[`value`][ 14604 14605A string holding the value of the field. 14606 ]] 14607 [[`ec`][ 14608 14609An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14610 ]] 14611] 14612[endsect] 14613[section:on_finish_impl http::basic_parser::on_finish_impl] 14614[indexterm2 on_finish_impl..http::basic_parser] 14615Called once when the complete message is received. 14616[heading Synopsis] 14617``` 14618void 14619on_finish_impl( 14620 error_code& ec); 14621``` 14622 14623[heading Description] 14624This virtual function is invoked once, after successfully parsing a complete HTTP message. 14625[heading Parameters] 14626[table [[Name][Description]] 14627 [[`ec`][ 14628 14629An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14630 ]] 14631] 14632[endsect] 14633[section:on_header_impl http::basic_parser::on_header_impl] 14634[indexterm2 on_header_impl..http::basic_parser] 14635Called once after the complete HTTP header is received. 14636[heading Synopsis] 14637``` 14638void 14639on_header_impl( 14640 error_code& ec); 14641``` 14642 14643[heading Description] 14644This virtual function is invoked once, after the complete HTTP header is received while parsing a message. 14645[heading Parameters] 14646[table [[Name][Description]] 14647 [[`ec`][ 14648 14649An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14650 ]] 14651] 14652[endsect] 14653[section:on_request_impl http::basic_parser::on_request_impl] 14654[indexterm2 on_request_impl..http::basic_parser] 14655Called after receiving the request-line. 14656[heading Synopsis] 14657``` 14658void 14659on_request_impl( 14660 verb method, 14661 string_view method_str, 14662 string_view target, 14663 int version, 14664 error_code& ec); 14665``` 14666 14667[heading Description] 14668This virtual function is invoked after receiving a request-line when parsing HTTP requests. It can only be called when `isRequest == true`. 14669[heading Parameters] 14670[table [[Name][Description]] 14671 [[`method`][ 14672 14673The verb enumeration. If the method string is not one of the predefined strings, this value will be [link beast.ref.boost__beast__http__field `http::unknown`]. 14674 ]] 14675 [[`method_str`][ 14676 14677The unmodified string representing the verb. 14678 ]] 14679 [[`target`][ 14680 14681The request-target. 14682 ]] 14683 [[`version`][ 14684 14685The HTTP-version. This will be 10 for HTTP/1.0, and 11 for HTTP/1.1. 14686 ]] 14687 [[`ec`][ 14688 14689An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14690 ]] 14691] 14692[endsect] 14693[section:on_response_impl http::basic_parser::on_response_impl] 14694[indexterm2 on_response_impl..http::basic_parser] 14695Called after receiving the status-line. 14696[heading Synopsis] 14697``` 14698void 14699on_response_impl( 14700 int code, 14701 string_view reason, 14702 int version, 14703 error_code& ec); 14704``` 14705 14706[heading Description] 14707This virtual function is invoked after receiving a status-line when parsing HTTP responses. It can only be called when `isRequest == false`. 14708[heading Parameters] 14709[table [[Name][Description]] 14710 [[`code`][ 14711 14712The numeric status code. 14713 ]] 14714 [[`reason`][ 14715 14716The reason-phrase. Note that this value is now obsolete, and only provided for historical or diagnostic purposes. 14717 ]] 14718 [[`version`][ 14719 14720The HTTP-version. This will be 10 for HTTP/1.0, and 11 for HTTP/1.1. 14721 ]] 14722 [[`ec`][ 14723 14724An output parameter which the function may set to indicate an error. The error will be clear before this function is invoked. 14725 ]] 14726] 14727[endsect] 14728[section:operator_eq_ http::basic_parser::operator=] 14729[indexterm2 operator=..http::basic_parser] 14730Move assignment. 14731[heading Synopsis] 14732``` 14733basic_parser& 14734operator=( 14735 basic_parser&&); 14736``` 14737 14738[heading Description] 14739[endsect] 14740[section:operator_eq_ http::basic_parser::operator=] 14741[indexterm2 operator=..http::basic_parser] 14742Copy assignment. 14743[heading Synopsis] 14744``` 14745basic_parser& 14746operator=( 14747 basic_parser const&); 14748``` 14749 14750[heading Description] 14751[endsect] 14752[section:put http::basic_parser::put] 14753[indexterm2 put..http::basic_parser] 14754Write a buffer sequence to the parser. 14755[heading Synopsis] 14756``` 14757template< 14758 class __ConstBufferSequence__> 14759std::size_t 14760put( 14761 ConstBufferSequence const& buffers, 14762 error_code& ec); 14763``` 14764 14765[heading Description] 14766This function attempts to incrementally parse the HTTP message data stored in the caller provided buffers. Upon success, a positive return value indicates that the parser made forward progress, consuming that number of bytes. 14767In some cases there may be an insufficient number of octets in the input buffer in order to make forward progress. This is indicated by the code [link beast.ref.boost__beast__http__error `http::need_more`]. When this happens, the caller should place additional bytes into the buffer sequence and call [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] again. 14768The error code [link beast.ref.boost__beast__http__error `http::need_more`] is special. When this error is returned, a subsequent call to [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] may succeed if the buffers have been updated. Otherwise, upon error the parser may not be restarted. 14769[heading Parameters] 14770[table [[Name][Description]] 14771 [[`buffers`][ 14772 14773An object meeting the requirements of ['ConstBufferSequence] that represents the next chunk of message data. If the length of this buffer sequence is one, the implementation will not allocate additional memory. The class [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`] is provided as one way to meet this requirement 14774 ]] 14775 [[`ec`][ 14776 14777Set to the error, if any occurred. 14778 ]] 14779] 14780[heading Return Value] 14781The number of octets consumed in the buffer sequence. The caller should remove these octets even if the error is set. 14782[endsect] 14783[section:put_eof http::basic_parser::put_eof] 14784[indexterm2 put_eof..http::basic_parser] 14785Inform the parser that the end of stream was reached. 14786[heading Synopsis] 14787``` 14788void 14789put_eof( 14790 error_code& ec); 14791``` 14792 14793[heading Description] 14794In certain cases, HTTP needs to know where the end of the stream is. For example, sometimes servers send responses without Content-Length and expect the client to consume input (for the body) until EOF. Callbacks and errors will still be processed as usual. 14795This is typically called when a read from the underlying stream object sets the error code to `net::error::eof`. 14796[heading Remarks] 14797Only valid after parsing a complete header. 14798[heading Parameters] 14799[table [[Name][Description]] 14800 [[`ec`][ 14801 14802Set to the error, if any occurred. 14803 ]] 14804] 14805[endsect] 14806[section:skip http::basic_parser::skip] 14807[indexterm2 skip..http::basic_parser] 14808Returns `true` if the skip parse option is set. ``` 14809bool 14810``[link beast.ref.boost__beast__http__basic_parser.skip.overload1 skip]``() const; 14811 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.skip.overload1 more...]]`` 14812 14813``` 14814Set the skip parse option. ``` 14815void 14816``[link beast.ref.boost__beast__http__basic_parser.skip.overload2 skip]``( 14817 bool v); 14818 ``[''''»''' [link beast.ref.boost__beast__http__basic_parser.skip.overload2 more...]]`` 14819``` 14820[section:overload1 http::basic_parser::skip (1 of 2 overloads)] 14821Returns `true` if the skip parse option is set. 14822[heading Synopsis] 14823``` 14824bool 14825skip() const; 14826``` 14827 14828[heading Description] 14829[endsect] 14830[section:overload2 http::basic_parser::skip (2 of 2 overloads)] 14831Set the skip parse option. 14832[heading Synopsis] 14833``` 14834void 14835skip( 14836 bool v); 14837``` 14838 14839[heading Description] 14840This option controls whether or not the parser expects to see an HTTP body, regardless of the presence or absence of certain fields such as Content-Length or a chunked Transfer-Encoding. Depending on the request, some responses do not carry a body. For example, a 200 response to a CONNECT request from a tunneling proxy, or a response to a HEAD request. In these cases, callers may use this function inform the parser that no body is expected. The parser will consider the message complete after the header has been received. 14841[heading Parameters] 14842[table [[Name][Description]] 14843 [[`v`][ 14844 14845`true` to set the skip body option or `false` to disable it. 14846 ]] 14847] 14848[heading Remarks] 14849This function must called before any bytes are processed. 14850[endsect] 14851[endsect] 14852 14853[section:upgrade http::basic_parser::upgrade] 14854[indexterm2 upgrade..http::basic_parser] 14855Returns `true` if the message is an upgrade message. 14856[heading Synopsis] 14857``` 14858bool 14859upgrade() const; 14860``` 14861 14862[heading Description] 14863[heading Remarks] 14864The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 14865[endsect] 14866[section:basic_parser_dtor_ http::basic_parser::~basic_parser] 14867[indexterm2 ~basic_parser..http::basic_parser] 14868Destructor. 14869[heading Synopsis] 14870``` 14871virtual 14872~basic_parser(); 14873``` 14874 14875[heading Description] 14876[endsect] 14877 14878 14879 14880Convenience header [include_file boost/beast/http.hpp] 14881 14882[endsect] 14883 14884 14885 14886[section:boost__beast__http__basic_string_body http::basic_string_body] 14887A ['Body] using `std::basic_string` 14888[heading Synopsis] 14889 14890Defined in header [include_file boost/beast/http/string_body.hpp] 14891 14892 14893 14894``` 14895template< 14896 class CharT, 14897 class Traits = std::char_traits<CharT>, 14898 class __Allocator__ = std::allocator<CharT>> 14899struct basic_string_body 14900``` 14901[heading Types] 14902[table [[Name][Description]] 14903 [ 14904 [[link beast.ref.boost__beast__http__basic_string_body.reader [*reader]]] 14905 [ 14906 The algorithm for parsing the body. 14907 ] 14908 ] 14909 [ 14910 [[link beast.ref.boost__beast__http__basic_string_body.value_type [*value_type]]] 14911 [ 14912 The type of container used for the body. 14913 ] 14914 ] 14915 [ 14916 [[link beast.ref.boost__beast__http__basic_string_body.writer [*writer]]] 14917 [ 14918 The algorithm for serializing the body. 14919 ] 14920 ] 14921] 14922[heading Member Functions] 14923[table [[Name][Description]] 14924 [ 14925 [[link beast.ref.boost__beast__http__basic_string_body.size [*size]]] 14926 [ 14927 Returns the payload size of the body. 14928 ] 14929 ] 14930] 14931 14932[heading Description] 14933This body uses `std::basic_string` as a memory-based container for holding message payloads. Messages using this body type may be serialized and parsed. [section:reader http::basic_string_body::reader] 14934[indexterm2 reader..http::basic_string_body] 14935The algorithm for parsing the body. 14936[heading Synopsis] 14937 14938``` 14939using reader = ``['implementation-defined]``; 14940``` 14941 14942[heading Description] 14943Meets the requirements of ['BodyReader]. [endsect] 14944[section:size http::basic_string_body::size] 14945[indexterm2 size..http::basic_string_body] 14946Returns the payload size of the body. 14947[heading Synopsis] 14948``` 14949static 14950std::uint64_t 14951size( 14952 value_type const& body); 14953``` 14954 14955[heading Description] 14956When this body is used with [link beast.ref.boost__beast__http__message.prepare_payload `http::message::prepare_payload`], the Content-Length will be set to the payload size, and any chunked Transfer-Encoding will be removed. [endsect] 14957[section:value_type http::basic_string_body::value_type] 14958[indexterm2 value_type..http::basic_string_body] 14959The type of container used for the body. 14960[heading Synopsis] 14961 14962``` 14963using value_type = std::basic_string< CharT, Traits, Allocator >; 14964``` 14965 14966[heading Description] 14967This determines the type of [link beast.ref.boost__beast__http__message.body `http::message::body`] when this body type is used with a message container. [endsect] 14968[section:writer http::basic_string_body::writer] 14969[indexterm2 writer..http::basic_string_body] 14970The algorithm for serializing the body. 14971[heading Synopsis] 14972 14973``` 14974using writer = ``['implementation-defined]``; 14975``` 14976 14977[heading Description] 14978Meets the requirements of ['BodyWriter]. [endsect] 14979 14980 14981 14982Convenience header [include_file boost/beast/http.hpp] 14983 14984[endsect] 14985 14986 14987 14988[section:boost__beast__http__buffer_body http::buffer_body] 14989A ['Body] using a caller provided buffer. 14990[heading Synopsis] 14991 14992Defined in header [include_file boost/beast/http/buffer_body.hpp] 14993 14994 14995 14996``` 14997struct buffer_body 14998``` 14999[heading Types] 15000[table [[Name][Description]] 15001 [ 15002 [[link beast.ref.boost__beast__http__buffer_body__value_type [*value_type]]] 15003 [ 15004 The type of the body member when used in a message. 15005 ] 15006 ] 15007 [ 15008 [[link beast.ref.boost__beast__http__buffer_body.reader [*reader]]] 15009 [ 15010 The algorithm for parsing the body. 15011 ] 15012 ] 15013 [ 15014 [[link beast.ref.boost__beast__http__buffer_body.writer [*writer]]] 15015 [ 15016 The algorithm for serializing the body. 15017 ] 15018 ] 15019] 15020 15021[heading Description] 15022Messages using this body type may be serialized and parsed. To use this class, the caller must initialize the members of [link beast.ref.boost__beast__http__buffer_body__value_type `http::buffer_body::value_type`] to appropriate values before each call to read or write during a stream operation. [section:reader http::buffer_body::reader] 15023[indexterm2 reader..http::buffer_body] 15024The algorithm for parsing the body. 15025[heading Synopsis] 15026 15027``` 15028using reader = ``['implementation-defined]``; 15029``` 15030 15031[heading Description] 15032Meets the requirements of ['BodyReader]. [endsect] 15033[section:writer http::buffer_body::writer] 15034[indexterm2 writer..http::buffer_body] 15035The algorithm for serializing the body. 15036[heading Synopsis] 15037 15038``` 15039using writer = ``['implementation-defined]``; 15040``` 15041 15042[heading Description] 15043Meets the requirements of ['BodyWriter]. [endsect] 15044 15045 15046 15047Convenience header [include_file boost/beast/http.hpp] 15048 15049[endsect] 15050 15051 15052 15053[section:boost__beast__http__buffer_body__value_type http::buffer_body::value_type] 15054The type of the body member when used in a message. 15055[heading Synopsis] 15056 15057Defined in header [include_file boost/beast/http/buffer_body.hpp] 15058 15059 15060 15061``` 15062struct value_type 15063``` 15064[heading Data Members] 15065[table [[Name][Description]] 15066 [ 15067 [[link beast.ref.boost__beast__http__buffer_body__value_type.data [*data]]] 15068 [ 15069 A pointer to a contiguous area of memory of size octets, else nullptr. 15070 ] 15071 ] 15072 [ 15073 [[link beast.ref.boost__beast__http__buffer_body__value_type.more [*more]]] 15074 [ 15075 true if this is not the last buffer. 15076 ] 15077 ] 15078 [ 15079 [[link beast.ref.boost__beast__http__buffer_body__value_type.size [*size]]] 15080 [ 15081 The number of octets in the buffer pointed to by data. 15082 ] 15083 ] 15084] 15085 15086[heading Description] 15087[section:data http::buffer_body::value_type::data] 15088[indexterm2 data..http::buffer_body::value_type] 15089A pointer to a contiguous area of memory of [link beast.ref.boost__beast__http__buffer_body__value_type.size `http::buffer_body::value_type::size`] octets, else `nullptr`. 15090[heading Synopsis] 15091``` 15092void * data = nullptr; 15093``` 15094 15095[heading Description] 15096[heading When Serializing] 15097 15098If this is `nullptr` and `more` is `true`, the error [link beast.ref.boost__beast__http__error `http::need_buffer`] will be returned from [link beast.ref.boost__beast__http__serializer.get `http::serializer::get`] Otherwise, the serializer will use the memory pointed to by `data` having `size` octets of valid storage as the next buffer representing the body. 15099[heading When Parsing] 15100 15101If this is `nullptr`, the error [link beast.ref.boost__beast__http__error `http::need_buffer`] will be returned from [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`]. Otherwise, the parser will store body octets into the memory pointed to by `data` having `size` octets of valid storage. After octets are stored, the `data` and `size` members are adjusted: `data` is incremented to point to the next octet after the data written, while `size` is decremented to reflect the remaining space at the memory location pointed to by `data`. [endsect] 15102[section:more http::buffer_body::value_type::more] 15103[indexterm2 more..http::buffer_body::value_type] 15104`true` if this is not the last buffer. 15105[heading Synopsis] 15106``` 15107bool more = true; 15108``` 15109 15110[heading Description] 15111[heading When Serializing] 15112 15113If this is `true` and `data` is `nullptr`, the error [link beast.ref.boost__beast__http__error `http::need_buffer`] will be returned from [link beast.ref.boost__beast__http__serializer.get `http::serializer::get`] 15114[heading When Parsing] 15115 15116This field is not used during parsing. [endsect] 15117[section:size http::buffer_body::value_type::size] 15118[indexterm2 size..http::buffer_body::value_type] 15119The number of octets in the buffer pointed to by [link beast.ref.boost__beast__http__buffer_body__value_type.data `http::buffer_body::value_type::data`]. 15120[heading Synopsis] 15121``` 15122std::size_t size = 0; 15123``` 15124 15125[heading Description] 15126[heading When Serializing] 15127 15128If `data` is `nullptr` during serialization, this value is ignored. Otherwise, it represents the number of valid body octets pointed to by `data`. 15129[heading When Parsing] 15130 15131The value of this field will be decremented during parsing to indicate the number of remaining free octets in the buffer pointed to by `data`. When it reaches zero, the parser will return [link beast.ref.boost__beast__http__error `http::need_buffer`], indicating to the caller that the values of `data` and `size` should be updated to point to a new memory buffer. [endsect] 15132 15133 15134 15135Convenience header [include_file boost/beast/http.hpp] 15136 15137[endsect] 15138 15139 15140 15141[section:boost__beast__http__chunk_body http::chunk_body] 15142A ['chunk]. 15143[heading Synopsis] 15144 15145Defined in header [include_file boost/beast/http/chunk_encode.hpp] 15146 15147 15148 15149``` 15150template< 15151 class __ConstBufferSequence__> 15152class chunk_body 15153``` 15154[heading Types] 15155[table [[Name][Description]] 15156 [ 15157 [[link beast.ref.boost__beast__http__chunk_body.const_iterator [*const_iterator]]] 15158 [ 15159 Required for ConstBufferSequence 15160 ] 15161 ] 15162 [ 15163 [[link beast.ref.boost__beast__http__chunk_body.value_type [*value_type]]] 15164 [ 15165 Required for ConstBufferSequence 15166 ] 15167 ] 15168] 15169[heading Member Functions] 15170[table [[Name][Description]] 15171 [ 15172 [[link beast.ref.boost__beast__http__chunk_body.begin [*begin]]] 15173 [ 15174 Required for ConstBufferSequence 15175 ] 15176 ] 15177 [ 15178 [[link beast.ref.boost__beast__http__chunk_body.chunk_body [*chunk_body]]] 15179 [ 15180 Constructor. 15181 ] 15182 ] 15183 [ 15184 [[link beast.ref.boost__beast__http__chunk_body.end [*end]]] 15185 [ 15186 Required for ConstBufferSequence 15187 ] 15188 ] 15189] 15190 15191[heading Description] 15192This implements a ['ConstBufferSequence] representing a ['chunk]. The serialized format is as follows: 15193``` 15194 chunk = chunk-size [ chunk-ext ] CRLF chunk-data CRLF 15195 chunk-size = 1*HEXDIG 15196 chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 15197 chunk-ext-name = token 15198 chunk-ext-val = token / quoted-string 15199 chunk-data = 1*OCTET ; a sequence of chunk-size octets 15200``` 15201The chunk extension is optional. 15202To use this class, pass an instance of it to a stream algorithm as the buffer sequence. 15203[heading See Also] 15204[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15205[section:begin http::chunk_body::begin] 15206[indexterm2 begin..http::chunk_body] 15207Required for ['ConstBufferSequence] 15208[heading Synopsis] 15209``` 15210const_iterator 15211begin() const; 15212``` 15213 15214[heading Description] 15215[endsect] 15216[section:chunk_body http::chunk_body::chunk_body] 15217[indexterm2 chunk_body..http::chunk_body] 15218Constructor. ``` 15219explicit 15220``[link beast.ref.boost__beast__http__chunk_body.chunk_body.overload1 chunk_body]``( 15221 ConstBufferSequence const& buffers); 15222 ``[''''»''' [link beast.ref.boost__beast__http__chunk_body.chunk_body.overload1 more...]]`` 15223 15224``[link beast.ref.boost__beast__http__chunk_body.chunk_body.overload2 chunk_body]``( 15225 ConstBufferSequence const& buffers, 15226 string_view extensions); 15227 ``[''''»''' [link beast.ref.boost__beast__http__chunk_body.chunk_body.overload2 more...]]`` 15228 15229template< 15230 class ChunkExtensions> 15231``[link beast.ref.boost__beast__http__chunk_body.chunk_body.overload3 chunk_body]``( 15232 ConstBufferSequence const& buffers, 15233 ChunkExtensions&& extensions); 15234 ``[''''»''' [link beast.ref.boost__beast__http__chunk_body.chunk_body.overload3 more...]]`` 15235 15236template< 15237 class ChunkExtensions, 15238 class __Allocator__> 15239``[link beast.ref.boost__beast__http__chunk_body.chunk_body.overload4 chunk_body]``( 15240 ConstBufferSequence const& buffers, 15241 ChunkExtensions&& extensions, 15242 Allocator const& allocator); 15243 ``[''''»''' [link beast.ref.boost__beast__http__chunk_body.chunk_body.overload4 more...]]`` 15244``` 15245[section:overload1 http::chunk_body::chunk_body (1 of 4 overloads)] 15246Constructor. 15247[heading Synopsis] 15248``` 15249chunk_body( 15250 ConstBufferSequence const& buffers); 15251``` 15252 15253[heading Description] 15254This constructs buffers representing a complete ['chunk] with no chunk extensions and having the size and contents of the specified buffer sequence. 15255[heading Parameters] 15256[table [[Name][Description]] 15257 [[`buffers`][ 15258 15259A buffer sequence representing the chunk body. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid while this object is in use. 15260 ]] 15261] 15262[heading See Also] 15263[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15264[endsect] 15265[section:overload2 http::chunk_body::chunk_body (2 of 4 overloads)] 15266Constructor. 15267[heading Synopsis] 15268``` 15269chunk_body( 15270 ConstBufferSequence const& buffers, 15271 string_view extensions); 15272``` 15273 15274[heading Description] 15275This constructs buffers representing a complete ['chunk] with the passed chunk extensions and having the size and contents of the specified buffer sequence. 15276[heading Parameters] 15277[table [[Name][Description]] 15278 [[`buffers`][ 15279 15280A buffer sequence representing the chunk body. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid while this object is in use. 15281 ]] 15282 [[`extensions`][ 15283 15284The chunk extensions string. This string must be formatted correctly as per rfc7230, using this BNF syntax: 15285``` 15286 chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 15287 chunk-ext-name = token 15288 chunk-ext-val = token / quoted-string 15289``` 15290The data pointed to by this string view must remain valid for the lifetime of any operations performed on the object. 15291 ]] 15292] 15293[heading See Also] 15294[@https://tools.ietf.org/html/rfc7230#section-4.1.1 https://tools.ietf.org/html/rfc7230#section-4.1.1] 15295[endsect] 15296[section:overload3 http::chunk_body::chunk_body (3 of 4 overloads)] 15297Constructor. 15298[heading Synopsis] 15299``` 15300template< 15301 class ChunkExtensions> 15302chunk_body( 15303 ConstBufferSequence const& buffers, 15304 ChunkExtensions&& extensions); 15305``` 15306 15307[heading Description] 15308This constructs buffers representing a complete ['chunk] with the passed chunk extensions and having the size and contents of the specified buffer sequence. The default allocator is used to provide storage for the extensions object. 15309[heading Parameters] 15310[table [[Name][Description]] 15311 [[`buffers`][ 15312 15313A buffer sequence representing the chunk body. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid while this object is in use. 15314 ]] 15315 [[`extensions`][ 15316 15317The chunk extensions object. The expression `extensions.str()` must be valid, and the return type must be convertible to [link beast.ref.boost__beast__string_view `string_view`]. This object will be copied or moved as needed to ensure that the chunk header object retains ownership of the buffers provided by the chunk extensions object. 15318 ]] 15319] 15320[heading Remarks] 15321This function participates in overload resolution only if [*ChunkExtensions] meets the requirements stated above. 15322[heading See Also] 15323[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15324[endsect] 15325[section:overload4 http::chunk_body::chunk_body (4 of 4 overloads)] 15326Constructor. 15327[heading Synopsis] 15328``` 15329template< 15330 class ChunkExtensions, 15331 class __Allocator__> 15332chunk_body( 15333 ConstBufferSequence const& buffers, 15334 ChunkExtensions&& extensions, 15335 Allocator const& allocator); 15336``` 15337 15338[heading Description] 15339This constructs buffers representing a complete ['chunk] with the passed chunk extensions and having the size and contents of the specified buffer sequence. The specified allocator is used to provide storage for the extensions object. 15340[heading Parameters] 15341[table [[Name][Description]] 15342 [[`buffers`][ 15343 15344A buffer sequence representing the chunk body. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid while this object is in use. 15345 ]] 15346 [[`extensions`][ 15347 15348The chunk extensions object. The expression `extensions.str()` must be valid, and the return type must be convertible to [link beast.ref.boost__beast__string_view `string_view`]. This object will be copied or moved as needed to ensure that the chunk header object retains ownership of the buffers provided by the chunk extensions object. 15349 ]] 15350 [[`allocator`][ 15351 15352The allocator to provide storage for the moved or copied extensions object. 15353 ]] 15354] 15355[heading Remarks] 15356This function participates in overload resolution only if [*ChunkExtensions] meets the requirements stated above. 15357[heading See Also] 15358[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15359[endsect] 15360[endsect] 15361 15362[section:const_iterator http::chunk_body::const_iterator] 15363[indexterm2 const_iterator..http::chunk_body] 15364Required for ['ConstBufferSequence] 15365[heading Synopsis] 15366 15367``` 15368using const_iterator = ``['implementation-defined]``; 15369``` 15370 15371[heading Description] 15372[endsect] 15373[section:end http::chunk_body::end] 15374[indexterm2 end..http::chunk_body] 15375Required for ['ConstBufferSequence] 15376[heading Synopsis] 15377``` 15378const_iterator 15379end() const; 15380``` 15381 15382[heading Description] 15383[endsect] 15384[section:value_type http::chunk_body::value_type] 15385[indexterm2 value_type..http::chunk_body] 15386Required for ['ConstBufferSequence] 15387[heading Synopsis] 15388 15389``` 15390using value_type = ``['implementation-defined]``; 15391``` 15392 15393[heading Description] 15394[endsect] 15395 15396 15397 15398Convenience header [include_file boost/beast/http.hpp] 15399 15400[endsect] 15401 15402 15403 15404[section:boost__beast__http__chunk_crlf http::chunk_crlf] 15405A chunked encoding crlf. 15406[heading Synopsis] 15407 15408Defined in header [include_file boost/beast/http/chunk_encode.hpp] 15409 15410 15411 15412``` 15413struct chunk_crlf 15414``` 15415[heading Types] 15416[table [[Name][Description]] 15417 [ 15418 [[link beast.ref.boost__beast__http__chunk_crlf.const_iterator [*const_iterator]]] 15419 [ 15420 Required for ConstBufferSequence 15421 ] 15422 ] 15423 [ 15424 [[link beast.ref.boost__beast__http__chunk_crlf.value_type [*value_type]]] 15425 [ 15426 Required for ConstBufferSequence 15427 ] 15428 ] 15429] 15430[heading Member Functions] 15431[table [[Name][Description]] 15432 [ 15433 [[link beast.ref.boost__beast__http__chunk_crlf.begin [*begin]]] 15434 [ 15435 Required for ConstBufferSequence 15436 ] 15437 ] 15438 [ 15439 [[link beast.ref.boost__beast__http__chunk_crlf.chunk_crlf [*chunk_crlf]]] 15440 [ 15441 Constructor. 15442 15443 Required for ConstBufferSequence 15444 ] 15445 ] 15446 [ 15447 [[link beast.ref.boost__beast__http__chunk_crlf.end [*end]]] 15448 [ 15449 Required for ConstBufferSequence 15450 ] 15451 ] 15452] 15453 15454[heading Description] 15455This implements a ['ConstBufferSequence] holding the CRLF (`"\r\n"`) used as a delimiter in a ['chunk]. 15456To use this class, pass an instance of it to a stream algorithm as the buffer sequence: 15457``` 15458 // writes "\r\n" 15459 net::write(stream, chunk_crlf{}); 15460``` 15461[heading See Also] 15462[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15463[section:begin http::chunk_crlf::begin] 15464[indexterm2 begin..http::chunk_crlf] 15465Required for ['ConstBufferSequence] 15466[heading Synopsis] 15467``` 15468const_iterator 15469begin() const; 15470``` 15471 15472[heading Description] 15473[endsect] 15474[section:chunk_crlf http::chunk_crlf::chunk_crlf] 15475[indexterm2 chunk_crlf..http::chunk_crlf] 15476Constructor. ``` 15477``[link beast.ref.boost__beast__http__chunk_crlf.chunk_crlf.overload1 chunk_crlf]``(); 15478 ``[''''»''' [link beast.ref.boost__beast__http__chunk_crlf.chunk_crlf.overload1 more...]]`` 15479 15480``` 15481Required for ['ConstBufferSequence] ``` 15482``[link beast.ref.boost__beast__http__chunk_crlf.chunk_crlf.overload2 chunk_crlf]``( 15483 chunk_crlf const&); 15484 ``[''''»''' [link beast.ref.boost__beast__http__chunk_crlf.chunk_crlf.overload2 more...]]`` 15485``` 15486[section:overload1 http::chunk_crlf::chunk_crlf (1 of 2 overloads)] 15487Constructor. 15488[heading Synopsis] 15489``` 15490chunk_crlf(); 15491``` 15492 15493[heading Description] 15494[endsect] 15495[section:overload2 http::chunk_crlf::chunk_crlf (2 of 2 overloads)] 15496Required for ['ConstBufferSequence] 15497[heading Synopsis] 15498``` 15499chunk_crlf( 15500 chunk_crlf const&); 15501``` 15502 15503[heading Description] 15504[endsect] 15505[endsect] 15506 15507[section:const_iterator http::chunk_crlf::const_iterator] 15508[indexterm2 const_iterator..http::chunk_crlf] 15509Required for ['ConstBufferSequence] 15510[heading Synopsis] 15511 15512``` 15513using const_iterator = value_type const *; 15514``` 15515 15516[heading Description] 15517[endsect] 15518[section:end http::chunk_crlf::end] 15519[indexterm2 end..http::chunk_crlf] 15520Required for ['ConstBufferSequence] 15521[heading Synopsis] 15522``` 15523const_iterator 15524end() const; 15525``` 15526 15527[heading Description] 15528[endsect] 15529[section:value_type http::chunk_crlf::value_type] 15530[indexterm2 value_type..http::chunk_crlf] 15531Required for ['ConstBufferSequence] 15532[heading Synopsis] 15533 15534``` 15535using value_type = ``['implementation-defined]``; 15536``` 15537 15538[heading Description] 15539[endsect] 15540 15541 15542 15543Convenience header [include_file boost/beast/http.hpp] 15544 15545[endsect] 15546 15547 15548 15549[section:boost__beast__http__chunk_extensions http::chunk_extensions] 15550[indexterm1 http::chunk_extensions] 15551A set of chunk extensions. 15552[heading Synopsis] 15553 15554Defined in header [include_file boost/beast/http/chunk_encode.hpp] 15555 15556 15557 15558``` 15559using chunk_extensions = basic_chunk_extensions< std::allocator< char > >; 15560``` 15561[heading Types] 15562[table [[Name][Description]] 15563 [ 15564 [[link beast.ref.boost__beast__http__basic_chunk_extensions.value_type [*value_type]]] 15565 [ 15566 The type of value when iterating. 15567 ] 15568 ] 15569] 15570[heading Member Functions] 15571[table [[Name][Description]] 15572 [ 15573 [[link beast.ref.boost__beast__http__basic_chunk_extensions.basic_chunk_extensions [*basic_chunk_extensions]]] 15574 [ 15575 Constructor. 15576 ] 15577 ] 15578 [ 15579 [[link beast.ref.boost__beast__http__basic_chunk_extensions.begin [*begin]]] 15580 [ 15581 15582 ] 15583 ] 15584 [ 15585 [[link beast.ref.boost__beast__http__basic_chunk_extensions.clear [*clear]]] 15586 [ 15587 Clear the chunk extensions. 15588 ] 15589 ] 15590 [ 15591 [[link beast.ref.boost__beast__http__basic_chunk_extensions.end [*end]]] 15592 [ 15593 15594 ] 15595 ] 15596 [ 15597 [[link beast.ref.boost__beast__http__basic_chunk_extensions.insert [*insert]]] 15598 [ 15599 Insert an extension name with an empty value. 15600 15601 Insert an extension value. 15602 ] 15603 ] 15604 [ 15605 [[link beast.ref.boost__beast__http__basic_chunk_extensions.parse [*parse]]] 15606 [ 15607 Parse a set of chunk extensions. 15608 ] 15609 ] 15610 [ 15611 [[link beast.ref.boost__beast__http__basic_chunk_extensions.str [*str]]] 15612 [ 15613 Return the serialized representation of the chunk extension. 15614 ] 15615 ] 15616] 15617This container stores a set of chunk extensions suited for use with [link beast.ref.boost__beast__http__chunk_header `http::chunk_header`] and [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`]. The container may be iterated to access the extensions in their structured form. 15618Meets the requirements of ChunkExtensions 15619[heading Description] 15620 15621 15622 15623Convenience header [include_file boost/beast/http.hpp] 15624 15625[endsect] 15626[section:boost__beast__http__chunk_header http::chunk_header] 15627A ['chunk] header. 15628[heading Synopsis] 15629 15630Defined in header [include_file boost/beast/http/chunk_encode.hpp] 15631 15632 15633 15634``` 15635class chunk_header 15636``` 15637[heading Types] 15638[table [[Name][Description]] 15639 [ 15640 [[link beast.ref.boost__beast__http__chunk_header.const_iterator [*const_iterator]]] 15641 [ 15642 Required for ConstBufferSequence 15643 ] 15644 ] 15645 [ 15646 [[link beast.ref.boost__beast__http__chunk_header.value_type [*value_type]]] 15647 [ 15648 Required for ConstBufferSequence 15649 ] 15650 ] 15651] 15652[heading Member Functions] 15653[table [[Name][Description]] 15654 [ 15655 [[link beast.ref.boost__beast__http__chunk_header.begin [*begin]]] 15656 [ 15657 Required for ConstBufferSequence 15658 ] 15659 ] 15660 [ 15661 [[link beast.ref.boost__beast__http__chunk_header.chunk_header [*chunk_header]]] 15662 [ 15663 Constructor. 15664 15665 Required for ConstBufferSequence 15666 ] 15667 ] 15668 [ 15669 [[link beast.ref.boost__beast__http__chunk_header.end [*end]]] 15670 [ 15671 Required for ConstBufferSequence 15672 ] 15673 ] 15674] 15675 15676[heading Description] 15677This implements a ['ConstBufferSequence] representing the header of a ['chunk]. The serialized format is as follows: 15678``` 15679 chunk-header = 1*HEXDIG chunk-ext CRLF 15680 chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 15681 chunk-ext-name = token 15682 chunk-ext-val = token / quoted-string 15683``` 15684The chunk extension is optional. After the header and chunk body have been serialized, it is the callers responsibility to also serialize the final CRLF (`"\r\n"`). 15685This class allows the caller to emit piecewise chunk bodies, by first serializing the chunk header using this class and then serializing the chunk body in a series of one or more calls to a stream write operation. 15686To use this class, pass an instance of it to a stream algorithm as the buffer sequence: 15687``` 15688 // writes "400;x\r\n" 15689 net::write(stream, chunk_header{1024, "x"}); 15690``` 15691[heading See Also] 15692[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15693[section:begin http::chunk_header::begin] 15694[indexterm2 begin..http::chunk_header] 15695Required for ['ConstBufferSequence] 15696[heading Synopsis] 15697``` 15698const_iterator 15699begin() const; 15700``` 15701 15702[heading Description] 15703[endsect] 15704[section:chunk_header http::chunk_header::chunk_header] 15705[indexterm2 chunk_header..http::chunk_header] 15706Constructor. ``` 15707explicit 15708``[link beast.ref.boost__beast__http__chunk_header.chunk_header.overload1 chunk_header]``( 15709 std::size_t size); 15710 ``[''''»''' [link beast.ref.boost__beast__http__chunk_header.chunk_header.overload1 more...]]`` 15711 15712``[link beast.ref.boost__beast__http__chunk_header.chunk_header.overload2 chunk_header]``( 15713 std::size_t size, 15714 string_view extensions); 15715 ``[''''»''' [link beast.ref.boost__beast__http__chunk_header.chunk_header.overload2 more...]]`` 15716 15717template< 15718 class ChunkExtensions> 15719``[link beast.ref.boost__beast__http__chunk_header.chunk_header.overload3 chunk_header]``( 15720 std::size_t size, 15721 ChunkExtensions&& extensions); 15722 ``[''''»''' [link beast.ref.boost__beast__http__chunk_header.chunk_header.overload3 more...]]`` 15723 15724template< 15725 class ChunkExtensions, 15726 class __Allocator__> 15727``[link beast.ref.boost__beast__http__chunk_header.chunk_header.overload4 chunk_header]``( 15728 std::size_t size, 15729 ChunkExtensions&& extensions, 15730 Allocator const& allocator); 15731 ``[''''»''' [link beast.ref.boost__beast__http__chunk_header.chunk_header.overload4 more...]]`` 15732 15733``` 15734Required for ['ConstBufferSequence] ``` 15735``[link beast.ref.boost__beast__http__chunk_header.chunk_header.overload5 chunk_header]``( 15736 chunk_header const&); 15737 ``[''''»''' [link beast.ref.boost__beast__http__chunk_header.chunk_header.overload5 more...]]`` 15738``` 15739[section:overload1 http::chunk_header::chunk_header (1 of 5 overloads)] 15740Constructor. 15741[heading Synopsis] 15742``` 15743chunk_header( 15744 std::size_t size); 15745``` 15746 15747[heading Description] 15748This constructs a buffer sequence representing a ['chunked-body] size and terminating CRLF (`"\r\n"`) with no chunk extensions. 15749[heading Parameters] 15750[table [[Name][Description]] 15751 [[`size`][ 15752 15753The size of the chunk body that follows. The value must be greater than zero. 15754 ]] 15755] 15756[heading See Also] 15757[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15758[endsect] 15759[section:overload2 http::chunk_header::chunk_header (2 of 5 overloads)] 15760Constructor. 15761[heading Synopsis] 15762``` 15763chunk_header( 15764 std::size_t size, 15765 string_view extensions); 15766``` 15767 15768[heading Description] 15769This constructs a buffer sequence representing a ['chunked-body] size and terminating CRLF (`"\r\n"`) with provided chunk extensions. 15770[heading Parameters] 15771[table [[Name][Description]] 15772 [[`size`][ 15773 15774The size of the chunk body that follows. The value must be greater than zero. 15775 ]] 15776 [[`extensions`][ 15777 15778The chunk extensions string. This string must be formatted correctly as per rfc7230, using this BNF syntax: 15779``` 15780 chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) 15781 chunk-ext-name = token 15782 chunk-ext-val = token / quoted-string 15783``` 15784The data pointed to by this string view must remain valid for the lifetime of any operations performed on the object. 15785 ]] 15786] 15787[heading See Also] 15788[@https://tools.ietf.org/html/rfc7230#section-4.1.1 https://tools.ietf.org/html/rfc7230#section-4.1.1] 15789[endsect] 15790[section:overload3 http::chunk_header::chunk_header (3 of 5 overloads)] 15791Constructor. 15792[heading Synopsis] 15793``` 15794template< 15795 class ChunkExtensions> 15796chunk_header( 15797 std::size_t size, 15798 ChunkExtensions&& extensions); 15799``` 15800 15801[heading Description] 15802This constructs a buffer sequence representing a ['chunked-body] size and terminating CRLF (`"\r\n"`) with provided chunk extensions. The default allocator is used to provide storage for the extensions object. 15803[heading Parameters] 15804[table [[Name][Description]] 15805 [[`size`][ 15806 15807The size of the chunk body that follows. The value must be greater than zero. 15808 ]] 15809 [[`extensions`][ 15810 15811The chunk extensions object. The expression `extensions.str()` must be valid, and the return type must be convertible to [link beast.ref.boost__beast__string_view `string_view`]. This object will be copied or moved as needed to ensure that the chunk header object retains ownership of the buffers provided by the chunk extensions object. 15812 ]] 15813] 15814[heading Remarks] 15815This function participates in overload resolution only if [*ChunkExtensions] meets the requirements stated above. 15816[heading See Also] 15817[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15818[endsect] 15819[section:overload4 http::chunk_header::chunk_header (4 of 5 overloads)] 15820Constructor. 15821[heading Synopsis] 15822``` 15823template< 15824 class ChunkExtensions, 15825 class __Allocator__> 15826chunk_header( 15827 std::size_t size, 15828 ChunkExtensions&& extensions, 15829 Allocator const& allocator); 15830``` 15831 15832[heading Description] 15833This constructs a buffer sequence representing a ['chunked-body] size and terminating CRLF (`"\r\n"`) with provided chunk extensions. The specified allocator is used to provide storage for the extensions object. 15834[heading Parameters] 15835[table [[Name][Description]] 15836 [[`size`][ 15837 15838The size of the chunk body that follows. The value be greater than zero. 15839 ]] 15840 [[`extensions`][ 15841 15842The chunk extensions object. The expression `extensions.str()` must be valid, and the return type must be convertible to [link beast.ref.boost__beast__string_view `string_view`]. This object will be copied or moved as needed to ensure that the chunk header object retains ownership of the buffers provided by the chunk extensions object. 15843 ]] 15844 [[`allocator`][ 15845 15846The allocator to provide storage for the moved or copied extensions object. 15847 ]] 15848] 15849[heading Remarks] 15850This function participates in overload resolution only if [*ChunkExtensions] meets the requirements stated above. 15851[heading See Also] 15852[@https://tools.ietf.org/html/rfc7230#section-4.1 https://tools.ietf.org/html/rfc7230#section-4.1] 15853[endsect] 15854[section:overload5 http::chunk_header::chunk_header (5 of 5 overloads)] 15855Required for ['ConstBufferSequence] 15856[heading Synopsis] 15857``` 15858chunk_header( 15859 chunk_header const&); 15860``` 15861 15862[heading Description] 15863[endsect] 15864[endsect] 15865 15866[section:const_iterator http::chunk_header::const_iterator] 15867[indexterm2 const_iterator..http::chunk_header] 15868Required for ['ConstBufferSequence] 15869[heading Synopsis] 15870 15871``` 15872using const_iterator = ``['implementation-defined]``; 15873``` 15874 15875[heading Description] 15876[endsect] 15877[section:end http::chunk_header::end] 15878[indexterm2 end..http::chunk_header] 15879Required for ['ConstBufferSequence] 15880[heading Synopsis] 15881``` 15882const_iterator 15883end() const; 15884``` 15885 15886[heading Description] 15887[endsect] 15888[section:value_type http::chunk_header::value_type] 15889[indexterm2 value_type..http::chunk_header] 15890Required for ['ConstBufferSequence] 15891[heading Synopsis] 15892 15893``` 15894using value_type = ``['implementation-defined]``; 15895``` 15896 15897[heading Description] 15898[endsect] 15899 15900 15901 15902Convenience header [include_file boost/beast/http.hpp] 15903 15904[endsect] 15905 15906 15907 15908[section:boost__beast__http__chunk_last http::chunk_last] 15909A chunked-encoding last chunk. 15910[heading Synopsis] 15911 15912Defined in header [include_file boost/beast/http/chunk_encode.hpp] 15913 15914 15915 15916``` 15917template< 15918 class Trailer = chunk_crlf> 15919class chunk_last 15920``` 15921[heading Types] 15922[table [[Name][Description]] 15923 [ 15924 [[link beast.ref.boost__beast__http__chunk_last.const_iterator [*const_iterator]]] 15925 [ 15926 Required for ConstBufferSequence 15927 ] 15928 ] 15929 [ 15930 [[link beast.ref.boost__beast__http__chunk_last.value_type [*value_type]]] 15931 [ 15932 Required for ConstBufferSequence 15933 ] 15934 ] 15935] 15936[heading Member Functions] 15937[table [[Name][Description]] 15938 [ 15939 [[link beast.ref.boost__beast__http__chunk_last.begin [*begin]]] 15940 [ 15941 Required for ConstBufferSequence 15942 ] 15943 ] 15944 [ 15945 [[link beast.ref.boost__beast__http__chunk_last.chunk_last [*chunk_last]]] 15946 [ 15947 Constructor. 15948 15949 Required for ConstBufferSequence 15950 ] 15951 ] 15952 [ 15953 [[link beast.ref.boost__beast__http__chunk_last.end [*end]]] 15954 [ 15955 Required for ConstBufferSequence 15956 ] 15957 ] 15958] 15959 15960[heading Description] 15961[section:begin http::chunk_last::begin] 15962[indexterm2 begin..http::chunk_last] 15963Required for ['ConstBufferSequence] 15964[heading Synopsis] 15965``` 15966const_iterator 15967begin() const; 15968``` 15969 15970[heading Description] 15971[endsect] 15972[section:chunk_last http::chunk_last::chunk_last] 15973[indexterm2 chunk_last..http::chunk_last] 15974Constructor. ``` 15975``[link beast.ref.boost__beast__http__chunk_last.chunk_last.overload1 chunk_last]``(); 15976 ``[''''»''' [link beast.ref.boost__beast__http__chunk_last.chunk_last.overload1 more...]]`` 15977 15978explicit 15979``[link beast.ref.boost__beast__http__chunk_last.chunk_last.overload2 chunk_last]``( 15980 Trailer const& trailer); 15981 ``[''''»''' [link beast.ref.boost__beast__http__chunk_last.chunk_last.overload2 more...]]`` 15982 15983template< 15984 class __Allocator__> 15985``[link beast.ref.boost__beast__http__chunk_last.chunk_last.overload3 chunk_last]``( 15986 Trailer const& trailer, 15987 Allocator const& allocator); 15988 ``[''''»''' [link beast.ref.boost__beast__http__chunk_last.chunk_last.overload3 more...]]`` 15989 15990``` 15991Required for ['ConstBufferSequence] ``` 15992``[link beast.ref.boost__beast__http__chunk_last.chunk_last.overload4 chunk_last]``( 15993 chunk_last const&); 15994 ``[''''»''' [link beast.ref.boost__beast__http__chunk_last.chunk_last.overload4 more...]]`` 15995``` 15996[section:overload1 http::chunk_last::chunk_last (1 of 4 overloads)] 15997Constructor. 15998[heading Synopsis] 15999``` 16000chunk_last(); 16001``` 16002 16003[heading Description] 16004The last chunk will have an empty trailer [endsect] 16005[section:overload2 http::chunk_last::chunk_last (2 of 4 overloads)] 16006Constructor. 16007[heading Synopsis] 16008``` 16009chunk_last( 16010 Trailer const& trailer); 16011``` 16012 16013[heading Description] 16014[heading Parameters] 16015[table [[Name][Description]] 16016 [[`trailer`][ 16017 16018The trailer to use. This may be a type meeting the requirements of either Fields or ConstBufferSequence. If it is a ConstBufferSequence, the trailer must be formatted correctly as per rfc7230 including a CRLF on its own line to denote the end of the trailer. 16019 ]] 16020] 16021[endsect] 16022[section:overload3 http::chunk_last::chunk_last (3 of 4 overloads)] 16023Constructor. 16024[heading Synopsis] 16025``` 16026template< 16027 class __Allocator__> 16028chunk_last( 16029 Trailer const& trailer, 16030 Allocator const& allocator); 16031``` 16032 16033[heading Description] 16034[heading Parameters] 16035[table [[Name][Description]] 16036 [[`trailer`][ 16037 16038The trailer to use. This type must meet the requirements of Fields. 16039 ]] 16040 [[`allocator`][ 16041 16042The allocator to use for storing temporary data associated with the serialized trailer buffers. 16043 ]] 16044] 16045[endsect] 16046[section:overload4 http::chunk_last::chunk_last (4 of 4 overloads)] 16047Required for ['ConstBufferSequence] 16048[heading Synopsis] 16049``` 16050chunk_last( 16051 chunk_last const&); 16052``` 16053 16054[heading Description] 16055[endsect] 16056[endsect] 16057 16058[section:const_iterator http::chunk_last::const_iterator] 16059[indexterm2 const_iterator..http::chunk_last] 16060Required for ['ConstBufferSequence] 16061[heading Synopsis] 16062 16063``` 16064using const_iterator = ``['implementation-defined]``; 16065``` 16066 16067[heading Description] 16068[endsect] 16069[section:end http::chunk_last::end] 16070[indexterm2 end..http::chunk_last] 16071Required for ['ConstBufferSequence] 16072[heading Synopsis] 16073``` 16074const_iterator 16075end() const; 16076``` 16077 16078[heading Description] 16079[endsect] 16080[section:value_type http::chunk_last::value_type] 16081[indexterm2 value_type..http::chunk_last] 16082Required for ['ConstBufferSequence] 16083[heading Synopsis] 16084 16085``` 16086using value_type = ``['implementation-defined]``; 16087``` 16088 16089[heading Description] 16090[endsect] 16091 16092 16093 16094Convenience header [include_file boost/beast/http.hpp] 16095 16096[endsect] 16097 16098 16099 16100[section:boost__beast__http__dynamic_body http::dynamic_body] 16101[indexterm1 http::dynamic_body] 16102A dynamic message body represented by a [link beast.ref.boost__beast__multi_buffer `multi_buffer`]. 16103[heading Synopsis] 16104 16105Defined in header [include_file boost/beast/http/dynamic_body.hpp] 16106 16107 16108 16109``` 16110using dynamic_body = basic_dynamic_body< multi_buffer >; 16111``` 16112[heading Types] 16113[table [[Name][Description]] 16114 [ 16115 [[link beast.ref.boost__beast__http__basic_dynamic_body.reader [*reader]]] 16116 [ 16117 The algorithm for parsing the body. 16118 ] 16119 ] 16120 [ 16121 [[link beast.ref.boost__beast__http__basic_dynamic_body.value_type [*value_type]]] 16122 [ 16123 The type of container used for the body. 16124 ] 16125 ] 16126 [ 16127 [[link beast.ref.boost__beast__http__basic_dynamic_body.writer [*writer]]] 16128 [ 16129 The algorithm for serializing the body. 16130 ] 16131 ] 16132] 16133[heading Member Functions] 16134[table [[Name][Description]] 16135 [ 16136 [[link beast.ref.boost__beast__http__basic_dynamic_body.size [*size]]] 16137 [ 16138 Returns the payload size of the body. 16139 ] 16140 ] 16141] 16142This body uses a ['DynamicBuffer] as a memory-based container for holding message payloads. Messages using this body type may be serialized and parsed. 16143[heading Description] 16144Meets the requirements of ['Body]. 16145 16146 16147Convenience header [include_file boost/beast/http.hpp] 16148 16149[endsect] 16150[section:boost__beast__http__empty_body http::empty_body] 16151An empty ['Body] 16152[heading Synopsis] 16153 16154Defined in header [include_file boost/beast/http/empty_body.hpp] 16155 16156 16157 16158``` 16159struct empty_body 16160``` 16161[heading Types] 16162[table [[Name][Description]] 16163 [ 16164 [[link beast.ref.boost__beast__http__empty_body__value_type [*value_type]]] 16165 [ 16166 The type of container used for the body. 16167 ] 16168 ] 16169 [ 16170 [[link beast.ref.boost__beast__http__empty_body.reader [*reader]]] 16171 [ 16172 The algorithm for parsing the body. 16173 ] 16174 ] 16175 [ 16176 [[link beast.ref.boost__beast__http__empty_body.writer [*writer]]] 16177 [ 16178 The algorithm for serializing the body. 16179 ] 16180 ] 16181] 16182[heading Member Functions] 16183[table [[Name][Description]] 16184 [ 16185 [[link beast.ref.boost__beast__http__empty_body.size [*size]]] 16186 [ 16187 Returns the payload size of the body. 16188 ] 16189 ] 16190] 16191 16192[heading Description] 16193This body is used to represent messages which do not have a message body. If this body is used with a parser, and the parser encounters octets corresponding to a message body, the parser will fail with the error [link beast.ref.boost__beast__http__error `http::unexpected_body`]. 16194The Content-Length of this body is always 0. [section:reader http::empty_body::reader] 16195[indexterm2 reader..http::empty_body] 16196The algorithm for parsing the body. 16197[heading Synopsis] 16198 16199``` 16200using reader = ``['implementation-defined]``; 16201``` 16202 16203[heading Description] 16204Meets the requirements of ['BodyReader]. [endsect] 16205[section:size http::empty_body::size] 16206[indexterm2 size..http::empty_body] 16207Returns the payload size of the body. 16208[heading Synopsis] 16209``` 16210static 16211std::uint64_t 16212size( 16213 value_type); 16214``` 16215 16216[heading Description] 16217When this body is used with [link beast.ref.boost__beast__http__message.prepare_payload `http::message::prepare_payload`], the Content-Length will be set to the payload size, and any chunked Transfer-Encoding will be removed. [endsect] 16218[section:writer http::empty_body::writer] 16219[indexterm2 writer..http::empty_body] 16220The algorithm for serializing the body. 16221[heading Synopsis] 16222 16223``` 16224using writer = ``['implementation-defined]``; 16225``` 16226 16227[heading Description] 16228Meets the requirements of ['BodyWriter]. [endsect] 16229 16230 16231 16232Convenience header [include_file boost/beast/http.hpp] 16233 16234[endsect] 16235 16236 16237 16238[section:boost__beast__http__empty_body__value_type http::empty_body::value_type] 16239The type of container used for the body. 16240[heading Synopsis] 16241 16242Defined in header [include_file boost/beast/http/empty_body.hpp] 16243 16244 16245 16246``` 16247struct value_type 16248``` 16249 16250[heading Description] 16251This determines the type of [link beast.ref.boost__beast__http__message.body `http::message::body`] when this body type is used with a message container. 16252 16253 16254Convenience header [include_file boost/beast/http.hpp] 16255 16256[endsect] 16257 16258 16259 16260[section:boost__beast__http__error http::error] 16261[indexterm1 http::error] 16262Error codes returned from HTTP algorithms and operations. 16263[heading Synopsis] 16264 16265Defined in header [include_file boost/beast/http/error.hpp] 16266 16267 16268``` 16269enum error 16270``` 16271 16272[indexterm2 end_of_stream..http::error] 16273[indexterm2 partial_message..http::error] 16274[indexterm2 need_more..http::error] 16275[indexterm2 unexpected_body..http::error] 16276[indexterm2 need_buffer..http::error] 16277[indexterm2 end_of_chunk..http::error] 16278[indexterm2 buffer_overflow..http::error] 16279[indexterm2 header_limit..http::error] 16280[indexterm2 body_limit..http::error] 16281[indexterm2 bad_alloc..http::error] 16282[indexterm2 bad_line_ending..http::error] 16283[indexterm2 bad_method..http::error] 16284[indexterm2 bad_target..http::error] 16285[indexterm2 bad_version..http::error] 16286[indexterm2 bad_status..http::error] 16287[indexterm2 bad_reason..http::error] 16288[indexterm2 bad_field..http::error] 16289[indexterm2 bad_value..http::error] 16290[indexterm2 bad_content_length..http::error] 16291[indexterm2 bad_transfer_encoding..http::error] 16292[indexterm2 bad_chunk..http::error] 16293[indexterm2 bad_chunk_extension..http::error] 16294[indexterm2 bad_obs_fold..http::error] 16295[indexterm2 stale_parser..http::error] 16296[heading Values] 16297[table [[Name][Description]] 16298 [[[^end_of_stream]][The end of the stream was reached. 16299 16300This error is returned when attempting to read HTTP data, 16301and the stream returns the error `net::error::eof` 16302before any octets corresponding to a new HTTP message have 16303been received. 16304 ]] 16305 [[[^partial_message]][The incoming message is incomplete. 16306 16307This happens when the end of stream is reached during 16308parsing and some octets have been received, but not the 16309entire message. 16310 ]] 16311 [[[^need_more]][Additional buffers are required. 16312 16313This error is returned during parsing when additional 16314octets are needed. The caller should append more data 16315to the existing buffer and retry the parse operaetion. 16316 ]] 16317 [[[^unexpected_body]][An unexpected body was encountered during parsing. 16318 16319This error is returned when attempting to parse body 16320octets into a message container which has the 16321@ref empty_body body type. 16322 16323@see empty_body 16324 ]] 16325 [[[^need_buffer]][Additional buffers are required. 16326 16327This error is returned under the following conditions: 16328 16329@li During serialization when using @ref buffer_body. 16330The caller should update the body to point to a new 16331buffer or indicate that there are no more octets in 16332the body. 16333 16334@li During parsing when using @ref buffer_body. 16335The caller should update the body to point to a new 16336storage area to receive additional body octets. 16337 ]] 16338 [[[^end_of_chunk]][The end of a chunk was reached. 16339 16340]] 16341 [[[^buffer_overflow]][Buffer maximum exceeded. 16342 16343This error is returned when reading HTTP content 16344into a dynamic buffer, and the operation would 16345exceed the maximum size of the buffer. 16346 ]] 16347 [[[^header_limit]][Header limit exceeded. 16348 16349The parser detected an incoming message header which 16350exceeded a configured limit. 16351 ]] 16352 [[[^body_limit]][Body limit exceeded. 16353 16354The parser detected an incoming message body which 16355exceeded a configured limit. 16356 ]] 16357 [[[^bad_alloc]][A memory allocation failed. 16358 16359When basic_fields throws std::bad_alloc, it is 16360converted into this error by @ref parser. 16361 ]] 16362 [[[^bad_line_ending]][The line ending was malformed. 16363 16364]] 16365 [[[^bad_method]][The method is invalid. 16366 16367]] 16368 [[[^bad_target]][The request-target is invalid. 16369 16370]] 16371 [[[^bad_version]][The HTTP-version is invalid. 16372 16373]] 16374 [[[^bad_status]][The status-code is invalid. 16375 16376]] 16377 [[[^bad_reason]][The reason-phrase is invalid. 16378 16379]] 16380 [[[^bad_field]][The field name is invalid. 16381 16382]] 16383 [[[^bad_value]][The field value is invalid. 16384 16385]] 16386 [[[^bad_content_length]][The Content-Length is invalid. 16387 16388]] 16389 [[[^bad_transfer_encoding]][The Transfer-Encoding is invalid. 16390 16391]] 16392 [[[^bad_chunk]][The chunk syntax is invalid. 16393 16394]] 16395 [[[^bad_chunk_extension]][The chunk extension is invalid. 16396 16397]] 16398 [[[^bad_obs_fold]][An obs-fold exceeded an internal limit. 16399 16400]] 16401 [[[^stale_parser]][The parser is stale. 16402 16403This happens when attempting to re-use a parser that has 16404already completed parsing a message. Programs must construct 16405a new parser for each message. This can be easily done by 16406storing the parser in an boost or std::optional container. 16407 ]] 16408] 16409 16410[heading Description] 16411 16412 16413 16414Convenience header [include_file boost/beast/http.hpp] 16415 16416[endsect] 16417[section:boost__beast__http__ext_list http::ext_list] 16418A list of extensions in a comma separated HTTP field value. 16419[heading Synopsis] 16420 16421Defined in header [include_file boost/beast/http/rfc7230.hpp] 16422 16423 16424 16425``` 16426class ext_list 16427``` 16428[heading Types] 16429[table [[Name][Description]] 16430 [ 16431 [[link beast.ref.boost__beast__http__ext_list.const_iterator [*const_iterator]]] 16432 [ 16433 A constant iterator to the list. 16434 ] 16435 ] 16436 [ 16437 [[link beast.ref.boost__beast__http__ext_list.value_type [*value_type]]] 16438 [ 16439 The type of each element in the list. 16440 ] 16441 ] 16442] 16443[heading Member Functions] 16444[table [[Name][Description]] 16445 [ 16446 [[link beast.ref.boost__beast__http__ext_list.begin [*begin]]] 16447 [ 16448 Return a const iterator to the beginning of the list. 16449 ] 16450 ] 16451 [ 16452 [[link beast.ref.boost__beast__http__ext_list.cbegin [*cbegin]]] 16453 [ 16454 Return a const iterator to the beginning of the list. 16455 ] 16456 ] 16457 [ 16458 [[link beast.ref.boost__beast__http__ext_list.cend [*cend]]] 16459 [ 16460 Return a const iterator to the end of the list. 16461 ] 16462 ] 16463 [ 16464 [[link beast.ref.boost__beast__http__ext_list.end [*end]]] 16465 [ 16466 Return a const iterator to the end of the list. 16467 ] 16468 ] 16469 [ 16470 [[link beast.ref.boost__beast__http__ext_list.exists [*exists]]] 16471 [ 16472 Return true if a token is present in the list. 16473 ] 16474 ] 16475 [ 16476 [[link beast.ref.boost__beast__http__ext_list.ext_list [*ext_list]]] 16477 [ 16478 Construct a list. 16479 ] 16480 ] 16481 [ 16482 [[link beast.ref.boost__beast__http__ext_list.find [*find]]] 16483 [ 16484 Find a token in the list. 16485 ] 16486 ] 16487] 16488 16489[heading Description] 16490This container allows iteration of the extensions in an HTTP field value. The extension list is a comma separated list of token parameter list pairs. 16491If a parsing error is encountered while iterating the string, the behavior of the container will be as if a string containing only characters up to but excluding the first invalid character was used to construct the list. 16492[heading BNF] 16493 16494``` 16495 ext-list = *( "," OWS ) ext *( OWS "," [ OWS ext ] ) 16496 ext = token param-list 16497 param-list = *( OWS ";" OWS param ) 16498 param = token OWS [ "=" OWS ( token / quoted-string ) ] 16499``` 16500To use this class, construct with the string to be parsed and then use [link beast.ref.boost__beast__http__ext_list.begin `http::ext_list::begin`] and [link beast.ref.boost__beast__http__ext_list.end `http::ext_list::end`], or range-for to iterate each item: 16501[heading Example] 16502 16503``` 16504 for(auto const& ext : ext_list{"none, 7z;level=9, zip;no_context_takeover;bits=15"}) 16505 { 16506 std::cout << ext.first << "\n"; 16507 for(auto const& param : ext.second) 16508 { 16509 std::cout << ";" << param.first; 16510 if(! param.second.empty()) 16511 std::cout << "=" << param.second; 16512 std::cout << "\n"; 16513 } 16514 } 16515``` 16516[section:begin http::ext_list::begin] 16517[indexterm2 begin..http::ext_list] 16518Return a const iterator to the beginning of the list. 16519[heading Synopsis] 16520``` 16521const_iterator 16522begin() const; 16523``` 16524 16525[heading Description] 16526[endsect] 16527[section:cbegin http::ext_list::cbegin] 16528[indexterm2 cbegin..http::ext_list] 16529Return a const iterator to the beginning of the list. 16530[heading Synopsis] 16531``` 16532const_iterator 16533cbegin() const; 16534``` 16535 16536[heading Description] 16537[endsect] 16538[section:cend http::ext_list::cend] 16539[indexterm2 cend..http::ext_list] 16540Return a const iterator to the end of the list. 16541[heading Synopsis] 16542``` 16543const_iterator 16544cend() const; 16545``` 16546 16547[heading Description] 16548[endsect] 16549[section:const_iterator http::ext_list::const_iterator] 16550[indexterm2 const_iterator..http::ext_list] 16551A constant iterator to the list. 16552[heading Synopsis] 16553 16554``` 16555using const_iterator = ``['implementation-defined]``; 16556``` 16557 16558[heading Description] 16559[endsect] 16560[section:end http::ext_list::end] 16561[indexterm2 end..http::ext_list] 16562Return a const iterator to the end of the list. 16563[heading Synopsis] 16564``` 16565const_iterator 16566end() const; 16567``` 16568 16569[heading Description] 16570[endsect] 16571[section:exists http::ext_list::exists] 16572[indexterm2 exists..http::ext_list] 16573Return `true` if a token is present in the list. 16574[heading Synopsis] 16575``` 16576bool 16577exists( 16578 string_view const& s); 16579``` 16580 16581[heading Description] 16582[heading Parameters] 16583[table [[Name][Description]] 16584 [[`s`][ 16585 16586The token to find. A case-insensitive comparison is used. 16587 ]] 16588] 16589[endsect] 16590[section:ext_list http::ext_list::ext_list] 16591[indexterm2 ext_list..http::ext_list] 16592Construct a list. 16593[heading Synopsis] 16594``` 16595ext_list( 16596 string_view s); 16597``` 16598 16599[heading Description] 16600[heading Parameters] 16601[table [[Name][Description]] 16602 [[`s`][ 16603 16604A string containing the list contents. The string must remain valid for the lifetime of the container. 16605 ]] 16606] 16607[endsect] 16608[section:find http::ext_list::find] 16609[indexterm2 find..http::ext_list] 16610Find a token in the list. 16611[heading Synopsis] 16612``` 16613const_iterator 16614find( 16615 string_view const& s); 16616``` 16617 16618[heading Description] 16619[heading Parameters] 16620[table [[Name][Description]] 16621 [[`s`][ 16622 16623The token to find. A case-insensitive comparison is used. 16624 ]] 16625] 16626[heading Return Value] 16627An iterator to the matching token, or `end()` if no token exists. 16628[endsect] 16629[section:value_type http::ext_list::value_type] 16630[indexterm2 value_type..http::ext_list] 16631The type of each element in the list. 16632[heading Synopsis] 16633 16634``` 16635using value_type = std::pair< string_view, param_list >; 16636``` 16637 16638[heading Description] 16639The first element of the pair is the extension token, and the second element of the pair is an iterable container holding the extension's name/value parameters. [endsect] 16640 16641 16642 16643Convenience header [include_file boost/beast/http.hpp] 16644 16645[endsect] 16646 16647 16648 16649[section:boost__beast__http__field http::field] 16650[indexterm1 http::field] 16651 16652[heading Synopsis] 16653 16654Defined in header [include_file boost/beast/http/field.hpp] 16655 16656 16657``` 16658enum field 16659``` 16660 16661[indexterm2 unknown..http::field] 16662[indexterm2 a_im..http::field] 16663[indexterm2 accept..http::field] 16664[indexterm2 accept_additions..http::field] 16665[indexterm2 accept_charset..http::field] 16666[indexterm2 accept_datetime..http::field] 16667[indexterm2 accept_encoding..http::field] 16668[indexterm2 accept_features..http::field] 16669[indexterm2 accept_language..http::field] 16670[indexterm2 accept_patch..http::field] 16671[indexterm2 accept_post..http::field] 16672[indexterm2 accept_ranges..http::field] 16673[indexterm2 access_control..http::field] 16674[indexterm2 access_control_allow_credentials..http::field] 16675[indexterm2 access_control_allow_headers..http::field] 16676[indexterm2 access_control_allow_methods..http::field] 16677[indexterm2 access_control_allow_origin..http::field] 16678[indexterm2 access_control_expose_headers..http::field] 16679[indexterm2 access_control_max_age..http::field] 16680[indexterm2 access_control_request_headers..http::field] 16681[indexterm2 access_control_request_method..http::field] 16682[indexterm2 age..http::field] 16683[indexterm2 allow..http::field] 16684[indexterm2 alpn..http::field] 16685[indexterm2 also_control..http::field] 16686[indexterm2 alt_svc..http::field] 16687[indexterm2 alt_used..http::field] 16688[indexterm2 alternate_recipient..http::field] 16689[indexterm2 alternates..http::field] 16690[indexterm2 apparently_to..http::field] 16691[indexterm2 apply_to_redirect_ref..http::field] 16692[indexterm2 approved..http::field] 16693[indexterm2 archive..http::field] 16694[indexterm2 archived_at..http::field] 16695[indexterm2 article_names..http::field] 16696[indexterm2 article_updates..http::field] 16697[indexterm2 authentication_control..http::field] 16698[indexterm2 authentication_info..http::field] 16699[indexterm2 authentication_results..http::field] 16700[indexterm2 authorization..http::field] 16701[indexterm2 auto_submitted..http::field] 16702[indexterm2 autoforwarded..http::field] 16703[indexterm2 autosubmitted..http::field] 16704[indexterm2 base..http::field] 16705[indexterm2 bcc..http::field] 16706[indexterm2 body..http::field] 16707[indexterm2 c_ext..http::field] 16708[indexterm2 c_man..http::field] 16709[indexterm2 c_opt..http::field] 16710[indexterm2 c_pep..http::field] 16711[indexterm2 c_pep_info..http::field] 16712[indexterm2 cache_control..http::field] 16713[indexterm2 caldav_timezones..http::field] 16714[indexterm2 cancel_key..http::field] 16715[indexterm2 cancel_lock..http::field] 16716[indexterm2 cc..http::field] 16717[indexterm2 close..http::field] 16718[indexterm2 comments..http::field] 16719[indexterm2 compliance..http::field] 16720[indexterm2 connection..http::field] 16721[indexterm2 content_alternative..http::field] 16722[indexterm2 content_base..http::field] 16723[indexterm2 content_description..http::field] 16724[indexterm2 content_disposition..http::field] 16725[indexterm2 content_duration..http::field] 16726[indexterm2 content_encoding..http::field] 16727[indexterm2 content_features..http::field] 16728[indexterm2 content_id..http::field] 16729[indexterm2 content_identifier..http::field] 16730[indexterm2 content_language..http::field] 16731[indexterm2 content_length..http::field] 16732[indexterm2 content_location..http::field] 16733[indexterm2 content_md5..http::field] 16734[indexterm2 content_range..http::field] 16735[indexterm2 content_return..http::field] 16736[indexterm2 content_script_type..http::field] 16737[indexterm2 content_style_type..http::field] 16738[indexterm2 content_transfer_encoding..http::field] 16739[indexterm2 content_type..http::field] 16740[indexterm2 content_version..http::field] 16741[indexterm2 control..http::field] 16742[indexterm2 conversion..http::field] 16743[indexterm2 conversion_with_loss..http::field] 16744[indexterm2 cookie..http::field] 16745[indexterm2 cookie2..http::field] 16746[indexterm2 cost..http::field] 16747[indexterm2 dasl..http::field] 16748[indexterm2 date..http::field] 16749[indexterm2 date_received..http::field] 16750[indexterm2 dav..http::field] 16751[indexterm2 default_style..http::field] 16752[indexterm2 deferred_delivery..http::field] 16753[indexterm2 delivery_date..http::field] 16754[indexterm2 delta_base..http::field] 16755[indexterm2 depth..http::field] 16756[indexterm2 derived_from..http::field] 16757[indexterm2 destination..http::field] 16758[indexterm2 differential_id..http::field] 16759[indexterm2 digest..http::field] 16760[indexterm2 discarded_x400_ipms_extensions..http::field] 16761[indexterm2 discarded_x400_mts_extensions..http::field] 16762[indexterm2 disclose_recipients..http::field] 16763[indexterm2 disposition_notification_options..http::field] 16764[indexterm2 disposition_notification_to..http::field] 16765[indexterm2 distribution..http::field] 16766[indexterm2 dkim_signature..http::field] 16767[indexterm2 dl_expansion_history..http::field] 16768[indexterm2 downgraded_bcc..http::field] 16769[indexterm2 downgraded_cc..http::field] 16770[indexterm2 downgraded_disposition_notification_to..http::field] 16771[indexterm2 downgraded_final_recipient..http::field] 16772[indexterm2 downgraded_from..http::field] 16773[indexterm2 downgraded_in_reply_to..http::field] 16774[indexterm2 downgraded_mail_from..http::field] 16775[indexterm2 downgraded_message_id..http::field] 16776[indexterm2 downgraded_original_recipient..http::field] 16777[indexterm2 downgraded_rcpt_to..http::field] 16778[indexterm2 downgraded_references..http::field] 16779[indexterm2 downgraded_reply_to..http::field] 16780[indexterm2 downgraded_resent_bcc..http::field] 16781[indexterm2 downgraded_resent_cc..http::field] 16782[indexterm2 downgraded_resent_from..http::field] 16783[indexterm2 downgraded_resent_reply_to..http::field] 16784[indexterm2 downgraded_resent_sender..http::field] 16785[indexterm2 downgraded_resent_to..http::field] 16786[indexterm2 downgraded_return_path..http::field] 16787[indexterm2 downgraded_sender..http::field] 16788[indexterm2 downgraded_to..http::field] 16789[indexterm2 ediint_features..http::field] 16790[indexterm2 eesst_version..http::field] 16791[indexterm2 encoding..http::field] 16792[indexterm2 encrypted..http::field] 16793[indexterm2 errors_to..http::field] 16794[indexterm2 etag..http::field] 16795[indexterm2 expect..http::field] 16796[indexterm2 expires..http::field] 16797[indexterm2 expiry_date..http::field] 16798[indexterm2 ext..http::field] 16799[indexterm2 followup_to..http::field] 16800[indexterm2 forwarded..http::field] 16801[indexterm2 from..http::field] 16802[indexterm2 generate_delivery_report..http::field] 16803[indexterm2 getprofile..http::field] 16804[indexterm2 hobareg..http::field] 16805[indexterm2 host..http::field] 16806[indexterm2 http2_settings..http::field] 16807[indexterm2 if_..http::field] 16808[indexterm2 if_match..http::field] 16809[indexterm2 if_modified_since..http::field] 16810[indexterm2 if_none_match..http::field] 16811[indexterm2 if_range..http::field] 16812[indexterm2 if_schedule_tag_match..http::field] 16813[indexterm2 if_unmodified_since..http::field] 16814[indexterm2 im..http::field] 16815[indexterm2 importance..http::field] 16816[indexterm2 in_reply_to..http::field] 16817[indexterm2 incomplete_copy..http::field] 16818[indexterm2 injection_date..http::field] 16819[indexterm2 injection_info..http::field] 16820[indexterm2 jabber_id..http::field] 16821[indexterm2 keep_alive..http::field] 16822[indexterm2 keywords..http::field] 16823[indexterm2 label..http::field] 16824[indexterm2 language..http::field] 16825[indexterm2 last_modified..http::field] 16826[indexterm2 latest_delivery_time..http::field] 16827[indexterm2 lines..http::field] 16828[indexterm2 link..http::field] 16829[indexterm2 list_archive..http::field] 16830[indexterm2 list_help..http::field] 16831[indexterm2 list_id..http::field] 16832[indexterm2 list_owner..http::field] 16833[indexterm2 list_post..http::field] 16834[indexterm2 list_subscribe..http::field] 16835[indexterm2 list_unsubscribe..http::field] 16836[indexterm2 list_unsubscribe_post..http::field] 16837[indexterm2 location..http::field] 16838[indexterm2 lock_token..http::field] 16839[indexterm2 man..http::field] 16840[indexterm2 max_forwards..http::field] 16841[indexterm2 memento_datetime..http::field] 16842[indexterm2 message_context..http::field] 16843[indexterm2 message_id..http::field] 16844[indexterm2 message_type..http::field] 16845[indexterm2 meter..http::field] 16846[indexterm2 method_check..http::field] 16847[indexterm2 method_check_expires..http::field] 16848[indexterm2 mime_version..http::field] 16849[indexterm2 mmhs_acp127_message_identifier..http::field] 16850[indexterm2 mmhs_authorizing_users..http::field] 16851[indexterm2 mmhs_codress_message_indicator..http::field] 16852[indexterm2 mmhs_copy_precedence..http::field] 16853[indexterm2 mmhs_exempted_address..http::field] 16854[indexterm2 mmhs_extended_authorisation_info..http::field] 16855[indexterm2 mmhs_handling_instructions..http::field] 16856[indexterm2 mmhs_message_instructions..http::field] 16857[indexterm2 mmhs_message_type..http::field] 16858[indexterm2 mmhs_originator_plad..http::field] 16859[indexterm2 mmhs_originator_reference..http::field] 16860[indexterm2 mmhs_other_recipients_indicator_cc..http::field] 16861[indexterm2 mmhs_other_recipients_indicator_to..http::field] 16862[indexterm2 mmhs_primary_precedence..http::field] 16863[indexterm2 mmhs_subject_indicator_codes..http::field] 16864[indexterm2 mt_priority..http::field] 16865[indexterm2 negotiate..http::field] 16866[indexterm2 newsgroups..http::field] 16867[indexterm2 nntp_posting_date..http::field] 16868[indexterm2 nntp_posting_host..http::field] 16869[indexterm2 non_compliance..http::field] 16870[indexterm2 obsoletes..http::field] 16871[indexterm2 opt..http::field] 16872[indexterm2 optional..http::field] 16873[indexterm2 optional_www_authenticate..http::field] 16874[indexterm2 ordering_type..http::field] 16875[indexterm2 organization..http::field] 16876[indexterm2 origin..http::field] 16877[indexterm2 original_encoded_information_types..http::field] 16878[indexterm2 original_from..http::field] 16879[indexterm2 original_message_id..http::field] 16880[indexterm2 original_recipient..http::field] 16881[indexterm2 original_sender..http::field] 16882[indexterm2 original_subject..http::field] 16883[indexterm2 originator_return_address..http::field] 16884[indexterm2 overwrite..http::field] 16885[indexterm2 p3p..http::field] 16886[indexterm2 path..http::field] 16887[indexterm2 pep..http::field] 16888[indexterm2 pep_info..http::field] 16889[indexterm2 pics_label..http::field] 16890[indexterm2 position..http::field] 16891[indexterm2 posting_version..http::field] 16892[indexterm2 pragma..http::field] 16893[indexterm2 prefer..http::field] 16894[indexterm2 preference_applied..http::field] 16895[indexterm2 prevent_nondelivery_report..http::field] 16896[indexterm2 priority..http::field] 16897[indexterm2 privicon..http::field] 16898[indexterm2 profileobject..http::field] 16899[indexterm2 protocol..http::field] 16900[indexterm2 protocol_info..http::field] 16901[indexterm2 protocol_query..http::field] 16902[indexterm2 protocol_request..http::field] 16903[indexterm2 proxy_authenticate..http::field] 16904[indexterm2 proxy_authentication_info..http::field] 16905[indexterm2 proxy_authorization..http::field] 16906[indexterm2 proxy_connection..http::field] 16907[indexterm2 proxy_features..http::field] 16908[indexterm2 proxy_instruction..http::field] 16909[indexterm2 public_..http::field] 16910[indexterm2 public_key_pins..http::field] 16911[indexterm2 public_key_pins_report_only..http::field] 16912[indexterm2 range..http::field] 16913[indexterm2 received..http::field] 16914[indexterm2 received_spf..http::field] 16915[indexterm2 redirect_ref..http::field] 16916[indexterm2 references..http::field] 16917[indexterm2 referer..http::field] 16918[indexterm2 referer_root..http::field] 16919[indexterm2 relay_version..http::field] 16920[indexterm2 reply_by..http::field] 16921[indexterm2 reply_to..http::field] 16922[indexterm2 require_recipient_valid_since..http::field] 16923[indexterm2 resent_bcc..http::field] 16924[indexterm2 resent_cc..http::field] 16925[indexterm2 resent_date..http::field] 16926[indexterm2 resent_from..http::field] 16927[indexterm2 resent_message_id..http::field] 16928[indexterm2 resent_reply_to..http::field] 16929[indexterm2 resent_sender..http::field] 16930[indexterm2 resent_to..http::field] 16931[indexterm2 resolution_hint..http::field] 16932[indexterm2 resolver_location..http::field] 16933[indexterm2 retry_after..http::field] 16934[indexterm2 return_path..http::field] 16935[indexterm2 safe..http::field] 16936[indexterm2 schedule_reply..http::field] 16937[indexterm2 schedule_tag..http::field] 16938[indexterm2 sec_websocket_accept..http::field] 16939[indexterm2 sec_websocket_extensions..http::field] 16940[indexterm2 sec_websocket_key..http::field] 16941[indexterm2 sec_websocket_protocol..http::field] 16942[indexterm2 sec_websocket_version..http::field] 16943[indexterm2 security_scheme..http::field] 16944[indexterm2 see_also..http::field] 16945[indexterm2 sender..http::field] 16946[indexterm2 sensitivity..http::field] 16947[indexterm2 server..http::field] 16948[indexterm2 set_cookie..http::field] 16949[indexterm2 set_cookie2..http::field] 16950[indexterm2 setprofile..http::field] 16951[indexterm2 sio_label..http::field] 16952[indexterm2 sio_label_history..http::field] 16953[indexterm2 slug..http::field] 16954[indexterm2 soapaction..http::field] 16955[indexterm2 solicitation..http::field] 16956[indexterm2 status_uri..http::field] 16957[indexterm2 strict_transport_security..http::field] 16958[indexterm2 subject..http::field] 16959[indexterm2 subok..http::field] 16960[indexterm2 subst..http::field] 16961[indexterm2 summary..http::field] 16962[indexterm2 supersedes..http::field] 16963[indexterm2 surrogate_capability..http::field] 16964[indexterm2 surrogate_control..http::field] 16965[indexterm2 tcn..http::field] 16966[indexterm2 te..http::field] 16967[indexterm2 timeout..http::field] 16968[indexterm2 title..http::field] 16969[indexterm2 to..http::field] 16970[indexterm2 topic..http::field] 16971[indexterm2 trailer..http::field] 16972[indexterm2 transfer_encoding..http::field] 16973[indexterm2 ttl..http::field] 16974[indexterm2 ua_color..http::field] 16975[indexterm2 ua_media..http::field] 16976[indexterm2 ua_pixels..http::field] 16977[indexterm2 ua_resolution..http::field] 16978[indexterm2 ua_windowpixels..http::field] 16979[indexterm2 upgrade..http::field] 16980[indexterm2 urgency..http::field] 16981[indexterm2 uri..http::field] 16982[indexterm2 user_agent..http::field] 16983[indexterm2 variant_vary..http::field] 16984[indexterm2 vary..http::field] 16985[indexterm2 vbr_info..http::field] 16986[indexterm2 version..http::field] 16987[indexterm2 via..http::field] 16988[indexterm2 want_digest..http::field] 16989[indexterm2 warning..http::field] 16990[indexterm2 www_authenticate..http::field] 16991[indexterm2 x_archived_at..http::field] 16992[indexterm2 x_device_accept..http::field] 16993[indexterm2 x_device_accept_charset..http::field] 16994[indexterm2 x_device_accept_encoding..http::field] 16995[indexterm2 x_device_accept_language..http::field] 16996[indexterm2 x_device_user_agent..http::field] 16997[indexterm2 x_frame_options..http::field] 16998[indexterm2 x_mittente..http::field] 16999[indexterm2 x_pgp_sig..http::field] 17000[indexterm2 x_ricevuta..http::field] 17001[indexterm2 x_riferimento_message_id..http::field] 17002[indexterm2 x_tiporicevuta..http::field] 17003[indexterm2 x_trasporto..http::field] 17004[indexterm2 x_verificasicurezza..http::field] 17005[indexterm2 x400_content_identifier..http::field] 17006[indexterm2 x400_content_return..http::field] 17007[indexterm2 x400_content_type..http::field] 17008[indexterm2 x400_mts_identifier..http::field] 17009[indexterm2 x400_originator..http::field] 17010[indexterm2 x400_received..http::field] 17011[indexterm2 x400_recipients..http::field] 17012[indexterm2 x400_trace..http::field] 17013[indexterm2 xref..http::field] 17014[heading Values] 17015[table [[Name][Description]] 17016 [[[^unknown]][ 17017 17018]] 17019 [[[^a_im]][ 17020 17021]] 17022 [[[^accept]][ 17023 17024]] 17025 [[[^accept_additions]][ 17026 17027]] 17028 [[[^accept_charset]][ 17029 17030]] 17031 [[[^accept_datetime]][ 17032 17033]] 17034 [[[^accept_encoding]][ 17035 17036]] 17037 [[[^accept_features]][ 17038 17039]] 17040 [[[^accept_language]][ 17041 17042]] 17043 [[[^accept_patch]][ 17044 17045]] 17046 [[[^accept_post]][ 17047 17048]] 17049 [[[^accept_ranges]][ 17050 17051]] 17052 [[[^access_control]][ 17053 17054]] 17055 [[[^access_control_allow_credentials]][ 17056 17057]] 17058 [[[^access_control_allow_headers]][ 17059 17060]] 17061 [[[^access_control_allow_methods]][ 17062 17063]] 17064 [[[^access_control_allow_origin]][ 17065 17066]] 17067 [[[^access_control_expose_headers]][ 17068 17069]] 17070 [[[^access_control_max_age]][ 17071 17072]] 17073 [[[^access_control_request_headers]][ 17074 17075]] 17076 [[[^access_control_request_method]][ 17077 17078]] 17079 [[[^age]][ 17080 17081]] 17082 [[[^allow]][ 17083 17084]] 17085 [[[^alpn]][ 17086 17087]] 17088 [[[^also_control]][ 17089 17090]] 17091 [[[^alt_svc]][ 17092 17093]] 17094 [[[^alt_used]][ 17095 17096]] 17097 [[[^alternate_recipient]][ 17098 17099]] 17100 [[[^alternates]][ 17101 17102]] 17103 [[[^apparently_to]][ 17104 17105]] 17106 [[[^apply_to_redirect_ref]][ 17107 17108]] 17109 [[[^approved]][ 17110 17111]] 17112 [[[^archive]][ 17113 17114]] 17115 [[[^archived_at]][ 17116 17117]] 17118 [[[^article_names]][ 17119 17120]] 17121 [[[^article_updates]][ 17122 17123]] 17124 [[[^authentication_control]][ 17125 17126]] 17127 [[[^authentication_info]][ 17128 17129]] 17130 [[[^authentication_results]][ 17131 17132]] 17133 [[[^authorization]][ 17134 17135]] 17136 [[[^auto_submitted]][ 17137 17138]] 17139 [[[^autoforwarded]][ 17140 17141]] 17142 [[[^autosubmitted]][ 17143 17144]] 17145 [[[^base]][ 17146 17147]] 17148 [[[^bcc]][ 17149 17150]] 17151 [[[^body]][ 17152 17153]] 17154 [[[^c_ext]][ 17155 17156]] 17157 [[[^c_man]][ 17158 17159]] 17160 [[[^c_opt]][ 17161 17162]] 17163 [[[^c_pep]][ 17164 17165]] 17166 [[[^c_pep_info]][ 17167 17168]] 17169 [[[^cache_control]][ 17170 17171]] 17172 [[[^caldav_timezones]][ 17173 17174]] 17175 [[[^cancel_key]][ 17176 17177]] 17178 [[[^cancel_lock]][ 17179 17180]] 17181 [[[^cc]][ 17182 17183]] 17184 [[[^close]][ 17185 17186]] 17187 [[[^comments]][ 17188 17189]] 17190 [[[^compliance]][ 17191 17192]] 17193 [[[^connection]][ 17194 17195]] 17196 [[[^content_alternative]][ 17197 17198]] 17199 [[[^content_base]][ 17200 17201]] 17202 [[[^content_description]][ 17203 17204]] 17205 [[[^content_disposition]][ 17206 17207]] 17208 [[[^content_duration]][ 17209 17210]] 17211 [[[^content_encoding]][ 17212 17213]] 17214 [[[^content_features]][ 17215 17216]] 17217 [[[^content_id]][ 17218 17219]] 17220 [[[^content_identifier]][ 17221 17222]] 17223 [[[^content_language]][ 17224 17225]] 17226 [[[^content_length]][ 17227 17228]] 17229 [[[^content_location]][ 17230 17231]] 17232 [[[^content_md5]][ 17233 17234]] 17235 [[[^content_range]][ 17236 17237]] 17238 [[[^content_return]][ 17239 17240]] 17241 [[[^content_script_type]][ 17242 17243]] 17244 [[[^content_style_type]][ 17245 17246]] 17247 [[[^content_transfer_encoding]][ 17248 17249]] 17250 [[[^content_type]][ 17251 17252]] 17253 [[[^content_version]][ 17254 17255]] 17256 [[[^control]][ 17257 17258]] 17259 [[[^conversion]][ 17260 17261]] 17262 [[[^conversion_with_loss]][ 17263 17264]] 17265 [[[^cookie]][ 17266 17267]] 17268 [[[^cookie2]][ 17269 17270]] 17271 [[[^cost]][ 17272 17273]] 17274 [[[^dasl]][ 17275 17276]] 17277 [[[^date]][ 17278 17279]] 17280 [[[^date_received]][ 17281 17282]] 17283 [[[^dav]][ 17284 17285]] 17286 [[[^default_style]][ 17287 17288]] 17289 [[[^deferred_delivery]][ 17290 17291]] 17292 [[[^delivery_date]][ 17293 17294]] 17295 [[[^delta_base]][ 17296 17297]] 17298 [[[^depth]][ 17299 17300]] 17301 [[[^derived_from]][ 17302 17303]] 17304 [[[^destination]][ 17305 17306]] 17307 [[[^differential_id]][ 17308 17309]] 17310 [[[^digest]][ 17311 17312]] 17313 [[[^discarded_x400_ipms_extensions]][ 17314 17315]] 17316 [[[^discarded_x400_mts_extensions]][ 17317 17318]] 17319 [[[^disclose_recipients]][ 17320 17321]] 17322 [[[^disposition_notification_options]][ 17323 17324]] 17325 [[[^disposition_notification_to]][ 17326 17327]] 17328 [[[^distribution]][ 17329 17330]] 17331 [[[^dkim_signature]][ 17332 17333]] 17334 [[[^dl_expansion_history]][ 17335 17336]] 17337 [[[^downgraded_bcc]][ 17338 17339]] 17340 [[[^downgraded_cc]][ 17341 17342]] 17343 [[[^downgraded_disposition_notification_to]][ 17344 17345]] 17346 [[[^downgraded_final_recipient]][ 17347 17348]] 17349 [[[^downgraded_from]][ 17350 17351]] 17352 [[[^downgraded_in_reply_to]][ 17353 17354]] 17355 [[[^downgraded_mail_from]][ 17356 17357]] 17358 [[[^downgraded_message_id]][ 17359 17360]] 17361 [[[^downgraded_original_recipient]][ 17362 17363]] 17364 [[[^downgraded_rcpt_to]][ 17365 17366]] 17367 [[[^downgraded_references]][ 17368 17369]] 17370 [[[^downgraded_reply_to]][ 17371 17372]] 17373 [[[^downgraded_resent_bcc]][ 17374 17375]] 17376 [[[^downgraded_resent_cc]][ 17377 17378]] 17379 [[[^downgraded_resent_from]][ 17380 17381]] 17382 [[[^downgraded_resent_reply_to]][ 17383 17384]] 17385 [[[^downgraded_resent_sender]][ 17386 17387]] 17388 [[[^downgraded_resent_to]][ 17389 17390]] 17391 [[[^downgraded_return_path]][ 17392 17393]] 17394 [[[^downgraded_sender]][ 17395 17396]] 17397 [[[^downgraded_to]][ 17398 17399]] 17400 [[[^ediint_features]][ 17401 17402]] 17403 [[[^eesst_version]][ 17404 17405]] 17406 [[[^encoding]][ 17407 17408]] 17409 [[[^encrypted]][ 17410 17411]] 17412 [[[^errors_to]][ 17413 17414]] 17415 [[[^etag]][ 17416 17417]] 17418 [[[^expect]][ 17419 17420]] 17421 [[[^expires]][ 17422 17423]] 17424 [[[^expiry_date]][ 17425 17426]] 17427 [[[^ext]][ 17428 17429]] 17430 [[[^followup_to]][ 17431 17432]] 17433 [[[^forwarded]][ 17434 17435]] 17436 [[[^from]][ 17437 17438]] 17439 [[[^generate_delivery_report]][ 17440 17441]] 17442 [[[^getprofile]][ 17443 17444]] 17445 [[[^hobareg]][ 17446 17447]] 17448 [[[^host]][ 17449 17450]] 17451 [[[^http2_settings]][ 17452 17453]] 17454 [[[^if_]][ 17455 17456]] 17457 [[[^if_match]][ 17458 17459]] 17460 [[[^if_modified_since]][ 17461 17462]] 17463 [[[^if_none_match]][ 17464 17465]] 17466 [[[^if_range]][ 17467 17468]] 17469 [[[^if_schedule_tag_match]][ 17470 17471]] 17472 [[[^if_unmodified_since]][ 17473 17474]] 17475 [[[^im]][ 17476 17477]] 17478 [[[^importance]][ 17479 17480]] 17481 [[[^in_reply_to]][ 17482 17483]] 17484 [[[^incomplete_copy]][ 17485 17486]] 17487 [[[^injection_date]][ 17488 17489]] 17490 [[[^injection_info]][ 17491 17492]] 17493 [[[^jabber_id]][ 17494 17495]] 17496 [[[^keep_alive]][ 17497 17498]] 17499 [[[^keywords]][ 17500 17501]] 17502 [[[^label]][ 17503 17504]] 17505 [[[^language]][ 17506 17507]] 17508 [[[^last_modified]][ 17509 17510]] 17511 [[[^latest_delivery_time]][ 17512 17513]] 17514 [[[^lines]][ 17515 17516]] 17517 [[[^link]][ 17518 17519]] 17520 [[[^list_archive]][ 17521 17522]] 17523 [[[^list_help]][ 17524 17525]] 17526 [[[^list_id]][ 17527 17528]] 17529 [[[^list_owner]][ 17530 17531]] 17532 [[[^list_post]][ 17533 17534]] 17535 [[[^list_subscribe]][ 17536 17537]] 17538 [[[^list_unsubscribe]][ 17539 17540]] 17541 [[[^list_unsubscribe_post]][ 17542 17543]] 17544 [[[^location]][ 17545 17546]] 17547 [[[^lock_token]][ 17548 17549]] 17550 [[[^man]][ 17551 17552]] 17553 [[[^max_forwards]][ 17554 17555]] 17556 [[[^memento_datetime]][ 17557 17558]] 17559 [[[^message_context]][ 17560 17561]] 17562 [[[^message_id]][ 17563 17564]] 17565 [[[^message_type]][ 17566 17567]] 17568 [[[^meter]][ 17569 17570]] 17571 [[[^method_check]][ 17572 17573]] 17574 [[[^method_check_expires]][ 17575 17576]] 17577 [[[^mime_version]][ 17578 17579]] 17580 [[[^mmhs_acp127_message_identifier]][ 17581 17582]] 17583 [[[^mmhs_authorizing_users]][ 17584 17585]] 17586 [[[^mmhs_codress_message_indicator]][ 17587 17588]] 17589 [[[^mmhs_copy_precedence]][ 17590 17591]] 17592 [[[^mmhs_exempted_address]][ 17593 17594]] 17595 [[[^mmhs_extended_authorisation_info]][ 17596 17597]] 17598 [[[^mmhs_handling_instructions]][ 17599 17600]] 17601 [[[^mmhs_message_instructions]][ 17602 17603]] 17604 [[[^mmhs_message_type]][ 17605 17606]] 17607 [[[^mmhs_originator_plad]][ 17608 17609]] 17610 [[[^mmhs_originator_reference]][ 17611 17612]] 17613 [[[^mmhs_other_recipients_indicator_cc]][ 17614 17615]] 17616 [[[^mmhs_other_recipients_indicator_to]][ 17617 17618]] 17619 [[[^mmhs_primary_precedence]][ 17620 17621]] 17622 [[[^mmhs_subject_indicator_codes]][ 17623 17624]] 17625 [[[^mt_priority]][ 17626 17627]] 17628 [[[^negotiate]][ 17629 17630]] 17631 [[[^newsgroups]][ 17632 17633]] 17634 [[[^nntp_posting_date]][ 17635 17636]] 17637 [[[^nntp_posting_host]][ 17638 17639]] 17640 [[[^non_compliance]][ 17641 17642]] 17643 [[[^obsoletes]][ 17644 17645]] 17646 [[[^opt]][ 17647 17648]] 17649 [[[^optional]][ 17650 17651]] 17652 [[[^optional_www_authenticate]][ 17653 17654]] 17655 [[[^ordering_type]][ 17656 17657]] 17658 [[[^organization]][ 17659 17660]] 17661 [[[^origin]][ 17662 17663]] 17664 [[[^original_encoded_information_types]][ 17665 17666]] 17667 [[[^original_from]][ 17668 17669]] 17670 [[[^original_message_id]][ 17671 17672]] 17673 [[[^original_recipient]][ 17674 17675]] 17676 [[[^original_sender]][ 17677 17678]] 17679 [[[^original_subject]][ 17680 17681]] 17682 [[[^originator_return_address]][ 17683 17684]] 17685 [[[^overwrite]][ 17686 17687]] 17688 [[[^p3p]][ 17689 17690]] 17691 [[[^path]][ 17692 17693]] 17694 [[[^pep]][ 17695 17696]] 17697 [[[^pep_info]][ 17698 17699]] 17700 [[[^pics_label]][ 17701 17702]] 17703 [[[^position]][ 17704 17705]] 17706 [[[^posting_version]][ 17707 17708]] 17709 [[[^pragma]][ 17710 17711]] 17712 [[[^prefer]][ 17713 17714]] 17715 [[[^preference_applied]][ 17716 17717]] 17718 [[[^prevent_nondelivery_report]][ 17719 17720]] 17721 [[[^priority]][ 17722 17723]] 17724 [[[^privicon]][ 17725 17726]] 17727 [[[^profileobject]][ 17728 17729]] 17730 [[[^protocol]][ 17731 17732]] 17733 [[[^protocol_info]][ 17734 17735]] 17736 [[[^protocol_query]][ 17737 17738]] 17739 [[[^protocol_request]][ 17740 17741]] 17742 [[[^proxy_authenticate]][ 17743 17744]] 17745 [[[^proxy_authentication_info]][ 17746 17747]] 17748 [[[^proxy_authorization]][ 17749 17750]] 17751 [[[^proxy_connection]][ 17752 17753]] 17754 [[[^proxy_features]][ 17755 17756]] 17757 [[[^proxy_instruction]][ 17758 17759]] 17760 [[[^public_]][ 17761 17762]] 17763 [[[^public_key_pins]][ 17764 17765]] 17766 [[[^public_key_pins_report_only]][ 17767 17768]] 17769 [[[^range]][ 17770 17771]] 17772 [[[^received]][ 17773 17774]] 17775 [[[^received_spf]][ 17776 17777]] 17778 [[[^redirect_ref]][ 17779 17780]] 17781 [[[^references]][ 17782 17783]] 17784 [[[^referer]][ 17785 17786]] 17787 [[[^referer_root]][ 17788 17789]] 17790 [[[^relay_version]][ 17791 17792]] 17793 [[[^reply_by]][ 17794 17795]] 17796 [[[^reply_to]][ 17797 17798]] 17799 [[[^require_recipient_valid_since]][ 17800 17801]] 17802 [[[^resent_bcc]][ 17803 17804]] 17805 [[[^resent_cc]][ 17806 17807]] 17808 [[[^resent_date]][ 17809 17810]] 17811 [[[^resent_from]][ 17812 17813]] 17814 [[[^resent_message_id]][ 17815 17816]] 17817 [[[^resent_reply_to]][ 17818 17819]] 17820 [[[^resent_sender]][ 17821 17822]] 17823 [[[^resent_to]][ 17824 17825]] 17826 [[[^resolution_hint]][ 17827 17828]] 17829 [[[^resolver_location]][ 17830 17831]] 17832 [[[^retry_after]][ 17833 17834]] 17835 [[[^return_path]][ 17836 17837]] 17838 [[[^safe]][ 17839 17840]] 17841 [[[^schedule_reply]][ 17842 17843]] 17844 [[[^schedule_tag]][ 17845 17846]] 17847 [[[^sec_websocket_accept]][ 17848 17849]] 17850 [[[^sec_websocket_extensions]][ 17851 17852]] 17853 [[[^sec_websocket_key]][ 17854 17855]] 17856 [[[^sec_websocket_protocol]][ 17857 17858]] 17859 [[[^sec_websocket_version]][ 17860 17861]] 17862 [[[^security_scheme]][ 17863 17864]] 17865 [[[^see_also]][ 17866 17867]] 17868 [[[^sender]][ 17869 17870]] 17871 [[[^sensitivity]][ 17872 17873]] 17874 [[[^server]][ 17875 17876]] 17877 [[[^set_cookie]][ 17878 17879]] 17880 [[[^set_cookie2]][ 17881 17882]] 17883 [[[^setprofile]][ 17884 17885]] 17886 [[[^sio_label]][ 17887 17888]] 17889 [[[^sio_label_history]][ 17890 17891]] 17892 [[[^slug]][ 17893 17894]] 17895 [[[^soapaction]][ 17896 17897]] 17898 [[[^solicitation]][ 17899 17900]] 17901 [[[^status_uri]][ 17902 17903]] 17904 [[[^strict_transport_security]][ 17905 17906]] 17907 [[[^subject]][ 17908 17909]] 17910 [[[^subok]][ 17911 17912]] 17913 [[[^subst]][ 17914 17915]] 17916 [[[^summary]][ 17917 17918]] 17919 [[[^supersedes]][ 17920 17921]] 17922 [[[^surrogate_capability]][ 17923 17924]] 17925 [[[^surrogate_control]][ 17926 17927]] 17928 [[[^tcn]][ 17929 17930]] 17931 [[[^te]][ 17932 17933]] 17934 [[[^timeout]][ 17935 17936]] 17937 [[[^title]][ 17938 17939]] 17940 [[[^to]][ 17941 17942]] 17943 [[[^topic]][ 17944 17945]] 17946 [[[^trailer]][ 17947 17948]] 17949 [[[^transfer_encoding]][ 17950 17951]] 17952 [[[^ttl]][ 17953 17954]] 17955 [[[^ua_color]][ 17956 17957]] 17958 [[[^ua_media]][ 17959 17960]] 17961 [[[^ua_pixels]][ 17962 17963]] 17964 [[[^ua_resolution]][ 17965 17966]] 17967 [[[^ua_windowpixels]][ 17968 17969]] 17970 [[[^upgrade]][ 17971 17972]] 17973 [[[^urgency]][ 17974 17975]] 17976 [[[^uri]][ 17977 17978]] 17979 [[[^user_agent]][ 17980 17981]] 17982 [[[^variant_vary]][ 17983 17984]] 17985 [[[^vary]][ 17986 17987]] 17988 [[[^vbr_info]][ 17989 17990]] 17991 [[[^version]][ 17992 17993]] 17994 [[[^via]][ 17995 17996]] 17997 [[[^want_digest]][ 17998 17999]] 18000 [[[^warning]][ 18001 18002]] 18003 [[[^www_authenticate]][ 18004 18005]] 18006 [[[^x_archived_at]][ 18007 18008]] 18009 [[[^x_device_accept]][ 18010 18011]] 18012 [[[^x_device_accept_charset]][ 18013 18014]] 18015 [[[^x_device_accept_encoding]][ 18016 18017]] 18018 [[[^x_device_accept_language]][ 18019 18020]] 18021 [[[^x_device_user_agent]][ 18022 18023]] 18024 [[[^x_frame_options]][ 18025 18026]] 18027 [[[^x_mittente]][ 18028 18029]] 18030 [[[^x_pgp_sig]][ 18031 18032]] 18033 [[[^x_ricevuta]][ 18034 18035]] 18036 [[[^x_riferimento_message_id]][ 18037 18038]] 18039 [[[^x_tiporicevuta]][ 18040 18041]] 18042 [[[^x_trasporto]][ 18043 18044]] 18045 [[[^x_verificasicurezza]][ 18046 18047]] 18048 [[[^x400_content_identifier]][ 18049 18050]] 18051 [[[^x400_content_return]][ 18052 18053]] 18054 [[[^x400_content_type]][ 18055 18056]] 18057 [[[^x400_mts_identifier]][ 18058 18059]] 18060 [[[^x400_originator]][ 18061 18062]] 18063 [[[^x400_received]][ 18064 18065]] 18066 [[[^x400_recipients]][ 18067 18068]] 18069 [[[^x400_trace]][ 18070 18071]] 18072 [[[^xref]][ 18073 18074]] 18075] 18076 18077[heading Description] 18078 18079 18080 18081Convenience header [include_file boost/beast/http.hpp] 18082 18083[endsect] 18084[section:boost__beast__http__fields http::fields] 18085[indexterm1 http::fields] 18086A typical HTTP header fields container. 18087[heading Synopsis] 18088 18089Defined in header [include_file boost/beast/http/fields.hpp] 18090 18091 18092 18093``` 18094using fields = basic_fields< std::allocator< char > >; 18095``` 18096[heading Types] 18097[table [[Name][Description]] 18098 [ 18099 [[link beast.ref.boost__beast__http__basic_fields.allocator_type [*allocator_type]]] 18100 [ 18101 The type of allocator used. 18102 ] 18103 ] 18104 [ 18105 [[link beast.ref.boost__beast__http__basic_fields__value_type [*value_type]]] 18106 [ 18107 The type of element used to represent a field. 18108 ] 18109 ] 18110 [ 18111 [[link beast.ref.boost__beast__http__basic_fields.const_iterator [*const_iterator]]] 18112 [ 18113 A constant iterator to the field sequence. 18114 ] 18115 ] 18116 [ 18117 [[link beast.ref.boost__beast__http__basic_fields.iterator [*iterator]]] 18118 [ 18119 A constant iterator to the field sequence. 18120 ] 18121 ] 18122 [ 18123 [[link beast.ref.boost__beast__http__basic_fields.key_compare [*key_compare]]] 18124 [ 18125 A strictly less predicate for comparing keys, using a case-insensitive comparison. 18126 ] 18127 ] 18128 [ 18129 [[link beast.ref.boost__beast__http__basic_fields.writer [*writer]]] 18130 [ 18131 The algorithm used to serialize the header. 18132 ] 18133 ] 18134] 18135[heading Member Functions] 18136[table [[Name][Description]] 18137 [ 18138 [[link beast.ref.boost__beast__http__basic_fields.at [*at]]] 18139 [ 18140 Returns the value for a field, or throws an exception. 18141 ] 18142 ] 18143 [ 18144 [[link beast.ref.boost__beast__http__basic_fields.basic_fields [*basic_fields]]] 18145 [ 18146 Constructor. 18147 18148 Move constructor. 18149 18150 Copy constructor. 18151 ] 18152 ] 18153 [ 18154 [[link beast.ref.boost__beast__http__basic_fields.begin [*begin]]] 18155 [ 18156 Return a const iterator to the beginning of the field sequence. 18157 ] 18158 ] 18159 [ 18160 [[link beast.ref.boost__beast__http__basic_fields.cbegin [*cbegin]]] 18161 [ 18162 Return a const iterator to the beginning of the field sequence. 18163 ] 18164 ] 18165 [ 18166 [[link beast.ref.boost__beast__http__basic_fields.cend [*cend]]] 18167 [ 18168 Return a const iterator to the end of the field sequence. 18169 ] 18170 ] 18171 [ 18172 [[link beast.ref.boost__beast__http__basic_fields.clear [*clear]]] 18173 [ 18174 Remove all fields from the container. 18175 ] 18176 ] 18177 [ 18178 [[link beast.ref.boost__beast__http__basic_fields.count [*count]]] 18179 [ 18180 Return the number of fields with the specified name. 18181 ] 18182 ] 18183 [ 18184 [[link beast.ref.boost__beast__http__basic_fields.end [*end]]] 18185 [ 18186 Return a const iterator to the end of the field sequence. 18187 ] 18188 ] 18189 [ 18190 [[link beast.ref.boost__beast__http__basic_fields.equal_range [*equal_range]]] 18191 [ 18192 Returns a range of iterators to the fields with the specified name. 18193 ] 18194 ] 18195 [ 18196 [[link beast.ref.boost__beast__http__basic_fields.erase [*erase]]] 18197 [ 18198 Remove a field. 18199 18200 Remove all fields with the specified name. 18201 ] 18202 ] 18203 [ 18204 [[link beast.ref.boost__beast__http__basic_fields.find [*find]]] 18205 [ 18206 Returns an iterator to the case-insensitive matching field. 18207 18208 Returns an iterator to the case-insensitive matching field name. 18209 ] 18210 ] 18211 [ 18212 [[link beast.ref.boost__beast__http__basic_fields.get_allocator [*get_allocator]]] 18213 [ 18214 Return a copy of the allocator associated with the container. 18215 ] 18216 ] 18217 [ 18218 [[link beast.ref.boost__beast__http__basic_fields.insert [*insert]]] 18219 [ 18220 Insert a field. 18221 ] 18222 ] 18223 [ 18224 [[link beast.ref.boost__beast__http__basic_fields.key_comp [*key_comp]]] 18225 [ 18226 Returns a copy of the key comparison function. 18227 ] 18228 ] 18229 [ 18230 [[link beast.ref.boost__beast__http__basic_fields.operator_eq_ [*operator=]]] 18231 [ 18232 Move assignment. 18233 18234 Copy assignment. 18235 ] 18236 ] 18237 [ 18238 [[link beast.ref.boost__beast__http__basic_fields.operator_lb__rb_ [*operator\[\]]]] 18239 [ 18240 Returns the value for a field, or "" if it does not exist. 18241 18242 Returns the value for a case-insensitive matching header, or "" if it does not exist. 18243 ] 18244 ] 18245 [ 18246 [[link beast.ref.boost__beast__http__basic_fields.set [*set]]] 18247 [ 18248 Set a field value, removing any other instances of that field. 18249 ] 18250 ] 18251 [ 18252 [[link beast.ref.boost__beast__http__basic_fields.swap [*swap]]] 18253 [ 18254 Return a buffer sequence representing the trailers. 18255 ] 18256 ] 18257 [ 18258 [[link beast.ref.boost__beast__http__basic_fields.basic_fields_dtor_ [*~basic_fields]]] 18259 [ 18260 Destructor. 18261 ] 18262 ] 18263] 18264[heading Protected Member Functions] 18265[table [[Name][Description]] 18266 [ 18267 [[link beast.ref.boost__beast__http__basic_fields.get_chunked_impl [*get_chunked_impl]]] 18268 [ 18269 Returns the chunked Transfer-Encoding setting. 18270 ] 18271 ] 18272 [ 18273 [[link beast.ref.boost__beast__http__basic_fields.get_keep_alive_impl [*get_keep_alive_impl]]] 18274 [ 18275 Returns the keep-alive setting. 18276 ] 18277 ] 18278 [ 18279 [[link beast.ref.boost__beast__http__basic_fields.get_method_impl [*get_method_impl]]] 18280 [ 18281 Returns the request-method string. 18282 ] 18283 ] 18284 [ 18285 [[link beast.ref.boost__beast__http__basic_fields.get_reason_impl [*get_reason_impl]]] 18286 [ 18287 Returns the response reason-phrase string. 18288 ] 18289 ] 18290 [ 18291 [[link beast.ref.boost__beast__http__basic_fields.get_target_impl [*get_target_impl]]] 18292 [ 18293 Returns the request-target string. 18294 ] 18295 ] 18296 [ 18297 [[link beast.ref.boost__beast__http__basic_fields.has_content_length_impl [*has_content_length_impl]]] 18298 [ 18299 Returns true if the Content-Length field is present. 18300 ] 18301 ] 18302 [ 18303 [[link beast.ref.boost__beast__http__basic_fields.set_chunked_impl [*set_chunked_impl]]] 18304 [ 18305 Adjusts the chunked Transfer-Encoding value. 18306 ] 18307 ] 18308 [ 18309 [[link beast.ref.boost__beast__http__basic_fields.set_content_length_impl [*set_content_length_impl]]] 18310 [ 18311 Sets or clears the Content-Length field. 18312 ] 18313 ] 18314 [ 18315 [[link beast.ref.boost__beast__http__basic_fields.set_keep_alive_impl [*set_keep_alive_impl]]] 18316 [ 18317 Adjusts the Connection field. 18318 ] 18319 ] 18320 [ 18321 [[link beast.ref.boost__beast__http__basic_fields.set_method_impl [*set_method_impl]]] 18322 [ 18323 Set or clear the method string. 18324 ] 18325 ] 18326 [ 18327 [[link beast.ref.boost__beast__http__basic_fields.set_reason_impl [*set_reason_impl]]] 18328 [ 18329 Set or clear the reason string. 18330 ] 18331 ] 18332 [ 18333 [[link beast.ref.boost__beast__http__basic_fields.set_target_impl [*set_target_impl]]] 18334 [ 18335 Set or clear the target string. 18336 ] 18337 ] 18338] 18339[heading Friends] 18340[table [[Name][Description]] 18341 [ 18342 [[link beast.ref.boost__beast__http__basic_fields.swap [*swap]]] 18343 [ 18344 Swap two field containers. 18345 ] 18346 ] 18347] 18348This container is designed to store the field value pairs that make up the fields and trailers in an HTTP message. Objects of this type are iterable, with each element holding the field name and field value. 18349Field names are stored as-is, but comparisons are case-insensitive. The container behaves as a `std::multiset`; there will be a separate value for each occurrence of the same field name. When the container is iterated the fields are presented in the order of insertion, with fields having the same name following each other consecutively. 18350Meets the requirements of ['Fields] 18351[heading Template Parameters] 18352[table [[Type][Description]] 18353 [[`Allocator`][ 18354 18355The allocator to use. 18356 ]] 18357] 18358 18359[heading Description] 18360 18361 18362 18363Convenience header [include_file boost/beast/http.hpp] 18364 18365[endsect] 18366[section:boost__beast__http__file_body http::file_body] 18367[indexterm1 http::file_body] 18368A message body represented by a file on the filesystem. 18369[heading Synopsis] 18370 18371Defined in header [include_file boost/beast/http/file_body.hpp] 18372 18373 18374 18375``` 18376using file_body = basic_file_body< file >; 18377``` 18378[heading Types] 18379[table [[Name][Description]] 18380 [ 18381 [[link beast.ref.boost__beast__http__basic_file_body__reader [*reader]]] 18382 [ 18383 Algorithm for storing buffers when parsing. 18384 ] 18385 ] 18386 [ 18387 [[link beast.ref.boost__beast__http__basic_file_body__value_type [*value_type]]] 18388 [ 18389 The type of the message::body member. 18390 ] 18391 ] 18392 [ 18393 [[link beast.ref.boost__beast__http__basic_file_body__writer [*writer]]] 18394 [ 18395 Algorithm for retrieving buffers when serializing. 18396 ] 18397 ] 18398 [ 18399 [[link beast.ref.boost__beast__http__basic_file_body.file_type [*file_type]]] 18400 [ 18401 The type of File this body uses. 18402 ] 18403 ] 18404] 18405[heading Member Functions] 18406[table [[Name][Description]] 18407 [ 18408 [[link beast.ref.boost__beast__http__basic_file_body.size [*size]]] 18409 [ 18410 Returns the size of the body. 18411 ] 18412 ] 18413] 18414Messages with this type have bodies represented by a file on the file system. When parsing a message using this body type, the data is stored in the file pointed to by the path, which must be writable. When serializing, the implementation will read the file and present those octets as the body content. This may be used to serve content from a directory as part of a web service. 18415[heading Template Parameters] 18416[table [[Type][Description]] 18417 [[`File`][ 18418 18419The implementation to use for accessing files. This type must meet the requirements of ['File]. 18420 ]] 18421] 18422 18423[heading Description] 18424 18425 18426 18427Convenience header [include_file boost/beast/http.hpp] 18428 18429[endsect] 18430[section:boost__beast__http__header http::header] 18431A container for an HTTP request or response header. 18432[heading Synopsis] 18433 18434Defined in header [include_file boost/beast/http/message.hpp] 18435 18436 18437 18438``` 18439template< 18440 bool isRequest, 18441 class __Fields__ = fields> 18442class header : 18443 public Fields 18444``` 18445[heading Types] 18446[table [[Name][Description]] 18447 [ 18448 [[link beast.ref.boost__beast__http__header.fields_type [*fields_type]]] 18449 [ 18450 The type representing the fields. 18451 ] 18452 ] 18453 [ 18454 [[link beast.ref.boost__beast__http__header.is_request [*is_request]]] 18455 [ 18456 Indicates if the header is a request or response. 18457 ] 18458 ] 18459] 18460[heading Member Functions] 18461[table [[Name][Description]] 18462 [ 18463 [[link beast.ref.boost__beast__http__header.header [*header]]] 18464 [ 18465 Constructor. 18466 ] 18467 ] 18468 [ 18469 [[link beast.ref.boost__beast__http__header.method [*method]]] 18470 [ 18471 Return the request-method verb. 18472 18473 Set the request-method. 18474 ] 18475 ] 18476 [ 18477 [[link beast.ref.boost__beast__http__header.method_string [*method_string]]] 18478 [ 18479 Return the request-method as a string. 18480 ] 18481 ] 18482 [ 18483 [[link beast.ref.boost__beast__http__header.operator_eq_ [*operator=]]] 18484 [ 18485 Assignment. 18486 ] 18487 ] 18488 [ 18489 [[link beast.ref.boost__beast__http__header.reason [*reason]]] 18490 [ 18491 Return the response reason-phrase. 18492 18493 Set the response reason-phrase (deprecated) 18494 ] 18495 ] 18496 [ 18497 [[link beast.ref.boost__beast__http__header.result [*result]]] 18498 [ 18499 The response status-code result. 18500 18501 Set the response status-code. 18502 18503 Set the response status-code as an integer. 18504 ] 18505 ] 18506 [ 18507 [[link beast.ref.boost__beast__http__header.result_int [*result_int]]] 18508 [ 18509 The response status-code expressed as an integer. 18510 ] 18511 ] 18512 [ 18513 [[link beast.ref.boost__beast__http__header.target [*target]]] 18514 [ 18515 Returns the request-target string. 18516 18517 Set the request-target string. 18518 ] 18519 ] 18520 [ 18521 [[link beast.ref.boost__beast__http__header.version [*version]]] 18522 [ 18523 Return the HTTP-version. 18524 18525 Set the HTTP-version. 18526 ] 18527 ] 18528] 18529 18530[heading Description] 18531This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 18532Newly constructed header objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 18533A `header` includes the start-line and header-fields. [section:fields_type http::header::fields_type] 18534[indexterm2 fields_type..http::header] 18535The type representing the fields. 18536[heading Synopsis] 18537 18538``` 18539using fields_type = Fields; 18540``` 18541 18542[heading Description] 18543[endsect] 18544[section:header http::header::header] 18545[indexterm2 header..http::header] 18546Constructor. ``` 18547``[link beast.ref.boost__beast__http__header.header.overload1 header]``(); 18548 ``[''''»''' [link beast.ref.boost__beast__http__header.header.overload1 more...]]`` 18549 18550``[link beast.ref.boost__beast__http__header.header.overload2 header]``( 18551 header&&); 18552 ``[''''»''' [link beast.ref.boost__beast__http__header.header.overload2 more...]]`` 18553 18554``[link beast.ref.boost__beast__http__header.header.overload3 header]``( 18555 header const&); 18556 ``[''''»''' [link beast.ref.boost__beast__http__header.header.overload3 more...]]`` 18557 18558template< 18559 class... Args> 18560explicit 18561``[link beast.ref.boost__beast__http__header.header.overload4 header]``( 18562 Args&&... args); 18563 ``[''''»''' [link beast.ref.boost__beast__http__header.header.overload4 more...]]`` 18564``` 18565[section:overload1 http::header::header (1 of 4 overloads)] 18566Constructor. 18567[heading Synopsis] 18568``` 18569header(); 18570``` 18571 18572[heading Description] 18573[endsect] 18574[section:overload2 http::header::header (2 of 4 overloads)] 18575Constructor. 18576[heading Synopsis] 18577``` 18578header( 18579 header&&); 18580``` 18581 18582[heading Description] 18583[endsect] 18584[section:overload3 http::header::header (3 of 4 overloads)] 18585Constructor. 18586[heading Synopsis] 18587``` 18588header( 18589 header const&); 18590``` 18591 18592[heading Description] 18593[endsect] 18594[section:overload4 http::header::header (4 of 4 overloads)] 18595Constructor. 18596[heading Synopsis] 18597``` 18598template< 18599 class... Args> 18600header( 18601 Args&&... args); 18602``` 18603 18604[heading Description] 18605[heading Parameters] 18606[table [[Name][Description]] 18607 [[`args`][ 18608 18609Arguments forwarded to the `Fields` base class constructor. 18610 ]] 18611] 18612[heading Remarks] 18613This constructor participates in overload resolution if and only if the first parameter is not convertible to [link beast.ref.boost__beast__http__header `http::header`], [link beast.ref.boost__beast__http__verb `http::verb`], or [link beast.ref.boost__beast__http__status `http::status`]. 18614[endsect] 18615[endsect] 18616 18617[section:is_request http::header::is_request] 18618[indexterm2 is_request..http::header] 18619Indicates if the header is a request or response. 18620[heading Synopsis] 18621 18622``` 18623using is_request = std::integral_constant< bool, isRequest >; 18624``` 18625 18626[heading Description] 18627[endsect] 18628[section:method http::header::method] 18629[indexterm2 method..http::header] 18630Return the request-method verb. ``` 18631verb 18632``[link beast.ref.boost__beast__http__header.method.overload1 method]``() const; 18633 ``[''''»''' [link beast.ref.boost__beast__http__header.method.overload1 more...]]`` 18634 18635``` 18636Set the request-method. ``` 18637void 18638``[link beast.ref.boost__beast__http__header.method.overload2 method]``( 18639 verb v); 18640 ``[''''»''' [link beast.ref.boost__beast__http__header.method.overload2 more...]]`` 18641``` 18642[section:overload1 http::header::method (1 of 2 overloads)] 18643Return the request-method verb. 18644[heading Synopsis] 18645``` 18646verb 18647method() const; 18648``` 18649 18650[heading Description] 18651If the request-method is not one of the recognized verbs, [link beast.ref.boost__beast__http__field `http::unknown`] is returned. Callers may use [link beast.ref.boost__beast__http__header.method_string `http::header::method_string`] to retrieve the exact text. 18652[heading Remarks] 18653This function is only available when `isRequest == true`. 18654[heading See Also] 18655[link beast.ref.boost__beast__http__header.method_string `http::header::method_string`] 18656[endsect] 18657[section:overload2 http::header::method (2 of 2 overloads)] 18658Set the request-method. 18659[heading Synopsis] 18660``` 18661void 18662method( 18663 verb v); 18664``` 18665 18666[heading Description] 18667This function will set the method for requests to a known verb. 18668[heading Parameters] 18669[table [[Name][Description]] 18670 [[`v`][ 18671 18672The request method verb to set. This may not be [link beast.ref.boost__beast__http__field `http::unknown`]. 18673 ]] 18674] 18675[heading Exceptions] 18676[table [[Type][Thrown On]] 18677 [[`std::invalid_argument`][ 18678 18679when `v == verb::unknown`. 18680 ]] 18681] 18682[heading Remarks] 18683This function is only available when `isRequest == true`. 18684[endsect] 18685[endsect] 18686 18687[section:method_string http::header::method_string] 18688[indexterm2 method_string..http::header] 18689Return the request-method as a string. ``` 18690string_view 18691``[link beast.ref.boost__beast__http__header.method_string.overload1 method_string]``() const; 18692 ``[''''»''' [link beast.ref.boost__beast__http__header.method_string.overload1 more...]]`` 18693 18694void 18695``[link beast.ref.boost__beast__http__header.method_string.overload2 method_string]``( 18696 string_view s); 18697 ``[''''»''' [link beast.ref.boost__beast__http__header.method_string.overload2 more...]]`` 18698``` 18699[section:overload1 http::header::method_string (1 of 2 overloads)] 18700Return the request-method as a string. 18701[heading Synopsis] 18702``` 18703string_view 18704method_string() const; 18705``` 18706 18707[heading Description] 18708[heading Remarks] 18709This function is only available when `isRequest == true`. 18710[heading See Also] 18711[link beast.ref.boost__beast__http__header.method `http::header::method`] 18712[endsect] 18713[section:overload2 http::header::method_string (2 of 2 overloads)] 18714Set the request-method. 18715[heading Synopsis] 18716``` 18717void 18718method_string( 18719 string_view s); 18720``` 18721 18722[heading Description] 18723This function will set the request-method a known verb if the string matches, otherwise it will store a copy of the passed string. 18724[heading Parameters] 18725[table [[Name][Description]] 18726 [[`s`][ 18727 18728A string representing the request-method. 18729 ]] 18730] 18731[heading Remarks] 18732This function is only available when `isRequest == true`. 18733[endsect] 18734[endsect] 18735 18736[section:operator_eq_ http::header::operator=] 18737[indexterm2 operator=..http::header] 18738Assignment. ``` 18739header& 18740``[link beast.ref.boost__beast__http__header.operator_eq_.overload1 operator=]``( 18741 header&&); 18742 ``[''''»''' [link beast.ref.boost__beast__http__header.operator_eq_.overload1 more...]]`` 18743 18744header& 18745``[link beast.ref.boost__beast__http__header.operator_eq_.overload2 operator=]``( 18746 header const&); 18747 ``[''''»''' [link beast.ref.boost__beast__http__header.operator_eq_.overload2 more...]]`` 18748``` 18749[section:overload1 http::header::operator= (1 of 2 overloads)] 18750Assignment. 18751[heading Synopsis] 18752``` 18753header& 18754operator=( 18755 header&&); 18756``` 18757 18758[heading Description] 18759[endsect] 18760[section:overload2 http::header::operator= (2 of 2 overloads)] 18761Assignment. 18762[heading Synopsis] 18763``` 18764header& 18765operator=( 18766 header const&); 18767``` 18768 18769[heading Description] 18770[endsect] 18771[endsect] 18772 18773[section:reason http::header::reason] 18774[indexterm2 reason..http::header] 18775Return the response reason-phrase. ``` 18776string_view 18777``[link beast.ref.boost__beast__http__header.reason.overload1 reason]``() const; 18778 ``[''''»''' [link beast.ref.boost__beast__http__header.reason.overload1 more...]]`` 18779 18780``` 18781Set the response reason-phrase (deprecated) ``` 18782void 18783``[link beast.ref.boost__beast__http__header.reason.overload2 reason]``( 18784 string_view s); 18785 ``[''''»''' [link beast.ref.boost__beast__http__header.reason.overload2 more...]]`` 18786``` 18787[section:overload1 http::header::reason (1 of 2 overloads)] 18788Return the response reason-phrase. 18789[heading Synopsis] 18790``` 18791string_view 18792reason() const; 18793``` 18794 18795[heading Description] 18796The reason-phrase is obsolete as of rfc7230. 18797[heading Remarks] 18798This function is only available when `isRequest == false`. 18799[endsect] 18800[section:overload2 http::header::reason (2 of 2 overloads)] 18801Set the response reason-phrase (deprecated) 18802[heading Synopsis] 18803``` 18804void 18805reason( 18806 string_view s); 18807``` 18808 18809[heading Description] 18810This function sets a custom reason-phrase to a copy of the string passed in. Normally it is not necessary to set the reason phrase on an outgoing response object; the implementation will automatically use the standard reason text for the corresponding status code. 18811To clear a previously set custom phrase, pass an empty string. This will restore the default standard reason text based on the status code used when serializing. 18812The reason-phrase is obsolete as of rfc7230. 18813[heading Parameters] 18814[table [[Name][Description]] 18815 [[`s`][ 18816 18817The string to use for the reason-phrase. 18818 ]] 18819] 18820[heading Remarks] 18821This function is only available when `isRequest == false`. 18822[endsect] 18823[endsect] 18824 18825[section:result http::header::result] 18826[indexterm2 result..http::header] 18827The response status-code result. ``` 18828status 18829``[link beast.ref.boost__beast__http__header.result.overload1 result]``() const; 18830 ``[''''»''' [link beast.ref.boost__beast__http__header.result.overload1 more...]]`` 18831 18832``` 18833Set the response status-code. ``` 18834void 18835``[link beast.ref.boost__beast__http__header.result.overload2 result]``( 18836 status v); 18837 ``[''''»''' [link beast.ref.boost__beast__http__header.result.overload2 more...]]`` 18838 18839``` 18840Set the response status-code as an integer. ``` 18841void 18842``[link beast.ref.boost__beast__http__header.result.overload3 result]``( 18843 unsigned v); 18844 ``[''''»''' [link beast.ref.boost__beast__http__header.result.overload3 more...]]`` 18845``` 18846[section:overload1 http::header::result (1 of 3 overloads)] 18847The response status-code result. 18848[heading Synopsis] 18849``` 18850status 18851result() const; 18852``` 18853 18854[heading Description] 18855If the actual status code is not a known code, this function returns [link beast.ref.boost__beast__http__field `http::unknown`]. Use [link beast.ref.boost__beast__http__header.result_int `http::header::result_int`] to return the raw status code as a number. 18856[heading Remarks] 18857This member is only available when `isRequest == false`. 18858[endsect] 18859[section:overload2 http::header::result (2 of 3 overloads)] 18860Set the response status-code. 18861[heading Synopsis] 18862``` 18863void 18864result( 18865 status v); 18866``` 18867 18868[heading Description] 18869[heading Parameters] 18870[table [[Name][Description]] 18871 [[`v`][ 18872 18873The code to set. 18874 ]] 18875] 18876[heading Remarks] 18877This member is only available when `isRequest == false`. 18878[endsect] 18879[section:overload3 http::header::result (3 of 3 overloads)] 18880Set the response status-code as an integer. 18881[heading Synopsis] 18882``` 18883void 18884result( 18885 unsigned v); 18886``` 18887 18888[heading Description] 18889This sets the status code to the exact number passed in. If the number does not correspond to one of the known status codes, the function [link beast.ref.boost__beast__http__header.result `http::header::result`] will return [link beast.ref.boost__beast__http__field `http::unknown`]. Use [link beast.ref.boost__beast__http__header.result_int `http::header::result_int`] to obtain the original raw status-code. 18890[heading Parameters] 18891[table [[Name][Description]] 18892 [[`v`][ 18893 18894The status-code integer to set. 18895 ]] 18896] 18897[heading Exceptions] 18898[table [[Type][Thrown On]] 18899 [[`std::invalid_argument`][ 18900 18901if `v > 999`. 18902 ]] 18903] 18904[endsect] 18905[endsect] 18906 18907[section:result_int http::header::result_int] 18908[indexterm2 result_int..http::header] 18909The response status-code expressed as an integer. 18910[heading Synopsis] 18911``` 18912unsigned 18913result_int() const; 18914``` 18915 18916[heading Description] 18917This returns the raw status code as an integer, even when that code is not in the list of known status codes. 18918[heading Remarks] 18919This member is only available when `isRequest == false`. 18920[endsect] 18921[section:target http::header::target] 18922[indexterm2 target..http::header] 18923Returns the request-target string. ``` 18924string_view 18925``[link beast.ref.boost__beast__http__header.target.overload1 target]``() const; 18926 ``[''''»''' [link beast.ref.boost__beast__http__header.target.overload1 more...]]`` 18927 18928``` 18929Set the request-target string. ``` 18930void 18931``[link beast.ref.boost__beast__http__header.target.overload2 target]``( 18932 string_view s); 18933 ``[''''»''' [link beast.ref.boost__beast__http__header.target.overload2 more...]]`` 18934``` 18935[section:overload1 http::header::target (1 of 2 overloads)] 18936Returns the request-target string. 18937[heading Synopsis] 18938``` 18939string_view 18940target() const; 18941``` 18942 18943[heading Description] 18944The request target string returned is the same string which was received from the network or stored. In particular, it will contain url-encoded characters and should follow the syntax rules for URIs used with HTTP. 18945[heading Remarks] 18946This function is only available when `isRequest == true`. 18947[endsect] 18948[section:overload2 http::header::target (2 of 2 overloads)] 18949Set the request-target string. 18950[heading Synopsis] 18951``` 18952void 18953target( 18954 string_view s); 18955``` 18956 18957[heading Description] 18958It is the caller's responsibility to ensure that the request target string follows the syntax rules for URIs used with HTTP. In particular, reserved or special characters must be url-encoded. The implementation does not perform syntax checking on the passed string. 18959[heading Parameters] 18960[table [[Name][Description]] 18961 [[`s`][ 18962 18963A string representing the request-target. 18964 ]] 18965] 18966[heading Remarks] 18967This function is only available when `isRequest == true`. 18968[endsect] 18969[endsect] 18970 18971[section:version http::header::version] 18972[indexterm2 version..http::header] 18973Return the HTTP-version. ``` 18974unsigned 18975``[link beast.ref.boost__beast__http__header.version.overload1 version]``() const; 18976 ``[''''»''' [link beast.ref.boost__beast__http__header.version.overload1 more...]]`` 18977 18978``` 18979Set the HTTP-version. ``` 18980void 18981``[link beast.ref.boost__beast__http__header.version.overload2 version]``( 18982 unsigned value); 18983 ``[''''»''' [link beast.ref.boost__beast__http__header.version.overload2 more...]]`` 18984``` 18985[section:overload1 http::header::version (1 of 2 overloads)] 18986Return the HTTP-version. 18987[heading Synopsis] 18988``` 18989unsigned 18990version() const; 18991``` 18992 18993[heading Description] 18994This holds both the major and minor version numbers, using these formulas: 18995``` 18996 unsigned major = version / 10; 18997 unsigned minor = version % 10; 18998``` 18999Newly constructed headers will use HTTP/1.1 by default. [endsect] 19000[section:overload2 http::header::version (2 of 2 overloads)] 19001Set the HTTP-version. 19002[heading Synopsis] 19003``` 19004void 19005version( 19006 unsigned value); 19007``` 19008 19009[heading Description] 19010This holds both the major and minor version numbers, using these formulas: 19011``` 19012 unsigned major = version / 10; 19013 unsigned minor = version % 10; 19014``` 19015Newly constructed headers will use HTTP/1.1 by default. 19016[heading Parameters] 19017[table [[Name][Description]] 19018 [[`value`][ 19019 19020The version number to use 19021 ]] 19022] 19023[endsect] 19024[endsect] 19025 19026 19027 19028 19029Convenience header [include_file boost/beast/http.hpp] 19030 19031[endsect] 19032 19033 19034 19035[section:boost__beast__http__icy_stream http::icy_stream] 19036Stream wrapper to process Shoutcast HTTP responses. 19037[heading Synopsis] 19038 19039Defined in header [include_file boost/beast/_experimental/http/icy_stream.hpp] 19040 19041 19042 19043``` 19044template< 19045 class NextLayer> 19046class icy_stream 19047``` 19048[heading Types] 19049[table [[Name][Description]] 19050 [ 19051 [[link beast.ref.boost__beast__http__icy_stream.executor_type [*executor_type]]] 19052 [ 19053 The type of the executor associated with the object. 19054 ] 19055 ] 19056 [ 19057 [[link beast.ref.boost__beast__http__icy_stream.next_layer_type [*next_layer_type]]] 19058 [ 19059 The type of the next layer. 19060 ] 19061 ] 19062] 19063[heading Member Functions] 19064[table [[Name][Description]] 19065 [ 19066 [[link beast.ref.boost__beast__http__icy_stream.async_read_some [*async_read_some]]] 19067 [ 19068 Start an asynchronous read. 19069 ] 19070 ] 19071 [ 19072 [[link beast.ref.boost__beast__http__icy_stream.async_write_some [*async_write_some]]] 19073 [ 19074 Start an asynchronous write. 19075 ] 19076 ] 19077 [ 19078 [[link beast.ref.boost__beast__http__icy_stream.get_executor [*get_executor]]] 19079 [ 19080 Get the executor associated with the object. 19081 ] 19082 ] 19083 [ 19084 [[link beast.ref.boost__beast__http__icy_stream.icy_stream [*icy_stream]]] 19085 [ 19086 19087 19088 Constructor. 19089 ] 19090 ] 19091 [ 19092 [[link beast.ref.boost__beast__http__icy_stream.next_layer [*next_layer]]] 19093 [ 19094 Get a reference to the next layer. 19095 ] 19096 ] 19097 [ 19098 [[link beast.ref.boost__beast__http__icy_stream.operator_eq_ [*operator=]]] 19099 [ 19100 19101 ] 19102 ] 19103 [ 19104 [[link beast.ref.boost__beast__http__icy_stream.read_some [*read_some]]] 19105 [ 19106 Read some data from the stream. 19107 ] 19108 ] 19109 [ 19110 [[link beast.ref.boost__beast__http__icy_stream.write_some [*write_some]]] 19111 [ 19112 Write some data to the stream. 19113 ] 19114 ] 19115 [ 19116 [[link beast.ref.boost__beast__http__icy_stream.icy_stream_dtor_ [*~icy_stream]]] 19117 [ 19118 Destructor. 19119 ] 19120 ] 19121] 19122 19123[heading Description] 19124This wrapper replaces the word "ICY" in the first HTTP response received on the connection, with "HTTP/1.1". This allows the Beast parser to be used with Shoutcast servers, which send a non-standard HTTP message as the response. 19125For asynchronous operations, the application must ensure that they are are all performed within the same implicit or explicit strand. 19126[heading Thread Safety] 19127['Distinct] ['objects:] Safe. 19128 19129['Shared] ['objects:] Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 19130[heading Example] 19131To use the [link beast.ref.boost__beast__http__icy_stream `http::icy_stream`] template with an [link beast.ref.boost__beast__tcp_stream `tcp_stream`] you would write: 19132``` 19133 http::icy_stream<tcp_stream> is(ioc); 19134``` 19135[heading Template Parameters] 19136[table [[Type][Description]] 19137 [[`NextLayer`][ 19138 19139The type representing the next layer, to which data will be read and written during operations. For synchronous operations, the type must support the ['SyncStream] concept. For asynchronous operations, the type must support the ['AsyncStream] concept. 19140 ]] 19141] 19142[heading Remarks] 19143A stream object must not be moved or destroyed while there are pending asynchronous operations associated with it. 19144[heading Concepts] 19145['AsyncStream], ['SyncStream] 19146[section:async_read_some http::icy_stream::async_read_some] 19147[indexterm2 async_read_some..http::icy_stream] 19148Start an asynchronous read. 19149[heading Synopsis] 19150``` 19151template< 19152 class __MutableBufferSequence__, 19153 class __ReadHandler__ = net::default_completion_token_t<executor_type>> 19154``__deduced__`` 19155async_read_some( 19156 MutableBufferSequence const& buffers, 19157 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 19158``` 19159 19160[heading Description] 19161This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately. 19162[heading Parameters] 19163[table [[Name][Description]] 19164 [[`buffers`][ 19165 19166The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 19167 ]] 19168 [[`handler`][ 19169 19170The 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: 19171``` 19172 void handler( 19173 const boost::system::error_code& error, // Result of operation. 19174 std::size_t bytes_transferred // Number of bytes read. 19175 ); 19176``` 19177Regardless 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 `net::post`. 19178 ]] 19179] 19180[heading Remarks] 19181The `async_read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. 19182[endsect] 19183[section:async_write_some http::icy_stream::async_write_some] 19184[indexterm2 async_write_some..http::icy_stream] 19185Start an asynchronous write. 19186[heading Synopsis] 19187``` 19188template< 19189 class __ConstBufferSequence__, 19190 class __WriteHandler__ = net::default_completion_token_t<executor_type>> 19191``__deduced__`` 19192async_write_some( 19193 ConstBufferSequence const& buffers, 19194 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 19195``` 19196 19197[heading Description] 19198This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately. 19199[heading Parameters] 19200[table [[Name][Description]] 19201 [[`buffers`][ 19202 19203The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 19204 ]] 19205 [[`handler`][ 19206 19207The 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: 19208``` 19209 void handler( 19210 error_code const& error, // Result of operation. 19211 std::size_t bytes_transferred // Number of bytes written. 19212 ); 19213``` 19214Regardless 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 `net::post`. 19215 ]] 19216] 19217[heading Remarks] 19218The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need to ensure that all data is written before the asynchronous operation completes. 19219[endsect] 19220[section:executor_type http::icy_stream::executor_type] 19221[indexterm2 executor_type..http::icy_stream] 19222The type of the executor associated with the object. 19223[heading Synopsis] 19224 19225``` 19226using executor_type = typename next_layer_type::executor_type; 19227``` 19228 19229[heading Description] 19230[endsect] 19231[section:get_executor http::icy_stream::get_executor] 19232[indexterm2 get_executor..http::icy_stream] 19233Get the executor associated with the object. 19234[heading Synopsis] 19235``` 19236executor_type 19237get_executor(); 19238``` 19239 19240[heading Description] 19241This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations. 19242[heading Return Value] 19243A copy of the executor that stream will use to dispatch handlers. 19244[endsect] 19245[section:icy_stream http::icy_stream::icy_stream] 19246[indexterm2 icy_stream..http::icy_stream] 19247``` 19248``[link beast.ref.boost__beast__http__icy_stream.icy_stream.overload1 icy_stream]``( 19249 icy_stream&&); 19250 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.icy_stream.overload1 more...]]`` 19251 19252``[link beast.ref.boost__beast__http__icy_stream.icy_stream.overload2 icy_stream]``( 19253 icy_stream const&); 19254 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.icy_stream.overload2 more...]]`` 19255 19256``` 19257Constructor. ``` 19258template< 19259 class... Args> 19260explicit 19261``[link beast.ref.boost__beast__http__icy_stream.icy_stream.overload3 icy_stream]``( 19262 Args&&... args); 19263 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.icy_stream.overload3 more...]]`` 19264``` 19265[section:overload1 http::icy_stream::icy_stream (1 of 3 overloads)] 19266 19267[heading Synopsis] 19268``` 19269icy_stream( 19270 icy_stream&&); 19271``` 19272 19273[heading Description] 19274[endsect] 19275[section:overload2 http::icy_stream::icy_stream (2 of 3 overloads)] 19276 19277[heading Synopsis] 19278``` 19279icy_stream( 19280 icy_stream const&); 19281``` 19282 19283[heading Description] 19284[endsect] 19285[section:overload3 http::icy_stream::icy_stream (3 of 3 overloads)] 19286Constructor. 19287[heading Synopsis] 19288``` 19289template< 19290 class... Args> 19291icy_stream( 19292 Args&&... args); 19293``` 19294 19295[heading Description] 19296Arguments, if any, are forwarded to the next layer's constructor. [endsect] 19297[endsect] 19298 19299[section:next_layer http::icy_stream::next_layer] 19300[indexterm2 next_layer..http::icy_stream] 19301Get a reference to the next layer. ``` 19302next_layer_type& 19303``[link beast.ref.boost__beast__http__icy_stream.next_layer.overload1 next_layer]``(); 19304 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.next_layer.overload1 more...]]`` 19305 19306next_layer_type const & 19307``[link beast.ref.boost__beast__http__icy_stream.next_layer.overload2 next_layer]``() const; 19308 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.next_layer.overload2 more...]]`` 19309``` 19310[section:overload1 http::icy_stream::next_layer (1 of 2 overloads)] 19311Get a reference to the next layer. 19312[heading Synopsis] 19313``` 19314next_layer_type& 19315next_layer(); 19316``` 19317 19318[heading Description] 19319This function returns a reference to the next layer in a stack of stream layers. 19320[heading Return Value] 19321A reference to the next layer in the stack of stream layers. 19322[endsect] 19323[section:overload2 http::icy_stream::next_layer (2 of 2 overloads)] 19324Get a reference to the next layer. 19325[heading Synopsis] 19326``` 19327next_layer_type const & 19328next_layer() const; 19329``` 19330 19331[heading Description] 19332This function returns a reference to the next layer in a stack of stream layers. 19333[heading Return Value] 19334A reference to the next layer in the stack of stream layers. 19335[endsect] 19336[endsect] 19337 19338[section:next_layer_type http::icy_stream::next_layer_type] 19339[indexterm2 next_layer_type..http::icy_stream] 19340The type of the next layer. 19341[heading Synopsis] 19342 19343``` 19344using next_layer_type = typename std::remove_reference< NextLayer >::type; 19345``` 19346 19347[heading Description] 19348[endsect] 19349[section:operator_eq_ http::icy_stream::operator=] 19350[indexterm2 operator=..http::icy_stream] 19351``` 19352icy_stream& 19353``[link beast.ref.boost__beast__http__icy_stream.operator_eq_.overload1 operator=]``( 19354 icy_stream&&); 19355 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.operator_eq_.overload1 more...]]`` 19356 19357icy_stream& 19358``[link beast.ref.boost__beast__http__icy_stream.operator_eq_.overload2 operator=]``( 19359 icy_stream const&); 19360 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.operator_eq_.overload2 more...]]`` 19361``` 19362[section:overload1 http::icy_stream::operator= (1 of 2 overloads)] 19363 19364[heading Synopsis] 19365``` 19366icy_stream& 19367operator=( 19368 icy_stream&&); 19369``` 19370 19371[heading Description] 19372[endsect] 19373[section:overload2 http::icy_stream::operator= (2 of 2 overloads)] 19374 19375[heading Synopsis] 19376``` 19377icy_stream& 19378operator=( 19379 icy_stream const&); 19380``` 19381 19382[heading Description] 19383[endsect] 19384[endsect] 19385 19386[section:read_some http::icy_stream::read_some] 19387[indexterm2 read_some..http::icy_stream] 19388Read some data from the stream. ``` 19389template< 19390 class __MutableBufferSequence__> 19391std::size_t 19392``[link beast.ref.boost__beast__http__icy_stream.read_some.overload1 read_some]``( 19393 MutableBufferSequence const& buffers); 19394 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.read_some.overload1 more...]]`` 19395 19396template< 19397 class __MutableBufferSequence__> 19398std::size_t 19399``[link beast.ref.boost__beast__http__icy_stream.read_some.overload2 read_some]``( 19400 MutableBufferSequence const& buffers, 19401 error_code& ec); 19402 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.read_some.overload2 more...]]`` 19403``` 19404[section:overload1 http::icy_stream::read_some (1 of 2 overloads)] 19405Read some data from the stream. 19406[heading Synopsis] 19407``` 19408template< 19409 class __MutableBufferSequence__> 19410std::size_t 19411read_some( 19412 MutableBufferSequence const& buffers); 19413``` 19414 19415[heading Description] 19416This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 19417[heading Parameters] 19418[table [[Name][Description]] 19419 [[`buffers`][ 19420 19421The buffers into which the data will be read. 19422 ]] 19423] 19424[heading Return Value] 19425The number of bytes read. 19426[heading Exceptions] 19427[table [[Type][Thrown On]] 19428 [[`system_error`][ 19429 19430Thrown on failure. 19431 ]] 19432] 19433[heading Remarks] 19434The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 19435[endsect] 19436[section:overload2 http::icy_stream::read_some (2 of 2 overloads)] 19437Read some data from the stream. 19438[heading Synopsis] 19439``` 19440template< 19441 class __MutableBufferSequence__> 19442std::size_t 19443read_some( 19444 MutableBufferSequence const& buffers, 19445 error_code& ec); 19446``` 19447 19448[heading Description] 19449This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 19450[heading Parameters] 19451[table [[Name][Description]] 19452 [[`buffers`][ 19453 19454The buffers into which the data will be read. 19455 ]] 19456 [[`ec`][ 19457 19458Set to indicate what error occurred, if any. 19459 ]] 19460] 19461[heading Return Value] 19462The number of bytes read. 19463[heading Remarks] 19464The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 19465[endsect] 19466[endsect] 19467 19468[section:write_some http::icy_stream::write_some] 19469[indexterm2 write_some..http::icy_stream] 19470Write some data to the stream. ``` 19471template< 19472 class __ConstBufferSequence__> 19473std::size_t 19474``[link beast.ref.boost__beast__http__icy_stream.write_some.overload1 write_some]``( 19475 ConstBufferSequence const& buffers); 19476 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.write_some.overload1 more...]]`` 19477 19478template< 19479 class __ConstBufferSequence__> 19480std::size_t 19481``[link beast.ref.boost__beast__http__icy_stream.write_some.overload2 write_some]``( 19482 ConstBufferSequence const& buffers, 19483 error_code& ec); 19484 ``[''''»''' [link beast.ref.boost__beast__http__icy_stream.write_some.overload2 more...]]`` 19485``` 19486[section:overload1 http::icy_stream::write_some (1 of 2 overloads)] 19487Write some data to the stream. 19488[heading Synopsis] 19489``` 19490template< 19491 class __ConstBufferSequence__> 19492std::size_t 19493write_some( 19494 ConstBufferSequence const& buffers); 19495``` 19496 19497[heading Description] 19498This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 19499[heading Parameters] 19500[table [[Name][Description]] 19501 [[`buffers`][ 19502 19503The data to be written. 19504 ]] 19505] 19506[heading Return Value] 19507The number of bytes written. 19508[heading Exceptions] 19509[table [[Type][Thrown On]] 19510 [[`system_error`][ 19511 19512Thrown on failure. 19513 ]] 19514] 19515[heading Remarks] 19516The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 19517[endsect] 19518[section:overload2 http::icy_stream::write_some (2 of 2 overloads)] 19519Write some data to the stream. 19520[heading Synopsis] 19521``` 19522template< 19523 class __ConstBufferSequence__> 19524std::size_t 19525write_some( 19526 ConstBufferSequence const& buffers, 19527 error_code& ec); 19528``` 19529 19530[heading Description] 19531This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 19532[heading Parameters] 19533[table [[Name][Description]] 19534 [[`buffers`][ 19535 19536The data to be written. 19537 ]] 19538 [[`ec`][ 19539 19540Set to indicate what error occurred, if any. 19541 ]] 19542] 19543[heading Return Value] 19544The number of bytes written. 19545[heading Remarks] 19546The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 19547[endsect] 19548[endsect] 19549 19550[section:icy_stream_dtor_ http::icy_stream::~icy_stream] 19551[indexterm2 ~icy_stream..http::icy_stream] 19552Destructor. 19553[heading Synopsis] 19554``` 19555~icy_stream(); 19556``` 19557 19558[heading Description] 19559The treatment of pending operations will be the same as that of the next layer. [endsect] 19560 19561 19562[endsect] 19563 19564 19565 19566[section:boost__beast__http__int_to_status http::int_to_status] 19567[indexterm1 http::int_to_status] 19568Converts the integer to a known status-code. 19569[heading Synopsis] 19570 19571Defined in header [include_file boost/beast/http/status.hpp] 19572 19573 19574 19575``` 19576status 19577int_to_status( 19578 unsigned v); 19579 19580``` 19581 19582[heading Description] 19583If the integer does not match a known status code, [link beast.ref.boost__beast__http__field `http::unknown`] is returned. 19584 19585 19586Convenience header [include_file boost/beast/http.hpp] 19587 19588[endsect] 19589[section:boost__beast__http__is_body http::is_body] 19590[indexterm1 http::is_body] 19591Determine if a type meets the ['Body] named requirements. 19592[heading Synopsis] 19593 19594Defined in header [include_file boost/beast/http/type_traits.hpp] 19595 19596 19597 19598``` 19599template< 19600 class T> 19601using is_body = ``['see-below]``; 19602``` 19603 19604[heading Description] 19605This alias template is `std::true_type` if `T` meets the requirements, otherwise it is `std::false_type`. 19606[heading Template Parameters] 19607[table [[Type][Description]] 19608 [[`T`][ 19609 19610The type to test. 19611 ]] 19612] 19613[heading Example] 19614 19615``` 19616 template<bool isRequest, class Body, class Fields> 19617 void check_body(message<isRequest, Body, Fields> const&) 19618 { 19619 static_assert(is_body<Body>::value, 19620 "Body type requirements not met"); 19621 } 19622``` 19623 19624 19625 19626Convenience header [include_file boost/beast/http.hpp] 19627 19628[endsect] 19629[section:boost__beast__http__is_body_reader http::is_body_reader] 19630[indexterm1 http::is_body_reader] 19631Determine if a type has a nested ['BodyReader]. 19632[heading Synopsis] 19633 19634Defined in header [include_file boost/beast/http/type_traits.hpp] 19635 19636 19637 19638``` 19639template< 19640 class T> 19641using is_body_reader = ``['see-below]``; 19642``` 19643 19644[heading Description] 19645This alias template is `std::true_type` when: 19646 19647* `T` has a nested type named `reader` 19648 19649 19650* `reader` meets the requirements of ['BodyReader]. 19651 19652[heading Template Parameters] 19653[table [[Type][Description]] 19654 [[`T`][ 19655 19656The body type to test. 19657 ]] 19658] 19659[heading Example] 19660 19661``` 19662 template<bool isRequest, class Body, class Fields> 19663 void check_can_parse(message<isRequest, Body, Fields>&) 19664 { 19665 static_assert(is_body_reader<Body>::value, 19666 "Cannot parse Body, no reader"); 19667 } 19668``` 19669 19670 19671 19672Convenience header [include_file boost/beast/http.hpp] 19673 19674[endsect] 19675[section:boost__beast__http__is_body_writer http::is_body_writer] 19676[indexterm1 http::is_body_writer] 19677Determine if a type has a nested ['BodyWriter]. 19678[heading Synopsis] 19679 19680Defined in header [include_file boost/beast/http/type_traits.hpp] 19681 19682 19683 19684``` 19685template< 19686 class T> 19687using is_body_writer = ``['see-below]``; 19688``` 19689 19690[heading Description] 19691This alias template is `std::true_type` when: 19692 19693* `T` has a nested type named `writer` 19694 19695 19696* `writer` meets the requirements of ['BodyWriter]. 19697 19698[heading Template Parameters] 19699[table [[Type][Description]] 19700 [[`T`][ 19701 19702The body type to test. 19703 ]] 19704] 19705[heading Example] 19706 19707``` 19708 template<bool isRequest, class Body, class Fields> 19709 void check_can_serialize(message<isRequest, Body, Fields> const&) 19710 { 19711 static_assert(is_body_writer<Body>::value, 19712 "Cannot serialize Body, no reader"); 19713 } 19714``` 19715 19716 19717 19718Convenience header [include_file boost/beast/http.hpp] 19719 19720[endsect] 19721[section:boost__beast__http__is_fields http::is_fields] 19722[indexterm1 http::is_fields] 19723Determine if a type meets the ['Fields] named requirements. 19724[heading Synopsis] 19725 19726Defined in header [include_file boost/beast/http/type_traits.hpp] 19727 19728 19729 19730``` 19731template< 19732 class T> 19733using is_fields = ``['see-below]``; 19734``` 19735 19736[heading Description] 19737This alias template is `std::true_type` if `T` meets the requirements, otherwise it is `std::false_type`. 19738[heading Template Parameters] 19739[table [[Type][Description]] 19740 [[`T`][ 19741 19742The type to test. 19743 ]] 19744] 19745[heading Example] 19746Use with `static_assert`: 19747``` 19748 template<bool isRequest, class Body, class Fields> 19749 void f(message<isRequest, Body, Fields> const&) 19750 { 19751 static_assert(is_fields<Fields>::value, 19752 "Fields type requirements not met"); 19753 ... 19754``` 19755Use with `std::enable_if` (SFINAE): 19756``` 19757 template<bool isRequest, class Body, class Fields> 19758 typename std::enable_if<is_fields<Fields>::value>::type 19759 f(message<isRequest, Body, Fields> const&); 19760``` 19761 19762 19763 19764Convenience header [include_file boost/beast/http.hpp] 19765 19766[endsect] 19767[section:boost__beast__http__is_mutable_body_writer http::is_mutable_body_writer] 19768[indexterm1 http::is_mutable_body_writer] 19769Determine if a type has a nested ['BodyWriter]. 19770[heading Synopsis] 19771 19772Defined in header [include_file boost/beast/http/type_traits.hpp] 19773 19774 19775 19776``` 19777template< 19778 class T> 19779using is_mutable_body_writer = ``['see-below]``; 19780``` 19781 19782[heading Description] 19783This alias template is `std::true_type` when: 19784 19785* `T` has a nested type named `writer` 19786 19787 19788* `writer` meets the requirements of ['BodyWriter]. 19789 19790[heading Template Parameters] 19791[table [[Type][Description]] 19792 [[`T`][ 19793 19794The body type to test. 19795 ]] 19796] 19797 19798 19799 19800Convenience header [include_file boost/beast/http.hpp] 19801 19802[endsect] 19803[section:boost__beast__http__make_chunk http::make_chunk] 19804[indexterm1 http::make_chunk] 19805Returns a [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`]. 19806[heading Synopsis] 19807 19808Defined in header [include_file boost/beast/http/chunk_encode.hpp] 19809 19810 19811 19812``` 19813template< 19814 class __ConstBufferSequence__, 19815 class... Args> 19816auto 19817make_chunk( 19818 ConstBufferSequence const& buffers, 19819 Args&&... args); 19820 19821``` 19822 19823[heading Description] 19824This functions constructs and returns a complete [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`] for a chunk body represented by the specified buffer sequence. 19825[heading Parameters] 19826[table [[Name][Description]] 19827 [[`buffers`][ 19828 19829The buffers representing the chunk body. 19830 ]] 19831 [[`args`][ 19832 19833Optional arguments passed to the [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`] constructor. 19834 ]] 19835] 19836[heading Remarks] 19837This function is provided as a notational convenience to omit specification of the class template arguments. 19838 19839 19840 19841Convenience header [include_file boost/beast/http.hpp] 19842 19843[endsect] 19844[section:boost__beast__http__make_chunk_last http::make_chunk_last] 19845[indexterm1 http::make_chunk_last] 19846Returns a [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. ``` 19847chunk_last< chunk_crlf > 19848``[link beast.ref.boost__beast__http__make_chunk_last.overload1 make_chunk_last]``(); 19849 ``[''''»''' [link beast.ref.boost__beast__http__make_chunk_last.overload1 more...]]`` 19850 19851template< 19852 class Trailer, 19853 class... Args> 19854chunk_last< Trailer > 19855``[link beast.ref.boost__beast__http__make_chunk_last.overload2 make_chunk_last]``( 19856 Trailer const& trailer, 19857 Args&&... args); 19858 ``[''''»''' [link beast.ref.boost__beast__http__make_chunk_last.overload2 more...]]`` 19859``` 19860[section:overload1 http::make_chunk_last (1 of 2 overloads)] 19861Returns a [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. 19862[heading Synopsis] 19863 19864Defined in header [include_file boost/beast/http/chunk_encode.hpp] 19865 19866 19867 19868``` 19869chunk_last< chunk_crlf > 19870make_chunk_last(); 19871 19872``` 19873 19874[heading Description] 19875[heading Remarks] 19876This function is provided as a notational convenience to omit specification of the class template arguments. 19877 19878 19879 19880Convenience header [include_file boost/beast/http.hpp] 19881 19882[endsect] 19883[section:overload2 http::make_chunk_last (2 of 2 overloads)] 19884Returns a [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. 19885[heading Synopsis] 19886 19887Defined in header [include_file boost/beast/http/chunk_encode.hpp] 19888 19889 19890 19891``` 19892template< 19893 class Trailer, 19894 class... Args> 19895chunk_last< Trailer > 19896make_chunk_last( 19897 Trailer const& trailer, 19898 Args&&... args); 19899 19900``` 19901 19902[heading Description] 19903This function construct and returns a complete [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`] for a last chunk containing the specified trailers. 19904[heading Parameters] 19905[table [[Name][Description]] 19906 [[`trailer`][ 19907 19908A ConstBufferSequence or 19909 ]] 19910] 19911[heading Remarks] 19912This function is provided as a notational convenience to omit specification of the class template arguments. 19913[heading Parameters] 19914[table [[Name][Description]] 19915 [[`args`][ 19916 19917Optional arguments passed to the [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`] constructor. 19918 ]] 19919] 19920 19921 19922 19923Convenience header [include_file boost/beast/http.hpp] 19924 19925[endsect] 19926[endsect] 19927 19928 19929 19930[section:boost__beast__http__message http::message] 19931A container for a complete HTTP message. 19932[heading Synopsis] 19933 19934Defined in header [include_file boost/beast/http/message.hpp] 19935 19936 19937 19938``` 19939template< 19940 bool isRequest, 19941 class __Body__, 19942 class __Fields__ = fields> 19943class message : 19944 public http::header< isRequest, Fields > 19945``` 19946[heading Types] 19947[table [[Name][Description]] 19948 [ 19949 [[link beast.ref.boost__beast__http__message.body_type [*body_type]]] 19950 [ 19951 The type providing the body traits. 19952 ] 19953 ] 19954 [ 19955 [[link beast.ref.boost__beast__http__message.fields_type [*fields_type]]] 19956 [ 19957 The type representing the fields. 19958 ] 19959 ] 19960 [ 19961 [[link beast.ref.boost__beast__http__message.header_type [*header_type]]] 19962 [ 19963 The base class used to hold the header portion of the message. 19964 ] 19965 ] 19966 [ 19967 [[link beast.ref.boost__beast__http__message.is_request [*is_request]]] 19968 [ 19969 Indicates if the header is a request or response. 19970 ] 19971 ] 19972] 19973[heading Member Functions] 19974[table [[Name][Description]] 19975 [ 19976 [[link beast.ref.boost__beast__http__message.base [*base]]] 19977 [ 19978 Returns the header portion of the message. 19979 ] 19980 ] 19981 [ 19982 [[link beast.ref.boost__beast__http__message.body [*body]]] 19983 [ 19984 Returns the body. 19985 ] 19986 ] 19987 [ 19988 [[link beast.ref.boost__beast__http__message.chunked [*chunked]]] 19989 [ 19990 Returns true if the chunked Transfer-Encoding is specified. 19991 19992 Set or clear the chunked Transfer-Encoding. 19993 ] 19994 ] 19995 [ 19996 [[link beast.ref.boost__beast__http__message.content_length [*content_length]]] 19997 [ 19998 Set or clear the Content-Length field. 19999 ] 20000 ] 20001 [ 20002 [[link beast.ref.boost__beast__http__message.has_content_length [*has_content_length]]] 20003 [ 20004 Returns true if the Content-Length field is present. 20005 ] 20006 ] 20007 [ 20008 [[link beast.ref.boost__beast__http__message.keep_alive [*keep_alive]]] 20009 [ 20010 Returns true if the message semantics indicate keep-alive. 20011 20012 Set the keep-alive message semantic option. 20013 ] 20014 ] 20015 [ 20016 [[link beast.ref.boost__beast__http__message.message [*message]]] 20017 [ 20018 Constructor. 20019 20020 Construct a message. 20021 ] 20022 ] 20023 [ 20024 [[link beast.ref.boost__beast__http__message.method [*method]]] 20025 [ 20026 Return the request-method verb. 20027 20028 Set the request-method. 20029 ] 20030 ] 20031 [ 20032 [[link beast.ref.boost__beast__http__message.method_string [*method_string]]] 20033 [ 20034 Return the request-method as a string. 20035 ] 20036 ] 20037 [ 20038 [[link beast.ref.boost__beast__http__message.need_eof [*need_eof]]] 20039 [ 20040 Returns true if the message semantics require an end of file. 20041 ] 20042 ] 20043 [ 20044 [[link beast.ref.boost__beast__http__message.operator_eq_ [*operator=]]] 20045 [ 20046 Assignment. 20047 ] 20048 ] 20049 [ 20050 [[link beast.ref.boost__beast__http__message.payload_size [*payload_size]]] 20051 [ 20052 Returns the payload size of the body in octets if possible. 20053 ] 20054 ] 20055 [ 20056 [[link beast.ref.boost__beast__http__message.prepare_payload [*prepare_payload]]] 20057 [ 20058 Prepare the message payload fields for the body. 20059 ] 20060 ] 20061 [ 20062 [[link beast.ref.boost__beast__http__message.reason [*reason]]] 20063 [ 20064 Return the response reason-phrase. 20065 20066 Set the response reason-phrase (deprecated) 20067 ] 20068 ] 20069 [ 20070 [[link beast.ref.boost__beast__http__message.result [*result]]] 20071 [ 20072 The response status-code result. 20073 20074 Set the response status-code. 20075 20076 Set the response status-code as an integer. 20077 ] 20078 ] 20079 [ 20080 [[link beast.ref.boost__beast__http__message.result_int [*result_int]]] 20081 [ 20082 The response status-code expressed as an integer. 20083 ] 20084 ] 20085 [ 20086 [[link beast.ref.boost__beast__http__message.target [*target]]] 20087 [ 20088 Returns the request-target string. 20089 20090 Set the request-target string. 20091 ] 20092 ] 20093 [ 20094 [[link beast.ref.boost__beast__http__message.version [*version]]] 20095 [ 20096 Return the HTTP-version. 20097 20098 Set the HTTP-version. 20099 ] 20100 ] 20101] 20102 20103[heading Description] 20104This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 20105A message can be a request or response, depending on the `isRequest` template argument value. Requests and responses have different types; functions may be overloaded based on the type if desired. 20106The `Body` template argument type determines the model used to read or write the content body of the message. 20107Newly constructed messages objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 20108[heading Template Parameters] 20109[table [[Type][Description]] 20110 [[`isRequest`][ 20111 20112`true` if this represents a request, or `false` if this represents a response. Some class data members are conditionally present depending on this value. 20113 ]] 20114 [[`Body`][ 20115 20116A type meeting the requirements of Body. 20117 ]] 20118 [[`Fields`][ 20119 20120The type of container used to hold the field value pairs. 20121 ]] 20122] 20123[section:base http::message::base] 20124[indexterm2 base..http::message] 20125Returns the header portion of the message. ``` 20126header_type const & 20127``[link beast.ref.boost__beast__http__message.base.overload1 base]``() const; 20128 ``[''''»''' [link beast.ref.boost__beast__http__message.base.overload1 more...]]`` 20129 20130header_type& 20131``[link beast.ref.boost__beast__http__message.base.overload2 base]``(); 20132 ``[''''»''' [link beast.ref.boost__beast__http__message.base.overload2 more...]]`` 20133``` 20134[section:overload1 http::message::base (1 of 2 overloads)] 20135Returns the header portion of the message. 20136[heading Synopsis] 20137``` 20138header_type const & 20139base() const; 20140``` 20141 20142[heading Description] 20143[endsect] 20144[section:overload2 http::message::base (2 of 2 overloads)] 20145Returns the header portion of the message. 20146[heading Synopsis] 20147``` 20148header_type& 20149base(); 20150``` 20151 20152[heading Description] 20153[endsect] 20154[endsect] 20155 20156[section:body http::message::body] 20157[indexterm2 body..http::message] 20158Returns the body. ``` 20159body_type::value_type& 20160``[link beast.ref.boost__beast__http__message.body.overload1 body]``(); 20161 ``[''''»''' [link beast.ref.boost__beast__http__message.body.overload1 more...]]`` 20162 20163body_type::value_type&& 20164``[link beast.ref.boost__beast__http__message.body.overload2 body]``(); 20165 ``[''''»''' [link beast.ref.boost__beast__http__message.body.overload2 more...]]`` 20166 20167body_type::value_type const & 20168``[link beast.ref.boost__beast__http__message.body.overload3 body]``() const; 20169 ``[''''»''' [link beast.ref.boost__beast__http__message.body.overload3 more...]]`` 20170``` 20171[section:overload1 http::message::body (1 of 3 overloads)] 20172Returns the body. 20173[heading Synopsis] 20174``` 20175body_type::value_type& 20176body(); 20177``` 20178 20179[heading Description] 20180[endsect] 20181[section:overload2 http::message::body (2 of 3 overloads)] 20182Returns the body. 20183[heading Synopsis] 20184``` 20185body_type::value_type&& 20186body(); 20187``` 20188 20189[heading Description] 20190[endsect] 20191[section:overload3 http::message::body (3 of 3 overloads)] 20192Returns the body. 20193[heading Synopsis] 20194``` 20195body_type::value_type const & 20196body() const; 20197``` 20198 20199[heading Description] 20200[endsect] 20201[endsect] 20202 20203[section:body_type http::message::body_type] 20204[indexterm2 body_type..http::message] 20205The type providing the body traits. 20206[heading Synopsis] 20207 20208``` 20209using body_type = Body; 20210``` 20211 20212[heading Description] 20213The [link beast.ref.boost__beast__http__message.body `http::message::body`] member will be of type `body_type::value_type`. [endsect] 20214[section:chunked http::message::chunked] 20215[indexterm2 chunked..http::message] 20216Returns `true` if the chunked Transfer-Encoding is specified. ``` 20217bool 20218``[link beast.ref.boost__beast__http__message.chunked.overload1 chunked]``() const; 20219 ``[''''»''' [link beast.ref.boost__beast__http__message.chunked.overload1 more...]]`` 20220 20221``` 20222Set or clear the chunked Transfer-Encoding. ``` 20223void 20224``[link beast.ref.boost__beast__http__message.chunked.overload2 chunked]``( 20225 bool value); 20226 ``[''''»''' [link beast.ref.boost__beast__http__message.chunked.overload2 more...]]`` 20227``` 20228[section:overload1 http::message::chunked (1 of 2 overloads)] 20229Returns `true` if the chunked Transfer-Encoding is specified. 20230[heading Synopsis] 20231``` 20232bool 20233chunked() const; 20234``` 20235 20236[heading Description] 20237[endsect] 20238[section:overload2 http::message::chunked (2 of 2 overloads)] 20239Set or clear the chunked Transfer-Encoding. 20240[heading Synopsis] 20241``` 20242void 20243chunked( 20244 bool value); 20245``` 20246 20247[heading Description] 20248This function will set or remove the "chunked" transfer encoding as the last item in the list of encodings in the field. 20249If the result of removing the chunked token results in an empty string, the field is erased. 20250The Content-Length field is erased unconditionally. [endsect] 20251[endsect] 20252 20253[section:content_length http::message::content_length] 20254[indexterm2 content_length..http::message] 20255Set or clear the Content-Length field. 20256[heading Synopsis] 20257``` 20258void 20259content_length( 20260 boost::optional< std::uint64_t > const& value); 20261``` 20262 20263[heading Description] 20264This function adjusts the Content-Length field as follows: 20265 20266* If `value` specifies a value, the Content-Length field is set to the value. Otherwise 20267 20268 20269* The Content-Length field is erased. 20270 20271If "chunked" token appears as the last item in the Transfer-Encoding field it is unconditionally removed. 20272[heading Parameters] 20273[table [[Name][Description]] 20274 [[`value`][ 20275 20276The value to set for Content-Length. 20277 ]] 20278] 20279[endsect] 20280[section:fields_type http::message::fields_type] 20281(Inherited from `http::header`) 20282 20283[indexterm2 fields_type..http::message] 20284The type representing the fields. 20285[heading Synopsis] 20286 20287``` 20288using fields_type = Fields; 20289``` 20290 20291[heading Description] 20292[endsect] 20293[section:has_content_length http::message::has_content_length] 20294[indexterm2 has_content_length..http::message] 20295Returns `true` if the Content-Length field is present. 20296[heading Synopsis] 20297``` 20298bool 20299has_content_length() const; 20300``` 20301 20302[heading Description] 20303This function inspects the fields and returns `true` if the Content-Length field is present. The properties of the body are not checked, this only looks for the field. [endsect] 20304[section:header_type http::message::header_type] 20305[indexterm2 header_type..http::message] 20306The base class used to hold the header portion of the message. 20307[heading Synopsis] 20308 20309``` 20310using header_type = header< isRequest, Fields >; 20311``` 20312[heading Types] 20313[table [[Name][Description]] 20314 [ 20315 [[link beast.ref.boost__beast__http__header.fields_type [*fields_type]]] 20316 [ 20317 The type representing the fields. 20318 ] 20319 ] 20320 [ 20321 [[link beast.ref.boost__beast__http__header.is_request [*is_request]]] 20322 [ 20323 Indicates if the header is a request or response. 20324 ] 20325 ] 20326] 20327[heading Member Functions] 20328[table [[Name][Description]] 20329 [ 20330 [[link beast.ref.boost__beast__http__header.header [*header]]] 20331 [ 20332 Constructor. 20333 ] 20334 ] 20335 [ 20336 [[link beast.ref.boost__beast__http__header.method [*method]]] 20337 [ 20338 Return the request-method verb. 20339 20340 Set the request-method. 20341 ] 20342 ] 20343 [ 20344 [[link beast.ref.boost__beast__http__header.method_string [*method_string]]] 20345 [ 20346 Return the request-method as a string. 20347 ] 20348 ] 20349 [ 20350 [[link beast.ref.boost__beast__http__header.operator_eq_ [*operator=]]] 20351 [ 20352 Assignment. 20353 ] 20354 ] 20355 [ 20356 [[link beast.ref.boost__beast__http__header.reason [*reason]]] 20357 [ 20358 Return the response reason-phrase. 20359 20360 Set the response reason-phrase (deprecated) 20361 ] 20362 ] 20363 [ 20364 [[link beast.ref.boost__beast__http__header.result [*result]]] 20365 [ 20366 The response status-code result. 20367 20368 Set the response status-code. 20369 20370 Set the response status-code as an integer. 20371 ] 20372 ] 20373 [ 20374 [[link beast.ref.boost__beast__http__header.result_int [*result_int]]] 20375 [ 20376 The response status-code expressed as an integer. 20377 ] 20378 ] 20379 [ 20380 [[link beast.ref.boost__beast__http__header.target [*target]]] 20381 [ 20382 Returns the request-target string. 20383 20384 Set the request-target string. 20385 ] 20386 ] 20387 [ 20388 [[link beast.ref.boost__beast__http__header.version [*version]]] 20389 [ 20390 Return the HTTP-version. 20391 20392 Set the HTTP-version. 20393 ] 20394 ] 20395] 20396This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 20397Newly constructed header objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 20398A `header` includes the start-line and header-fields. 20399[heading Description] 20400[endsect] 20401[section:is_request http::message::is_request] 20402(Inherited from `http::header`) 20403 20404[indexterm2 is_request..http::message] 20405Indicates if the header is a request or response. 20406[heading Synopsis] 20407 20408``` 20409using is_request = std::integral_constant< bool, isRequest >; 20410``` 20411 20412[heading Description] 20413[endsect] 20414[section:keep_alive http::message::keep_alive] 20415[indexterm2 keep_alive..http::message] 20416Returns `true` if the message semantics indicate keep-alive. ``` 20417bool 20418``[link beast.ref.boost__beast__http__message.keep_alive.overload1 keep_alive]``() const; 20419 ``[''''»''' [link beast.ref.boost__beast__http__message.keep_alive.overload1 more...]]`` 20420 20421``` 20422Set the keep-alive message semantic option. ``` 20423void 20424``[link beast.ref.boost__beast__http__message.keep_alive.overload2 keep_alive]``( 20425 bool value); 20426 ``[''''»''' [link beast.ref.boost__beast__http__message.keep_alive.overload2 more...]]`` 20427``` 20428[section:overload1 http::message::keep_alive (1 of 2 overloads)] 20429Returns `true` if the message semantics indicate keep-alive. 20430[heading Synopsis] 20431``` 20432bool 20433keep_alive() const; 20434``` 20435 20436[heading Description] 20437The value depends on the version in the message, which must be set to the final value before this function is called or else the return value is unreliable. [endsect] 20438[section:overload2 http::message::keep_alive (2 of 2 overloads)] 20439Set the keep-alive message semantic option. 20440[heading Synopsis] 20441``` 20442void 20443keep_alive( 20444 bool value); 20445``` 20446 20447[heading Description] 20448This function adjusts the Connection field to indicate whether or not the connection should be kept open after the corresponding response. The result depends on the version set on the message, which must be set to the final value before making this call. 20449[heading Parameters] 20450[table [[Name][Description]] 20451 [[`value`][ 20452 20453`true` if the connection should persist. 20454 ]] 20455] 20456[endsect] 20457[endsect] 20458 20459[section:message http::message::message] 20460[indexterm2 message..http::message] 20461Constructor. ``` 20462``[link beast.ref.boost__beast__http__message.message.overload1 message]``(); 20463 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload1 more...]]`` 20464 20465``[link beast.ref.boost__beast__http__message.message.overload2 message]``( 20466 message&&); 20467 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload2 more...]]`` 20468 20469``[link beast.ref.boost__beast__http__message.message.overload3 message]``( 20470 message const&); 20471 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload3 more...]]`` 20472 20473template< 20474 class... BodyArgs> 20475explicit 20476``[link beast.ref.boost__beast__http__message.message.overload4 message]``( 20477 header_type&& h, 20478 BodyArgs&&... body_args); 20479 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload4 more...]]`` 20480 20481template< 20482 class... BodyArgs> 20483explicit 20484``[link beast.ref.boost__beast__http__message.message.overload5 message]``( 20485 header_type const& h, 20486 BodyArgs&&... body_args); 20487 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload5 more...]]`` 20488 20489``[link beast.ref.boost__beast__http__message.message.overload6 message]``( 20490 verb method, 20491 string_view target, 20492 unsigned version); 20493 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload6 more...]]`` 20494 20495template< 20496 class BodyArg> 20497``[link beast.ref.boost__beast__http__message.message.overload7 message]``( 20498 verb method, 20499 string_view target, 20500 unsigned version, 20501 BodyArg&& body_arg); 20502 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload7 more...]]`` 20503 20504template< 20505 class BodyArg, 20506 class FieldsArg> 20507``[link beast.ref.boost__beast__http__message.message.overload8 message]``( 20508 verb method, 20509 string_view target, 20510 unsigned version, 20511 BodyArg&& body_arg, 20512 FieldsArg&& fields_arg); 20513 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload8 more...]]`` 20514 20515``[link beast.ref.boost__beast__http__message.message.overload9 message]``( 20516 status result, 20517 unsigned version); 20518 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload9 more...]]`` 20519 20520template< 20521 class BodyArg> 20522``[link beast.ref.boost__beast__http__message.message.overload10 message]``( 20523 status result, 20524 unsigned version, 20525 BodyArg&& body_arg); 20526 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload10 more...]]`` 20527 20528template< 20529 class BodyArg, 20530 class FieldsArg> 20531``[link beast.ref.boost__beast__http__message.message.overload11 message]``( 20532 status result, 20533 unsigned version, 20534 BodyArg&& body_arg, 20535 FieldsArg&& fields_arg); 20536 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload11 more...]]`` 20537 20538explicit 20539``[link beast.ref.boost__beast__http__message.message.overload12 message]``( 20540 std::piecewise_construct_t); 20541 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload12 more...]]`` 20542 20543``` 20544Construct a message. ``` 20545template< 20546 class... BodyArgs> 20547``[link beast.ref.boost__beast__http__message.message.overload13 message]``( 20548 std::piecewise_construct_t, 20549 std::tuple< BodyArgs... > body_args); 20550 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload13 more...]]`` 20551 20552template< 20553 class... BodyArgs, 20554 class... FieldsArgs> 20555``[link beast.ref.boost__beast__http__message.message.overload14 message]``( 20556 std::piecewise_construct_t, 20557 std::tuple< BodyArgs... > body_args, 20558 std::tuple< FieldsArgs... > fields_args); 20559 ``[''''»''' [link beast.ref.boost__beast__http__message.message.overload14 more...]]`` 20560``` 20561[section:overload1 http::message::message (1 of 14 overloads)] 20562Constructor. 20563[heading Synopsis] 20564``` 20565message(); 20566``` 20567 20568[heading Description] 20569[endsect] 20570[section:overload2 http::message::message (2 of 14 overloads)] 20571Constructor. 20572[heading Synopsis] 20573``` 20574message( 20575 message&&); 20576``` 20577 20578[heading Description] 20579[endsect] 20580[section:overload3 http::message::message (3 of 14 overloads)] 20581Constructor. 20582[heading Synopsis] 20583``` 20584message( 20585 message const&); 20586``` 20587 20588[heading Description] 20589[endsect] 20590[section:overload4 http::message::message (4 of 14 overloads)] 20591Constructor. 20592[heading Synopsis] 20593``` 20594template< 20595 class... BodyArgs> 20596message( 20597 header_type&& h, 20598 BodyArgs&&... body_args); 20599``` 20600 20601[heading Description] 20602[heading Parameters] 20603[table [[Name][Description]] 20604 [[`h`][ 20605 20606The header to move construct from. 20607 ]] 20608 [[`body_args`][ 20609 20610Optional arguments forwarded to the `body` constructor. 20611 ]] 20612] 20613[endsect] 20614[section:overload5 http::message::message (5 of 14 overloads)] 20615Constructor. 20616[heading Synopsis] 20617``` 20618template< 20619 class... BodyArgs> 20620message( 20621 header_type const& h, 20622 BodyArgs&&... body_args); 20623``` 20624 20625[heading Description] 20626[heading Parameters] 20627[table [[Name][Description]] 20628 [[`h`][ 20629 20630The header to copy construct from. 20631 ]] 20632 [[`body_args`][ 20633 20634Optional arguments forwarded to the `body` constructor. 20635 ]] 20636] 20637[endsect] 20638[section:overload6 http::message::message (6 of 14 overloads)] 20639Constructor. 20640[heading Synopsis] 20641``` 20642message( 20643 verb method, 20644 string_view target, 20645 unsigned version); 20646``` 20647 20648[heading Description] 20649[heading Parameters] 20650[table [[Name][Description]] 20651 [[`method`][ 20652 20653The request-method to use. 20654 ]] 20655 [[`target`][ 20656 20657The request-target. 20658 ]] 20659 [[`version`][ 20660 20661The HTTP-version. 20662 ]] 20663] 20664[heading Remarks] 20665This function is only available when `isRequest == true`. 20666[endsect] 20667[section:overload7 http::message::message (7 of 14 overloads)] 20668Constructor. 20669[heading Synopsis] 20670``` 20671template< 20672 class BodyArg> 20673message( 20674 verb method, 20675 string_view target, 20676 unsigned version, 20677 BodyArg&& body_arg); 20678``` 20679 20680[heading Description] 20681[heading Parameters] 20682[table [[Name][Description]] 20683 [[`method`][ 20684 20685The request-method to use. 20686 ]] 20687 [[`target`][ 20688 20689The request-target. 20690 ]] 20691 [[`version`][ 20692 20693The HTTP-version. 20694 ]] 20695 [[`body_arg`][ 20696 20697An argument forwarded to the `body` constructor. 20698 ]] 20699] 20700[heading Remarks] 20701This function is only available when `isRequest == true`. 20702[endsect] 20703[section:overload8 http::message::message (8 of 14 overloads)] 20704Constructor. 20705[heading Synopsis] 20706``` 20707template< 20708 class BodyArg, 20709 class FieldsArg> 20710message( 20711 verb method, 20712 string_view target, 20713 unsigned version, 20714 BodyArg&& body_arg, 20715 FieldsArg&& fields_arg); 20716``` 20717 20718[heading Description] 20719[heading Parameters] 20720[table [[Name][Description]] 20721 [[`method`][ 20722 20723The request-method to use. 20724 ]] 20725 [[`target`][ 20726 20727The request-target. 20728 ]] 20729 [[`version`][ 20730 20731The HTTP-version. 20732 ]] 20733 [[`body_arg`][ 20734 20735An argument forwarded to the `body` constructor. 20736 ]] 20737 [[`fields_arg`][ 20738 20739An argument forwarded to the `Fields` constructor. 20740 ]] 20741] 20742[heading Remarks] 20743This function is only available when `isRequest == true`. 20744[endsect] 20745[section:overload9 http::message::message (9 of 14 overloads)] 20746Constructor. 20747[heading Synopsis] 20748``` 20749message( 20750 status result, 20751 unsigned version); 20752``` 20753 20754[heading Description] 20755[heading Parameters] 20756[table [[Name][Description]] 20757 [[`result`][ 20758 20759The status-code for the response. 20760 ]] 20761 [[`version`][ 20762 20763The HTTP-version. 20764 ]] 20765] 20766[heading Remarks] 20767This member is only available when `isRequest == false`. 20768[endsect] 20769[section:overload10 http::message::message (10 of 14 overloads)] 20770Constructor. 20771[heading Synopsis] 20772``` 20773template< 20774 class BodyArg> 20775message( 20776 status result, 20777 unsigned version, 20778 BodyArg&& body_arg); 20779``` 20780 20781[heading Description] 20782[heading Parameters] 20783[table [[Name][Description]] 20784 [[`result`][ 20785 20786The status-code for the response. 20787 ]] 20788 [[`version`][ 20789 20790The HTTP-version. 20791 ]] 20792 [[`body_arg`][ 20793 20794An argument forwarded to the `body` constructor. 20795 ]] 20796] 20797[heading Remarks] 20798This member is only available when `isRequest == false`. 20799[endsect] 20800[section:overload11 http::message::message (11 of 14 overloads)] 20801Constructor. 20802[heading Synopsis] 20803``` 20804template< 20805 class BodyArg, 20806 class FieldsArg> 20807message( 20808 status result, 20809 unsigned version, 20810 BodyArg&& body_arg, 20811 FieldsArg&& fields_arg); 20812``` 20813 20814[heading Description] 20815[heading Parameters] 20816[table [[Name][Description]] 20817 [[`result`][ 20818 20819The status-code for the response. 20820 ]] 20821 [[`version`][ 20822 20823The HTTP-version. 20824 ]] 20825 [[`body_arg`][ 20826 20827An argument forwarded to the `body` constructor. 20828 ]] 20829 [[`fields_arg`][ 20830 20831An argument forwarded to the `Fields` base class constructor. 20832 ]] 20833] 20834[heading Remarks] 20835This member is only available when `isRequest == false`. 20836[endsect] 20837[section:overload12 http::message::message (12 of 14 overloads)] 20838Constructor. 20839[heading Synopsis] 20840``` 20841message( 20842 std::piecewise_construct_t); 20843``` 20844 20845[heading Description] 20846The header and body are default-constructed. [endsect] 20847[section:overload13 http::message::message (13 of 14 overloads)] 20848Construct a message. 20849[heading Synopsis] 20850``` 20851template< 20852 class... BodyArgs> 20853message( 20854 std::piecewise_construct_t, 20855 std::tuple< BodyArgs... > body_args); 20856``` 20857 20858[heading Description] 20859[heading Parameters] 20860[table [[Name][Description]] 20861 [[`body_args`][ 20862 20863A tuple forwarded as a parameter pack to the body constructor. 20864 ]] 20865] 20866[endsect] 20867[section:overload14 http::message::message (14 of 14 overloads)] 20868Construct a message. 20869[heading Synopsis] 20870``` 20871template< 20872 class... BodyArgs, 20873 class... FieldsArgs> 20874message( 20875 std::piecewise_construct_t, 20876 std::tuple< BodyArgs... > body_args, 20877 std::tuple< FieldsArgs... > fields_args); 20878``` 20879 20880[heading Description] 20881[heading Parameters] 20882[table [[Name][Description]] 20883 [[`body_args`][ 20884 20885A tuple forwarded as a parameter pack to the body constructor. 20886 ]] 20887 [[`fields_args`][ 20888 20889A tuple forwarded as a parameter pack to the `Fields` constructor. 20890 ]] 20891] 20892[endsect] 20893[endsect] 20894 20895[section:method http::message::method] 20896[indexterm2 method..http::message] 20897Return the request-method verb. ``` 20898verb 20899``[link beast.ref.boost__beast__http__message.method.overload1 method]``() const; 20900 ``[''''»''' [link beast.ref.boost__beast__http__message.method.overload1 more...]]`` 20901 20902``` 20903Set the request-method. ``` 20904void 20905``[link beast.ref.boost__beast__http__message.method.overload2 method]``( 20906 verb v); 20907 ``[''''»''' [link beast.ref.boost__beast__http__message.method.overload2 more...]]`` 20908``` 20909[section:overload1 http::message::method (1 of 2 overloads)] 20910(Inherited from `http::header`) 20911 20912Return the request-method verb. 20913[heading Synopsis] 20914``` 20915verb 20916method() const; 20917``` 20918 20919[heading Description] 20920If the request-method is not one of the recognized verbs, [link beast.ref.boost__beast__http__field `http::unknown`] is returned. Callers may use [link beast.ref.boost__beast__http__header.method_string `http::header::method_string`] to retrieve the exact text. 20921[heading Remarks] 20922This function is only available when `isRequest == true`. 20923[heading See Also] 20924[link beast.ref.boost__beast__http__header.method_string `http::header::method_string`] 20925[endsect] 20926[section:overload2 http::message::method (2 of 2 overloads)] 20927(Inherited from `http::header`) 20928 20929Set the request-method. 20930[heading Synopsis] 20931``` 20932void 20933method( 20934 verb v); 20935``` 20936 20937[heading Description] 20938This function will set the method for requests to a known verb. 20939[heading Parameters] 20940[table [[Name][Description]] 20941 [[`v`][ 20942 20943The request method verb to set. This may not be [link beast.ref.boost__beast__http__field `http::unknown`]. 20944 ]] 20945] 20946[heading Exceptions] 20947[table [[Type][Thrown On]] 20948 [[`std::invalid_argument`][ 20949 20950when `v == verb::unknown`. 20951 ]] 20952] 20953[heading Remarks] 20954This function is only available when `isRequest == true`. 20955[endsect] 20956[endsect] 20957 20958[section:method_string http::message::method_string] 20959[indexterm2 method_string..http::message] 20960Return the request-method as a string. ``` 20961string_view 20962``[link beast.ref.boost__beast__http__message.method_string.overload1 method_string]``() const; 20963 ``[''''»''' [link beast.ref.boost__beast__http__message.method_string.overload1 more...]]`` 20964 20965void 20966``[link beast.ref.boost__beast__http__message.method_string.overload2 method_string]``( 20967 string_view s); 20968 ``[''''»''' [link beast.ref.boost__beast__http__message.method_string.overload2 more...]]`` 20969``` 20970[section:overload1 http::message::method_string (1 of 2 overloads)] 20971(Inherited from `http::header`) 20972 20973Return the request-method as a string. 20974[heading Synopsis] 20975``` 20976string_view 20977method_string() const; 20978``` 20979 20980[heading Description] 20981[heading Remarks] 20982This function is only available when `isRequest == true`. 20983[heading See Also] 20984[link beast.ref.boost__beast__http__header.method `http::header::method`] 20985[endsect] 20986[section:overload2 http::message::method_string (2 of 2 overloads)] 20987(Inherited from `http::header`) 20988 20989Set the request-method. 20990[heading Synopsis] 20991``` 20992void 20993method_string( 20994 string_view s); 20995``` 20996 20997[heading Description] 20998This function will set the request-method a known verb if the string matches, otherwise it will store a copy of the passed string. 20999[heading Parameters] 21000[table [[Name][Description]] 21001 [[`s`][ 21002 21003A string representing the request-method. 21004 ]] 21005] 21006[heading Remarks] 21007This function is only available when `isRequest == true`. 21008[endsect] 21009[endsect] 21010 21011[section:need_eof http::message::need_eof] 21012[indexterm2 need_eof..http::message] 21013Returns `true` if the message semantics require an end of file. 21014[heading Synopsis] 21015``` 21016bool 21017need_eof() const; 21018``` 21019 21020[heading Description] 21021For HTTP requests, this function returns the logical NOT of a call to [link beast.ref.boost__beast__http__message.keep_alive `http::message::keep_alive`]. 21022For HTTP responses, this function returns the logical NOT of a call to [link beast.ref.boost__beast__http__message.keep_alive `http::message::keep_alive`] if any of the following are true: 21023 21024* [link beast.ref.boost__beast__http__message.has_content_length `http::message::has_content_length`] would return `true` 21025 21026 21027* [link beast.ref.boost__beast__http__message.chunked `http::message::chunked`] would return `true` 21028 21029 21030* [link beast.ref.boost__beast__http__header.result `http::header::result`] returns [link beast.ref.boost__beast__http__status `http::no_content`] 21031 21032 21033* [link beast.ref.boost__beast__http__header.result `http::header::result`] returns [link beast.ref.boost__beast__http__status `http::not_modified`] 21034 21035 21036* [link beast.ref.boost__beast__http__header.result `http::header::result`] returns any informational status class (100 to 199) 21037 21038Otherwise, the function returns `true`. 21039[heading See Also] 21040[@https://tools.ietf.org/html/rfc7230#section-3.3 https://tools.ietf.org/html/rfc7230#section-3.3] 21041[endsect] 21042[section:operator_eq_ http::message::operator=] 21043[indexterm2 operator=..http::message] 21044Assignment. ``` 21045message& 21046``[link beast.ref.boost__beast__http__message.operator_eq_.overload1 operator=]``( 21047 message&&); 21048 ``[''''»''' [link beast.ref.boost__beast__http__message.operator_eq_.overload1 more...]]`` 21049 21050message& 21051``[link beast.ref.boost__beast__http__message.operator_eq_.overload2 operator=]``( 21052 message const&); 21053 ``[''''»''' [link beast.ref.boost__beast__http__message.operator_eq_.overload2 more...]]`` 21054``` 21055[section:overload1 http::message::operator= (1 of 2 overloads)] 21056Assignment. 21057[heading Synopsis] 21058``` 21059message& 21060operator=( 21061 message&&); 21062``` 21063 21064[heading Description] 21065[endsect] 21066[section:overload2 http::message::operator= (2 of 2 overloads)] 21067Assignment. 21068[heading Synopsis] 21069``` 21070message& 21071operator=( 21072 message const&); 21073``` 21074 21075[heading Description] 21076[endsect] 21077[endsect] 21078 21079[section:payload_size http::message::payload_size] 21080[indexterm2 payload_size..http::message] 21081Returns the payload size of the body in octets if possible. 21082[heading Synopsis] 21083``` 21084boost::optional< std::uint64_t > 21085payload_size() const; 21086``` 21087 21088[heading Description] 21089This function invokes the ['Body] algorithm to measure the number of octets in the serialized body container. If there is no body, this will return zero. Otherwise, if the body exists but is not known ahead of time, `boost::none` is returned (usually indicating that a chunked Transfer-Encoding will be used). 21090[heading Remarks] 21091The value of the Content-Length field in the message is not inspected. 21092[endsect] 21093[section:prepare_payload http::message::prepare_payload] 21094[indexterm2 prepare_payload..http::message] 21095Prepare the message payload fields for the body. 21096[heading Synopsis] 21097``` 21098void 21099prepare_payload(); 21100``` 21101 21102[heading Description] 21103This function will adjust the Content-Length and Transfer-Encoding field values based on the properties of the body. 21104[heading Example] 21105 21106``` 21107 request<string_body> req{verb::post, "/"}; 21108 req.set(field::user_agent, "Beast"); 21109 req.body() = "Hello, world!"; 21110 req.prepare_payload(); 21111``` 21112[endsect] 21113[section:reason http::message::reason] 21114[indexterm2 reason..http::message] 21115Return the response reason-phrase. ``` 21116string_view 21117``[link beast.ref.boost__beast__http__message.reason.overload1 reason]``() const; 21118 ``[''''»''' [link beast.ref.boost__beast__http__message.reason.overload1 more...]]`` 21119 21120``` 21121Set the response reason-phrase (deprecated) ``` 21122void 21123``[link beast.ref.boost__beast__http__message.reason.overload2 reason]``( 21124 string_view s); 21125 ``[''''»''' [link beast.ref.boost__beast__http__message.reason.overload2 more...]]`` 21126``` 21127[section:overload1 http::message::reason (1 of 2 overloads)] 21128(Inherited from `http::header`) 21129 21130Return the response reason-phrase. 21131[heading Synopsis] 21132``` 21133string_view 21134reason() const; 21135``` 21136 21137[heading Description] 21138The reason-phrase is obsolete as of rfc7230. 21139[heading Remarks] 21140This function is only available when `isRequest == false`. 21141[endsect] 21142[section:overload2 http::message::reason (2 of 2 overloads)] 21143(Inherited from `http::header`) 21144 21145Set the response reason-phrase (deprecated) 21146[heading Synopsis] 21147``` 21148void 21149reason( 21150 string_view s); 21151``` 21152 21153[heading Description] 21154This function sets a custom reason-phrase to a copy of the string passed in. Normally it is not necessary to set the reason phrase on an outgoing response object; the implementation will automatically use the standard reason text for the corresponding status code. 21155To clear a previously set custom phrase, pass an empty string. This will restore the default standard reason text based on the status code used when serializing. 21156The reason-phrase is obsolete as of rfc7230. 21157[heading Parameters] 21158[table [[Name][Description]] 21159 [[`s`][ 21160 21161The string to use for the reason-phrase. 21162 ]] 21163] 21164[heading Remarks] 21165This function is only available when `isRequest == false`. 21166[endsect] 21167[endsect] 21168 21169[section:result http::message::result] 21170[indexterm2 result..http::message] 21171The response status-code result. ``` 21172status 21173``[link beast.ref.boost__beast__http__message.result.overload1 result]``() const; 21174 ``[''''»''' [link beast.ref.boost__beast__http__message.result.overload1 more...]]`` 21175 21176``` 21177Set the response status-code. ``` 21178void 21179``[link beast.ref.boost__beast__http__message.result.overload2 result]``( 21180 status v); 21181 ``[''''»''' [link beast.ref.boost__beast__http__message.result.overload2 more...]]`` 21182 21183``` 21184Set the response status-code as an integer. ``` 21185void 21186``[link beast.ref.boost__beast__http__message.result.overload3 result]``( 21187 unsigned v); 21188 ``[''''»''' [link beast.ref.boost__beast__http__message.result.overload3 more...]]`` 21189``` 21190[section:overload1 http::message::result (1 of 3 overloads)] 21191(Inherited from `http::header`) 21192 21193The response status-code result. 21194[heading Synopsis] 21195``` 21196status 21197result() const; 21198``` 21199 21200[heading Description] 21201If the actual status code is not a known code, this function returns [link beast.ref.boost__beast__http__field `http::unknown`]. Use [link beast.ref.boost__beast__http__header.result_int `http::header::result_int`] to return the raw status code as a number. 21202[heading Remarks] 21203This member is only available when `isRequest == false`. 21204[endsect] 21205[section:overload2 http::message::result (2 of 3 overloads)] 21206(Inherited from `http::header`) 21207 21208Set the response status-code. 21209[heading Synopsis] 21210``` 21211void 21212result( 21213 status v); 21214``` 21215 21216[heading Description] 21217[heading Parameters] 21218[table [[Name][Description]] 21219 [[`v`][ 21220 21221The code to set. 21222 ]] 21223] 21224[heading Remarks] 21225This member is only available when `isRequest == false`. 21226[endsect] 21227[section:overload3 http::message::result (3 of 3 overloads)] 21228(Inherited from `http::header`) 21229 21230Set the response status-code as an integer. 21231[heading Synopsis] 21232``` 21233void 21234result( 21235 unsigned v); 21236``` 21237 21238[heading Description] 21239This sets the status code to the exact number passed in. If the number does not correspond to one of the known status codes, the function [link beast.ref.boost__beast__http__header.result `http::header::result`] will return [link beast.ref.boost__beast__http__field `http::unknown`]. Use [link beast.ref.boost__beast__http__header.result_int `http::header::result_int`] to obtain the original raw status-code. 21240[heading Parameters] 21241[table [[Name][Description]] 21242 [[`v`][ 21243 21244The status-code integer to set. 21245 ]] 21246] 21247[heading Exceptions] 21248[table [[Type][Thrown On]] 21249 [[`std::invalid_argument`][ 21250 21251if `v > 999`. 21252 ]] 21253] 21254[endsect] 21255[endsect] 21256 21257[section:result_int http::message::result_int] 21258(Inherited from `http::header`) 21259 21260[indexterm2 result_int..http::message] 21261The response status-code expressed as an integer. 21262[heading Synopsis] 21263``` 21264unsigned 21265result_int() const; 21266``` 21267 21268[heading Description] 21269This returns the raw status code as an integer, even when that code is not in the list of known status codes. 21270[heading Remarks] 21271This member is only available when `isRequest == false`. 21272[endsect] 21273[section:target http::message::target] 21274[indexterm2 target..http::message] 21275Returns the request-target string. ``` 21276string_view 21277``[link beast.ref.boost__beast__http__message.target.overload1 target]``() const; 21278 ``[''''»''' [link beast.ref.boost__beast__http__message.target.overload1 more...]]`` 21279 21280``` 21281Set the request-target string. ``` 21282void 21283``[link beast.ref.boost__beast__http__message.target.overload2 target]``( 21284 string_view s); 21285 ``[''''»''' [link beast.ref.boost__beast__http__message.target.overload2 more...]]`` 21286``` 21287[section:overload1 http::message::target (1 of 2 overloads)] 21288(Inherited from `http::header`) 21289 21290Returns the request-target string. 21291[heading Synopsis] 21292``` 21293string_view 21294target() const; 21295``` 21296 21297[heading Description] 21298The request target string returned is the same string which was received from the network or stored. In particular, it will contain url-encoded characters and should follow the syntax rules for URIs used with HTTP. 21299[heading Remarks] 21300This function is only available when `isRequest == true`. 21301[endsect] 21302[section:overload2 http::message::target (2 of 2 overloads)] 21303(Inherited from `http::header`) 21304 21305Set the request-target string. 21306[heading Synopsis] 21307``` 21308void 21309target( 21310 string_view s); 21311``` 21312 21313[heading Description] 21314It is the caller's responsibility to ensure that the request target string follows the syntax rules for URIs used with HTTP. In particular, reserved or special characters must be url-encoded. The implementation does not perform syntax checking on the passed string. 21315[heading Parameters] 21316[table [[Name][Description]] 21317 [[`s`][ 21318 21319A string representing the request-target. 21320 ]] 21321] 21322[heading Remarks] 21323This function is only available when `isRequest == true`. 21324[endsect] 21325[endsect] 21326 21327[section:version http::message::version] 21328[indexterm2 version..http::message] 21329Return the HTTP-version. ``` 21330unsigned 21331``[link beast.ref.boost__beast__http__message.version.overload1 version]``() const; 21332 ``[''''»''' [link beast.ref.boost__beast__http__message.version.overload1 more...]]`` 21333 21334``` 21335Set the HTTP-version. ``` 21336void 21337``[link beast.ref.boost__beast__http__message.version.overload2 version]``( 21338 unsigned value); 21339 ``[''''»''' [link beast.ref.boost__beast__http__message.version.overload2 more...]]`` 21340``` 21341[section:overload1 http::message::version (1 of 2 overloads)] 21342(Inherited from `http::header`) 21343 21344Return the HTTP-version. 21345[heading Synopsis] 21346``` 21347unsigned 21348version() const; 21349``` 21350 21351[heading Description] 21352This holds both the major and minor version numbers, using these formulas: 21353``` 21354 unsigned major = version / 10; 21355 unsigned minor = version % 10; 21356``` 21357Newly constructed headers will use HTTP/1.1 by default. [endsect] 21358[section:overload2 http::message::version (2 of 2 overloads)] 21359(Inherited from `http::header`) 21360 21361Set the HTTP-version. 21362[heading Synopsis] 21363``` 21364void 21365version( 21366 unsigned value); 21367``` 21368 21369[heading Description] 21370This holds both the major and minor version numbers, using these formulas: 21371``` 21372 unsigned major = version / 10; 21373 unsigned minor = version % 10; 21374``` 21375Newly constructed headers will use HTTP/1.1 by default. 21376[heading Parameters] 21377[table [[Name][Description]] 21378 [[`value`][ 21379 21380The version number to use 21381 ]] 21382] 21383[endsect] 21384[endsect] 21385 21386 21387 21388 21389Convenience header [include_file boost/beast/http.hpp] 21390 21391[endsect] 21392 21393 21394 21395[section:boost__beast__http__obsolete_reason http::obsolete_reason] 21396[indexterm1 http::obsolete_reason] 21397Returns the obsolete reason-phrase text for a status code. 21398[heading Synopsis] 21399 21400Defined in header [include_file boost/beast/http/status.hpp] 21401 21402 21403 21404``` 21405string_view 21406obsolete_reason( 21407 status v); 21408 21409``` 21410 21411[heading Description] 21412[heading Parameters] 21413[table [[Name][Description]] 21414 [[`v`][ 21415 21416The status code to use. 21417 ]] 21418] 21419 21420 21421 21422Convenience header [include_file boost/beast/http.hpp] 21423 21424[endsect] 21425[section:boost__beast__http__operator_lt__lt_ http::operator<<] 21426[indexterm1 http::operator<<] 21427Write the text for a field name to an output stream. ``` 21428std::ostream& 21429``[link beast.ref.boost__beast__http__operator_lt__lt_.overload1 operator<<]``( 21430 std::ostream& os, 21431 field f); 21432 ``[''''»''' [link beast.ref.boost__beast__http__operator_lt__lt_.overload1 more...]]`` 21433 21434``` 21435Outputs the standard reason phrase of a status code to a stream. ``` 21436std::ostream& 21437``[link beast.ref.boost__beast__http__operator_lt__lt_.overload2 operator<<]``( 21438 std::ostream&, 21439 status); 21440 ``[''''»''' [link beast.ref.boost__beast__http__operator_lt__lt_.overload2 more...]]`` 21441 21442``` 21443Write the text for a request method verb to an output stream. ``` 21444std::ostream& 21445``[link beast.ref.boost__beast__http__operator_lt__lt_.overload3 operator<<]``( 21446 std::ostream& os, 21447 verb v); 21448 ``[''''»''' [link beast.ref.boost__beast__http__operator_lt__lt_.overload3 more...]]`` 21449 21450``` 21451Serialize an HTTP/1 header to a `std::ostream`. ``` 21452template< 21453 bool isRequest, 21454 class __Fields__> 21455std::ostream& 21456``[link beast.ref.boost__beast__http__operator_lt__lt_.overload4 operator<<]``( 21457 std::ostream& os, 21458 header< isRequest, Fields > const& msg); 21459 ``[''''»''' [link beast.ref.boost__beast__http__operator_lt__lt_.overload4 more...]]`` 21460 21461``` 21462Serialize an HTTP/1 message to a `std::ostream`. ``` 21463template< 21464 bool isRequest, 21465 class __Body__, 21466 class __Fields__> 21467std::ostream& 21468``[link beast.ref.boost__beast__http__operator_lt__lt_.overload5 operator<<]``( 21469 std::ostream& os, 21470 message< isRequest, Body, Fields > const& msg); 21471 ``[''''»''' [link beast.ref.boost__beast__http__operator_lt__lt_.overload5 more...]]`` 21472``` 21473[section:overload1 http::operator<< (1 of 5 overloads)] 21474Write the text for a field name to an output stream. 21475[heading Synopsis] 21476 21477Defined in header [include_file boost/beast/http/field.hpp] 21478 21479 21480 21481``` 21482std::ostream& 21483operator<<( 21484 std::ostream& os, 21485 field f); 21486 21487``` 21488 21489[heading Description] 21490 21491 21492 21493Convenience header [include_file boost/beast/http.hpp] 21494 21495[endsect] 21496[section:overload2 http::operator<< (2 of 5 overloads)] 21497Outputs the standard reason phrase of a status code to a stream. 21498[heading Synopsis] 21499 21500Defined in header [include_file boost/beast/http/status.hpp] 21501 21502 21503 21504``` 21505std::ostream& 21506operator<<( 21507 std::ostream&, 21508 status); 21509 21510``` 21511 21512[heading Description] 21513 21514 21515 21516Convenience header [include_file boost/beast/http.hpp] 21517 21518[endsect] 21519[section:overload3 http::operator<< (3 of 5 overloads)] 21520Write the text for a request method verb to an output stream. 21521[heading Synopsis] 21522 21523Defined in header [include_file boost/beast/http/verb.hpp] 21524 21525 21526 21527``` 21528std::ostream& 21529operator<<( 21530 std::ostream& os, 21531 verb v); 21532 21533``` 21534 21535[heading Description] 21536 21537 21538 21539Convenience header [include_file boost/beast/http.hpp] 21540 21541[endsect] 21542[section:overload4 http::operator<< (4 of 5 overloads)] 21543Serialize an HTTP/1 header to a `std::ostream`. 21544[heading Synopsis] 21545 21546Defined in header [include_file boost/beast/http/write.hpp] 21547 21548 21549 21550``` 21551template< 21552 bool isRequest, 21553 class __Fields__> 21554std::ostream& 21555operator<<( 21556 std::ostream& os, 21557 header< isRequest, Fields > const& msg); 21558 21559``` 21560 21561[heading Description] 21562The function converts the header to its HTTP/1 serialized representation and stores the result in the output stream. 21563[heading Parameters] 21564[table [[Name][Description]] 21565 [[`os`][ 21566 21567The output stream to write to. 21568 ]] 21569 [[`msg`][ 21570 21571The message fields to write. 21572 ]] 21573] 21574 21575 21576 21577Convenience header [include_file boost/beast/http.hpp] 21578 21579[endsect] 21580[section:overload5 http::operator<< (5 of 5 overloads)] 21581Serialize an HTTP/1 message to a `std::ostream`. 21582[heading Synopsis] 21583 21584Defined in header [include_file boost/beast/http/write.hpp] 21585 21586 21587 21588``` 21589template< 21590 bool isRequest, 21591 class __Body__, 21592 class __Fields__> 21593std::ostream& 21594operator<<( 21595 std::ostream& os, 21596 message< isRequest, Body, Fields > const& msg); 21597 21598``` 21599 21600[heading Description] 21601The function converts the message to its HTTP/1 serialized representation and stores the result in the output stream. 21602The implementation will automatically perform chunk encoding if the contents of the message indicate that chunk encoding is required. 21603[heading Parameters] 21604[table [[Name][Description]] 21605 [[`os`][ 21606 21607The output stream to write to. 21608 ]] 21609 [[`msg`][ 21610 21611The message to write. 21612 ]] 21613] 21614 21615 21616 21617Convenience header [include_file boost/beast/http.hpp] 21618 21619[endsect] 21620[endsect] 21621 21622 21623 21624[section:boost__beast__http__opt_token_list http::opt_token_list] 21625[indexterm1 http::opt_token_list] 21626A list of tokens in a comma separated HTTP field value. 21627[heading Synopsis] 21628 21629Defined in header [include_file boost/beast/http/rfc7230.hpp] 21630 21631 21632 21633``` 21634using opt_token_list = detail::basic_parsed_list< detail::opt_token_list_policy >; 21635``` 21636 21637[heading Description] 21638This container allows iteration of a list of items in a header field value. The input is a comma separated list of tokens. 21639If a parsing error is encountered while iterating the string, the behavior of the container will be as if a string containing only characters up to but excluding the first invalid character was used to construct the list. 21640[heading BNF] 21641 21642``` 21643 token-list = *( "," OWS ) token *( OWS "," [ OWS token ] ) 21644``` 21645To use this class, construct with the string to be parsed and then use `begin` and `end`, or range-for to iterate each item: 21646[heading Example] 21647 21648``` 21649 for(auto const& token : token_list{"apple, pear, banana"}) 21650 std::cout << token << "\n"; 21651``` 21652 21653 21654 21655Convenience header [include_file boost/beast/http.hpp] 21656 21657[endsect] 21658[section:boost__beast__http__param_list http::param_list] 21659A list of parameters in an HTTP extension field value. 21660[heading Synopsis] 21661 21662Defined in header [include_file boost/beast/http/rfc7230.hpp] 21663 21664 21665 21666``` 21667class param_list 21668``` 21669[heading Types] 21670[table [[Name][Description]] 21671 [ 21672 [[link beast.ref.boost__beast__http__param_list.const_iterator [*const_iterator]]] 21673 [ 21674 A constant iterator to the list. 21675 ] 21676 ] 21677 [ 21678 [[link beast.ref.boost__beast__http__param_list.value_type [*value_type]]] 21679 [ 21680 The type of each element in the list. 21681 ] 21682 ] 21683] 21684[heading Member Functions] 21685[table [[Name][Description]] 21686 [ 21687 [[link beast.ref.boost__beast__http__param_list.begin [*begin]]] 21688 [ 21689 Return a const iterator to the beginning of the list. 21690 ] 21691 ] 21692 [ 21693 [[link beast.ref.boost__beast__http__param_list.cbegin [*cbegin]]] 21694 [ 21695 Return a const iterator to the beginning of the list. 21696 ] 21697 ] 21698 [ 21699 [[link beast.ref.boost__beast__http__param_list.cend [*cend]]] 21700 [ 21701 Return a const iterator to the end of the list. 21702 ] 21703 ] 21704 [ 21705 [[link beast.ref.boost__beast__http__param_list.end [*end]]] 21706 [ 21707 Return a const iterator to the end of the list. 21708 ] 21709 ] 21710 [ 21711 [[link beast.ref.boost__beast__http__param_list.param_list [*param_list]]] 21712 [ 21713 Default constructor. 21714 21715 Construct a list. 21716 ] 21717 ] 21718] 21719 21720[heading Description] 21721This container allows iteration of the parameter list in an HTTP extension. The parameter list is a series of name/value pairs with each pair starting with a semicolon. The value is optional. 21722If a parsing error is encountered while iterating the string, the behavior of the container will be as if a string containing only characters up to but excluding the first invalid character was used to construct the list. 21723[heading BNF] 21724 21725``` 21726 param-list = *( OWS ";" OWS param ) 21727 param = token OWS [ "=" OWS ( token / quoted-string ) ] 21728``` 21729To use this class, construct with the string to be parsed and then use [link beast.ref.boost__beast__http__param_list.begin `http::param_list::begin`] and [link beast.ref.boost__beast__http__param_list.end `http::param_list::end`], or range-for to iterate each item: 21730[heading Example] 21731 21732``` 21733 for(auto const& param : param_list{";level=9;no_context_takeover;bits=15"}) 21734 { 21735 std::cout << ";" << param.first; 21736 if(! param.second.empty()) 21737 std::cout << "=" << param.second; 21738 std::cout << "\n"; 21739 } 21740``` 21741[section:begin http::param_list::begin] 21742[indexterm2 begin..http::param_list] 21743Return a const iterator to the beginning of the list. 21744[heading Synopsis] 21745``` 21746const_iterator 21747begin() const; 21748``` 21749 21750[heading Description] 21751[endsect] 21752[section:cbegin http::param_list::cbegin] 21753[indexterm2 cbegin..http::param_list] 21754Return a const iterator to the beginning of the list. 21755[heading Synopsis] 21756``` 21757const_iterator 21758cbegin() const; 21759``` 21760 21761[heading Description] 21762[endsect] 21763[section:cend http::param_list::cend] 21764[indexterm2 cend..http::param_list] 21765Return a const iterator to the end of the list. 21766[heading Synopsis] 21767``` 21768const_iterator 21769cend() const; 21770``` 21771 21772[heading Description] 21773[endsect] 21774[section:const_iterator http::param_list::const_iterator] 21775[indexterm2 const_iterator..http::param_list] 21776A constant iterator to the list. 21777[heading Synopsis] 21778 21779``` 21780using const_iterator = ``['implementation-defined]``; 21781``` 21782 21783[heading Description] 21784[endsect] 21785[section:end http::param_list::end] 21786[indexterm2 end..http::param_list] 21787Return a const iterator to the end of the list. 21788[heading Synopsis] 21789``` 21790const_iterator 21791end() const; 21792``` 21793 21794[heading Description] 21795[endsect] 21796[section:param_list http::param_list::param_list] 21797[indexterm2 param_list..http::param_list] 21798Default constructor. ``` 21799``[link beast.ref.boost__beast__http__param_list.param_list.overload1 param_list]``(); 21800 ``[''''»''' [link beast.ref.boost__beast__http__param_list.param_list.overload1 more...]]`` 21801 21802``` 21803Construct a list. ``` 21804explicit 21805``[link beast.ref.boost__beast__http__param_list.param_list.overload2 param_list]``( 21806 string_view s); 21807 ``[''''»''' [link beast.ref.boost__beast__http__param_list.param_list.overload2 more...]]`` 21808``` 21809[section:overload1 http::param_list::param_list (1 of 2 overloads)] 21810Default constructor. 21811[heading Synopsis] 21812``` 21813param_list(); 21814``` 21815 21816[heading Description] 21817[endsect] 21818[section:overload2 http::param_list::param_list (2 of 2 overloads)] 21819Construct a list. 21820[heading Synopsis] 21821``` 21822param_list( 21823 string_view s); 21824``` 21825 21826[heading Description] 21827[heading Parameters] 21828[table [[Name][Description]] 21829 [[`s`][ 21830 21831A string containing the list contents. The string must remain valid for the lifetime of the container. 21832 ]] 21833] 21834[endsect] 21835[endsect] 21836 21837[section:value_type http::param_list::value_type] 21838[indexterm2 value_type..http::param_list] 21839The type of each element in the list. 21840[heading Synopsis] 21841 21842``` 21843using value_type = std::pair< string_view, string_view >; 21844``` 21845 21846[heading Description] 21847The first string in the pair is the name of the parameter, and the second string in the pair is its value (which may be empty). [endsect] 21848 21849 21850 21851Convenience header [include_file boost/beast/http.hpp] 21852 21853[endsect] 21854 21855 21856 21857[section:boost__beast__http__parser http::parser] 21858An HTTP/1 parser for producing a message. 21859[heading Synopsis] 21860 21861Defined in header [include_file boost/beast/http/parser.hpp] 21862 21863 21864 21865``` 21866template< 21867 bool isRequest, 21868 class __Body__, 21869 class __Allocator__ = std::allocator<char>> 21870class parser : 21871 public http::basic_parser< isRequest > 21872``` 21873[heading Types] 21874[table [[Name][Description]] 21875 [ 21876 [[link beast.ref.boost__beast__http__parser.is_request [*is_request]]] 21877 [ 21878 true if this parser parses requests, false for responses. 21879 ] 21880 ] 21881 [ 21882 [[link beast.ref.boost__beast__http__parser.value_type [*value_type]]] 21883 [ 21884 The type of message returned by the parser. 21885 ] 21886 ] 21887] 21888[heading Member Functions] 21889[table [[Name][Description]] 21890 [ 21891 [[link beast.ref.boost__beast__http__parser.body_limit [*body_limit]]] 21892 [ 21893 Set the limit on the payload body. 21894 ] 21895 ] 21896 [ 21897 [[link beast.ref.boost__beast__http__parser.chunked [*chunked]]] 21898 [ 21899 Returns true if the last value for Transfer-Encoding is "chunked". 21900 ] 21901 ] 21902 [ 21903 [[link beast.ref.boost__beast__http__parser.content_length [*content_length]]] 21904 [ 21905 Returns the optional value of Content-Length if known. 21906 ] 21907 ] 21908 [ 21909 [[link beast.ref.boost__beast__http__parser.content_length_remaining [*content_length_remaining]]] 21910 [ 21911 Returns the remaining content length if known. 21912 ] 21913 ] 21914 [ 21915 [[link beast.ref.boost__beast__http__parser.eager [*eager]]] 21916 [ 21917 Returns true if the eager parse option is set. 21918 21919 Set the eager parse option. 21920 ] 21921 ] 21922 [ 21923 [[link beast.ref.boost__beast__http__parser.get [*get]]] 21924 [ 21925 Returns the parsed message. 21926 ] 21927 ] 21928 [ 21929 [[link beast.ref.boost__beast__http__parser.got_some [*got_some]]] 21930 [ 21931 Returns true if the parser has received at least one byte of input. 21932 ] 21933 ] 21934 [ 21935 [[link beast.ref.boost__beast__http__parser.header_limit [*header_limit]]] 21936 [ 21937 Set a limit on the total size of the header. 21938 ] 21939 ] 21940 [ 21941 [[link beast.ref.boost__beast__http__parser.is_done [*is_done]]] 21942 [ 21943 Returns true if the message is complete. 21944 ] 21945 ] 21946 [ 21947 [[link beast.ref.boost__beast__http__parser.is_header_done [*is_header_done]]] 21948 [ 21949 Returns true if a the parser has produced the full header. 21950 ] 21951 ] 21952 [ 21953 [[link beast.ref.boost__beast__http__parser.keep_alive [*keep_alive]]] 21954 [ 21955 Returns true if the message has keep-alive connection semantics. 21956 ] 21957 ] 21958 [ 21959 [[link beast.ref.boost__beast__http__parser.need_eof [*need_eof]]] 21960 [ 21961 Returns true if the message semantics require an end of file. 21962 ] 21963 ] 21964 [ 21965 [[link beast.ref.boost__beast__http__parser.on_chunk_body [*on_chunk_body]]] 21966 [ 21967 Set a callback to be invoked on chunk body data. 21968 ] 21969 ] 21970 [ 21971 [[link beast.ref.boost__beast__http__parser.on_chunk_header [*on_chunk_header]]] 21972 [ 21973 Set a callback to be invoked on each chunk header. 21974 ] 21975 ] 21976 [ 21977 [[link beast.ref.boost__beast__http__parser.operator_eq_ [*operator=]]] 21978 [ 21979 Assignment (disallowed) 21980 ] 21981 ] 21982 [ 21983 [[link beast.ref.boost__beast__http__parser.parser [*parser]]] 21984 [ 21985 Constructor (disallowed) 21986 21987 Constructor. 21988 21989 Construct a parser from another parser, changing the Body type. 21990 ] 21991 ] 21992 [ 21993 [[link beast.ref.boost__beast__http__parser.put [*put]]] 21994 [ 21995 Write a buffer sequence to the parser. 21996 ] 21997 ] 21998 [ 21999 [[link beast.ref.boost__beast__http__parser.put_eof [*put_eof]]] 22000 [ 22001 Inform the parser that the end of stream was reached. 22002 ] 22003 ] 22004 [ 22005 [[link beast.ref.boost__beast__http__parser.release [*release]]] 22006 [ 22007 Returns ownership of the parsed message. 22008 ] 22009 ] 22010 [ 22011 [[link beast.ref.boost__beast__http__parser.skip [*skip]]] 22012 [ 22013 Returns true if the skip parse option is set. 22014 22015 Set the skip parse option. 22016 ] 22017 ] 22018 [ 22019 [[link beast.ref.boost__beast__http__parser.upgrade [*upgrade]]] 22020 [ 22021 Returns true if the message is an upgrade message. 22022 ] 22023 ] 22024 [ 22025 [[link beast.ref.boost__beast__http__parser.parser_dtor_ [*~parser]]] 22026 [ 22027 Destructor. 22028 ] 22029 ] 22030] 22031 22032[heading Description] 22033This class uses the basic HTTP/1 wire format parser to convert a series of octets into a [link beast.ref.boost__beast__http__message `http::message`] using the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container to represent the fields. 22034[heading Template Parameters] 22035[table [[Type][Description]] 22036 [[`isRequest`][ 22037 22038Indicates whether a request or response will be parsed. 22039 ]] 22040 [[`Body`][ 22041 22042The type used to represent the body. This must meet the requirements of ['Body]. 22043 ]] 22044 [[`Allocator`][ 22045 22046The type of allocator used with the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container. 22047 ]] 22048] 22049[heading Remarks] 22050A new instance of the parser is required for each message. 22051[section:body_limit http::parser::body_limit] 22052(Inherited from `http::basic_parser`) 22053 22054[indexterm2 body_limit..http::parser] 22055Set the limit on the payload body. 22056[heading Synopsis] 22057``` 22058void 22059body_limit( 22060 std::uint64_t v); 22061``` 22062 22063[heading Description] 22064This function sets the maximum allowed size of the payload body, before any encodings except chunked have been removed. Depending on the message semantics, one of these cases will apply: 22065 22066* The Content-Length is specified and exceeds the limit. In this case the result [link beast.ref.boost__beast__http__error `http::body_limit`] is returned immediately after the header is parsed. 22067 22068 22069* The Content-Length is unspecified and the chunked encoding is not specified as the last encoding. In this case the end of message is determined by the end of file indicator on the associated stream or input source. If a sufficient number of body payload octets are presented to the parser to exceed the configured limit, the parse fails with the result [link beast.ref.boost__beast__http__error `http::body_limit`] 22070 22071 22072* The Transfer-Encoding specifies the chunked encoding as the last encoding. In this case, when the number of payload body octets produced by removing the chunked encoding exceeds the configured limit, the parse fails with the result [link beast.ref.boost__beast__http__error `http::body_limit`]. 22073 22074Setting the limit after any body octets have been parsed results in undefined behavior. 22075The default limit is 1MB for requests and 8MB for responses. 22076[heading Parameters] 22077[table [[Name][Description]] 22078 [[`v`][ 22079 22080The payload body limit to set 22081 ]] 22082] 22083[endsect] 22084[section:chunked http::parser::chunked] 22085(Inherited from `http::basic_parser`) 22086 22087[indexterm2 chunked..http::parser] 22088Returns `true` if the last value for Transfer-Encoding is "chunked". 22089[heading Synopsis] 22090``` 22091bool 22092chunked() const; 22093``` 22094 22095[heading Description] 22096[heading Remarks] 22097The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 22098[endsect] 22099[section:content_length http::parser::content_length] 22100(Inherited from `http::basic_parser`) 22101 22102[indexterm2 content_length..http::parser] 22103Returns the optional value of Content-Length if known. 22104[heading Synopsis] 22105``` 22106boost::optional< std::uint64_t > 22107content_length() const; 22108``` 22109 22110[heading Description] 22111[heading Remarks] 22112The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 22113[endsect] 22114[section:content_length_remaining http::parser::content_length_remaining] 22115(Inherited from `http::basic_parser`) 22116 22117[indexterm2 content_length_remaining..http::parser] 22118Returns the remaining content length if known. 22119[heading Synopsis] 22120``` 22121boost::optional< std::uint64_t > 22122content_length_remaining() const; 22123``` 22124 22125[heading Description] 22126If the message header specifies a Content-Length, the return value will be the number of bytes remaining in the payload body have not yet been parsed. 22127[heading Remarks] 22128The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 22129[endsect] 22130[section:eager http::parser::eager] 22131[indexterm2 eager..http::parser] 22132Returns `true` if the eager parse option is set. ``` 22133bool 22134``[link beast.ref.boost__beast__http__parser.eager.overload1 eager]``() const; 22135 ``[''''»''' [link beast.ref.boost__beast__http__parser.eager.overload1 more...]]`` 22136 22137``` 22138Set the eager parse option. ``` 22139void 22140``[link beast.ref.boost__beast__http__parser.eager.overload2 eager]``( 22141 bool v); 22142 ``[''''»''' [link beast.ref.boost__beast__http__parser.eager.overload2 more...]]`` 22143``` 22144[section:overload1 http::parser::eager (1 of 2 overloads)] 22145(Inherited from `http::basic_parser`) 22146 22147Returns `true` if the eager parse option is set. 22148[heading Synopsis] 22149``` 22150bool 22151eager() const; 22152``` 22153 22154[heading Description] 22155[endsect] 22156[section:overload2 http::parser::eager (2 of 2 overloads)] 22157(Inherited from `http::basic_parser`) 22158 22159Set the eager parse option. 22160[heading Synopsis] 22161``` 22162void 22163eager( 22164 bool v); 22165``` 22166 22167[heading Description] 22168Normally the parser returns after successfully parsing a structured element (header, chunk header, or chunk body) even if there are octets remaining in the input. This is necessary when attempting to parse the header first, or when the caller wants to inspect information which may be invalidated by subsequent parsing, such as a chunk extension. The `eager` option controls whether the parser keeps going after parsing structured element if there are octets remaining in the buffer and no error occurs. This option is automatically set or cleared during certain stream operations to improve performance with no change in functionality. 22169The default setting is `false`. 22170[heading Parameters] 22171[table [[Name][Description]] 22172 [[`v`][ 22173 22174`true` to set the eager parse option or `false` to disable it. 22175 ]] 22176] 22177[endsect] 22178[endsect] 22179 22180[section:get http::parser::get] 22181[indexterm2 get..http::parser] 22182Returns the parsed message. ``` 22183value_type const & 22184``[link beast.ref.boost__beast__http__parser.get.overload1 get]``() const; 22185 ``[''''»''' [link beast.ref.boost__beast__http__parser.get.overload1 more...]]`` 22186 22187value_type& 22188``[link beast.ref.boost__beast__http__parser.get.overload2 get]``(); 22189 ``[''''»''' [link beast.ref.boost__beast__http__parser.get.overload2 more...]]`` 22190``` 22191[section:overload1 http::parser::get (1 of 2 overloads)] 22192Returns the parsed message. 22193[heading Synopsis] 22194``` 22195value_type const & 22196get() const; 22197``` 22198 22199[heading Description] 22200Depending on the parser's progress, parts of this object may be incomplete. [endsect] 22201[section:overload2 http::parser::get (2 of 2 overloads)] 22202Returns the parsed message. 22203[heading Synopsis] 22204``` 22205value_type& 22206get(); 22207``` 22208 22209[heading Description] 22210Depending on the parser's progress, parts of this object may be incomplete. [endsect] 22211[endsect] 22212 22213[section:got_some http::parser::got_some] 22214(Inherited from `http::basic_parser`) 22215 22216[indexterm2 got_some..http::parser] 22217Returns `true` if the parser has received at least one byte of input. 22218[heading Synopsis] 22219``` 22220bool 22221got_some() const; 22222``` 22223 22224[heading Description] 22225[endsect] 22226[section:header_limit http::parser::header_limit] 22227(Inherited from `http::basic_parser`) 22228 22229[indexterm2 header_limit..http::parser] 22230Set a limit on the total size of the header. 22231[heading Synopsis] 22232``` 22233void 22234header_limit( 22235 std::uint32_t v); 22236``` 22237 22238[heading Description] 22239This function sets the maximum allowed size of the header including all field name, value, and delimiter characters and also including the CRLF sequences in the serialized input. If the end of the header is not found within the limit of the header size, the error [link beast.ref.boost__beast__http__error `http::header_limit`] is returned by [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`]. 22240Setting the limit after any header octets have been parsed results in undefined behavior. [endsect] 22241[section:is_done http::parser::is_done] 22242(Inherited from `http::basic_parser`) 22243 22244[indexterm2 is_done..http::parser] 22245Returns `true` if the message is complete. 22246[heading Synopsis] 22247``` 22248bool 22249is_done() const; 22250``` 22251 22252[heading Description] 22253The message is complete after the full header is prduced and one of the following is true: 22254 22255* The skip body option was set. 22256 22257 22258* The semantics of the message indicate there is no body. 22259 22260 22261* The semantics of the message indicate a body is expected, and the entire body was parsed. 22262 22263[endsect] 22264[section:is_header_done http::parser::is_header_done] 22265(Inherited from `http::basic_parser`) 22266 22267[indexterm2 is_header_done..http::parser] 22268Returns `true` if a the parser has produced the full header. 22269[heading Synopsis] 22270``` 22271bool 22272is_header_done() const; 22273``` 22274 22275[heading Description] 22276[endsect] 22277[section:is_request http::parser::is_request] 22278(Inherited from `http::basic_parser`) 22279 22280[indexterm2 is_request..http::parser] 22281`true` if this parser parses requests, `false` for responses. 22282[heading Synopsis] 22283 22284``` 22285using is_request = std::integral_constant< bool, isRequest >; 22286``` 22287 22288[heading Description] 22289[endsect] 22290[section:keep_alive http::parser::keep_alive] 22291(Inherited from `http::basic_parser`) 22292 22293[indexterm2 keep_alive..http::parser] 22294Returns `true` if the message has keep-alive connection semantics. 22295[heading Synopsis] 22296``` 22297bool 22298keep_alive() const; 22299``` 22300 22301[heading Description] 22302This function always returns `false` if [link beast.ref.boost__beast__http__basic_parser.need_eof `http::basic_parser::need_eof`] would return `false`. 22303[heading Remarks] 22304The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 22305[endsect] 22306[section:need_eof http::parser::need_eof] 22307(Inherited from `http::basic_parser`) 22308 22309[indexterm2 need_eof..http::parser] 22310Returns `true` if the message semantics require an end of file. 22311[heading Synopsis] 22312``` 22313bool 22314need_eof() const; 22315``` 22316 22317[heading Description] 22318Depending on the contents of the header, the parser may require and end of file notification to know where the end of the body lies. If this function returns `true` it will be necessary to call [link beast.ref.boost__beast__http__basic_parser.put_eof `http::basic_parser::put_eof`] when there will never be additional data from the input. [endsect] 22319[section:on_chunk_body http::parser::on_chunk_body] 22320[indexterm2 on_chunk_body..http::parser] 22321Set a callback to be invoked on chunk body data. 22322[heading Synopsis] 22323``` 22324template< 22325 class Callback> 22326void 22327on_chunk_body( 22328 Callback& cb); 22329``` 22330 22331[heading Description] 22332The provided function object will be invoked one or more times to provide buffers corresponding to the chunk body for the current chunk. The callback receives the number of octets remaining in this chunk body including the octets in the buffer provided. 22333The callback must return the number of octets actually consumed. Any octets not consumed will be presented again in a subsequent invocation of the callback. The implementation type-erases the callback without requiring a dynamic allocation. For this reason, the callback object is passed by a non-constant reference. 22334[heading Example] 22335 22336``` 22337 auto callback = 22338 [](std::uint64_t remain, string_view body, error_code& ec) 22339 { 22340 //... 22341 }; 22342 parser.on_chunk_body(callback); 22343``` 22344[heading Parameters] 22345[table [[Name][Description]] 22346 [[`cb`][ 22347 22348The function to set, which must be invocable with this equivalent signature: 22349``` 22350 std::size_t 22351 on_chunk_header( 22352 std::uint64_t remain, // Octets remaining in this chunk, includes `body` 22353 string_view body, // A buffer holding some or all of the remainder of the chunk body 22354 error_code& ec); // May be set by the callback to indicate an error 22355``` 22356 22357 ]] 22358] 22359[endsect] 22360[section:on_chunk_header http::parser::on_chunk_header] 22361[indexterm2 on_chunk_header..http::parser] 22362Set a callback to be invoked on each chunk header. 22363[heading Synopsis] 22364``` 22365template< 22366 class Callback> 22367void 22368on_chunk_header( 22369 Callback& cb); 22370``` 22371 22372[heading Description] 22373The callback will be invoked once for every chunk in the message payload, as well as once for the last chunk. The invocation happens after the chunk header is available but before any body octets have been parsed. 22374The extensions are provided in raw, validated form, use [link beast.ref.boost__beast__http__basic_chunk_extensions.parse `http::basic_chunk_extensions::parse`] to parse the extensions into a structured container for easier access. The implementation type-erases the callback without requiring a dynamic allocation. For this reason, the callback object is passed by a non-constant reference. 22375[heading Example] 22376 22377``` 22378 auto callback = 22379 [](std::uint64_t size, string_view extensions, error_code& ec) 22380 { 22381 //... 22382 }; 22383 parser.on_chunk_header(callback); 22384``` 22385[heading Parameters] 22386[table [[Name][Description]] 22387 [[`cb`][ 22388 22389The function to set, which must be invocable with this equivalent signature: 22390``` 22391 void 22392 on_chunk_header( 22393 std::uint64_t size, // Size of the chunk, zero for the last chunk 22394 string_view extensions, // The chunk-extensions in raw form 22395 error_code& ec); // May be set by the callback to indicate an error 22396``` 22397 22398 ]] 22399] 22400[endsect] 22401[section:operator_eq_ http::parser::operator=] 22402[indexterm2 operator=..http::parser] 22403Assignment (disallowed) 22404[heading Synopsis] 22405``` 22406parser& 22407operator=( 22408 parser const&); 22409``` 22410 22411[heading Description] 22412[endsect] 22413[section:parser http::parser::parser] 22414[indexterm2 parser..http::parser] 22415Constructor (disallowed) ``` 22416``[link beast.ref.boost__beast__http__parser.parser.overload1 parser]``( 22417 parser const&); 22418 ``[''''»''' [link beast.ref.boost__beast__http__parser.parser.overload1 more...]]`` 22419 22420``[link beast.ref.boost__beast__http__parser.parser.overload2 parser]``( 22421 parser&& other); 22422 ``[''''»''' [link beast.ref.boost__beast__http__parser.parser.overload2 more...]]`` 22423 22424``` 22425Constructor. ``` 22426``[link beast.ref.boost__beast__http__parser.parser.overload3 parser]``(); 22427 ``[''''»''' [link beast.ref.boost__beast__http__parser.parser.overload3 more...]]`` 22428 22429template< 22430 class... Args> 22431explicit 22432``[link beast.ref.boost__beast__http__parser.parser.overload4 parser]``( 22433 Args&&... args); 22434 ``[''''»''' [link beast.ref.boost__beast__http__parser.parser.overload4 more...]]`` 22435 22436``` 22437Construct a parser from another parser, changing the Body type. ``` 22438template< 22439 class OtherBody, 22440 class... Args> 22441explicit 22442``[link beast.ref.boost__beast__http__parser.parser.overload5 parser]``( 22443 parser< isRequest, OtherBody, Allocator >&& parser, 22444 Args&&... args); 22445 ``[''''»''' [link beast.ref.boost__beast__http__parser.parser.overload5 more...]]`` 22446``` 22447[section:overload1 http::parser::parser (1 of 5 overloads)] 22448Constructor (disallowed) 22449[heading Synopsis] 22450``` 22451parser( 22452 parser const&); 22453``` 22454 22455[heading Description] 22456[endsect] 22457[section:overload2 http::parser::parser (2 of 5 overloads)] 22458Constructor (disallowed) 22459[heading Synopsis] 22460``` 22461parser( 22462 parser&& other); 22463``` 22464 22465[heading Description] 22466[endsect] 22467[section:overload3 http::parser::parser (3 of 5 overloads)] 22468Constructor. 22469[heading Synopsis] 22470``` 22471parser(); 22472``` 22473 22474[heading Description] 22475[endsect] 22476[section:overload4 http::parser::parser (4 of 5 overloads)] 22477Constructor. 22478[heading Synopsis] 22479``` 22480template< 22481 class... Args> 22482parser( 22483 Args&&... args); 22484``` 22485 22486[heading Description] 22487[heading Parameters] 22488[table [[Name][Description]] 22489 [[`args`][ 22490 22491Optional arguments forwarded to the [link beast.ref.boost__beast__http__message `http::message`] constructor. 22492 ]] 22493] 22494[heading Remarks] 22495This function participates in overload resolution only if the first argument is not a [link beast.ref.boost__beast__http__parser `http::parser`]. 22496[endsect] 22497[section:overload5 http::parser::parser (5 of 5 overloads)] 22498Construct a parser from another parser, changing the Body type. 22499[heading Synopsis] 22500``` 22501template< 22502 class OtherBody, 22503 class... Args> 22504parser( 22505 parser< isRequest, OtherBody, Allocator >&& parser, 22506 Args&&... args); 22507``` 22508 22509[heading Description] 22510This constructs a new parser by move constructing the header from another parser with a different body type. The constructed-from parser must not have any parsed body octets or initialized ['BodyReader], otherwise an exception is generated. 22511[heading Example] 22512 22513``` 22514 // Deferred body type commitment 22515 request_parser<empty_body> req0; 22516 ... 22517 request_parser<string_body> req{std::move(req0)}; 22518``` 22519If an exception is thrown, the state of the constructed-from parser is undefined. 22520[heading Parameters] 22521[table [[Name][Description]] 22522 [[`parser`][ 22523 22524The other parser to construct from. After this call returns, the constructed-from parser may only be destroyed. 22525 ]] 22526 [[`args`][ 22527 22528Optional arguments forwarded to the message constructor. 22529 ]] 22530] 22531[heading Exceptions] 22532[table [[Type][Thrown On]] 22533 [[`std::invalid_argument`][ 22534 22535Thrown when the constructed-from parser has already initialized a body reader. 22536 ]] 22537] 22538[heading Remarks] 22539This function participates in overload resolution only if the other parser uses a different body type. 22540[endsect] 22541[endsect] 22542 22543[section:put http::parser::put] 22544(Inherited from `http::basic_parser`) 22545 22546[indexterm2 put..http::parser] 22547Write a buffer sequence to the parser. 22548[heading Synopsis] 22549``` 22550template< 22551 class __ConstBufferSequence__> 22552std::size_t 22553put( 22554 ConstBufferSequence const& buffers, 22555 error_code& ec); 22556``` 22557 22558[heading Description] 22559This function attempts to incrementally parse the HTTP message data stored in the caller provided buffers. Upon success, a positive return value indicates that the parser made forward progress, consuming that number of bytes. 22560In some cases there may be an insufficient number of octets in the input buffer in order to make forward progress. This is indicated by the code [link beast.ref.boost__beast__http__error `http::need_more`]. When this happens, the caller should place additional bytes into the buffer sequence and call [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] again. 22561The error code [link beast.ref.boost__beast__http__error `http::need_more`] is special. When this error is returned, a subsequent call to [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] may succeed if the buffers have been updated. Otherwise, upon error the parser may not be restarted. 22562[heading Parameters] 22563[table [[Name][Description]] 22564 [[`buffers`][ 22565 22566An object meeting the requirements of ['ConstBufferSequence] that represents the next chunk of message data. If the length of this buffer sequence is one, the implementation will not allocate additional memory. The class [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`] is provided as one way to meet this requirement 22567 ]] 22568 [[`ec`][ 22569 22570Set to the error, if any occurred. 22571 ]] 22572] 22573[heading Return Value] 22574The number of octets consumed in the buffer sequence. The caller should remove these octets even if the error is set. 22575[endsect] 22576[section:put_eof http::parser::put_eof] 22577(Inherited from `http::basic_parser`) 22578 22579[indexterm2 put_eof..http::parser] 22580Inform the parser that the end of stream was reached. 22581[heading Synopsis] 22582``` 22583void 22584put_eof( 22585 error_code& ec); 22586``` 22587 22588[heading Description] 22589In certain cases, HTTP needs to know where the end of the stream is. For example, sometimes servers send responses without Content-Length and expect the client to consume input (for the body) until EOF. Callbacks and errors will still be processed as usual. 22590This is typically called when a read from the underlying stream object sets the error code to `net::error::eof`. 22591[heading Remarks] 22592Only valid after parsing a complete header. 22593[heading Parameters] 22594[table [[Name][Description]] 22595 [[`ec`][ 22596 22597Set to the error, if any occurred. 22598 ]] 22599] 22600[endsect] 22601[section:release http::parser::release] 22602[indexterm2 release..http::parser] 22603Returns ownership of the parsed message. 22604[heading Synopsis] 22605``` 22606value_type 22607release(); 22608``` 22609 22610[heading Description] 22611Ownership is transferred to the caller. Depending on the parser's progress, parts of this object may be incomplete. 22612[heading Requires] 22613 22614[link beast.ref.boost__beast__http__parser.value_type `http::parser::value_type`] is [*MoveConstructible] [endsect] 22615[section:skip http::parser::skip] 22616[indexterm2 skip..http::parser] 22617Returns `true` if the skip parse option is set. ``` 22618bool 22619``[link beast.ref.boost__beast__http__parser.skip.overload1 skip]``() const; 22620 ``[''''»''' [link beast.ref.boost__beast__http__parser.skip.overload1 more...]]`` 22621 22622``` 22623Set the skip parse option. ``` 22624void 22625``[link beast.ref.boost__beast__http__parser.skip.overload2 skip]``( 22626 bool v); 22627 ``[''''»''' [link beast.ref.boost__beast__http__parser.skip.overload2 more...]]`` 22628``` 22629[section:overload1 http::parser::skip (1 of 2 overloads)] 22630(Inherited from `http::basic_parser`) 22631 22632Returns `true` if the skip parse option is set. 22633[heading Synopsis] 22634``` 22635bool 22636skip() const; 22637``` 22638 22639[heading Description] 22640[endsect] 22641[section:overload2 http::parser::skip (2 of 2 overloads)] 22642(Inherited from `http::basic_parser`) 22643 22644Set the skip parse option. 22645[heading Synopsis] 22646``` 22647void 22648skip( 22649 bool v); 22650``` 22651 22652[heading Description] 22653This option controls whether or not the parser expects to see an HTTP body, regardless of the presence or absence of certain fields such as Content-Length or a chunked Transfer-Encoding. Depending on the request, some responses do not carry a body. For example, a 200 response to a CONNECT request from a tunneling proxy, or a response to a HEAD request. In these cases, callers may use this function inform the parser that no body is expected. The parser will consider the message complete after the header has been received. 22654[heading Parameters] 22655[table [[Name][Description]] 22656 [[`v`][ 22657 22658`true` to set the skip body option or `false` to disable it. 22659 ]] 22660] 22661[heading Remarks] 22662This function must called before any bytes are processed. 22663[endsect] 22664[endsect] 22665 22666[section:upgrade http::parser::upgrade] 22667(Inherited from `http::basic_parser`) 22668 22669[indexterm2 upgrade..http::parser] 22670Returns `true` if the message is an upgrade message. 22671[heading Synopsis] 22672``` 22673bool 22674upgrade() const; 22675``` 22676 22677[heading Description] 22678[heading Remarks] 22679The return value is undefined unless [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] would return `true`. 22680[endsect] 22681[section:value_type http::parser::value_type] 22682[indexterm2 value_type..http::parser] 22683The type of message returned by the parser. 22684[heading Synopsis] 22685 22686``` 22687using value_type = message< isRequest, Body, basic_fields< Allocator > >; 22688``` 22689[heading Types] 22690[table [[Name][Description]] 22691 [ 22692 [[link beast.ref.boost__beast__http__message.body_type [*body_type]]] 22693 [ 22694 The type providing the body traits. 22695 ] 22696 ] 22697 [ 22698 [[link beast.ref.boost__beast__http__message.fields_type [*fields_type]]] 22699 [ 22700 The type representing the fields. 22701 ] 22702 ] 22703 [ 22704 [[link beast.ref.boost__beast__http__message.header_type [*header_type]]] 22705 [ 22706 The base class used to hold the header portion of the message. 22707 ] 22708 ] 22709 [ 22710 [[link beast.ref.boost__beast__http__message.is_request [*is_request]]] 22711 [ 22712 Indicates if the header is a request or response. 22713 ] 22714 ] 22715] 22716[heading Member Functions] 22717[table [[Name][Description]] 22718 [ 22719 [[link beast.ref.boost__beast__http__message.base [*base]]] 22720 [ 22721 Returns the header portion of the message. 22722 ] 22723 ] 22724 [ 22725 [[link beast.ref.boost__beast__http__message.body [*body]]] 22726 [ 22727 Returns the body. 22728 ] 22729 ] 22730 [ 22731 [[link beast.ref.boost__beast__http__message.chunked [*chunked]]] 22732 [ 22733 Returns true if the chunked Transfer-Encoding is specified. 22734 22735 Set or clear the chunked Transfer-Encoding. 22736 ] 22737 ] 22738 [ 22739 [[link beast.ref.boost__beast__http__message.content_length [*content_length]]] 22740 [ 22741 Set or clear the Content-Length field. 22742 ] 22743 ] 22744 [ 22745 [[link beast.ref.boost__beast__http__message.has_content_length [*has_content_length]]] 22746 [ 22747 Returns true if the Content-Length field is present. 22748 ] 22749 ] 22750 [ 22751 [[link beast.ref.boost__beast__http__message.keep_alive [*keep_alive]]] 22752 [ 22753 Returns true if the message semantics indicate keep-alive. 22754 22755 Set the keep-alive message semantic option. 22756 ] 22757 ] 22758 [ 22759 [[link beast.ref.boost__beast__http__message.message [*message]]] 22760 [ 22761 Constructor. 22762 22763 Construct a message. 22764 ] 22765 ] 22766 [ 22767 [[link beast.ref.boost__beast__http__message.method [*method]]] 22768 [ 22769 Return the request-method verb. 22770 22771 Set the request-method. 22772 ] 22773 ] 22774 [ 22775 [[link beast.ref.boost__beast__http__message.method_string [*method_string]]] 22776 [ 22777 Return the request-method as a string. 22778 ] 22779 ] 22780 [ 22781 [[link beast.ref.boost__beast__http__message.need_eof [*need_eof]]] 22782 [ 22783 Returns true if the message semantics require an end of file. 22784 ] 22785 ] 22786 [ 22787 [[link beast.ref.boost__beast__http__message.operator_eq_ [*operator=]]] 22788 [ 22789 Assignment. 22790 ] 22791 ] 22792 [ 22793 [[link beast.ref.boost__beast__http__message.payload_size [*payload_size]]] 22794 [ 22795 Returns the payload size of the body in octets if possible. 22796 ] 22797 ] 22798 [ 22799 [[link beast.ref.boost__beast__http__message.prepare_payload [*prepare_payload]]] 22800 [ 22801 Prepare the message payload fields for the body. 22802 ] 22803 ] 22804 [ 22805 [[link beast.ref.boost__beast__http__message.reason [*reason]]] 22806 [ 22807 Return the response reason-phrase. 22808 22809 Set the response reason-phrase (deprecated) 22810 ] 22811 ] 22812 [ 22813 [[link beast.ref.boost__beast__http__message.result [*result]]] 22814 [ 22815 The response status-code result. 22816 22817 Set the response status-code. 22818 22819 Set the response status-code as an integer. 22820 ] 22821 ] 22822 [ 22823 [[link beast.ref.boost__beast__http__message.result_int [*result_int]]] 22824 [ 22825 The response status-code expressed as an integer. 22826 ] 22827 ] 22828 [ 22829 [[link beast.ref.boost__beast__http__message.target [*target]]] 22830 [ 22831 Returns the request-target string. 22832 22833 Set the request-target string. 22834 ] 22835 ] 22836 [ 22837 [[link beast.ref.boost__beast__http__message.version [*version]]] 22838 [ 22839 Return the HTTP-version. 22840 22841 Set the HTTP-version. 22842 ] 22843 ] 22844] 22845This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 22846A message can be a request or response, depending on the `isRequest` template argument value. Requests and responses have different types; functions may be overloaded based on the type if desired. 22847The `Body` template argument type determines the model used to read or write the content body of the message. 22848Newly constructed messages objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 22849[heading Template Parameters] 22850[table [[Type][Description]] 22851 [[`isRequest`][ 22852 22853`true` if this represents a request, or `false` if this represents a response. Some class data members are conditionally present depending on this value. 22854 ]] 22855 [[`Body`][ 22856 22857A type meeting the requirements of Body. 22858 ]] 22859 [[`Fields`][ 22860 22861The type of container used to hold the field value pairs. 22862 ]] 22863] 22864 22865[heading Description] 22866[endsect] 22867[section:parser_dtor_ http::parser::~parser] 22868[indexterm2 ~parser..http::parser] 22869Destructor. 22870[heading Synopsis] 22871``` 22872~parser(); 22873``` 22874 22875[heading Description] 22876[endsect] 22877 22878 22879 22880Convenience header [include_file boost/beast/http.hpp] 22881 22882[endsect] 22883 22884 22885 22886[section:boost__beast__http__read http::read] 22887[indexterm1 http::read] 22888Read a complete message from a stream using a parser. ``` 22889template< 22890 class __SyncReadStream__, 22891 class __DynamicBuffer__, 22892 bool isRequest> 22893std::size_t 22894``[link beast.ref.boost__beast__http__read.overload1 read]``( 22895 SyncReadStream& stream, 22896 DynamicBuffer& buffer, 22897 basic_parser< isRequest >& parser); 22898 ``[''''»''' [link beast.ref.boost__beast__http__read.overload1 more...]]`` 22899 22900template< 22901 class __SyncReadStream__, 22902 class __DynamicBuffer__, 22903 bool isRequest> 22904std::size_t 22905``[link beast.ref.boost__beast__http__read.overload2 read]``( 22906 SyncReadStream& stream, 22907 DynamicBuffer& buffer, 22908 basic_parser< isRequest >& parser, 22909 error_code& ec); 22910 ``[''''»''' [link beast.ref.boost__beast__http__read.overload2 more...]]`` 22911 22912``` 22913Read a complete message from a stream. ``` 22914template< 22915 class __SyncReadStream__, 22916 class __DynamicBuffer__, 22917 bool isRequest, 22918 class __Body__, 22919 class __Allocator__> 22920std::size_t 22921``[link beast.ref.boost__beast__http__read.overload3 read]``( 22922 SyncReadStream& stream, 22923 DynamicBuffer& buffer, 22924 message< isRequest, Body, basic_fields< Allocator >>& msg); 22925 ``[''''»''' [link beast.ref.boost__beast__http__read.overload3 more...]]`` 22926 22927template< 22928 class __SyncReadStream__, 22929 class __DynamicBuffer__, 22930 bool isRequest, 22931 class __Body__, 22932 class __Allocator__> 22933std::size_t 22934``[link beast.ref.boost__beast__http__read.overload4 read]``( 22935 SyncReadStream& stream, 22936 DynamicBuffer& buffer, 22937 message< isRequest, Body, basic_fields< Allocator >>& msg, 22938 error_code& ec); 22939 ``[''''»''' [link beast.ref.boost__beast__http__read.overload4 more...]]`` 22940``` 22941[section:overload1 http::read (1 of 4 overloads)] 22942Read a complete message from a stream using a parser. 22943[heading Synopsis] 22944 22945Defined in header [include_file boost/beast/http/read.hpp] 22946 22947 22948 22949``` 22950template< 22951 class __SyncReadStream__, 22952 class __DynamicBuffer__, 22953 bool isRequest> 22954std::size_t 22955read( 22956 SyncReadStream& stream, 22957 DynamicBuffer& buffer, 22958 basic_parser< isRequest >& parser); 22959 22960``` 22961 22962[heading Description] 22963This function is used to read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 22964 22965* [link beast.ref.boost__beast__http__basic_parser.is_done `http::basic_parser::is_done`] returns `true` 22966 22967 22968* An error occurs. 22969 22970This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 22971If the end of file error is received while reading from the stream, then the error returned from this function will be: 22972 22973* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 22974 22975 22976* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 22977 22978 22979* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 22980 22981[heading Parameters] 22982[table [[Name][Description]] 22983 [[`stream`][ 22984 22985The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 22986 ]] 22987 [[`buffer`][ 22988 22989Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 22990 ]] 22991 [[`parser`][ 22992 22993The parser to use. 22994 ]] 22995] 22996[heading Return Value] 22997The number of bytes transferred from the stream. 22998[heading Exceptions] 22999[table [[Type][Thrown On]] 23000 [[`system_error`][ 23001 23002Thrown on failure. 23003 ]] 23004] 23005[heading Remarks] 23006The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 23007 23008 23009 23010Convenience header [include_file boost/beast/http.hpp] 23011 23012[endsect] 23013[section:overload2 http::read (2 of 4 overloads)] 23014Read a complete message from a stream using a parser. 23015[heading Synopsis] 23016 23017Defined in header [include_file boost/beast/http/read.hpp] 23018 23019 23020 23021``` 23022template< 23023 class __SyncReadStream__, 23024 class __DynamicBuffer__, 23025 bool isRequest> 23026std::size_t 23027read( 23028 SyncReadStream& stream, 23029 DynamicBuffer& buffer, 23030 basic_parser< isRequest >& parser, 23031 error_code& ec); 23032 23033``` 23034 23035[heading Description] 23036This function is used to read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 23037 23038* [link beast.ref.boost__beast__http__basic_parser.is_done `http::basic_parser::is_done`] returns `true` 23039 23040 23041* An error occurs. 23042 23043This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23044If the end of file error is received while reading from the stream, then the error returned from this function will be: 23045 23046* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23047 23048 23049* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23050 23051 23052* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23053 23054[heading Parameters] 23055[table [[Name][Description]] 23056 [[`stream`][ 23057 23058The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23059 ]] 23060 [[`buffer`][ 23061 23062Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23063 ]] 23064 [[`parser`][ 23065 23066The parser to use. 23067 ]] 23068 [[`ec`][ 23069 23070Set to the error, if any occurred. 23071 ]] 23072] 23073[heading Return Value] 23074The number of bytes transferred from the stream. 23075[heading Remarks] 23076The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 23077 23078 23079 23080Convenience header [include_file boost/beast/http.hpp] 23081 23082[endsect] 23083[section:overload3 http::read (3 of 4 overloads)] 23084Read a complete message from a stream. 23085[heading Synopsis] 23086 23087Defined in header [include_file boost/beast/http/read.hpp] 23088 23089 23090 23091``` 23092template< 23093 class __SyncReadStream__, 23094 class __DynamicBuffer__, 23095 bool isRequest, 23096 class __Body__, 23097 class __Allocator__> 23098std::size_t 23099read( 23100 SyncReadStream& stream, 23101 DynamicBuffer& buffer, 23102 message< isRequest, Body, basic_fields< Allocator >>& msg); 23103 23104``` 23105 23106[heading Description] 23107This function is used to read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__message `http::message`]. The call will block until one of the following conditions is true: 23108 23109* The entire message is read in. 23110 23111 23112* An error occurs. 23113 23114This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23115If the end of file error is received while reading from the stream, then the error returned from this function will be: 23116 23117* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23118 23119 23120* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23121 23122 23123* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23124 23125[heading Parameters] 23126[table [[Name][Description]] 23127 [[`stream`][ 23128 23129The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23130 ]] 23131 [[`buffer`][ 23132 23133Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23134 ]] 23135 [[`msg`][ 23136 23137The container in which to store the message contents. This message container should not have previous contents, otherwise the behavior is undefined. The type must be meet the ['MoveAssignable] and ['MoveConstructible] requirements. 23138 ]] 23139] 23140[heading Return Value] 23141The number of bytes transferred from the stream. 23142[heading Exceptions] 23143[table [[Type][Thrown On]] 23144 [[`system_error`][ 23145 23146Thrown on failure. 23147 ]] 23148] 23149[heading Remarks] 23150The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 23151 23152 23153 23154Convenience header [include_file boost/beast/http.hpp] 23155 23156[endsect] 23157[section:overload4 http::read (4 of 4 overloads)] 23158Read a complete message from a stream. 23159[heading Synopsis] 23160 23161Defined in header [include_file boost/beast/http/read.hpp] 23162 23163 23164 23165``` 23166template< 23167 class __SyncReadStream__, 23168 class __DynamicBuffer__, 23169 bool isRequest, 23170 class __Body__, 23171 class __Allocator__> 23172std::size_t 23173read( 23174 SyncReadStream& stream, 23175 DynamicBuffer& buffer, 23176 message< isRequest, Body, basic_fields< Allocator >>& msg, 23177 error_code& ec); 23178 23179``` 23180 23181[heading Description] 23182This function is used to read a complete message from a stream into an instance of [link beast.ref.boost__beast__http__message `http::message`]. The call will block until one of the following conditions is true: 23183 23184* The entire message is read in. 23185 23186 23187* An error occurs. 23188 23189This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23190If the end of file error is received while reading from the stream, then the error returned from this function will be: 23191 23192* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23193 23194 23195* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23196 23197 23198* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23199 23200[heading Parameters] 23201[table [[Name][Description]] 23202 [[`stream`][ 23203 23204The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23205 ]] 23206 [[`buffer`][ 23207 23208Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23209 ]] 23210 [[`msg`][ 23211 23212The container in which to store the message contents. This message container should not have previous contents, otherwise the behavior is undefined. The type must be meet the ['MoveAssignable] and ['MoveConstructible] requirements. 23213 ]] 23214 [[`ec`][ 23215 23216Set to the error, if any occurred. 23217 ]] 23218] 23219[heading Return Value] 23220The number of bytes transferred from the stream. 23221[heading Remarks] 23222The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `true` on the parser passed in. 23223 23224 23225 23226Convenience header [include_file boost/beast/http.hpp] 23227 23228[endsect] 23229[endsect] 23230 23231 23232 23233[section:boost__beast__http__read_header http::read_header] 23234[indexterm1 http::read_header] 23235Read a complete message header from a stream using a parser. ``` 23236template< 23237 class __SyncReadStream__, 23238 class __DynamicBuffer__, 23239 bool isRequest> 23240std::size_t 23241``[link beast.ref.boost__beast__http__read_header.overload1 read_header]``( 23242 SyncReadStream& stream, 23243 DynamicBuffer& buffer, 23244 basic_parser< isRequest >& parser); 23245 ``[''''»''' [link beast.ref.boost__beast__http__read_header.overload1 more...]]`` 23246 23247template< 23248 class __SyncReadStream__, 23249 class __DynamicBuffer__, 23250 bool isRequest> 23251std::size_t 23252``[link beast.ref.boost__beast__http__read_header.overload2 read_header]``( 23253 SyncReadStream& stream, 23254 DynamicBuffer& buffer, 23255 basic_parser< isRequest >& parser, 23256 error_code& ec); 23257 ``[''''»''' [link beast.ref.boost__beast__http__read_header.overload2 more...]]`` 23258``` 23259[section:overload1 http::read_header (1 of 2 overloads)] 23260Read a complete message header from a stream using a parser. 23261[heading Synopsis] 23262 23263Defined in header [include_file boost/beast/http/read.hpp] 23264 23265 23266 23267``` 23268template< 23269 class __SyncReadStream__, 23270 class __DynamicBuffer__, 23271 bool isRequest> 23272std::size_t 23273read_header( 23274 SyncReadStream& stream, 23275 DynamicBuffer& buffer, 23276 basic_parser< isRequest >& parser); 23277 23278``` 23279 23280[heading Description] 23281This function is used to read a complete message header from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 23282 23283* [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] returns `true` 23284 23285 23286* An error occurs. 23287 23288This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23289If the end of file error is received while reading from the stream, then the error returned from this function will be: 23290 23291* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23292 23293 23294* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23295 23296 23297* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23298 23299[heading Parameters] 23300[table [[Name][Description]] 23301 [[`stream`][ 23302 23303The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23304 ]] 23305 [[`buffer`][ 23306 23307Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23308 ]] 23309 [[`parser`][ 23310 23311The parser to use. 23312 ]] 23313] 23314[heading Return Value] 23315The number of bytes transferred from the stream. 23316[heading Exceptions] 23317[table [[Type][Thrown On]] 23318 [[`system_error`][ 23319 23320Thrown on failure. 23321 ]] 23322] 23323[heading Remarks] 23324The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `false` on the parser passed in. 23325 23326 23327 23328Convenience header [include_file boost/beast/http.hpp] 23329 23330[endsect] 23331[section:overload2 http::read_header (2 of 2 overloads)] 23332Read a complete message header from a stream using a parser. 23333[heading Synopsis] 23334 23335Defined in header [include_file boost/beast/http/read.hpp] 23336 23337 23338 23339``` 23340template< 23341 class __SyncReadStream__, 23342 class __DynamicBuffer__, 23343 bool isRequest> 23344std::size_t 23345read_header( 23346 SyncReadStream& stream, 23347 DynamicBuffer& buffer, 23348 basic_parser< isRequest >& parser, 23349 error_code& ec); 23350 23351``` 23352 23353[heading Description] 23354This function is used to read a complete message header from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 23355 23356* [link beast.ref.boost__beast__http__basic_parser.is_header_done `http::basic_parser::is_header_done`] returns `true` 23357 23358 23359* An error occurs. 23360 23361This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23362If the end of file error is received while reading from the stream, then the error returned from this function will be: 23363 23364* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23365 23366 23367* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23368 23369 23370* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23371 23372[heading Parameters] 23373[table [[Name][Description]] 23374 [[`stream`][ 23375 23376The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23377 ]] 23378 [[`buffer`][ 23379 23380Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23381 ]] 23382 [[`parser`][ 23383 23384The parser to use. 23385 ]] 23386 [[`ec`][ 23387 23388Set to the error, if any occurred. 23389 ]] 23390] 23391[heading Return Value] 23392The number of bytes transferred from the stream. 23393[heading Remarks] 23394The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. The implementation will call [link beast.ref.boost__beast__http__basic_parser.eager `http::basic_parser::eager`] with the value `false` on the parser passed in. 23395 23396 23397 23398Convenience header [include_file boost/beast/http.hpp] 23399 23400[endsect] 23401[endsect] 23402 23403 23404 23405[section:boost__beast__http__read_some http::read_some] 23406[indexterm1 http::read_some] 23407Read part of a message from a stream using a parser. ``` 23408template< 23409 class __SyncReadStream__, 23410 class __DynamicBuffer__, 23411 bool isRequest> 23412std::size_t 23413``[link beast.ref.boost__beast__http__read_some.overload1 read_some]``( 23414 SyncReadStream& stream, 23415 DynamicBuffer& buffer, 23416 basic_parser< isRequest >& parser); 23417 ``[''''»''' [link beast.ref.boost__beast__http__read_some.overload1 more...]]`` 23418 23419template< 23420 class __SyncReadStream__, 23421 class __DynamicBuffer__, 23422 bool isRequest> 23423std::size_t 23424``[link beast.ref.boost__beast__http__read_some.overload2 read_some]``( 23425 SyncReadStream& stream, 23426 DynamicBuffer& buffer, 23427 basic_parser< isRequest >& parser, 23428 error_code& ec); 23429 ``[''''»''' [link beast.ref.boost__beast__http__read_some.overload2 more...]]`` 23430``` 23431[section:overload1 http::read_some (1 of 2 overloads)] 23432Read part of a message from a stream using a parser. 23433[heading Synopsis] 23434 23435Defined in header [include_file boost/beast/http/read.hpp] 23436 23437 23438 23439``` 23440template< 23441 class __SyncReadStream__, 23442 class __DynamicBuffer__, 23443 bool isRequest> 23444std::size_t 23445read_some( 23446 SyncReadStream& stream, 23447 DynamicBuffer& buffer, 23448 basic_parser< isRequest >& parser); 23449 23450``` 23451 23452[heading Description] 23453This function is used to read part of a message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 23454 23455* A call to [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] with a non-empty buffer sequence is successful. 23456 23457 23458* An error occurs. 23459 23460This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23461If the end of file error is received while reading from the stream, then the error returned from this function will be: 23462 23463* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23464 23465 23466* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23467 23468 23469* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23470 23471[heading Parameters] 23472[table [[Name][Description]] 23473 [[`stream`][ 23474 23475The stream from which the data is to be read. The type must meet the ['SyncReadStream] requirements. 23476 ]] 23477 [[`buffer`][ 23478 23479Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23480 ]] 23481 [[`parser`][ 23482 23483The parser to use. 23484 ]] 23485] 23486[heading Return Value] 23487The number of bytes transferred from the stream. 23488[heading Exceptions] 23489[table [[Type][Thrown On]] 23490 [[`system_error`][ 23491 23492Thrown on failure. 23493 ]] 23494] 23495[heading Remarks] 23496The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. 23497 23498 23499 23500Convenience header [include_file boost/beast/http.hpp] 23501 23502[endsect] 23503[section:overload2 http::read_some (2 of 2 overloads)] 23504Read part of a message from a stream using a parser. 23505[heading Synopsis] 23506 23507Defined in header [include_file boost/beast/http/read.hpp] 23508 23509 23510 23511``` 23512template< 23513 class __SyncReadStream__, 23514 class __DynamicBuffer__, 23515 bool isRequest> 23516std::size_t 23517read_some( 23518 SyncReadStream& stream, 23519 DynamicBuffer& buffer, 23520 basic_parser< isRequest >& parser, 23521 error_code& ec); 23522 23523``` 23524 23525[heading Description] 23526This function is used to read part of a message from a stream into an instance of [link beast.ref.boost__beast__http__basic_parser `http::basic_parser`]. The call will block until one of the following conditions is true: 23527 23528* A call to [link beast.ref.boost__beast__http__basic_parser.put `http::basic_parser::put`] with a non-empty buffer sequence is successful. 23529 23530 23531* An error occurs. 23532 23533This operation is implemented in terms of one or more calls to the stream's `read_some` function. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads. 23534If the end of file error is received while reading from the stream, then the error returned from this function will be: 23535 23536* [link beast.ref.boost__beast__http__error `http::end_of_stream`] if no bytes were parsed, or 23537 23538 23539* [link beast.ref.boost__beast__http__error `http::partial_message`] if any bytes were parsed but the message was incomplete, otherwise: 23540 23541 23542* A successful result. The next attempt to read will return [link beast.ref.boost__beast__http__error `http::end_of_stream`] 23543 23544[heading Parameters] 23545[table [[Name][Description]] 23546 [[`stream`][ 23547 23548The stream from which the data is to be read. The type must support the ['SyncReadStream] requirements. 23549 ]] 23550 [[`buffer`][ 23551 23552Storage for additional bytes read by the implementation from the stream. This is both an input and an output parameter; on entry, the parser will be presented with any remaining data in the dynamic buffer's readable bytes sequence first. The type must meet the ['DynamicBuffer] requirements. 23553 ]] 23554 [[`parser`][ 23555 23556The parser to use. 23557 ]] 23558 [[`ec`][ 23559 23560Set to the error, if any occurred. 23561 ]] 23562] 23563[heading Return Value] 23564The number of bytes transferred from the stream. 23565[heading Remarks] 23566The function returns the total number of bytes transferred from the stream. This may be zero for the case where there is sufficient pre-existing message data in the dynamic buffer. 23567 23568 23569 23570Convenience header [include_file boost/beast/http.hpp] 23571 23572[endsect] 23573[endsect] 23574 23575 23576 23577[section:boost__beast__http__request http::request] 23578[indexterm1 http::request] 23579A typical HTTP request. 23580[heading Synopsis] 23581 23582Defined in header [include_file boost/beast/http/message.hpp] 23583 23584 23585 23586``` 23587template< 23588 class __Body__, 23589 class __Fields__ = fields> 23590using request = message< true, Body, Fields >; 23591``` 23592[heading Types] 23593[table [[Name][Description]] 23594 [ 23595 [[link beast.ref.boost__beast__http__message.body_type [*body_type]]] 23596 [ 23597 The type providing the body traits. 23598 ] 23599 ] 23600 [ 23601 [[link beast.ref.boost__beast__http__message.fields_type [*fields_type]]] 23602 [ 23603 The type representing the fields. 23604 ] 23605 ] 23606 [ 23607 [[link beast.ref.boost__beast__http__message.header_type [*header_type]]] 23608 [ 23609 The base class used to hold the header portion of the message. 23610 ] 23611 ] 23612 [ 23613 [[link beast.ref.boost__beast__http__message.is_request [*is_request]]] 23614 [ 23615 Indicates if the header is a request or response. 23616 ] 23617 ] 23618] 23619[heading Member Functions] 23620[table [[Name][Description]] 23621 [ 23622 [[link beast.ref.boost__beast__http__message.base [*base]]] 23623 [ 23624 Returns the header portion of the message. 23625 ] 23626 ] 23627 [ 23628 [[link beast.ref.boost__beast__http__message.body [*body]]] 23629 [ 23630 Returns the body. 23631 ] 23632 ] 23633 [ 23634 [[link beast.ref.boost__beast__http__message.chunked [*chunked]]] 23635 [ 23636 Returns true if the chunked Transfer-Encoding is specified. 23637 23638 Set or clear the chunked Transfer-Encoding. 23639 ] 23640 ] 23641 [ 23642 [[link beast.ref.boost__beast__http__message.content_length [*content_length]]] 23643 [ 23644 Set or clear the Content-Length field. 23645 ] 23646 ] 23647 [ 23648 [[link beast.ref.boost__beast__http__message.has_content_length [*has_content_length]]] 23649 [ 23650 Returns true if the Content-Length field is present. 23651 ] 23652 ] 23653 [ 23654 [[link beast.ref.boost__beast__http__message.keep_alive [*keep_alive]]] 23655 [ 23656 Returns true if the message semantics indicate keep-alive. 23657 23658 Set the keep-alive message semantic option. 23659 ] 23660 ] 23661 [ 23662 [[link beast.ref.boost__beast__http__message.message [*message]]] 23663 [ 23664 Constructor. 23665 23666 Construct a message. 23667 ] 23668 ] 23669 [ 23670 [[link beast.ref.boost__beast__http__message.method [*method]]] 23671 [ 23672 Return the request-method verb. 23673 23674 Set the request-method. 23675 ] 23676 ] 23677 [ 23678 [[link beast.ref.boost__beast__http__message.method_string [*method_string]]] 23679 [ 23680 Return the request-method as a string. 23681 ] 23682 ] 23683 [ 23684 [[link beast.ref.boost__beast__http__message.need_eof [*need_eof]]] 23685 [ 23686 Returns true if the message semantics require an end of file. 23687 ] 23688 ] 23689 [ 23690 [[link beast.ref.boost__beast__http__message.operator_eq_ [*operator=]]] 23691 [ 23692 Assignment. 23693 ] 23694 ] 23695 [ 23696 [[link beast.ref.boost__beast__http__message.payload_size [*payload_size]]] 23697 [ 23698 Returns the payload size of the body in octets if possible. 23699 ] 23700 ] 23701 [ 23702 [[link beast.ref.boost__beast__http__message.prepare_payload [*prepare_payload]]] 23703 [ 23704 Prepare the message payload fields for the body. 23705 ] 23706 ] 23707 [ 23708 [[link beast.ref.boost__beast__http__message.reason [*reason]]] 23709 [ 23710 Return the response reason-phrase. 23711 23712 Set the response reason-phrase (deprecated) 23713 ] 23714 ] 23715 [ 23716 [[link beast.ref.boost__beast__http__message.result [*result]]] 23717 [ 23718 The response status-code result. 23719 23720 Set the response status-code. 23721 23722 Set the response status-code as an integer. 23723 ] 23724 ] 23725 [ 23726 [[link beast.ref.boost__beast__http__message.result_int [*result_int]]] 23727 [ 23728 The response status-code expressed as an integer. 23729 ] 23730 ] 23731 [ 23732 [[link beast.ref.boost__beast__http__message.target [*target]]] 23733 [ 23734 Returns the request-target string. 23735 23736 Set the request-target string. 23737 ] 23738 ] 23739 [ 23740 [[link beast.ref.boost__beast__http__message.version [*version]]] 23741 [ 23742 Return the HTTP-version. 23743 23744 Set the HTTP-version. 23745 ] 23746 ] 23747] 23748This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 23749A message can be a request or response, depending on the `isRequest` template argument value. Requests and responses have different types; functions may be overloaded based on the type if desired. 23750The `Body` template argument type determines the model used to read or write the content body of the message. 23751Newly constructed messages objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 23752[heading Template Parameters] 23753[table [[Type][Description]] 23754 [[`isRequest`][ 23755 23756`true` if this represents a request, or `false` if this represents a response. Some class data members are conditionally present depending on this value. 23757 ]] 23758 [[`Body`][ 23759 23760A type meeting the requirements of Body. 23761 ]] 23762 [[`Fields`][ 23763 23764The type of container used to hold the field value pairs. 23765 ]] 23766] 23767 23768[heading Description] 23769 23770 23771 23772Convenience header [include_file boost/beast/http.hpp] 23773 23774[endsect] 23775[section:boost__beast__http__request_header http::request_header] 23776[indexterm1 http::request_header] 23777A typical HTTP request header. 23778[heading Synopsis] 23779 23780Defined in header [include_file boost/beast/http/message.hpp] 23781 23782 23783 23784``` 23785template< 23786 class __Fields__ = fields> 23787using request_header = header< true, Fields >; 23788``` 23789[heading Types] 23790[table [[Name][Description]] 23791 [ 23792 [[link beast.ref.boost__beast__http__header.fields_type [*fields_type]]] 23793 [ 23794 The type representing the fields. 23795 ] 23796 ] 23797 [ 23798 [[link beast.ref.boost__beast__http__header.is_request [*is_request]]] 23799 [ 23800 Indicates if the header is a request or response. 23801 ] 23802 ] 23803] 23804[heading Member Functions] 23805[table [[Name][Description]] 23806 [ 23807 [[link beast.ref.boost__beast__http__header.header [*header]]] 23808 [ 23809 Constructor. 23810 ] 23811 ] 23812 [ 23813 [[link beast.ref.boost__beast__http__header.method [*method]]] 23814 [ 23815 Return the request-method verb. 23816 23817 Set the request-method. 23818 ] 23819 ] 23820 [ 23821 [[link beast.ref.boost__beast__http__header.method_string [*method_string]]] 23822 [ 23823 Return the request-method as a string. 23824 ] 23825 ] 23826 [ 23827 [[link beast.ref.boost__beast__http__header.operator_eq_ [*operator=]]] 23828 [ 23829 Assignment. 23830 ] 23831 ] 23832 [ 23833 [[link beast.ref.boost__beast__http__header.reason [*reason]]] 23834 [ 23835 Return the response reason-phrase. 23836 23837 Set the response reason-phrase (deprecated) 23838 ] 23839 ] 23840 [ 23841 [[link beast.ref.boost__beast__http__header.result [*result]]] 23842 [ 23843 The response status-code result. 23844 23845 Set the response status-code. 23846 23847 Set the response status-code as an integer. 23848 ] 23849 ] 23850 [ 23851 [[link beast.ref.boost__beast__http__header.result_int [*result_int]]] 23852 [ 23853 The response status-code expressed as an integer. 23854 ] 23855 ] 23856 [ 23857 [[link beast.ref.boost__beast__http__header.target [*target]]] 23858 [ 23859 Returns the request-target string. 23860 23861 Set the request-target string. 23862 ] 23863 ] 23864 [ 23865 [[link beast.ref.boost__beast__http__header.version [*version]]] 23866 [ 23867 Return the HTTP-version. 23868 23869 Set the HTTP-version. 23870 ] 23871 ] 23872] 23873This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 23874Newly constructed header objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 23875A `header` includes the start-line and header-fields. 23876[heading Description] 23877 23878 23879 23880Convenience header [include_file boost/beast/http.hpp] 23881 23882[endsect] 23883[section:boost__beast__http__request_parser http::request_parser] 23884[indexterm1 http::request_parser] 23885An HTTP/1 parser for producing a request message. 23886[heading Synopsis] 23887 23888Defined in header [include_file boost/beast/http/parser.hpp] 23889 23890 23891 23892``` 23893template< 23894 class __Body__, 23895 class __Allocator__ = std::allocator<char>> 23896using request_parser = parser< true, Body, Allocator >; 23897``` 23898[heading Types] 23899[table [[Name][Description]] 23900 [ 23901 [[link beast.ref.boost__beast__http__parser.is_request [*is_request]]] 23902 [ 23903 true if this parser parses requests, false for responses. 23904 ] 23905 ] 23906 [ 23907 [[link beast.ref.boost__beast__http__parser.value_type [*value_type]]] 23908 [ 23909 The type of message returned by the parser. 23910 ] 23911 ] 23912] 23913[heading Member Functions] 23914[table [[Name][Description]] 23915 [ 23916 [[link beast.ref.boost__beast__http__parser.body_limit [*body_limit]]] 23917 [ 23918 Set the limit on the payload body. 23919 ] 23920 ] 23921 [ 23922 [[link beast.ref.boost__beast__http__parser.chunked [*chunked]]] 23923 [ 23924 Returns true if the last value for Transfer-Encoding is "chunked". 23925 ] 23926 ] 23927 [ 23928 [[link beast.ref.boost__beast__http__parser.content_length [*content_length]]] 23929 [ 23930 Returns the optional value of Content-Length if known. 23931 ] 23932 ] 23933 [ 23934 [[link beast.ref.boost__beast__http__parser.content_length_remaining [*content_length_remaining]]] 23935 [ 23936 Returns the remaining content length if known. 23937 ] 23938 ] 23939 [ 23940 [[link beast.ref.boost__beast__http__parser.eager [*eager]]] 23941 [ 23942 Returns true if the eager parse option is set. 23943 23944 Set the eager parse option. 23945 ] 23946 ] 23947 [ 23948 [[link beast.ref.boost__beast__http__parser.get [*get]]] 23949 [ 23950 Returns the parsed message. 23951 ] 23952 ] 23953 [ 23954 [[link beast.ref.boost__beast__http__parser.got_some [*got_some]]] 23955 [ 23956 Returns true if the parser has received at least one byte of input. 23957 ] 23958 ] 23959 [ 23960 [[link beast.ref.boost__beast__http__parser.header_limit [*header_limit]]] 23961 [ 23962 Set a limit on the total size of the header. 23963 ] 23964 ] 23965 [ 23966 [[link beast.ref.boost__beast__http__parser.is_done [*is_done]]] 23967 [ 23968 Returns true if the message is complete. 23969 ] 23970 ] 23971 [ 23972 [[link beast.ref.boost__beast__http__parser.is_header_done [*is_header_done]]] 23973 [ 23974 Returns true if a the parser has produced the full header. 23975 ] 23976 ] 23977 [ 23978 [[link beast.ref.boost__beast__http__parser.keep_alive [*keep_alive]]] 23979 [ 23980 Returns true if the message has keep-alive connection semantics. 23981 ] 23982 ] 23983 [ 23984 [[link beast.ref.boost__beast__http__parser.need_eof [*need_eof]]] 23985 [ 23986 Returns true if the message semantics require an end of file. 23987 ] 23988 ] 23989 [ 23990 [[link beast.ref.boost__beast__http__parser.on_chunk_body [*on_chunk_body]]] 23991 [ 23992 Set a callback to be invoked on chunk body data. 23993 ] 23994 ] 23995 [ 23996 [[link beast.ref.boost__beast__http__parser.on_chunk_header [*on_chunk_header]]] 23997 [ 23998 Set a callback to be invoked on each chunk header. 23999 ] 24000 ] 24001 [ 24002 [[link beast.ref.boost__beast__http__parser.operator_eq_ [*operator=]]] 24003 [ 24004 Assignment (disallowed) 24005 ] 24006 ] 24007 [ 24008 [[link beast.ref.boost__beast__http__parser.parser [*parser]]] 24009 [ 24010 Constructor (disallowed) 24011 24012 Constructor. 24013 24014 Construct a parser from another parser, changing the Body type. 24015 ] 24016 ] 24017 [ 24018 [[link beast.ref.boost__beast__http__parser.put [*put]]] 24019 [ 24020 Write a buffer sequence to the parser. 24021 ] 24022 ] 24023 [ 24024 [[link beast.ref.boost__beast__http__parser.put_eof [*put_eof]]] 24025 [ 24026 Inform the parser that the end of stream was reached. 24027 ] 24028 ] 24029 [ 24030 [[link beast.ref.boost__beast__http__parser.release [*release]]] 24031 [ 24032 Returns ownership of the parsed message. 24033 ] 24034 ] 24035 [ 24036 [[link beast.ref.boost__beast__http__parser.skip [*skip]]] 24037 [ 24038 Returns true if the skip parse option is set. 24039 24040 Set the skip parse option. 24041 ] 24042 ] 24043 [ 24044 [[link beast.ref.boost__beast__http__parser.upgrade [*upgrade]]] 24045 [ 24046 Returns true if the message is an upgrade message. 24047 ] 24048 ] 24049 [ 24050 [[link beast.ref.boost__beast__http__parser.parser_dtor_ [*~parser]]] 24051 [ 24052 Destructor. 24053 ] 24054 ] 24055] 24056This class uses the basic HTTP/1 wire format parser to convert a series of octets into a [link beast.ref.boost__beast__http__message `http::message`] using the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container to represent the fields. 24057[heading Template Parameters] 24058[table [[Type][Description]] 24059 [[`isRequest`][ 24060 24061Indicates whether a request or response will be parsed. 24062 ]] 24063 [[`Body`][ 24064 24065The type used to represent the body. This must meet the requirements of ['Body]. 24066 ]] 24067 [[`Allocator`][ 24068 24069The type of allocator used with the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container. 24070 ]] 24071] 24072[heading Remarks] 24073A new instance of the parser is required for each message. 24074 24075[heading Description] 24076 24077 24078 24079Convenience header [include_file boost/beast/http.hpp] 24080 24081[endsect] 24082[section:boost__beast__http__request_serializer http::request_serializer] 24083[indexterm1 http::request_serializer] 24084A serializer for HTTP/1 requests. 24085[heading Synopsis] 24086 24087Defined in header [include_file boost/beast/http/serializer.hpp] 24088 24089 24090 24091``` 24092template< 24093 class __Body__, 24094 class __Fields__ = fields> 24095using request_serializer = serializer< true, Body, Fields >; 24096``` 24097[heading Types] 24098[table [[Name][Description]] 24099 [ 24100 [[link beast.ref.boost__beast__http__serializer.value_type [*value_type]]] 24101 [ 24102 The type of message this serializer uses. 24103 ] 24104 ] 24105] 24106[heading Member Functions] 24107[table [[Name][Description]] 24108 [ 24109 [[link beast.ref.boost__beast__http__serializer.consume [*consume]]] 24110 [ 24111 Consume buffer octets in the serialization. 24112 ] 24113 ] 24114 [ 24115 [[link beast.ref.boost__beast__http__serializer.get [*get]]] 24116 [ 24117 Returns the message being serialized. 24118 ] 24119 ] 24120 [ 24121 [[link beast.ref.boost__beast__http__serializer.is_done [*is_done]]] 24122 [ 24123 Return true if serialization is complete. 24124 ] 24125 ] 24126 [ 24127 [[link beast.ref.boost__beast__http__serializer.is_header_done [*is_header_done]]] 24128 [ 24129 Return true if serialization of the header is complete. 24130 ] 24131 ] 24132 [ 24133 [[link beast.ref.boost__beast__http__serializer.limit [*limit]]] 24134 [ 24135 Returns the serialized buffer size limit. 24136 24137 Set the serialized buffer size limit. 24138 ] 24139 ] 24140 [ 24141 [[link beast.ref.boost__beast__http__serializer.next [*next]]] 24142 [ 24143 Returns the next set of buffers in the serialization. 24144 ] 24145 ] 24146 [ 24147 [[link beast.ref.boost__beast__http__serializer.operator_eq_ [*operator=]]] 24148 [ 24149 Assignment. 24150 ] 24151 ] 24152 [ 24153 [[link beast.ref.boost__beast__http__serializer.serializer [*serializer]]] 24154 [ 24155 Constructor. 24156 ] 24157 ] 24158 [ 24159 [[link beast.ref.boost__beast__http__serializer.split [*split]]] 24160 [ 24161 Returns true if we will pause after writing the complete header. 24162 24163 Set whether the header and body are written separately. 24164 ] 24165 ] 24166 [ 24167 [[link beast.ref.boost__beast__http__serializer.writer_impl [*writer_impl]]] 24168 [ 24169 Provides low-level access to the associated BodyWriter 24170 ] 24171 ] 24172] 24173An object of this type is used to serialize a complete HTTP message into a sequence of octets. To use this class, construct an instance with the message to be serialized. The implementation will automatically perform chunk encoding if the contents of the message indicate that chunk encoding is required. 24174Chunked output produced by the serializer never contains chunk extensions or trailers, and the location of chunk boundaries is not specified. If callers require chunk extensions, trailers, or control over the exact contents of each chunk they should use the serializer to write just the message header, and then assume control over serializing the chunked payload by using the chunk buffer sequence types [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`], [link beast.ref.boost__beast__http__chunk_crlf `http::chunk_crlf`], [link beast.ref.boost__beast__http__chunk_header `http::chunk_header`], and [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. 24175[heading Template Parameters] 24176[table [[Type][Description]] 24177 [[`isRequest`][ 24178 24179`true` if the message is a request. 24180 ]] 24181 [[`Body`][ 24182 24183The body type of the message. 24184 ]] 24185 [[`Fields`][ 24186 24187The type of fields in the message. 24188 ]] 24189] 24190 24191[heading Description] 24192 24193 24194 24195Convenience header [include_file boost/beast/http.hpp] 24196 24197[endsect] 24198[section:boost__beast__http__response http::response] 24199[indexterm1 http::response] 24200A typical HTTP response. 24201[heading Synopsis] 24202 24203Defined in header [include_file boost/beast/http/message.hpp] 24204 24205 24206 24207``` 24208template< 24209 class __Body__, 24210 class __Fields__ = fields> 24211using response = message< false, Body, Fields >; 24212``` 24213[heading Types] 24214[table [[Name][Description]] 24215 [ 24216 [[link beast.ref.boost__beast__http__message.body_type [*body_type]]] 24217 [ 24218 The type providing the body traits. 24219 ] 24220 ] 24221 [ 24222 [[link beast.ref.boost__beast__http__message.fields_type [*fields_type]]] 24223 [ 24224 The type representing the fields. 24225 ] 24226 ] 24227 [ 24228 [[link beast.ref.boost__beast__http__message.header_type [*header_type]]] 24229 [ 24230 The base class used to hold the header portion of the message. 24231 ] 24232 ] 24233 [ 24234 [[link beast.ref.boost__beast__http__message.is_request [*is_request]]] 24235 [ 24236 Indicates if the header is a request or response. 24237 ] 24238 ] 24239] 24240[heading Member Functions] 24241[table [[Name][Description]] 24242 [ 24243 [[link beast.ref.boost__beast__http__message.base [*base]]] 24244 [ 24245 Returns the header portion of the message. 24246 ] 24247 ] 24248 [ 24249 [[link beast.ref.boost__beast__http__message.body [*body]]] 24250 [ 24251 Returns the body. 24252 ] 24253 ] 24254 [ 24255 [[link beast.ref.boost__beast__http__message.chunked [*chunked]]] 24256 [ 24257 Returns true if the chunked Transfer-Encoding is specified. 24258 24259 Set or clear the chunked Transfer-Encoding. 24260 ] 24261 ] 24262 [ 24263 [[link beast.ref.boost__beast__http__message.content_length [*content_length]]] 24264 [ 24265 Set or clear the Content-Length field. 24266 ] 24267 ] 24268 [ 24269 [[link beast.ref.boost__beast__http__message.has_content_length [*has_content_length]]] 24270 [ 24271 Returns true if the Content-Length field is present. 24272 ] 24273 ] 24274 [ 24275 [[link beast.ref.boost__beast__http__message.keep_alive [*keep_alive]]] 24276 [ 24277 Returns true if the message semantics indicate keep-alive. 24278 24279 Set the keep-alive message semantic option. 24280 ] 24281 ] 24282 [ 24283 [[link beast.ref.boost__beast__http__message.message [*message]]] 24284 [ 24285 Constructor. 24286 24287 Construct a message. 24288 ] 24289 ] 24290 [ 24291 [[link beast.ref.boost__beast__http__message.method [*method]]] 24292 [ 24293 Return the request-method verb. 24294 24295 Set the request-method. 24296 ] 24297 ] 24298 [ 24299 [[link beast.ref.boost__beast__http__message.method_string [*method_string]]] 24300 [ 24301 Return the request-method as a string. 24302 ] 24303 ] 24304 [ 24305 [[link beast.ref.boost__beast__http__message.need_eof [*need_eof]]] 24306 [ 24307 Returns true if the message semantics require an end of file. 24308 ] 24309 ] 24310 [ 24311 [[link beast.ref.boost__beast__http__message.operator_eq_ [*operator=]]] 24312 [ 24313 Assignment. 24314 ] 24315 ] 24316 [ 24317 [[link beast.ref.boost__beast__http__message.payload_size [*payload_size]]] 24318 [ 24319 Returns the payload size of the body in octets if possible. 24320 ] 24321 ] 24322 [ 24323 [[link beast.ref.boost__beast__http__message.prepare_payload [*prepare_payload]]] 24324 [ 24325 Prepare the message payload fields for the body. 24326 ] 24327 ] 24328 [ 24329 [[link beast.ref.boost__beast__http__message.reason [*reason]]] 24330 [ 24331 Return the response reason-phrase. 24332 24333 Set the response reason-phrase (deprecated) 24334 ] 24335 ] 24336 [ 24337 [[link beast.ref.boost__beast__http__message.result [*result]]] 24338 [ 24339 The response status-code result. 24340 24341 Set the response status-code. 24342 24343 Set the response status-code as an integer. 24344 ] 24345 ] 24346 [ 24347 [[link beast.ref.boost__beast__http__message.result_int [*result_int]]] 24348 [ 24349 The response status-code expressed as an integer. 24350 ] 24351 ] 24352 [ 24353 [[link beast.ref.boost__beast__http__message.target [*target]]] 24354 [ 24355 Returns the request-target string. 24356 24357 Set the request-target string. 24358 ] 24359 ] 24360 [ 24361 [[link beast.ref.boost__beast__http__message.version [*version]]] 24362 [ 24363 Return the HTTP-version. 24364 24365 Set the HTTP-version. 24366 ] 24367 ] 24368] 24369This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 24370A message can be a request or response, depending on the `isRequest` template argument value. Requests and responses have different types; functions may be overloaded based on the type if desired. 24371The `Body` template argument type determines the model used to read or write the content body of the message. 24372Newly constructed messages objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 24373[heading Template Parameters] 24374[table [[Type][Description]] 24375 [[`isRequest`][ 24376 24377`true` if this represents a request, or `false` if this represents a response. Some class data members are conditionally present depending on this value. 24378 ]] 24379 [[`Body`][ 24380 24381A type meeting the requirements of Body. 24382 ]] 24383 [[`Fields`][ 24384 24385The type of container used to hold the field value pairs. 24386 ]] 24387] 24388 24389[heading Description] 24390 24391 24392 24393Convenience header [include_file boost/beast/http.hpp] 24394 24395[endsect] 24396[section:boost__beast__http__response_header http::response_header] 24397[indexterm1 http::response_header] 24398A typical HTTP response header. 24399[heading Synopsis] 24400 24401Defined in header [include_file boost/beast/http/message.hpp] 24402 24403 24404 24405``` 24406template< 24407 class __Fields__ = fields> 24408using response_header = header< false, Fields >; 24409``` 24410[heading Types] 24411[table [[Name][Description]] 24412 [ 24413 [[link beast.ref.boost__beast__http__header.fields_type [*fields_type]]] 24414 [ 24415 The type representing the fields. 24416 ] 24417 ] 24418 [ 24419 [[link beast.ref.boost__beast__http__header.is_request [*is_request]]] 24420 [ 24421 Indicates if the header is a request or response. 24422 ] 24423 ] 24424] 24425[heading Member Functions] 24426[table [[Name][Description]] 24427 [ 24428 [[link beast.ref.boost__beast__http__header.header [*header]]] 24429 [ 24430 Constructor. 24431 ] 24432 ] 24433 [ 24434 [[link beast.ref.boost__beast__http__header.method [*method]]] 24435 [ 24436 Return the request-method verb. 24437 24438 Set the request-method. 24439 ] 24440 ] 24441 [ 24442 [[link beast.ref.boost__beast__http__header.method_string [*method_string]]] 24443 [ 24444 Return the request-method as a string. 24445 ] 24446 ] 24447 [ 24448 [[link beast.ref.boost__beast__http__header.operator_eq_ [*operator=]]] 24449 [ 24450 Assignment. 24451 ] 24452 ] 24453 [ 24454 [[link beast.ref.boost__beast__http__header.reason [*reason]]] 24455 [ 24456 Return the response reason-phrase. 24457 24458 Set the response reason-phrase (deprecated) 24459 ] 24460 ] 24461 [ 24462 [[link beast.ref.boost__beast__http__header.result [*result]]] 24463 [ 24464 The response status-code result. 24465 24466 Set the response status-code. 24467 24468 Set the response status-code as an integer. 24469 ] 24470 ] 24471 [ 24472 [[link beast.ref.boost__beast__http__header.result_int [*result_int]]] 24473 [ 24474 The response status-code expressed as an integer. 24475 ] 24476 ] 24477 [ 24478 [[link beast.ref.boost__beast__http__header.target [*target]]] 24479 [ 24480 Returns the request-target string. 24481 24482 Set the request-target string. 24483 ] 24484 ] 24485 [ 24486 [[link beast.ref.boost__beast__http__header.version [*version]]] 24487 [ 24488 Return the HTTP-version. 24489 24490 Set the HTTP-version. 24491 ] 24492 ] 24493] 24494This container is derived from the `Fields` template type. To understand all of the members of this class it is necessary to view the declaration for the `Fields` type. When using the default fields container, those declarations are in [link beast.ref.boost__beast__http__fields `http::fields`]. 24495Newly constructed header objects have version set to HTTP/1.1. Newly constructed response objects also have result code set to [link beast.ref.boost__beast__http__status `http::ok`]. 24496A `header` includes the start-line and header-fields. 24497[heading Description] 24498 24499 24500 24501Convenience header [include_file boost/beast/http.hpp] 24502 24503[endsect] 24504[section:boost__beast__http__response_parser http::response_parser] 24505[indexterm1 http::response_parser] 24506An HTTP/1 parser for producing a response message. 24507[heading Synopsis] 24508 24509Defined in header [include_file boost/beast/http/parser.hpp] 24510 24511 24512 24513``` 24514template< 24515 class __Body__, 24516 class __Allocator__ = std::allocator<char>> 24517using response_parser = parser< false, Body, Allocator >; 24518``` 24519[heading Types] 24520[table [[Name][Description]] 24521 [ 24522 [[link beast.ref.boost__beast__http__parser.is_request [*is_request]]] 24523 [ 24524 true if this parser parses requests, false for responses. 24525 ] 24526 ] 24527 [ 24528 [[link beast.ref.boost__beast__http__parser.value_type [*value_type]]] 24529 [ 24530 The type of message returned by the parser. 24531 ] 24532 ] 24533] 24534[heading Member Functions] 24535[table [[Name][Description]] 24536 [ 24537 [[link beast.ref.boost__beast__http__parser.body_limit [*body_limit]]] 24538 [ 24539 Set the limit on the payload body. 24540 ] 24541 ] 24542 [ 24543 [[link beast.ref.boost__beast__http__parser.chunked [*chunked]]] 24544 [ 24545 Returns true if the last value for Transfer-Encoding is "chunked". 24546 ] 24547 ] 24548 [ 24549 [[link beast.ref.boost__beast__http__parser.content_length [*content_length]]] 24550 [ 24551 Returns the optional value of Content-Length if known. 24552 ] 24553 ] 24554 [ 24555 [[link beast.ref.boost__beast__http__parser.content_length_remaining [*content_length_remaining]]] 24556 [ 24557 Returns the remaining content length if known. 24558 ] 24559 ] 24560 [ 24561 [[link beast.ref.boost__beast__http__parser.eager [*eager]]] 24562 [ 24563 Returns true if the eager parse option is set. 24564 24565 Set the eager parse option. 24566 ] 24567 ] 24568 [ 24569 [[link beast.ref.boost__beast__http__parser.get [*get]]] 24570 [ 24571 Returns the parsed message. 24572 ] 24573 ] 24574 [ 24575 [[link beast.ref.boost__beast__http__parser.got_some [*got_some]]] 24576 [ 24577 Returns true if the parser has received at least one byte of input. 24578 ] 24579 ] 24580 [ 24581 [[link beast.ref.boost__beast__http__parser.header_limit [*header_limit]]] 24582 [ 24583 Set a limit on the total size of the header. 24584 ] 24585 ] 24586 [ 24587 [[link beast.ref.boost__beast__http__parser.is_done [*is_done]]] 24588 [ 24589 Returns true if the message is complete. 24590 ] 24591 ] 24592 [ 24593 [[link beast.ref.boost__beast__http__parser.is_header_done [*is_header_done]]] 24594 [ 24595 Returns true if a the parser has produced the full header. 24596 ] 24597 ] 24598 [ 24599 [[link beast.ref.boost__beast__http__parser.keep_alive [*keep_alive]]] 24600 [ 24601 Returns true if the message has keep-alive connection semantics. 24602 ] 24603 ] 24604 [ 24605 [[link beast.ref.boost__beast__http__parser.need_eof [*need_eof]]] 24606 [ 24607 Returns true if the message semantics require an end of file. 24608 ] 24609 ] 24610 [ 24611 [[link beast.ref.boost__beast__http__parser.on_chunk_body [*on_chunk_body]]] 24612 [ 24613 Set a callback to be invoked on chunk body data. 24614 ] 24615 ] 24616 [ 24617 [[link beast.ref.boost__beast__http__parser.on_chunk_header [*on_chunk_header]]] 24618 [ 24619 Set a callback to be invoked on each chunk header. 24620 ] 24621 ] 24622 [ 24623 [[link beast.ref.boost__beast__http__parser.operator_eq_ [*operator=]]] 24624 [ 24625 Assignment (disallowed) 24626 ] 24627 ] 24628 [ 24629 [[link beast.ref.boost__beast__http__parser.parser [*parser]]] 24630 [ 24631 Constructor (disallowed) 24632 24633 Constructor. 24634 24635 Construct a parser from another parser, changing the Body type. 24636 ] 24637 ] 24638 [ 24639 [[link beast.ref.boost__beast__http__parser.put [*put]]] 24640 [ 24641 Write a buffer sequence to the parser. 24642 ] 24643 ] 24644 [ 24645 [[link beast.ref.boost__beast__http__parser.put_eof [*put_eof]]] 24646 [ 24647 Inform the parser that the end of stream was reached. 24648 ] 24649 ] 24650 [ 24651 [[link beast.ref.boost__beast__http__parser.release [*release]]] 24652 [ 24653 Returns ownership of the parsed message. 24654 ] 24655 ] 24656 [ 24657 [[link beast.ref.boost__beast__http__parser.skip [*skip]]] 24658 [ 24659 Returns true if the skip parse option is set. 24660 24661 Set the skip parse option. 24662 ] 24663 ] 24664 [ 24665 [[link beast.ref.boost__beast__http__parser.upgrade [*upgrade]]] 24666 [ 24667 Returns true if the message is an upgrade message. 24668 ] 24669 ] 24670 [ 24671 [[link beast.ref.boost__beast__http__parser.parser_dtor_ [*~parser]]] 24672 [ 24673 Destructor. 24674 ] 24675 ] 24676] 24677This class uses the basic HTTP/1 wire format parser to convert a series of octets into a [link beast.ref.boost__beast__http__message `http::message`] using the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container to represent the fields. 24678[heading Template Parameters] 24679[table [[Type][Description]] 24680 [[`isRequest`][ 24681 24682Indicates whether a request or response will be parsed. 24683 ]] 24684 [[`Body`][ 24685 24686The type used to represent the body. This must meet the requirements of ['Body]. 24687 ]] 24688 [[`Allocator`][ 24689 24690The type of allocator used with the [link beast.ref.boost__beast__http__basic_fields `http::basic_fields`] container. 24691 ]] 24692] 24693[heading Remarks] 24694A new instance of the parser is required for each message. 24695 24696[heading Description] 24697 24698 24699 24700Convenience header [include_file boost/beast/http.hpp] 24701 24702[endsect] 24703[section:boost__beast__http__response_serializer http::response_serializer] 24704[indexterm1 http::response_serializer] 24705A serializer for HTTP/1 responses. 24706[heading Synopsis] 24707 24708Defined in header [include_file boost/beast/http/serializer.hpp] 24709 24710 24711 24712``` 24713template< 24714 class __Body__, 24715 class __Fields__ = fields> 24716using response_serializer = serializer< false, Body, Fields >; 24717``` 24718[heading Types] 24719[table [[Name][Description]] 24720 [ 24721 [[link beast.ref.boost__beast__http__serializer.value_type [*value_type]]] 24722 [ 24723 The type of message this serializer uses. 24724 ] 24725 ] 24726] 24727[heading Member Functions] 24728[table [[Name][Description]] 24729 [ 24730 [[link beast.ref.boost__beast__http__serializer.consume [*consume]]] 24731 [ 24732 Consume buffer octets in the serialization. 24733 ] 24734 ] 24735 [ 24736 [[link beast.ref.boost__beast__http__serializer.get [*get]]] 24737 [ 24738 Returns the message being serialized. 24739 ] 24740 ] 24741 [ 24742 [[link beast.ref.boost__beast__http__serializer.is_done [*is_done]]] 24743 [ 24744 Return true if serialization is complete. 24745 ] 24746 ] 24747 [ 24748 [[link beast.ref.boost__beast__http__serializer.is_header_done [*is_header_done]]] 24749 [ 24750 Return true if serialization of the header is complete. 24751 ] 24752 ] 24753 [ 24754 [[link beast.ref.boost__beast__http__serializer.limit [*limit]]] 24755 [ 24756 Returns the serialized buffer size limit. 24757 24758 Set the serialized buffer size limit. 24759 ] 24760 ] 24761 [ 24762 [[link beast.ref.boost__beast__http__serializer.next [*next]]] 24763 [ 24764 Returns the next set of buffers in the serialization. 24765 ] 24766 ] 24767 [ 24768 [[link beast.ref.boost__beast__http__serializer.operator_eq_ [*operator=]]] 24769 [ 24770 Assignment. 24771 ] 24772 ] 24773 [ 24774 [[link beast.ref.boost__beast__http__serializer.serializer [*serializer]]] 24775 [ 24776 Constructor. 24777 ] 24778 ] 24779 [ 24780 [[link beast.ref.boost__beast__http__serializer.split [*split]]] 24781 [ 24782 Returns true if we will pause after writing the complete header. 24783 24784 Set whether the header and body are written separately. 24785 ] 24786 ] 24787 [ 24788 [[link beast.ref.boost__beast__http__serializer.writer_impl [*writer_impl]]] 24789 [ 24790 Provides low-level access to the associated BodyWriter 24791 ] 24792 ] 24793] 24794An object of this type is used to serialize a complete HTTP message into a sequence of octets. To use this class, construct an instance with the message to be serialized. The implementation will automatically perform chunk encoding if the contents of the message indicate that chunk encoding is required. 24795Chunked output produced by the serializer never contains chunk extensions or trailers, and the location of chunk boundaries is not specified. If callers require chunk extensions, trailers, or control over the exact contents of each chunk they should use the serializer to write just the message header, and then assume control over serializing the chunked payload by using the chunk buffer sequence types [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`], [link beast.ref.boost__beast__http__chunk_crlf `http::chunk_crlf`], [link beast.ref.boost__beast__http__chunk_header `http::chunk_header`], and [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. 24796[heading Template Parameters] 24797[table [[Type][Description]] 24798 [[`isRequest`][ 24799 24800`true` if the message is a request. 24801 ]] 24802 [[`Body`][ 24803 24804The body type of the message. 24805 ]] 24806 [[`Fields`][ 24807 24808The type of fields in the message. 24809 ]] 24810] 24811 24812[heading Description] 24813 24814 24815 24816Convenience header [include_file boost/beast/http.hpp] 24817 24818[endsect] 24819[section:boost__beast__http__serializer http::serializer] 24820Provides buffer oriented HTTP message serialization functionality. 24821[heading Synopsis] 24822 24823Defined in header [include_file boost/beast/http/serializer.hpp] 24824 24825 24826 24827``` 24828template< 24829 bool isRequest, 24830 class __Body__, 24831 class __Fields__ = fields> 24832class serializer 24833``` 24834[heading Types] 24835[table [[Name][Description]] 24836 [ 24837 [[link beast.ref.boost__beast__http__serializer.value_type [*value_type]]] 24838 [ 24839 The type of message this serializer uses. 24840 ] 24841 ] 24842] 24843[heading Member Functions] 24844[table [[Name][Description]] 24845 [ 24846 [[link beast.ref.boost__beast__http__serializer.consume [*consume]]] 24847 [ 24848 Consume buffer octets in the serialization. 24849 ] 24850 ] 24851 [ 24852 [[link beast.ref.boost__beast__http__serializer.get [*get]]] 24853 [ 24854 Returns the message being serialized. 24855 ] 24856 ] 24857 [ 24858 [[link beast.ref.boost__beast__http__serializer.is_done [*is_done]]] 24859 [ 24860 Return true if serialization is complete. 24861 ] 24862 ] 24863 [ 24864 [[link beast.ref.boost__beast__http__serializer.is_header_done [*is_header_done]]] 24865 [ 24866 Return true if serialization of the header is complete. 24867 ] 24868 ] 24869 [ 24870 [[link beast.ref.boost__beast__http__serializer.limit [*limit]]] 24871 [ 24872 Returns the serialized buffer size limit. 24873 24874 Set the serialized buffer size limit. 24875 ] 24876 ] 24877 [ 24878 [[link beast.ref.boost__beast__http__serializer.next [*next]]] 24879 [ 24880 Returns the next set of buffers in the serialization. 24881 ] 24882 ] 24883 [ 24884 [[link beast.ref.boost__beast__http__serializer.operator_eq_ [*operator=]]] 24885 [ 24886 Assignment. 24887 ] 24888 ] 24889 [ 24890 [[link beast.ref.boost__beast__http__serializer.serializer [*serializer]]] 24891 [ 24892 Constructor. 24893 ] 24894 ] 24895 [ 24896 [[link beast.ref.boost__beast__http__serializer.split [*split]]] 24897 [ 24898 Returns true if we will pause after writing the complete header. 24899 24900 Set whether the header and body are written separately. 24901 ] 24902 ] 24903 [ 24904 [[link beast.ref.boost__beast__http__serializer.writer_impl [*writer_impl]]] 24905 [ 24906 Provides low-level access to the associated BodyWriter 24907 ] 24908 ] 24909] 24910 24911[heading Description] 24912An object of this type is used to serialize a complete HTTP message into a sequence of octets. To use this class, construct an instance with the message to be serialized. The implementation will automatically perform chunk encoding if the contents of the message indicate that chunk encoding is required. 24913Chunked output produced by the serializer never contains chunk extensions or trailers, and the location of chunk boundaries is not specified. If callers require chunk extensions, trailers, or control over the exact contents of each chunk they should use the serializer to write just the message header, and then assume control over serializing the chunked payload by using the chunk buffer sequence types [link beast.ref.boost__beast__http__chunk_body `http::chunk_body`], [link beast.ref.boost__beast__http__chunk_crlf `http::chunk_crlf`], [link beast.ref.boost__beast__http__chunk_header `http::chunk_header`], and [link beast.ref.boost__beast__http__chunk_last `http::chunk_last`]. 24914[heading Template Parameters] 24915[table [[Type][Description]] 24916 [[`isRequest`][ 24917 24918`true` if the message is a request. 24919 ]] 24920 [[`Body`][ 24921 24922The body type of the message. 24923 ]] 24924 [[`Fields`][ 24925 24926The type of fields in the message. 24927 ]] 24928] 24929[section:consume http::serializer::consume] 24930[indexterm2 consume..http::serializer] 24931Consume buffer octets in the serialization. 24932[heading Synopsis] 24933``` 24934void 24935consume( 24936 std::size_t n); 24937``` 24938 24939[heading Description] 24940This function should be called after one or more octets contained in the buffers provided in the prior call to [link beast.ref.boost__beast__http__serializer.next `http::serializer::next`] have been used. 24941After a call to [link beast.ref.boost__beast__http__serializer.consume `http::serializer::consume`], callers should check the return value of [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] to determine if the entire message has been serialized. 24942[heading Parameters] 24943[table [[Name][Description]] 24944 [[`n`][ 24945 24946The number of octets to consume. This number must be greater than zero and no greater than the number of octets in the buffers provided in the prior call to [link beast.ref.boost__beast__http__serializer.next `http::serializer::next`]. 24947 ]] 24948] 24949[endsect] 24950[section:get http::serializer::get] 24951[indexterm2 get..http::serializer] 24952Returns the message being serialized. 24953[heading Synopsis] 24954``` 24955value_type& 24956get(); 24957``` 24958 24959[heading Description] 24960[endsect] 24961[section:is_done http::serializer::is_done] 24962[indexterm2 is_done..http::serializer] 24963Return `true` if serialization is complete. 24964[heading Synopsis] 24965``` 24966bool 24967is_done(); 24968``` 24969 24970[heading Description] 24971The operation is complete when all octets corresponding to the serialized representation of the message have been successfully retrieved. [endsect] 24972[section:is_header_done http::serializer::is_header_done] 24973[indexterm2 is_header_done..http::serializer] 24974Return `true` if serialization of the header is complete. 24975[heading Synopsis] 24976``` 24977bool 24978is_header_done(); 24979``` 24980 24981[heading Description] 24982This function indicates whether or not all buffers containing serialized header octets have been retrieved. [endsect] 24983[section:limit http::serializer::limit] 24984[indexterm2 limit..http::serializer] 24985Returns the serialized buffer size limit. ``` 24986std::size_t 24987``[link beast.ref.boost__beast__http__serializer.limit.overload1 limit]``(); 24988 ``[''''»''' [link beast.ref.boost__beast__http__serializer.limit.overload1 more...]]`` 24989 24990``` 24991Set the serialized buffer size limit. ``` 24992void 24993``[link beast.ref.boost__beast__http__serializer.limit.overload2 limit]``( 24994 std::size_t limit); 24995 ``[''''»''' [link beast.ref.boost__beast__http__serializer.limit.overload2 more...]]`` 24996``` 24997[section:overload1 http::serializer::limit (1 of 2 overloads)] 24998Returns the serialized buffer size limit. 24999[heading Synopsis] 25000``` 25001std::size_t 25002limit(); 25003``` 25004 25005[heading Description] 25006[endsect] 25007[section:overload2 http::serializer::limit (2 of 2 overloads)] 25008Set the serialized buffer size limit. 25009[heading Synopsis] 25010``` 25011void 25012limit( 25013 std::size_t limit); 25014``` 25015 25016[heading Description] 25017This function adjusts the limit on the maximum size of the buffers passed to the visitor. The new size limit takes effect in the following call to [link beast.ref.boost__beast__http__serializer.next `http::serializer::next`]. 25018The default is no buffer size limit. 25019[heading Parameters] 25020[table [[Name][Description]] 25021 [[`limit`][ 25022 25023The new buffer size limit. If this number is zero, the size limit is removed. 25024 ]] 25025] 25026[endsect] 25027[endsect] 25028 25029[section:next http::serializer::next] 25030[indexterm2 next..http::serializer] 25031Returns the next set of buffers in the serialization. 25032[heading Synopsis] 25033``` 25034template< 25035 class Visit> 25036void 25037next( 25038 error_code& ec, 25039 Visit&& visit); 25040``` 25041 25042[heading Description] 25043This function will attempt to call the `visit` function object with a ['ConstBufferSequence] of unspecified type representing the next set of buffers in the serialization of the message represented by this object. 25044If there are no more buffers in the serialization, the visit function will not be called. In this case, no error will be indicated, and the function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] will return `true`. 25045[heading Parameters] 25046[table [[Name][Description]] 25047 [[`ec`][ 25048 25049Set to the error, if any occurred. 25050 ]] 25051 [[`visit`][ 25052 25053The function to call. The equivalent function signature of this object must be: 25054``` 25055 template<class ConstBufferSequence> 25056 void visit(error_code&, ConstBufferSequence const&); 25057``` 25058The function is not copied, if no error occurs it will be invoked before the call to [link beast.ref.boost__beast__http__serializer.next `http::serializer::next`] returns. 25059 ]] 25060] 25061[endsect] 25062[section:operator_eq_ http::serializer::operator=] 25063[indexterm2 operator=..http::serializer] 25064Assignment. 25065[heading Synopsis] 25066``` 25067serializer& 25068operator=( 25069 serializer const&); 25070``` 25071 25072[heading Description] 25073[endsect] 25074[section:serializer http::serializer::serializer] 25075[indexterm2 serializer..http::serializer] 25076Constructor. ``` 25077``[link beast.ref.boost__beast__http__serializer.serializer.overload1 serializer]``( 25078 serializer&&); 25079 ``[''''»''' [link beast.ref.boost__beast__http__serializer.serializer.overload1 more...]]`` 25080 25081``[link beast.ref.boost__beast__http__serializer.serializer.overload2 serializer]``( 25082 serializer const&); 25083 ``[''''»''' [link beast.ref.boost__beast__http__serializer.serializer.overload2 more...]]`` 25084 25085explicit 25086``[link beast.ref.boost__beast__http__serializer.serializer.overload3 serializer]``( 25087 value_type& msg); 25088 ``[''''»''' [link beast.ref.boost__beast__http__serializer.serializer.overload3 more...]]`` 25089``` 25090[section:overload1 http::serializer::serializer (1 of 3 overloads)] 25091Constructor. 25092[heading Synopsis] 25093``` 25094serializer( 25095 serializer&&); 25096``` 25097 25098[heading Description] 25099[endsect] 25100[section:overload2 http::serializer::serializer (2 of 3 overloads)] 25101Constructor. 25102[heading Synopsis] 25103``` 25104serializer( 25105 serializer const&); 25106``` 25107 25108[heading Description] 25109[endsect] 25110[section:overload3 http::serializer::serializer (3 of 3 overloads)] 25111Constructor. 25112[heading Synopsis] 25113``` 25114serializer( 25115 value_type& msg); 25116``` 25117 25118[heading Description] 25119The implementation guarantees that the message passed on construction will not be accessed until the first call to [link beast.ref.boost__beast__http__serializer.next `http::serializer::next`]. This allows the message to be lazily created. For example, if the header is filled in before serialization. 25120[heading Parameters] 25121[table [[Name][Description]] 25122 [[`msg`][ 25123 25124A reference to the message to serialize, which must remain valid for the lifetime of the serializer. Depending on the type of Body used, this may or may not be a `const` reference. 25125 ]] 25126] 25127[heading Remarks] 25128This function participates in overload resolution only if Body::writer is constructible from a `const` message reference. 25129[endsect] 25130[endsect] 25131 25132[section:split http::serializer::split] 25133[indexterm2 split..http::serializer] 25134Returns `true` if we will pause after writing the complete header. ``` 25135bool 25136``[link beast.ref.boost__beast__http__serializer.split.overload1 split]``(); 25137 ``[''''»''' [link beast.ref.boost__beast__http__serializer.split.overload1 more...]]`` 25138 25139``` 25140Set whether the header and body are written separately. ``` 25141void 25142``[link beast.ref.boost__beast__http__serializer.split.overload2 split]``( 25143 bool v); 25144 ``[''''»''' [link beast.ref.boost__beast__http__serializer.split.overload2 more...]]`` 25145``` 25146[section:overload1 http::serializer::split (1 of 2 overloads)] 25147Returns `true` if we will pause after writing the complete header. 25148[heading Synopsis] 25149``` 25150bool 25151split(); 25152``` 25153 25154[heading Description] 25155[endsect] 25156[section:overload2 http::serializer::split (2 of 2 overloads)] 25157Set whether the header and body are written separately. 25158[heading Synopsis] 25159``` 25160void 25161split( 25162 bool v); 25163``` 25164 25165[heading Description] 25166When the split feature is enabled, the implementation will write only the octets corresponding to the serialized header first. If the header has already been written, this function will have no effect on output. [endsect] 25167[endsect] 25168 25169[section:value_type http::serializer::value_type] 25170[indexterm2 value_type..http::serializer] 25171The type of message this serializer uses. 25172[heading Synopsis] 25173 25174``` 25175using value_type = ``['implementation-defined]``; 25176``` 25177 25178[heading Description] 25179This may be const or non-const depending on the implementation of the corresponding ['BodyWriter]. [endsect] 25180[section:writer_impl http::serializer::writer_impl] 25181[indexterm2 writer_impl..http::serializer] 25182Provides low-level access to the associated ['BodyWriter] 25183[heading Synopsis] 25184``` 25185writer& 25186writer_impl(); 25187``` 25188 25189[heading Description] 25190This function provides access to the instance of the writer associated with the body and created by the serializer upon construction. The behavior of accessing this object is defined by the specification of the particular writer and its associated body. 25191[heading Return Value] 25192A reference to the writer. 25193[endsect] 25194 25195 25196 25197Convenience header [include_file boost/beast/http.hpp] 25198 25199[endsect] 25200 25201 25202 25203[section:boost__beast__http__span_body http::span_body] 25204A ['Body] using [link beast.ref.boost__beast__span `span`]. 25205[heading Synopsis] 25206 25207Defined in header [include_file boost/beast/http/span_body.hpp] 25208 25209 25210 25211``` 25212template< 25213 class T> 25214struct span_body 25215``` 25216[heading Types] 25217[table [[Name][Description]] 25218 [ 25219 [[link beast.ref.boost__beast__http__span_body.reader [*reader]]] 25220 [ 25221 The algorithm for parsing the body. 25222 ] 25223 ] 25224 [ 25225 [[link beast.ref.boost__beast__http__span_body.value_type [*value_type]]] 25226 [ 25227 The type of container used for the body. 25228 ] 25229 ] 25230 [ 25231 [[link beast.ref.boost__beast__http__span_body.writer [*writer]]] 25232 [ 25233 The algorithm for serializing the body. 25234 ] 25235 ] 25236] 25237[heading Member Functions] 25238[table [[Name][Description]] 25239 [ 25240 [[link beast.ref.boost__beast__http__span_body.size [*size]]] 25241 [ 25242 Returns the payload size of the body. 25243 ] 25244 ] 25245] 25246 25247[heading Description] 25248This body uses [link beast.ref.boost__beast__span `span`] as a memory-based container for holding message payloads. The container represents a non-owning reference to a contiguous area of memory. Messages using this body type may be serialized and parsed. 25249Unlike [link beast.ref.boost__beast__http__buffer_body `http::buffer_body`], only one buffer may be provided during a parse or serialize operation. [section:reader http::span_body::reader] 25250[indexterm2 reader..http::span_body] 25251The algorithm for parsing the body. 25252[heading Synopsis] 25253 25254``` 25255using reader = ``['implementation-defined]``; 25256``` 25257 25258[heading Description] 25259Meets the requirements of ['BodyReader]. [endsect] 25260[section:size http::span_body::size] 25261[indexterm2 size..http::span_body] 25262Returns the payload size of the body. 25263[heading Synopsis] 25264``` 25265static 25266std::uint64_t 25267size( 25268 value_type const& body); 25269``` 25270 25271[heading Description] 25272When this body is used with [link beast.ref.boost__beast__http__message.prepare_payload `http::message::prepare_payload`], the Content-Length will be set to the payload size, and any chunked Transfer-Encoding will be removed. [endsect] 25273[section:value_type http::span_body::value_type] 25274[indexterm2 value_type..http::span_body] 25275The type of container used for the body. 25276[heading Synopsis] 25277 25278``` 25279using value_type = span< T >; 25280``` 25281[heading Types] 25282[table [[Name][Description]] 25283 [ 25284 [[link beast.ref.boost__beast__span.const_iterator [*const_iterator]]] 25285 [ 25286 The const iterator used by the container. 25287 ] 25288 ] 25289 [ 25290 [[link beast.ref.boost__beast__span.const_pointer [*const_pointer]]] 25291 [ 25292 The const pointer used by the container. 25293 ] 25294 ] 25295 [ 25296 [[link beast.ref.boost__beast__span.const_reference [*const_reference]]] 25297 [ 25298 The const reference used by the container. 25299 ] 25300 ] 25301 [ 25302 [[link beast.ref.boost__beast__span.element_type [*element_type]]] 25303 [ 25304 The type of value, including cv qualifiers. 25305 ] 25306 ] 25307 [ 25308 [[link beast.ref.boost__beast__span.index_type [*index_type]]] 25309 [ 25310 The type of integer used to index the span. 25311 ] 25312 ] 25313 [ 25314 [[link beast.ref.boost__beast__span.iterator [*iterator]]] 25315 [ 25316 The iterator used by the container. 25317 ] 25318 ] 25319 [ 25320 [[link beast.ref.boost__beast__span.pointer [*pointer]]] 25321 [ 25322 A pointer to a span element. 25323 ] 25324 ] 25325 [ 25326 [[link beast.ref.boost__beast__span.reference [*reference]]] 25327 [ 25328 A reference to a span element. 25329 ] 25330 ] 25331 [ 25332 [[link beast.ref.boost__beast__span.value_type [*value_type]]] 25333 [ 25334 The type of value of each span element. 25335 ] 25336 ] 25337] 25338[heading Member Functions] 25339[table [[Name][Description]] 25340 [ 25341 [[link beast.ref.boost__beast__span.begin [*begin]]] 25342 [ 25343 Returns an iterator to the beginning of the span. 25344 ] 25345 ] 25346 [ 25347 [[link beast.ref.boost__beast__span.cbegin [*cbegin]]] 25348 [ 25349 Returns an iterator to the beginning of the span. 25350 ] 25351 ] 25352 [ 25353 [[link beast.ref.boost__beast__span.cend [*cend]]] 25354 [ 25355 Returns an iterator to one past the end of the span. 25356 ] 25357 ] 25358 [ 25359 [[link beast.ref.boost__beast__span.data [*data]]] 25360 [ 25361 Returns a pointer to the beginning of the span. 25362 ] 25363 ] 25364 [ 25365 [[link beast.ref.boost__beast__span.empty [*empty]]] 25366 [ 25367 Returns true if the span is empty. 25368 ] 25369 ] 25370 [ 25371 [[link beast.ref.boost__beast__span.end [*end]]] 25372 [ 25373 Returns an iterator to one past the end of the span. 25374 ] 25375 ] 25376 [ 25377 [[link beast.ref.boost__beast__span.operator_eq_ [*operator=]]] 25378 [ 25379 Assignment. 25380 ] 25381 ] 25382 [ 25383 [[link beast.ref.boost__beast__span.size [*size]]] 25384 [ 25385 Returns the number of elements in the span. 25386 ] 25387 ] 25388 [ 25389 [[link beast.ref.boost__beast__span.span [*span]]] 25390 [ 25391 Constructor. 25392 ] 25393 ] 25394] 25395This class implements a non-owning reference to a storage area of a certain size and having an underlying integral type with size of 1. 25396[heading Template Parameters] 25397[table [[Type][Description]] 25398 [[`T`][ 25399 25400The type pointed to by span iterators 25401 ]] 25402] 25403 25404[heading Description] 25405This determines the type of [link beast.ref.boost__beast__http__message.body `http::message::body`] when this body type is used with a message container. [endsect] 25406[section:writer http::span_body::writer] 25407[indexterm2 writer..http::span_body] 25408The algorithm for serializing the body. 25409[heading Synopsis] 25410 25411``` 25412using writer = ``['implementation-defined]``; 25413``` 25414 25415[heading Description] 25416Meets the requirements of ['BodyWriter]. [endsect] 25417 25418 25419 25420Convenience header [include_file boost/beast/http.hpp] 25421 25422[endsect] 25423 25424 25425 25426[section:boost__beast__http__status http::status] 25427[indexterm1 http::status] 25428 25429[heading Synopsis] 25430 25431Defined in header [include_file boost/beast/http/status.hpp] 25432 25433 25434``` 25435enum status 25436``` 25437 25438[indexterm2 unknown..http::status] 25439[indexterm2 continue_..http::status] 25440[indexterm2 switching_protocols..http::status] 25441[indexterm2 processing..http::status] 25442[indexterm2 ok..http::status] 25443[indexterm2 created..http::status] 25444[indexterm2 accepted..http::status] 25445[indexterm2 non_authoritative_information..http::status] 25446[indexterm2 no_content..http::status] 25447[indexterm2 reset_content..http::status] 25448[indexterm2 partial_content..http::status] 25449[indexterm2 multi_status..http::status] 25450[indexterm2 already_reported..http::status] 25451[indexterm2 im_used..http::status] 25452[indexterm2 multiple_choices..http::status] 25453[indexterm2 moved_permanently..http::status] 25454[indexterm2 found..http::status] 25455[indexterm2 see_other..http::status] 25456[indexterm2 not_modified..http::status] 25457[indexterm2 use_proxy..http::status] 25458[indexterm2 temporary_redirect..http::status] 25459[indexterm2 permanent_redirect..http::status] 25460[indexterm2 bad_request..http::status] 25461[indexterm2 unauthorized..http::status] 25462[indexterm2 payment_required..http::status] 25463[indexterm2 forbidden..http::status] 25464[indexterm2 not_found..http::status] 25465[indexterm2 method_not_allowed..http::status] 25466[indexterm2 not_acceptable..http::status] 25467[indexterm2 proxy_authentication_required..http::status] 25468[indexterm2 request_timeout..http::status] 25469[indexterm2 conflict..http::status] 25470[indexterm2 gone..http::status] 25471[indexterm2 length_required..http::status] 25472[indexterm2 precondition_failed..http::status] 25473[indexterm2 payload_too_large..http::status] 25474[indexterm2 uri_too_long..http::status] 25475[indexterm2 unsupported_media_type..http::status] 25476[indexterm2 range_not_satisfiable..http::status] 25477[indexterm2 expectation_failed..http::status] 25478[indexterm2 misdirected_request..http::status] 25479[indexterm2 unprocessable_entity..http::status] 25480[indexterm2 locked..http::status] 25481[indexterm2 failed_dependency..http::status] 25482[indexterm2 upgrade_required..http::status] 25483[indexterm2 precondition_required..http::status] 25484[indexterm2 too_many_requests..http::status] 25485[indexterm2 request_header_fields_too_large..http::status] 25486[indexterm2 connection_closed_without_response..http::status] 25487[indexterm2 unavailable_for_legal_reasons..http::status] 25488[indexterm2 client_closed_request..http::status] 25489[indexterm2 internal_server_error..http::status] 25490[indexterm2 not_implemented..http::status] 25491[indexterm2 bad_gateway..http::status] 25492[indexterm2 service_unavailable..http::status] 25493[indexterm2 gateway_timeout..http::status] 25494[indexterm2 http_version_not_supported..http::status] 25495[indexterm2 variant_also_negotiates..http::status] 25496[indexterm2 insufficient_storage..http::status] 25497[indexterm2 loop_detected..http::status] 25498[indexterm2 not_extended..http::status] 25499[indexterm2 network_authentication_required..http::status] 25500[indexterm2 network_connect_timeout_error..http::status] 25501[heading Values] 25502[table [[Name][Description]] 25503 [[[^unknown]][An unknown status-code. 25504 25505This value indicates that the value for the status code 25506is not in the list of commonly recognized status codes. 25507Callers interested in the exactly value should use the 25508interface which provides the raw integer. 25509 ]] 25510 [[[^continue_]][ 25511 25512]] 25513 [[[^switching_protocols]][Switching Protocols. 25514 25515This status indicates that a request to switch to a new 25516protocol was accepted and applied by the server. A successful 25517response to a WebSocket Upgrade HTTP request will have this 25518code. 25519 ]] 25520 [[[^processing]][ 25521 25522]] 25523 [[[^ok]][ 25524 25525]] 25526 [[[^created]][ 25527 25528]] 25529 [[[^accepted]][ 25530 25531]] 25532 [[[^non_authoritative_information]][ 25533 25534]] 25535 [[[^no_content]][ 25536 25537]] 25538 [[[^reset_content]][ 25539 25540]] 25541 [[[^partial_content]][ 25542 25543]] 25544 [[[^multi_status]][ 25545 25546]] 25547 [[[^already_reported]][ 25548 25549]] 25550 [[[^im_used]][ 25551 25552]] 25553 [[[^multiple_choices]][ 25554 25555]] 25556 [[[^moved_permanently]][ 25557 25558]] 25559 [[[^found]][ 25560 25561]] 25562 [[[^see_other]][ 25563 25564]] 25565 [[[^not_modified]][ 25566 25567]] 25568 [[[^use_proxy]][ 25569 25570]] 25571 [[[^temporary_redirect]][ 25572 25573]] 25574 [[[^permanent_redirect]][ 25575 25576]] 25577 [[[^bad_request]][ 25578 25579]] 25580 [[[^unauthorized]][ 25581 25582]] 25583 [[[^payment_required]][ 25584 25585]] 25586 [[[^forbidden]][ 25587 25588]] 25589 [[[^not_found]][ 25590 25591]] 25592 [[[^method_not_allowed]][ 25593 25594]] 25595 [[[^not_acceptable]][ 25596 25597]] 25598 [[[^proxy_authentication_required]][ 25599 25600]] 25601 [[[^request_timeout]][ 25602 25603]] 25604 [[[^conflict]][ 25605 25606]] 25607 [[[^gone]][ 25608 25609]] 25610 [[[^length_required]][ 25611 25612]] 25613 [[[^precondition_failed]][ 25614 25615]] 25616 [[[^payload_too_large]][ 25617 25618]] 25619 [[[^uri_too_long]][ 25620 25621]] 25622 [[[^unsupported_media_type]][ 25623 25624]] 25625 [[[^range_not_satisfiable]][ 25626 25627]] 25628 [[[^expectation_failed]][ 25629 25630]] 25631 [[[^misdirected_request]][ 25632 25633]] 25634 [[[^unprocessable_entity]][ 25635 25636]] 25637 [[[^locked]][ 25638 25639]] 25640 [[[^failed_dependency]][ 25641 25642]] 25643 [[[^upgrade_required]][ 25644 25645]] 25646 [[[^precondition_required]][ 25647 25648]] 25649 [[[^too_many_requests]][ 25650 25651]] 25652 [[[^request_header_fields_too_large]][ 25653 25654]] 25655 [[[^connection_closed_without_response]][ 25656 25657]] 25658 [[[^unavailable_for_legal_reasons]][ 25659 25660]] 25661 [[[^client_closed_request]][ 25662 25663]] 25664 [[[^internal_server_error]][ 25665 25666]] 25667 [[[^not_implemented]][ 25668 25669]] 25670 [[[^bad_gateway]][ 25671 25672]] 25673 [[[^service_unavailable]][ 25674 25675]] 25676 [[[^gateway_timeout]][ 25677 25678]] 25679 [[[^http_version_not_supported]][ 25680 25681]] 25682 [[[^variant_also_negotiates]][ 25683 25684]] 25685 [[[^insufficient_storage]][ 25686 25687]] 25688 [[[^loop_detected]][ 25689 25690]] 25691 [[[^not_extended]][ 25692 25693]] 25694 [[[^network_authentication_required]][ 25695 25696]] 25697 [[[^network_connect_timeout_error]][ 25698 25699]] 25700] 25701 25702[heading Description] 25703 25704 25705 25706Convenience header [include_file boost/beast/http.hpp] 25707 25708[endsect] 25709[section:boost__beast__http__status_class http::status_class] 25710[indexterm1 http::status_class] 25711Represents the class of a status-code. 25712[heading Synopsis] 25713 25714Defined in header [include_file boost/beast/http/status.hpp] 25715 25716 25717``` 25718enum status_class 25719``` 25720 25721[indexterm2 unknown..http::status_class] 25722[indexterm2 informational..http::status_class] 25723[indexterm2 successful..http::status_class] 25724[indexterm2 redirection..http::status_class] 25725[indexterm2 client_error..http::status_class] 25726[indexterm2 server_error..http::status_class] 25727[heading Values] 25728[table [[Name][Description]] 25729 [[[^unknown]][Unknown status-class. 25730 25731]] 25732 [[[^informational]][The request was received, continuing processing. 25733 25734]] 25735 [[[^successful]][The request was successfully received, understood, and accepted. 25736 25737]] 25738 [[[^redirection]][Further action needs to be taken in order to complete the request. 25739 25740]] 25741 [[[^client_error]][The request contains bad syntax or cannot be fulfilled. 25742 25743]] 25744 [[[^server_error]][The server failed to fulfill an apparently valid request. 25745 25746]] 25747] 25748 25749[heading Description] 25750 25751 25752 25753Convenience header [include_file boost/beast/http.hpp] 25754 25755[endsect] 25756[section:boost__beast__http__string_body http::string_body] 25757[indexterm1 http::string_body] 25758A ['Body] using `std::string` 25759[heading Synopsis] 25760 25761Defined in header [include_file boost/beast/http/string_body.hpp] 25762 25763 25764 25765``` 25766using string_body = basic_string_body< char >; 25767``` 25768[heading Types] 25769[table [[Name][Description]] 25770 [ 25771 [[link beast.ref.boost__beast__http__basic_string_body.reader [*reader]]] 25772 [ 25773 The algorithm for parsing the body. 25774 ] 25775 ] 25776 [ 25777 [[link beast.ref.boost__beast__http__basic_string_body.value_type [*value_type]]] 25778 [ 25779 The type of container used for the body. 25780 ] 25781 ] 25782 [ 25783 [[link beast.ref.boost__beast__http__basic_string_body.writer [*writer]]] 25784 [ 25785 The algorithm for serializing the body. 25786 ] 25787 ] 25788] 25789[heading Member Functions] 25790[table [[Name][Description]] 25791 [ 25792 [[link beast.ref.boost__beast__http__basic_string_body.size [*size]]] 25793 [ 25794 Returns the payload size of the body. 25795 ] 25796 ] 25797] 25798This body uses `std::basic_string` as a memory-based container for holding message payloads. Messages using this body type may be serialized and parsed. 25799[heading Description] 25800 25801 25802 25803Convenience header [include_file boost/beast/http.hpp] 25804 25805[endsect] 25806[section:boost__beast__http__string_to_field http::string_to_field] 25807[indexterm1 http::string_to_field] 25808Attempt to convert a string to a field enum. 25809[heading Synopsis] 25810 25811Defined in header [include_file boost/beast/http/field.hpp] 25812 25813 25814 25815``` 25816field 25817string_to_field( 25818 string_view s); 25819 25820``` 25821 25822[heading Description] 25823The string comparison is case-insensitive. 25824[heading Return Value] 25825The corresponding field, or [link beast.ref.boost__beast__http__field `http::unknown`] if no known field matches. 25826 25827 25828 25829Convenience header [include_file boost/beast/http.hpp] 25830 25831[endsect] 25832[section:boost__beast__http__string_to_verb http::string_to_verb] 25833[indexterm1 http::string_to_verb] 25834Converts a string to the request method verb. 25835[heading Synopsis] 25836 25837Defined in header [include_file boost/beast/http/verb.hpp] 25838 25839 25840 25841``` 25842verb 25843string_to_verb( 25844 string_view s); 25845 25846``` 25847 25848[heading Description] 25849If the string does not match a known request method, [link beast.ref.boost__beast__http__field `http::unknown`] is returned. 25850 25851 25852Convenience header [include_file boost/beast/http.hpp] 25853 25854[endsect] 25855[section:boost__beast__http__swap http::swap] 25856[indexterm1 http::swap] 25857Swap two header objects. ``` 25858template< 25859 bool isRequest, 25860 class __Fields__> 25861void 25862``[link beast.ref.boost__beast__http__swap.overload1 swap]``( 25863 header< isRequest, Fields >& m1, 25864 header< isRequest, Fields >& m2); 25865 ``[''''»''' [link beast.ref.boost__beast__http__swap.overload1 more...]]`` 25866 25867``` 25868Swap two message objects. ``` 25869template< 25870 bool isRequest, 25871 class __Body__, 25872 class __Fields__> 25873void 25874``[link beast.ref.boost__beast__http__swap.overload2 swap]``( 25875 message< isRequest, Body, Fields >& m1, 25876 message< isRequest, Body, Fields >& m2); 25877 ``[''''»''' [link beast.ref.boost__beast__http__swap.overload2 more...]]`` 25878``` 25879[section:overload1 http::swap (1 of 2 overloads)] 25880Swap two header objects. 25881[heading Synopsis] 25882 25883Defined in header [include_file boost/beast/http/message.hpp] 25884 25885 25886 25887``` 25888template< 25889 bool isRequest, 25890 class __Fields__> 25891void 25892swap( 25893 header< isRequest, Fields >& m1, 25894 header< isRequest, Fields >& m2); 25895 25896``` 25897 25898[heading Description] 25899[heading Requirements] 25900`Fields` is [*Swappable]. 25901 25902 25903 25904Convenience header [include_file boost/beast/http.hpp] 25905 25906[endsect] 25907[section:overload2 http::swap (2 of 2 overloads)] 25908Swap two message objects. 25909[heading Synopsis] 25910 25911Defined in header [include_file boost/beast/http/message.hpp] 25912 25913 25914 25915``` 25916template< 25917 bool isRequest, 25918 class __Body__, 25919 class __Fields__> 25920void 25921swap( 25922 message< isRequest, Body, Fields >& m1, 25923 message< isRequest, Body, Fields >& m2); 25924 25925``` 25926 25927[heading Description] 25928[heading Requirements:] 25929`Body::value_type` and `Fields` are [*Swappable]. 25930 25931 25932 25933Convenience header [include_file boost/beast/http.hpp] 25934 25935[endsect] 25936[endsect] 25937 25938 25939 25940[section:boost__beast__http__to_status_class http::to_status_class] 25941[indexterm1 http::to_status_class] 25942Convert an integer to a status\_class. ``` 25943status_class 25944``[link beast.ref.boost__beast__http__to_status_class.overload1 to_status_class]``( 25945 unsigned v); 25946 ``[''''»''' [link beast.ref.boost__beast__http__to_status_class.overload1 more...]]`` 25947 25948``` 25949Convert a status\_code to a status\_class. ``` 25950status_class 25951``[link beast.ref.boost__beast__http__to_status_class.overload2 to_status_class]``( 25952 status v); 25953 ``[''''»''' [link beast.ref.boost__beast__http__to_status_class.overload2 more...]]`` 25954``` 25955[section:overload1 http::to_status_class (1 of 2 overloads)] 25956Convert an integer to a status\_class. 25957[heading Synopsis] 25958 25959Defined in header [include_file boost/beast/http/status.hpp] 25960 25961 25962 25963``` 25964status_class 25965to_status_class( 25966 unsigned v); 25967 25968``` 25969 25970[heading Description] 25971[heading Parameters] 25972[table [[Name][Description]] 25973 [[`v`][ 25974 25975The integer representing a status code. 25976 ]] 25977] 25978[heading Return Value] 25979The status class. If the integer does not match a known status class, [link beast.ref.boost__beast__http__field `http::unknown`] is returned. 25980 25981 25982 25983Convenience header [include_file boost/beast/http.hpp] 25984 25985[endsect] 25986[section:overload2 http::to_status_class (2 of 2 overloads)] 25987Convert a status\_code to a status\_class. 25988[heading Synopsis] 25989 25990Defined in header [include_file boost/beast/http/status.hpp] 25991 25992 25993 25994``` 25995status_class 25996to_status_class( 25997 status v); 25998 25999``` 26000 26001[heading Description] 26002[heading Parameters] 26003[table [[Name][Description]] 26004 [[`v`][ 26005 26006The status code to convert. 26007 ]] 26008] 26009[heading Return Value] 26010The status class. 26011 26012 26013 26014Convenience header [include_file boost/beast/http.hpp] 26015 26016[endsect] 26017[endsect] 26018 26019 26020 26021[section:boost__beast__http__to_string http::to_string] 26022[indexterm1 http::to_string] 26023Convert a field enum to a string. ``` 26024string_view 26025``[link beast.ref.boost__beast__http__to_string.overload1 to_string]``( 26026 field f); 26027 ``[''''»''' [link beast.ref.boost__beast__http__to_string.overload1 more...]]`` 26028 26029``` 26030Returns the text representation of a request method verb. ``` 26031string_view 26032``[link beast.ref.boost__beast__http__to_string.overload2 to_string]``( 26033 verb v); 26034 ``[''''»''' [link beast.ref.boost__beast__http__to_string.overload2 more...]]`` 26035``` 26036[section:overload1 http::to_string (1 of 2 overloads)] 26037Convert a field enum to a string. 26038[heading Synopsis] 26039 26040Defined in header [include_file boost/beast/http/field.hpp] 26041 26042 26043 26044``` 26045string_view 26046to_string( 26047 field f); 26048 26049``` 26050 26051[heading Description] 26052[heading Parameters] 26053[table [[Name][Description]] 26054 [[`f`][ 26055 26056The field to convert 26057 ]] 26058] 26059 26060 26061 26062Convenience header [include_file boost/beast/http.hpp] 26063 26064[endsect] 26065[section:overload2 http::to_string (2 of 2 overloads)] 26066Returns the text representation of a request method verb. 26067[heading Synopsis] 26068 26069Defined in header [include_file boost/beast/http/verb.hpp] 26070 26071 26072 26073``` 26074string_view 26075to_string( 26076 verb v); 26077 26078``` 26079 26080[heading Description] 26081 26082 26083 26084Convenience header [include_file boost/beast/http.hpp] 26085 26086[endsect] 26087[endsect] 26088 26089 26090 26091[section:boost__beast__http__token_list http::token_list] 26092A list of tokens in a comma separated HTTP field value. 26093[heading Synopsis] 26094 26095Defined in header [include_file boost/beast/http/rfc7230.hpp] 26096 26097 26098 26099``` 26100class token_list 26101``` 26102[heading Types] 26103[table [[Name][Description]] 26104 [ 26105 [[link beast.ref.boost__beast__http__token_list.const_iterator [*const_iterator]]] 26106 [ 26107 A constant iterator to the list. 26108 ] 26109 ] 26110 [ 26111 [[link beast.ref.boost__beast__http__token_list.value_type [*value_type]]] 26112 [ 26113 The type of each element in the token list. 26114 ] 26115 ] 26116] 26117[heading Member Functions] 26118[table [[Name][Description]] 26119 [ 26120 [[link beast.ref.boost__beast__http__token_list.begin [*begin]]] 26121 [ 26122 Return a const iterator to the beginning of the list. 26123 ] 26124 ] 26125 [ 26126 [[link beast.ref.boost__beast__http__token_list.cbegin [*cbegin]]] 26127 [ 26128 Return a const iterator to the beginning of the list. 26129 ] 26130 ] 26131 [ 26132 [[link beast.ref.boost__beast__http__token_list.cend [*cend]]] 26133 [ 26134 Return a const iterator to the end of the list. 26135 ] 26136 ] 26137 [ 26138 [[link beast.ref.boost__beast__http__token_list.end [*end]]] 26139 [ 26140 Return a const iterator to the end of the list. 26141 ] 26142 ] 26143 [ 26144 [[link beast.ref.boost__beast__http__token_list.exists [*exists]]] 26145 [ 26146 Return true if a token is present in the list. 26147 ] 26148 ] 26149 [ 26150 [[link beast.ref.boost__beast__http__token_list.token_list [*token_list]]] 26151 [ 26152 Construct a list. 26153 ] 26154 ] 26155] 26156 26157[heading Description] 26158This container allows iteration of a list of items in a header field value. The input is a comma separated list of tokens. 26159If a parsing error is encountered while iterating the string, the behavior of the container will be as if a string containing only characters up to but excluding the first invalid character was used to construct the list. 26160[heading BNF] 26161 26162``` 26163 token-list = *( "," OWS ) token *( OWS "," [ OWS token ] ) 26164``` 26165To use this class, construct with the string to be parsed and then use [link beast.ref.boost__beast__http__token_list.begin `http::token_list::begin`] and [link beast.ref.boost__beast__http__token_list.end `http::token_list::end`], or range-for to iterate each item: 26166[heading Example] 26167 26168``` 26169 for(auto const& token : token_list{"apple, pear, banana"}) 26170 std::cout << token << "\n"; 26171``` 26172[section:begin http::token_list::begin] 26173[indexterm2 begin..http::token_list] 26174Return a const iterator to the beginning of the list. 26175[heading Synopsis] 26176``` 26177const_iterator 26178begin() const; 26179``` 26180 26181[heading Description] 26182[endsect] 26183[section:cbegin http::token_list::cbegin] 26184[indexterm2 cbegin..http::token_list] 26185Return a const iterator to the beginning of the list. 26186[heading Synopsis] 26187``` 26188const_iterator 26189cbegin() const; 26190``` 26191 26192[heading Description] 26193[endsect] 26194[section:cend http::token_list::cend] 26195[indexterm2 cend..http::token_list] 26196Return a const iterator to the end of the list. 26197[heading Synopsis] 26198``` 26199const_iterator 26200cend() const; 26201``` 26202 26203[heading Description] 26204[endsect] 26205[section:const_iterator http::token_list::const_iterator] 26206[indexterm2 const_iterator..http::token_list] 26207A constant iterator to the list. 26208[heading Synopsis] 26209 26210``` 26211using const_iterator = ``['implementation-defined]``; 26212``` 26213 26214[heading Description] 26215[endsect] 26216[section:end http::token_list::end] 26217[indexterm2 end..http::token_list] 26218Return a const iterator to the end of the list. 26219[heading Synopsis] 26220``` 26221const_iterator 26222end() const; 26223``` 26224 26225[heading Description] 26226[endsect] 26227[section:exists http::token_list::exists] 26228[indexterm2 exists..http::token_list] 26229Return `true` if a token is present in the list. 26230[heading Synopsis] 26231``` 26232bool 26233exists( 26234 string_view const& s); 26235``` 26236 26237[heading Description] 26238[heading Parameters] 26239[table [[Name][Description]] 26240 [[`s`][ 26241 26242The token to find. A case-insensitive comparison is used. 26243 ]] 26244] 26245[endsect] 26246[section:token_list http::token_list::token_list] 26247[indexterm2 token_list..http::token_list] 26248Construct a list. 26249[heading Synopsis] 26250``` 26251token_list( 26252 string_view s); 26253``` 26254 26255[heading Description] 26256[heading Parameters] 26257[table [[Name][Description]] 26258 [[`s`][ 26259 26260A string containing the list contents. The string must remain valid for the lifetime of the container. 26261 ]] 26262] 26263[endsect] 26264[section:value_type http::token_list::value_type] 26265[indexterm2 value_type..http::token_list] 26266The type of each element in the token list. 26267[heading Synopsis] 26268 26269``` 26270using value_type = string_view; 26271``` 26272 26273[heading Description] 26274[endsect] 26275 26276 26277 26278Convenience header [include_file boost/beast/http.hpp] 26279 26280[endsect] 26281 26282 26283 26284[section:boost__beast__http__validate_list http::validate_list] 26285[indexterm1 http::validate_list] 26286Returns `true` if a parsed list is parsed without errors. 26287[heading Synopsis] 26288 26289Defined in header [include_file boost/beast/http/rfc7230.hpp] 26290 26291 26292 26293``` 26294template< 26295 class Policy> 26296bool 26297validate_list( 26298 detail::basic_parsed_list< Policy > const& list); 26299 26300``` 26301 26302[heading Description] 26303This function iterates a single pass through a parsed list and returns `true` if there were no parsing errors, else returns `false`. 26304 26305 26306Convenience header [include_file boost/beast/http.hpp] 26307 26308[endsect] 26309[section:boost__beast__http__vector_body http::vector_body] 26310A ['Body] using `std::vector` 26311[heading Synopsis] 26312 26313Defined in header [include_file boost/beast/http/vector_body.hpp] 26314 26315 26316 26317``` 26318template< 26319 class T, 26320 class __Allocator__ = std::allocator<T>> 26321struct vector_body 26322``` 26323[heading Types] 26324[table [[Name][Description]] 26325 [ 26326 [[link beast.ref.boost__beast__http__vector_body.reader [*reader]]] 26327 [ 26328 The algorithm for parsing the body. 26329 ] 26330 ] 26331 [ 26332 [[link beast.ref.boost__beast__http__vector_body.value_type [*value_type]]] 26333 [ 26334 The type of container used for the body. 26335 ] 26336 ] 26337 [ 26338 [[link beast.ref.boost__beast__http__vector_body.writer [*writer]]] 26339 [ 26340 The algorithm for serializing the body. 26341 ] 26342 ] 26343] 26344[heading Member Functions] 26345[table [[Name][Description]] 26346 [ 26347 [[link beast.ref.boost__beast__http__vector_body.size [*size]]] 26348 [ 26349 Returns the payload size of the body. 26350 ] 26351 ] 26352] 26353 26354[heading Description] 26355This body uses `std::vector` as a memory-based container for holding message payloads. Messages using this body type may be serialized and parsed. [section:reader http::vector_body::reader] 26356[indexterm2 reader..http::vector_body] 26357The algorithm for parsing the body. 26358[heading Synopsis] 26359 26360``` 26361using reader = ``['implementation-defined]``; 26362``` 26363 26364[heading Description] 26365Meets the requirements of ['BodyReader]. [endsect] 26366[section:size http::vector_body::size] 26367[indexterm2 size..http::vector_body] 26368Returns the payload size of the body. 26369[heading Synopsis] 26370``` 26371static 26372std::uint64_t 26373size( 26374 value_type const& body); 26375``` 26376 26377[heading Description] 26378When this body is used with [link beast.ref.boost__beast__http__message.prepare_payload `http::message::prepare_payload`], the Content-Length will be set to the payload size, and any chunked Transfer-Encoding will be removed. [endsect] 26379[section:value_type http::vector_body::value_type] 26380[indexterm2 value_type..http::vector_body] 26381The type of container used for the body. 26382[heading Synopsis] 26383 26384``` 26385using value_type = std::vector< T, Allocator >; 26386``` 26387 26388[heading Description] 26389This determines the type of [link beast.ref.boost__beast__http__message.body `http::message::body`] when this body type is used with a message container. [endsect] 26390[section:writer http::vector_body::writer] 26391[indexterm2 writer..http::vector_body] 26392The algorithm for serializing the body. 26393[heading Synopsis] 26394 26395``` 26396using writer = ``['implementation-defined]``; 26397``` 26398 26399[heading Description] 26400Meets the requirements of ['BodyWriter]. [endsect] 26401 26402 26403 26404Convenience header [include_file boost/beast/http.hpp] 26405 26406[endsect] 26407 26408 26409 26410[section:boost__beast__http__verb http::verb] 26411[indexterm1 http::verb] 26412HTTP request method verbs. 26413[heading Synopsis] 26414 26415Defined in header [include_file boost/beast/http/verb.hpp] 26416 26417 26418``` 26419enum verb 26420``` 26421 26422[indexterm2 unknown..http::verb] 26423[indexterm2 delete_..http::verb] 26424[indexterm2 get..http::verb] 26425[indexterm2 head..http::verb] 26426[indexterm2 post..http::verb] 26427[indexterm2 put..http::verb] 26428[indexterm2 connect..http::verb] 26429[indexterm2 options..http::verb] 26430[indexterm2 trace..http::verb] 26431[indexterm2 copy..http::verb] 26432[indexterm2 lock..http::verb] 26433[indexterm2 mkcol..http::verb] 26434[indexterm2 move..http::verb] 26435[indexterm2 propfind..http::verb] 26436[indexterm2 proppatch..http::verb] 26437[indexterm2 search..http::verb] 26438[indexterm2 unlock..http::verb] 26439[indexterm2 bind..http::verb] 26440[indexterm2 rebind..http::verb] 26441[indexterm2 unbind..http::verb] 26442[indexterm2 acl..http::verb] 26443[indexterm2 report..http::verb] 26444[indexterm2 mkactivity..http::verb] 26445[indexterm2 checkout..http::verb] 26446[indexterm2 merge..http::verb] 26447[indexterm2 msearch..http::verb] 26448[indexterm2 notify..http::verb] 26449[indexterm2 subscribe..http::verb] 26450[indexterm2 unsubscribe..http::verb] 26451[indexterm2 patch..http::verb] 26452[indexterm2 purge..http::verb] 26453[indexterm2 mkcalendar..http::verb] 26454[indexterm2 link..http::verb] 26455[indexterm2 unlink..http::verb] 26456[heading Values] 26457[table [[Name][Description]] 26458 [[[^unknown]][An unknown method. 26459 26460This value indicates that the request method string is not 26461one of the recognized verbs. Callers interested in the method 26462should use an interface which returns the original string. 26463 ]] 26464 [[[^delete_]][The DELETE method deletes the specified resource. 26465 26466]] 26467 [[[^get]][The GET method requests a representation of the specified resource. 26468 26469Requests using GET should only retrieve data and should have no other effect. 26470 ]] 26471 [[[^head]][The HEAD method asks for a response identical to that of a GET request, but without the response body. 26472 26473This is useful for retrieving meta-information written in response 26474headers, without having to transport the entire content. 26475 ]] 26476 [[[^post]][The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. 26477 26478The data POSTed might be, for example, an annotation for existing 26479resources; a message for a bulletin board, newsgroup, mailing list, 26480or comment thread; a block of data that is the result of submitting 26481a web form to a data-handling process; or an item to add to a database 26482 ]] 26483 [[[^put]][The PUT method requests that the enclosed entity be stored under the supplied URI. 26484 26485If the URI refers to an already existing resource, it is modified; 26486if the URI does not point to an existing resource, then the server 26487can create the resource with that URI. 26488 ]] 26489 [[[^connect]][The CONNECT method converts the request connection to a transparent TCP/IP tunnel. 26490 26491This is usually to facilitate SSL-encrypted communication (HTTPS) 26492through an unencrypted HTTP proxy. 26493 ]] 26494 [[[^options]][The OPTIONS method returns the HTTP methods that the server supports for the specified URL. 26495 26496This can be used to check the functionality of a web server by requesting 26497'*' instead of a specific resource. 26498 ]] 26499 [[[^trace]][The TRACE method echoes the received request so that a client can see what (if any) changes or additions have been made by intermediate servers. 26500 26501]] 26502 [[[^copy]][ 26503 26504]] 26505 [[[^lock]][ 26506 26507]] 26508 [[[^mkcol]][ 26509 26510]] 26511 [[[^move]][ 26512 26513]] 26514 [[[^propfind]][ 26515 26516]] 26517 [[[^proppatch]][ 26518 26519]] 26520 [[[^search]][ 26521 26522]] 26523 [[[^unlock]][ 26524 26525]] 26526 [[[^bind]][ 26527 26528]] 26529 [[[^rebind]][ 26530 26531]] 26532 [[[^unbind]][ 26533 26534]] 26535 [[[^acl]][ 26536 26537]] 26538 [[[^report]][ 26539 26540]] 26541 [[[^mkactivity]][ 26542 26543]] 26544 [[[^checkout]][ 26545 26546]] 26547 [[[^merge]][ 26548 26549]] 26550 [[[^msearch]][ 26551 26552]] 26553 [[[^notify]][ 26554 26555]] 26556 [[[^subscribe]][ 26557 26558]] 26559 [[[^unsubscribe]][ 26560 26561]] 26562 [[[^patch]][ 26563 26564]] 26565 [[[^purge]][ 26566 26567]] 26568 [[[^mkcalendar]][ 26569 26570]] 26571 [[[^link]][ 26572 26573]] 26574 [[[^unlink]][ 26575 26576]] 26577] 26578 26579[heading Description] 26580Each verb corresponds to a particular method string used in HTTP request messages. 26581 26582 26583Convenience header [include_file boost/beast/http.hpp] 26584 26585[endsect] 26586[section:boost__beast__http__write http::write] 26587[indexterm1 http::write] 26588Write a complete message to a stream using a serializer. ``` 26589template< 26590 class __SyncWriteStream__, 26591 bool isRequest, 26592 class __Body__, 26593 class __Fields__> 26594std::size_t 26595``[link beast.ref.boost__beast__http__write.overload1 write]``( 26596 SyncWriteStream& stream, 26597 serializer< isRequest, Body, Fields >& sr); 26598 ``[''''»''' [link beast.ref.boost__beast__http__write.overload1 more...]]`` 26599 26600template< 26601 class __SyncWriteStream__, 26602 bool isRequest, 26603 class __Body__, 26604 class __Fields__> 26605std::size_t 26606``[link beast.ref.boost__beast__http__write.overload2 write]``( 26607 SyncWriteStream& stream, 26608 serializer< isRequest, Body, Fields >& sr, 26609 error_code& ec); 26610 ``[''''»''' [link beast.ref.boost__beast__http__write.overload2 more...]]`` 26611 26612``` 26613Write a complete message to a stream. ``` 26614template< 26615 class __SyncWriteStream__, 26616 bool isRequest, 26617 class __Body__, 26618 class __Fields__> 26619std::size_t 26620``[link beast.ref.boost__beast__http__write.overload3 write]``( 26621 SyncWriteStream& stream, 26622 message< isRequest, Body, Fields >& msg); 26623 ``[''''»''' [link beast.ref.boost__beast__http__write.overload3 more...]]`` 26624 26625template< 26626 class __SyncWriteStream__, 26627 bool isRequest, 26628 class __Body__, 26629 class __Fields__> 26630std::size_t 26631``[link beast.ref.boost__beast__http__write.overload4 write]``( 26632 SyncWriteStream& stream, 26633 message< isRequest, Body, Fields > const& msg); 26634 ``[''''»''' [link beast.ref.boost__beast__http__write.overload4 more...]]`` 26635 26636template< 26637 class __SyncWriteStream__, 26638 bool isRequest, 26639 class __Body__, 26640 class __Fields__> 26641std::size_t 26642``[link beast.ref.boost__beast__http__write.overload5 write]``( 26643 SyncWriteStream& stream, 26644 message< isRequest, Body, Fields >& msg, 26645 error_code& ec); 26646 ``[''''»''' [link beast.ref.boost__beast__http__write.overload5 more...]]`` 26647 26648template< 26649 class __SyncWriteStream__, 26650 bool isRequest, 26651 class __Body__, 26652 class __Fields__> 26653std::size_t 26654``[link beast.ref.boost__beast__http__write.overload6 write]``( 26655 SyncWriteStream& stream, 26656 message< isRequest, Body, Fields > const& msg, 26657 error_code& ec); 26658 ``[''''»''' [link beast.ref.boost__beast__http__write.overload6 more...]]`` 26659``` 26660[section:overload1 http::write (1 of 6 overloads)] 26661Write a complete message to a stream using a serializer. 26662[heading Synopsis] 26663 26664Defined in header [include_file boost/beast/http/write.hpp] 26665 26666 26667 26668``` 26669template< 26670 class __SyncWriteStream__, 26671 bool isRequest, 26672 class __Body__, 26673 class __Fields__> 26674std::size_t 26675write( 26676 SyncWriteStream& stream, 26677 serializer< isRequest, Body, Fields >& sr); 26678 26679``` 26680 26681[heading Description] 26682This 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: 26683 26684* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 26685 26686 26687* An error occurs. 26688 26689This operation is implemented in terms of one or more calls to the stream's `write_some` function. 26690[heading Parameters] 26691[table [[Name][Description]] 26692 [[`stream`][ 26693 26694The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26695 ]] 26696 [[`sr`][ 26697 26698The serializer to use. 26699 ]] 26700] 26701[heading Return Value] 26702The number of bytes written to the stream. 26703[heading Exceptions] 26704[table [[Type][Thrown On]] 26705 [[`system_error`][ 26706 26707Thrown on failure. 26708 ]] 26709] 26710[heading See Also] 26711[link beast.ref.boost__beast__http__serializer `http::serializer`] 26712 26713 26714 26715Convenience header [include_file boost/beast/http.hpp] 26716 26717[endsect] 26718[section:overload2 http::write (2 of 6 overloads)] 26719Write a complete message to a stream using a serializer. 26720[heading Synopsis] 26721 26722Defined in header [include_file boost/beast/http/write.hpp] 26723 26724 26725 26726``` 26727template< 26728 class __SyncWriteStream__, 26729 bool isRequest, 26730 class __Body__, 26731 class __Fields__> 26732std::size_t 26733write( 26734 SyncWriteStream& stream, 26735 serializer< isRequest, Body, Fields >& sr, 26736 error_code& ec); 26737 26738``` 26739 26740[heading Description] 26741This 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: 26742 26743* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 26744 26745 26746* An error occurs. 26747 26748This operation is implemented in terms of one or more calls to the stream's `write_some` function. 26749[heading Parameters] 26750[table [[Name][Description]] 26751 [[`stream`][ 26752 26753The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26754 ]] 26755 [[`sr`][ 26756 26757The serializer to use. 26758 ]] 26759 [[`ec`][ 26760 26761Set to the error, if any occurred. 26762 ]] 26763] 26764[heading Return Value] 26765The number of bytes written to the stream. 26766[heading See Also] 26767[link beast.ref.boost__beast__http__serializer `http::serializer`] 26768 26769 26770 26771Convenience header [include_file boost/beast/http.hpp] 26772 26773[endsect] 26774[section:overload3 http::write (3 of 6 overloads)] 26775Write a complete message to a stream. 26776[heading Synopsis] 26777 26778Defined in header [include_file boost/beast/http/write.hpp] 26779 26780 26781 26782``` 26783template< 26784 class __SyncWriteStream__, 26785 bool isRequest, 26786 class __Body__, 26787 class __Fields__> 26788std::size_t 26789write( 26790 SyncWriteStream& stream, 26791 message< isRequest, Body, Fields >& msg); 26792 26793``` 26794 26795[heading Description] 26796This 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: 26797 26798* The entire message is written. 26799 26800 26801* An error occurs. 26802 26803This operation is implemented in terms of one or more calls to the stream's `write_some` function. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 26804[heading Remarks] 26805This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `true`. 26806[heading Parameters] 26807[table [[Name][Description]] 26808 [[`stream`][ 26809 26810The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26811 ]] 26812 [[`msg`][ 26813 26814The message to write. 26815 ]] 26816] 26817[heading Return Value] 26818The number of bytes written to the stream. 26819[heading Exceptions] 26820[table [[Type][Thrown On]] 26821 [[`system_error`][ 26822 26823Thrown on failure. 26824 ]] 26825] 26826[heading See Also] 26827[link beast.ref.boost__beast__http__message `http::message`] 26828 26829 26830 26831Convenience header [include_file boost/beast/http.hpp] 26832 26833[endsect] 26834[section:overload4 http::write (4 of 6 overloads)] 26835Write a complete message to a stream. 26836[heading Synopsis] 26837 26838Defined in header [include_file boost/beast/http/write.hpp] 26839 26840 26841 26842``` 26843template< 26844 class __SyncWriteStream__, 26845 bool isRequest, 26846 class __Body__, 26847 class __Fields__> 26848std::size_t 26849write( 26850 SyncWriteStream& stream, 26851 message< isRequest, Body, Fields > const& msg); 26852 26853``` 26854 26855[heading Description] 26856This 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: 26857 26858* The entire message is written. 26859 26860 26861* An error occurs. 26862 26863This operation is implemented in terms of one or more calls to the stream's `write_some` function. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 26864[heading Remarks] 26865This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `false`. 26866[heading Parameters] 26867[table [[Name][Description]] 26868 [[`stream`][ 26869 26870The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26871 ]] 26872 [[`msg`][ 26873 26874The message to write. 26875 ]] 26876] 26877[heading Return Value] 26878The number of bytes written to the stream. 26879[heading Exceptions] 26880[table [[Type][Thrown On]] 26881 [[`system_error`][ 26882 26883Thrown on failure. 26884 ]] 26885] 26886[heading See Also] 26887[link beast.ref.boost__beast__http__message `http::message`] 26888 26889 26890 26891Convenience header [include_file boost/beast/http.hpp] 26892 26893[endsect] 26894[section:overload5 http::write (5 of 6 overloads)] 26895Write a complete message to a stream. 26896[heading Synopsis] 26897 26898Defined in header [include_file boost/beast/http/write.hpp] 26899 26900 26901 26902``` 26903template< 26904 class __SyncWriteStream__, 26905 bool isRequest, 26906 class __Body__, 26907 class __Fields__> 26908std::size_t 26909write( 26910 SyncWriteStream& stream, 26911 message< isRequest, Body, Fields >& msg, 26912 error_code& ec); 26913 26914``` 26915 26916[heading Description] 26917This 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: 26918 26919* The entire message is written. 26920 26921 26922* An error occurs. 26923 26924This operation is implemented in terms of one or more calls to the stream's `write_some` function. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 26925[heading Remarks] 26926This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `true`. 26927[heading Parameters] 26928[table [[Name][Description]] 26929 [[`stream`][ 26930 26931The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26932 ]] 26933 [[`msg`][ 26934 26935The message to write. 26936 ]] 26937 [[`ec`][ 26938 26939Set to the error, if any occurred. 26940 ]] 26941] 26942[heading Return Value] 26943The number of bytes written to the stream. 26944[heading See Also] 26945[link beast.ref.boost__beast__http__message `http::message`] 26946 26947 26948 26949Convenience header [include_file boost/beast/http.hpp] 26950 26951[endsect] 26952[section:overload6 http::write (6 of 6 overloads)] 26953Write a complete message to a stream. 26954[heading Synopsis] 26955 26956Defined in header [include_file boost/beast/http/write.hpp] 26957 26958 26959 26960``` 26961template< 26962 class __SyncWriteStream__, 26963 bool isRequest, 26964 class __Body__, 26965 class __Fields__> 26966std::size_t 26967write( 26968 SyncWriteStream& stream, 26969 message< isRequest, Body, Fields > const& msg, 26970 error_code& ec); 26971 26972``` 26973 26974[heading Description] 26975This 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: 26976 26977* The entire message is written. 26978 26979 26980* An error occurs. 26981 26982This operation is implemented in terms of one or more calls to the stream's `write_some` function. The algorithm will use a temporary [link beast.ref.boost__beast__http__serializer `http::serializer`] with an empty chunk decorator to produce buffers. 26983[heading Remarks] 26984This function only participates in overload resolution if [link beast.ref.boost__beast__http__is_mutable_body_writer `http::is_mutable_body_writer`] for ['Body] returns `false`. 26985[heading Parameters] 26986[table [[Name][Description]] 26987 [[`stream`][ 26988 26989The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 26990 ]] 26991 [[`msg`][ 26992 26993The message to write. 26994 ]] 26995 [[`ec`][ 26996 26997Set to the error, if any occurred. 26998 ]] 26999] 27000[heading Return Value] 27001The number of bytes written to the stream. 27002[heading See Also] 27003[link beast.ref.boost__beast__http__message `http::message`] 27004 27005 27006 27007Convenience header [include_file boost/beast/http.hpp] 27008 27009[endsect] 27010[endsect] 27011 27012 27013 27014[section:boost__beast__http__write_header http::write_header] 27015[indexterm1 http::write_header] 27016Write a header to a stream using a serializer. ``` 27017template< 27018 class __SyncWriteStream__, 27019 bool isRequest, 27020 class __Body__, 27021 class __Fields__> 27022std::size_t 27023``[link beast.ref.boost__beast__http__write_header.overload1 write_header]``( 27024 SyncWriteStream& stream, 27025 serializer< isRequest, Body, Fields >& sr); 27026 ``[''''»''' [link beast.ref.boost__beast__http__write_header.overload1 more...]]`` 27027 27028template< 27029 class __SyncWriteStream__, 27030 bool isRequest, 27031 class __Body__, 27032 class __Fields__> 27033std::size_t 27034``[link beast.ref.boost__beast__http__write_header.overload2 write_header]``( 27035 SyncWriteStream& stream, 27036 serializer< isRequest, Body, Fields >& sr, 27037 error_code& ec); 27038 ``[''''»''' [link beast.ref.boost__beast__http__write_header.overload2 more...]]`` 27039``` 27040[section:overload1 http::write_header (1 of 2 overloads)] 27041Write a header to a stream using a serializer. 27042[heading Synopsis] 27043 27044Defined in header [include_file boost/beast/http/write.hpp] 27045 27046 27047 27048``` 27049template< 27050 class __SyncWriteStream__, 27051 bool isRequest, 27052 class __Body__, 27053 class __Fields__> 27054std::size_t 27055write_header( 27056 SyncWriteStream& stream, 27057 serializer< isRequest, Body, Fields >& sr); 27058 27059``` 27060 27061[heading Description] 27062This 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: 27063 27064* The function [link beast.ref.boost__beast__http__serializer.is_header_done `http::serializer::is_header_done`] returns `true` 27065 27066 27067* An error occurs. 27068 27069This operation is implemented in terms of one or more calls to the stream's `write_some` function. 27070[heading Parameters] 27071[table [[Name][Description]] 27072 [[`stream`][ 27073 27074The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 27075 ]] 27076 [[`sr`][ 27077 27078The serializer to use. 27079 ]] 27080] 27081[heading Return Value] 27082The number of bytes written to the stream. 27083[heading Exceptions] 27084[table [[Type][Thrown On]] 27085 [[`system_error`][ 27086 27087Thrown on failure. 27088 ]] 27089] 27090[heading Remarks] 27091The implementation will call [link beast.ref.boost__beast__http__serializer.split `http::serializer::split`] with the value `true` on the serializer passed in. 27092[heading See Also] 27093[link beast.ref.boost__beast__http__serializer `http::serializer`] 27094 27095 27096 27097Convenience header [include_file boost/beast/http.hpp] 27098 27099[endsect] 27100[section:overload2 http::write_header (2 of 2 overloads)] 27101Write a header to a stream using a serializer. 27102[heading Synopsis] 27103 27104Defined in header [include_file boost/beast/http/write.hpp] 27105 27106 27107 27108``` 27109template< 27110 class __SyncWriteStream__, 27111 bool isRequest, 27112 class __Body__, 27113 class __Fields__> 27114std::size_t 27115write_header( 27116 SyncWriteStream& stream, 27117 serializer< isRequest, Body, Fields >& sr, 27118 error_code& ec); 27119 27120``` 27121 27122[heading Description] 27123This 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: 27124 27125* The function [link beast.ref.boost__beast__http__serializer.is_header_done `http::serializer::is_header_done`] returns `true` 27126 27127 27128* An error occurs. 27129 27130This operation is implemented in terms of one or more calls to the stream's `write_some` function. 27131[heading Parameters] 27132[table [[Name][Description]] 27133 [[`stream`][ 27134 27135The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 27136 ]] 27137 [[`sr`][ 27138 27139The serializer to use. 27140 ]] 27141 [[`ec`][ 27142 27143Set to indicate what error occurred, if any. 27144 ]] 27145] 27146[heading Return Value] 27147The number of bytes written to the stream. 27148[heading Remarks] 27149The implementation will call [link beast.ref.boost__beast__http__serializer.split `http::serializer::split`] with the value `true` on the serializer passed in. 27150[heading See Also] 27151[link beast.ref.boost__beast__http__serializer `http::serializer`] 27152 27153 27154 27155Convenience header [include_file boost/beast/http.hpp] 27156 27157[endsect] 27158[endsect] 27159 27160 27161 27162[section:boost__beast__http__write_some http::write_some] 27163[indexterm1 http::write_some] 27164Write part of a message to a stream using a serializer. ``` 27165template< 27166 class __SyncWriteStream__, 27167 bool isRequest, 27168 class __Body__, 27169 class __Fields__> 27170std::size_t 27171``[link beast.ref.boost__beast__http__write_some.overload1 write_some]``( 27172 SyncWriteStream& stream, 27173 serializer< isRequest, Body, Fields >& sr); 27174 ``[''''»''' [link beast.ref.boost__beast__http__write_some.overload1 more...]]`` 27175 27176template< 27177 class __SyncWriteStream__, 27178 bool isRequest, 27179 class __Body__, 27180 class __Fields__> 27181std::size_t 27182``[link beast.ref.boost__beast__http__write_some.overload2 write_some]``( 27183 SyncWriteStream& stream, 27184 serializer< isRequest, Body, Fields >& sr, 27185 error_code& ec); 27186 ``[''''»''' [link beast.ref.boost__beast__http__write_some.overload2 more...]]`` 27187``` 27188[section:overload1 http::write_some (1 of 2 overloads)] 27189Write part of a message to a stream using a serializer. 27190[heading Synopsis] 27191 27192Defined in header [include_file boost/beast/http/write.hpp] 27193 27194 27195 27196``` 27197template< 27198 class __SyncWriteStream__, 27199 bool isRequest, 27200 class __Body__, 27201 class __Fields__> 27202std::size_t 27203write_some( 27204 SyncWriteStream& stream, 27205 serializer< isRequest, Body, Fields >& sr); 27206 27207``` 27208 27209[heading Description] 27210This 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: 27211 27212* One or more bytes have been transferred. 27213 27214 27215* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 27216 27217 27218* An error occurs on the stream. 27219 27220This operation is implemented in terms of one or more calls to the stream's `write_some` function. 27221The 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 [link beast.ref.boost__beast__http__serializer.limit `http::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. 27222[heading Parameters] 27223[table [[Name][Description]] 27224 [[`stream`][ 27225 27226The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 27227 ]] 27228 [[`sr`][ 27229 27230The serializer to use. 27231 ]] 27232] 27233[heading Return Value] 27234The number of bytes written to the stream. 27235[heading Exceptions] 27236[table [[Type][Thrown On]] 27237 [[`system_error`][ 27238 27239Thrown on failure. 27240 ]] 27241] 27242[heading See Also] 27243[link beast.ref.boost__beast__http__serializer `http::serializer`] 27244 27245 27246 27247Convenience header [include_file boost/beast/http.hpp] 27248 27249[endsect] 27250[section:overload2 http::write_some (2 of 2 overloads)] 27251Write part of a message to a stream using a serializer. 27252[heading Synopsis] 27253 27254Defined in header [include_file boost/beast/http/write.hpp] 27255 27256 27257 27258``` 27259template< 27260 class __SyncWriteStream__, 27261 bool isRequest, 27262 class __Body__, 27263 class __Fields__> 27264std::size_t 27265write_some( 27266 SyncWriteStream& stream, 27267 serializer< isRequest, Body, Fields >& sr, 27268 error_code& ec); 27269 27270``` 27271 27272[heading Description] 27273This 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: 27274 27275* One or more bytes have been transferred. 27276 27277 27278* The function [link beast.ref.boost__beast__http__serializer.is_done `http::serializer::is_done`] returns `true` 27279 27280 27281* An error occurs on the stream. 27282 27283This operation is implemented in terms of one or more calls to the stream's `write_some` function. 27284The 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 [link beast.ref.boost__beast__http__serializer.limit `http::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. 27285[heading Parameters] 27286[table [[Name][Description]] 27287 [[`stream`][ 27288 27289The stream to which the data is to be written. The type must support the ['SyncWriteStream] concept. 27290 ]] 27291 [[`sr`][ 27292 27293The serializer to use. 27294 ]] 27295 [[`ec`][ 27296 27297Set to indicate what error occurred, if any. 27298 ]] 27299] 27300[heading Return Value] 27301The number of bytes written to the stream. 27302[heading See Also] 27303[link beast.ref.boost__beast__http__async_write_some `http::async_write_some`], [link beast.ref.boost__beast__http__serializer `http::serializer`] 27304 27305 27306 27307Convenience header [include_file boost/beast/http.hpp] 27308 27309[endsect] 27310[endsect] 27311 27312 27313 27314[section:boost__beast__iequal iequal] 27315A case-insensitive equality predicate for strings. 27316[heading Synopsis] 27317 27318Defined in header [include_file boost/beast/core/string.hpp] 27319 27320 27321 27322``` 27323struct iequal 27324``` 27325[heading Member Functions] 27326[table [[Name][Description]] 27327 [ 27328 [[link beast.ref.boost__beast__iequal.operator_lp__rp_ [*operator()]]] 27329 [ 27330 27331 ] 27332 ] 27333] 27334 27335[heading Description] 27336The case-comparison operation is defined only for low-ASCII characters. [section:operator_lp__rp_ iequal::operator()] 27337[indexterm2 operator()..iequal] 27338 27339[heading Synopsis] 27340``` 27341bool 27342operator()( 27343 string_view lhs, 27344 string_view rhs) const; 27345``` 27346 27347[heading Description] 27348[endsect] 27349 27350 27351 27352Convenience header [include_file boost/beast/core.hpp] 27353 27354[endsect] 27355 27356 27357 27358[section:boost__beast__iequals iequals] 27359[indexterm1 iequals] 27360Returns `true` if two strings are equal, using a case-insensitive comparison. 27361[heading Synopsis] 27362 27363Defined in header [include_file boost/beast/core/string.hpp] 27364 27365 27366 27367``` 27368bool 27369iequals( 27370 beast::string_view lhs, 27371 beast::string_view rhs); 27372 27373``` 27374 27375[heading Description] 27376The case-comparison operation is defined only for low-ASCII characters. 27377[heading Parameters] 27378[table [[Name][Description]] 27379 [[`lhs`][ 27380 27381The string on the left side of the equality 27382 ]] 27383 [[`rhs`][ 27384 27385The string on the right side of the equality 27386 ]] 27387] 27388 27389 27390 27391Convenience header [include_file boost/beast/core.hpp] 27392 27393[endsect] 27394[section:boost__beast__iless iless] 27395A case-insensitive less predicate for strings. 27396[heading Synopsis] 27397 27398Defined in header [include_file boost/beast/core/string.hpp] 27399 27400 27401 27402``` 27403struct iless 27404``` 27405[heading Member Functions] 27406[table [[Name][Description]] 27407 [ 27408 [[link beast.ref.boost__beast__iless.operator_lp__rp_ [*operator()]]] 27409 [ 27410 27411 ] 27412 ] 27413] 27414 27415[heading Description] 27416The case-comparison operation is defined only for low-ASCII characters. [section:operator_lp__rp_ iless::operator()] 27417[indexterm2 operator()..iless] 27418 27419[heading Synopsis] 27420``` 27421bool 27422operator()( 27423 string_view lhs, 27424 string_view rhs) const; 27425``` 27426 27427[heading Description] 27428[endsect] 27429 27430 27431 27432Convenience header [include_file boost/beast/core.hpp] 27433 27434[endsect] 27435 27436 27437 27438[section:boost__beast__is_async_read_stream is_async_read_stream] 27439[indexterm1 is_async_read_stream] 27440Determine if `T` meets the requirements of ['AsyncReadStream]. 27441[heading Synopsis] 27442 27443Defined in header [include_file boost/beast/core/stream_traits.hpp] 27444 27445 27446 27447``` 27448template< 27449 class T> 27450using is_async_read_stream = ``['see-below]``; 27451``` 27452 27453[heading Description] 27454Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27455[heading Example] 27456 27457Use with `static_assert`: 27458 27459``` 27460 template<class AsyncReadStream> 27461 void f(AsyncReadStream& stream) 27462 { 27463 static_assert(is_async_read_stream<AsyncReadStream>::value, 27464 "AsyncReadStream type requirements not met"); 27465 ... 27466``` 27467Use with `std::enable_if` (SFINAE): 27468 27469``` 27470 template<class AsyncReadStream> 27471 typename std::enable_if<is_async_read_stream<AsyncReadStream>::value>::type 27472 f(AsyncReadStream& stream); 27473``` 27474 27475 27476 27477Convenience header [include_file boost/beast/core.hpp] 27478 27479[endsect] 27480[section:boost__beast__is_async_stream is_async_stream] 27481[indexterm1 is_async_stream] 27482Determine if `T` meets the requirements of [*AsyncStream]. 27483[heading Synopsis] 27484 27485Defined in header [include_file boost/beast/core/stream_traits.hpp] 27486 27487 27488 27489``` 27490template< 27491 class T> 27492using is_async_stream = ``['see-below]``; 27493``` 27494 27495[heading Description] 27496Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27497[heading Example] 27498 27499Use with `static_assert`: 27500 27501``` 27502 template<class AsyncStream> 27503 void f(AsyncStream& stream) 27504 { 27505 static_assert(is_async_stream<AsyncStream>::value, 27506 "AsyncStream type requirements not met"); 27507 ... 27508``` 27509Use with `std::enable_if` (SFINAE): 27510 27511``` 27512 template<class AsyncStream> 27513 typename std::enable_if<is_async_stream<AsyncStream>::value>::type 27514 f(AsyncStream& stream); 27515``` 27516 27517 27518 27519Convenience header [include_file boost/beast/core.hpp] 27520 27521[endsect] 27522[section:boost__beast__is_async_write_stream is_async_write_stream] 27523[indexterm1 is_async_write_stream] 27524Determine if `T` meets the requirements of ['AsyncWriteStream]. 27525[heading Synopsis] 27526 27527Defined in header [include_file boost/beast/core/stream_traits.hpp] 27528 27529 27530 27531``` 27532template< 27533 class T> 27534using is_async_write_stream = ``['see-below]``; 27535``` 27536 27537[heading Description] 27538Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27539[heading Example] 27540 27541Use with `static_assert`: 27542 27543``` 27544 template<class AsyncWriteStream> 27545 void f(AsyncWriteStream& stream) 27546 { 27547 static_assert(is_async_write_stream<AsyncWriteStream>::value, 27548 "AsyncWriteStream type requirements not met"); 27549 ... 27550``` 27551Use with `std::enable_if` (SFINAE): 27552 27553``` 27554 template<class AsyncWriteStream> 27555 typename std::enable_if<is_async_write_stream<AsyncWriteStream>::value>::type 27556 f(AsyncWriteStream& stream); 27557``` 27558 27559 27560 27561Convenience header [include_file boost/beast/core.hpp] 27562 27563[endsect] 27564[section:boost__beast__is_const_buffer_sequence is_const_buffer_sequence] 27565[indexterm1 is_const_buffer_sequence] 27566Determine if a list of types satisfy the ['ConstBufferSequence] requirements. 27567[heading Synopsis] 27568 27569Defined in header [include_file boost/beast/core/buffer_traits.hpp] 27570 27571 27572 27573``` 27574template< 27575 class... __BufferSequence__> 27576using is_const_buffer_sequence = ``['see-below]``; 27577``` 27578 27579[heading Description] 27580This metafunction is used to determine if all of the specified types meet the requirements for constant buffer sequences. This type alias will be `std::true_type` if each specified type meets the requirements, otherwise, this type alias will be `std::false_type`. 27581[heading Template Parameters] 27582[table [[Type][Description]] 27583 [[`BufferSequence`][ 27584 27585A list of zero or more types to check. If this list is empty, the resulting type alias will be `std::true_type`. 27586 ]] 27587] 27588 27589 27590 27591Convenience header [include_file boost/beast/core.hpp] 27592 27593[endsect] 27594[section:boost__beast__is_file is_file] 27595Determine if `T` meets the requirements of ['File]. 27596[heading Synopsis] 27597 27598Defined in header [include_file boost/beast/core/file_base.hpp] 27599 27600 27601 27602``` 27603template< 27604 class T> 27605struct is_file : 27606 public std::integral_constant< bool,... > 27607``` 27608 27609[heading Description] 27610Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27611[heading Example] 27612 27613Use with `static_assert`: 27614 27615``` 27616 template<class File> 27617 void f(File& file) 27618 { 27619 static_assert(is_file<File>::value, 27620 "File type requirements not met"); 27621 ... 27622``` 27623Use with `std::enable_if` (SFINAE): 27624 27625``` 27626 template<class File> 27627 typename std::enable_if<is_file<File>::value>::type 27628 f(File& file); 27629``` 27630 27631 27632 27633Convenience header [include_file boost/beast/core.hpp] 27634 27635[endsect] 27636 27637 27638 27639[section:boost__beast__is_mutable_buffer_sequence is_mutable_buffer_sequence] 27640[indexterm1 is_mutable_buffer_sequence] 27641Determine if a list of types satisfy the ['MutableBufferSequence] requirements. 27642[heading Synopsis] 27643 27644Defined in header [include_file boost/beast/core/buffer_traits.hpp] 27645 27646 27647 27648``` 27649template< 27650 class... __BufferSequence__> 27651using is_mutable_buffer_sequence = ``['see-below]``; 27652``` 27653 27654[heading Description] 27655This metafunction is used to determine if all of the specified types meet the requirements for mutable buffer sequences. This type alias will be `std::true_type` if each specified type meets the requirements, otherwise, this type alias will be `std::false_type`. 27656[heading Template Parameters] 27657[table [[Type][Description]] 27658 [[`BufferSequence`][ 27659 27660A list of zero or more types to check. If this list is empty, the resulting type alias will be `std::true_type`. 27661 ]] 27662] 27663 27664 27665 27666Convenience header [include_file boost/beast/core.hpp] 27667 27668[endsect] 27669[section:boost__beast__is_sync_read_stream is_sync_read_stream] 27670[indexterm1 is_sync_read_stream] 27671Determine if at type meets the requirements of ['SyncReadStream]. 27672[heading Synopsis] 27673 27674Defined in header [include_file boost/beast/core/stream_traits.hpp] 27675 27676 27677 27678``` 27679template< 27680 class T> 27681using is_sync_read_stream = ``['see-below]``; 27682``` 27683 27684[heading Description] 27685Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27686[heading Example] 27687Use with `static_assert`: 27688``` 27689 template<class SyncReadStream> 27690 void f(SyncReadStream& stream) 27691 { 27692 static_assert(is_sync_read_stream<SyncReadStream>::value, 27693 "SyncReadStream type requirements not met"); 27694 ... 27695``` 27696Use with `std::enable_if` (SFINAE): 27697``` 27698 template<class SyncReadStream> 27699 typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type 27700 f(SyncReadStream& stream); 27701``` 27702 27703 27704 27705Convenience header [include_file boost/beast/core.hpp] 27706 27707[endsect] 27708[section:boost__beast__is_sync_stream is_sync_stream] 27709[indexterm1 is_sync_stream] 27710Determine if `T` meets the requirements of [*SyncStream]. 27711[heading Synopsis] 27712 27713Defined in header [include_file boost/beast/core/stream_traits.hpp] 27714 27715 27716 27717``` 27718template< 27719 class T> 27720using is_sync_stream = ``['see-below]``; 27721``` 27722 27723[heading Description] 27724Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27725[heading Example] 27726 27727Use with `static_assert`: 27728 27729``` 27730 template<class SyncStream> 27731 void f(SyncStream& stream) 27732 { 27733 static_assert(is_sync_stream<SyncStream>::value, 27734 "SyncStream type requirements not met"); 27735 ... 27736``` 27737Use with `std::enable_if` (SFINAE): 27738 27739``` 27740 template<class SyncStream> 27741 typename std::enable_if<is_sync_stream<SyncStream>::value>::type 27742 f(SyncStream& stream); 27743``` 27744 27745 27746 27747Convenience header [include_file boost/beast/core.hpp] 27748 27749[endsect] 27750[section:boost__beast__is_sync_write_stream is_sync_write_stream] 27751[indexterm1 is_sync_write_stream] 27752Determine if `T` meets the requirements of ['SyncWriteStream]. 27753[heading Synopsis] 27754 27755Defined in header [include_file boost/beast/core/stream_traits.hpp] 27756 27757 27758 27759``` 27760template< 27761 class T> 27762using is_sync_write_stream = ``['see-below]``; 27763``` 27764 27765[heading Description] 27766Metafunctions are used to perform compile time checking of template types. This type will be `std::true_type` if `T` meets the requirements, else the type will be `std::false_type`. 27767[heading Example] 27768 27769Use with `static_assert`: 27770 27771``` 27772 template<class SyncReadStream> 27773 void f(SyncReadStream& stream) 27774 { 27775 static_assert(is_sync_read_stream<SyncReadStream>::value, 27776 "SyncReadStream type requirements not met"); 27777 ... 27778``` 27779Use with `std::enable_if` (SFINAE): 27780 27781``` 27782 template<class SyncReadStream> 27783 typename std::enable_if<is_sync_read_stream<SyncReadStream>::value>::type 27784 f(SyncReadStream& stream); 27785``` 27786 27787 27788 27789Convenience header [include_file boost/beast/core.hpp] 27790 27791[endsect] 27792[section:boost__beast__lowest_layer_type lowest_layer_type] 27793[indexterm1 lowest_layer_type] 27794A trait to determine the lowest layer type of a stack of stream layers. 27795[heading Synopsis] 27796 27797Defined in header [include_file boost/beast/core/stream_traits.hpp] 27798 27799 27800 27801``` 27802template< 27803 class T> 27804using lowest_layer_type = ``['see-below]``; 27805``` 27806 27807[heading Description] 27808If `t.next_layer()` is well-defined for an object `t` of type `T`, then `lowest_layer_type<T>` will be an alias for `lowest_layer_type<decltype(t.next_layer())>`, otherwise it will be the type `std::remove_reference<T>`. 27809[heading Parameters] 27810[table [[Name][Description]] 27811 [[`T`][ 27812 27813The type to determine the lowest layer type of. 27814 ]] 27815] 27816[heading Return Value] 27817The type of the lowest layer. 27818 27819 27820 27821Convenience header [include_file boost/beast/core.hpp] 27822 27823[endsect] 27824[section:boost__beast__make_printable make_printable] 27825[indexterm1 make_printable] 27826Helper to permit a buffer sequence to be printed to a std::ostream. 27827[heading Synopsis] 27828 27829Defined in header [include_file boost/beast/core/make_printable.hpp] 27830 27831 27832 27833``` 27834template< 27835 class __ConstBufferSequence__> 27836``['implementation-defined]`` 27837make_printable( 27838 ConstBufferSequence const& buffers); 27839 27840``` 27841 27842[heading Description] 27843This function is used to wrap a buffer sequence to allow it to be interpreted as characters and written to a `std::ostream` such as `std::cout`. No character translation is performed; unprintable and null characters will be transferred as-is to the output stream. 27844[heading Example] 27845This function prints the size and contents of a buffer sequence to standard output: 27846``` 27847 template <class ConstBufferSequence> 27848 void 27849 print (ConstBufferSequence const& buffers) 27850 { 27851 std::cout << 27852 "Buffer size: " << buffer_bytes(buffers) << " bytes\n" 27853 "Buffer data: '" << make_printable(buffers) << "'\n"; 27854 } 27855``` 27856[heading Parameters] 27857[table [[Name][Description]] 27858 [[`buffers`][ 27859 27860An object meeting the requirements of ['ConstBufferSequence] to be streamed. The implementation will make a copy of this object. Ownership of the underlying memory is not transferred, the application is still responsible for managing its lifetime. 27861 ]] 27862] 27863 27864 27865 27866Convenience header [include_file boost/beast/core.hpp] 27867 27868[endsect] 27869[section:boost__beast__multi_buffer multi_buffer] 27870[indexterm1 multi_buffer] 27871A typical multi buffer. 27872[heading Synopsis] 27873 27874Defined in header [include_file boost/beast/core/multi_buffer.hpp] 27875 27876 27877 27878``` 27879using multi_buffer = basic_multi_buffer< std::allocator< char > >; 27880``` 27881[heading Types] 27882[table [[Name][Description]] 27883 [ 27884 [[link beast.ref.boost__beast__basic_multi_buffer.allocator_type [*allocator_type]]] 27885 [ 27886 The type of allocator used. 27887 ] 27888 ] 27889 [ 27890 [[link beast.ref.boost__beast__basic_multi_buffer.const_buffers_type [*const_buffers_type]]] 27891 [ 27892 The ConstBufferSequence used to represent the readable bytes. 27893 ] 27894 ] 27895 [ 27896 [[link beast.ref.boost__beast__basic_multi_buffer.mutable_buffers_type [*mutable_buffers_type]]] 27897 [ 27898 The MutableBufferSequence used to represent the writable bytes. 27899 ] 27900 ] 27901 [ 27902 [[link beast.ref.boost__beast__basic_multi_buffer.mutable_data_type [*mutable_data_type]]] 27903 [ 27904 The MutableBufferSequence used to represent the readable bytes. 27905 ] 27906 ] 27907] 27908[heading Member Functions] 27909[table [[Name][Description]] 27910 [ 27911 [[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer [*basic_multi_buffer]]] 27912 [ 27913 Constructor. 27914 27915 Move Constructor. 27916 27917 Copy Constructor. 27918 ] 27919 ] 27920 [ 27921 [[link beast.ref.boost__beast__basic_multi_buffer.capacity [*capacity]]] 27922 [ 27923 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 27924 ] 27925 ] 27926 [ 27927 [[link beast.ref.boost__beast__basic_multi_buffer.cdata [*cdata]]] 27928 [ 27929 Returns a constant buffer sequence representing the readable bytes. 27930 ] 27931 ] 27932 [ 27933 [[link beast.ref.boost__beast__basic_multi_buffer.clear [*clear]]] 27934 [ 27935 Set the size of the readable and writable bytes to zero. 27936 ] 27937 ] 27938 [ 27939 [[link beast.ref.boost__beast__basic_multi_buffer.commit [*commit]]] 27940 [ 27941 Append writable bytes to the readable bytes. 27942 ] 27943 ] 27944 [ 27945 [[link beast.ref.boost__beast__basic_multi_buffer.consume [*consume]]] 27946 [ 27947 Remove bytes from beginning of the readable bytes. 27948 ] 27949 ] 27950 [ 27951 [[link beast.ref.boost__beast__basic_multi_buffer.data [*data]]] 27952 [ 27953 Returns a constant buffer sequence representing the readable bytes. 27954 27955 Returns a mutable buffer sequence representing the readable bytes. 27956 ] 27957 ] 27958 [ 27959 [[link beast.ref.boost__beast__basic_multi_buffer.get_allocator [*get_allocator]]] 27960 [ 27961 Returns a copy of the allocator used. 27962 ] 27963 ] 27964 [ 27965 [[link beast.ref.boost__beast__basic_multi_buffer.max_size [*max_size]]] 27966 [ 27967 Set the maximum allowed capacity. 27968 27969 Return the maximum number of bytes, both readable and writable, that can ever be held. 27970 ] 27971 ] 27972 [ 27973 [[link beast.ref.boost__beast__basic_multi_buffer.operator_eq_ [*operator=]]] 27974 [ 27975 Move Assignment. 27976 27977 Copy Assignment. 27978 ] 27979 ] 27980 [ 27981 [[link beast.ref.boost__beast__basic_multi_buffer.prepare [*prepare]]] 27982 [ 27983 Returns a mutable buffer sequence representing writable bytes. 27984 ] 27985 ] 27986 [ 27987 [[link beast.ref.boost__beast__basic_multi_buffer.reserve [*reserve]]] 27988 [ 27989 Guarantee a minimum capacity. 27990 ] 27991 ] 27992 [ 27993 [[link beast.ref.boost__beast__basic_multi_buffer.shrink_to_fit [*shrink_to_fit]]] 27994 [ 27995 Reallocate the buffer to fit the readable bytes exactly. 27996 ] 27997 ] 27998 [ 27999 [[link beast.ref.boost__beast__basic_multi_buffer.size [*size]]] 28000 [ 28001 Returns the number of readable bytes. 28002 ] 28003 ] 28004 [ 28005 [[link beast.ref.boost__beast__basic_multi_buffer.basic_multi_buffer_dtor_ [*~basic_multi_buffer]]] 28006 [ 28007 Destructor. 28008 ] 28009 ] 28010] 28011[heading Friends] 28012[table [[Name][Description]] 28013 [ 28014 [[link beast.ref.boost__beast__basic_multi_buffer.swap [*swap]]] 28015 [ 28016 Exchange two dynamic buffers. 28017 ] 28018 ] 28019] 28020A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 28021The implementation uses a sequence of one or more byte arrays of varying sizes to represent the readable and writable bytes. Additional byte array objects are appended to the sequence to accommodate changes in the desired size. The behavior and implementation of this container is most similar to `std::deque`. 28022Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 28023 28024* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] when `this` is non-const. 28025 28026 28027* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] and [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`], may have length greater than one. 28028 28029 28030* A configurable maximum size may be set upon construction and adjusted afterwards. Calls to [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] that would exceed this size will throw `std::length_error`. 28031 28032 28033* Sequences previously obtained using [link beast.ref.boost__beast__basic_multi_buffer.data `basic_multi_buffer::data`] remain valid after calls to [link beast.ref.boost__beast__basic_multi_buffer.prepare `basic_multi_buffer::prepare`] or [link beast.ref.boost__beast__basic_multi_buffer.commit `basic_multi_buffer::commit`]. 28034 28035[heading Template Parameters] 28036[table [[Type][Description]] 28037 [[`Allocator`][ 28038 28039The allocator to use for managing memory. 28040 ]] 28041] 28042 28043[heading Description] 28044 28045 28046 28047Convenience header [include_file boost/beast/core.hpp] 28048 28049[endsect] 28050[section:boost__beast__operator_not__eq_ operator!=] 28051[indexterm1 operator!=] 28052``` 28053template< 28054 std::size_t N, 28055 std::size_t M, 28056 class CharT, 28057 class Traits> 28058bool 28059``[link beast.ref.boost__beast__operator_not__eq_.overload1 operator!=]``( 28060 static_string< N, CharT, Traits > const& lhs, 28061 static_string< M, CharT, Traits > const& rhs); 28062 ``[''''»''' [link beast.ref.boost__beast__operator_not__eq_.overload1 more...]]`` 28063 28064template< 28065 std::size_t N, 28066 class CharT, 28067 class Traits> 28068bool 28069``[link beast.ref.boost__beast__operator_not__eq_.overload2 operator!=]``( 28070 CharT const* lhs, 28071 static_string< N, CharT, Traits > const& rhs); 28072 ``[''''»''' [link beast.ref.boost__beast__operator_not__eq_.overload2 more...]]`` 28073 28074template< 28075 std::size_t N, 28076 class CharT, 28077 class Traits> 28078bool 28079``[link beast.ref.boost__beast__operator_not__eq_.overload3 operator!=]``( 28080 static_string< N, CharT, Traits > const& lhs, 28081 CharT const* rhs); 28082 ``[''''»''' [link beast.ref.boost__beast__operator_not__eq_.overload3 more...]]`` 28083``` 28084[section:overload1 operator!= (1 of 3 overloads)] 28085 28086[heading Synopsis] 28087 28088Defined in header [include_file boost/beast/core/static_string.hpp] 28089 28090 28091 28092``` 28093template< 28094 std::size_t N, 28095 std::size_t M, 28096 class CharT, 28097 class Traits> 28098bool 28099operator!=( 28100 static_string< N, CharT, Traits > const& lhs, 28101 static_string< M, CharT, Traits > const& rhs); 28102 28103``` 28104 28105[heading Description] 28106 28107 28108 28109Convenience header [include_file boost/beast/core.hpp] 28110 28111[endsect] 28112[section:overload2 operator!= (2 of 3 overloads)] 28113 28114[heading Synopsis] 28115 28116Defined in header [include_file boost/beast/core/static_string.hpp] 28117 28118 28119 28120``` 28121template< 28122 std::size_t N, 28123 class CharT, 28124 class Traits> 28125bool 28126operator!=( 28127 CharT const* lhs, 28128 static_string< N, CharT, Traits > const& rhs); 28129 28130``` 28131 28132[heading Description] 28133 28134 28135 28136Convenience header [include_file boost/beast/core.hpp] 28137 28138[endsect] 28139[section:overload3 operator!= (3 of 3 overloads)] 28140 28141[heading Synopsis] 28142 28143Defined in header [include_file boost/beast/core/static_string.hpp] 28144 28145 28146 28147``` 28148template< 28149 std::size_t N, 28150 class CharT, 28151 class Traits> 28152bool 28153operator!=( 28154 static_string< N, CharT, Traits > const& lhs, 28155 CharT const* rhs); 28156 28157``` 28158 28159[heading Description] 28160 28161 28162 28163Convenience header [include_file boost/beast/core.hpp] 28164 28165[endsect] 28166[endsect] 28167 28168 28169 28170[section:boost__beast__operator_plus_ operator+] 28171[indexterm1 operator+] 28172``` 28173template< 28174 std::size_t N, 28175 std::size_t M, 28176 class CharT, 28177 class Traits> 28178void 28179``[link beast.ref.boost__beast__operator_plus_.overload1 operator+]``( 28180 static_string< N, CharT, Traits >const&, 28181 static_string< M, CharT, Traits >const&); 28182 ``[''''»''' [link beast.ref.boost__beast__operator_plus_.overload1 more...]]`` 28183 28184template< 28185 std::size_t N, 28186 class CharT, 28187 class Traits> 28188void 28189``[link beast.ref.boost__beast__operator_plus_.overload2 operator+]``( 28190 CharT const*, 28191 static_string< N, CharT, Traits >const&); 28192 ``[''''»''' [link beast.ref.boost__beast__operator_plus_.overload2 more...]]`` 28193 28194template< 28195 std::size_t N, 28196 class CharT, 28197 class Traits> 28198void 28199``[link beast.ref.boost__beast__operator_plus_.overload3 operator+]``( 28200 CharT, 28201 static_string< N, CharT, Traits > const&); 28202 ``[''''»''' [link beast.ref.boost__beast__operator_plus_.overload3 more...]]`` 28203 28204template< 28205 std::size_t N, 28206 class CharT, 28207 class Traits> 28208void 28209``[link beast.ref.boost__beast__operator_plus_.overload4 operator+]``( 28210 static_string< N, CharT, Traits > const&, 28211 CharT const*); 28212 ``[''''»''' [link beast.ref.boost__beast__operator_plus_.overload4 more...]]`` 28213 28214template< 28215 std::size_t N, 28216 class CharT, 28217 class Traits> 28218void 28219``[link beast.ref.boost__beast__operator_plus_.overload5 operator+]``( 28220 static_string< N, CharT, Traits > const&, 28221 CharT); 28222 ``[''''»''' [link beast.ref.boost__beast__operator_plus_.overload5 more...]]`` 28223``` 28224[section:overload1 operator+ (1 of 5 overloads)] 28225 28226[heading Synopsis] 28227 28228Defined in header [include_file boost/beast/core/static_string.hpp] 28229 28230 28231 28232``` 28233template< 28234 std::size_t N, 28235 std::size_t M, 28236 class CharT, 28237 class Traits> 28238void 28239operator+( 28240 static_string< N, CharT, Traits >const&, 28241 static_string< M, CharT, Traits >const&); 28242 28243``` 28244 28245[heading Description] 28246 28247 28248 28249Convenience header [include_file boost/beast/core.hpp] 28250 28251[endsect] 28252[section:overload2 operator+ (2 of 5 overloads)] 28253 28254[heading Synopsis] 28255 28256Defined in header [include_file boost/beast/core/static_string.hpp] 28257 28258 28259 28260``` 28261template< 28262 std::size_t N, 28263 class CharT, 28264 class Traits> 28265void 28266operator+( 28267 CharT const*, 28268 static_string< N, CharT, Traits >const&); 28269 28270``` 28271 28272[heading Description] 28273 28274 28275 28276Convenience header [include_file boost/beast/core.hpp] 28277 28278[endsect] 28279[section:overload3 operator+ (3 of 5 overloads)] 28280 28281[heading Synopsis] 28282 28283Defined in header [include_file boost/beast/core/static_string.hpp] 28284 28285 28286 28287``` 28288template< 28289 std::size_t N, 28290 class CharT, 28291 class Traits> 28292void 28293operator+( 28294 CharT, 28295 static_string< N, CharT, Traits > const&); 28296 28297``` 28298 28299[heading Description] 28300 28301 28302 28303Convenience header [include_file boost/beast/core.hpp] 28304 28305[endsect] 28306[section:overload4 operator+ (4 of 5 overloads)] 28307 28308[heading Synopsis] 28309 28310Defined in header [include_file boost/beast/core/static_string.hpp] 28311 28312 28313 28314``` 28315template< 28316 std::size_t N, 28317 class CharT, 28318 class Traits> 28319void 28320operator+( 28321 static_string< N, CharT, Traits > const&, 28322 CharT const*); 28323 28324``` 28325 28326[heading Description] 28327 28328 28329 28330Convenience header [include_file boost/beast/core.hpp] 28331 28332[endsect] 28333[section:overload5 operator+ (5 of 5 overloads)] 28334 28335[heading Synopsis] 28336 28337Defined in header [include_file boost/beast/core/static_string.hpp] 28338 28339 28340 28341``` 28342template< 28343 std::size_t N, 28344 class CharT, 28345 class Traits> 28346void 28347operator+( 28348 static_string< N, CharT, Traits > const&, 28349 CharT); 28350 28351``` 28352 28353[heading Description] 28354 28355 28356 28357Convenience header [include_file boost/beast/core.hpp] 28358 28359[endsect] 28360[endsect] 28361 28362 28363 28364[section:boost__beast__operator_lt_ operator<] 28365[indexterm1 operator<] 28366``` 28367template< 28368 std::size_t N, 28369 std::size_t M, 28370 class CharT, 28371 class Traits> 28372bool 28373``[link beast.ref.boost__beast__operator_lt_.overload1 operator<]``( 28374 static_string< N, CharT, Traits > const& lhs, 28375 static_string< M, CharT, Traits > const& rhs); 28376 ``[''''»''' [link beast.ref.boost__beast__operator_lt_.overload1 more...]]`` 28377 28378template< 28379 std::size_t N, 28380 class CharT, 28381 class Traits> 28382bool 28383``[link beast.ref.boost__beast__operator_lt_.overload2 operator<]``( 28384 CharT const* lhs, 28385 static_string< N, CharT, Traits > const& rhs); 28386 ``[''''»''' [link beast.ref.boost__beast__operator_lt_.overload2 more...]]`` 28387 28388template< 28389 std::size_t N, 28390 class CharT, 28391 class Traits> 28392bool 28393``[link beast.ref.boost__beast__operator_lt_.overload3 operator<]``( 28394 static_string< N, CharT, Traits > const& lhs, 28395 CharT const* rhs); 28396 ``[''''»''' [link beast.ref.boost__beast__operator_lt_.overload3 more...]]`` 28397``` 28398[section:overload1 operator< (1 of 3 overloads)] 28399 28400[heading Synopsis] 28401 28402Defined in header [include_file boost/beast/core/static_string.hpp] 28403 28404 28405 28406``` 28407template< 28408 std::size_t N, 28409 std::size_t M, 28410 class CharT, 28411 class Traits> 28412bool 28413operator<( 28414 static_string< N, CharT, Traits > const& lhs, 28415 static_string< M, CharT, Traits > const& rhs); 28416 28417``` 28418 28419[heading Description] 28420 28421 28422 28423Convenience header [include_file boost/beast/core.hpp] 28424 28425[endsect] 28426[section:overload2 operator< (2 of 3 overloads)] 28427 28428[heading Synopsis] 28429 28430Defined in header [include_file boost/beast/core/static_string.hpp] 28431 28432 28433 28434``` 28435template< 28436 std::size_t N, 28437 class CharT, 28438 class Traits> 28439bool 28440operator<( 28441 CharT const* lhs, 28442 static_string< N, CharT, Traits > const& rhs); 28443 28444``` 28445 28446[heading Description] 28447 28448 28449 28450Convenience header [include_file boost/beast/core.hpp] 28451 28452[endsect] 28453[section:overload3 operator< (3 of 3 overloads)] 28454 28455[heading Synopsis] 28456 28457Defined in header [include_file boost/beast/core/static_string.hpp] 28458 28459 28460 28461``` 28462template< 28463 std::size_t N, 28464 class CharT, 28465 class Traits> 28466bool 28467operator<( 28468 static_string< N, CharT, Traits > const& lhs, 28469 CharT const* rhs); 28470 28471``` 28472 28473[heading Description] 28474 28475 28476 28477Convenience header [include_file boost/beast/core.hpp] 28478 28479[endsect] 28480[endsect] 28481 28482 28483 28484[section:boost__beast__operator_lt__lt_ operator<<] 28485[indexterm1 operator<<] 28486 28487[heading Synopsis] 28488 28489Defined in header [include_file boost/beast/core/static_string.hpp] 28490 28491 28492 28493``` 28494template< 28495 std::size_t N, 28496 class CharT, 28497 class Traits> 28498std::basic_ostream< CharT, Traits >& 28499operator<<( 28500 std::basic_ostream< CharT, Traits >& os, 28501 static_string< N, CharT, Traits > const& str); 28502 28503``` 28504 28505[heading Description] 28506 28507 28508 28509Convenience header [include_file boost/beast/core.hpp] 28510 28511[endsect] 28512[section:boost__beast__operator_lt__eq_ operator<=] 28513[indexterm1 operator<=] 28514``` 28515template< 28516 std::size_t N, 28517 std::size_t M, 28518 class CharT, 28519 class Traits> 28520bool 28521``[link beast.ref.boost__beast__operator_lt__eq_.overload1 operator<=]``( 28522 static_string< N, CharT, Traits > const& lhs, 28523 static_string< M, CharT, Traits > const& rhs); 28524 ``[''''»''' [link beast.ref.boost__beast__operator_lt__eq_.overload1 more...]]`` 28525 28526template< 28527 std::size_t N, 28528 class CharT, 28529 class Traits> 28530bool 28531``[link beast.ref.boost__beast__operator_lt__eq_.overload2 operator<=]``( 28532 CharT const* lhs, 28533 static_string< N, CharT, Traits > const& rhs); 28534 ``[''''»''' [link beast.ref.boost__beast__operator_lt__eq_.overload2 more...]]`` 28535 28536template< 28537 std::size_t N, 28538 class CharT, 28539 class Traits> 28540bool 28541``[link beast.ref.boost__beast__operator_lt__eq_.overload3 operator<=]``( 28542 static_string< N, CharT, Traits > const& lhs, 28543 CharT const* rhs); 28544 ``[''''»''' [link beast.ref.boost__beast__operator_lt__eq_.overload3 more...]]`` 28545``` 28546[section:overload1 operator<= (1 of 3 overloads)] 28547 28548[heading Synopsis] 28549 28550Defined in header [include_file boost/beast/core/static_string.hpp] 28551 28552 28553 28554``` 28555template< 28556 std::size_t N, 28557 std::size_t M, 28558 class CharT, 28559 class Traits> 28560bool 28561operator<=( 28562 static_string< N, CharT, Traits > const& lhs, 28563 static_string< M, CharT, Traits > const& rhs); 28564 28565``` 28566 28567[heading Description] 28568 28569 28570 28571Convenience header [include_file boost/beast/core.hpp] 28572 28573[endsect] 28574[section:overload2 operator<= (2 of 3 overloads)] 28575 28576[heading Synopsis] 28577 28578Defined in header [include_file boost/beast/core/static_string.hpp] 28579 28580 28581 28582``` 28583template< 28584 std::size_t N, 28585 class CharT, 28586 class Traits> 28587bool 28588operator<=( 28589 CharT const* lhs, 28590 static_string< N, CharT, Traits > const& rhs); 28591 28592``` 28593 28594[heading Description] 28595 28596 28597 28598Convenience header [include_file boost/beast/core.hpp] 28599 28600[endsect] 28601[section:overload3 operator<= (3 of 3 overloads)] 28602 28603[heading Synopsis] 28604 28605Defined in header [include_file boost/beast/core/static_string.hpp] 28606 28607 28608 28609``` 28610template< 28611 std::size_t N, 28612 class CharT, 28613 class Traits> 28614bool 28615operator<=( 28616 static_string< N, CharT, Traits > const& lhs, 28617 CharT const* rhs); 28618 28619``` 28620 28621[heading Description] 28622 28623 28624 28625Convenience header [include_file boost/beast/core.hpp] 28626 28627[endsect] 28628[endsect] 28629 28630 28631 28632[section:boost__beast__operator_eq__eq_ operator==] 28633[indexterm1 operator==] 28634``` 28635template< 28636 std::size_t N, 28637 std::size_t M, 28638 class CharT, 28639 class Traits> 28640bool 28641``[link beast.ref.boost__beast__operator_eq__eq_.overload1 operator==]``( 28642 static_string< N, CharT, Traits > const& lhs, 28643 static_string< M, CharT, Traits > const& rhs); 28644 ``[''''»''' [link beast.ref.boost__beast__operator_eq__eq_.overload1 more...]]`` 28645 28646template< 28647 std::size_t N, 28648 class CharT, 28649 class Traits> 28650bool 28651``[link beast.ref.boost__beast__operator_eq__eq_.overload2 operator==]``( 28652 CharT const* lhs, 28653 static_string< N, CharT, Traits > const& rhs); 28654 ``[''''»''' [link beast.ref.boost__beast__operator_eq__eq_.overload2 more...]]`` 28655 28656template< 28657 std::size_t N, 28658 class CharT, 28659 class Traits> 28660bool 28661``[link beast.ref.boost__beast__operator_eq__eq_.overload3 operator==]``( 28662 static_string< N, CharT, Traits > const& lhs, 28663 CharT const* rhs); 28664 ``[''''»''' [link beast.ref.boost__beast__operator_eq__eq_.overload3 more...]]`` 28665``` 28666[section:overload1 operator== (1 of 3 overloads)] 28667 28668[heading Synopsis] 28669 28670Defined in header [include_file boost/beast/core/static_string.hpp] 28671 28672 28673 28674``` 28675template< 28676 std::size_t N, 28677 std::size_t M, 28678 class CharT, 28679 class Traits> 28680bool 28681operator==( 28682 static_string< N, CharT, Traits > const& lhs, 28683 static_string< M, CharT, Traits > const& rhs); 28684 28685``` 28686 28687[heading Description] 28688 28689 28690 28691Convenience header [include_file boost/beast/core.hpp] 28692 28693[endsect] 28694[section:overload2 operator== (2 of 3 overloads)] 28695 28696[heading Synopsis] 28697 28698Defined in header [include_file boost/beast/core/static_string.hpp] 28699 28700 28701 28702``` 28703template< 28704 std::size_t N, 28705 class CharT, 28706 class Traits> 28707bool 28708operator==( 28709 CharT const* lhs, 28710 static_string< N, CharT, Traits > const& rhs); 28711 28712``` 28713 28714[heading Description] 28715 28716 28717 28718Convenience header [include_file boost/beast/core.hpp] 28719 28720[endsect] 28721[section:overload3 operator== (3 of 3 overloads)] 28722 28723[heading Synopsis] 28724 28725Defined in header [include_file boost/beast/core/static_string.hpp] 28726 28727 28728 28729``` 28730template< 28731 std::size_t N, 28732 class CharT, 28733 class Traits> 28734bool 28735operator==( 28736 static_string< N, CharT, Traits > const& lhs, 28737 CharT const* rhs); 28738 28739``` 28740 28741[heading Description] 28742 28743 28744 28745Convenience header [include_file boost/beast/core.hpp] 28746 28747[endsect] 28748[endsect] 28749 28750 28751 28752[section:boost__beast__operator_gt_ operator>] 28753[indexterm1 operator>] 28754``` 28755template< 28756 std::size_t N, 28757 std::size_t M, 28758 class CharT, 28759 class Traits> 28760bool 28761``[link beast.ref.boost__beast__operator_gt_.overload1 operator>]``( 28762 static_string< N, CharT, Traits > const& lhs, 28763 static_string< M, CharT, Traits > const& rhs); 28764 ``[''''»''' [link beast.ref.boost__beast__operator_gt_.overload1 more...]]`` 28765 28766template< 28767 std::size_t N, 28768 class CharT, 28769 class Traits> 28770bool 28771``[link beast.ref.boost__beast__operator_gt_.overload2 operator>]``( 28772 CharT const* lhs, 28773 static_string< N, CharT, Traits > const& rhs); 28774 ``[''''»''' [link beast.ref.boost__beast__operator_gt_.overload2 more...]]`` 28775 28776template< 28777 std::size_t N, 28778 class CharT, 28779 class Traits> 28780bool 28781``[link beast.ref.boost__beast__operator_gt_.overload3 operator>]``( 28782 static_string< N, CharT, Traits > const& lhs, 28783 CharT const* rhs); 28784 ``[''''»''' [link beast.ref.boost__beast__operator_gt_.overload3 more...]]`` 28785``` 28786[section:overload1 operator> (1 of 3 overloads)] 28787 28788[heading Synopsis] 28789 28790Defined in header [include_file boost/beast/core/static_string.hpp] 28791 28792 28793 28794``` 28795template< 28796 std::size_t N, 28797 std::size_t M, 28798 class CharT, 28799 class Traits> 28800bool 28801operator>( 28802 static_string< N, CharT, Traits > const& lhs, 28803 static_string< M, CharT, Traits > const& rhs); 28804 28805``` 28806 28807[heading Description] 28808 28809 28810 28811Convenience header [include_file boost/beast/core.hpp] 28812 28813[endsect] 28814[section:overload2 operator> (2 of 3 overloads)] 28815 28816[heading Synopsis] 28817 28818Defined in header [include_file boost/beast/core/static_string.hpp] 28819 28820 28821 28822``` 28823template< 28824 std::size_t N, 28825 class CharT, 28826 class Traits> 28827bool 28828operator>( 28829 CharT const* lhs, 28830 static_string< N, CharT, Traits > const& rhs); 28831 28832``` 28833 28834[heading Description] 28835 28836 28837 28838Convenience header [include_file boost/beast/core.hpp] 28839 28840[endsect] 28841[section:overload3 operator> (3 of 3 overloads)] 28842 28843[heading Synopsis] 28844 28845Defined in header [include_file boost/beast/core/static_string.hpp] 28846 28847 28848 28849``` 28850template< 28851 std::size_t N, 28852 class CharT, 28853 class Traits> 28854bool 28855operator>( 28856 static_string< N, CharT, Traits > const& lhs, 28857 CharT const* rhs); 28858 28859``` 28860 28861[heading Description] 28862 28863 28864 28865Convenience header [include_file boost/beast/core.hpp] 28866 28867[endsect] 28868[endsect] 28869 28870 28871 28872[section:boost__beast__operator_gt__eq_ operator>=] 28873[indexterm1 operator>=] 28874``` 28875template< 28876 std::size_t N, 28877 std::size_t M, 28878 class CharT, 28879 class Traits> 28880bool 28881``[link beast.ref.boost__beast__operator_gt__eq_.overload1 operator>=]``( 28882 static_string< N, CharT, Traits > const& lhs, 28883 static_string< M, CharT, Traits > const& rhs); 28884 ``[''''»''' [link beast.ref.boost__beast__operator_gt__eq_.overload1 more...]]`` 28885 28886template< 28887 std::size_t N, 28888 class CharT, 28889 class Traits> 28890bool 28891``[link beast.ref.boost__beast__operator_gt__eq_.overload2 operator>=]``( 28892 CharT const* lhs, 28893 static_string< N, CharT, Traits > const& rhs); 28894 ``[''''»''' [link beast.ref.boost__beast__operator_gt__eq_.overload2 more...]]`` 28895 28896template< 28897 std::size_t N, 28898 class CharT, 28899 class Traits> 28900bool 28901``[link beast.ref.boost__beast__operator_gt__eq_.overload3 operator>=]``( 28902 static_string< N, CharT, Traits > const& lhs, 28903 CharT const* rhs); 28904 ``[''''»''' [link beast.ref.boost__beast__operator_gt__eq_.overload3 more...]]`` 28905``` 28906[section:overload1 operator>= (1 of 3 overloads)] 28907 28908[heading Synopsis] 28909 28910Defined in header [include_file boost/beast/core/static_string.hpp] 28911 28912 28913 28914``` 28915template< 28916 std::size_t N, 28917 std::size_t M, 28918 class CharT, 28919 class Traits> 28920bool 28921operator>=( 28922 static_string< N, CharT, Traits > const& lhs, 28923 static_string< M, CharT, Traits > const& rhs); 28924 28925``` 28926 28927[heading Description] 28928 28929 28930 28931Convenience header [include_file boost/beast/core.hpp] 28932 28933[endsect] 28934[section:overload2 operator>= (2 of 3 overloads)] 28935 28936[heading Synopsis] 28937 28938Defined in header [include_file boost/beast/core/static_string.hpp] 28939 28940 28941 28942``` 28943template< 28944 std::size_t N, 28945 class CharT, 28946 class Traits> 28947bool 28948operator>=( 28949 CharT const* lhs, 28950 static_string< N, CharT, Traits > const& rhs); 28951 28952``` 28953 28954[heading Description] 28955 28956 28957 28958Convenience header [include_file boost/beast/core.hpp] 28959 28960[endsect] 28961[section:overload3 operator>= (3 of 3 overloads)] 28962 28963[heading Synopsis] 28964 28965Defined in header [include_file boost/beast/core/static_string.hpp] 28966 28967 28968 28969``` 28970template< 28971 std::size_t N, 28972 class CharT, 28973 class Traits> 28974bool 28975operator>=( 28976 static_string< N, CharT, Traits > const& lhs, 28977 CharT const* rhs); 28978 28979``` 28980 28981[heading Description] 28982 28983 28984 28985Convenience header [include_file boost/beast/core.hpp] 28986 28987[endsect] 28988[endsect] 28989 28990 28991 28992[section:boost__beast__ostream ostream] 28993[indexterm1 ostream] 28994Return an output stream that formats values into a ['DynamicBuffer]. 28995[heading Synopsis] 28996 28997Defined in header [include_file boost/beast/core/ostream.hpp] 28998 28999 29000 29001``` 29002template< 29003 class __DynamicBuffer__> 29004``['implementation-defined]`` 29005ostream( 29006 DynamicBuffer& buffer); 29007 29008``` 29009 29010[heading Description] 29011This function wraps the caller provided ['DynamicBuffer] into a `std::ostream` derived class, to allow `operator<<` stream style formatting operations. 29012[heading Example] 29013 29014``` 29015 ostream(buffer) << "Hello, world!" << std::endl; 29016``` 29017[heading Remarks] 29018Calling members of the underlying buffer before the output stream is destroyed results in undefined behavior. 29019[heading Parameters] 29020[table [[Name][Description]] 29021 [[`buffer`][ 29022 29023An object meeting the requirements of ['DynamicBuffer] into which the formatted output will be placed. 29024 ]] 29025] 29026[heading Return Value] 29027An object derived from `std::ostream` which redirects output The wrapped dynamic buffer is not modified, a copy is made instead. Ownership of the underlying memory is not transferred, the application is still responsible for managing its lifetime. The caller is responsible for ensuring the dynamic buffer is not destroyed for the lifetime of the output stream. 29028 29029 29030 29031Convenience header [include_file boost/beast/core.hpp] 29032 29033[endsect] 29034[section:boost__beast__rate_policy_access rate_policy_access] 29035Helper class to assist implementing a ['RatePolicy]. 29036[heading Synopsis] 29037 29038Defined in header [include_file boost/beast/core/rate_policy.hpp] 29039 29040 29041 29042``` 29043class rate_policy_access 29044``` 29045 29046[heading Description] 29047This class is used by the implementation to gain access to the private members of a user-defined object meeting the requirements of ['RatePolicy]. To use it, simply declare it as a friend in your class: 29048[heading Example] 29049 29050``` 29051 class custom_rate_policy 29052 { 29053 friend class beast::rate_policy_access; 29054 ... 29055``` 29056[heading Concepts] 29057 29058 29059* ['RatePolicy] 29060 29061[heading See Also] 29062[link beast.ref.boost__beast__basic_stream `basic_stream`] 29063 29064 29065 29066Convenience header [include_file boost/beast/core.hpp] 29067 29068[endsect] 29069 29070 29071 29072[section:boost__beast__read_size read_size] 29073[indexterm1 read_size] 29074Returns a natural read size. 29075[heading Synopsis] 29076 29077Defined in header [include_file boost/beast/core/read_size.hpp] 29078 29079 29080 29081``` 29082template< 29083 class __DynamicBuffer__> 29084std::size_t 29085read_size( 29086 DynamicBuffer& buffer, 29087 std::size_t max_size); 29088 29089``` 29090 29091[heading Description] 29092This function inspects the capacity, size, and maximum size of the dynamic buffer. Then it computes a natural read size given the passed-in upper limit. It favors a read size that does not require a reallocation, subject to a reasonable minimum to avoid tiny reads. 29093[heading Parameters] 29094[table [[Name][Description]] 29095 [[`buffer`][ 29096 29097The dynamic buffer to inspect. 29098 ]] 29099 [[`max_size`][ 29100 29101An upper limit on the returned value. 29102 ]] 29103] 29104[heading Remarks] 29105If the buffer is already at its maximum size, zero is returned. 29106 29107 29108 29109Convenience header [include_file boost/beast/core.hpp] 29110 29111[endsect] 29112[section:boost__beast__read_size_or_throw read_size_or_throw] 29113[indexterm1 read_size_or_throw] 29114Returns a natural read size or throw if the buffer is full. 29115[heading Synopsis] 29116 29117Defined in header [include_file boost/beast/core/read_size.hpp] 29118 29119 29120 29121``` 29122template< 29123 class __DynamicBuffer__> 29124std::size_t 29125read_size_or_throw( 29126 DynamicBuffer& buffer, 29127 std::size_t max_size); 29128 29129``` 29130 29131[heading Description] 29132This function inspects the capacity, size, and maximum size of the dynamic buffer. Then it computes a natural read size given the passed-in upper limit. It favors a read size that does not require a reallocation, subject to a reasonable minimum to avoid tiny reads. 29133[heading Parameters] 29134[table [[Name][Description]] 29135 [[`buffer`][ 29136 29137The dynamic buffer to inspect. 29138 ]] 29139 [[`max_size`][ 29140 29141An upper limit on the returned value. 29142 ]] 29143] 29144[heading Exceptions] 29145[table [[Type][Thrown On]] 29146 [[`std::length_error`][ 29147 29148if `max_size > 0` and the buffer is full. 29149 ]] 29150] 29151 29152 29153 29154Convenience header [include_file boost/beast/core.hpp] 29155 29156[endsect] 29157[section:boost__beast__role_type role_type] 29158[indexterm1 role_type] 29159The role of local or remote peer. 29160[heading Synopsis] 29161 29162Defined in header [include_file boost/beast/core/role.hpp] 29163 29164 29165``` 29166enum role_type 29167``` 29168 29169[indexterm2 client..role_type] 29170[indexterm2 server..role_type] 29171[heading Values] 29172[table [[Name][Description]] 29173 [[[^client]][The stream is operating as a client. 29174 29175]] 29176 [[[^server]][The stream is operating as a server. 29177 29178]] 29179] 29180 29181[heading Description] 29182Whether the endpoint is a client or server affects the behavior of teardown. The teardown behavior also depends on the type of the stream being torn down. 29183The default implementation of teardown for regular TCP/IP sockets is as follows: 29184 29185* In the client role, a TCP/IP shutdown is sent after reading all remaining data on the connection. 29186 29187 29188* In the server role, a TCP/IP shutdown is sent before reading all remaining data on the connection. 29189 29190When the next layer type is a `net::ssl::stream`, the connection is closed by performing the SSL closing handshake corresponding to the role type, client or server. 29191 29192 29193Convenience header [include_file boost/beast/core.hpp] 29194 29195[endsect] 29196[section:boost__beast__saved_handler saved_handler] 29197An invocable, nullary function object which holds a completion handler. 29198[heading Synopsis] 29199 29200Defined in header [include_file boost/beast/core/saved_handler.hpp] 29201 29202 29203 29204``` 29205class saved_handler 29206``` 29207[heading Member Functions] 29208[table [[Name][Description]] 29209 [ 29210 [[link beast.ref.boost__beast__saved_handler.emplace [*emplace]]] 29211 [ 29212 Store a completion handler in the container. 29213 ] 29214 ] 29215 [ 29216 [[link beast.ref.boost__beast__saved_handler.has_value [*has_value]]] 29217 [ 29218 Returns true if *this contains a completion handler. 29219 ] 29220 ] 29221 [ 29222 [[link beast.ref.boost__beast__saved_handler.invoke [*invoke]]] 29223 [ 29224 Unconditionally invoke the stored completion handler. 29225 ] 29226 ] 29227 [ 29228 [[link beast.ref.boost__beast__saved_handler.maybe_invoke [*maybe_invoke]]] 29229 [ 29230 Conditionally invoke the stored completion handler. 29231 ] 29232 ] 29233 [ 29234 [[link beast.ref.boost__beast__saved_handler.operator_eq_ [*operator=]]] 29235 [ 29236 Copy Assignment (deleted) 29237 29238 Move Assignment. 29239 ] 29240 ] 29241 [ 29242 [[link beast.ref.boost__beast__saved_handler.reset [*reset]]] 29243 [ 29244 Discard the saved handler, if one exists. 29245 ] 29246 ] 29247 [ 29248 [[link beast.ref.boost__beast__saved_handler.saved_handler [*saved_handler]]] 29249 [ 29250 Default Constructor. 29251 29252 Copy Constructor (deleted) 29253 29254 Move Constructor. 29255 ] 29256 ] 29257 [ 29258 [[link beast.ref.boost__beast__saved_handler.saved_handler_dtor_ [*~saved_handler]]] 29259 [ 29260 Destructor. 29261 ] 29262 ] 29263] 29264 29265[heading Description] 29266This container can hold a type-erased instance of any completion handler, or it can be empty. When the container holds a value, the implementation maintains an instance of `net::executor_work_guard` for the handler's associated executor. Memory is dynamically allocated to store the completion handler, and the allocator may optionally be specified. Otherwise, the implementation uses the handler's associated allocator. [section:emplace saved_handler::emplace] 29267[indexterm2 emplace..saved_handler] 29268Store a completion handler in the container. ``` 29269template< 29270 class __Handler__, 29271 class __Allocator__> 29272void 29273``[link beast.ref.boost__beast__saved_handler.emplace.overload1 emplace]``( 29274 Handler&& handler, 29275 Allocator const& alloc); 29276 ``[''''»''' [link beast.ref.boost__beast__saved_handler.emplace.overload1 more...]]`` 29277 29278template< 29279 class __Handler__> 29280void 29281``[link beast.ref.boost__beast__saved_handler.emplace.overload2 emplace]``( 29282 Handler&& handler); 29283 ``[''''»''' [link beast.ref.boost__beast__saved_handler.emplace.overload2 more...]]`` 29284``` 29285[section:overload1 saved_handler::emplace (1 of 2 overloads)] 29286Store a completion handler in the container. 29287[heading Synopsis] 29288``` 29289template< 29290 class __Handler__, 29291 class __Allocator__> 29292void 29293emplace( 29294 Handler&& handler, 29295 Allocator const& alloc); 29296``` 29297 29298[heading Description] 29299Requires `this->has_value() == false`. 29300[heading Parameters] 29301[table [[Name][Description]] 29302 [[`handler`][ 29303 29304The completion handler to store. The implementation takes ownership of the handler by performing a decay-copy. 29305 ]] 29306 [[`alloc`][ 29307 29308The allocator to use. 29309 ]] 29310] 29311[endsect] 29312[section:overload2 saved_handler::emplace (2 of 2 overloads)] 29313Store a completion handler in the container. 29314[heading Synopsis] 29315``` 29316template< 29317 class __Handler__> 29318void 29319emplace( 29320 Handler&& handler); 29321``` 29322 29323[heading Description] 29324Requires `this->has_value() == false`. The implementation will use the handler's associated allocator to obtian storage. 29325[heading Parameters] 29326[table [[Name][Description]] 29327 [[`handler`][ 29328 29329The completion handler to store. The implementation takes ownership of the handler by performing a decay-copy. 29330 ]] 29331] 29332[endsect] 29333[endsect] 29334 29335[section:has_value saved_handler::has_value] 29336[indexterm2 has_value..saved_handler] 29337Returns `true` if `*this` contains a completion handler. 29338[heading Synopsis] 29339``` 29340bool 29341has_value() const; 29342``` 29343 29344[heading Description] 29345[endsect] 29346[section:invoke saved_handler::invoke] 29347[indexterm2 invoke..saved_handler] 29348Unconditionally invoke the stored completion handler. 29349[heading Synopsis] 29350``` 29351void 29352invoke(); 29353``` 29354 29355[heading Description] 29356Requires `this->has_value() == true`. Any dynamic memory used is deallocated before the stored completion handler is invoked. The executor work guard is also reset before the invocation. [endsect] 29357[section:maybe_invoke saved_handler::maybe_invoke] 29358[indexterm2 maybe_invoke..saved_handler] 29359Conditionally invoke the stored completion handler. 29360[heading Synopsis] 29361``` 29362bool 29363maybe_invoke(); 29364``` 29365 29366[heading Description] 29367Invokes the stored completion handler if `this->has_value() == true`, otherwise does nothing. Any dynamic memory used is deallocated before the stored completion handler is invoked. The executor work guard is also reset before the invocation. 29368[heading Return Value] 29369`true` if the invocation took place. 29370[endsect] 29371[section:operator_eq_ saved_handler::operator=] 29372[indexterm2 operator=..saved_handler] 29373Copy Assignment (deleted) ``` 29374saved_handler& 29375``[link beast.ref.boost__beast__saved_handler.operator_eq_.overload1 operator=]``( 29376 saved_handler const&); 29377 ``[''''»''' [link beast.ref.boost__beast__saved_handler.operator_eq_.overload1 more...]]`` 29378 29379``` 29380Move Assignment. ``` 29381saved_handler& 29382``[link beast.ref.boost__beast__saved_handler.operator_eq_.overload2 operator=]``( 29383 saved_handler&& other); 29384 ``[''''»''' [link beast.ref.boost__beast__saved_handler.operator_eq_.overload2 more...]]`` 29385``` 29386[section:overload1 saved_handler::operator= (1 of 2 overloads)] 29387Copy Assignment (deleted) 29388[heading Synopsis] 29389``` 29390saved_handler& 29391operator=( 29392 saved_handler const&); 29393``` 29394 29395[heading Description] 29396[endsect] 29397[section:overload2 saved_handler::operator= (2 of 2 overloads)] 29398Move Assignment. 29399[heading Synopsis] 29400``` 29401saved_handler& 29402operator=( 29403 saved_handler&& other); 29404``` 29405 29406[heading Description] 29407[endsect] 29408[endsect] 29409 29410[section:reset saved_handler::reset] 29411[indexterm2 reset..saved_handler] 29412Discard the saved handler, if one exists. 29413[heading Synopsis] 29414``` 29415bool 29416reset(); 29417``` 29418 29419[heading Description] 29420If `*this` contains an object, it is destroyed. 29421[heading Return Value] 29422`true` if an object was destroyed. 29423[endsect] 29424[section:saved_handler saved_handler::saved_handler] 29425[indexterm2 saved_handler..saved_handler] 29426Default Constructor. ``` 29427``[link beast.ref.boost__beast__saved_handler.saved_handler.overload1 saved_handler]``(); 29428 ``[''''»''' [link beast.ref.boost__beast__saved_handler.saved_handler.overload1 more...]]`` 29429 29430``` 29431Copy Constructor (deleted) ``` 29432``[link beast.ref.boost__beast__saved_handler.saved_handler.overload2 saved_handler]``( 29433 saved_handler const&); 29434 ``[''''»''' [link beast.ref.boost__beast__saved_handler.saved_handler.overload2 more...]]`` 29435 29436``` 29437Move Constructor. ``` 29438``[link beast.ref.boost__beast__saved_handler.saved_handler.overload3 saved_handler]``( 29439 saved_handler&& other); 29440 ``[''''»''' [link beast.ref.boost__beast__saved_handler.saved_handler.overload3 more...]]`` 29441``` 29442[section:overload1 saved_handler::saved_handler (1 of 3 overloads)] 29443Default Constructor. 29444[heading Synopsis] 29445``` 29446saved_handler(); 29447``` 29448 29449[heading Description] 29450[endsect] 29451[section:overload2 saved_handler::saved_handler (2 of 3 overloads)] 29452Copy Constructor (deleted) 29453[heading Synopsis] 29454``` 29455saved_handler( 29456 saved_handler const&); 29457``` 29458 29459[heading Description] 29460[endsect] 29461[section:overload3 saved_handler::saved_handler (3 of 3 overloads)] 29462Move Constructor. 29463[heading Synopsis] 29464``` 29465saved_handler( 29466 saved_handler&& other); 29467``` 29468 29469[heading Description] 29470[endsect] 29471[endsect] 29472 29473[section:saved_handler_dtor_ saved_handler::~saved_handler] 29474[indexterm2 ~saved_handler..saved_handler] 29475Destructor. 29476[heading Synopsis] 29477``` 29478~saved_handler(); 29479``` 29480 29481[heading Description] 29482[endsect] 29483 29484 29485 29486Convenience header [include_file boost/beast/core.hpp] 29487 29488[endsect] 29489 29490 29491 29492[section:boost__beast__saved_handler__impl saved_handler::impl] 29493 29494[heading Synopsis] 29495 29496Defined in header [include_file boost/beast/core/saved_handler.hpp] 29497 29498 29499 29500``` 29501template< 29502 [role red error.class-detail-template.1][role red error.class-detail-template.2], 29503 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 29504class impl 29505``` 29506 29507[heading Description] 29508 29509 29510 29511Convenience header [include_file boost/beast/core.hpp] 29512 29513[endsect] 29514 29515 29516 29517[section:boost__beast__simple_rate_policy simple_rate_policy] 29518A rate policy with simple, configurable limits on reads and writes. 29519[heading Synopsis] 29520 29521Defined in header [include_file boost/beast/core/rate_policy.hpp] 29522 29523 29524 29525``` 29526class simple_rate_policy 29527``` 29528[heading Member Functions] 29529[table [[Name][Description]] 29530 [ 29531 [[link beast.ref.boost__beast__simple_rate_policy.read_limit [*read_limit]]] 29532 [ 29533 Set the limit of bytes per second to read. 29534 ] 29535 ] 29536 [ 29537 [[link beast.ref.boost__beast__simple_rate_policy.write_limit [*write_limit]]] 29538 [ 29539 Set the limit of bytes per second to write. 29540 ] 29541 ] 29542] 29543 29544[heading Description] 29545This rate policy allows for simple individual limits on the amount of bytes per second allowed for reads and writes. 29546[heading Concepts] 29547 29548 29549* ['RatePolicy] 29550 29551[heading See Also] 29552[link beast.ref.boost__beast__basic_stream `basic_stream`] 29553[section:read_limit simple_rate_policy::read_limit] 29554[indexterm2 read_limit..simple_rate_policy] 29555Set the limit of bytes per second to read. 29556[heading Synopsis] 29557``` 29558void 29559read_limit( 29560 std::size_t bytes_per_second); 29561``` 29562 29563[heading Description] 29564[endsect] 29565[section:write_limit simple_rate_policy::write_limit] 29566[indexterm2 write_limit..simple_rate_policy] 29567Set the limit of bytes per second to write. 29568[heading Synopsis] 29569``` 29570void 29571write_limit( 29572 std::size_t bytes_per_second); 29573``` 29574 29575[heading Description] 29576[endsect] 29577 29578 29579 29580Convenience header [include_file boost/beast/core.hpp] 29581 29582[endsect] 29583 29584 29585 29586[section:boost__beast__span span] 29587A range of bytes expressed as a ContiguousContainer. 29588[heading Synopsis] 29589 29590Defined in header [include_file boost/beast/core/span.hpp] 29591 29592 29593 29594``` 29595template< 29596 class T> 29597class span 29598``` 29599[heading Types] 29600[table [[Name][Description]] 29601 [ 29602 [[link beast.ref.boost__beast__span.const_iterator [*const_iterator]]] 29603 [ 29604 The const iterator used by the container. 29605 ] 29606 ] 29607 [ 29608 [[link beast.ref.boost__beast__span.const_pointer [*const_pointer]]] 29609 [ 29610 The const pointer used by the container. 29611 ] 29612 ] 29613 [ 29614 [[link beast.ref.boost__beast__span.const_reference [*const_reference]]] 29615 [ 29616 The const reference used by the container. 29617 ] 29618 ] 29619 [ 29620 [[link beast.ref.boost__beast__span.element_type [*element_type]]] 29621 [ 29622 The type of value, including cv qualifiers. 29623 ] 29624 ] 29625 [ 29626 [[link beast.ref.boost__beast__span.index_type [*index_type]]] 29627 [ 29628 The type of integer used to index the span. 29629 ] 29630 ] 29631 [ 29632 [[link beast.ref.boost__beast__span.iterator [*iterator]]] 29633 [ 29634 The iterator used by the container. 29635 ] 29636 ] 29637 [ 29638 [[link beast.ref.boost__beast__span.pointer [*pointer]]] 29639 [ 29640 A pointer to a span element. 29641 ] 29642 ] 29643 [ 29644 [[link beast.ref.boost__beast__span.reference [*reference]]] 29645 [ 29646 A reference to a span element. 29647 ] 29648 ] 29649 [ 29650 [[link beast.ref.boost__beast__span.value_type [*value_type]]] 29651 [ 29652 The type of value of each span element. 29653 ] 29654 ] 29655] 29656[heading Member Functions] 29657[table [[Name][Description]] 29658 [ 29659 [[link beast.ref.boost__beast__span.begin [*begin]]] 29660 [ 29661 Returns an iterator to the beginning of the span. 29662 ] 29663 ] 29664 [ 29665 [[link beast.ref.boost__beast__span.cbegin [*cbegin]]] 29666 [ 29667 Returns an iterator to the beginning of the span. 29668 ] 29669 ] 29670 [ 29671 [[link beast.ref.boost__beast__span.cend [*cend]]] 29672 [ 29673 Returns an iterator to one past the end of the span. 29674 ] 29675 ] 29676 [ 29677 [[link beast.ref.boost__beast__span.data [*data]]] 29678 [ 29679 Returns a pointer to the beginning of the span. 29680 ] 29681 ] 29682 [ 29683 [[link beast.ref.boost__beast__span.empty [*empty]]] 29684 [ 29685 Returns true if the span is empty. 29686 ] 29687 ] 29688 [ 29689 [[link beast.ref.boost__beast__span.end [*end]]] 29690 [ 29691 Returns an iterator to one past the end of the span. 29692 ] 29693 ] 29694 [ 29695 [[link beast.ref.boost__beast__span.operator_eq_ [*operator=]]] 29696 [ 29697 Assignment. 29698 ] 29699 ] 29700 [ 29701 [[link beast.ref.boost__beast__span.size [*size]]] 29702 [ 29703 Returns the number of elements in the span. 29704 ] 29705 ] 29706 [ 29707 [[link beast.ref.boost__beast__span.span [*span]]] 29708 [ 29709 Constructor. 29710 ] 29711 ] 29712] 29713 29714[heading Description] 29715This class implements a non-owning reference to a storage area of a certain size and having an underlying integral type with size of 1. 29716[heading Template Parameters] 29717[table [[Type][Description]] 29718 [[`T`][ 29719 29720The type pointed to by span iterators 29721 ]] 29722] 29723[section:begin span::begin] 29724[indexterm2 begin..span] 29725Returns an iterator to the beginning of the span. 29726[heading Synopsis] 29727``` 29728const_iterator 29729begin() const; 29730``` 29731 29732[heading Description] 29733[endsect] 29734[section:cbegin span::cbegin] 29735[indexterm2 cbegin..span] 29736Returns an iterator to the beginning of the span. 29737[heading Synopsis] 29738``` 29739const_iterator 29740cbegin() const; 29741``` 29742 29743[heading Description] 29744[endsect] 29745[section:cend span::cend] 29746[indexterm2 cend..span] 29747Returns an iterator to one past the end of the span. 29748[heading Synopsis] 29749``` 29750const_iterator 29751cend() const; 29752``` 29753 29754[heading Description] 29755[endsect] 29756[section:const_iterator span::const_iterator] 29757[indexterm2 const_iterator..span] 29758The const iterator used by the container. 29759[heading Synopsis] 29760 29761``` 29762using const_iterator = const_pointer; 29763``` 29764 29765[heading Description] 29766[endsect] 29767[section:const_pointer span::const_pointer] 29768[indexterm2 const_pointer..span] 29769The const pointer used by the container. 29770[heading Synopsis] 29771 29772``` 29773using const_pointer = T const *; 29774``` 29775 29776[heading Description] 29777[endsect] 29778[section:const_reference span::const_reference] 29779[indexterm2 const_reference..span] 29780The const reference used by the container. 29781[heading Synopsis] 29782 29783``` 29784using const_reference = T const &; 29785``` 29786 29787[heading Description] 29788[endsect] 29789[section:data span::data] 29790[indexterm2 data..span] 29791Returns a pointer to the beginning of the span. 29792[heading Synopsis] 29793``` 29794T* 29795data() const; 29796``` 29797 29798[heading Description] 29799[endsect] 29800[section:element_type span::element_type] 29801[indexterm2 element_type..span] 29802The type of value, including cv qualifiers. 29803[heading Synopsis] 29804 29805``` 29806using element_type = T; 29807``` 29808 29809[heading Description] 29810[endsect] 29811[section:empty span::empty] 29812[indexterm2 empty..span] 29813Returns `true` if the span is empty. 29814[heading Synopsis] 29815``` 29816bool 29817empty() const; 29818``` 29819 29820[heading Description] 29821[endsect] 29822[section:end span::end] 29823[indexterm2 end..span] 29824Returns an iterator to one past the end of the span. 29825[heading Synopsis] 29826``` 29827const_iterator 29828end() const; 29829``` 29830 29831[heading Description] 29832[endsect] 29833[section:index_type span::index_type] 29834[indexterm2 index_type..span] 29835The type of integer used to index the span. 29836[heading Synopsis] 29837 29838``` 29839using index_type = std::ptrdiff_t; 29840``` 29841 29842[heading Description] 29843[endsect] 29844[section:iterator span::iterator] 29845[indexterm2 iterator..span] 29846The iterator used by the container. 29847[heading Synopsis] 29848 29849``` 29850using iterator = pointer; 29851``` 29852 29853[heading Description] 29854[endsect] 29855[section:operator_eq_ span::operator=] 29856[indexterm2 operator=..span] 29857Assignment. ``` 29858span& 29859``[link beast.ref.boost__beast__span.operator_eq_.overload1 operator=]``( 29860 span const&); 29861 ``[''''»''' [link beast.ref.boost__beast__span.operator_eq_.overload1 more...]]`` 29862 29863template< 29864 class ContiguousContainer> 29865span& 29866``[link beast.ref.boost__beast__span.operator_eq_.overload2 operator=]``( 29867 ContiguousContainer&& container); 29868 ``[''''»''' [link beast.ref.boost__beast__span.operator_eq_.overload2 more...]]`` 29869``` 29870[section:overload1 span::operator= (1 of 2 overloads)] 29871Assignment. 29872[heading Synopsis] 29873``` 29874span& 29875operator=( 29876 span const&); 29877``` 29878 29879[heading Description] 29880[endsect] 29881[section:overload2 span::operator= (2 of 2 overloads)] 29882Assignment. 29883[heading Synopsis] 29884``` 29885template< 29886 class ContiguousContainer> 29887span& 29888operator=( 29889 ContiguousContainer&& container); 29890``` 29891 29892[heading Description] 29893[heading Parameters] 29894[table [[Name][Description]] 29895 [[`container`][ 29896 29897The container to assign from 29898 ]] 29899] 29900[endsect] 29901[endsect] 29902 29903[section:pointer span::pointer] 29904[indexterm2 pointer..span] 29905A pointer to a span element. 29906[heading Synopsis] 29907 29908``` 29909using pointer = T*; 29910``` 29911 29912[heading Description] 29913[endsect] 29914[section:reference span::reference] 29915[indexterm2 reference..span] 29916A reference to a span element. 29917[heading Synopsis] 29918 29919``` 29920using reference = T&; 29921``` 29922 29923[heading Description] 29924[endsect] 29925[section:size span::size] 29926[indexterm2 size..span] 29927Returns the number of elements in the span. 29928[heading Synopsis] 29929``` 29930std::size_t 29931size() const; 29932``` 29933 29934[heading Description] 29935[endsect] 29936[section:span span::span] 29937[indexterm2 span..span] 29938Constructor. ``` 29939``[link beast.ref.boost__beast__span.span.overload1 span]``(); 29940 ``[''''»''' [link beast.ref.boost__beast__span.span.overload1 more...]]`` 29941 29942``[link beast.ref.boost__beast__span.span.overload2 span]``( 29943 span const&); 29944 ``[''''»''' [link beast.ref.boost__beast__span.span.overload2 more...]]`` 29945 29946``[link beast.ref.boost__beast__span.span.overload3 span]``( 29947 T* data, 29948 std::size_t size); 29949 ``[''''»''' [link beast.ref.boost__beast__span.span.overload3 more...]]`` 29950 29951template< 29952 class ContiguousContainer> 29953explicit 29954``[link beast.ref.boost__beast__span.span.overload4 span]``( 29955 ContiguousContainer&& container); 29956 ``[''''»''' [link beast.ref.boost__beast__span.span.overload4 more...]]`` 29957``` 29958[section:overload1 span::span (1 of 4 overloads)] 29959Constructor. 29960[heading Synopsis] 29961``` 29962span(); 29963``` 29964 29965[heading Description] 29966[endsect] 29967[section:overload2 span::span (2 of 4 overloads)] 29968Constructor. 29969[heading Synopsis] 29970``` 29971span( 29972 span const&); 29973``` 29974 29975[heading Description] 29976[endsect] 29977[section:overload3 span::span (3 of 4 overloads)] 29978Constructor. 29979[heading Synopsis] 29980``` 29981span( 29982 T* data, 29983 std::size_t size); 29984``` 29985 29986[heading Description] 29987[heading Parameters] 29988[table [[Name][Description]] 29989 [[`data`][ 29990 29991A pointer to the beginning of the range of elements 29992 ]] 29993 [[`size`][ 29994 29995The number of elements pointed to by `data` 29996 ]] 29997] 29998[endsect] 29999[section:overload4 span::span (4 of 4 overloads)] 30000Constructor. 30001[heading Synopsis] 30002``` 30003template< 30004 class ContiguousContainer> 30005span( 30006 ContiguousContainer&& container); 30007``` 30008 30009[heading Description] 30010[heading Parameters] 30011[table [[Name][Description]] 30012 [[`container`][ 30013 30014The container to construct from 30015 ]] 30016] 30017[endsect] 30018[endsect] 30019 30020[section:value_type span::value_type] 30021[indexterm2 value_type..span] 30022The type of value of each span element. 30023[heading Synopsis] 30024 30025``` 30026using value_type = typename std::remove_const< T >::type; 30027``` 30028 30029[heading Description] 30030[endsect] 30031 30032 30033 30034Convenience header [include_file boost/beast/core.hpp] 30035 30036[endsect] 30037 30038 30039 30040[section:boost__beast__ssl_stream ssl_stream] 30041Provides stream-oriented functionality using OpenSSL. 30042[heading Synopsis] 30043 30044Defined in header [include_file boost/beast/ssl/ssl_stream.hpp] 30045 30046 30047 30048``` 30049template< 30050 class NextLayer> 30051class ssl_stream : 30052 public stream_base 30053``` 30054[heading Types] 30055[table [[Name][Description]] 30056 [ 30057 [[link beast.ref.boost__beast__ssl_stream.executor_type [*executor_type]]] 30058 [ 30059 The type of the executor associated with the object. 30060 ] 30061 ] 30062 [ 30063 [[link beast.ref.boost__beast__ssl_stream.impl_struct [*impl_struct]]] 30064 [ 30065 Structure for use with deprecated impl_type. 30066 ] 30067 ] 30068 [ 30069 [[link beast.ref.boost__beast__ssl_stream.native_handle_type [*native_handle_type]]] 30070 [ 30071 The native handle type of the SSL stream. 30072 ] 30073 ] 30074 [ 30075 [[link beast.ref.boost__beast__ssl_stream.next_layer_type [*next_layer_type]]] 30076 [ 30077 The type of the next layer. 30078 ] 30079 ] 30080] 30081[heading Member Functions] 30082[table [[Name][Description]] 30083 [ 30084 [[link beast.ref.boost__beast__ssl_stream.async_handshake [*async_handshake]]] 30085 [ 30086 Start an asynchronous SSL handshake. 30087 ] 30088 ] 30089 [ 30090 [[link beast.ref.boost__beast__ssl_stream.async_read_some [*async_read_some]]] 30091 [ 30092 Start an asynchronous read. 30093 ] 30094 ] 30095 [ 30096 [[link beast.ref.boost__beast__ssl_stream.async_shutdown [*async_shutdown]]] 30097 [ 30098 Asynchronously shut down SSL on the stream. 30099 ] 30100 ] 30101 [ 30102 [[link beast.ref.boost__beast__ssl_stream.async_write_some [*async_write_some]]] 30103 [ 30104 Start an asynchronous write. 30105 ] 30106 ] 30107 [ 30108 [[link beast.ref.boost__beast__ssl_stream.get_executor [*get_executor]]] 30109 [ 30110 Get the executor associated with the object. 30111 ] 30112 ] 30113 [ 30114 [[link beast.ref.boost__beast__ssl_stream.handshake [*handshake]]] 30115 [ 30116 Perform SSL handshaking. 30117 ] 30118 ] 30119 [ 30120 [[link beast.ref.boost__beast__ssl_stream.native_handle [*native_handle]]] 30121 [ 30122 Get the underlying implementation in the native type. 30123 ] 30124 ] 30125 [ 30126 [[link beast.ref.boost__beast__ssl_stream.next_layer [*next_layer]]] 30127 [ 30128 Get a reference to the next layer. 30129 ] 30130 ] 30131 [ 30132 [[link beast.ref.boost__beast__ssl_stream.read_some [*read_some]]] 30133 [ 30134 Read some data from the stream. 30135 ] 30136 ] 30137 [ 30138 [[link beast.ref.boost__beast__ssl_stream.set_verify_callback [*set_verify_callback]]] 30139 [ 30140 Set the callback used to verify peer certificates. 30141 ] 30142 ] 30143 [ 30144 [[link beast.ref.boost__beast__ssl_stream.set_verify_depth [*set_verify_depth]]] 30145 [ 30146 Set the peer verification depth. 30147 ] 30148 ] 30149 [ 30150 [[link beast.ref.boost__beast__ssl_stream.set_verify_mode [*set_verify_mode]]] 30151 [ 30152 Set the peer verification mode. 30153 ] 30154 ] 30155 [ 30156 [[link beast.ref.boost__beast__ssl_stream.shutdown [*shutdown]]] 30157 [ 30158 Shut down SSL on the stream. 30159 ] 30160 ] 30161 [ 30162 [[link beast.ref.boost__beast__ssl_stream.ssl_stream [*ssl_stream]]] 30163 [ 30164 Construct a stream. 30165 ] 30166 ] 30167 [ 30168 [[link beast.ref.boost__beast__ssl_stream.write_some [*write_some]]] 30169 [ 30170 Write some data to the stream. 30171 ] 30172 ] 30173] 30174 30175[heading Description] 30176The stream class template provides asynchronous and blocking stream-oriented functionality using SSL. 30177[heading Thread Safety] 30178['Distinct] ['objects:] Safe. 30179 30180['Shared] ['objects:] Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 30181[heading Example] 30182To use this template with a [link beast.ref.boost__beast__tcp_stream `tcp_stream`], you would write: 30183``` 30184 net::io_context ioc; 30185 net::ssl::context ctx{net::ssl::context::tlsv12}; 30186 beast::ssl_stream<beast::tcp_stream> sock{ioc, ctx}; 30187``` 30188In addition to providing an interface identical to `net::ssl::stream`, the wrapper has the following additional properties: 30189 30190* Satisfies [*MoveConstructible] 30191 30192 30193* Satisfies [*MoveAssignable] 30194 30195 30196* Constructible from a moved socket. 30197 30198 30199* Uses [link beast.ref.boost__beast__flat_stream `flat_stream`] internally, as a performance work-around for a limitation of `net::ssl::stream` when writing buffer sequences having length greater than one. 30200 30201 30202[section:async_handshake ssl_stream::async_handshake] 30203[indexterm2 async_handshake..ssl_stream] 30204Start an asynchronous SSL handshake. ``` 30205template< 30206 class HandshakeHandler> 30207``__deduced__`` 30208``[link beast.ref.boost__beast__ssl_stream.async_handshake.overload1 async_handshake]``( 30209 handshake_type type, 30210 BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler); 30211 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.async_handshake.overload1 more...]]`` 30212 30213template< 30214 class __ConstBufferSequence__, 30215 class BufferedHandshakeHandler> 30216``__deduced__`` 30217``[link beast.ref.boost__beast__ssl_stream.async_handshake.overload2 async_handshake]``( 30218 handshake_type type, 30219 ConstBufferSequence const& buffers, 30220 BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler); 30221 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.async_handshake.overload2 more...]]`` 30222``` 30223[section:overload1 ssl_stream::async_handshake (1 of 2 overloads)] 30224Start an asynchronous SSL handshake. 30225[heading Synopsis] 30226``` 30227template< 30228 class HandshakeHandler> 30229``__deduced__`` 30230async_handshake( 30231 handshake_type type, 30232 BOOST_ASIO_MOVE_ARG(HandshakeHandler) handler); 30233``` 30234 30235[heading Description] 30236This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately. 30237[heading Parameters] 30238[table [[Name][Description]] 30239 [[`type`][ 30240 30241The type of handshaking to be performed, i.e. as a client or as a server. 30242 ]] 30243 [[`handler`][ 30244 30245The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: 30246``` 30247 void handler( 30248 const boost::system::error_code& error // Result of operation. 30249 ); 30250``` 30251 30252 ]] 30253] 30254[endsect] 30255[section:overload2 ssl_stream::async_handshake (2 of 2 overloads)] 30256Start an asynchronous SSL handshake. 30257[heading Synopsis] 30258``` 30259template< 30260 class __ConstBufferSequence__, 30261 class BufferedHandshakeHandler> 30262``__deduced__`` 30263async_handshake( 30264 handshake_type type, 30265 ConstBufferSequence const& buffers, 30266 BOOST_ASIO_MOVE_ARG(BufferedHandshakeHandler) handler); 30267``` 30268 30269[heading Description] 30270This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately. 30271[heading Parameters] 30272[table [[Name][Description]] 30273 [[`type`][ 30274 30275The type of handshaking to be performed, i.e. as a client or as a server. 30276 ]] 30277 [[`buffers`][ 30278 30279The buffered data to be reused for the handshake. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 30280 ]] 30281 [[`handler`][ 30282 30283The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: 30284``` 30285 void handler( 30286 const boost::system::error_code& error, // Result of operation. 30287 std::size_t bytes_transferred // Amount of buffers used in handshake. 30288 ); 30289``` 30290 30291 ]] 30292] 30293[endsect] 30294[endsect] 30295 30296[section:async_read_some ssl_stream::async_read_some] 30297[indexterm2 async_read_some..ssl_stream] 30298Start an asynchronous read. 30299[heading Synopsis] 30300``` 30301template< 30302 class __MutableBufferSequence__, 30303 class __ReadHandler__> 30304``__deduced__`` 30305async_read_some( 30306 MutableBufferSequence const& buffers, 30307 BOOST_ASIO_MOVE_ARG(ReadHandler) handler); 30308``` 30309 30310[heading Description] 30311This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately. 30312[heading Parameters] 30313[table [[Name][Description]] 30314 [[`buffers`][ 30315 30316The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 30317 ]] 30318 [[`handler`][ 30319 30320The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: 30321``` 30322 void handler( 30323 const boost::system::error_code& error, // Result of operation. 30324 std::size_t bytes_transferred // Number of bytes read. 30325 ); 30326``` 30327 30328 ]] 30329] 30330[heading Remarks] 30331The `async_read_some` operation may not read all of the requested number of bytes. Consider using the `net::async_read` function if you need to ensure that the requested amount of data is read before the asynchronous operation completes. 30332[endsect] 30333[section:async_shutdown ssl_stream::async_shutdown] 30334[indexterm2 async_shutdown..ssl_stream] 30335Asynchronously shut down SSL on the stream. 30336[heading Synopsis] 30337``` 30338template< 30339 class ShutdownHandler> 30340``__deduced__`` 30341async_shutdown( 30342 BOOST_ASIO_MOVE_ARG(ShutdownHandler) handler); 30343``` 30344 30345[heading Description] 30346This function is used to asynchronously shut down SSL on the stream. This function call always returns immediately. 30347[heading Parameters] 30348[table [[Name][Description]] 30349 [[`handler`][ 30350 30351The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: 30352``` 30353 void handler( 30354 const boost::system::error_code& error // Result of operation. 30355 ); 30356``` 30357 30358 ]] 30359] 30360[endsect] 30361[section:async_write_some ssl_stream::async_write_some] 30362[indexterm2 async_write_some..ssl_stream] 30363Start an asynchronous write. 30364[heading Synopsis] 30365``` 30366template< 30367 class __ConstBufferSequence__, 30368 class __WriteHandler__> 30369``__deduced__`` 30370async_write_some( 30371 ConstBufferSequence const& buffers, 30372 BOOST_ASIO_MOVE_ARG(WriteHandler) handler); 30373``` 30374 30375[heading Description] 30376This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately. 30377[heading Parameters] 30378[table [[Name][Description]] 30379 [[`buffers`][ 30380 30381The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 30382 ]] 30383 [[`handler`][ 30384 30385The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be: 30386``` 30387 void handler( 30388 const boost::system::error_code& error, // Result of operation. 30389 std::size_t bytes_transferred // Number of bytes written. 30390 ); 30391``` 30392 30393 ]] 30394] 30395[heading Remarks] 30396The `async_write_some` operation may not transmit all of the data to the peer. Consider using the `net::async_write` function if you need to ensure that all data is written before the asynchronous operation completes. 30397[endsect] 30398[section:executor_type ssl_stream::executor_type] 30399[indexterm2 executor_type..ssl_stream] 30400The type of the executor associated with the object. 30401[heading Synopsis] 30402 30403``` 30404using executor_type = typename stream_type::executor_type; 30405``` 30406 30407[heading Description] 30408[endsect] 30409[section:get_executor ssl_stream::get_executor] 30410[indexterm2 get_executor..ssl_stream] 30411Get the executor associated with the object. 30412[heading Synopsis] 30413``` 30414executor_type 30415get_executor(); 30416``` 30417 30418[heading Description] 30419This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations. 30420[heading Return Value] 30421A copy of the executor that stream will use to dispatch handlers. 30422[endsect] 30423[section:handshake ssl_stream::handshake] 30424[indexterm2 handshake..ssl_stream] 30425Perform SSL handshaking. ``` 30426void 30427``[link beast.ref.boost__beast__ssl_stream.handshake.overload1 handshake]``( 30428 handshake_type type); 30429 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.handshake.overload1 more...]]`` 30430 30431void 30432``[link beast.ref.boost__beast__ssl_stream.handshake.overload2 handshake]``( 30433 handshake_type type, 30434 boost::system::error_code& ec); 30435 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.handshake.overload2 more...]]`` 30436 30437template< 30438 class __ConstBufferSequence__> 30439void 30440``[link beast.ref.boost__beast__ssl_stream.handshake.overload3 handshake]``( 30441 handshake_type type, 30442 ConstBufferSequence const& buffers); 30443 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.handshake.overload3 more...]]`` 30444 30445template< 30446 class __ConstBufferSequence__> 30447void 30448``[link beast.ref.boost__beast__ssl_stream.handshake.overload4 handshake]``( 30449 handshake_type type, 30450 ConstBufferSequence const& buffers, 30451 boost::system::error_code& ec); 30452 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.handshake.overload4 more...]]`` 30453``` 30454[section:overload1 ssl_stream::handshake (1 of 4 overloads)] 30455Perform SSL handshaking. 30456[heading Synopsis] 30457``` 30458void 30459handshake( 30460 handshake_type type); 30461``` 30462 30463[heading Description] 30464This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs. 30465[heading Parameters] 30466[table [[Name][Description]] 30467 [[`type`][ 30468 30469The type of handshaking to be performed, i.e. as a client or as a server. 30470 ]] 30471] 30472[heading Exceptions] 30473[table [[Type][Thrown On]] 30474 [[`boost::system::system_error`][ 30475 30476Thrown on failure. 30477 ]] 30478] 30479[endsect] 30480[section:overload2 ssl_stream::handshake (2 of 4 overloads)] 30481Perform SSL handshaking. 30482[heading Synopsis] 30483``` 30484void 30485handshake( 30486 handshake_type type, 30487 boost::system::error_code& ec); 30488``` 30489 30490[heading Description] 30491This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs. 30492[heading Parameters] 30493[table [[Name][Description]] 30494 [[`type`][ 30495 30496The type of handshaking to be performed, i.e. as a client or as a server. 30497 ]] 30498 [[`ec`][ 30499 30500Set to indicate what error occurred, if any. 30501 ]] 30502] 30503[endsect] 30504[section:overload3 ssl_stream::handshake (3 of 4 overloads)] 30505Perform SSL handshaking. 30506[heading Synopsis] 30507``` 30508template< 30509 class __ConstBufferSequence__> 30510void 30511handshake( 30512 handshake_type type, 30513 ConstBufferSequence const& buffers); 30514``` 30515 30516[heading Description] 30517This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs. 30518[heading Parameters] 30519[table [[Name][Description]] 30520 [[`type`][ 30521 30522The type of handshaking to be performed, i.e. as a client or as a server. 30523 ]] 30524 [[`buffers`][ 30525 30526The buffered data to be reused for the handshake. 30527 ]] 30528] 30529[heading Exceptions] 30530[table [[Type][Thrown On]] 30531 [[`boost::system::system_error`][ 30532 30533Thrown on failure. 30534 ]] 30535] 30536[endsect] 30537[section:overload4 ssl_stream::handshake (4 of 4 overloads)] 30538Perform SSL handshaking. 30539[heading Synopsis] 30540``` 30541template< 30542 class __ConstBufferSequence__> 30543void 30544handshake( 30545 handshake_type type, 30546 ConstBufferSequence const& buffers, 30547 boost::system::error_code& ec); 30548``` 30549 30550[heading Description] 30551This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs. 30552[heading Parameters] 30553[table [[Name][Description]] 30554 [[`type`][ 30555 30556The type of handshaking to be performed, i.e. as a client or as a server. 30557 ]] 30558 [[`buffers`][ 30559 30560The buffered data to be reused for the handshake. 30561 ]] 30562 [[`ec`][ 30563 30564Set to indicate what error occurred, if any. 30565 ]] 30566] 30567[endsect] 30568[endsect] 30569 30570[section:impl_struct ssl_stream::impl_struct] 30571[indexterm2 impl_struct..ssl_stream] 30572Structure for use with deprecated impl\_type. 30573[heading Synopsis] 30574 30575``` 30576using impl_struct = typename ssl_stream_type::impl_struct; 30577``` 30578 30579[heading Description] 30580[endsect] 30581[section:native_handle ssl_stream::native_handle] 30582[indexterm2 native_handle..ssl_stream] 30583Get the underlying implementation in the native type. 30584[heading Synopsis] 30585``` 30586native_handle_type 30587native_handle(); 30588``` 30589 30590[heading Description] 30591This function may be used to obtain the underlying implementation of the context. This is intended to allow access to context functionality that is not otherwise provided. 30592[heading Example] 30593The [link beast.ref.boost__beast__ssl_stream.native_handle `ssl_stream::native_handle()`] function returns a pointer of type `SSL*` that is suitable for passing to functions such as `SSL_get_verify_result` and `SSL_get_peer_certificate:` 30594``` 30595 boost::beast::ssl_stream<net::ip::tcp::socket> ss{ioc, ctx}; 30596 30597 // ... establish connection and perform handshake ... 30598 30599 if (X509* cert = SSL_get_peer_certificate(ss.native_handle())) 30600 { 30601 if (SSL_get_verify_result(ss.native_handle()) == X509_V_OK) 30602 { 30603 // ... 30604 } 30605 } 30606``` 30607[endsect] 30608[section:native_handle_type ssl_stream::native_handle_type] 30609[indexterm2 native_handle_type..ssl_stream] 30610The native handle type of the SSL stream. 30611[heading Synopsis] 30612 30613``` 30614using native_handle_type = typename ssl_stream_type::native_handle_type; 30615``` 30616 30617[heading Description] 30618[endsect] 30619[section:next_layer ssl_stream::next_layer] 30620[indexterm2 next_layer..ssl_stream] 30621Get a reference to the next layer. ``` 30622next_layer_type const & 30623``[link beast.ref.boost__beast__ssl_stream.next_layer.overload1 next_layer]``() const; 30624 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.next_layer.overload1 more...]]`` 30625 30626next_layer_type& 30627``[link beast.ref.boost__beast__ssl_stream.next_layer.overload2 next_layer]``(); 30628 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.next_layer.overload2 more...]]`` 30629``` 30630[section:overload1 ssl_stream::next_layer (1 of 2 overloads)] 30631Get a reference to the next layer. 30632[heading Synopsis] 30633``` 30634next_layer_type const & 30635next_layer() const; 30636``` 30637 30638[heading Description] 30639This function returns a reference to the next layer in a stack of stream layers. 30640[heading Remarks] 30641The next layer is the wrapped stream and not the [link beast.ref.boost__beast__flat_stream `flat_stream`] used in the implementation. 30642[heading Return Value] 30643A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller. 30644[endsect] 30645[section:overload2 ssl_stream::next_layer (2 of 2 overloads)] 30646Get a reference to the next layer. 30647[heading Synopsis] 30648``` 30649next_layer_type& 30650next_layer(); 30651``` 30652 30653[heading Description] 30654This function returns a reference to the next layer in a stack of stream layers. 30655[heading Remarks] 30656The next layer is the wrapped stream and not the [link beast.ref.boost__beast__flat_stream `flat_stream`] used in the implementation. 30657[heading Return Value] 30658A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller. 30659[endsect] 30660[endsect] 30661 30662[section:next_layer_type ssl_stream::next_layer_type] 30663[indexterm2 next_layer_type..ssl_stream] 30664The type of the next layer. 30665[heading Synopsis] 30666 30667``` 30668using next_layer_type = typename ssl_stream_type::next_layer_type; 30669``` 30670 30671[heading Description] 30672[endsect] 30673[section:read_some ssl_stream::read_some] 30674[indexterm2 read_some..ssl_stream] 30675Read some data from the stream. ``` 30676template< 30677 class __MutableBufferSequence__> 30678std::size_t 30679``[link beast.ref.boost__beast__ssl_stream.read_some.overload1 read_some]``( 30680 MutableBufferSequence const& buffers); 30681 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.read_some.overload1 more...]]`` 30682 30683template< 30684 class __MutableBufferSequence__> 30685std::size_t 30686``[link beast.ref.boost__beast__ssl_stream.read_some.overload2 read_some]``( 30687 MutableBufferSequence const& buffers, 30688 boost::system::error_code& ec); 30689 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.read_some.overload2 more...]]`` 30690``` 30691[section:overload1 ssl_stream::read_some (1 of 2 overloads)] 30692Read some data from the stream. 30693[heading Synopsis] 30694``` 30695template< 30696 class __MutableBufferSequence__> 30697std::size_t 30698read_some( 30699 MutableBufferSequence const& buffers); 30700``` 30701 30702[heading Description] 30703This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 30704[heading Parameters] 30705[table [[Name][Description]] 30706 [[`buffers`][ 30707 30708The buffers into which the data will be read. 30709 ]] 30710] 30711[heading Return Value] 30712The number of bytes read. 30713[heading Exceptions] 30714[table [[Type][Thrown On]] 30715 [[`boost::system::system_error`][ 30716 30717Thrown on failure. 30718 ]] 30719] 30720[heading Remarks] 30721The `read_some` operation may not read all of the requested number of bytes. Consider using the `net::read` function if you need to ensure that the requested amount of data is read before the blocking operation completes. 30722[endsect] 30723[section:overload2 ssl_stream::read_some (2 of 2 overloads)] 30724Read some data from the stream. 30725[heading Synopsis] 30726``` 30727template< 30728 class __MutableBufferSequence__> 30729std::size_t 30730read_some( 30731 MutableBufferSequence const& buffers, 30732 boost::system::error_code& ec); 30733``` 30734 30735[heading Description] 30736This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 30737[heading Parameters] 30738[table [[Name][Description]] 30739 [[`buffers`][ 30740 30741The buffers into which the data will be read. 30742 ]] 30743 [[`ec`][ 30744 30745Set to indicate what error occurred, if any. 30746 ]] 30747] 30748[heading Return Value] 30749The number of bytes read. Returns 0 if an error occurred. 30750[heading Remarks] 30751The `read_some` operation may not read all of the requested number of bytes. Consider using the `net::read` function if you need to ensure that the requested amount of data is read before the blocking operation completes. 30752[endsect] 30753[endsect] 30754 30755[section:set_verify_callback ssl_stream::set_verify_callback] 30756[indexterm2 set_verify_callback..ssl_stream] 30757Set the callback used to verify peer certificates. ``` 30758template< 30759 class VerifyCallback> 30760void 30761``[link beast.ref.boost__beast__ssl_stream.set_verify_callback.overload1 set_verify_callback]``( 30762 VerifyCallback callback); 30763 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_callback.overload1 more...]]`` 30764 30765template< 30766 class VerifyCallback> 30767void 30768``[link beast.ref.boost__beast__ssl_stream.set_verify_callback.overload2 set_verify_callback]``( 30769 VerifyCallback callback, 30770 boost::system::error_code& ec); 30771 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_callback.overload2 more...]]`` 30772``` 30773[section:overload1 ssl_stream::set_verify_callback (1 of 2 overloads)] 30774Set the callback used to verify peer certificates. 30775[heading Synopsis] 30776``` 30777template< 30778 class VerifyCallback> 30779void 30780set_verify_callback( 30781 VerifyCallback callback); 30782``` 30783 30784[heading Description] 30785This function is used to specify a callback function that will be called by the implementation when it needs to verify a peer certificate. 30786[heading Parameters] 30787[table [[Name][Description]] 30788 [[`callback`][ 30789 30790The function object to be used for verifying a certificate. The function signature of the handler must be: 30791``` 30792 bool verify_callback( 30793 bool preverified, // True if the certificate passed pre-verification. 30794 verify_context& ctx // The peer certificate and other context. 30795 ); 30796``` 30797The return value of the callback is true if the certificate has passed verification, false otherwise. 30798 ]] 30799] 30800[heading Exceptions] 30801[table [[Type][Thrown On]] 30802 [[`boost::system::system_error`][ 30803 30804Thrown on failure. 30805 ]] 30806] 30807[heading Remarks] 30808Calls `SSL_set_verify`. 30809[endsect] 30810[section:overload2 ssl_stream::set_verify_callback (2 of 2 overloads)] 30811Set the callback used to verify peer certificates. 30812[heading Synopsis] 30813``` 30814template< 30815 class VerifyCallback> 30816void 30817set_verify_callback( 30818 VerifyCallback callback, 30819 boost::system::error_code& ec); 30820``` 30821 30822[heading Description] 30823This function is used to specify a callback function that will be called by the implementation when it needs to verify a peer certificate. 30824[heading Parameters] 30825[table [[Name][Description]] 30826 [[`callback`][ 30827 30828The function object to be used for verifying a certificate. The function signature of the handler must be: 30829``` 30830 bool verify_callback( 30831 bool preverified, // True if the certificate passed pre-verification. 30832 net::verify_context& ctx // The peer certificate and other context. 30833 ); 30834``` 30835The return value of the callback is true if the certificate has passed verification, false otherwise. 30836 ]] 30837 [[`ec`][ 30838 30839Set to indicate what error occurred, if any. 30840 ]] 30841] 30842[heading Remarks] 30843Calls `SSL_set_verify`. 30844[endsect] 30845[endsect] 30846 30847[section:set_verify_depth ssl_stream::set_verify_depth] 30848[indexterm2 set_verify_depth..ssl_stream] 30849Set the peer verification depth. ``` 30850void 30851``[link beast.ref.boost__beast__ssl_stream.set_verify_depth.overload1 set_verify_depth]``( 30852 int depth); 30853 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_depth.overload1 more...]]`` 30854 30855void 30856``[link beast.ref.boost__beast__ssl_stream.set_verify_depth.overload2 set_verify_depth]``( 30857 int depth, 30858 boost::system::error_code& ec); 30859 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_depth.overload2 more...]]`` 30860``` 30861[section:overload1 ssl_stream::set_verify_depth (1 of 2 overloads)] 30862Set the peer verification depth. 30863[heading Synopsis] 30864``` 30865void 30866set_verify_depth( 30867 int depth); 30868``` 30869 30870[heading Description] 30871This function may be used to configure the maximum verification depth allowed by the stream. 30872[heading Parameters] 30873[table [[Name][Description]] 30874 [[`depth`][ 30875 30876Maximum depth for the certificate chain verification that shall be allowed. 30877 ]] 30878] 30879[heading Exceptions] 30880[table [[Type][Thrown On]] 30881 [[`boost::system::system_error`][ 30882 30883Thrown on failure. 30884 ]] 30885] 30886[heading Remarks] 30887Calls `SSL_set_verify_depth`. 30888[endsect] 30889[section:overload2 ssl_stream::set_verify_depth (2 of 2 overloads)] 30890Set the peer verification depth. 30891[heading Synopsis] 30892``` 30893void 30894set_verify_depth( 30895 int depth, 30896 boost::system::error_code& ec); 30897``` 30898 30899[heading Description] 30900This function may be used to configure the maximum verification depth allowed by the stream. 30901[heading Parameters] 30902[table [[Name][Description]] 30903 [[`depth`][ 30904 30905Maximum depth for the certificate chain verification that shall be allowed. 30906 ]] 30907 [[`ec`][ 30908 30909Set to indicate what error occurred, if any. 30910 ]] 30911] 30912[heading Remarks] 30913Calls `SSL_set_verify_depth`. 30914[endsect] 30915[endsect] 30916 30917[section:set_verify_mode ssl_stream::set_verify_mode] 30918[indexterm2 set_verify_mode..ssl_stream] 30919Set the peer verification mode. ``` 30920void 30921``[link beast.ref.boost__beast__ssl_stream.set_verify_mode.overload1 set_verify_mode]``( 30922 net::ssl::verify_mode v); 30923 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_mode.overload1 more...]]`` 30924 30925void 30926``[link beast.ref.boost__beast__ssl_stream.set_verify_mode.overload2 set_verify_mode]``( 30927 net::ssl::verify_mode v, 30928 boost::system::error_code& ec); 30929 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.set_verify_mode.overload2 more...]]`` 30930``` 30931[section:overload1 ssl_stream::set_verify_mode (1 of 2 overloads)] 30932Set the peer verification mode. 30933[heading Synopsis] 30934``` 30935void 30936set_verify_mode( 30937 net::ssl::verify_mode v); 30938``` 30939 30940[heading Description] 30941This function may be used to configure the peer verification mode used by the stream. The new mode will override the mode inherited from the context. 30942[heading Parameters] 30943[table [[Name][Description]] 30944 [[`v`][ 30945 30946A bitmask of peer verification modes. 30947 ]] 30948] 30949[heading Exceptions] 30950[table [[Type][Thrown On]] 30951 [[`boost::system::system_error`][ 30952 30953Thrown on failure. 30954 ]] 30955] 30956[heading Remarks] 30957Calls `SSL_set_verify`. 30958[endsect] 30959[section:overload2 ssl_stream::set_verify_mode (2 of 2 overloads)] 30960Set the peer verification mode. 30961[heading Synopsis] 30962``` 30963void 30964set_verify_mode( 30965 net::ssl::verify_mode v, 30966 boost::system::error_code& ec); 30967``` 30968 30969[heading Description] 30970This function may be used to configure the peer verification mode used by the stream. The new mode will override the mode inherited from the context. 30971[heading Parameters] 30972[table [[Name][Description]] 30973 [[`v`][ 30974 30975A bitmask of peer verification modes. See `verify_mode` for available values. 30976 ]] 30977 [[`ec`][ 30978 30979Set to indicate what error occurred, if any. 30980 ]] 30981] 30982[heading Remarks] 30983Calls `SSL_set_verify`. 30984[endsect] 30985[endsect] 30986 30987[section:shutdown ssl_stream::shutdown] 30988[indexterm2 shutdown..ssl_stream] 30989Shut down SSL on the stream. ``` 30990void 30991``[link beast.ref.boost__beast__ssl_stream.shutdown.overload1 shutdown]``(); 30992 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.shutdown.overload1 more...]]`` 30993 30994void 30995``[link beast.ref.boost__beast__ssl_stream.shutdown.overload2 shutdown]``( 30996 boost::system::error_code& ec); 30997 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.shutdown.overload2 more...]]`` 30998``` 30999[section:overload1 ssl_stream::shutdown (1 of 2 overloads)] 31000Shut down SSL on the stream. 31001[heading Synopsis] 31002``` 31003void 31004shutdown(); 31005``` 31006 31007[heading Description] 31008This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs. 31009[heading Exceptions] 31010[table [[Type][Thrown On]] 31011 [[`boost::system::system_error`][ 31012 31013Thrown on failure. 31014 ]] 31015] 31016[endsect] 31017[section:overload2 ssl_stream::shutdown (2 of 2 overloads)] 31018Shut down SSL on the stream. 31019[heading Synopsis] 31020``` 31021void 31022shutdown( 31023 boost::system::error_code& ec); 31024``` 31025 31026[heading Description] 31027This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs. 31028[heading Parameters] 31029[table [[Name][Description]] 31030 [[`ec`][ 31031 31032Set to indicate what error occurred, if any. 31033 ]] 31034] 31035[endsect] 31036[endsect] 31037 31038[section:ssl_stream ssl_stream::ssl_stream] 31039[indexterm2 ssl_stream..ssl_stream] 31040Construct a stream. 31041[heading Synopsis] 31042``` 31043template< 31044 class Arg> 31045ssl_stream( 31046 Arg&& arg, 31047 net::ssl::context& ctx); 31048``` 31049 31050[heading Description] 31051This constructor creates a stream and initialises the underlying stream object. 31052[heading Parameters] 31053[table [[Name][Description]] 31054 [[`arg`][ 31055 31056The argument to be passed to initialise the underlying stream. 31057 ]] 31058 [[`ctx`][ 31059 31060The SSL context to be used for the stream. 31061 ]] 31062] 31063[endsect] 31064[section:write_some ssl_stream::write_some] 31065[indexterm2 write_some..ssl_stream] 31066Write some data to the stream. ``` 31067template< 31068 class __ConstBufferSequence__> 31069std::size_t 31070``[link beast.ref.boost__beast__ssl_stream.write_some.overload1 write_some]``( 31071 ConstBufferSequence const& buffers); 31072 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.write_some.overload1 more...]]`` 31073 31074template< 31075 class __ConstBufferSequence__> 31076std::size_t 31077``[link beast.ref.boost__beast__ssl_stream.write_some.overload2 write_some]``( 31078 ConstBufferSequence const& buffers, 31079 boost::system::error_code& ec); 31080 ``[''''»''' [link beast.ref.boost__beast__ssl_stream.write_some.overload2 more...]]`` 31081``` 31082[section:overload1 ssl_stream::write_some (1 of 2 overloads)] 31083Write some data to the stream. 31084[heading Synopsis] 31085``` 31086template< 31087 class __ConstBufferSequence__> 31088std::size_t 31089write_some( 31090 ConstBufferSequence const& buffers); 31091``` 31092 31093[heading Description] 31094This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 31095[heading Parameters] 31096[table [[Name][Description]] 31097 [[`buffers`][ 31098 31099The data to be written. 31100 ]] 31101] 31102[heading Return Value] 31103The number of bytes written. 31104[heading Exceptions] 31105[table [[Type][Thrown On]] 31106 [[`boost::system::system_error`][ 31107 31108Thrown on failure. 31109 ]] 31110] 31111[heading Remarks] 31112The `write_some` operation may not transmit all of the data to the peer. Consider using the `net::write` function if you need to ensure that all data is written before the blocking operation completes. 31113[endsect] 31114[section:overload2 ssl_stream::write_some (2 of 2 overloads)] 31115Write some data to the stream. 31116[heading Synopsis] 31117``` 31118template< 31119 class __ConstBufferSequence__> 31120std::size_t 31121write_some( 31122 ConstBufferSequence const& buffers, 31123 boost::system::error_code& ec); 31124``` 31125 31126[heading Description] 31127This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 31128[heading Parameters] 31129[table [[Name][Description]] 31130 [[`buffers`][ 31131 31132The data to be written to the stream. 31133 ]] 31134 [[`ec`][ 31135 31136Set to indicate what error occurred, if any. 31137 ]] 31138] 31139[heading Return Value] 31140The number of bytes written. Returns 0 if an error occurred. 31141[heading Remarks] 31142The `write_some` operation may not transmit all of the data to the peer. Consider using the `net::write` function if you need to ensure that all data is written before the blocking operation completes. 31143[endsect] 31144[endsect] 31145 31146 31147 31148 31149Convenience header [include_file boost/beast/ssl.hpp] 31150 31151[endsect] 31152 31153 31154 31155[section:boost__beast__stable_async_base stable_async_base] 31156Base class to provide completion handler boilerplate for composed operations. 31157[heading Synopsis] 31158 31159Defined in header [include_file boost/beast/core/async_base.hpp] 31160 31161 31162 31163``` 31164template< 31165 class __Handler__, 31166 class __Executor1__, 31167 class __Allocator__ = std::allocator<void>> 31168class stable_async_base : 31169 public async_base< Handler, Executor1, Allocator > 31170``` 31171[heading Types] 31172[table [[Name][Description]] 31173 [ 31174 [[link beast.ref.boost__beast__stable_async_base.allocator_type [*allocator_type]]] 31175 [ 31176 The type of allocator associated with this object. 31177 ] 31178 ] 31179 [ 31180 [[link beast.ref.boost__beast__stable_async_base.executor_type [*executor_type]]] 31181 [ 31182 The type of executor associated with this object. 31183 ] 31184 ] 31185] 31186[heading Member Functions] 31187[table [[Name][Description]] 31188 [ 31189 [[link beast.ref.boost__beast__stable_async_base.complete [*complete]]] 31190 [ 31191 Invoke the final completion handler, maybe using post. 31192 ] 31193 ] 31194 [ 31195 [[link beast.ref.boost__beast__stable_async_base.complete_now [*complete_now]]] 31196 [ 31197 Invoke the final completion handler. 31198 ] 31199 ] 31200 [ 31201 [[link beast.ref.boost__beast__stable_async_base.get_allocator [*get_allocator]]] 31202 [ 31203 Returns the allocator associated with this object. 31204 ] 31205 ] 31206 [ 31207 [[link beast.ref.boost__beast__stable_async_base.get_executor [*get_executor]]] 31208 [ 31209 Returns the executor associated with this object. 31210 ] 31211 ] 31212 [ 31213 [[link beast.ref.boost__beast__stable_async_base.handler [*handler]]] 31214 [ 31215 Returns the handler associated with this object. 31216 ] 31217 ] 31218 [ 31219 [[link beast.ref.boost__beast__stable_async_base.release_handler [*release_handler]]] 31220 [ 31221 Returns ownership of the handler associated with this object. 31222 ] 31223 ] 31224 [ 31225 [[link beast.ref.boost__beast__stable_async_base.stable_async_base [*stable_async_base]]] 31226 [ 31227 Constructor. 31228 31229 Move Constructor. 31230 ] 31231 ] 31232 [ 31233 [[link beast.ref.boost__beast__stable_async_base.stable_async_base_dtor_ [*~stable_async_base]]] 31234 [ 31235 Destructor. 31236 ] 31237 ] 31238] 31239[heading Friends] 31240[table [[Name][Description]] 31241 [ 31242 [[link beast.ref.boost__beast__stable_async_base.allocate_stable [*allocate_stable]]] 31243 [ 31244 Allocate a temporary object to hold operation state. 31245 ] 31246 ] 31247] 31248 31249[heading Description] 31250A function object submitted to intermediate initiating functions during a composed operation may derive from this type to inherit all of the boilerplate to forward the executor, allocator, and legacy customization points associated with the completion handler invoked at the end of the composed operation. 31251The composed operation must be typical; that is, associated with one executor of an I/O object, and invoking a caller-provided completion handler when the operation is finished. Classes derived from [link beast.ref.boost__beast__async_base `async_base`] will acquire these properties: 31252 31253* Ownership of the final completion handler provided upon construction. 31254 31255 31256* If the final handler has an associated allocator, this allocator will be propagated to the composed operation subclass. Otherwise, the associated allocator will be the type specified in the allocator template parameter, or the default of `std::allocator<void>` if the parameter is omitted. 31257 31258 31259* If the final handler has an associated executor, then it will be used as the executor associated with the composed operation. Otherwise, the specified `Executor1` will be the type of executor associated with the composed operation. 31260 31261 31262* An instance of `net::executor_work_guard` for the instance of `Executor1` shall be maintained until either the final handler is invoked, or the operation base is destroyed, whichever comes first. 31263 31264 31265* Calls to the legacy customization points `asio_handler_invoke`, `asio_handler_allocate`, `asio_handler_deallocate`, and `asio_handler_is_continuation`, which use argument-dependent lookup, will be forwarded to the legacy customization points associated with the handler. 31266 31267Data members of composed operations implemented as completion handlers do not have stable addresses, as the composed operation object is move constructed upon each call to an initiating function. For most operations this is not a problem. For complex operations requiring stable temporary storage, the class [link beast.ref.boost__beast__stable_async_base `stable_async_base`] is provided which offers additional functionality: 31268 31269* The free function [link beast.ref.boost__beast__allocate_stable `allocate_stable`] may be used to allocate one or more temporary objects associated with the composed operation. 31270 31271 31272* Memory for stable temporary objects is allocated using the allocator associated with the composed operation. 31273 31274 31275* Stable temporary objects are automatically destroyed, and the memory freed using the associated allocator, either before the final completion handler is invoked (a Networking requirement) or when the composed operation is destroyed, whichever occurs first. 31276 31277[heading Example] 31278 31279The following code demonstrates how [link beast.ref.boost__beast__stable_async_base `stable_async_base`] may be be used to assist authoring an asynchronous initiating function, by providing all of the boilerplate to manage the final completion handler in a way that maintains the allocator and executor associations. Furthermore, the operation shown allocates temporary memory using [link beast.ref.boost__beast__allocate_stable `allocate_stable`] for the timer and message, whose addresses must not change between intermediate operations: 31280 31281``` 31282 // Asynchronously send a message multiple times, once per second 31283 template <class AsyncWriteStream, class T, class WriteHandler> 31284 auto async_write_messages( 31285 AsyncWriteStream& stream, 31286 T const& message, 31287 std::size_t repeat_count, 31288 WriteHandler&& handler) -> 31289 typename net::async_result< 31290 typename std::decay<WriteHandler>::type, 31291 void(error_code)>::return_type 31292 { 31293 using handler_type = typename net::async_completion<WriteHandler, void(error_code)>::completion_handler_type; 31294 using base_type = stable_async_base<handler_type, typename AsyncWriteStream::executor_type>; 31295 31296 struct op : base_type, boost::asio::coroutine 31297 { 31298 // This object must have a stable address 31299 struct temporary_data 31300 { 31301 // Although std::string is in theory movable, most implementations 31302 // use a "small buffer optimization" which means that we might 31303 // be submitting a buffer to the write operation and then 31304 // moving the string, invalidating the buffer. To prevent 31305 // undefined behavior we store the string object itself at 31306 // a stable location. 31307 std::string const message; 31308 31309 net::steady_timer timer; 31310 31311 temporary_data(std::string message_, net::io_context& ctx) 31312 : message(std::move(message_)) 31313 , timer(ctx) 31314 { 31315 } 31316 }; 31317 31318 AsyncWriteStream& stream_; 31319 std::size_t repeats_; 31320 temporary_data& data_; 31321 31322 op(AsyncWriteStream& stream, std::size_t repeats, std::string message, handler_type& handler) 31323 : base_type(std::move(handler), stream.get_executor()) 31324 , stream_(stream) 31325 , repeats_(repeats) 31326 , data_(allocate_stable<temporary_data>(*this, std::move(message), stream.get_executor().context())) 31327 { 31328 (*this)(); // start the operation 31329 } 31330 31331 // Including this file provides the keywords for macro-based coroutines 31332 #include <boost/asio/yield.hpp> 31333 31334 void operator()(error_code ec = {}, std::size_t = 0) 31335 { 31336 reenter(*this) 31337 { 31338 // If repeats starts at 0 then we must complete immediately. But 31339 // we can't call the final handler from inside the initiating 31340 // function, so we post our intermediate handler first. We use 31341 // net::async_write with an empty buffer instead of calling 31342 // net::post to avoid an extra function template instantiation, to 31343 // keep compile times lower and make the resulting executable smaller. 31344 yield net::async_write(stream_, net::const_buffer{}, std::move(*this)); 31345 while(! ec && repeats_-- > 0) 31346 { 31347 // Send the string. We construct a `const_buffer` here to guarantee 31348 // that we do not create an additional function template instantation 31349 // of net::async_write, since we already instantiated it above for 31350 // net::const_buffer. 31351 31352 yield net::async_write(stream_, 31353 net::const_buffer(net::buffer(data_.message)), std::move(*this)); 31354 if(ec) 31355 break; 31356 31357 // Set the timer and wait 31358 data_.timer.expires_after(std::chrono::seconds(1)); 31359 yield data_.timer.async_wait(std::move(*this)); 31360 } 31361 } 31362 31363 // The base class destroys the temporary data automatically, 31364 // before invoking the final completion handler 31365 this->complete_now(ec); 31366 } 31367 31368 // Including this file undefines the macros for the coroutines 31369 #include <boost/asio/unyield.hpp> 31370 }; 31371 31372 net::async_completion<WriteHandler, void(error_code)> completion(handler); 31373 std::ostringstream os; 31374 os << message; 31375 op(stream, repeat_count, os.str(), completion.completion_handler); 31376 return completion.result.get(); 31377 } 31378``` 31379[heading Template Parameters] 31380[table [[Type][Description]] 31381 [[`Handler`][ 31382 31383The type of the completion handler to store. This type must meet the requirements of ['CompletionHandler]. 31384 ]] 31385 [[`Executor1`][ 31386 31387The type of the executor used when the handler has no associated executor. An instance of this type must be provided upon construction. The implementation will maintain an executor work guard and a copy of this instance. 31388 ]] 31389 [[`Allocator`][ 31390 31391The allocator type to use if the handler does not have an associated allocator. If this parameter is omitted, then `std::allocator<void>` will be used. If the specified allocator is not default constructible, an instance of the type must be provided upon construction. 31392 ]] 31393] 31394[heading See Also] 31395[link beast.ref.boost__beast__stable_async_base.allocate_stable `stable_async_base::allocate_stable`], [link beast.ref.boost__beast__async_base `async_base`] 31396[section:allocate_stable stable_async_base::allocate_stable] 31397[indexterm2 allocate_stable..stable_async_base] 31398Allocate a temporary object to hold operation state. 31399[heading Synopsis] 31400 31401Defined in header [include_file boost/beast/core/async_base.hpp] 31402 31403 31404``` 31405template< 31406 class State, 31407 class __Handler__, 31408 class Executor1_, 31409 class Allocator_, 31410 class... Args> 31411friend State& 31412allocate_stable( 31413 stable_async_base< Handler_, Executor1_, Allocator_ >& base, 31414 Args&&... args); 31415``` 31416 31417[heading Description] 31418The object will be destroyed just before the completion handler is invoked, or when the operation base is destroyed. 31419 31420 31421Convenience header [include_file boost/beast/core.hpp] 31422 31423[endsect] 31424[section:allocator_type stable_async_base::allocator_type] 31425(Inherited from `async_base`) 31426 31427[indexterm2 allocator_type..stable_async_base] 31428The type of allocator associated with this object. 31429[heading Synopsis] 31430 31431``` 31432using allocator_type = net::associated_allocator_t< Handler, Allocator >; 31433``` 31434 31435[heading Description] 31436If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the associated allocator of the derived class will be this type. [endsect] 31437[section:complete stable_async_base::complete] 31438(Inherited from `async_base`) 31439 31440[indexterm2 complete..stable_async_base] 31441Invoke the final completion handler, maybe using post. 31442[heading Synopsis] 31443``` 31444template< 31445 class... Args> 31446void 31447complete( 31448 bool is_continuation, 31449 Args&&... args); 31450``` 31451 31452[heading Description] 31453This invokes the final completion handler with the specified arguments forwarded. It is undefined to call either of [link beast.ref.boost__beast__async_base.complete `async_base::complete`] or [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`] more than once. 31454Any temporary objects allocated with [link beast.ref.boost__beast__allocate_stable `allocate_stable`] will be automatically destroyed before the final completion handler is invoked. 31455[heading Parameters] 31456[table [[Name][Description]] 31457 [[`is_continuation`][ 31458 31459If this value is `false`, then the handler will be submitted to the executor using `net::post`. Otherwise the handler will be invoked as if by calling [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`]. 31460 ]] 31461 [[`args`][ 31462 31463A list of optional parameters to invoke the handler with. The completion handler must be invocable with the parameter list, or else a compilation error will result. 31464 ]] 31465] 31466[endsect] 31467[section:complete_now stable_async_base::complete_now] 31468(Inherited from `async_base`) 31469 31470[indexterm2 complete_now..stable_async_base] 31471Invoke the final completion handler. 31472[heading Synopsis] 31473``` 31474template< 31475 class... Args> 31476void 31477complete_now( 31478 Args&&... args); 31479``` 31480 31481[heading Description] 31482This invokes the final completion handler with the specified arguments forwarded. It is undefined to call either of [link beast.ref.boost__beast__async_base.complete `async_base::complete`] or [link beast.ref.boost__beast__async_base.complete_now `async_base::complete_now`] more than once. 31483Any temporary objects allocated with [link beast.ref.boost__beast__allocate_stable `allocate_stable`] will be automatically destroyed before the final completion handler is invoked. 31484[heading Parameters] 31485[table [[Name][Description]] 31486 [[`args`][ 31487 31488A list of optional parameters to invoke the handler with. The completion handler must be invocable with the parameter list, or else a compilation error will result. 31489 ]] 31490] 31491[endsect] 31492[section:executor_type stable_async_base::executor_type] 31493(Inherited from `async_base`) 31494 31495[indexterm2 executor_type..stable_async_base] 31496The type of executor associated with this object. 31497[heading Synopsis] 31498 31499``` 31500using executor_type = net::associated_executor_t< Handler, Executor1 >; 31501``` 31502 31503[heading Description] 31504If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the associated executor of the derived class will be this type. [endsect] 31505[section:get_allocator stable_async_base::get_allocator] 31506(Inherited from `async_base`) 31507 31508[indexterm2 get_allocator..stable_async_base] 31509Returns the allocator associated with this object. 31510[heading Synopsis] 31511``` 31512allocator_type 31513get_allocator() const; 31514``` 31515 31516[heading Description] 31517If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the object returned from this function will be used as the associated allocator of the derived class. [endsect] 31518[section:get_executor stable_async_base::get_executor] 31519(Inherited from `async_base`) 31520 31521[indexterm2 get_executor..stable_async_base] 31522Returns the executor associated with this object. 31523[heading Synopsis] 31524``` 31525executor_type 31526get_executor() const; 31527``` 31528 31529[heading Description] 31530If a class derived from [link beast.ref.boost__beast__async_base `async_base`] is a completion handler, then the object returned from this function will be used as the associated executor of the derived class. [endsect] 31531[section:handler stable_async_base::handler] 31532(Inherited from `async_base`) 31533 31534[indexterm2 handler..stable_async_base] 31535Returns the handler associated with this object. 31536[heading Synopsis] 31537``` 31538Handler const & 31539handler() const; 31540``` 31541 31542[heading Description] 31543[endsect] 31544[section:release_handler stable_async_base::release_handler] 31545(Inherited from `async_base`) 31546 31547[indexterm2 release_handler..stable_async_base] 31548Returns ownership of the handler associated with this object. 31549[heading Synopsis] 31550``` 31551Handler 31552release_handler(); 31553``` 31554 31555[heading Description] 31556This function is used to transfer ownership of the handler to the caller, by move-construction. After the move, the only valid operations on the base object are move construction and destruction. [endsect] 31557[section:stable_async_base stable_async_base::stable_async_base] 31558[indexterm2 stable_async_base..stable_async_base] 31559Constructor. ``` 31560template< 31561 class __Handler__> 31562``[link beast.ref.boost__beast__stable_async_base.stable_async_base.overload1 stable_async_base]``( 31563 Handler&& handler, 31564 Executor1 const& ex1, 31565 Allocator const& alloc = Allocator()); 31566 ``[''''»''' [link beast.ref.boost__beast__stable_async_base.stable_async_base.overload1 more...]]`` 31567 31568``` 31569Move Constructor. ``` 31570``[link beast.ref.boost__beast__stable_async_base.stable_async_base.overload2 stable_async_base]``( 31571 stable_async_base&& other); 31572 ``[''''»''' [link beast.ref.boost__beast__stable_async_base.stable_async_base.overload2 more...]]`` 31573``` 31574[section:overload1 stable_async_base::stable_async_base (1 of 2 overloads)] 31575Constructor. 31576[heading Synopsis] 31577``` 31578template< 31579 class __Handler__> 31580stable_async_base( 31581 Handler&& handler, 31582 Executor1 const& ex1, 31583 Allocator const& alloc = Allocator()); 31584``` 31585 31586[heading Description] 31587[heading Parameters] 31588[table [[Name][Description]] 31589 [[`handler`][ 31590 31591The final completion handler. The type of this object must meet the requirements of ['CompletionHandler]. The implementation takes ownership of the handler by performing a decay-copy. 31592 ]] 31593 [[`ex1`][ 31594 31595The executor associated with the implied I/O object target of the operation. The implementation shall maintain an executor work guard for the lifetime of the operation, or until the final completion handler is invoked, whichever is shorter. 31596 ]] 31597 [[`alloc`][ 31598 31599The allocator to be associated with objects derived from this class. If `Allocator` is default-constructible, this parameter is optional and may be omitted. 31600 ]] 31601] 31602[endsect] 31603[section:overload2 stable_async_base::stable_async_base (2 of 2 overloads)] 31604Move Constructor. 31605[heading Synopsis] 31606``` 31607stable_async_base( 31608 stable_async_base&& other); 31609``` 31610 31611[heading Description] 31612[endsect] 31613[endsect] 31614 31615[section:stable_async_base_dtor_ stable_async_base::~stable_async_base] 31616[indexterm2 ~stable_async_base..stable_async_base] 31617Destructor. 31618[heading Synopsis] 31619``` 31620~stable_async_base(); 31621``` 31622 31623[heading Description] 31624If the completion handler was not invoked, then any state objects allocated with [link beast.ref.boost__beast__stable_async_base.allocate_stable `stable_async_base::allocate_stable`] will be destroyed here. [endsect] 31625 31626 31627 31628Convenience header [include_file boost/beast/core.hpp] 31629 31630[endsect] 31631 31632 31633 31634[section:boost__beast__static_buffer static_buffer] 31635A dynamic buffer providing a fixed size, circular buffer. 31636[heading Synopsis] 31637 31638Defined in header [include_file boost/beast/core/static_buffer.hpp] 31639 31640 31641 31642``` 31643template< 31644 std::size_t N> 31645class static_buffer : 31646 public static_buffer_base 31647``` 31648[heading Types] 31649[table [[Name][Description]] 31650 [ 31651 [[link beast.ref.boost__beast__static_buffer.const_buffers_type [*const_buffers_type]]] 31652 [ 31653 The ConstBufferSequence used to represent the readable bytes. 31654 ] 31655 ] 31656 [ 31657 [[link beast.ref.boost__beast__static_buffer.mutable_buffers_type [*mutable_buffers_type]]] 31658 [ 31659 The MutableBufferSequence used to represent the writable bytes. 31660 ] 31661 ] 31662 [ 31663 [[link beast.ref.boost__beast__static_buffer.mutable_data_type [*mutable_data_type]]] 31664 [ 31665 The MutableBufferSequence used to represent the readable bytes. 31666 ] 31667 ] 31668] 31669[heading Member Functions] 31670[table [[Name][Description]] 31671 [ 31672 [[link beast.ref.boost__beast__static_buffer.base [*base]]] 31673 [ 31674 Returns the static_buffer_base portion of this object. 31675 ] 31676 ] 31677 [ 31678 [[link beast.ref.boost__beast__static_buffer.capacity [*capacity]]] 31679 [ 31680 Return the maximum sum of input and output sizes that can be held without an allocation. 31681 ] 31682 ] 31683 [ 31684 [[link beast.ref.boost__beast__static_buffer.cdata [*cdata]]] 31685 [ 31686 Returns a constant buffer sequence representing the readable bytes. 31687 ] 31688 ] 31689 [ 31690 [[link beast.ref.boost__beast__static_buffer.clear [*clear]]] 31691 [ 31692 Clear the readable and writable bytes to zero. 31693 ] 31694 ] 31695 [ 31696 [[link beast.ref.boost__beast__static_buffer.commit [*commit]]] 31697 [ 31698 Append writable bytes to the readable bytes. 31699 ] 31700 ] 31701 [ 31702 [[link beast.ref.boost__beast__static_buffer.consume [*consume]]] 31703 [ 31704 Remove bytes from beginning of the readable bytes. 31705 ] 31706 ] 31707 [ 31708 [[link beast.ref.boost__beast__static_buffer.data [*data]]] 31709 [ 31710 Returns a constant buffer sequence representing the readable bytes. 31711 31712 Returns a mutable buffer sequence representing the readable bytes. 31713 ] 31714 ] 31715 [ 31716 [[link beast.ref.boost__beast__static_buffer.max_size [*max_size]]] 31717 [ 31718 Return the maximum sum of the input and output sequence sizes. 31719 ] 31720 ] 31721 [ 31722 [[link beast.ref.boost__beast__static_buffer.operator_eq_ [*operator=]]] 31723 [ 31724 Assignment. 31725 ] 31726 ] 31727 [ 31728 [[link beast.ref.boost__beast__static_buffer.prepare [*prepare]]] 31729 [ 31730 Returns a mutable buffer sequence representing writable bytes. 31731 ] 31732 ] 31733 [ 31734 [[link beast.ref.boost__beast__static_buffer.size [*size]]] 31735 [ 31736 Returns the number of readable bytes. 31737 ] 31738 ] 31739 [ 31740 [[link beast.ref.boost__beast__static_buffer.static_buffer [*static_buffer]]] 31741 [ 31742 Constructor. 31743 ] 31744 ] 31745] 31746 31747[heading Description] 31748A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 31749Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 31750 31751* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] when `this` is non-const. 31752 31753 31754* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] and [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`], may have length up to two. 31755 31756 31757* All operations execute in constant time. 31758 31759[heading Template Parameters] 31760[table [[Type][Description]] 31761 [[`N`][ 31762 31763The number of bytes in the internal buffer. 31764 ]] 31765] 31766[heading Remarks] 31767To reduce the number of template instantiations when passing objects of this type in a deduced context, the signature of the receiving function should use [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] instead. 31768[heading See Also] 31769[link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] 31770[section:base static_buffer::base] 31771[indexterm2 base..static_buffer] 31772Returns the [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] portion of this object. ``` 31773static_buffer_base& 31774``[link beast.ref.boost__beast__static_buffer.base.overload1 base]``(); 31775 ``[''''»''' [link beast.ref.boost__beast__static_buffer.base.overload1 more...]]`` 31776 31777static_buffer_base const & 31778``[link beast.ref.boost__beast__static_buffer.base.overload2 base]``() const; 31779 ``[''''»''' [link beast.ref.boost__beast__static_buffer.base.overload2 more...]]`` 31780``` 31781[section:overload1 static_buffer::base (1 of 2 overloads)] 31782Returns the [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] portion of this object. 31783[heading Synopsis] 31784``` 31785static_buffer_base& 31786base(); 31787``` 31788 31789[heading Description] 31790[endsect] 31791[section:overload2 static_buffer::base (2 of 2 overloads)] 31792Returns the [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] portion of this object. 31793[heading Synopsis] 31794``` 31795static_buffer_base const & 31796base() const; 31797``` 31798 31799[heading Description] 31800[endsect] 31801[endsect] 31802 31803[section:capacity static_buffer::capacity] 31804[indexterm2 capacity..static_buffer] 31805Return the maximum sum of input and output sizes that can be held without an allocation. 31806[heading Synopsis] 31807``` 31808std::size_t constexpr 31809capacity() const; 31810``` 31811 31812[heading Description] 31813[endsect] 31814[section:cdata static_buffer::cdata] 31815[indexterm2 cdata..static_buffer] 31816Returns a constant buffer sequence representing the readable bytes. 31817[heading Synopsis] 31818``` 31819const_buffers_type 31820cdata() const; 31821``` 31822 31823[heading Description] 31824[endsect] 31825[section:clear static_buffer::clear] 31826[indexterm2 clear..static_buffer] 31827Clear the readable and writable bytes to zero. 31828[heading Synopsis] 31829``` 31830void 31831clear(); 31832``` 31833 31834[heading Description] 31835This function causes the readable and writable bytes to become empty. The capacity is not changed. 31836Buffer sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] become invalid. 31837[heading Exception Safety] 31838 31839No-throw guarantee. [endsect] 31840[section:commit static_buffer::commit] 31841[indexterm2 commit..static_buffer] 31842Append writable bytes to the readable bytes. 31843[heading Synopsis] 31844``` 31845void 31846commit( 31847 std::size_t n); 31848``` 31849 31850[heading Description] 31851Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 31852All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 31853[heading Parameters] 31854[table [[Name][Description]] 31855 [[`n`][ 31856 31857The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 31858 ]] 31859] 31860[heading Exception Safety] 31861 31862No-throw guarantee. [endsect] 31863[section:const_buffers_type static_buffer::const_buffers_type] 31864[indexterm2 const_buffers_type..static_buffer] 31865The ConstBufferSequence used to represent the readable bytes. 31866[heading Synopsis] 31867 31868``` 31869using const_buffers_type = ``['implementation-defined]``; 31870``` 31871 31872[heading Description] 31873[endsect] 31874[section:consume static_buffer::consume] 31875[indexterm2 consume..static_buffer] 31876Remove bytes from beginning of the readable bytes. 31877[heading Synopsis] 31878``` 31879void 31880consume( 31881 std::size_t n); 31882``` 31883 31884[heading Description] 31885Removes n bytes from the beginning of the readable bytes. 31886All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 31887[heading Parameters] 31888[table [[Name][Description]] 31889 [[`n`][ 31890 31891The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 31892 ]] 31893] 31894[heading Exception Safety] 31895 31896No-throw guarantee. [endsect] 31897[section:data static_buffer::data] 31898[indexterm2 data..static_buffer] 31899Returns a constant buffer sequence representing the readable bytes. ``` 31900const_buffers_type 31901``[link beast.ref.boost__beast__static_buffer.data.overload1 data]``() const; 31902 ``[''''»''' [link beast.ref.boost__beast__static_buffer.data.overload1 more...]]`` 31903 31904``` 31905Returns a mutable buffer sequence representing the readable bytes. ``` 31906mutable_data_type 31907``[link beast.ref.boost__beast__static_buffer.data.overload2 data]``(); 31908 ``[''''»''' [link beast.ref.boost__beast__static_buffer.data.overload2 more...]]`` 31909``` 31910[section:overload1 static_buffer::data (1 of 2 overloads)] 31911Returns a constant buffer sequence representing the readable bytes. 31912[heading Synopsis] 31913``` 31914const_buffers_type 31915data() const; 31916``` 31917 31918[heading Description] 31919[endsect] 31920[section:overload2 static_buffer::data (2 of 2 overloads)] 31921Returns a mutable buffer sequence representing the readable bytes. 31922[heading Synopsis] 31923``` 31924mutable_data_type 31925data(); 31926``` 31927 31928[heading Description] 31929[endsect] 31930[endsect] 31931 31932[section:max_size static_buffer::max_size] 31933[indexterm2 max_size..static_buffer] 31934Return the maximum sum of the input and output sequence sizes. 31935[heading Synopsis] 31936``` 31937std::size_t constexpr 31938max_size() const; 31939``` 31940 31941[heading Description] 31942[endsect] 31943[section:mutable_buffers_type static_buffer::mutable_buffers_type] 31944[indexterm2 mutable_buffers_type..static_buffer] 31945The MutableBufferSequence used to represent the writable bytes. 31946[heading Synopsis] 31947 31948``` 31949using mutable_buffers_type = ``['implementation-defined]``; 31950``` 31951 31952[heading Description] 31953[endsect] 31954[section:mutable_data_type static_buffer::mutable_data_type] 31955[indexterm2 mutable_data_type..static_buffer] 31956The MutableBufferSequence used to represent the readable bytes. 31957[heading Synopsis] 31958 31959``` 31960using mutable_data_type = ``['implementation-defined]``; 31961``` 31962 31963[heading Description] 31964[endsect] 31965[section:operator_eq_ static_buffer::operator=] 31966[indexterm2 operator=..static_buffer] 31967Assignment. 31968[heading Synopsis] 31969``` 31970static_buffer& 31971operator=( 31972 static_buffer const&); 31973``` 31974 31975[heading Description] 31976[endsect] 31977[section:prepare static_buffer::prepare] 31978[indexterm2 prepare..static_buffer] 31979Returns a mutable buffer sequence representing writable bytes. 31980[heading Synopsis] 31981``` 31982mutable_buffers_type 31983prepare( 31984 std::size_t n); 31985``` 31986 31987[heading Description] 31988Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. Memory may be reallocated as needed. 31989All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 31990[heading Parameters] 31991[table [[Name][Description]] 31992 [[`n`][ 31993 31994The desired number of bytes in the returned buffer sequence. 31995 ]] 31996] 31997[heading Exceptions] 31998[table [[Type][Thrown On]] 31999 [[`std::length_error`][ 32000 32001if `size() + n` exceeds `max_size()`. 32002 ]] 32003] 32004[heading Exception Safety] 32005 32006Strong guarantee. [endsect] 32007[section:size static_buffer::size] 32008[indexterm2 size..static_buffer] 32009Returns the number of readable bytes. 32010[heading Synopsis] 32011``` 32012std::size_t 32013size() const; 32014``` 32015 32016[heading Description] 32017[endsect] 32018[section:static_buffer static_buffer::static_buffer] 32019[indexterm2 static_buffer..static_buffer] 32020Constructor. ``` 32021``[link beast.ref.boost__beast__static_buffer.static_buffer.overload1 static_buffer]``(); 32022 ``[''''»''' [link beast.ref.boost__beast__static_buffer.static_buffer.overload1 more...]]`` 32023 32024``[link beast.ref.boost__beast__static_buffer.static_buffer.overload2 static_buffer]``( 32025 static_buffer const&); 32026 ``[''''»''' [link beast.ref.boost__beast__static_buffer.static_buffer.overload2 more...]]`` 32027``` 32028[section:overload1 static_buffer::static_buffer (1 of 2 overloads)] 32029Constructor. 32030[heading Synopsis] 32031``` 32032static_buffer(); 32033``` 32034 32035[heading Description] 32036[endsect] 32037[section:overload2 static_buffer::static_buffer (2 of 2 overloads)] 32038Constructor. 32039[heading Synopsis] 32040``` 32041static_buffer( 32042 static_buffer const&); 32043``` 32044 32045[heading Description] 32046[endsect] 32047[endsect] 32048 32049 32050 32051 32052Convenience header [include_file boost/beast/core.hpp] 32053 32054[endsect] 32055 32056 32057 32058[section:boost__beast__static_buffer_base static_buffer_base] 32059A dynamic buffer providing a fixed size, circular buffer. 32060[heading Synopsis] 32061 32062Defined in header [include_file boost/beast/core/static_buffer.hpp] 32063 32064 32065 32066``` 32067class static_buffer_base 32068``` 32069[heading Types] 32070[table [[Name][Description]] 32071 [ 32072 [[link beast.ref.boost__beast__static_buffer_base.const_buffers_type [*const_buffers_type]]] 32073 [ 32074 The ConstBufferSequence used to represent the readable bytes. 32075 ] 32076 ] 32077 [ 32078 [[link beast.ref.boost__beast__static_buffer_base.mutable_buffers_type [*mutable_buffers_type]]] 32079 [ 32080 The MutableBufferSequence used to represent the writable bytes. 32081 ] 32082 ] 32083 [ 32084 [[link beast.ref.boost__beast__static_buffer_base.mutable_data_type [*mutable_data_type]]] 32085 [ 32086 The MutableBufferSequence used to represent the readable bytes. 32087 ] 32088 ] 32089] 32090[heading Member Functions] 32091[table [[Name][Description]] 32092 [ 32093 [[link beast.ref.boost__beast__static_buffer_base.capacity [*capacity]]] 32094 [ 32095 Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 32096 ] 32097 ] 32098 [ 32099 [[link beast.ref.boost__beast__static_buffer_base.cdata [*cdata]]] 32100 [ 32101 Returns a constant buffer sequence representing the readable bytes. 32102 ] 32103 ] 32104 [ 32105 [[link beast.ref.boost__beast__static_buffer_base.clear [*clear]]] 32106 [ 32107 Clear the readable and writable bytes to zero. 32108 ] 32109 ] 32110 [ 32111 [[link beast.ref.boost__beast__static_buffer_base.commit [*commit]]] 32112 [ 32113 Append writable bytes to the readable bytes. 32114 ] 32115 ] 32116 [ 32117 [[link beast.ref.boost__beast__static_buffer_base.consume [*consume]]] 32118 [ 32119 Remove bytes from beginning of the readable bytes. 32120 ] 32121 ] 32122 [ 32123 [[link beast.ref.boost__beast__static_buffer_base.data [*data]]] 32124 [ 32125 Returns a constant buffer sequence representing the readable bytes. 32126 32127 Returns a mutable buffer sequence representing the readable bytes. 32128 ] 32129 ] 32130 [ 32131 [[link beast.ref.boost__beast__static_buffer_base.max_size [*max_size]]] 32132 [ 32133 Return the maximum number of bytes, both readable and writable, that can ever be held. 32134 ] 32135 ] 32136 [ 32137 [[link beast.ref.boost__beast__static_buffer_base.prepare [*prepare]]] 32138 [ 32139 Returns a mutable buffer sequence representing writable bytes. 32140 ] 32141 ] 32142 [ 32143 [[link beast.ref.boost__beast__static_buffer_base.size [*size]]] 32144 [ 32145 Returns the number of readable bytes. 32146 ] 32147 ] 32148 [ 32149 [[link beast.ref.boost__beast__static_buffer_base.static_buffer_base [*static_buffer_base]]] 32150 [ 32151 Constructor. 32152 ] 32153 ] 32154] 32155 32156[heading Description] 32157A dynamic buffer encapsulates memory storage that may be automatically resized as required, where the memory is divided into two regions: readable bytes followed by writable bytes. These memory regions are internal to the dynamic buffer, but direct access to the elements is provided to permit them to be efficiently used with I/O operations. 32158Objects of this type meet the requirements of ['DynamicBuffer] and have the following additional properties: 32159 32160* A mutable buffer sequence representing the readable bytes is returned by [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] when `this` is non-const. 32161 32162 32163* Buffer sequences representing the readable and writable bytes, returned by [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] and [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`], may have length up to two. 32164 32165 32166* All operations execute in constant time. 32167 32168 32169* Ownership of the underlying storage belongs to the derived class. 32170 32171[heading Remarks] 32172Variables are usually declared using the template class [link beast.ref.boost__beast__static_buffer `static_buffer`]; however, to reduce the number of template instantiations, objects should be passed `static_buffer_base&`. 32173[heading See Also] 32174[link beast.ref.boost__beast__static_buffer `static_buffer`] 32175[section:capacity static_buffer_base::capacity] 32176[indexterm2 capacity..static_buffer_base] 32177Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. 32178[heading Synopsis] 32179``` 32180std::size_t 32181capacity() const; 32182``` 32183 32184[heading Description] 32185[endsect] 32186[section:cdata static_buffer_base::cdata] 32187[indexterm2 cdata..static_buffer_base] 32188Returns a constant buffer sequence representing the readable bytes. 32189[heading Synopsis] 32190``` 32191const_buffers_type 32192cdata() const; 32193``` 32194 32195[heading Description] 32196[endsect] 32197[section:clear static_buffer_base::clear] 32198[indexterm2 clear..static_buffer_base] 32199Clear the readable and writable bytes to zero. 32200[heading Synopsis] 32201``` 32202void 32203clear(); 32204``` 32205 32206[heading Description] 32207This function causes the readable and writable bytes to become empty. The capacity is not changed. 32208Buffer sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] become invalid. 32209[heading Exception Safety] 32210 32211No-throw guarantee. [endsect] 32212[section:commit static_buffer_base::commit] 32213[indexterm2 commit..static_buffer_base] 32214Append writable bytes to the readable bytes. 32215[heading Synopsis] 32216``` 32217void 32218commit( 32219 std::size_t n); 32220``` 32221 32222[heading Description] 32223Appends n bytes from the start of the writable bytes to the end of the readable bytes. The remainder of the writable bytes are discarded. If n is greater than the number of writable bytes, all writable bytes are appended to the readable bytes. 32224All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 32225[heading Parameters] 32226[table [[Name][Description]] 32227 [[`n`][ 32228 32229The number of bytes to append. If this number is greater than the number of writable bytes, all writable bytes are appended. 32230 ]] 32231] 32232[heading Exception Safety] 32233 32234No-throw guarantee. [endsect] 32235[section:const_buffers_type static_buffer_base::const_buffers_type] 32236[indexterm2 const_buffers_type..static_buffer_base] 32237The ConstBufferSequence used to represent the readable bytes. 32238[heading Synopsis] 32239 32240``` 32241using const_buffers_type = ``['implementation-defined]``; 32242``` 32243 32244[heading Description] 32245[endsect] 32246[section:consume static_buffer_base::consume] 32247[indexterm2 consume..static_buffer_base] 32248Remove bytes from beginning of the readable bytes. 32249[heading Synopsis] 32250``` 32251void 32252consume( 32253 std::size_t n); 32254``` 32255 32256[heading Description] 32257Removes n bytes from the beginning of the readable bytes. 32258All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 32259[heading Parameters] 32260[table [[Name][Description]] 32261 [[`n`][ 32262 32263The number of bytes to remove. If this number is greater than the number of readable bytes, all readable bytes are removed. 32264 ]] 32265] 32266[heading Exception Safety] 32267 32268No-throw guarantee. [endsect] 32269[section:data static_buffer_base::data] 32270[indexterm2 data..static_buffer_base] 32271Returns a constant buffer sequence representing the readable bytes. ``` 32272const_buffers_type 32273``[link beast.ref.boost__beast__static_buffer_base.data.overload1 data]``() const; 32274 ``[''''»''' [link beast.ref.boost__beast__static_buffer_base.data.overload1 more...]]`` 32275 32276``` 32277Returns a mutable buffer sequence representing the readable bytes. ``` 32278mutable_data_type 32279``[link beast.ref.boost__beast__static_buffer_base.data.overload2 data]``(); 32280 ``[''''»''' [link beast.ref.boost__beast__static_buffer_base.data.overload2 more...]]`` 32281``` 32282[section:overload1 static_buffer_base::data (1 of 2 overloads)] 32283Returns a constant buffer sequence representing the readable bytes. 32284[heading Synopsis] 32285``` 32286const_buffers_type 32287data() const; 32288``` 32289 32290[heading Description] 32291[endsect] 32292[section:overload2 static_buffer_base::data (2 of 2 overloads)] 32293Returns a mutable buffer sequence representing the readable bytes. 32294[heading Synopsis] 32295``` 32296mutable_data_type 32297data(); 32298``` 32299 32300[heading Description] 32301[endsect] 32302[endsect] 32303 32304[section:max_size static_buffer_base::max_size] 32305[indexterm2 max_size..static_buffer_base] 32306Return the maximum number of bytes, both readable and writable, that can ever be held. 32307[heading Synopsis] 32308``` 32309std::size_t 32310max_size() const; 32311``` 32312 32313[heading Description] 32314[endsect] 32315[section:mutable_buffers_type static_buffer_base::mutable_buffers_type] 32316[indexterm2 mutable_buffers_type..static_buffer_base] 32317The MutableBufferSequence used to represent the writable bytes. 32318[heading Synopsis] 32319 32320``` 32321using mutable_buffers_type = ``['implementation-defined]``; 32322``` 32323 32324[heading Description] 32325[endsect] 32326[section:mutable_data_type static_buffer_base::mutable_data_type] 32327[indexterm2 mutable_data_type..static_buffer_base] 32328The MutableBufferSequence used to represent the readable bytes. 32329[heading Synopsis] 32330 32331``` 32332using mutable_data_type = ``['implementation-defined]``; 32333``` 32334 32335[heading Description] 32336[endsect] 32337[section:prepare static_buffer_base::prepare] 32338[indexterm2 prepare..static_buffer_base] 32339Returns a mutable buffer sequence representing writable bytes. 32340[heading Synopsis] 32341``` 32342mutable_buffers_type 32343prepare( 32344 std::size_t n); 32345``` 32346 32347[heading Description] 32348Returns a mutable buffer sequence representing the writable bytes containing exactly `n` bytes of storage. Memory may be reallocated as needed. 32349All buffers sequences previously obtained using [link beast.ref.boost__beast__static_buffer.data `static_buffer::data`] or [link beast.ref.boost__beast__static_buffer.prepare `static_buffer::prepare`] are invalidated. 32350[heading Parameters] 32351[table [[Name][Description]] 32352 [[`n`][ 32353 32354The desired number of bytes in the returned buffer sequence. 32355 ]] 32356] 32357[heading Exceptions] 32358[table [[Type][Thrown On]] 32359 [[`std::length_error`][ 32360 32361if `size() + n` exceeds `max_size()`. 32362 ]] 32363] 32364[heading Exception Safety] 32365 32366Strong guarantee. [endsect] 32367[section:size static_buffer_base::size] 32368[indexterm2 size..static_buffer_base] 32369Returns the number of readable bytes. 32370[heading Synopsis] 32371``` 32372std::size_t 32373size() const; 32374``` 32375 32376[heading Description] 32377[endsect] 32378[section:static_buffer_base static_buffer_base::static_buffer_base] 32379[indexterm2 static_buffer_base..static_buffer_base] 32380Constructor. 32381[heading Synopsis] 32382``` 32383static_buffer_base( 32384 void* p, 32385 std::size_t size); 32386``` 32387 32388[heading Description] 32389This creates a dynamic buffer using the provided storage area. 32390[heading Parameters] 32391[table [[Name][Description]] 32392 [[`p`][ 32393 32394A pointer to valid storage of at least `n` bytes. 32395 ]] 32396 [[`size`][ 32397 32398The number of valid bytes pointed to by `p`. 32399 ]] 32400] 32401[endsect] 32402 32403 32404 32405Convenience header [include_file boost/beast/core.hpp] 32406 32407[endsect] 32408 32409 32410 32411[section:boost__beast__static_string static_string] 32412A modifiable string with a fixed-size storage area. 32413[heading Synopsis] 32414 32415Defined in header [include_file boost/beast/core/static_string.hpp] 32416 32417 32418 32419``` 32420template< 32421 std::size_t N, 32422 class CharT = char, 32423 class Traits = std::char_traits<CharT>> 32424class static_string 32425``` 32426[heading Types] 32427[table [[Name][Description]] 32428 [ 32429 [[link beast.ref.boost__beast__static_string.const_iterator [*const_iterator]]] 32430 [ 32431 32432 ] 32433 ] 32434 [ 32435 [[link beast.ref.boost__beast__static_string.const_pointer [*const_pointer]]] 32436 [ 32437 32438 ] 32439 ] 32440 [ 32441 [[link beast.ref.boost__beast__static_string.const_reference [*const_reference]]] 32442 [ 32443 32444 ] 32445 ] 32446 [ 32447 [[link beast.ref.boost__beast__static_string.const_reverse_iterator [*const_reverse_iterator]]] 32448 [ 32449 32450 ] 32451 ] 32452 [ 32453 [[link beast.ref.boost__beast__static_string.difference_type [*difference_type]]] 32454 [ 32455 32456 ] 32457 ] 32458 [ 32459 [[link beast.ref.boost__beast__static_string.iterator [*iterator]]] 32460 [ 32461 32462 ] 32463 ] 32464 [ 32465 [[link beast.ref.boost__beast__static_string.pointer [*pointer]]] 32466 [ 32467 32468 ] 32469 ] 32470 [ 32471 [[link beast.ref.boost__beast__static_string.reference [*reference]]] 32472 [ 32473 32474 ] 32475 ] 32476 [ 32477 [[link beast.ref.boost__beast__static_string.reverse_iterator [*reverse_iterator]]] 32478 [ 32479 32480 ] 32481 ] 32482 [ 32483 [[link beast.ref.boost__beast__static_string.size_type [*size_type]]] 32484 [ 32485 32486 ] 32487 ] 32488 [ 32489 [[link beast.ref.boost__beast__static_string.string_view_type [*string_view_type]]] 32490 [ 32491 The type of string_view returned by the interface. 32492 ] 32493 ] 32494 [ 32495 [[link beast.ref.boost__beast__static_string.traits_type [*traits_type]]] 32496 [ 32497 32498 ] 32499 ] 32500 [ 32501 [[link beast.ref.boost__beast__static_string.value_type [*value_type]]] 32502 [ 32503 32504 ] 32505 ] 32506] 32507[heading Member Functions] 32508[table [[Name][Description]] 32509 [ 32510 [[link beast.ref.boost__beast__static_string.append [*append]]] 32511 [ 32512 32513 ] 32514 ] 32515 [ 32516 [[link beast.ref.boost__beast__static_string.assign [*assign]]] 32517 [ 32518 Assign count copies of ch. 32519 32520 Assign from another static_string 32521 32522 Assign count characterss starting at npos from other. 32523 32524 Assign the first count characters of s, including nulls. 32525 32526 Assign a null terminated string. 32527 32528 Assign from an iterator range of characters. 32529 32530 Assign from any object convertible to string_view_type. 32531 ] 32532 ] 32533 [ 32534 [[link beast.ref.boost__beast__static_string.at [*at]]] 32535 [ 32536 Access specified character with bounds checking. 32537 ] 32538 ] 32539 [ 32540 [[link beast.ref.boost__beast__static_string.back [*back]]] 32541 [ 32542 Accesses the last character. 32543 ] 32544 ] 32545 [ 32546 [[link beast.ref.boost__beast__static_string.begin [*begin]]] 32547 [ 32548 Returns an iterator to the beginning. 32549 ] 32550 ] 32551 [ 32552 [[link beast.ref.boost__beast__static_string.c_str [*c_str]]] 32553 [ 32554 Returns a non-modifiable standard C character array version of the string. 32555 ] 32556 ] 32557 [ 32558 [[link beast.ref.boost__beast__static_string.capacity [*capacity]]] 32559 [ 32560 Returns the number of characters that can be held in currently allocated storage. 32561 ] 32562 ] 32563 [ 32564 [[link beast.ref.boost__beast__static_string.cbegin [*cbegin]]] 32565 [ 32566 Returns an iterator to the beginning. 32567 ] 32568 ] 32569 [ 32570 [[link beast.ref.boost__beast__static_string.cend [*cend]]] 32571 [ 32572 Returns an iterator to the end. 32573 ] 32574 ] 32575 [ 32576 [[link beast.ref.boost__beast__static_string.clear [*clear]]] 32577 [ 32578 Clears the contents. 32579 ] 32580 ] 32581 [ 32582 [[link beast.ref.boost__beast__static_string.compare [*compare]]] 32583 [ 32584 32585 ] 32586 ] 32587 [ 32588 [[link beast.ref.boost__beast__static_string.copy [*copy]]] 32589 [ 32590 Copy a substring (pos, pos+count) to character string pointed to by dest. 32591 ] 32592 ] 32593 [ 32594 [[link beast.ref.boost__beast__static_string.crbegin [*crbegin]]] 32595 [ 32596 Returns a reverse iterator to the beginning. 32597 ] 32598 ] 32599 [ 32600 [[link beast.ref.boost__beast__static_string.crend [*crend]]] 32601 [ 32602 Returns a reverse iterator to the end. 32603 ] 32604 ] 32605 [ 32606 [[link beast.ref.boost__beast__static_string.data [*data]]] 32607 [ 32608 Returns a pointer to the first character of a string. 32609 ] 32610 ] 32611 [ 32612 [[link beast.ref.boost__beast__static_string.empty [*empty]]] 32613 [ 32614 Returns true if the string is empty. 32615 ] 32616 ] 32617 [ 32618 [[link beast.ref.boost__beast__static_string.end [*end]]] 32619 [ 32620 Returns an iterator to the end. 32621 ] 32622 ] 32623 [ 32624 [[link beast.ref.boost__beast__static_string.erase [*erase]]] 32625 [ 32626 32627 ] 32628 ] 32629 [ 32630 [[link beast.ref.boost__beast__static_string.front [*front]]] 32631 [ 32632 Accesses the first character. 32633 ] 32634 ] 32635 [ 32636 [[link beast.ref.boost__beast__static_string.insert [*insert]]] 32637 [ 32638 32639 ] 32640 ] 32641 [ 32642 [[link beast.ref.boost__beast__static_string.length [*length]]] 32643 [ 32644 Returns the number of characters, excluding the null terminator. 32645 ] 32646 ] 32647 [ 32648 [[link beast.ref.boost__beast__static_string.max_size [*max_size]]] 32649 [ 32650 Returns the maximum number of characters that can be stored, excluding the null terminator. 32651 ] 32652 ] 32653 [ 32654 [[link beast.ref.boost__beast__static_string.operator_string_view_type [*operator string_view_type]]] 32655 [ 32656 Convert a static string to a string_view_type 32657 ] 32658 ] 32659 [ 32660 [[link beast.ref.boost__beast__static_string.operator_plus__eq_ [*operator+=]]] 32661 [ 32662 32663 ] 32664 ] 32665 [ 32666 [[link beast.ref.boost__beast__static_string.operator_eq_ [*operator=]]] 32667 [ 32668 Copy assignment. 32669 32670 Assign from null-terminated string. 32671 32672 Assign from single character. 32673 32674 Assign from initializer list. 32675 32676 Assign from string_view_type. 32677 ] 32678 ] 32679 [ 32680 [[link beast.ref.boost__beast__static_string.operator_lb__rb_ [*operator\[\]]]] 32681 [ 32682 Access specified character. 32683 ] 32684 ] 32685 [ 32686 [[link beast.ref.boost__beast__static_string.pop_back [*pop_back]]] 32687 [ 32688 32689 ] 32690 ] 32691 [ 32692 [[link beast.ref.boost__beast__static_string.push_back [*push_back]]] 32693 [ 32694 32695 ] 32696 ] 32697 [ 32698 [[link beast.ref.boost__beast__static_string.rbegin [*rbegin]]] 32699 [ 32700 Returns a reverse iterator to the beginning. 32701 ] 32702 ] 32703 [ 32704 [[link beast.ref.boost__beast__static_string.rend [*rend]]] 32705 [ 32706 Returns a reverse iterator to the end. 32707 ] 32708 ] 32709 [ 32710 [[link beast.ref.boost__beast__static_string.reserve [*reserve]]] 32711 [ 32712 Reserves storage. 32713 ] 32714 ] 32715 [ 32716 [[link beast.ref.boost__beast__static_string.resize [*resize]]] 32717 [ 32718 Changes the number of characters stored. 32719 ] 32720 ] 32721 [ 32722 [[link beast.ref.boost__beast__static_string.shrink_to_fit [*shrink_to_fit]]] 32723 [ 32724 Reduces memory usage by freeing unused memory. 32725 ] 32726 ] 32727 [ 32728 [[link beast.ref.boost__beast__static_string.size [*size]]] 32729 [ 32730 Returns the number of characters, excluding the null terminator. 32731 ] 32732 ] 32733 [ 32734 [[link beast.ref.boost__beast__static_string.static_string [*static_string]]] 32735 [ 32736 Default constructor (empty string). 32737 32738 Construct with count copies of character ch. 32739 32740 Construct with a substring (pos, other.size()) of other. 32741 32742 Construct with a substring (pos, count) of other. 32743 32744 Construct with the first count characters of s, including nulls. 32745 32746 Construct from a null terminated string. 32747 32748 Construct from a range of characters. 32749 32750 Copy constructor. 32751 32752 Construct from an initializer list. 32753 32754 Construct from a string_view 32755 32756 Construct from any object convertible to string_view_type. 32757 ] 32758 ] 32759 [ 32760 [[link beast.ref.boost__beast__static_string.substr [*substr]]] 32761 [ 32762 32763 ] 32764 ] 32765 [ 32766 [[link beast.ref.boost__beast__static_string.swap [*swap]]] 32767 [ 32768 Exchange the contents of this string with another. 32769 ] 32770 ] 32771] 32772[heading Data Members] 32773[table [[Name][Description]] 32774 [ 32775 [[link beast.ref.boost__beast__static_string.max_size_n [*max_size_n]]] 32776 [ 32777 Maximum size of the string excluding the null terminator. 32778 ] 32779 ] 32780 [ 32781 [[link beast.ref.boost__beast__static_string.npos [*npos]]] 32782 [ 32783 A special index. 32784 ] 32785 ] 32786] 32787 32788[heading Description] 32789These objects behave like `std::string` except that the storage is not dynamically allocated but rather fixed in size. 32790These strings offer performance advantages when a protocol imposes a natural small upper limit on the size of a value. 32791[heading Remarks] 32792The stored string is always null-terminated. 32793[heading See Also] 32794[link beast.ref.boost__beast__to_static_string `to_static_string`] 32795[section:append static_string::append] 32796[indexterm2 append..static_string] 32797``` 32798static_string& 32799``[link beast.ref.boost__beast__static_string.append.overload1 append]``( 32800 size_type count, 32801 CharT ch); 32802 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload1 more...]]`` 32803 32804template< 32805 std::size_t M> 32806static_string& 32807``[link beast.ref.boost__beast__static_string.append.overload2 append]``( 32808 static_string< M, CharT, Traits > const& str); 32809 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload2 more...]]`` 32810 32811template< 32812 std::size_t M> 32813static_string& 32814``[link beast.ref.boost__beast__static_string.append.overload3 append]``( 32815 static_string< M, CharT, Traits > const& str, 32816 size_type pos, 32817 size_type count = npos); 32818 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload3 more...]]`` 32819 32820static_string& 32821``[link beast.ref.boost__beast__static_string.append.overload4 append]``( 32822 CharT const* s, 32823 size_type count); 32824 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload4 more...]]`` 32825 32826static_string& 32827``[link beast.ref.boost__beast__static_string.append.overload5 append]``( 32828 CharT const* s); 32829 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload5 more...]]`` 32830 32831template< 32832 class InputIt> 32833static_string& 32834``[link beast.ref.boost__beast__static_string.append.overload6 append]``( 32835 InputIt first, 32836 InputIt last); 32837 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload6 more...]]`` 32838 32839static_string& 32840``[link beast.ref.boost__beast__static_string.append.overload7 append]``( 32841 std::initializer_list< CharT > init); 32842 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload7 more...]]`` 32843 32844static_string& 32845``[link beast.ref.boost__beast__static_string.append.overload8 append]``( 32846 string_view_type sv); 32847 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload8 more...]]`` 32848 32849template< 32850 class T> 32851std::enable_if< std::is_convertible< T const &, string_view_type >::value &&! std::is_convertible< T const &, CharT const * >::value, static_string & >::type 32852``[link beast.ref.boost__beast__static_string.append.overload9 append]``( 32853 T const& t, 32854 size_type pos, 32855 size_type count = npos); 32856 ``[''''»''' [link beast.ref.boost__beast__static_string.append.overload9 more...]]`` 32857``` 32858[section:overload1 static_string::append (1 of 9 overloads)] 32859 32860[heading Synopsis] 32861``` 32862static_string& 32863append( 32864 size_type count, 32865 CharT ch); 32866``` 32867 32868[heading Description] 32869[endsect] 32870[section:overload2 static_string::append (2 of 9 overloads)] 32871 32872[heading Synopsis] 32873``` 32874template< 32875 std::size_t M> 32876static_string& 32877append( 32878 static_string< M, CharT, Traits > const& str); 32879``` 32880 32881[heading Description] 32882[endsect] 32883[section:overload3 static_string::append (3 of 9 overloads)] 32884 32885[heading Synopsis] 32886``` 32887template< 32888 std::size_t M> 32889static_string& 32890append( 32891 static_string< M, CharT, Traits > const& str, 32892 size_type pos, 32893 size_type count = npos); 32894``` 32895 32896[heading Description] 32897[endsect] 32898[section:overload4 static_string::append (4 of 9 overloads)] 32899 32900[heading Synopsis] 32901``` 32902static_string& 32903append( 32904 CharT const* s, 32905 size_type count); 32906``` 32907 32908[heading Description] 32909[endsect] 32910[section:overload5 static_string::append (5 of 9 overloads)] 32911 32912[heading Synopsis] 32913``` 32914static_string& 32915append( 32916 CharT const* s); 32917``` 32918 32919[heading Description] 32920[endsect] 32921[section:overload6 static_string::append (6 of 9 overloads)] 32922 32923[heading Synopsis] 32924``` 32925template< 32926 class InputIt> 32927static_string& 32928append( 32929 InputIt first, 32930 InputIt last); 32931``` 32932 32933[heading Description] 32934[endsect] 32935[section:overload7 static_string::append (7 of 9 overloads)] 32936 32937[heading Synopsis] 32938``` 32939static_string& 32940append( 32941 std::initializer_list< CharT > init); 32942``` 32943 32944[heading Description] 32945[endsect] 32946[section:overload8 static_string::append (8 of 9 overloads)] 32947 32948[heading Synopsis] 32949``` 32950static_string& 32951append( 32952 string_view_type sv); 32953``` 32954 32955[heading Description] 32956[endsect] 32957[section:overload9 static_string::append (9 of 9 overloads)] 32958 32959[heading Synopsis] 32960``` 32961template< 32962 class T> 32963std::enable_if< std::is_convertible< T const &, string_view_type >::value &&! std::is_convertible< T const &, CharT const * >::value, static_string & >::type 32964append( 32965 T const& t, 32966 size_type pos, 32967 size_type count = npos); 32968``` 32969 32970[heading Description] 32971[endsect] 32972[endsect] 32973 32974[section:assign static_string::assign] 32975[indexterm2 assign..static_string] 32976Assign `count` copies of `ch`. ``` 32977static_string& 32978``[link beast.ref.boost__beast__static_string.assign.overload1 assign]``( 32979 size_type count, 32980 CharT ch); 32981 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload1 more...]]`` 32982 32983``` 32984Assign from another `static_string` ``` 32985static_string& 32986``[link beast.ref.boost__beast__static_string.assign.overload2 assign]``( 32987 static_string const& str); 32988 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload2 more...]]`` 32989 32990template< 32991 std::size_t M> 32992static_string& 32993``[link beast.ref.boost__beast__static_string.assign.overload3 assign]``( 32994 static_string< M, CharT, Traits > const& str); 32995 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload3 more...]]`` 32996 32997``` 32998Assign `count` characterss starting at `npos` from `other`. ``` 32999template< 33000 std::size_t M> 33001static_string& 33002``[link beast.ref.boost__beast__static_string.assign.overload4 assign]``( 33003 static_string< M, CharT, Traits > const& str, 33004 size_type pos, 33005 size_type count = npos); 33006 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload4 more...]]`` 33007 33008``` 33009Assign the first `count` characters of `s`, including nulls. ``` 33010static_string& 33011``[link beast.ref.boost__beast__static_string.assign.overload5 assign]``( 33012 CharT const* s, 33013 size_type count); 33014 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload5 more...]]`` 33015 33016``` 33017Assign a null terminated string. ``` 33018static_string& 33019``[link beast.ref.boost__beast__static_string.assign.overload6 assign]``( 33020 CharT const* s); 33021 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload6 more...]]`` 33022 33023``` 33024Assign from an iterator range of characters. ``` 33025template< 33026 class InputIt> 33027static_string& 33028``[link beast.ref.boost__beast__static_string.assign.overload7 assign]``( 33029 InputIt first, 33030 InputIt last); 33031 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload7 more...]]`` 33032 33033static_string& 33034``[link beast.ref.boost__beast__static_string.assign.overload8 assign]``( 33035 std::initializer_list< CharT > init); 33036 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload8 more...]]`` 33037 33038static_string& 33039``[link beast.ref.boost__beast__static_string.assign.overload9 assign]``( 33040 string_view_type str); 33041 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload9 more...]]`` 33042 33043``` 33044Assign from any object convertible to `string_view_type`. ``` 33045template< 33046 class T> 33047static_string& 33048``[link beast.ref.boost__beast__static_string.assign.overload10 assign]``( 33049 T const& t, 33050 size_type pos, 33051 size_type count = npos); 33052 ``[''''»''' [link beast.ref.boost__beast__static_string.assign.overload10 more...]]`` 33053``` 33054[section:overload1 static_string::assign (1 of 10 overloads)] 33055Assign `count` copies of `ch`. 33056[heading Synopsis] 33057``` 33058static_string& 33059assign( 33060 size_type count, 33061 CharT ch); 33062``` 33063 33064[heading Description] 33065[endsect] 33066[section:overload2 static_string::assign (2 of 10 overloads)] 33067Assign from another `static_string` 33068[heading Synopsis] 33069``` 33070static_string& 33071assign( 33072 static_string const& str); 33073``` 33074 33075[heading Description] 33076[endsect] 33077[section:overload3 static_string::assign (3 of 10 overloads)] 33078Assign from another `static_string` 33079[heading Synopsis] 33080``` 33081template< 33082 std::size_t M> 33083static_string& 33084assign( 33085 static_string< M, CharT, Traits > const& str); 33086``` 33087 33088[heading Description] 33089[endsect] 33090[section:overload4 static_string::assign (4 of 10 overloads)] 33091Assign `count` characterss starting at `npos` from `other`. 33092[heading Synopsis] 33093``` 33094template< 33095 std::size_t M> 33096static_string& 33097assign( 33098 static_string< M, CharT, Traits > const& str, 33099 size_type pos, 33100 size_type count = npos); 33101``` 33102 33103[heading Description] 33104[endsect] 33105[section:overload5 static_string::assign (5 of 10 overloads)] 33106Assign the first `count` characters of `s`, including nulls. 33107[heading Synopsis] 33108``` 33109static_string& 33110assign( 33111 CharT const* s, 33112 size_type count); 33113``` 33114 33115[heading Description] 33116[endsect] 33117[section:overload6 static_string::assign (6 of 10 overloads)] 33118Assign a null terminated string. 33119[heading Synopsis] 33120``` 33121static_string& 33122assign( 33123 CharT const* s); 33124``` 33125 33126[heading Description] 33127[endsect] 33128[section:overload7 static_string::assign (7 of 10 overloads)] 33129Assign from an iterator range of characters. 33130[heading Synopsis] 33131``` 33132template< 33133 class InputIt> 33134static_string& 33135assign( 33136 InputIt first, 33137 InputIt last); 33138``` 33139 33140[heading Description] 33141[endsect] 33142[section:overload8 static_string::assign (8 of 10 overloads)] 33143Assign from initializer list. 33144[heading Synopsis] 33145``` 33146static_string& 33147assign( 33148 std::initializer_list< CharT > init); 33149``` 33150 33151[heading Description] 33152[endsect] 33153[section:overload9 static_string::assign (9 of 10 overloads)] 33154Assign from `string_view_type`. 33155[heading Synopsis] 33156``` 33157static_string& 33158assign( 33159 string_view_type str); 33160``` 33161 33162[heading Description] 33163[endsect] 33164[section:overload10 static_string::assign (10 of 10 overloads)] 33165Assign from any object convertible to `string_view_type`. 33166[heading Synopsis] 33167``` 33168template< 33169 class T> 33170static_string& 33171assign( 33172 T const& t, 33173 size_type pos, 33174 size_type count = npos); 33175``` 33176 33177[heading Description] 33178The range (pos, n) is extracted from the value obtained by converting `t` to `string_view_type`, and used to assign the string. [endsect] 33179[endsect] 33180 33181[section:at static_string::at] 33182[indexterm2 at..static_string] 33183Access specified character with bounds checking. ``` 33184reference 33185``[link beast.ref.boost__beast__static_string.at.overload1 at]``( 33186 size_type pos); 33187 ``[''''»''' [link beast.ref.boost__beast__static_string.at.overload1 more...]]`` 33188 33189const_reference 33190``[link beast.ref.boost__beast__static_string.at.overload2 at]``( 33191 size_type pos) const; 33192 ``[''''»''' [link beast.ref.boost__beast__static_string.at.overload2 more...]]`` 33193``` 33194[section:overload1 static_string::at (1 of 2 overloads)] 33195Access specified character with bounds checking. 33196[heading Synopsis] 33197``` 33198reference 33199at( 33200 size_type pos); 33201``` 33202 33203[heading Description] 33204[endsect] 33205[section:overload2 static_string::at (2 of 2 overloads)] 33206Access specified character with bounds checking. 33207[heading Synopsis] 33208``` 33209const_reference 33210at( 33211 size_type pos) const; 33212``` 33213 33214[heading Description] 33215[endsect] 33216[endsect] 33217 33218[section:back static_string::back] 33219[indexterm2 back..static_string] 33220Accesses the last character. ``` 33221CharT& 33222``[link beast.ref.boost__beast__static_string.back.overload1 back]``(); 33223 ``[''''»''' [link beast.ref.boost__beast__static_string.back.overload1 more...]]`` 33224 33225CharT const & 33226``[link beast.ref.boost__beast__static_string.back.overload2 back]``() const; 33227 ``[''''»''' [link beast.ref.boost__beast__static_string.back.overload2 more...]]`` 33228``` 33229[section:overload1 static_string::back (1 of 2 overloads)] 33230Accesses the last character. 33231[heading Synopsis] 33232``` 33233CharT& 33234back(); 33235``` 33236 33237[heading Description] 33238[endsect] 33239[section:overload2 static_string::back (2 of 2 overloads)] 33240Accesses the last character. 33241[heading Synopsis] 33242``` 33243CharT const & 33244back() const; 33245``` 33246 33247[heading Description] 33248[endsect] 33249[endsect] 33250 33251[section:begin static_string::begin] 33252[indexterm2 begin..static_string] 33253Returns an iterator to the beginning. ``` 33254iterator 33255``[link beast.ref.boost__beast__static_string.begin.overload1 begin]``(); 33256 ``[''''»''' [link beast.ref.boost__beast__static_string.begin.overload1 more...]]`` 33257 33258const_iterator 33259``[link beast.ref.boost__beast__static_string.begin.overload2 begin]``() const; 33260 ``[''''»''' [link beast.ref.boost__beast__static_string.begin.overload2 more...]]`` 33261``` 33262[section:overload1 static_string::begin (1 of 2 overloads)] 33263Returns an iterator to the beginning. 33264[heading Synopsis] 33265``` 33266iterator 33267begin(); 33268``` 33269 33270[heading Description] 33271[endsect] 33272[section:overload2 static_string::begin (2 of 2 overloads)] 33273Returns an iterator to the beginning. 33274[heading Synopsis] 33275``` 33276const_iterator 33277begin() const; 33278``` 33279 33280[heading Description] 33281[endsect] 33282[endsect] 33283 33284[section:c_str static_string::c_str] 33285[indexterm2 c_str..static_string] 33286Returns a non-modifiable standard C character array version of the string. 33287[heading Synopsis] 33288``` 33289CharT const * 33290c_str() const; 33291``` 33292 33293[heading Description] 33294[endsect] 33295[section:capacity static_string::capacity] 33296[indexterm2 capacity..static_string] 33297Returns the number of characters that can be held in currently allocated storage. 33298[heading Synopsis] 33299``` 33300size_type constexpr 33301capacity() const; 33302``` 33303 33304[heading Description] 33305[endsect] 33306[section:cbegin static_string::cbegin] 33307[indexterm2 cbegin..static_string] 33308Returns an iterator to the beginning. 33309[heading Synopsis] 33310``` 33311const_iterator 33312cbegin() const; 33313``` 33314 33315[heading Description] 33316[endsect] 33317[section:cend static_string::cend] 33318[indexterm2 cend..static_string] 33319Returns an iterator to the end. 33320[heading Synopsis] 33321``` 33322const_iterator 33323cend() const; 33324``` 33325 33326[heading Description] 33327[endsect] 33328[section:clear static_string::clear] 33329[indexterm2 clear..static_string] 33330Clears the contents. 33331[heading Synopsis] 33332``` 33333void 33334clear(); 33335``` 33336 33337[heading Description] 33338[endsect] 33339[section:compare static_string::compare] 33340[indexterm2 compare..static_string] 33341``` 33342template< 33343 std::size_t M> 33344int 33345``[link beast.ref.boost__beast__static_string.compare.overload1 compare]``( 33346 static_string< M, CharT, Traits > const& str) const; 33347 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload1 more...]]`` 33348 33349template< 33350 std::size_t M> 33351int 33352``[link beast.ref.boost__beast__static_string.compare.overload2 compare]``( 33353 size_type pos1, 33354 size_type count1, 33355 static_string< M, CharT, Traits > const& str) const; 33356 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload2 more...]]`` 33357 33358template< 33359 std::size_t M> 33360int 33361``[link beast.ref.boost__beast__static_string.compare.overload3 compare]``( 33362 size_type pos1, 33363 size_type count1, 33364 static_string< M, CharT, Traits > const& str, 33365 size_type pos2, 33366 size_type count2 = npos) const; 33367 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload3 more...]]`` 33368 33369int 33370``[link beast.ref.boost__beast__static_string.compare.overload4 compare]``( 33371 CharT const* s) const; 33372 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload4 more...]]`` 33373 33374int 33375``[link beast.ref.boost__beast__static_string.compare.overload5 compare]``( 33376 size_type pos1, 33377 size_type count1, 33378 CharT const* s) const; 33379 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload5 more...]]`` 33380 33381int 33382``[link beast.ref.boost__beast__static_string.compare.overload6 compare]``( 33383 size_type pos1, 33384 size_type count1, 33385 CharT const* s, 33386 size_type count2) const; 33387 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload6 more...]]`` 33388 33389int 33390``[link beast.ref.boost__beast__static_string.compare.overload7 compare]``( 33391 string_view_type str) const; 33392 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload7 more...]]`` 33393 33394int 33395``[link beast.ref.boost__beast__static_string.compare.overload8 compare]``( 33396 size_type pos1, 33397 size_type count1, 33398 string_view_type str) const; 33399 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload8 more...]]`` 33400 33401template< 33402 class T> 33403int 33404``[link beast.ref.boost__beast__static_string.compare.overload9 compare]``( 33405 size_type pos1, 33406 size_type count1, 33407 T const& t, 33408 size_type pos2, 33409 size_type count2 = npos) const; 33410 ``[''''»''' [link beast.ref.boost__beast__static_string.compare.overload9 more...]]`` 33411``` 33412[section:overload1 static_string::compare (1 of 9 overloads)] 33413 33414[heading Synopsis] 33415``` 33416template< 33417 std::size_t M> 33418int 33419compare( 33420 static_string< M, CharT, Traits > const& str) const; 33421``` 33422 33423[heading Description] 33424[endsect] 33425[section:overload2 static_string::compare (2 of 9 overloads)] 33426 33427[heading Synopsis] 33428``` 33429template< 33430 std::size_t M> 33431int 33432compare( 33433 size_type pos1, 33434 size_type count1, 33435 static_string< M, CharT, Traits > const& str) const; 33436``` 33437 33438[heading Description] 33439[endsect] 33440[section:overload3 static_string::compare (3 of 9 overloads)] 33441 33442[heading Synopsis] 33443``` 33444template< 33445 std::size_t M> 33446int 33447compare( 33448 size_type pos1, 33449 size_type count1, 33450 static_string< M, CharT, Traits > const& str, 33451 size_type pos2, 33452 size_type count2 = npos) const; 33453``` 33454 33455[heading Description] 33456[endsect] 33457[section:overload4 static_string::compare (4 of 9 overloads)] 33458 33459[heading Synopsis] 33460``` 33461int 33462compare( 33463 CharT const* s) const; 33464``` 33465 33466[heading Description] 33467[endsect] 33468[section:overload5 static_string::compare (5 of 9 overloads)] 33469 33470[heading Synopsis] 33471``` 33472int 33473compare( 33474 size_type pos1, 33475 size_type count1, 33476 CharT const* s) const; 33477``` 33478 33479[heading Description] 33480[endsect] 33481[section:overload6 static_string::compare (6 of 9 overloads)] 33482 33483[heading Synopsis] 33484``` 33485int 33486compare( 33487 size_type pos1, 33488 size_type count1, 33489 CharT const* s, 33490 size_type count2) const; 33491``` 33492 33493[heading Description] 33494[endsect] 33495[section:overload7 static_string::compare (7 of 9 overloads)] 33496 33497[heading Synopsis] 33498``` 33499int 33500compare( 33501 string_view_type str) const; 33502``` 33503 33504[heading Description] 33505[endsect] 33506[section:overload8 static_string::compare (8 of 9 overloads)] 33507 33508[heading Synopsis] 33509``` 33510int 33511compare( 33512 size_type pos1, 33513 size_type count1, 33514 string_view_type str) const; 33515``` 33516 33517[heading Description] 33518[endsect] 33519[section:overload9 static_string::compare (9 of 9 overloads)] 33520 33521[heading Synopsis] 33522``` 33523template< 33524 class T> 33525int 33526compare( 33527 size_type pos1, 33528 size_type count1, 33529 T const& t, 33530 size_type pos2, 33531 size_type count2 = npos) const; 33532``` 33533 33534[heading Description] 33535[endsect] 33536[endsect] 33537 33538[section:const_iterator static_string::const_iterator] 33539[indexterm2 const_iterator..static_string] 33540 33541[heading Synopsis] 33542 33543``` 33544using const_iterator = value_type const *; 33545``` 33546 33547[heading Description] 33548[endsect] 33549[section:const_pointer static_string::const_pointer] 33550[indexterm2 const_pointer..static_string] 33551 33552[heading Synopsis] 33553 33554``` 33555using const_pointer = value_type const *; 33556``` 33557 33558[heading Description] 33559[endsect] 33560[section:const_reference static_string::const_reference] 33561[indexterm2 const_reference..static_string] 33562 33563[heading Synopsis] 33564 33565``` 33566using const_reference = value_type const &; 33567``` 33568 33569[heading Description] 33570[endsect] 33571[section:const_reverse_iterator static_string::const_reverse_iterator] 33572[indexterm2 const_reverse_iterator..static_string] 33573 33574[heading Synopsis] 33575 33576``` 33577using const_reverse_iterator = std::reverse_iterator< const_iterator >; 33578``` 33579 33580[heading Description] 33581[endsect] 33582[section:copy static_string::copy] 33583[indexterm2 copy..static_string] 33584Copy a substring (pos, pos+count) to character string pointed to by `dest`. 33585[heading Synopsis] 33586``` 33587size_type 33588copy( 33589 CharT* dest, 33590 size_type count, 33591 size_type pos = 0) const; 33592``` 33593 33594[heading Description] 33595[endsect] 33596[section:crbegin static_string::crbegin] 33597[indexterm2 crbegin..static_string] 33598Returns a reverse iterator to the beginning. 33599[heading Synopsis] 33600``` 33601const_reverse_iterator 33602crbegin() const; 33603``` 33604 33605[heading Description] 33606[endsect] 33607[section:crend static_string::crend] 33608[indexterm2 crend..static_string] 33609Returns a reverse iterator to the end. 33610[heading Synopsis] 33611``` 33612const_reverse_iterator 33613crend() const; 33614``` 33615 33616[heading Description] 33617[endsect] 33618[section:data static_string::data] 33619[indexterm2 data..static_string] 33620Returns a pointer to the first character of a string. ``` 33621CharT* 33622``[link beast.ref.boost__beast__static_string.data.overload1 data]``(); 33623 ``[''''»''' [link beast.ref.boost__beast__static_string.data.overload1 more...]]`` 33624 33625CharT const * 33626``[link beast.ref.boost__beast__static_string.data.overload2 data]``() const; 33627 ``[''''»''' [link beast.ref.boost__beast__static_string.data.overload2 more...]]`` 33628``` 33629[section:overload1 static_string::data (1 of 2 overloads)] 33630Returns a pointer to the first character of a string. 33631[heading Synopsis] 33632``` 33633CharT* 33634data(); 33635``` 33636 33637[heading Description] 33638[endsect] 33639[section:overload2 static_string::data (2 of 2 overloads)] 33640Returns a pointer to the first character of a string. 33641[heading Synopsis] 33642``` 33643CharT const * 33644data() const; 33645``` 33646 33647[heading Description] 33648[endsect] 33649[endsect] 33650 33651[section:difference_type static_string::difference_type] 33652[indexterm2 difference_type..static_string] 33653 33654[heading Synopsis] 33655 33656``` 33657using difference_type = std::ptrdiff_t; 33658``` 33659 33660[heading Description] 33661[endsect] 33662[section:empty static_string::empty] 33663[indexterm2 empty..static_string] 33664Returns `true` if the string is empty. 33665[heading Synopsis] 33666``` 33667bool 33668empty() const; 33669``` 33670 33671[heading Description] 33672[endsect] 33673[section:end static_string::end] 33674[indexterm2 end..static_string] 33675Returns an iterator to the end. ``` 33676iterator 33677``[link beast.ref.boost__beast__static_string.end.overload1 end]``(); 33678 ``[''''»''' [link beast.ref.boost__beast__static_string.end.overload1 more...]]`` 33679 33680const_iterator 33681``[link beast.ref.boost__beast__static_string.end.overload2 end]``() const; 33682 ``[''''»''' [link beast.ref.boost__beast__static_string.end.overload2 more...]]`` 33683``` 33684[section:overload1 static_string::end (1 of 2 overloads)] 33685Returns an iterator to the end. 33686[heading Synopsis] 33687``` 33688iterator 33689end(); 33690``` 33691 33692[heading Description] 33693[endsect] 33694[section:overload2 static_string::end (2 of 2 overloads)] 33695Returns an iterator to the end. 33696[heading Synopsis] 33697``` 33698const_iterator 33699end() const; 33700``` 33701 33702[heading Description] 33703[endsect] 33704[endsect] 33705 33706[section:erase static_string::erase] 33707[indexterm2 erase..static_string] 33708``` 33709static_string& 33710``[link beast.ref.boost__beast__static_string.erase.overload1 erase]``( 33711 size_type index = 0, 33712 size_type count = npos); 33713 ``[''''»''' [link beast.ref.boost__beast__static_string.erase.overload1 more...]]`` 33714 33715iterator 33716``[link beast.ref.boost__beast__static_string.erase.overload2 erase]``( 33717 const_iterator pos); 33718 ``[''''»''' [link beast.ref.boost__beast__static_string.erase.overload2 more...]]`` 33719 33720iterator 33721``[link beast.ref.boost__beast__static_string.erase.overload3 erase]``( 33722 const_iterator first, 33723 const_iterator last); 33724 ``[''''»''' [link beast.ref.boost__beast__static_string.erase.overload3 more...]]`` 33725``` 33726[section:overload1 static_string::erase (1 of 3 overloads)] 33727 33728[heading Synopsis] 33729``` 33730static_string& 33731erase( 33732 size_type index = 0, 33733 size_type count = npos); 33734``` 33735 33736[heading Description] 33737[endsect] 33738[section:overload2 static_string::erase (2 of 3 overloads)] 33739 33740[heading Synopsis] 33741``` 33742iterator 33743erase( 33744 const_iterator pos); 33745``` 33746 33747[heading Description] 33748[endsect] 33749[section:overload3 static_string::erase (3 of 3 overloads)] 33750 33751[heading Synopsis] 33752``` 33753iterator 33754erase( 33755 const_iterator first, 33756 const_iterator last); 33757``` 33758 33759[heading Description] 33760[endsect] 33761[endsect] 33762 33763[section:front static_string::front] 33764[indexterm2 front..static_string] 33765Accesses the first character. ``` 33766CharT& 33767``[link beast.ref.boost__beast__static_string.front.overload1 front]``(); 33768 ``[''''»''' [link beast.ref.boost__beast__static_string.front.overload1 more...]]`` 33769 33770CharT const & 33771``[link beast.ref.boost__beast__static_string.front.overload2 front]``() const; 33772 ``[''''»''' [link beast.ref.boost__beast__static_string.front.overload2 more...]]`` 33773``` 33774[section:overload1 static_string::front (1 of 2 overloads)] 33775Accesses the first character. 33776[heading Synopsis] 33777``` 33778CharT& 33779front(); 33780``` 33781 33782[heading Description] 33783[endsect] 33784[section:overload2 static_string::front (2 of 2 overloads)] 33785Accesses the first character. 33786[heading Synopsis] 33787``` 33788CharT const & 33789front() const; 33790``` 33791 33792[heading Description] 33793[endsect] 33794[endsect] 33795 33796[section:insert static_string::insert] 33797[indexterm2 insert..static_string] 33798``` 33799static_string& 33800``[link beast.ref.boost__beast__static_string.insert.overload1 insert]``( 33801 size_type index, 33802 size_type count, 33803 CharT ch); 33804 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload1 more...]]`` 33805 33806static_string& 33807``[link beast.ref.boost__beast__static_string.insert.overload2 insert]``( 33808 size_type index, 33809 CharT const* s); 33810 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload2 more...]]`` 33811 33812static_string& 33813``[link beast.ref.boost__beast__static_string.insert.overload3 insert]``( 33814 size_type index, 33815 CharT const* s, 33816 size_type count); 33817 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload3 more...]]`` 33818 33819template< 33820 std::size_t M> 33821static_string& 33822``[link beast.ref.boost__beast__static_string.insert.overload4 insert]``( 33823 size_type index, 33824 static_string< M, CharT, Traits > const& str); 33825 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload4 more...]]`` 33826 33827template< 33828 std::size_t M> 33829static_string& 33830``[link beast.ref.boost__beast__static_string.insert.overload5 insert]``( 33831 size_type index, 33832 static_string< M, CharT, Traits > const& str, 33833 size_type index_str, 33834 size_type count = npos); 33835 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload5 more...]]`` 33836 33837iterator 33838``[link beast.ref.boost__beast__static_string.insert.overload6 insert]``( 33839 const_iterator pos, 33840 CharT ch); 33841 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload6 more...]]`` 33842 33843iterator 33844``[link beast.ref.boost__beast__static_string.insert.overload7 insert]``( 33845 const_iterator pos, 33846 size_type count, 33847 CharT ch); 33848 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload7 more...]]`` 33849 33850template< 33851 class InputIt> 33852iterator 33853``[link beast.ref.boost__beast__static_string.insert.overload8 insert]``( 33854 const_iterator pos, 33855 InputIt first, 33856 InputIt last); 33857 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload8 more...]]`` 33858 33859iterator 33860``[link beast.ref.boost__beast__static_string.insert.overload9 insert]``( 33861 const_iterator pos, 33862 std::initializer_list< CharT > init); 33863 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload9 more...]]`` 33864 33865static_string& 33866``[link beast.ref.boost__beast__static_string.insert.overload10 insert]``( 33867 size_type index, 33868 string_view_type str); 33869 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload10 more...]]`` 33870 33871template< 33872 class T> 33873static_string& 33874``[link beast.ref.boost__beast__static_string.insert.overload11 insert]``( 33875 size_type index, 33876 T const& t, 33877 size_type index_str, 33878 size_type count = npos); 33879 ``[''''»''' [link beast.ref.boost__beast__static_string.insert.overload11 more...]]`` 33880``` 33881[section:overload1 static_string::insert (1 of 11 overloads)] 33882 33883[heading Synopsis] 33884``` 33885static_string& 33886insert( 33887 size_type index, 33888 size_type count, 33889 CharT ch); 33890``` 33891 33892[heading Description] 33893[endsect] 33894[section:overload2 static_string::insert (2 of 11 overloads)] 33895 33896[heading Synopsis] 33897``` 33898static_string& 33899insert( 33900 size_type index, 33901 CharT const* s); 33902``` 33903 33904[heading Description] 33905[endsect] 33906[section:overload3 static_string::insert (3 of 11 overloads)] 33907 33908[heading Synopsis] 33909``` 33910static_string& 33911insert( 33912 size_type index, 33913 CharT const* s, 33914 size_type count); 33915``` 33916 33917[heading Description] 33918[endsect] 33919[section:overload4 static_string::insert (4 of 11 overloads)] 33920 33921[heading Synopsis] 33922``` 33923template< 33924 std::size_t M> 33925static_string& 33926insert( 33927 size_type index, 33928 static_string< M, CharT, Traits > const& str); 33929``` 33930 33931[heading Description] 33932[endsect] 33933[section:overload5 static_string::insert (5 of 11 overloads)] 33934 33935[heading Synopsis] 33936``` 33937template< 33938 std::size_t M> 33939static_string& 33940insert( 33941 size_type index, 33942 static_string< M, CharT, Traits > const& str, 33943 size_type index_str, 33944 size_type count = npos); 33945``` 33946 33947[heading Description] 33948[endsect] 33949[section:overload6 static_string::insert (6 of 11 overloads)] 33950 33951[heading Synopsis] 33952``` 33953iterator 33954insert( 33955 const_iterator pos, 33956 CharT ch); 33957``` 33958 33959[heading Description] 33960[endsect] 33961[section:overload7 static_string::insert (7 of 11 overloads)] 33962 33963[heading Synopsis] 33964``` 33965iterator 33966insert( 33967 const_iterator pos, 33968 size_type count, 33969 CharT ch); 33970``` 33971 33972[heading Description] 33973[endsect] 33974[section:overload8 static_string::insert (8 of 11 overloads)] 33975 33976[heading Synopsis] 33977``` 33978template< 33979 class InputIt> 33980iterator 33981insert( 33982 const_iterator pos, 33983 InputIt first, 33984 InputIt last); 33985``` 33986 33987[heading Description] 33988[endsect] 33989[section:overload9 static_string::insert (9 of 11 overloads)] 33990 33991[heading Synopsis] 33992``` 33993iterator 33994insert( 33995 const_iterator pos, 33996 std::initializer_list< CharT > init); 33997``` 33998 33999[heading Description] 34000[endsect] 34001[section:overload10 static_string::insert (10 of 11 overloads)] 34002 34003[heading Synopsis] 34004``` 34005static_string& 34006insert( 34007 size_type index, 34008 string_view_type str); 34009``` 34010 34011[heading Description] 34012[endsect] 34013[section:overload11 static_string::insert (11 of 11 overloads)] 34014 34015[heading Synopsis] 34016``` 34017template< 34018 class T> 34019static_string& 34020insert( 34021 size_type index, 34022 T const& t, 34023 size_type index_str, 34024 size_type count = npos); 34025``` 34026 34027[heading Description] 34028[endsect] 34029[endsect] 34030 34031[section:iterator static_string::iterator] 34032[indexterm2 iterator..static_string] 34033 34034[heading Synopsis] 34035 34036``` 34037using iterator = value_type*; 34038``` 34039 34040[heading Description] 34041[endsect] 34042[section:length static_string::length] 34043[indexterm2 length..static_string] 34044Returns the number of characters, excluding the null terminator. 34045[heading Synopsis] 34046``` 34047size_type 34048length() const; 34049``` 34050 34051[heading Description] 34052[endsect] 34053[section:max_size static_string::max_size] 34054[indexterm2 max_size..static_string] 34055Returns the maximum number of characters that can be stored, excluding the null terminator. 34056[heading Synopsis] 34057``` 34058size_type constexpr 34059max_size() const; 34060``` 34061 34062[heading Description] 34063[endsect] 34064[section:max_size_n static_string::max_size_n] 34065[indexterm2 max_size_n..static_string] 34066Maximum size of the string excluding the null terminator. 34067[heading Synopsis] 34068``` 34069static 34070std::size_t constexpr max_size_n = N; 34071``` 34072 34073[heading Description] 34074[endsect] 34075[section:npos static_string::npos] 34076[indexterm2 npos..static_string] 34077A special index. 34078[heading Synopsis] 34079``` 34080static 34081constexpr size_type npos = size_type(-1); 34082``` 34083 34084[heading Description] 34085[endsect] 34086[section:operator_string_view_type static_string::operator string_view_type] 34087[indexterm2 operator string_view_type..static_string] 34088Convert a static string to a `string_view_type` 34089[heading Synopsis] 34090``` 34091operator string_view_type() const; 34092``` 34093 34094[heading Description] 34095[endsect] 34096[section:operator_plus__eq_ static_string::operator+=] 34097[indexterm2 operator+=..static_string] 34098``` 34099template< 34100 std::size_t M> 34101static_string& 34102``[link beast.ref.boost__beast__static_string.operator_plus__eq_.overload1 operator+=]``( 34103 static_string< M, CharT, Traits > const& str); 34104 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_plus__eq_.overload1 more...]]`` 34105 34106static_string& 34107``[link beast.ref.boost__beast__static_string.operator_plus__eq_.overload2 operator+=]``( 34108 CharT ch); 34109 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_plus__eq_.overload2 more...]]`` 34110 34111static_string& 34112``[link beast.ref.boost__beast__static_string.operator_plus__eq_.overload3 operator+=]``( 34113 CharT const* s); 34114 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_plus__eq_.overload3 more...]]`` 34115 34116static_string& 34117``[link beast.ref.boost__beast__static_string.operator_plus__eq_.overload4 operator+=]``( 34118 std::initializer_list< CharT > init); 34119 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_plus__eq_.overload4 more...]]`` 34120 34121static_string& 34122``[link beast.ref.boost__beast__static_string.operator_plus__eq_.overload5 operator+=]``( 34123 string_view_type const& str); 34124 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_plus__eq_.overload5 more...]]`` 34125``` 34126[section:overload1 static_string::operator+= (1 of 5 overloads)] 34127 34128[heading Synopsis] 34129``` 34130template< 34131 std::size_t M> 34132static_string& 34133operator+=( 34134 static_string< M, CharT, Traits > const& str); 34135``` 34136 34137[heading Description] 34138[endsect] 34139[section:overload2 static_string::operator+= (2 of 5 overloads)] 34140 34141[heading Synopsis] 34142``` 34143static_string& 34144operator+=( 34145 CharT ch); 34146``` 34147 34148[heading Description] 34149[endsect] 34150[section:overload3 static_string::operator+= (3 of 5 overloads)] 34151 34152[heading Synopsis] 34153``` 34154static_string& 34155operator+=( 34156 CharT const* s); 34157``` 34158 34159[heading Description] 34160[endsect] 34161[section:overload4 static_string::operator+= (4 of 5 overloads)] 34162 34163[heading Synopsis] 34164``` 34165static_string& 34166operator+=( 34167 std::initializer_list< CharT > init); 34168``` 34169 34170[heading Description] 34171[endsect] 34172[section:overload5 static_string::operator+= (5 of 5 overloads)] 34173 34174[heading Synopsis] 34175``` 34176static_string& 34177operator+=( 34178 string_view_type const& str); 34179``` 34180 34181[heading Description] 34182[endsect] 34183[endsect] 34184 34185[section:operator_eq_ static_string::operator=] 34186[indexterm2 operator=..static_string] 34187Copy assignment. ``` 34188static_string& 34189``[link beast.ref.boost__beast__static_string.operator_eq_.overload1 operator=]``( 34190 static_string const& str); 34191 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload1 more...]]`` 34192 34193template< 34194 std::size_t M> 34195static_string& 34196``[link beast.ref.boost__beast__static_string.operator_eq_.overload2 operator=]``( 34197 static_string< M, CharT, Traits > const& str); 34198 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload2 more...]]`` 34199 34200``` 34201Assign from null-terminated string. ``` 34202static_string& 34203``[link beast.ref.boost__beast__static_string.operator_eq_.overload3 operator=]``( 34204 CharT const* s); 34205 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload3 more...]]`` 34206 34207``` 34208Assign from single character. ``` 34209static_string& 34210``[link beast.ref.boost__beast__static_string.operator_eq_.overload4 operator=]``( 34211 CharT ch); 34212 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload4 more...]]`` 34213 34214``` 34215Assign from initializer list. ``` 34216static_string& 34217``[link beast.ref.boost__beast__static_string.operator_eq_.overload5 operator=]``( 34218 std::initializer_list< CharT > init); 34219 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload5 more...]]`` 34220 34221``` 34222Assign from `string_view_type`. ``` 34223static_string& 34224``[link beast.ref.boost__beast__static_string.operator_eq_.overload6 operator=]``( 34225 string_view_type sv); 34226 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_eq_.overload6 more...]]`` 34227``` 34228[section:overload1 static_string::operator= (1 of 6 overloads)] 34229Copy assignment. 34230[heading Synopsis] 34231``` 34232static_string& 34233operator=( 34234 static_string const& str); 34235``` 34236 34237[heading Description] 34238[endsect] 34239[section:overload2 static_string::operator= (2 of 6 overloads)] 34240Copy assignment. 34241[heading Synopsis] 34242``` 34243template< 34244 std::size_t M> 34245static_string& 34246operator=( 34247 static_string< M, CharT, Traits > const& str); 34248``` 34249 34250[heading Description] 34251[endsect] 34252[section:overload3 static_string::operator= (3 of 6 overloads)] 34253Assign from null-terminated string. 34254[heading Synopsis] 34255``` 34256static_string& 34257operator=( 34258 CharT const* s); 34259``` 34260 34261[heading Description] 34262[endsect] 34263[section:overload4 static_string::operator= (4 of 6 overloads)] 34264Assign from single character. 34265[heading Synopsis] 34266``` 34267static_string& 34268operator=( 34269 CharT ch); 34270``` 34271 34272[heading Description] 34273[endsect] 34274[section:overload5 static_string::operator= (5 of 6 overloads)] 34275Assign from initializer list. 34276[heading Synopsis] 34277``` 34278static_string& 34279operator=( 34280 std::initializer_list< CharT > init); 34281``` 34282 34283[heading Description] 34284[endsect] 34285[section:overload6 static_string::operator= (6 of 6 overloads)] 34286Assign from `string_view_type`. 34287[heading Synopsis] 34288``` 34289static_string& 34290operator=( 34291 string_view_type sv); 34292``` 34293 34294[heading Description] 34295[endsect] 34296[endsect] 34297 34298[section:operator_lb__rb_ static_string::operator\[\]] 34299[indexterm2 operator\[\]..static_string] 34300Access specified character. ``` 34301reference 34302``[link beast.ref.boost__beast__static_string.operator_lb__rb_.overload1 operator[]]``( 34303 size_type pos); 34304 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_lb__rb_.overload1 more...]]`` 34305 34306const_reference 34307``[link beast.ref.boost__beast__static_string.operator_lb__rb_.overload2 operator[]]``( 34308 size_type pos) const; 34309 ``[''''»''' [link beast.ref.boost__beast__static_string.operator_lb__rb_.overload2 more...]]`` 34310``` 34311[section:overload1 static_string::operator\[\] (1 of 2 overloads)] 34312Access specified character. 34313[heading Synopsis] 34314``` 34315reference 34316operator[]( 34317 size_type pos); 34318``` 34319 34320[heading Description] 34321[endsect] 34322[section:overload2 static_string::operator\[\] (2 of 2 overloads)] 34323Access specified character. 34324[heading Synopsis] 34325``` 34326const_reference 34327operator[]( 34328 size_type pos) const; 34329``` 34330 34331[heading Description] 34332[endsect] 34333[endsect] 34334 34335[section:pointer static_string::pointer] 34336[indexterm2 pointer..static_string] 34337 34338[heading Synopsis] 34339 34340``` 34341using pointer = value_type*; 34342``` 34343 34344[heading Description] 34345[endsect] 34346[section:pop_back static_string::pop_back] 34347[indexterm2 pop_back..static_string] 34348 34349[heading Synopsis] 34350``` 34351void 34352pop_back(); 34353``` 34354 34355[heading Description] 34356[endsect] 34357[section:push_back static_string::push_back] 34358[indexterm2 push_back..static_string] 34359 34360[heading Synopsis] 34361``` 34362void 34363push_back( 34364 CharT ch); 34365``` 34366 34367[heading Description] 34368[endsect] 34369[section:rbegin static_string::rbegin] 34370[indexterm2 rbegin..static_string] 34371Returns a reverse iterator to the beginning. ``` 34372reverse_iterator 34373``[link beast.ref.boost__beast__static_string.rbegin.overload1 rbegin]``(); 34374 ``[''''»''' [link beast.ref.boost__beast__static_string.rbegin.overload1 more...]]`` 34375 34376const_reverse_iterator 34377``[link beast.ref.boost__beast__static_string.rbegin.overload2 rbegin]``() const; 34378 ``[''''»''' [link beast.ref.boost__beast__static_string.rbegin.overload2 more...]]`` 34379``` 34380[section:overload1 static_string::rbegin (1 of 2 overloads)] 34381Returns a reverse iterator to the beginning. 34382[heading Synopsis] 34383``` 34384reverse_iterator 34385rbegin(); 34386``` 34387 34388[heading Description] 34389[endsect] 34390[section:overload2 static_string::rbegin (2 of 2 overloads)] 34391Returns a reverse iterator to the beginning. 34392[heading Synopsis] 34393``` 34394const_reverse_iterator 34395rbegin() const; 34396``` 34397 34398[heading Description] 34399[endsect] 34400[endsect] 34401 34402[section:reference static_string::reference] 34403[indexterm2 reference..static_string] 34404 34405[heading Synopsis] 34406 34407``` 34408using reference = value_type&; 34409``` 34410 34411[heading Description] 34412[endsect] 34413[section:rend static_string::rend] 34414[indexterm2 rend..static_string] 34415Returns a reverse iterator to the end. ``` 34416reverse_iterator 34417``[link beast.ref.boost__beast__static_string.rend.overload1 rend]``(); 34418 ``[''''»''' [link beast.ref.boost__beast__static_string.rend.overload1 more...]]`` 34419 34420const_reverse_iterator 34421``[link beast.ref.boost__beast__static_string.rend.overload2 rend]``() const; 34422 ``[''''»''' [link beast.ref.boost__beast__static_string.rend.overload2 more...]]`` 34423``` 34424[section:overload1 static_string::rend (1 of 2 overloads)] 34425Returns a reverse iterator to the end. 34426[heading Synopsis] 34427``` 34428reverse_iterator 34429rend(); 34430``` 34431 34432[heading Description] 34433[endsect] 34434[section:overload2 static_string::rend (2 of 2 overloads)] 34435Returns a reverse iterator to the end. 34436[heading Synopsis] 34437``` 34438const_reverse_iterator 34439rend() const; 34440``` 34441 34442[heading Description] 34443[endsect] 34444[endsect] 34445 34446[section:reserve static_string::reserve] 34447[indexterm2 reserve..static_string] 34448Reserves storage. 34449[heading Synopsis] 34450``` 34451void 34452reserve( 34453 std::size_t n); 34454``` 34455 34456[heading Description] 34457This actually just throws an exception if `n > N`, otherwise does nothing since the storage is fixed. [endsect] 34458[section:resize static_string::resize] 34459[indexterm2 resize..static_string] 34460Changes the number of characters stored. ``` 34461void 34462``[link beast.ref.boost__beast__static_string.resize.overload1 resize]``( 34463 std::size_t n); 34464 ``[''''»''' [link beast.ref.boost__beast__static_string.resize.overload1 more...]]`` 34465 34466void 34467``[link beast.ref.boost__beast__static_string.resize.overload2 resize]``( 34468 std::size_t n, 34469 CharT c); 34470 ``[''''»''' [link beast.ref.boost__beast__static_string.resize.overload2 more...]]`` 34471``` 34472[section:overload1 static_string::resize (1 of 2 overloads)] 34473Changes the number of characters stored. 34474[heading Synopsis] 34475``` 34476void 34477resize( 34478 std::size_t n); 34479``` 34480 34481[heading Description] 34482If the resulting string is larger, the new characters are uninitialized. [endsect] 34483[section:overload2 static_string::resize (2 of 2 overloads)] 34484Changes the number of characters stored. 34485[heading Synopsis] 34486``` 34487void 34488resize( 34489 std::size_t n, 34490 CharT c); 34491``` 34492 34493[heading Description] 34494If the resulting string is larger, the new characters are initialized to the value of `c`. [endsect] 34495[endsect] 34496 34497[section:reverse_iterator static_string::reverse_iterator] 34498[indexterm2 reverse_iterator..static_string] 34499 34500[heading Synopsis] 34501 34502``` 34503using reverse_iterator = std::reverse_iterator< iterator >; 34504``` 34505 34506[heading Description] 34507[endsect] 34508[section:shrink_to_fit static_string::shrink_to_fit] 34509[indexterm2 shrink_to_fit..static_string] 34510Reduces memory usage by freeing unused memory. 34511[heading Synopsis] 34512``` 34513void 34514shrink_to_fit(); 34515``` 34516 34517[heading Description] 34518This actually does nothing, since the storage is fixed. [endsect] 34519[section:size static_string::size] 34520[indexterm2 size..static_string] 34521Returns the number of characters, excluding the null terminator. 34522[heading Synopsis] 34523``` 34524size_type 34525size() const; 34526``` 34527 34528[heading Description] 34529[endsect] 34530[section:size_type static_string::size_type] 34531[indexterm2 size_type..static_string] 34532 34533[heading Synopsis] 34534 34535``` 34536using size_type = std::size_t; 34537``` 34538 34539[heading Description] 34540[endsect] 34541[section:static_string static_string::static_string] 34542[indexterm2 static_string..static_string] 34543Default constructor (empty string). ``` 34544``[link beast.ref.boost__beast__static_string.static_string.overload1 static_string]``(); 34545 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload1 more...]]`` 34546 34547``` 34548Construct with count copies of character `ch`. ``` 34549``[link beast.ref.boost__beast__static_string.static_string.overload2 static_string]``( 34550 size_type count, 34551 CharT ch); 34552 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload2 more...]]`` 34553 34554``` 34555Construct with a substring (pos, other.size()) of `other`. ``` 34556template< 34557 std::size_t M> 34558``[link beast.ref.boost__beast__static_string.static_string.overload3 static_string]``( 34559 static_string< M, CharT, Traits > const& other, 34560 size_type pos); 34561 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload3 more...]]`` 34562 34563``` 34564Construct with a substring (pos, count) of `other`. ``` 34565template< 34566 std::size_t M> 34567``[link beast.ref.boost__beast__static_string.static_string.overload4 static_string]``( 34568 static_string< M, CharT, Traits > const& other, 34569 size_type pos, 34570 size_type count); 34571 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload4 more...]]`` 34572 34573``` 34574Construct with the first `count` characters of `s`, including nulls. ``` 34575``[link beast.ref.boost__beast__static_string.static_string.overload5 static_string]``( 34576 CharT const* s, 34577 size_type count); 34578 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload5 more...]]`` 34579 34580``` 34581Construct from a null terminated string. ``` 34582``[link beast.ref.boost__beast__static_string.static_string.overload6 static_string]``( 34583 CharT const* s); 34584 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload6 more...]]`` 34585 34586``` 34587Construct from a range of characters. ``` 34588template< 34589 class InputIt> 34590``[link beast.ref.boost__beast__static_string.static_string.overload7 static_string]``( 34591 InputIt first, 34592 InputIt last); 34593 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload7 more...]]`` 34594 34595``` 34596Copy constructor. ``` 34597``[link beast.ref.boost__beast__static_string.static_string.overload8 static_string]``( 34598 static_string const& other); 34599 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload8 more...]]`` 34600 34601template< 34602 std::size_t M> 34603``[link beast.ref.boost__beast__static_string.static_string.overload9 static_string]``( 34604 static_string< M, CharT, Traits > const& other); 34605 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload9 more...]]`` 34606 34607``` 34608Construct from an initializer list. ``` 34609``[link beast.ref.boost__beast__static_string.static_string.overload10 static_string]``( 34610 std::initializer_list< CharT > init); 34611 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload10 more...]]`` 34612 34613``` 34614Construct from a `string_view` ``` 34615explicit 34616``[link beast.ref.boost__beast__static_string.static_string.overload11 static_string]``( 34617 string_view_type sv); 34618 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload11 more...]]`` 34619 34620``` 34621Construct from any object convertible to `string_view_type`. ``` 34622template< 34623 class T> 34624``[link beast.ref.boost__beast__static_string.static_string.overload12 static_string]``( 34625 T const& t, 34626 size_type pos, 34627 size_type n); 34628 ``[''''»''' [link beast.ref.boost__beast__static_string.static_string.overload12 more...]]`` 34629``` 34630[section:overload1 static_string::static_string (1 of 12 overloads)] 34631Default constructor (empty string). 34632[heading Synopsis] 34633``` 34634static_string(); 34635``` 34636 34637[heading Description] 34638[endsect] 34639[section:overload2 static_string::static_string (2 of 12 overloads)] 34640Construct with count copies of character `ch`. 34641[heading Synopsis] 34642``` 34643static_string( 34644 size_type count, 34645 CharT ch); 34646``` 34647 34648[heading Description] 34649The behavior is undefined if `count >= npos` [endsect] 34650[section:overload3 static_string::static_string (3 of 12 overloads)] 34651Construct with a substring (pos, other.size()) of `other`. 34652[heading Synopsis] 34653``` 34654template< 34655 std::size_t M> 34656static_string( 34657 static_string< M, CharT, Traits > const& other, 34658 size_type pos); 34659``` 34660 34661[heading Description] 34662[endsect] 34663[section:overload4 static_string::static_string (4 of 12 overloads)] 34664Construct with a substring (pos, count) of `other`. 34665[heading Synopsis] 34666``` 34667template< 34668 std::size_t M> 34669static_string( 34670 static_string< M, CharT, Traits > const& other, 34671 size_type pos, 34672 size_type count); 34673``` 34674 34675[heading Description] 34676[endsect] 34677[section:overload5 static_string::static_string (5 of 12 overloads)] 34678Construct with the first `count` characters of `s`, including nulls. 34679[heading Synopsis] 34680``` 34681static_string( 34682 CharT const* s, 34683 size_type count); 34684``` 34685 34686[heading Description] 34687[endsect] 34688[section:overload6 static_string::static_string (6 of 12 overloads)] 34689Construct from a null terminated string. 34690[heading Synopsis] 34691``` 34692static_string( 34693 CharT const* s); 34694``` 34695 34696[heading Description] 34697[endsect] 34698[section:overload7 static_string::static_string (7 of 12 overloads)] 34699Construct from a range of characters. 34700[heading Synopsis] 34701``` 34702template< 34703 class InputIt> 34704static_string( 34705 InputIt first, 34706 InputIt last); 34707``` 34708 34709[heading Description] 34710[endsect] 34711[section:overload8 static_string::static_string (8 of 12 overloads)] 34712Copy constructor. 34713[heading Synopsis] 34714``` 34715static_string( 34716 static_string const& other); 34717``` 34718 34719[heading Description] 34720[endsect] 34721[section:overload9 static_string::static_string (9 of 12 overloads)] 34722Copy constructor. 34723[heading Synopsis] 34724``` 34725template< 34726 std::size_t M> 34727static_string( 34728 static_string< M, CharT, Traits > const& other); 34729``` 34730 34731[heading Description] 34732[endsect] 34733[section:overload10 static_string::static_string (10 of 12 overloads)] 34734Construct from an initializer list. 34735[heading Synopsis] 34736``` 34737static_string( 34738 std::initializer_list< CharT > init); 34739``` 34740 34741[heading Description] 34742[endsect] 34743[section:overload11 static_string::static_string (11 of 12 overloads)] 34744Construct from a `string_view` 34745[heading Synopsis] 34746``` 34747static_string( 34748 string_view_type sv); 34749``` 34750 34751[heading Description] 34752[endsect] 34753[section:overload12 static_string::static_string (12 of 12 overloads)] 34754Construct from any object convertible to `string_view_type`. 34755[heading Synopsis] 34756``` 34757template< 34758 class T> 34759static_string( 34760 T const& t, 34761 size_type pos, 34762 size_type n); 34763``` 34764 34765[heading Description] 34766The range (pos, n) is extracted from the value obtained by converting `t` to `string_view_type`, and used to construct the string. [endsect] 34767[endsect] 34768 34769[section:string_view_type static_string::string_view_type] 34770[indexterm2 string_view_type..static_string] 34771The type of `string_view` returned by the interface. 34772[heading Synopsis] 34773 34774``` 34775using string_view_type = basic_string_view< CharT, Traits >; 34776``` 34777 34778[heading Description] 34779[endsect] 34780[section:substr static_string::substr] 34781[indexterm2 substr..static_string] 34782 34783[heading Synopsis] 34784``` 34785string_view_type 34786substr( 34787 size_type pos = 0, 34788 size_type count = npos) const; 34789``` 34790 34791[heading Description] 34792[endsect] 34793[section:swap static_string::swap] 34794[indexterm2 swap..static_string] 34795Exchange the contents of this string with another. ``` 34796void 34797``[link beast.ref.boost__beast__static_string.swap.overload1 swap]``( 34798 static_string& str); 34799 ``[''''»''' [link beast.ref.boost__beast__static_string.swap.overload1 more...]]`` 34800 34801template< 34802 std::size_t M> 34803void 34804``[link beast.ref.boost__beast__static_string.swap.overload2 swap]``( 34805 static_string< M, CharT, Traits >& str); 34806 ``[''''»''' [link beast.ref.boost__beast__static_string.swap.overload2 more...]]`` 34807``` 34808[section:overload1 static_string::swap (1 of 2 overloads)] 34809Exchange the contents of this string with another. 34810[heading Synopsis] 34811``` 34812void 34813swap( 34814 static_string& str); 34815``` 34816 34817[heading Description] 34818[endsect] 34819[section:overload2 static_string::swap (2 of 2 overloads)] 34820Exchange the contents of this string with another. 34821[heading Synopsis] 34822``` 34823template< 34824 std::size_t M> 34825void 34826swap( 34827 static_string< M, CharT, Traits >& str); 34828``` 34829 34830[heading Description] 34831[endsect] 34832[endsect] 34833 34834[section:traits_type static_string::traits_type] 34835[indexterm2 traits_type..static_string] 34836 34837[heading Synopsis] 34838 34839``` 34840using traits_type = Traits; 34841``` 34842 34843[heading Description] 34844[endsect] 34845[section:value_type static_string::value_type] 34846[indexterm2 value_type..static_string] 34847 34848[heading Synopsis] 34849 34850``` 34851using value_type = typename Traits::char_type; 34852``` 34853 34854[heading Description] 34855[endsect] 34856 34857 34858 34859Convenience header [include_file boost/beast/core.hpp] 34860 34861[endsect] 34862 34863 34864 34865[section:boost__beast__string_param string_param] 34866A function parameter which efficiently converts to string. 34867[heading Synopsis] 34868 34869Defined in header [include_file boost/beast/core/string_param.hpp] 34870 34871 34872 34873``` 34874class string_param 34875``` 34876[heading Member Functions] 34877[table [[Name][Description]] 34878 [ 34879 [[link beast.ref.boost__beast__string_param.operator_string_view_const [*operator string_view const]]] 34880 [ 34881 Implicit conversion to string_view. 34882 ] 34883 ] 34884 [ 34885 [[link beast.ref.boost__beast__string_param.operator_eq_ [*operator=]]] 34886 [ 34887 Copy assignment (disallowed) 34888 ] 34889 ] 34890 [ 34891 [[link beast.ref.boost__beast__string_param.str [*str]]] 34892 [ 34893 Returns the contained string. 34894 ] 34895 ] 34896 [ 34897 [[link beast.ref.boost__beast__string_param.string_param [*string_param]]] 34898 [ 34899 Copy constructor (disallowed) 34900 34901 Constructor. 34902 ] 34903 ] 34904] 34905 34906[heading Description] 34907This is used as a function parameter type to allow callers notational convenience: objects other than strings may be passed in contexts where a string is expected. The conversion to string is made using `operator<<` to a non-dynamically allocated static buffer if possible, else to a `std::string` on overflow. 34908To use it, modify your function signature to accept `string_param` and then extract the string inside the function: 34909``` 34910 void print(string_param s) 34911 { 34912 std::cout << s.str(); 34913 } 34914``` 34915[section:operator_string_view_const string_param::operator string_view const] 34916[indexterm2 operator string_view const..string_param] 34917Implicit conversion to [link beast.ref.boost__beast__string_view `string_view`]. 34918[heading Synopsis] 34919``` 34920operator string_view const() const; 34921``` 34922 34923[heading Description] 34924[endsect] 34925[section:operator_eq_ string_param::operator=] 34926[indexterm2 operator=..string_param] 34927Copy assignment (disallowed) 34928[heading Synopsis] 34929``` 34930string_param& 34931operator=( 34932 string_param const&); 34933``` 34934 34935[heading Description] 34936[endsect] 34937[section:str string_param::str] 34938[indexterm2 str..string_param] 34939Returns the contained string. 34940[heading Synopsis] 34941``` 34942string_view 34943str() const; 34944``` 34945 34946[heading Description] 34947[endsect] 34948[section:string_param string_param::string_param] 34949[indexterm2 string_param..string_param] 34950Copy constructor (disallowed) ``` 34951``[link beast.ref.boost__beast__string_param.string_param.overload1 string_param]``( 34952 string_param const&); 34953 ``[''''»''' [link beast.ref.boost__beast__string_param.string_param.overload1 more...]]`` 34954 34955``` 34956Constructor. ``` 34957template< 34958 class... Args> 34959``[link beast.ref.boost__beast__string_param.string_param.overload2 string_param]``( 34960 Args const&... args); 34961 ``[''''»''' [link beast.ref.boost__beast__string_param.string_param.overload2 more...]]`` 34962``` 34963[section:overload1 string_param::string_param (1 of 2 overloads)] 34964Copy constructor (disallowed) 34965[heading Synopsis] 34966``` 34967string_param( 34968 string_param const&); 34969``` 34970 34971[heading Description] 34972[endsect] 34973[section:overload2 string_param::string_param (2 of 2 overloads)] 34974Constructor. 34975[heading Synopsis] 34976``` 34977template< 34978 class... Args> 34979string_param( 34980 Args const&... args); 34981``` 34982 34983[heading Description] 34984This function constructs a string as if by concatenating the result of streaming each argument in order into an output stream. It is used as a notational convenience at call sites which expect a parameter with the semantics of a [link beast.ref.boost__beast__string_view `string_view`]. 34985The implementation uses a small, internal static buffer to avoid memory allocations especially for the case where the list of arguments to be converted consists of a single integral type. 34986[heading Parameters] 34987[table [[Name][Description]] 34988 [[`args`][ 34989 34990One or more arguments to convert 34991 ]] 34992] 34993[endsect] 34994[endsect] 34995 34996 34997 34998 34999Convenience header [include_file boost/beast/core.hpp] 35000 35001[endsect] 35002 35003 35004 35005[section:boost__beast__string_view string_view] 35006[indexterm1 string_view] 35007The type of string view used by the library. 35008[heading Synopsis] 35009 35010Defined in header [include_file boost/beast/core/string_type.hpp] 35011 35012 35013 35014``` 35015using string_view = boost::string_view; 35016``` 35017 35018[heading Description] 35019 35020 35021 35022Convenience header [include_file boost/beast/core.hpp] 35023 35024[endsect] 35025[section:boost__beast__swap swap] 35026[indexterm1 swap] 35027``` 35028template< 35029 std::size_t N, 35030 class CharT, 35031 class Traits> 35032void 35033``[link beast.ref.boost__beast__swap.overload1 swap]``( 35034 static_string< N, CharT, Traits >& lhs, 35035 static_string< N, CharT, Traits >& rhs); 35036 ``[''''»''' [link beast.ref.boost__beast__swap.overload1 more...]]`` 35037 35038template< 35039 std::size_t N, 35040 std::size_t M, 35041 class CharT, 35042 class Traits> 35043void 35044``[link beast.ref.boost__beast__swap.overload2 swap]``( 35045 static_string< N, CharT, Traits >& lhs, 35046 static_string< M, CharT, Traits >& rhs); 35047 ``[''''»''' [link beast.ref.boost__beast__swap.overload2 more...]]`` 35048``` 35049[section:overload1 swap (1 of 2 overloads)] 35050 35051[heading Synopsis] 35052 35053Defined in header [include_file boost/beast/core/static_string.hpp] 35054 35055 35056 35057``` 35058template< 35059 std::size_t N, 35060 class CharT, 35061 class Traits> 35062void 35063swap( 35064 static_string< N, CharT, Traits >& lhs, 35065 static_string< N, CharT, Traits >& rhs); 35066 35067``` 35068 35069[heading Description] 35070 35071 35072 35073Convenience header [include_file boost/beast/core.hpp] 35074 35075[endsect] 35076[section:overload2 swap (2 of 2 overloads)] 35077 35078[heading Synopsis] 35079 35080Defined in header [include_file boost/beast/core/static_string.hpp] 35081 35082 35083 35084``` 35085template< 35086 std::size_t N, 35087 std::size_t M, 35088 class CharT, 35089 class Traits> 35090void 35091swap( 35092 static_string< N, CharT, Traits >& lhs, 35093 static_string< M, CharT, Traits >& rhs); 35094 35095``` 35096 35097[heading Description] 35098 35099 35100 35101Convenience header [include_file boost/beast/core.hpp] 35102 35103[endsect] 35104[endsect] 35105 35106 35107 35108[section:boost__beast__system_category system_category] 35109[indexterm1 system_category] 35110A function to return the system error category used by the library. 35111[heading Synopsis] 35112 35113Defined in header [include_file boost/beast/core/error.hpp] 35114 35115 35116 35117``` 35118error_category const & 35119system_category(); 35120 35121``` 35122 35123[heading Description] 35124 35125 35126 35127Convenience header [include_file boost/beast/core.hpp] 35128 35129[endsect] 35130[section:boost__beast__system_error system_error] 35131[indexterm1 system_error] 35132The type of system error thrown by the library. 35133[heading Synopsis] 35134 35135Defined in header [include_file boost/beast/core/error.hpp] 35136 35137 35138 35139``` 35140using system_error = boost::system::system_error; 35141``` 35142 35143[heading Description] 35144 35145 35146 35147Convenience header [include_file boost/beast/core.hpp] 35148 35149[endsect] 35150[section:boost__beast__tcp_stream tcp_stream] 35151[indexterm1 tcp_stream] 35152A TCP/IP stream socket with timeouts and a polymorphic executor. 35153[heading Synopsis] 35154 35155Defined in header [include_file boost/beast/core/tcp_stream.hpp] 35156 35157 35158 35159``` 35160using tcp_stream = basic_stream< net::ip::tcp, net::executor, unlimited_rate_policy >; 35161``` 35162[heading Types] 35163[table [[Name][Description]] 35164 [ 35165 [[link beast.ref.boost__beast__basic_stream__rebind_executor [*rebind_executor]]] 35166 [ 35167 Rebinds the stream type to another executor. 35168 ] 35169 ] 35170 [ 35171 [[link beast.ref.boost__beast__basic_stream.endpoint_type [*endpoint_type]]] 35172 [ 35173 The endpoint type. 35174 ] 35175 ] 35176 [ 35177 [[link beast.ref.boost__beast__basic_stream.executor_type [*executor_type]]] 35178 [ 35179 The type of the executor associated with the stream. 35180 ] 35181 ] 35182 [ 35183 [[link beast.ref.boost__beast__basic_stream.protocol_type [*protocol_type]]] 35184 [ 35185 The protocol type. 35186 ] 35187 ] 35188 [ 35189 [[link beast.ref.boost__beast__basic_stream.socket_type [*socket_type]]] 35190 [ 35191 The type of the underlying socket. 35192 ] 35193 ] 35194] 35195[heading Member Functions] 35196[table [[Name][Description]] 35197 [ 35198 [[link beast.ref.boost__beast__basic_stream.async_connect [*async_connect]]] 35199 [ 35200 Connect the stream to the specified endpoint asynchronously. 35201 35202 Establishes a connection by trying each endpoint in a sequence asynchronously. 35203 ] 35204 ] 35205 [ 35206 [[link beast.ref.boost__beast__basic_stream.async_read_some [*async_read_some]]] 35207 [ 35208 Read some data asynchronously. 35209 ] 35210 ] 35211 [ 35212 [[link beast.ref.boost__beast__basic_stream.async_write_some [*async_write_some]]] 35213 [ 35214 Write some data asynchronously. 35215 ] 35216 ] 35217 [ 35218 [[link beast.ref.boost__beast__basic_stream.basic_stream [*basic_stream]]] 35219 [ 35220 Constructor. 35221 35222 Move constructor. 35223 ] 35224 ] 35225 [ 35226 [[link beast.ref.boost__beast__basic_stream.cancel [*cancel]]] 35227 [ 35228 Cancel all asynchronous operations associated with the socket. 35229 ] 35230 ] 35231 [ 35232 [[link beast.ref.boost__beast__basic_stream.close [*close]]] 35233 [ 35234 Close the timed stream. 35235 ] 35236 ] 35237 [ 35238 [[link beast.ref.boost__beast__basic_stream.connect [*connect]]] 35239 [ 35240 Connect the stream to the specified endpoint. 35241 35242 Establishes a connection by trying each endpoint in a sequence. 35243 ] 35244 ] 35245 [ 35246 [[link beast.ref.boost__beast__basic_stream.expires_after [*expires_after]]] 35247 [ 35248 Set the timeout for the next logical operation. 35249 ] 35250 ] 35251 [ 35252 [[link beast.ref.boost__beast__basic_stream.expires_at [*expires_at]]] 35253 [ 35254 Set the timeout for the next logical operation. 35255 ] 35256 ] 35257 [ 35258 [[link beast.ref.boost__beast__basic_stream.expires_never [*expires_never]]] 35259 [ 35260 Disable the timeout for the next logical operation. 35261 ] 35262 ] 35263 [ 35264 [[link beast.ref.boost__beast__basic_stream.get_executor [*get_executor]]] 35265 [ 35266 Get the executor associated with the object. 35267 ] 35268 ] 35269 [ 35270 [[link beast.ref.boost__beast__basic_stream.operator_eq_ [*operator=]]] 35271 [ 35272 Move assignment (deleted). 35273 ] 35274 ] 35275 [ 35276 [[link beast.ref.boost__beast__basic_stream.rate_policy [*rate_policy]]] 35277 [ 35278 Returns the rate policy associated with the object. 35279 ] 35280 ] 35281 [ 35282 [[link beast.ref.boost__beast__basic_stream.read_some [*read_some]]] 35283 [ 35284 Read some data. 35285 ] 35286 ] 35287 [ 35288 [[link beast.ref.boost__beast__basic_stream.release_socket [*release_socket]]] 35289 [ 35290 Release ownership of the underlying socket. 35291 ] 35292 ] 35293 [ 35294 [[link beast.ref.boost__beast__basic_stream.socket [*socket]]] 35295 [ 35296 Return a reference to the underlying socket. 35297 ] 35298 ] 35299 [ 35300 [[link beast.ref.boost__beast__basic_stream.write_some [*write_some]]] 35301 [ 35302 Write some data. 35303 ] 35304 ] 35305 [ 35306 [[link beast.ref.boost__beast__basic_stream.basic_stream_dtor_ [*~basic_stream]]] 35307 [ 35308 Destructor. 35309 ] 35310 ] 35311] 35312This stream wraps a `net::basic_stream_socket` to provide the following features: 35313 35314* An ['Executor] may be associated with the stream, which will be used to invoke any completion handlers which do not already have an associated executor. This achieves support for [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 35315 35316 35317* Timeouts may be specified for each logical asynchronous operation performing any reading, writing, or connecting. 35318 35319 35320* A ['RatePolicy] may be associated with the stream, to implement rate limiting through the policy's interface. 35321 35322Although the stream supports multiple concurrent outstanding asynchronous operations, the stream object is not thread-safe. The caller is responsible for ensuring that the stream is accessed from only one thread at a time. This includes the times when the stream, and its underlying socket, are accessed by the networking implementation. To meet this thread safety requirement, all asynchronous operations must be performed by the stream within the same implicit strand (only one thread `net::io_context::run`) or within the same explicit strand, such as an instance of `net::strand`. 35323Completion handlers with explicit associated executors (such as those arising from use of `net::bind_executor`) will be invoked by the stream using the associated executor. Otherwise, the completion handler will be invoked by the executor associated with the stream upon construction. The type of executor used with this stream must meet the following requirements: 35324 35325* Function objects submitted to the executor shall never run concurrently with each other. 35326 35327The executor type `net::strand` meets these requirements. Use of a strand as the executor in the stream class template offers an additional notational convenience: the strand does not need to be specified in each individual initiating function call. 35328Unlike other stream wrappers, the underlying socket is accessed through the [link beast.ref.boost__beast__basic_stream.socket `basic_stream::socket`] member function instead of `next_layer`. This causes the [link beast.ref.boost__beast__basic_stream `basic_stream`] to be returned in calls to [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]. 35329[heading Usage] 35330 35331To use this stream declare an instance of the class. Then, before each logical operation for which a timeout is desired, call [link beast.ref.boost__beast__basic_stream.expires_after `basic_stream::expires_after`] with a duration, or call [link beast.ref.boost__beast__basic_stream.expires_at `basic_stream::expires_at`] with a time point. Alternatively, call [link beast.ref.boost__beast__basic_stream.expires_never `basic_stream::expires_never`] to disable the timeout for subsequent logical operations. A logical operation is any series of one or more direct or indirect calls to the timeout stream's asynchronous read, asynchronous write, or asynchronous connect functions. 35332When a timeout is set and a mixed operation is performed (one that includes both reads and writes, for example) the timeout applies to all of the intermediate asynchronous operations used in the enclosing operation. This allows timeouts to be applied to stream algorithms which were not written specifically to allow for timeouts, when those algorithms are passed a timeout stream with a timeout set. 35333When a timeout occurs the socket will be closed, canceling any pending I/O operations. The completion handlers for these canceled operations will be invoked with the error [link beast.ref.boost__beast__error `timeout`]. 35334[heading Examples] 35335 35336This function reads an HTTP request with a timeout, then sends the HTTP response with a different timeout. 35337 35338``` 35339 void process_http_1 (tcp_stream& stream, net::yield_context yield) 35340 { 35341 flat_buffer buffer; 35342 http::request<http::empty_body> req; 35343 35344 // Read the request, with a 15 second timeout 35345 stream.expires_after(std::chrono::seconds(15)); 35346 http::async_read(stream, buffer, req, yield); 35347 35348 // Calculate the response 35349 http::response<http::string_body> res = make_response(req); 35350 35351 // Send the response, with a 30 second timeout. 35352 stream.expires_after (std::chrono::seconds(30)); 35353 http::async_write (stream, res, yield); 35354 } 35355``` 35356The example above could be expressed using a single timeout with a simple modification. The function that follows first reads an HTTP request then sends the HTTP response, with a single timeout that applies to the entire combined operation of reading and writing: 35357 35358``` 35359 void process_http_2 (tcp_stream& stream, net::yield_context yield) 35360 { 35361 flat_buffer buffer; 35362 http::request<http::empty_body> req; 35363 35364 // Require that the read and write combined take no longer than 30 seconds 35365 stream.expires_after(std::chrono::seconds(30)); 35366 35367 http::async_read(stream, buffer, req, yield); 35368 35369 http::response<http::string_body> res = make_response(req); 35370 http::async_write (stream, res, yield); 35371 } 35372``` 35373Some stream algorithms, such as `ssl::stream::async_handshake` perform both reads and writes. A timeout set before calling the initiating function of such composite stream algorithms will apply to the entire composite operation. For example, a timeout may be set on performing the SSL handshake thusly: 35374 35375``` 35376 void do_ssl_handshake (net::ssl::stream<tcp_stream>& stream, net::yield_context yield) 35377 { 35378 // Require that the SSL handshake take no longer than 10 seconds 35379 stream.expires_after(std::chrono::seconds(10)); 35380 35381 stream.async_handshake(net::ssl::stream_base::client, yield); 35382 } 35383``` 35384[heading Blocking I/O] 35385 35386Synchronous functions behave identically as that of the wrapped `net::basic_stream_socket`. Timeouts are not available when performing blocking calls. 35387[heading Template Parameters] 35388[table [[Type][Description]] 35389 [[`Protocol`][ 35390 35391A type meeting the requirements of ['Protocol] representing the protocol the protocol to use for the basic stream socket. A common choice is `net::ip::tcp`. 35392 ]] 35393 [[`Executor`][ 35394 35395A type meeting the requirements of ['Executor] to be used for submitting all completion handlers which do not already have an associated executor. If this type is omitted, the default of `net::executor` will be used. 35396 ]] 35397] 35398[heading Thread Safety] 35399['Distinct objects]: Safe. 35400 35401['Shared objects]: Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 35402[heading See Also] 35403 35404 35405* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1322r0.html [P1322R0] Networking TS enhancement to enable custom I/O executors]. 35406 35407 35408[heading Description] 35409[heading See Also] 35410[link beast.ref.boost__beast__basic_stream `basic_stream`] 35411 35412 35413 35414Convenience header [include_file boost/beast/core.hpp] 35415 35416[endsect] 35417[section:boost__beast__teardown teardown] 35418[indexterm1 teardown] 35419Tear down a `net::ssl::stream`. 35420[heading Synopsis] 35421 35422Defined in header [include_file boost/beast/websocket/ssl.hpp] 35423 35424 35425 35426``` 35427template< 35428 class __SyncStream__> 35429void 35430teardown( 35431 role_type role, 35432 net::ssl::stream< SyncStream >& stream, 35433 error_code& ec); 35434 35435``` 35436 35437[heading Description] 35438This tears down a connection. The implementation will call the overload of this function based on the `Stream` parameter used to consruct the socket. When `Stream` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 35439[heading Parameters] 35440[table [[Name][Description]] 35441 [[`role`][ 35442 35443The role of the local endpoint 35444 ]] 35445 [[`stream`][ 35446 35447The stream to tear down. 35448 ]] 35449 [[`ec`][ 35450 35451Set to the error if any occurred. 35452 ]] 35453] 35454 35455 35456 35457Convenience header [include_file boost/beast/websocket.hpp] 35458 35459[endsect] 35460[section:boost__beast__test__any_handler test::any_handler] 35461[indexterm1 test::any_handler] 35462Return a test CompletionHandler which requires invocation. 35463[heading Synopsis] 35464 35465Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 35466 35467 35468 35469``` 35470handler 35471any_handler(); 35472 35473``` 35474 35475[heading Description] 35476The returned handler can be invoked with any signature. The handler fails the test if: 35477 35478* The handler is destroyed without being invoked. 35479 35480 35481 35482[endsect] 35483[section:boost__beast__test__connect test::connect] 35484[indexterm1 test::connect] 35485Return a new stream connected to the given stream. ``` 35486template< 35487 class... Args> 35488stream 35489``[link beast.ref.boost__beast__test__connect.overload1 connect]``( 35490 stream& to, 35491 Args&&... args); 35492 ``[''''»''' [link beast.ref.boost__beast__test__connect.overload1 more...]]`` 35493 35494``` 35495Connect two TCP sockets together. ``` 35496template< 35497 class __Executor__> 35498bool 35499``[link beast.ref.boost__beast__test__connect.overload2 connect]``( 35500 net::basic_stream_socket< net::ip::tcp, Executor >& s1, 35501 net::basic_stream_socket< net::ip::tcp, Executor >& s2); 35502 ``[''''»''' [link beast.ref.boost__beast__test__connect.overload2 more...]]`` 35503``` 35504[section:overload1 test::connect (1 of 2 overloads)] 35505Return a new stream connected to the given stream. 35506[heading Synopsis] 35507 35508Defined in header [include_file boost/beast/_experimental/test/stream.hpp] 35509 35510 35511 35512``` 35513template< 35514 class... Args> 35515stream 35516connect( 35517 stream& to, 35518 Args&&... args); 35519 35520``` 35521 35522[heading Description] 35523[heading Parameters] 35524[table [[Name][Description]] 35525 [[`to`][ 35526 35527The stream to connect to. 35528 ]] 35529 [[`args`][ 35530 35531Optional arguments forwarded to the new stream's constructor. 35532 ]] 35533] 35534[heading Return Value] 35535The new, connected stream. 35536 35537 35538[endsect] 35539[section:overload2 test::connect (2 of 2 overloads)] 35540Connect two TCP sockets together. 35541[heading Synopsis] 35542 35543Defined in header [include_file boost/beast/_experimental/test/tcp.hpp] 35544 35545 35546 35547``` 35548template< 35549 class __Executor__> 35550bool 35551connect( 35552 net::basic_stream_socket< net::ip::tcp, Executor >& s1, 35553 net::basic_stream_socket< net::ip::tcp, Executor >& s2); 35554 35555``` 35556 35557[heading Description] 35558 35559 35560[endsect] 35561[endsect] 35562 35563 35564 35565[section:boost__beast__test__error test::error] 35566[indexterm1 test::error] 35567Error codes returned from unit testing algorithms. 35568[heading Synopsis] 35569 35570Defined in header [include_file boost/beast/_experimental/test/error.hpp] 35571 35572 35573``` 35574enum error 35575``` 35576 35577[indexterm2 test_failure..test::error] 35578[heading Values] 35579[table [[Name][Description]] 35580 [[[^test_failure]][The test stream generated a simulated testing error. 35581 35582This error is returned by a @ref fail_count object 35583when it generates a simulated error. 35584 ]] 35585] 35586 35587[heading Description] 35588 35589 35590[endsect] 35591[section:boost__beast__test__fail_count test::fail_count] 35592A countdown to simulated failure. 35593[heading Synopsis] 35594 35595Defined in header [include_file boost/beast/_experimental/test/fail_count.hpp] 35596 35597 35598 35599``` 35600class fail_count 35601``` 35602[heading Member Functions] 35603[table [[Name][Description]] 35604 [ 35605 [[link beast.ref.boost__beast__test__fail_count.fail [*fail]]] 35606 [ 35607 Throw an exception on the Nth failure. 35608 35609 Set an error code on the Nth failure. 35610 ] 35611 ] 35612 [ 35613 [[link beast.ref.boost__beast__test__fail_count.fail_count [*fail_count]]] 35614 [ 35615 35616 35617 Construct a counter. 35618 ] 35619 ] 35620] 35621 35622[heading Description] 35623On the Nth operation, the class will fail with the specified error code, or the default error code of [link beast.ref.boost__beast__test__error `test::test_failure`]. 35624Instances of this class may be used to build objects which are specifically designed to aid in writing unit tests, for interfaces which can throw exceptions or return `error_code` values representing failure. [section:fail test::fail_count::fail] 35625[indexterm2 fail..test::fail_count] 35626Throw an exception on the Nth failure. ``` 35627void 35628``[link beast.ref.boost__beast__test__fail_count.fail.overload1 fail]``(); 35629 ``[''''»''' [link beast.ref.boost__beast__test__fail_count.fail.overload1 more...]]`` 35630 35631``` 35632Set an error code on the Nth failure. ``` 35633bool 35634``[link beast.ref.boost__beast__test__fail_count.fail.overload2 fail]``( 35635 error_code& ec); 35636 ``[''''»''' [link beast.ref.boost__beast__test__fail_count.fail.overload2 more...]]`` 35637``` 35638[section:overload1 test::fail_count::fail (1 of 2 overloads)] 35639Throw an exception on the Nth failure. 35640[heading Synopsis] 35641``` 35642void 35643fail(); 35644``` 35645 35646[heading Description] 35647[endsect] 35648[section:overload2 test::fail_count::fail (2 of 2 overloads)] 35649Set an error code on the Nth failure. 35650[heading Synopsis] 35651``` 35652bool 35653fail( 35654 error_code& ec); 35655``` 35656 35657[heading Description] 35658[endsect] 35659[endsect] 35660 35661[section:fail_count test::fail_count::fail_count] 35662[indexterm2 fail_count..test::fail_count] 35663``` 35664``[link beast.ref.boost__beast__test__fail_count.fail_count.overload1 fail_count]``( 35665 fail_count&&); 35666 ``[''''»''' [link beast.ref.boost__beast__test__fail_count.fail_count.overload1 more...]]`` 35667 35668``` 35669Construct a counter. ``` 35670explicit 35671``[link beast.ref.boost__beast__test__fail_count.fail_count.overload2 fail_count]``( 35672 std::size_t n, 35673 error_code ev = error::test_failure); 35674 ``[''''»''' [link beast.ref.boost__beast__test__fail_count.fail_count.overload2 more...]]`` 35675``` 35676[section:overload1 test::fail_count::fail_count (1 of 2 overloads)] 35677 35678[heading Synopsis] 35679``` 35680fail_count( 35681 fail_count&&); 35682``` 35683 35684[heading Description] 35685[endsect] 35686[section:overload2 test::fail_count::fail_count (2 of 2 overloads)] 35687Construct a counter. 35688[heading Synopsis] 35689``` 35690fail_count( 35691 std::size_t n, 35692 error_code ev = error::test_failure); 35693``` 35694 35695[heading Description] 35696[heading Parameters] 35697[table [[Name][Description]] 35698 [[`n`][ 35699 35700The 0-based index of the operation to fail on or after 35701 ]] 35702 [[`ev`][ 35703 35704An optional error code to use when generating a simulated failure 35705 ]] 35706] 35707[endsect] 35708[endsect] 35709 35710 35711 35712[endsect] 35713 35714 35715 35716[section:boost__beast__test__fail_handler test::fail_handler] 35717[indexterm1 test::fail_handler] 35718Return a test CompletionHandler which requires a specific error code. 35719[heading Synopsis] 35720 35721Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 35722 35723 35724 35725``` 35726handler 35727fail_handler( 35728 error_code ec); 35729 35730``` 35731 35732[heading Description] 35733This handler can be invoked with any signature whose first parameter is an `error_code`. The handler fails the test if: 35734 35735* The handler is destroyed without being invoked. 35736 35737 35738* The handler is invoked with an error code different from what is specified. 35739 35740[heading Parameters] 35741[table [[Name][Description]] 35742 [[`ec`][ 35743 35744The error code to specify. 35745 ]] 35746] 35747 35748 35749[endsect] 35750[section:boost__beast__test__handler test::handler] 35751A CompletionHandler used for testing. 35752[heading Synopsis] 35753 35754Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 35755 35756 35757 35758``` 35759class handler 35760``` 35761[heading Member Functions] 35762[table [[Name][Description]] 35763 [ 35764 [[link beast.ref.boost__beast__test__handler.handler [*handler]]] 35765 [ 35766 35767 ] 35768 ] 35769 [ 35770 [[link beast.ref.boost__beast__test__handler.operator_lp__rp_ [*operator()]]] 35771 [ 35772 35773 ] 35774 ] 35775 [ 35776 [[link beast.ref.boost__beast__test__handler.handler_dtor_ [*~handler]]] 35777 [ 35778 35779 ] 35780 ] 35781] 35782 35783[heading Description] 35784This completion handler is used by tests to ensure correctness of behavior. It is designed as a single type to reduce template instantiations, with configurable settings through constructor arguments. Typically this type will be used in type lists and not instantiated directly; instances of this class are returned by the helper functions listed below. 35785[heading See Also] 35786[link beast.ref.boost__beast__test__success_handler `test::success_handler`], [link beast.ref.boost__beast__test__fail_handler `test::fail_handler`], [link beast.ref.boost__beast__test__any_handler `test::any_handler`] 35787[section:handler test::handler::handler] 35788[indexterm2 handler..test::handler] 35789``` 35790``[link beast.ref.boost__beast__test__handler.handler.overload1 handler]``(); 35791 ``[''''»''' [link beast.ref.boost__beast__test__handler.handler.overload1 more...]]`` 35792 35793explicit 35794``[link beast.ref.boost__beast__test__handler.handler.overload2 handler]``( 35795 error_code ec); 35796 ``[''''»''' [link beast.ref.boost__beast__test__handler.handler.overload2 more...]]`` 35797 35798explicit 35799``[link beast.ref.boost__beast__test__handler.handler.overload3 handler]``( 35800 boost::none_t); 35801 ``[''''»''' [link beast.ref.boost__beast__test__handler.handler.overload3 more...]]`` 35802 35803``[link beast.ref.boost__beast__test__handler.handler.overload4 handler]``( 35804 handler&& other); 35805 ``[''''»''' [link beast.ref.boost__beast__test__handler.handler.overload4 more...]]`` 35806``` 35807[section:overload1 test::handler::handler (1 of 4 overloads)] 35808 35809[heading Synopsis] 35810``` 35811handler(); 35812``` 35813 35814[heading Description] 35815[endsect] 35816[section:overload2 test::handler::handler (2 of 4 overloads)] 35817 35818[heading Synopsis] 35819``` 35820handler( 35821 error_code ec); 35822``` 35823 35824[heading Description] 35825[endsect] 35826[section:overload3 test::handler::handler (3 of 4 overloads)] 35827 35828[heading Synopsis] 35829``` 35830handler( 35831 boost::none_t); 35832``` 35833 35834[heading Description] 35835[endsect] 35836[section:overload4 test::handler::handler (4 of 4 overloads)] 35837 35838[heading Synopsis] 35839``` 35840handler( 35841 handler&& other); 35842``` 35843 35844[heading Description] 35845[endsect] 35846[endsect] 35847 35848[section:operator_lp__rp_ test::handler::operator()] 35849[indexterm2 operator()..test::handler] 35850``` 35851template< 35852 class... Args> 35853void 35854``[link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload1 operator()]``( 35855 error_code ec, 35856 Args&& ...); 35857 ``[''''»''' [link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload1 more...]]`` 35858 35859void 35860``[link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload2 operator()]``(); 35861 ``[''''»''' [link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload2 more...]]`` 35862 35863template< 35864 class Arg0, 35865 class... Args, 35866 [role red error.class-detail-template.1][role red error.class-detail-template.2] = typename std::enable_if< ! std::is_convertible<Arg0, error_code>::value>::type> 35867void 35868``[link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload3 operator()]``( 35869 Arg0&&, 35870 Args&& ...); 35871 ``[''''»''' [link beast.ref.boost__beast__test__handler.operator_lp__rp_.overload3 more...]]`` 35872``` 35873[section:overload1 test::handler::operator() (1 of 3 overloads)] 35874 35875[heading Synopsis] 35876``` 35877template< 35878 class... Args> 35879void 35880operator()( 35881 error_code ec, 35882 Args&& ...); 35883``` 35884 35885[heading Description] 35886[endsect] 35887[section:overload2 test::handler::operator() (2 of 3 overloads)] 35888 35889[heading Synopsis] 35890``` 35891void 35892operator()(); 35893``` 35894 35895[heading Description] 35896[endsect] 35897[section:overload3 test::handler::operator() (3 of 3 overloads)] 35898 35899[heading Synopsis] 35900``` 35901template< 35902 class Arg0, 35903 class... Args, 35904 [role red error.class-detail-template.1][role red error.class-detail-template.2] = typename std::enable_if< ! std::is_convertible<Arg0, error_code>::value>::type> 35905void 35906operator()( 35907 Arg0&&, 35908 Args&& ...); 35909``` 35910 35911[heading Description] 35912[endsect] 35913[endsect] 35914 35915[section:handler_dtor_ test::handler::~handler] 35916[indexterm2 ~handler..test::handler] 35917 35918[heading Synopsis] 35919``` 35920~handler(); 35921``` 35922 35923[heading Description] 35924[endsect] 35925 35926 35927[endsect] 35928 35929 35930 35931[section:boost__beast__test__run test::run] 35932[indexterm1 test::run] 35933Run an I/O context. 35934[heading Synopsis] 35935 35936Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 35937 35938 35939 35940``` 35941void 35942run( 35943 net::io_context& ioc); 35944 35945``` 35946 35947[heading Description] 35948This function runs and dispatches handlers on the specified I/O context, until one of the following conditions is true: 35949 35950* The I/O context runs out of work. 35951 35952[heading Parameters] 35953[table [[Name][Description]] 35954 [[`ioc`][ 35955 35956The I/O context to run 35957 ]] 35958] 35959 35960 35961[endsect] 35962[section:boost__beast__test__run_for test::run_for] 35963[indexterm1 test::run_for] 35964Run an I/O context for a certain amount of time. 35965[heading Synopsis] 35966 35967Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 35968 35969 35970 35971``` 35972template< 35973 class Rep, 35974 class Period> 35975void 35976run_for( 35977 net::io_context& ioc, 35978 std::chrono::duration< Rep, Period > elapsed); 35979 35980``` 35981 35982[heading Description] 35983This function runs and dispatches handlers on the specified I/O context, until one of the following conditions is true: 35984 35985* The I/O context runs out of work. 35986 35987 35988* No completions occur and the specified amount of time has elapsed. 35989 35990[heading Parameters] 35991[table [[Name][Description]] 35992 [[`ioc`][ 35993 35994The I/O context to run 35995 ]] 35996 [[`elapsed`][ 35997 35998The maximum amount of time to run for. 35999 ]] 36000] 36001 36002 36003[endsect] 36004[section:boost__beast__test__stream test::stream] 36005A two-way socket useful for unit testing. 36006[heading Synopsis] 36007 36008Defined in header [include_file boost/beast/_experimental/test/stream.hpp] 36009 36010 36011 36012``` 36013class stream 36014``` 36015[heading Types] 36016[table [[Name][Description]] 36017 [ 36018 [[link beast.ref.boost__beast__test__stream.buffer_type [*buffer_type]]] 36019 [ 36020 36021 ] 36022 ] 36023 [ 36024 [[link beast.ref.boost__beast__test__stream.executor_type [*executor_type]]] 36025 [ 36026 The type of the executor associated with the object. 36027 ] 36028 ] 36029] 36030[heading Member Functions] 36031[table [[Name][Description]] 36032 [ 36033 [[link beast.ref.boost__beast__test__stream.append [*append]]] 36034 [ 36035 Appends a string to the pending input data. 36036 ] 36037 ] 36038 [ 36039 [[link beast.ref.boost__beast__test__stream.async_read_some [*async_read_some]]] 36040 [ 36041 Start an asynchronous read. 36042 ] 36043 ] 36044 [ 36045 [[link beast.ref.boost__beast__test__stream.async_write_some [*async_write_some]]] 36046 [ 36047 Start an asynchronous write. 36048 ] 36049 ] 36050 [ 36051 [[link beast.ref.boost__beast__test__stream.buffer [*buffer]]] 36052 [ 36053 Direct input buffer access. 36054 ] 36055 ] 36056 [ 36057 [[link beast.ref.boost__beast__test__stream.clear [*clear]]] 36058 [ 36059 Clear the pending input area. 36060 ] 36061 ] 36062 [ 36063 [[link beast.ref.boost__beast__test__stream.close [*close]]] 36064 [ 36065 Close the stream. 36066 ] 36067 ] 36068 [ 36069 [[link beast.ref.boost__beast__test__stream.close_remote [*close_remote]]] 36070 [ 36071 Close the other end of the stream. 36072 ] 36073 ] 36074 [ 36075 [[link beast.ref.boost__beast__test__stream.connect [*connect]]] 36076 [ 36077 Establish a connection. 36078 ] 36079 ] 36080 [ 36081 [[link beast.ref.boost__beast__test__stream.get_executor [*get_executor]]] 36082 [ 36083 Return the executor associated with the object. 36084 ] 36085 ] 36086 [ 36087 [[link beast.ref.boost__beast__test__stream.nread [*nread]]] 36088 [ 36089 Return the number of reads. 36090 ] 36091 ] 36092 [ 36093 [[link beast.ref.boost__beast__test__stream.nread_bytes [*nread_bytes]]] 36094 [ 36095 Return the number of bytes read. 36096 ] 36097 ] 36098 [ 36099 [[link beast.ref.boost__beast__test__stream.nwrite [*nwrite]]] 36100 [ 36101 Return the number of writes. 36102 ] 36103 ] 36104 [ 36105 [[link beast.ref.boost__beast__test__stream.nwrite_bytes [*nwrite_bytes]]] 36106 [ 36107 Return the number of bytes written. 36108 ] 36109 ] 36110 [ 36111 [[link beast.ref.boost__beast__test__stream.operator_eq_ [*operator=]]] 36112 [ 36113 Move Assignment. 36114 ] 36115 ] 36116 [ 36117 [[link beast.ref.boost__beast__test__stream.read_size [*read_size]]] 36118 [ 36119 Set the maximum number of bytes returned by read_some. 36120 ] 36121 ] 36122 [ 36123 [[link beast.ref.boost__beast__test__stream.read_some [*read_some]]] 36124 [ 36125 Read some data from the stream. 36126 ] 36127 ] 36128 [ 36129 [[link beast.ref.boost__beast__test__stream.str [*str]]] 36130 [ 36131 Returns a string view representing the pending input data. 36132 ] 36133 ] 36134 [ 36135 [[link beast.ref.boost__beast__test__stream.stream [*stream]]] 36136 [ 36137 Move Constructor. 36138 36139 Construct a stream. 36140 ] 36141 ] 36142 [ 36143 [[link beast.ref.boost__beast__test__stream.write_size [*write_size]]] 36144 [ 36145 Set the maximum number of bytes returned by write_some. 36146 ] 36147 ] 36148 [ 36149 [[link beast.ref.boost__beast__test__stream.write_some [*write_some]]] 36150 [ 36151 Write some data to the stream. 36152 ] 36153 ] 36154 [ 36155 [[link beast.ref.boost__beast__test__stream.stream_dtor_ [*~stream]]] 36156 [ 36157 Destructor. 36158 ] 36159 ] 36160] 36161 36162[heading Description] 36163An instance of this class simulates a traditional socket, while also providing features useful for unit testing. Each endpoint maintains an independent buffer called the input area. Writes from one endpoint append data to the peer's pending input area. When an endpoint performs a read and data is present in the input area, the data is delivered to the blocking or asynchronous operation. Otherwise the operation is blocked or deferred until data is made available, or until the endpoints become disconnected. 36164These streams may be used anywhere an algorithm accepts a reference to a synchronous or asynchronous read or write stream. It is possible to use a test stream in a call to `net::read_until`, or in a call to [link beast.ref.boost__beast__http__async_write `http::async_write`] for example. 36165As with Boost.Asio I/O objects, a [link beast.ref.boost__beast__test__stream `test::stream`] constructs with a reference to the `net::io_context` to use for handling asynchronous I/O. For asynchronous operations, the stream follows the same rules as a traditional asio socket with respect to how completion handlers for asynchronous operations are performed. 36166To facilitate testing, these streams support some additional features: 36167 36168* The input area, represented by a [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`], may be directly accessed by the caller to inspect the contents before or after the remote endpoint writes data. This allows a unit test to verify that the received data matches. 36169 36170 36171* Data may be manually appended to the input area. This data will delivered in the next call to [link beast.ref.boost__beast__test__stream.read_some `test::stream::read_some`] or [link beast.ref.boost__beast__test__stream.async_read_some `test::stream::async_read_some`]. This allows predefined test vectors to be set up for testing read algorithms. 36172 36173 36174* The stream may be constructed with a fail count. The stream will eventually fail with a predefined error after a certain number of operations, where the number of operations is controlled by the test. When a test loops over a range of operation counts, it is possible to exercise every possible point of failure in the algorithm being tested. When used correctly the technique allows the tests to reach a high percentage of code coverage. 36175 36176[heading Thread Safety] 36177['Distinct] ['objects:] Safe. 36178 36179['Shared] ['objects:] Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 36180[heading Concepts] 36181 36182* ['SyncReadStream] 36183* ['SyncWriteStream] 36184* ['AsyncReadStream] 36185* ['AsyncWriteStream] 36186 36187 36188[section:append test::stream::append] 36189[indexterm2 append..test::stream] 36190Appends a string to the pending input data. 36191[heading Synopsis] 36192``` 36193void 36194append( 36195 string_view s); 36196``` 36197 36198[heading Description] 36199[endsect] 36200[section:async_read_some test::stream::async_read_some] 36201[indexterm2 async_read_some..test::stream] 36202Start an asynchronous read. 36203[heading Synopsis] 36204``` 36205template< 36206 class __MutableBufferSequence__, 36207 class __ReadHandler__> 36208``__deduced__`` 36209async_read_some( 36210 MutableBufferSequence const& buffers, 36211 ReadHandler&& handler); 36212``` 36213 36214[heading Description] 36215This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately. 36216[heading Parameters] 36217[table [[Name][Description]] 36218 [[`buffers`][ 36219 36220The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 36221 ]] 36222 [[`handler`][ 36223 36224The 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: 36225``` 36226 void handler( 36227 error_code const& ec, // Result of operation. 36228 std::size_t bytes_transferred // Number of bytes read. 36229 ); 36230``` 36231Regardless 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 `net::post`. 36232 ]] 36233] 36234[heading Remarks] 36235The `async_read_some` operation may not read all of the requested number of bytes. Consider using the function `net::async_read` if you need to ensure that the requested amount of data is read before the asynchronous operation completes. 36236[endsect] 36237[section:async_write_some test::stream::async_write_some] 36238[indexterm2 async_write_some..test::stream] 36239Start an asynchronous write. 36240[heading Synopsis] 36241``` 36242template< 36243 class __ConstBufferSequence__, 36244 class __WriteHandler__> 36245``__deduced__`` 36246async_write_some( 36247 ConstBufferSequence const& buffers, 36248 WriteHandler&& handler); 36249``` 36250 36251[heading Description] 36252This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately. 36253[heading Parameters] 36254[table [[Name][Description]] 36255 [[`buffers`][ 36256 36257The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called. 36258 ]] 36259 [[`handler`][ 36260 36261The 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: 36262``` 36263 void handler( 36264 error_code const& ec, // Result of operation. 36265 std::size_t bytes_transferred // Number of bytes written. 36266 ); 36267``` 36268Regardless 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 `net::post`. 36269 ]] 36270] 36271[heading Remarks] 36272The `async_write_some` operation may not transmit all of the data to the peer. Consider using the function `net::async_write` if you need to ensure that all data is written before the asynchronous operation completes. 36273[endsect] 36274[section:buffer test::stream::buffer] 36275[indexterm2 buffer..test::stream] 36276Direct input buffer access. 36277[heading Synopsis] 36278``` 36279buffer_type& 36280buffer(); 36281``` 36282 36283[heading Description] 36284[endsect] 36285[section:buffer_type test::stream::buffer_type] 36286[indexterm2 buffer_type..test::stream] 36287 36288[heading Synopsis] 36289 36290``` 36291using buffer_type = flat_buffer; 36292``` 36293 36294[heading Description] 36295[endsect] 36296[section:clear test::stream::clear] 36297[indexterm2 clear..test::stream] 36298Clear the pending input area. 36299[heading Synopsis] 36300``` 36301void 36302clear(); 36303``` 36304 36305[heading Description] 36306[endsect] 36307[section:close test::stream::close] 36308[indexterm2 close..test::stream] 36309Close the stream. 36310[heading Synopsis] 36311``` 36312void 36313close(); 36314``` 36315 36316[heading Description] 36317The other end of the connection will see `error::eof` after reading all the remaining data. [endsect] 36318[section:close_remote test::stream::close_remote] 36319[indexterm2 close_remote..test::stream] 36320Close the other end of the stream. 36321[heading Synopsis] 36322``` 36323void 36324close_remote(); 36325``` 36326 36327[heading Description] 36328This end of the connection will see `error::eof` after reading all the remaining data. [endsect] 36329[section:connect test::stream::connect] 36330[indexterm2 connect..test::stream] 36331Establish a connection. 36332[heading Synopsis] 36333``` 36334void 36335connect( 36336 stream& remote); 36337``` 36338 36339[heading Description] 36340[endsect] 36341[section:executor_type test::stream::executor_type] 36342[indexterm2 executor_type..test::stream] 36343The type of the executor associated with the object. 36344[heading Synopsis] 36345 36346``` 36347using executor_type = net::io_context::executor_type; 36348``` 36349 36350[heading Description] 36351[endsect] 36352[section:get_executor test::stream::get_executor] 36353[indexterm2 get_executor..test::stream] 36354Return the executor associated with the object. 36355[heading Synopsis] 36356``` 36357executor_type 36358get_executor(); 36359``` 36360 36361[heading Description] 36362[endsect] 36363[section:nread test::stream::nread] 36364[indexterm2 nread..test::stream] 36365Return the number of reads. 36366[heading Synopsis] 36367``` 36368std::size_t 36369nread() const; 36370``` 36371 36372[heading Description] 36373[endsect] 36374[section:nread_bytes test::stream::nread_bytes] 36375[indexterm2 nread_bytes..test::stream] 36376Return the number of bytes read. 36377[heading Synopsis] 36378``` 36379std::size_t 36380nread_bytes() const; 36381``` 36382 36383[heading Description] 36384[endsect] 36385[section:nwrite test::stream::nwrite] 36386[indexterm2 nwrite..test::stream] 36387Return the number of writes. 36388[heading Synopsis] 36389``` 36390std::size_t 36391nwrite() const; 36392``` 36393 36394[heading Description] 36395[endsect] 36396[section:nwrite_bytes test::stream::nwrite_bytes] 36397[indexterm2 nwrite_bytes..test::stream] 36398Return the number of bytes written. 36399[heading Synopsis] 36400``` 36401std::size_t 36402nwrite_bytes() const; 36403``` 36404 36405[heading Description] 36406[endsect] 36407[section:operator_eq_ test::stream::operator=] 36408[indexterm2 operator=..test::stream] 36409Move Assignment. 36410[heading Synopsis] 36411``` 36412stream& 36413operator=( 36414 stream&& other); 36415``` 36416 36417[heading Description] 36418Moving the stream while asynchronous operations are pending results in undefined behavior. [endsect] 36419[section:read_size test::stream::read_size] 36420[indexterm2 read_size..test::stream] 36421Set the maximum number of bytes returned by read\_some. 36422[heading Synopsis] 36423``` 36424void 36425read_size( 36426 std::size_t n); 36427``` 36428 36429[heading Description] 36430[endsect] 36431[section:read_some test::stream::read_some] 36432[indexterm2 read_some..test::stream] 36433Read some data from the stream. ``` 36434template< 36435 class __MutableBufferSequence__> 36436std::size_t 36437``[link beast.ref.boost__beast__test__stream.read_some.overload1 read_some]``( 36438 MutableBufferSequence const& buffers); 36439 ``[''''»''' [link beast.ref.boost__beast__test__stream.read_some.overload1 more...]]`` 36440 36441template< 36442 class __MutableBufferSequence__> 36443std::size_t 36444``[link beast.ref.boost__beast__test__stream.read_some.overload2 read_some]``( 36445 MutableBufferSequence const& buffers, 36446 error_code& ec); 36447 ``[''''»''' [link beast.ref.boost__beast__test__stream.read_some.overload2 more...]]`` 36448``` 36449[section:overload1 test::stream::read_some (1 of 2 overloads)] 36450Read some data from the stream. 36451[heading Synopsis] 36452``` 36453template< 36454 class __MutableBufferSequence__> 36455std::size_t 36456read_some( 36457 MutableBufferSequence const& buffers); 36458``` 36459 36460[heading Description] 36461This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 36462[heading Parameters] 36463[table [[Name][Description]] 36464 [[`buffers`][ 36465 36466The buffers into which the data will be read. 36467 ]] 36468] 36469[heading Return Value] 36470The number of bytes read. 36471[heading Exceptions] 36472[table [[Type][Thrown On]] 36473 [[`boost::system::system_error`][ 36474 36475Thrown on failure. 36476 ]] 36477] 36478[heading Remarks] 36479The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 36480[endsect] 36481[section:overload2 test::stream::read_some (2 of 2 overloads)] 36482Read some data from the stream. 36483[heading Synopsis] 36484``` 36485template< 36486 class __MutableBufferSequence__> 36487std::size_t 36488read_some( 36489 MutableBufferSequence const& buffers, 36490 error_code& ec); 36491``` 36492 36493[heading Description] 36494This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs. 36495[heading Parameters] 36496[table [[Name][Description]] 36497 [[`buffers`][ 36498 36499The buffers into which the data will be read. 36500 ]] 36501 [[`ec`][ 36502 36503Set to indicate what error occurred, if any. 36504 ]] 36505] 36506[heading Return Value] 36507The number of bytes read. 36508[heading Remarks] 36509The `read_some` operation may not read all of the requested number of bytes. Consider using the function `net::read` if you need to ensure that the requested amount of data is read before the blocking operation completes. 36510[endsect] 36511[endsect] 36512 36513[section:str test::stream::str] 36514[indexterm2 str..test::stream] 36515Returns a string view representing the pending input data. 36516[heading Synopsis] 36517``` 36518string_view 36519str() const; 36520``` 36521 36522[heading Description] 36523[endsect] 36524[section:stream test::stream::stream] 36525[indexterm2 stream..test::stream] 36526Move Constructor. ``` 36527``[link beast.ref.boost__beast__test__stream.stream.overload1 stream]``( 36528 stream&& other); 36529 ``[''''»''' [link beast.ref.boost__beast__test__stream.stream.overload1 more...]]`` 36530 36531``` 36532Construct a stream. ``` 36533explicit 36534``[link beast.ref.boost__beast__test__stream.stream.overload2 stream]``( 36535 net::io_context& ioc); 36536 ``[''''»''' [link beast.ref.boost__beast__test__stream.stream.overload2 more...]]`` 36537 36538``[link beast.ref.boost__beast__test__stream.stream.overload3 stream]``( 36539 net::io_context& ioc, 36540 fail_count& fc); 36541 ``[''''»''' [link beast.ref.boost__beast__test__stream.stream.overload3 more...]]`` 36542 36543``[link beast.ref.boost__beast__test__stream.stream.overload4 stream]``( 36544 net::io_context& ioc, 36545 string_view s); 36546 ``[''''»''' [link beast.ref.boost__beast__test__stream.stream.overload4 more...]]`` 36547 36548``[link beast.ref.boost__beast__test__stream.stream.overload5 stream]``( 36549 net::io_context& ioc, 36550 fail_count& fc, 36551 string_view s); 36552 ``[''''»''' [link beast.ref.boost__beast__test__stream.stream.overload5 more...]]`` 36553``` 36554[section:overload1 test::stream::stream (1 of 5 overloads)] 36555Move Constructor. 36556[heading Synopsis] 36557``` 36558stream( 36559 stream&& other); 36560``` 36561 36562[heading Description] 36563Moving the stream while asynchronous operations are pending results in undefined behavior. [endsect] 36564[section:overload2 test::stream::stream (2 of 5 overloads)] 36565Construct a stream. 36566[heading Synopsis] 36567``` 36568stream( 36569 net::io_context& ioc); 36570``` 36571 36572[heading Description] 36573The stream will be created in a disconnected state. 36574[heading Parameters] 36575[table [[Name][Description]] 36576 [[`ioc`][ 36577 36578The `io_context` object that the stream will use to dispatch handlers for any asynchronous operations. 36579 ]] 36580] 36581[endsect] 36582[section:overload3 test::stream::stream (3 of 5 overloads)] 36583Construct a stream. 36584[heading Synopsis] 36585``` 36586stream( 36587 net::io_context& ioc, 36588 fail_count& fc); 36589``` 36590 36591[heading Description] 36592The stream will be created in a disconnected state. 36593[heading Parameters] 36594[table [[Name][Description]] 36595 [[`ioc`][ 36596 36597The `io_context` object that the stream will use to dispatch handlers for any asynchronous operations. 36598 ]] 36599 [[`fc`][ 36600 36601The [link beast.ref.boost__beast__test__fail_count `test::fail_count`] to associate with the stream. Each I/O operation performed on the stream will increment the fail count. When the fail count reaches its internal limit, a simulated failure error will be raised. 36602 ]] 36603] 36604[endsect] 36605[section:overload4 test::stream::stream (4 of 5 overloads)] 36606Construct a stream. 36607[heading Synopsis] 36608``` 36609stream( 36610 net::io_context& ioc, 36611 string_view s); 36612``` 36613 36614[heading Description] 36615The stream will be created in a disconnected state. 36616[heading Parameters] 36617[table [[Name][Description]] 36618 [[`ioc`][ 36619 36620The `io_context` object that the stream will use to dispatch handlers for any asynchronous operations. 36621 ]] 36622 [[`s`][ 36623 36624A string which will be appended to the input area, not including the null terminator. 36625 ]] 36626] 36627[endsect] 36628[section:overload5 test::stream::stream (5 of 5 overloads)] 36629Construct a stream. 36630[heading Synopsis] 36631``` 36632stream( 36633 net::io_context& ioc, 36634 fail_count& fc, 36635 string_view s); 36636``` 36637 36638[heading Description] 36639The stream will be created in a disconnected state. 36640[heading Parameters] 36641[table [[Name][Description]] 36642 [[`ioc`][ 36643 36644The `io_context` object that the stream will use to dispatch handlers for any asynchronous operations. 36645 ]] 36646 [[`fc`][ 36647 36648The [link beast.ref.boost__beast__test__fail_count `test::fail_count`] to associate with the stream. Each I/O operation performed on the stream will increment the fail count. When the fail count reaches its internal limit, a simulated failure error will be raised. 36649 ]] 36650 [[`s`][ 36651 36652A string which will be appended to the input area, not including the null terminator. 36653 ]] 36654] 36655[endsect] 36656[endsect] 36657 36658[section:write_size test::stream::write_size] 36659[indexterm2 write_size..test::stream] 36660Set the maximum number of bytes returned by write\_some. 36661[heading Synopsis] 36662``` 36663void 36664write_size( 36665 std::size_t n); 36666``` 36667 36668[heading Description] 36669[endsect] 36670[section:write_some test::stream::write_some] 36671[indexterm2 write_some..test::stream] 36672Write some data to the stream. ``` 36673template< 36674 class __ConstBufferSequence__> 36675std::size_t 36676``[link beast.ref.boost__beast__test__stream.write_some.overload1 write_some]``( 36677 ConstBufferSequence const& buffers); 36678 ``[''''»''' [link beast.ref.boost__beast__test__stream.write_some.overload1 more...]]`` 36679 36680template< 36681 class __ConstBufferSequence__> 36682std::size_t 36683``[link beast.ref.boost__beast__test__stream.write_some.overload2 write_some]``( 36684 ConstBufferSequence const& buffers, 36685 error_code& ec); 36686 ``[''''»''' [link beast.ref.boost__beast__test__stream.write_some.overload2 more...]]`` 36687``` 36688[section:overload1 test::stream::write_some (1 of 2 overloads)] 36689Write some data to the stream. 36690[heading Synopsis] 36691``` 36692template< 36693 class __ConstBufferSequence__> 36694std::size_t 36695write_some( 36696 ConstBufferSequence const& buffers); 36697``` 36698 36699[heading Description] 36700This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 36701[heading Parameters] 36702[table [[Name][Description]] 36703 [[`buffers`][ 36704 36705The data to be written. 36706 ]] 36707] 36708[heading Return Value] 36709The number of bytes written. 36710[heading Exceptions] 36711[table [[Type][Thrown On]] 36712 [[`boost::system::system_error`][ 36713 36714Thrown on failure. 36715 ]] 36716] 36717[heading Remarks] 36718The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 36719[endsect] 36720[section:overload2 test::stream::write_some (2 of 2 overloads)] 36721Write some data to the stream. 36722[heading Synopsis] 36723``` 36724template< 36725 class __ConstBufferSequence__> 36726std::size_t 36727write_some( 36728 ConstBufferSequence const& buffers, 36729 error_code& ec); 36730``` 36731 36732[heading Description] 36733This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs. 36734[heading Parameters] 36735[table [[Name][Description]] 36736 [[`buffers`][ 36737 36738The data to be written. 36739 ]] 36740 [[`ec`][ 36741 36742Set to indicate what error occurred, if any. 36743 ]] 36744] 36745[heading Return Value] 36746The number of bytes written. 36747[heading Remarks] 36748The `write_some` operation may not transmit all of the data to the peer. Consider using the function `net::write` if you need to ensure that all data is written before the blocking operation completes. 36749[endsect] 36750[endsect] 36751 36752[section:stream_dtor_ test::stream::~stream] 36753[indexterm2 ~stream..test::stream] 36754Destructor. 36755[heading Synopsis] 36756``` 36757~stream(); 36758``` 36759 36760[heading Description] 36761If an asynchronous read operation is pending, it will simply be discarded with no notification to the completion handler. 36762If a connection is established while the stream is destroyed, the peer will see the error `net::error::connection_reset` when performing any reads or writes. [endsect] 36763 36764 36765[endsect] 36766 36767 36768 36769[section:boost__beast__test__stream__read_op test::stream::read_op] 36770 36771[heading Synopsis] 36772 36773Defined in header [include_file boost/beast/_experimental/test/stream.hpp] 36774 36775 36776 36777``` 36778template< 36779 class __Handler__, 36780 class Buffers> 36781class read_op 36782``` 36783 36784[heading Description] 36785 36786 36787[endsect] 36788 36789 36790 36791[section:boost__beast__test__stream__read_op_base test::stream::read_op_base] 36792 36793[heading Synopsis] 36794 36795Defined in header [include_file boost/beast/_experimental/test/stream.hpp] 36796 36797 36798 36799``` 36800struct read_op_base 36801``` 36802[heading Member Functions] 36803[table [[Name][Description]] 36804 [ 36805 [[link beast.ref.boost__beast__test__stream__read_op_base.operator_lp__rp_ [*operator()]]] 36806 [ 36807 36808 ] 36809 ] 36810 [ 36811 [[link beast.ref.boost__beast__test__stream__read_op_base.read_op_base_dtor_ [*~read_op_base]]] 36812 [ 36813 36814 ] 36815 ] 36816] 36817 36818[heading Description] 36819[section:operator_lp__rp_ test::stream::read_op_base::operator()] 36820[indexterm2 operator()..test::stream::read_op_base] 36821 36822[heading Synopsis] 36823``` 36824void 36825operator()( 36826 error_code ec); 36827``` 36828 36829[heading Description] 36830[endsect] 36831[section:read_op_base_dtor_ test::stream::read_op_base::~read_op_base] 36832[indexterm2 ~read_op_base..test::stream::read_op_base] 36833 36834[heading Synopsis] 36835``` 36836virtual 36837~read_op_base(); 36838``` 36839 36840[heading Description] 36841[endsect] 36842 36843 36844[endsect] 36845 36846 36847 36848[section:boost__beast__test__stream__state test::stream::state] 36849 36850[heading Synopsis] 36851 36852Defined in header [include_file boost/beast/_experimental/test/stream.hpp] 36853 36854 36855 36856``` 36857struct state 36858``` 36859[heading Member Functions] 36860[table [[Name][Description]] 36861 [ 36862 [[link beast.ref.boost__beast__test__stream__state.cancel_read [*cancel_read]]] 36863 [ 36864 36865 ] 36866 ] 36867 [ 36868 [[link beast.ref.boost__beast__test__stream__state.notify_read [*notify_read]]] 36869 [ 36870 36871 ] 36872 ] 36873 [ 36874 [[link beast.ref.boost__beast__test__stream__state.remove [*remove]]] 36875 [ 36876 36877 ] 36878 ] 36879 [ 36880 [[link beast.ref.boost__beast__test__stream__state.state [*state]]] 36881 [ 36882 36883 ] 36884 ] 36885 [ 36886 [[link beast.ref.boost__beast__test__stream__state.state_dtor_ [*~state]]] 36887 [ 36888 36889 ] 36890 ] 36891] 36892[heading Data Members] 36893[table [[Name][Description]] 36894 [ 36895 [[link beast.ref.boost__beast__test__stream__state.b [*b]]] 36896 [ 36897 36898 ] 36899 ] 36900 [ 36901 [[link beast.ref.boost__beast__test__stream__state.code [*code]]] 36902 [ 36903 36904 ] 36905 ] 36906 [ 36907 [[link beast.ref.boost__beast__test__stream__state.cv [*cv]]] 36908 [ 36909 36910 ] 36911 ] 36912 [ 36913 [[link beast.ref.boost__beast__test__stream__state.fc [*fc]]] 36914 [ 36915 36916 ] 36917 ] 36918 [ 36919 [[link beast.ref.boost__beast__test__stream__state.ioc [*ioc]]] 36920 [ 36921 36922 ] 36923 ] 36924 [ 36925 [[link beast.ref.boost__beast__test__stream__state.m [*m]]] 36926 [ 36927 36928 ] 36929 ] 36930 [ 36931 [[link beast.ref.boost__beast__test__stream__state.nread [*nread]]] 36932 [ 36933 36934 ] 36935 ] 36936 [ 36937 [[link beast.ref.boost__beast__test__stream__state.nread_bytes [*nread_bytes]]] 36938 [ 36939 36940 ] 36941 ] 36942 [ 36943 [[link beast.ref.boost__beast__test__stream__state.nwrite [*nwrite]]] 36944 [ 36945 36946 ] 36947 ] 36948 [ 36949 [[link beast.ref.boost__beast__test__stream__state.nwrite_bytes [*nwrite_bytes]]] 36950 [ 36951 36952 ] 36953 ] 36954 [ 36955 [[link beast.ref.boost__beast__test__stream__state.op [*op]]] 36956 [ 36957 36958 ] 36959 ] 36960 [ 36961 [[link beast.ref.boost__beast__test__stream__state.read_max [*read_max]]] 36962 [ 36963 36964 ] 36965 ] 36966 [ 36967 [[link beast.ref.boost__beast__test__stream__state.wp [*wp]]] 36968 [ 36969 36970 ] 36971 ] 36972 [ 36973 [[link beast.ref.boost__beast__test__stream__state.write_max [*write_max]]] 36974 [ 36975 36976 ] 36977 ] 36978] 36979 36980[heading Description] 36981[section:b test::stream::state::b] 36982[indexterm2 b..test::stream::state] 36983 36984[heading Synopsis] 36985``` 36986flat_buffer b; 36987``` 36988 36989[heading Description] 36990[endsect] 36991[section:cancel_read test::stream::state::cancel_read] 36992[indexterm2 cancel_read..test::stream::state] 36993 36994[heading Synopsis] 36995``` 36996void 36997cancel_read(); 36998``` 36999 37000[heading Description] 37001[endsect] 37002[section:code test::stream::state::code] 37003[indexterm2 code..test::stream::state] 37004 37005[heading Synopsis] 37006``` 37007status code = status::ok; 37008``` 37009 37010[heading Description] 37011[endsect] 37012[section:cv test::stream::state::cv] 37013[indexterm2 cv..test::stream::state] 37014 37015[heading Synopsis] 37016``` 37017std::condition_variable cv; 37018``` 37019 37020[heading Description] 37021[endsect] 37022[section:fc test::stream::state::fc] 37023[indexterm2 fc..test::stream::state] 37024 37025[heading Synopsis] 37026``` 37027fail_count * fc = nullptr; 37028``` 37029 37030[heading Description] 37031[endsect] 37032[section:ioc test::stream::state::ioc] 37033[indexterm2 ioc..test::stream::state] 37034 37035[heading Synopsis] 37036``` 37037net::io_context & ioc; 37038``` 37039 37040[heading Description] 37041[endsect] 37042[section:m test::stream::state::m] 37043[indexterm2 m..test::stream::state] 37044 37045[heading Synopsis] 37046``` 37047std::mutex m; 37048``` 37049 37050[heading Description] 37051[endsect] 37052[section:notify_read test::stream::state::notify_read] 37053[indexterm2 notify_read..test::stream::state] 37054 37055[heading Synopsis] 37056``` 37057void 37058notify_read(); 37059``` 37060 37061[heading Description] 37062[endsect] 37063[section:nread test::stream::state::nread] 37064[indexterm2 nread..test::stream::state] 37065 37066[heading Synopsis] 37067``` 37068std::size_t nread = 0; 37069``` 37070 37071[heading Description] 37072[endsect] 37073[section:nread_bytes test::stream::state::nread_bytes] 37074[indexterm2 nread_bytes..test::stream::state] 37075 37076[heading Synopsis] 37077``` 37078std::size_t nread_bytes = 0; 37079``` 37080 37081[heading Description] 37082[endsect] 37083[section:nwrite test::stream::state::nwrite] 37084[indexterm2 nwrite..test::stream::state] 37085 37086[heading Synopsis] 37087``` 37088std::size_t nwrite = 0; 37089``` 37090 37091[heading Description] 37092[endsect] 37093[section:nwrite_bytes test::stream::state::nwrite_bytes] 37094[indexterm2 nwrite_bytes..test::stream::state] 37095 37096[heading Synopsis] 37097``` 37098std::size_t nwrite_bytes = 0; 37099``` 37100 37101[heading Description] 37102[endsect] 37103[section:op test::stream::state::op] 37104[indexterm2 op..test::stream::state] 37105 37106[heading Synopsis] 37107``` 37108std::unique_ptr< read_op_base > op; 37109``` 37110 37111[heading Description] 37112[endsect] 37113[section:read_max test::stream::state::read_max] 37114[indexterm2 read_max..test::stream::state] 37115 37116[heading Synopsis] 37117``` 37118std::size_t read_max = 37119 (std::numeric_limits<std::size_t>::max)(); 37120``` 37121 37122[heading Description] 37123[endsect] 37124[section:remove test::stream::state::remove] 37125[indexterm2 remove..test::stream::state] 37126 37127[heading Synopsis] 37128``` 37129void 37130remove(); 37131``` 37132 37133[heading Description] 37134[endsect] 37135[section:state test::stream::state::state] 37136[indexterm2 state..test::stream::state] 37137 37138[heading Synopsis] 37139``` 37140state( 37141 net::io_context& ioc_, 37142 boost::weak_ptr< service_impl > wp_, 37143 fail_count* fc_); 37144``` 37145 37146[heading Description] 37147[endsect] 37148[section:wp test::stream::state::wp] 37149[indexterm2 wp..test::stream::state] 37150 37151[heading Synopsis] 37152``` 37153boost::weak_ptr< service_impl > wp; 37154``` 37155 37156[heading Description] 37157[endsect] 37158[section:write_max test::stream::state::write_max] 37159[indexterm2 write_max..test::stream::state] 37160 37161[heading Synopsis] 37162``` 37163std::size_t write_max = 37164 (std::numeric_limits<std::size_t>::max)(); 37165``` 37166 37167[heading Description] 37168[endsect] 37169[section:state_dtor_ test::stream::state::~state] 37170[indexterm2 ~state..test::stream::state] 37171 37172[heading Synopsis] 37173``` 37174~state(); 37175``` 37176 37177[heading Description] 37178[endsect] 37179 37180 37181[endsect] 37182 37183 37184 37185[section:boost__beast__test__success_handler test::success_handler] 37186[indexterm1 test::success_handler] 37187Return a test CompletionHandler which requires success. 37188[heading Synopsis] 37189 37190Defined in header [include_file boost/beast/_experimental/test/handler.hpp] 37191 37192 37193 37194``` 37195handler 37196success_handler(); 37197 37198``` 37199 37200[heading Description] 37201The returned handler can be invoked with any signature whose first parameter is an `error_code`. The handler fails the test if: 37202 37203* The handler is destroyed without being invoked, or 37204 37205 37206* The handler is invoked with a non-successful error code. 37207 37208 37209 37210[endsect] 37211[section:boost__beast__to_static_string to_static_string] 37212[indexterm1 to_static_string] 37213Returns a static string representing an integer as a decimal. 37214[heading Synopsis] 37215 37216Defined in header [include_file boost/beast/core/static_string.hpp] 37217 37218 37219 37220``` 37221template< 37222 class Integer> 37223static_string< detail::max_digits(sizeof(Integer))> 37224to_static_string( 37225 Integer x); 37226 37227``` 37228 37229[heading Description] 37230[heading Parameters] 37231[table [[Name][Description]] 37232 [[`x`][ 37233 37234The signed or unsigned integer to convert. This must be an integral type. 37235 ]] 37236] 37237[heading Return Value] 37238A [link beast.ref.boost__beast__static_string `static_string`] with an implementation defined maximum size large enough to hold the longest possible decimal representation of any integer of the given type. 37239 37240 37241 37242Convenience header [include_file boost/beast/core.hpp] 37243 37244[endsect] 37245[section:boost__beast__unlimited_rate_policy unlimited_rate_policy] 37246A rate policy with unlimited throughput. 37247[heading Synopsis] 37248 37249Defined in header [include_file boost/beast/core/rate_policy.hpp] 37250 37251 37252 37253``` 37254class unlimited_rate_policy 37255``` 37256 37257[heading Description] 37258This rate policy object does not apply any rate limit. 37259[heading Concepts] 37260 37261 37262* ['RatePolicy] 37263 37264[heading See Also] 37265[link beast.ref.boost__beast__basic_stream `basic_stream`], [link beast.ref.boost__beast__tcp_stream `tcp_stream`] 37266 37267 37268 37269Convenience header [include_file boost/beast/core.hpp] 37270 37271[endsect] 37272 37273 37274 37275[section:boost__beast__websocket__async_teardown websocket::async_teardown] 37276[indexterm1 websocket::async_teardown] 37277Start tearing down a connection. ``` 37278template< 37279 class Socket, 37280 class TeardownHandler> 37281void 37282``[link beast.ref.boost__beast__websocket__async_teardown.overload1 async_teardown]``( 37283 role_type role, 37284 Socket& socket, 37285 TeardownHandler&& handler); 37286 ``[''''»''' [link beast.ref.boost__beast__websocket__async_teardown.overload1 more...]]`` 37287 37288``` 37289Start tearing down a `net::ip::tcp::socket`. ``` 37290template< 37291 class __Protocol__, 37292 class __Executor__, 37293 class TeardownHandler> 37294void 37295``[link beast.ref.boost__beast__websocket__async_teardown.overload2 async_teardown]``( 37296 role_type role, 37297 net::basic_stream_socket< Protocol, Executor >& socket, 37298 TeardownHandler&& handler); 37299 ``[''''»''' [link beast.ref.boost__beast__websocket__async_teardown.overload2 more...]]`` 37300``` 37301[section:overload1 websocket::async_teardown (1 of 2 overloads)] 37302Start tearing down a connection. 37303[heading Synopsis] 37304 37305Defined in header [include_file boost/beast/websocket/teardown.hpp] 37306 37307 37308 37309``` 37310template< 37311 class Socket, 37312 class TeardownHandler> 37313void 37314async_teardown( 37315 role_type role, 37316 Socket& socket, 37317 TeardownHandler&& handler); 37318 37319``` 37320 37321[heading Description] 37322This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the `Socket` parameter used to consruct the socket. When `Stream` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 37323[heading Parameters] 37324[table [[Name][Description]] 37325 [[`role`][ 37326 37327The role of the local endpoint 37328 ]] 37329 [[`socket`][ 37330 37331The socket to tear down. 37332 ]] 37333 [[`handler`][ 37334 37335The 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: 37336``` 37337 void handler( 37338 error_code const& error // result of operation 37339 ); 37340``` 37341Regardless 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 `net::post`. 37342 ]] 37343] 37344 37345 37346 37347Convenience header [include_file boost/beast/websocket.hpp] 37348 37349[endsect] 37350[section:overload2 websocket::async_teardown (2 of 2 overloads)] 37351Start tearing down a `net::ip::tcp::socket`. 37352[heading Synopsis] 37353 37354Defined in header [include_file boost/beast/websocket/teardown.hpp] 37355 37356 37357 37358``` 37359template< 37360 class __Protocol__, 37361 class __Executor__, 37362 class TeardownHandler> 37363void 37364async_teardown( 37365 role_type role, 37366 net::basic_stream_socket< Protocol, Executor >& socket, 37367 TeardownHandler&& handler); 37368 37369``` 37370 37371[heading Description] 37372This begins tearing down a connection asynchronously. The implementation will call the overload of this function based on the `Stream` parameter used to consruct the socket. When `Stream` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 37373[heading Parameters] 37374[table [[Name][Description]] 37375 [[`role`][ 37376 37377The role of the local endpoint 37378 ]] 37379 [[`socket`][ 37380 37381The socket to tear down. 37382 ]] 37383 [[`handler`][ 37384 37385The 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: 37386``` 37387 void handler( 37388 error_code const& error // result of operation 37389 ); 37390``` 37391 37392 ]] 37393] 37394Regardless 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 `net::post`. 37395 37396 37397Convenience header [include_file boost/beast/websocket.hpp] 37398 37399[endsect] 37400[endsect] 37401 37402 37403 37404[section:boost__beast__websocket__close_code websocket::close_code] 37405[indexterm1 websocket::close_code] 37406Close status codes. 37407[heading Synopsis] 37408 37409Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 37410 37411 37412``` 37413enum close_code 37414``` 37415 37416[indexterm2 normal..websocket::close_code] 37417[indexterm2 going_away..websocket::close_code] 37418[indexterm2 protocol_error..websocket::close_code] 37419[indexterm2 unknown_data..websocket::close_code] 37420[indexterm2 bad_payload..websocket::close_code] 37421[indexterm2 policy_error..websocket::close_code] 37422[indexterm2 too_big..websocket::close_code] 37423[indexterm2 needs_extension..websocket::close_code] 37424[indexterm2 internal_error..websocket::close_code] 37425[indexterm2 service_restart..websocket::close_code] 37426[indexterm2 try_again_later..websocket::close_code] 37427[indexterm2 none..websocket::close_code] 37428[indexterm2 reserved1..websocket::close_code] 37429[indexterm2 no_status..websocket::close_code] 37430[indexterm2 abnormal..websocket::close_code] 37431[indexterm2 reserved2..websocket::close_code] 37432[indexterm2 reserved3..websocket::close_code] 37433[heading Values] 37434[table [[Name][Description]] 37435 [[[^normal]][Normal closure; the connection successfully completed whatever purpose for which it was created. 37436 37437]] 37438 [[[^going_away]][The endpoint is going away, either because of a server failure or because the browser is navigating away from the page that opened the connection. 37439 37440]] 37441 [[[^protocol_error]][The endpoint is terminating the connection due to a protocol error. 37442 37443]] 37444 [[[^unknown_data]][The connection is being terminated because the endpoint received data of a type it cannot accept (for example, a text-only endpoint received binary data). 37445 37446]] 37447 [[[^bad_payload]][The endpoint is terminating the connection because a message was received that contained inconsistent data (e.g., non-UTF-8 data within a text message). 37448 37449]] 37450 [[[^policy_error]][The endpoint is terminating the connection because it received a message that violates its policy. This is a generic status code, used when codes 1003 and 1009 are not suitable. 37451 37452]] 37453 [[[^too_big]][The endpoint is terminating the connection because a data frame was received that is too large. 37454 37455]] 37456 [[[^needs_extension]][The client is terminating the connection because it expected the server to negotiate one or more extension, but the server didn't. 37457 37458]] 37459 [[[^internal_error]][The server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request. 37460 37461]] 37462 [[[^service_restart]][The server is terminating the connection because it is restarting. 37463 37464]] 37465 [[[^try_again_later]][The server is terminating the connection due to a temporary condition, e.g. it is overloaded and is casting off some of its clients. 37466 37467]] 37468 [[[^none]][Used internally to mean "no error". 37469 37470This code is reserved and may not be sent. 37471 ]] 37472 [[[^reserved1]][Reserved for future use by the WebSocket standard. 37473 37474This code is reserved and may not be sent. 37475 ]] 37476 [[[^no_status]][No status code was provided even though one was expected. 37477 37478This code is reserved and may not be sent. 37479 ]] 37480 [[[^abnormal]][Connection was closed without receiving a close frame. 37481 37482This code is reserved and may not be sent. 37483 ]] 37484 [[[^reserved2]][Reserved for future use by the WebSocket standard. 37485 37486This code is reserved and may not be sent. 37487 ]] 37488 [[[^reserved3]][Reserved for future use by the WebSocket standard. 37489 37490This code is reserved and may not be sent. 37491 ]] 37492] 37493 37494[heading Description] 37495These codes accompany close frames. 37496[heading See Also] 37497[@https://tools.ietf.org/html/rfc6455#section-7.4.1 RFC 6455 7.4.1 Defined Status Codes] 37498 37499 37500 37501Convenience header [include_file boost/beast/websocket.hpp] 37502 37503[endsect] 37504[section:boost__beast__websocket__close_reason websocket::close_reason] 37505Description of the close reason. 37506[heading Synopsis] 37507 37508Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 37509 37510 37511 37512``` 37513struct close_reason 37514``` 37515[heading Member Functions] 37516[table [[Name][Description]] 37517 [ 37518 [[link beast.ref.boost__beast__websocket__close_reason.close_reason [*close_reason]]] 37519 [ 37520 Default constructor. 37521 37522 Construct from a code. 37523 37524 Construct from a reason string. code is close_code::normal. 37525 37526 Construct from a reason string literal. code is close_code::normal. 37527 37528 Construct from a close code and reason string. 37529 ] 37530 ] 37531 [ 37532 [[link beast.ref.boost__beast__websocket__close_reason.operator_bool [*operator bool]]] 37533 [ 37534 Returns true if a code was specified. 37535 ] 37536 ] 37537] 37538[heading Data Members] 37539[table [[Name][Description]] 37540 [ 37541 [[link beast.ref.boost__beast__websocket__close_reason.code [*code]]] 37542 [ 37543 The close code. 37544 ] 37545 ] 37546 [ 37547 [[link beast.ref.boost__beast__websocket__close_reason.reason [*reason]]] 37548 [ 37549 The optional utf8-encoded reason string. 37550 ] 37551 ] 37552] 37553 37554[heading Description] 37555This object stores the close code (if any) and the optional utf-8 encoded implementation defined reason string. [section:close_reason websocket::close_reason::close_reason] 37556[indexterm2 close_reason..websocket::close_reason] 37557Default constructor. ``` 37558``[link beast.ref.boost__beast__websocket__close_reason.close_reason.overload1 close_reason]``(); 37559 ``[''''»''' [link beast.ref.boost__beast__websocket__close_reason.close_reason.overload1 more...]]`` 37560 37561``` 37562Construct from a code. ``` 37563``[link beast.ref.boost__beast__websocket__close_reason.close_reason.overload2 close_reason]``( 37564 std::uint16_t code_); 37565 ``[''''»''' [link beast.ref.boost__beast__websocket__close_reason.close_reason.overload2 more...]]`` 37566 37567``` 37568Construct from a reason string. code is close\_code::normal. ``` 37569``[link beast.ref.boost__beast__websocket__close_reason.close_reason.overload3 close_reason]``( 37570 string_view s); 37571 ``[''''»''' [link beast.ref.boost__beast__websocket__close_reason.close_reason.overload3 more...]]`` 37572 37573``` 37574Construct from a reason string literal. code is close\_code::normal. ``` 37575``[link beast.ref.boost__beast__websocket__close_reason.close_reason.overload4 close_reason]``( 37576 char const* s); 37577 ``[''''»''' [link beast.ref.boost__beast__websocket__close_reason.close_reason.overload4 more...]]`` 37578 37579``` 37580Construct from a close code and reason string. ``` 37581``[link beast.ref.boost__beast__websocket__close_reason.close_reason.overload5 close_reason]``( 37582 close_code code_, 37583 string_view s); 37584 ``[''''»''' [link beast.ref.boost__beast__websocket__close_reason.close_reason.overload5 more...]]`` 37585``` 37586[section:overload1 websocket::close_reason::close_reason (1 of 5 overloads)] 37587Default constructor. 37588[heading Synopsis] 37589``` 37590close_reason(); 37591``` 37592 37593[heading Description] 37594The code will be none. Default constructed objects will explicitly convert to bool as `false`. [endsect] 37595[section:overload2 websocket::close_reason::close_reason (2 of 5 overloads)] 37596Construct from a code. 37597[heading Synopsis] 37598``` 37599close_reason( 37600 std::uint16_t code_); 37601``` 37602 37603[heading Description] 37604[endsect] 37605[section:overload3 websocket::close_reason::close_reason (3 of 5 overloads)] 37606Construct from a reason string. code is close\_code::normal. 37607[heading Synopsis] 37608``` 37609close_reason( 37610 string_view s); 37611``` 37612 37613[heading Description] 37614[endsect] 37615[section:overload4 websocket::close_reason::close_reason (4 of 5 overloads)] 37616Construct from a reason string literal. code is close\_code::normal. 37617[heading Synopsis] 37618``` 37619close_reason( 37620 char const* s); 37621``` 37622 37623[heading Description] 37624[endsect] 37625[section:overload5 websocket::close_reason::close_reason (5 of 5 overloads)] 37626Construct from a close code and reason string. 37627[heading Synopsis] 37628``` 37629close_reason( 37630 close_code code_, 37631 string_view s); 37632``` 37633 37634[heading Description] 37635[endsect] 37636[endsect] 37637 37638[section:code websocket::close_reason::code] 37639[indexterm2 code..websocket::close_reason] 37640The close code. 37641[heading Synopsis] 37642``` 37643std::uint16_t code = close_code::none; 37644``` 37645 37646[heading Description] 37647[endsect] 37648[section:operator_bool websocket::close_reason::operator bool] 37649[indexterm2 operator bool..websocket::close_reason] 37650Returns `true` if a code was specified. 37651[heading Synopsis] 37652``` 37653operator bool() const; 37654``` 37655 37656[heading Description] 37657[endsect] 37658[section:reason websocket::close_reason::reason] 37659[indexterm2 reason..websocket::close_reason] 37660The optional utf8-encoded reason string. 37661[heading Synopsis] 37662``` 37663reason_string reason; 37664``` 37665 37666[heading Description] 37667[endsect] 37668 37669 37670 37671Convenience header [include_file boost/beast/websocket.hpp] 37672 37673[endsect] 37674 37675 37676 37677[section:boost__beast__websocket__condition websocket::condition] 37678[indexterm1 websocket::condition] 37679Error conditions corresponding to sets of error codes. 37680[heading Synopsis] 37681 37682Defined in header [include_file boost/beast/websocket/error.hpp] 37683 37684 37685``` 37686enum condition 37687``` 37688 37689[indexterm2 handshake_failed..websocket::condition] 37690[indexterm2 protocol_violation..websocket::condition] 37691[heading Values] 37692[table [[Name][Description]] 37693 [[[^handshake_failed]][The WebSocket handshake failed. 37694 37695This condition indicates that the WebSocket handshake failed. If 37696the corresponding HTTP response indicates the keep-alive behavior, 37697then the handshake may be reattempted. 37698 ]] 37699 [[[^protocol_violation]][A WebSocket protocol violation occurred. 37700 37701This condition indicates that the remote peer on the WebSocket 37702connection sent data which violated the protocol. 37703 ]] 37704] 37705 37706[heading Description] 37707 37708 37709 37710Convenience header [include_file boost/beast/websocket.hpp] 37711 37712[endsect] 37713[section:boost__beast__websocket__error websocket::error] 37714[indexterm1 websocket::error] 37715Error codes returned from [link beast.ref.boost__beast__websocket__stream `websocket::stream`] operations. 37716[heading Synopsis] 37717 37718Defined in header [include_file boost/beast/websocket/error.hpp] 37719 37720 37721``` 37722enum error 37723``` 37724 37725[indexterm2 closed..websocket::error] 37726[indexterm2 buffer_overflow..websocket::error] 37727[indexterm2 partial_deflate_block..websocket::error] 37728[indexterm2 message_too_big..websocket::error] 37729[indexterm2 bad_http_version..websocket::error] 37730[indexterm2 bad_method..websocket::error] 37731[indexterm2 no_host..websocket::error] 37732[indexterm2 no_connection..websocket::error] 37733[indexterm2 no_connection_upgrade..websocket::error] 37734[indexterm2 no_upgrade..websocket::error] 37735[indexterm2 no_upgrade_websocket..websocket::error] 37736[indexterm2 no_sec_key..websocket::error] 37737[indexterm2 bad_sec_key..websocket::error] 37738[indexterm2 no_sec_version..websocket::error] 37739[indexterm2 bad_sec_version..websocket::error] 37740[indexterm2 no_sec_accept..websocket::error] 37741[indexterm2 bad_sec_accept..websocket::error] 37742[indexterm2 upgrade_declined..websocket::error] 37743[indexterm2 bad_opcode..websocket::error] 37744[indexterm2 bad_data_frame..websocket::error] 37745[indexterm2 bad_continuation..websocket::error] 37746[indexterm2 bad_reserved_bits..websocket::error] 37747[indexterm2 bad_control_fragment..websocket::error] 37748[indexterm2 bad_control_size..websocket::error] 37749[indexterm2 bad_unmasked_frame..websocket::error] 37750[indexterm2 bad_masked_frame..websocket::error] 37751[indexterm2 bad_size..websocket::error] 37752[indexterm2 bad_frame_payload..websocket::error] 37753[indexterm2 bad_close_code..websocket::error] 37754[indexterm2 bad_close_size..websocket::error] 37755[indexterm2 bad_close_payload..websocket::error] 37756[heading Values] 37757[table [[Name][Description]] 37758 [[[^closed]][The WebSocket stream was gracefully closed at both endpoints. 37759 37760]] 37761 [[[^buffer_overflow]][The WebSocket operation caused a dynamic buffer overflow. 37762 37763]] 37764 [[[^partial_deflate_block]][The WebSocket stream produced an incomplete deflate block. 37765 37766]] 37767 [[[^message_too_big]][The WebSocket message exceeded the locally configured limit. 37768 37769]] 37770 [[[^bad_http_version]][The WebSocket handshake was not HTTP/1.1. 37771 37772Error codes with this value will compare equal to @ref condition::handshake_failed 37773 ]] 37774 [[[^bad_method]][The WebSocket handshake method was not GET. 37775 37776Error codes with this value will compare equal to @ref condition::handshake_failed 37777 ]] 37778 [[[^no_host]][The WebSocket handshake Host field is missing. 37779 37780Error codes with this value will compare equal to @ref condition::handshake_failed 37781 ]] 37782 [[[^no_connection]][The WebSocket handshake Connection field is missing. 37783 37784Error codes with this value will compare equal to @ref condition::handshake_failed 37785 ]] 37786 [[[^no_connection_upgrade]][The WebSocket handshake Connection field is missing the upgrade token. 37787 37788Error codes with this value will compare equal to @ref condition::handshake_failed 37789 ]] 37790 [[[^no_upgrade]][The WebSocket handshake Upgrade field is missing. 37791 37792Error codes with this value will compare equal to @ref condition::handshake_failed 37793 ]] 37794 [[[^no_upgrade_websocket]][The WebSocket handshake Upgrade field is missing the websocket token. 37795 37796Error codes with this value will compare equal to @ref condition::handshake_failed 37797 ]] 37798 [[[^no_sec_key]][The WebSocket handshake Sec-WebSocket-Key field is missing. 37799 37800Error codes with this value will compare equal to @ref condition::handshake_failed 37801 ]] 37802 [[[^bad_sec_key]][The WebSocket handshake Sec-WebSocket-Key field is invalid. 37803 37804Error codes with this value will compare equal to @ref condition::handshake_failed 37805 ]] 37806 [[[^no_sec_version]][The WebSocket handshake Sec-WebSocket-Version field is missing. 37807 37808Error codes with this value will compare equal to @ref condition::handshake_failed 37809 ]] 37810 [[[^bad_sec_version]][The WebSocket handshake Sec-WebSocket-Version field is invalid. 37811 37812Error codes with this value will compare equal to @ref condition::handshake_failed 37813 ]] 37814 [[[^no_sec_accept]][The WebSocket handshake Sec-WebSocket-Accept field is missing. 37815 37816Error codes with this value will compare equal to @ref condition::handshake_failed 37817 ]] 37818 [[[^bad_sec_accept]][The WebSocket handshake Sec-WebSocket-Accept field is invalid. 37819 37820Error codes with this value will compare equal to @ref condition::handshake_failed 37821 ]] 37822 [[[^upgrade_declined]][The WebSocket handshake was declined by the remote peer. 37823 37824Error codes with this value will compare equal to @ref condition::handshake_failed 37825 ]] 37826 [[[^bad_opcode]][The WebSocket frame contained an illegal opcode. 37827 37828Error codes with this value will compare equal to @ref condition::protocol_violation 37829 ]] 37830 [[[^bad_data_frame]][The WebSocket data frame was unexpected. 37831 37832Error codes with this value will compare equal to @ref condition::protocol_violation 37833 ]] 37834 [[[^bad_continuation]][The WebSocket continuation frame was unexpected. 37835 37836Error codes with this value will compare equal to @ref condition::protocol_violation 37837 ]] 37838 [[[^bad_reserved_bits]][The WebSocket frame contained illegal reserved bits. 37839 37840Error codes with this value will compare equal to @ref condition::protocol_violation 37841 ]] 37842 [[[^bad_control_fragment]][The WebSocket control frame was fragmented. 37843 37844Error codes with this value will compare equal to @ref condition::protocol_violation 37845 ]] 37846 [[[^bad_control_size]][The WebSocket control frame size was invalid. 37847 37848Error codes with this value will compare equal to @ref condition::protocol_violation 37849 ]] 37850 [[[^bad_unmasked_frame]][The WebSocket frame was unmasked. 37851 37852Error codes with this value will compare equal to @ref condition::protocol_violation 37853 ]] 37854 [[[^bad_masked_frame]][The WebSocket frame was masked. 37855 37856Error codes with this value will compare equal to @ref condition::protocol_violation 37857 ]] 37858 [[[^bad_size]][The WebSocket frame size was not canonical. 37859 37860Error codes with this value will compare equal to @ref condition::protocol_violation 37861 ]] 37862 [[[^bad_frame_payload]][The WebSocket frame payload was not valid utf8. 37863 37864Error codes with this value will compare equal to @ref condition::protocol_violation 37865 ]] 37866 [[[^bad_close_code]][The WebSocket close frame reason code was invalid. 37867 37868Error codes with this value will compare equal to @ref condition::protocol_violation 37869 ]] 37870 [[[^bad_close_size]][The WebSocket close frame payload size was invalid. 37871 37872Error codes with this value will compare equal to @ref condition::protocol_violation 37873 ]] 37874 [[[^bad_close_payload]][The WebSocket close frame payload was not valid utf8. 37875 37876Error codes with this value will compare equal to @ref condition::protocol_violation 37877 ]] 37878] 37879 37880[heading Description] 37881 37882 37883 37884Convenience header [include_file boost/beast/websocket.hpp] 37885 37886[endsect] 37887[section:boost__beast__websocket__frame_type websocket::frame_type] 37888[indexterm1 websocket::frame_type] 37889The type of received control frame. 37890[heading Synopsis] 37891 37892Defined in header [include_file boost/beast/websocket/stream.hpp] 37893 37894 37895``` 37896enum frame_type 37897``` 37898 37899[indexterm2 close..websocket::frame_type] 37900[indexterm2 ping..websocket::frame_type] 37901[indexterm2 pong..websocket::frame_type] 37902[heading Values] 37903[table [[Name][Description]] 37904 [[[^close]][A close frame was received. 37905 37906]] 37907 [[[^ping]][A ping frame was received. 37908 37909]] 37910 [[[^pong]][A pong frame was received. 37911 37912]] 37913] 37914 37915[heading Description] 37916Values of this type are passed to the control frame callback set using [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`]. 37917 37918 37919Convenience header [include_file boost/beast/websocket.hpp] 37920 37921[endsect] 37922[section:boost__beast__websocket__is_upgrade websocket::is_upgrade] 37923[indexterm1 websocket::is_upgrade] 37924Returns `true` if the specified HTTP request is a WebSocket Upgrade. 37925[heading Synopsis] 37926 37927Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 37928 37929 37930 37931``` 37932template< 37933 class __Allocator__> 37934bool 37935is_upgrade( 37936 beast::http::header< true, http::basic_fields< Allocator >> const& req); 37937 37938``` 37939 37940[heading Description] 37941This function returns `true` when the passed HTTP Request indicates a WebSocket Upgrade. It does not validate the contents of the fields: it just trivially accepts requests which could only possibly be a valid or invalid WebSocket Upgrade message. 37942Callers who wish to manually read HTTP requests in their server implementation can use this function to determine if the request should be routed to an instance of [link beast.ref.boost__beast__websocket__stream `websocket::stream`]. 37943[heading Example] 37944 37945``` 37946 void handle_connection(net::ip::tcp::socket& sock) 37947 { 37948 boost::beast::flat_buffer buffer; 37949 boost::beast::http::request<boost::beast::http::string_body> req; 37950 boost::beast::http::read(sock, buffer, req); 37951 if(boost::beast::websocket::is_upgrade(req)) 37952 { 37953 boost::beast::websocket::stream<decltype(sock)> ws{std::move(sock)}; 37954 ws.accept(req); 37955 } 37956 } 37957``` 37958[heading Parameters] 37959[table [[Name][Description]] 37960 [[`req`][ 37961 37962The HTTP Request object to check. 37963 ]] 37964] 37965[heading Return Value] 37966`true` if the request is a WebSocket Upgrade. 37967 37968 37969 37970Convenience header [include_file boost/beast/websocket.hpp] 37971 37972[endsect] 37973[section:boost__beast__websocket__permessage_deflate websocket::permessage_deflate] 37974permessage-deflate extension options. 37975[heading Synopsis] 37976 37977Defined in header [include_file boost/beast/websocket/option.hpp] 37978 37979 37980 37981``` 37982struct permessage_deflate 37983``` 37984[heading Data Members] 37985[table [[Name][Description]] 37986 [ 37987 [[link beast.ref.boost__beast__websocket__permessage_deflate.client_enable [*client_enable]]] 37988 [ 37989 true to offer the extension in the client role 37990 ] 37991 ] 37992 [ 37993 [[link beast.ref.boost__beast__websocket__permessage_deflate.client_max_window_bits [*client_max_window_bits]]] 37994 [ 37995 Maximum client window bits to offer. 37996 ] 37997 ] 37998 [ 37999 [[link beast.ref.boost__beast__websocket__permessage_deflate.client_no_context_takeover [*client_no_context_takeover]]] 38000 [ 38001 true if client_no_context_takeover desired 38002 ] 38003 ] 38004 [ 38005 [[link beast.ref.boost__beast__websocket__permessage_deflate.compLevel [*compLevel]]] 38006 [ 38007 Deflate compression level 0..9. 38008 ] 38009 ] 38010 [ 38011 [[link beast.ref.boost__beast__websocket__permessage_deflate.memLevel [*memLevel]]] 38012 [ 38013 Deflate memory level, 1..9. 38014 ] 38015 ] 38016 [ 38017 [[link beast.ref.boost__beast__websocket__permessage_deflate.server_enable [*server_enable]]] 38018 [ 38019 true to offer the extension in the server role 38020 ] 38021 ] 38022 [ 38023 [[link beast.ref.boost__beast__websocket__permessage_deflate.server_max_window_bits [*server_max_window_bits]]] 38024 [ 38025 Maximum server window bits to offer. 38026 ] 38027 ] 38028 [ 38029 [[link beast.ref.boost__beast__websocket__permessage_deflate.server_no_context_takeover [*server_no_context_takeover]]] 38030 [ 38031 true if server_no_context_takeover desired 38032 ] 38033 ] 38034] 38035 38036[heading Description] 38037These settings control the permessage-deflate extension, which allows messages to be compressed. 38038[heading Remarks] 38039Objects of this type are used with [link beast.ref.boost__beast__websocket__stream.set_option `websocket::stream::set_option`]. 38040[section:client_enable websocket::permessage_deflate::client_enable] 38041[indexterm2 client_enable..websocket::permessage_deflate] 38042`true` to offer the extension in the client role 38043[heading Synopsis] 38044``` 38045bool client_enable = false; 38046``` 38047 38048[heading Description] 38049[endsect] 38050[section:client_max_window_bits websocket::permessage_deflate::client_max_window_bits] 38051[indexterm2 client_max_window_bits..websocket::permessage_deflate] 38052Maximum client window bits to offer. 38053[heading Synopsis] 38054``` 38055int client_max_window_bits = 15; 38056``` 38057 38058[heading Description] 38059[heading Remarks] 38060Due to a bug in ZLib, this value must be greater than 8. 38061[endsect] 38062[section:client_no_context_takeover websocket::permessage_deflate::client_no_context_takeover] 38063[indexterm2 client_no_context_takeover..websocket::permessage_deflate] 38064`true` if client\_no\_context\_takeover desired 38065[heading Synopsis] 38066``` 38067bool client_no_context_takeover = false; 38068``` 38069 38070[heading Description] 38071[endsect] 38072[section:compLevel websocket::permessage_deflate::compLevel] 38073[indexterm2 compLevel..websocket::permessage_deflate] 38074Deflate compression level 0..9. 38075[heading Synopsis] 38076``` 38077int compLevel = 8; 38078``` 38079 38080[heading Description] 38081[endsect] 38082[section:memLevel websocket::permessage_deflate::memLevel] 38083[indexterm2 memLevel..websocket::permessage_deflate] 38084Deflate memory level, 1..9. 38085[heading Synopsis] 38086``` 38087int memLevel = 4; 38088``` 38089 38090[heading Description] 38091[endsect] 38092[section:server_enable websocket::permessage_deflate::server_enable] 38093[indexterm2 server_enable..websocket::permessage_deflate] 38094`true` to offer the extension in the server role 38095[heading Synopsis] 38096``` 38097bool server_enable = false; 38098``` 38099 38100[heading Description] 38101[endsect] 38102[section:server_max_window_bits websocket::permessage_deflate::server_max_window_bits] 38103[indexterm2 server_max_window_bits..websocket::permessage_deflate] 38104Maximum server window bits to offer. 38105[heading Synopsis] 38106``` 38107int server_max_window_bits = 15; 38108``` 38109 38110[heading Description] 38111[heading Remarks] 38112Due to a bug in ZLib, this value must be greater than 8. 38113[endsect] 38114[section:server_no_context_takeover websocket::permessage_deflate::server_no_context_takeover] 38115[indexterm2 server_no_context_takeover..websocket::permessage_deflate] 38116`true` if server\_no\_context\_takeover desired 38117[heading Synopsis] 38118``` 38119bool server_no_context_takeover = false; 38120``` 38121 38122[heading Description] 38123[endsect] 38124 38125 38126 38127Convenience header [include_file boost/beast/websocket.hpp] 38128 38129[endsect] 38130 38131 38132 38133[section:boost__beast__websocket__ping_data websocket::ping_data] 38134[indexterm1 websocket::ping_data] 38135The type representing the payload of ping and pong messages. 38136[heading Synopsis] 38137 38138Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 38139 38140 38141 38142``` 38143using ping_data = static_string< 125, char >; 38144``` 38145[heading Types] 38146[table [[Name][Description]] 38147 [ 38148 [[link beast.ref.boost__beast__static_string.const_iterator [*const_iterator]]] 38149 [ 38150 38151 ] 38152 ] 38153 [ 38154 [[link beast.ref.boost__beast__static_string.const_pointer [*const_pointer]]] 38155 [ 38156 38157 ] 38158 ] 38159 [ 38160 [[link beast.ref.boost__beast__static_string.const_reference [*const_reference]]] 38161 [ 38162 38163 ] 38164 ] 38165 [ 38166 [[link beast.ref.boost__beast__static_string.const_reverse_iterator [*const_reverse_iterator]]] 38167 [ 38168 38169 ] 38170 ] 38171 [ 38172 [[link beast.ref.boost__beast__static_string.difference_type [*difference_type]]] 38173 [ 38174 38175 ] 38176 ] 38177 [ 38178 [[link beast.ref.boost__beast__static_string.iterator [*iterator]]] 38179 [ 38180 38181 ] 38182 ] 38183 [ 38184 [[link beast.ref.boost__beast__static_string.pointer [*pointer]]] 38185 [ 38186 38187 ] 38188 ] 38189 [ 38190 [[link beast.ref.boost__beast__static_string.reference [*reference]]] 38191 [ 38192 38193 ] 38194 ] 38195 [ 38196 [[link beast.ref.boost__beast__static_string.reverse_iterator [*reverse_iterator]]] 38197 [ 38198 38199 ] 38200 ] 38201 [ 38202 [[link beast.ref.boost__beast__static_string.size_type [*size_type]]] 38203 [ 38204 38205 ] 38206 ] 38207 [ 38208 [[link beast.ref.boost__beast__static_string.string_view_type [*string_view_type]]] 38209 [ 38210 The type of string_view returned by the interface. 38211 ] 38212 ] 38213 [ 38214 [[link beast.ref.boost__beast__static_string.traits_type [*traits_type]]] 38215 [ 38216 38217 ] 38218 ] 38219 [ 38220 [[link beast.ref.boost__beast__static_string.value_type [*value_type]]] 38221 [ 38222 38223 ] 38224 ] 38225] 38226[heading Member Functions] 38227[table [[Name][Description]] 38228 [ 38229 [[link beast.ref.boost__beast__static_string.append [*append]]] 38230 [ 38231 38232 ] 38233 ] 38234 [ 38235 [[link beast.ref.boost__beast__static_string.assign [*assign]]] 38236 [ 38237 Assign count copies of ch. 38238 38239 Assign from another static_string 38240 38241 Assign count characterss starting at npos from other. 38242 38243 Assign the first count characters of s, including nulls. 38244 38245 Assign a null terminated string. 38246 38247 Assign from an iterator range of characters. 38248 38249 Assign from any object convertible to string_view_type. 38250 ] 38251 ] 38252 [ 38253 [[link beast.ref.boost__beast__static_string.at [*at]]] 38254 [ 38255 Access specified character with bounds checking. 38256 ] 38257 ] 38258 [ 38259 [[link beast.ref.boost__beast__static_string.back [*back]]] 38260 [ 38261 Accesses the last character. 38262 ] 38263 ] 38264 [ 38265 [[link beast.ref.boost__beast__static_string.begin [*begin]]] 38266 [ 38267 Returns an iterator to the beginning. 38268 ] 38269 ] 38270 [ 38271 [[link beast.ref.boost__beast__static_string.c_str [*c_str]]] 38272 [ 38273 Returns a non-modifiable standard C character array version of the string. 38274 ] 38275 ] 38276 [ 38277 [[link beast.ref.boost__beast__static_string.capacity [*capacity]]] 38278 [ 38279 Returns the number of characters that can be held in currently allocated storage. 38280 ] 38281 ] 38282 [ 38283 [[link beast.ref.boost__beast__static_string.cbegin [*cbegin]]] 38284 [ 38285 Returns an iterator to the beginning. 38286 ] 38287 ] 38288 [ 38289 [[link beast.ref.boost__beast__static_string.cend [*cend]]] 38290 [ 38291 Returns an iterator to the end. 38292 ] 38293 ] 38294 [ 38295 [[link beast.ref.boost__beast__static_string.clear [*clear]]] 38296 [ 38297 Clears the contents. 38298 ] 38299 ] 38300 [ 38301 [[link beast.ref.boost__beast__static_string.compare [*compare]]] 38302 [ 38303 38304 ] 38305 ] 38306 [ 38307 [[link beast.ref.boost__beast__static_string.copy [*copy]]] 38308 [ 38309 Copy a substring (pos, pos+count) to character string pointed to by dest. 38310 ] 38311 ] 38312 [ 38313 [[link beast.ref.boost__beast__static_string.crbegin [*crbegin]]] 38314 [ 38315 Returns a reverse iterator to the beginning. 38316 ] 38317 ] 38318 [ 38319 [[link beast.ref.boost__beast__static_string.crend [*crend]]] 38320 [ 38321 Returns a reverse iterator to the end. 38322 ] 38323 ] 38324 [ 38325 [[link beast.ref.boost__beast__static_string.data [*data]]] 38326 [ 38327 Returns a pointer to the first character of a string. 38328 ] 38329 ] 38330 [ 38331 [[link beast.ref.boost__beast__static_string.empty [*empty]]] 38332 [ 38333 Returns true if the string is empty. 38334 ] 38335 ] 38336 [ 38337 [[link beast.ref.boost__beast__static_string.end [*end]]] 38338 [ 38339 Returns an iterator to the end. 38340 ] 38341 ] 38342 [ 38343 [[link beast.ref.boost__beast__static_string.erase [*erase]]] 38344 [ 38345 38346 ] 38347 ] 38348 [ 38349 [[link beast.ref.boost__beast__static_string.front [*front]]] 38350 [ 38351 Accesses the first character. 38352 ] 38353 ] 38354 [ 38355 [[link beast.ref.boost__beast__static_string.insert [*insert]]] 38356 [ 38357 38358 ] 38359 ] 38360 [ 38361 [[link beast.ref.boost__beast__static_string.length [*length]]] 38362 [ 38363 Returns the number of characters, excluding the null terminator. 38364 ] 38365 ] 38366 [ 38367 [[link beast.ref.boost__beast__static_string.max_size [*max_size]]] 38368 [ 38369 Returns the maximum number of characters that can be stored, excluding the null terminator. 38370 ] 38371 ] 38372 [ 38373 [[link beast.ref.boost__beast__static_string.operator_string_view_type [*operator string_view_type]]] 38374 [ 38375 Convert a static string to a string_view_type 38376 ] 38377 ] 38378 [ 38379 [[link beast.ref.boost__beast__static_string.operator_plus__eq_ [*operator+=]]] 38380 [ 38381 38382 ] 38383 ] 38384 [ 38385 [[link beast.ref.boost__beast__static_string.operator_eq_ [*operator=]]] 38386 [ 38387 Copy assignment. 38388 38389 Assign from null-terminated string. 38390 38391 Assign from single character. 38392 38393 Assign from initializer list. 38394 38395 Assign from string_view_type. 38396 ] 38397 ] 38398 [ 38399 [[link beast.ref.boost__beast__static_string.operator_lb__rb_ [*operator\[\]]]] 38400 [ 38401 Access specified character. 38402 ] 38403 ] 38404 [ 38405 [[link beast.ref.boost__beast__static_string.pop_back [*pop_back]]] 38406 [ 38407 38408 ] 38409 ] 38410 [ 38411 [[link beast.ref.boost__beast__static_string.push_back [*push_back]]] 38412 [ 38413 38414 ] 38415 ] 38416 [ 38417 [[link beast.ref.boost__beast__static_string.rbegin [*rbegin]]] 38418 [ 38419 Returns a reverse iterator to the beginning. 38420 ] 38421 ] 38422 [ 38423 [[link beast.ref.boost__beast__static_string.rend [*rend]]] 38424 [ 38425 Returns a reverse iterator to the end. 38426 ] 38427 ] 38428 [ 38429 [[link beast.ref.boost__beast__static_string.reserve [*reserve]]] 38430 [ 38431 Reserves storage. 38432 ] 38433 ] 38434 [ 38435 [[link beast.ref.boost__beast__static_string.resize [*resize]]] 38436 [ 38437 Changes the number of characters stored. 38438 ] 38439 ] 38440 [ 38441 [[link beast.ref.boost__beast__static_string.shrink_to_fit [*shrink_to_fit]]] 38442 [ 38443 Reduces memory usage by freeing unused memory. 38444 ] 38445 ] 38446 [ 38447 [[link beast.ref.boost__beast__static_string.size [*size]]] 38448 [ 38449 Returns the number of characters, excluding the null terminator. 38450 ] 38451 ] 38452 [ 38453 [[link beast.ref.boost__beast__static_string.static_string [*static_string]]] 38454 [ 38455 Default constructor (empty string). 38456 38457 Construct with count copies of character ch. 38458 38459 Construct with a substring (pos, other.size()) of other. 38460 38461 Construct with a substring (pos, count) of other. 38462 38463 Construct with the first count characters of s, including nulls. 38464 38465 Construct from a null terminated string. 38466 38467 Construct from a range of characters. 38468 38469 Copy constructor. 38470 38471 Construct from an initializer list. 38472 38473 Construct from a string_view 38474 38475 Construct from any object convertible to string_view_type. 38476 ] 38477 ] 38478 [ 38479 [[link beast.ref.boost__beast__static_string.substr [*substr]]] 38480 [ 38481 38482 ] 38483 ] 38484 [ 38485 [[link beast.ref.boost__beast__static_string.swap [*swap]]] 38486 [ 38487 Exchange the contents of this string with another. 38488 ] 38489 ] 38490] 38491[heading Data Members] 38492[table [[Name][Description]] 38493 [ 38494 [[link beast.ref.boost__beast__static_string.max_size_n [*max_size_n]]] 38495 [ 38496 Maximum size of the string excluding the null terminator. 38497 ] 38498 ] 38499 [ 38500 [[link beast.ref.boost__beast__static_string.npos [*npos]]] 38501 [ 38502 A special index. 38503 ] 38504 ] 38505] 38506These objects behave like `std::string` except that the storage is not dynamically allocated but rather fixed in size. 38507These strings offer performance advantages when a protocol imposes a natural small upper limit on the size of a value. 38508[heading Remarks] 38509The stored string is always null-terminated. 38510[heading See Also] 38511[link beast.ref.boost__beast__to_static_string `to_static_string`] 38512 38513[heading Description] 38514 38515 38516 38517Convenience header [include_file boost/beast/websocket.hpp] 38518 38519[endsect] 38520[section:boost__beast__websocket__reason_string websocket::reason_string] 38521[indexterm1 websocket::reason_string] 38522The type representing the reason string in a close frame. 38523[heading Synopsis] 38524 38525Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 38526 38527 38528 38529``` 38530using reason_string = static_string< 123, char >; 38531``` 38532[heading Types] 38533[table [[Name][Description]] 38534 [ 38535 [[link beast.ref.boost__beast__static_string.const_iterator [*const_iterator]]] 38536 [ 38537 38538 ] 38539 ] 38540 [ 38541 [[link beast.ref.boost__beast__static_string.const_pointer [*const_pointer]]] 38542 [ 38543 38544 ] 38545 ] 38546 [ 38547 [[link beast.ref.boost__beast__static_string.const_reference [*const_reference]]] 38548 [ 38549 38550 ] 38551 ] 38552 [ 38553 [[link beast.ref.boost__beast__static_string.const_reverse_iterator [*const_reverse_iterator]]] 38554 [ 38555 38556 ] 38557 ] 38558 [ 38559 [[link beast.ref.boost__beast__static_string.difference_type [*difference_type]]] 38560 [ 38561 38562 ] 38563 ] 38564 [ 38565 [[link beast.ref.boost__beast__static_string.iterator [*iterator]]] 38566 [ 38567 38568 ] 38569 ] 38570 [ 38571 [[link beast.ref.boost__beast__static_string.pointer [*pointer]]] 38572 [ 38573 38574 ] 38575 ] 38576 [ 38577 [[link beast.ref.boost__beast__static_string.reference [*reference]]] 38578 [ 38579 38580 ] 38581 ] 38582 [ 38583 [[link beast.ref.boost__beast__static_string.reverse_iterator [*reverse_iterator]]] 38584 [ 38585 38586 ] 38587 ] 38588 [ 38589 [[link beast.ref.boost__beast__static_string.size_type [*size_type]]] 38590 [ 38591 38592 ] 38593 ] 38594 [ 38595 [[link beast.ref.boost__beast__static_string.string_view_type [*string_view_type]]] 38596 [ 38597 The type of string_view returned by the interface. 38598 ] 38599 ] 38600 [ 38601 [[link beast.ref.boost__beast__static_string.traits_type [*traits_type]]] 38602 [ 38603 38604 ] 38605 ] 38606 [ 38607 [[link beast.ref.boost__beast__static_string.value_type [*value_type]]] 38608 [ 38609 38610 ] 38611 ] 38612] 38613[heading Member Functions] 38614[table [[Name][Description]] 38615 [ 38616 [[link beast.ref.boost__beast__static_string.append [*append]]] 38617 [ 38618 38619 ] 38620 ] 38621 [ 38622 [[link beast.ref.boost__beast__static_string.assign [*assign]]] 38623 [ 38624 Assign count copies of ch. 38625 38626 Assign from another static_string 38627 38628 Assign count characterss starting at npos from other. 38629 38630 Assign the first count characters of s, including nulls. 38631 38632 Assign a null terminated string. 38633 38634 Assign from an iterator range of characters. 38635 38636 Assign from any object convertible to string_view_type. 38637 ] 38638 ] 38639 [ 38640 [[link beast.ref.boost__beast__static_string.at [*at]]] 38641 [ 38642 Access specified character with bounds checking. 38643 ] 38644 ] 38645 [ 38646 [[link beast.ref.boost__beast__static_string.back [*back]]] 38647 [ 38648 Accesses the last character. 38649 ] 38650 ] 38651 [ 38652 [[link beast.ref.boost__beast__static_string.begin [*begin]]] 38653 [ 38654 Returns an iterator to the beginning. 38655 ] 38656 ] 38657 [ 38658 [[link beast.ref.boost__beast__static_string.c_str [*c_str]]] 38659 [ 38660 Returns a non-modifiable standard C character array version of the string. 38661 ] 38662 ] 38663 [ 38664 [[link beast.ref.boost__beast__static_string.capacity [*capacity]]] 38665 [ 38666 Returns the number of characters that can be held in currently allocated storage. 38667 ] 38668 ] 38669 [ 38670 [[link beast.ref.boost__beast__static_string.cbegin [*cbegin]]] 38671 [ 38672 Returns an iterator to the beginning. 38673 ] 38674 ] 38675 [ 38676 [[link beast.ref.boost__beast__static_string.cend [*cend]]] 38677 [ 38678 Returns an iterator to the end. 38679 ] 38680 ] 38681 [ 38682 [[link beast.ref.boost__beast__static_string.clear [*clear]]] 38683 [ 38684 Clears the contents. 38685 ] 38686 ] 38687 [ 38688 [[link beast.ref.boost__beast__static_string.compare [*compare]]] 38689 [ 38690 38691 ] 38692 ] 38693 [ 38694 [[link beast.ref.boost__beast__static_string.copy [*copy]]] 38695 [ 38696 Copy a substring (pos, pos+count) to character string pointed to by dest. 38697 ] 38698 ] 38699 [ 38700 [[link beast.ref.boost__beast__static_string.crbegin [*crbegin]]] 38701 [ 38702 Returns a reverse iterator to the beginning. 38703 ] 38704 ] 38705 [ 38706 [[link beast.ref.boost__beast__static_string.crend [*crend]]] 38707 [ 38708 Returns a reverse iterator to the end. 38709 ] 38710 ] 38711 [ 38712 [[link beast.ref.boost__beast__static_string.data [*data]]] 38713 [ 38714 Returns a pointer to the first character of a string. 38715 ] 38716 ] 38717 [ 38718 [[link beast.ref.boost__beast__static_string.empty [*empty]]] 38719 [ 38720 Returns true if the string is empty. 38721 ] 38722 ] 38723 [ 38724 [[link beast.ref.boost__beast__static_string.end [*end]]] 38725 [ 38726 Returns an iterator to the end. 38727 ] 38728 ] 38729 [ 38730 [[link beast.ref.boost__beast__static_string.erase [*erase]]] 38731 [ 38732 38733 ] 38734 ] 38735 [ 38736 [[link beast.ref.boost__beast__static_string.front [*front]]] 38737 [ 38738 Accesses the first character. 38739 ] 38740 ] 38741 [ 38742 [[link beast.ref.boost__beast__static_string.insert [*insert]]] 38743 [ 38744 38745 ] 38746 ] 38747 [ 38748 [[link beast.ref.boost__beast__static_string.length [*length]]] 38749 [ 38750 Returns the number of characters, excluding the null terminator. 38751 ] 38752 ] 38753 [ 38754 [[link beast.ref.boost__beast__static_string.max_size [*max_size]]] 38755 [ 38756 Returns the maximum number of characters that can be stored, excluding the null terminator. 38757 ] 38758 ] 38759 [ 38760 [[link beast.ref.boost__beast__static_string.operator_string_view_type [*operator string_view_type]]] 38761 [ 38762 Convert a static string to a string_view_type 38763 ] 38764 ] 38765 [ 38766 [[link beast.ref.boost__beast__static_string.operator_plus__eq_ [*operator+=]]] 38767 [ 38768 38769 ] 38770 ] 38771 [ 38772 [[link beast.ref.boost__beast__static_string.operator_eq_ [*operator=]]] 38773 [ 38774 Copy assignment. 38775 38776 Assign from null-terminated string. 38777 38778 Assign from single character. 38779 38780 Assign from initializer list. 38781 38782 Assign from string_view_type. 38783 ] 38784 ] 38785 [ 38786 [[link beast.ref.boost__beast__static_string.operator_lb__rb_ [*operator\[\]]]] 38787 [ 38788 Access specified character. 38789 ] 38790 ] 38791 [ 38792 [[link beast.ref.boost__beast__static_string.pop_back [*pop_back]]] 38793 [ 38794 38795 ] 38796 ] 38797 [ 38798 [[link beast.ref.boost__beast__static_string.push_back [*push_back]]] 38799 [ 38800 38801 ] 38802 ] 38803 [ 38804 [[link beast.ref.boost__beast__static_string.rbegin [*rbegin]]] 38805 [ 38806 Returns a reverse iterator to the beginning. 38807 ] 38808 ] 38809 [ 38810 [[link beast.ref.boost__beast__static_string.rend [*rend]]] 38811 [ 38812 Returns a reverse iterator to the end. 38813 ] 38814 ] 38815 [ 38816 [[link beast.ref.boost__beast__static_string.reserve [*reserve]]] 38817 [ 38818 Reserves storage. 38819 ] 38820 ] 38821 [ 38822 [[link beast.ref.boost__beast__static_string.resize [*resize]]] 38823 [ 38824 Changes the number of characters stored. 38825 ] 38826 ] 38827 [ 38828 [[link beast.ref.boost__beast__static_string.shrink_to_fit [*shrink_to_fit]]] 38829 [ 38830 Reduces memory usage by freeing unused memory. 38831 ] 38832 ] 38833 [ 38834 [[link beast.ref.boost__beast__static_string.size [*size]]] 38835 [ 38836 Returns the number of characters, excluding the null terminator. 38837 ] 38838 ] 38839 [ 38840 [[link beast.ref.boost__beast__static_string.static_string [*static_string]]] 38841 [ 38842 Default constructor (empty string). 38843 38844 Construct with count copies of character ch. 38845 38846 Construct with a substring (pos, other.size()) of other. 38847 38848 Construct with a substring (pos, count) of other. 38849 38850 Construct with the first count characters of s, including nulls. 38851 38852 Construct from a null terminated string. 38853 38854 Construct from a range of characters. 38855 38856 Copy constructor. 38857 38858 Construct from an initializer list. 38859 38860 Construct from a string_view 38861 38862 Construct from any object convertible to string_view_type. 38863 ] 38864 ] 38865 [ 38866 [[link beast.ref.boost__beast__static_string.substr [*substr]]] 38867 [ 38868 38869 ] 38870 ] 38871 [ 38872 [[link beast.ref.boost__beast__static_string.swap [*swap]]] 38873 [ 38874 Exchange the contents of this string with another. 38875 ] 38876 ] 38877] 38878[heading Data Members] 38879[table [[Name][Description]] 38880 [ 38881 [[link beast.ref.boost__beast__static_string.max_size_n [*max_size_n]]] 38882 [ 38883 Maximum size of the string excluding the null terminator. 38884 ] 38885 ] 38886 [ 38887 [[link beast.ref.boost__beast__static_string.npos [*npos]]] 38888 [ 38889 A special index. 38890 ] 38891 ] 38892] 38893These objects behave like `std::string` except that the storage is not dynamically allocated but rather fixed in size. 38894These strings offer performance advantages when a protocol imposes a natural small upper limit on the size of a value. 38895[heading Remarks] 38896The stored string is always null-terminated. 38897[heading See Also] 38898[link beast.ref.boost__beast__to_static_string `to_static_string`] 38899 38900[heading Description] 38901 38902 38903 38904Convenience header [include_file boost/beast/websocket.hpp] 38905 38906[endsect] 38907[section:boost__beast__websocket__request_type websocket::request_type] 38908[indexterm1 websocket::request_type] 38909The type of object holding HTTP Upgrade requests. 38910[heading Synopsis] 38911 38912Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 38913 38914 38915 38916``` 38917using request_type = http::request< http::empty_body >; 38918``` 38919 38920[heading Description] 38921 38922 38923 38924Convenience header [include_file boost/beast/websocket.hpp] 38925 38926[endsect] 38927[section:boost__beast__websocket__response_type websocket::response_type] 38928[indexterm1 websocket::response_type] 38929The type of object holding HTTP Upgrade responses. 38930[heading Synopsis] 38931 38932Defined in header [include_file boost/beast/websocket/rfc6455.hpp] 38933 38934 38935 38936``` 38937using response_type = http::response< http::string_body >; 38938``` 38939 38940[heading Description] 38941 38942 38943 38944Convenience header [include_file boost/beast/websocket.hpp] 38945 38946[endsect] 38947[section:boost__beast__websocket__seed_prng websocket::seed_prng] 38948[indexterm1 websocket::seed_prng] 38949Manually provide a one-time seed to initialize the PRNG. 38950[heading Synopsis] 38951 38952Defined in header [include_file boost/beast/websocket/stream.hpp] 38953 38954 38955 38956``` 38957void 38958seed_prng( 38959 std::seed_seq& ss); 38960 38961``` 38962 38963[heading Description] 38964This function invokes the specified seed sequence to produce a seed suitable for use with the pseudo-random number generator used to create masks and perform WebSocket protocol handshakes. 38965If a seed is not manually provided, the implementation will perform a one-time seed generation using `std::random_device`. This function may be used when the application runs in an environment where the random device is unreliable or does not provide sufficient entropy. 38966[heading Preconditions] 38967 38968This function may not be called after any websocket [link beast.ref.boost__beast__websocket__stream `websocket::stream`] objects have been constructed. 38969[heading Parameters] 38970[table [[Name][Description]] 38971 [[`ss`][ 38972 38973A reference to a `std::seed_seq` which will be used to seed the pseudo-random number generator. The seed sequence should have at least 256 bits of entropy. 38974 ]] 38975] 38976[heading See Also] 38977[link beast.ref.boost__beast__websocket__stream.secure_prng `websocket::stream::secure_prng`] 38978 38979 38980 38981Convenience header [include_file boost/beast/websocket.hpp] 38982 38983[endsect] 38984[section:boost__beast__websocket__stream websocket::stream] 38985Provides message-oriented functionality using WebSocket. 38986[heading Synopsis] 38987 38988Defined in header [include_file boost/beast/websocket/stream.hpp] 38989 38990 38991 38992``` 38993template< 38994 class NextLayer, 38995 bool deflateSupported> 38996class stream 38997``` 38998[heading Types] 38999[table [[Name][Description]] 39000 [ 39001 [[link beast.ref.boost__beast__websocket__stream.executor_type [*executor_type]]] 39002 [ 39003 The type of the executor associated with the object. 39004 ] 39005 ] 39006 [ 39007 [[link beast.ref.boost__beast__websocket__stream.is_deflate_supported [*is_deflate_supported]]] 39008 [ 39009 Indicates if the permessage-deflate extension is supported. 39010 ] 39011 ] 39012 [ 39013 [[link beast.ref.boost__beast__websocket__stream.next_layer_type [*next_layer_type]]] 39014 [ 39015 The type of the next layer. 39016 ] 39017 ] 39018] 39019[heading Member Functions] 39020[table [[Name][Description]] 39021 [ 39022 [[link beast.ref.boost__beast__websocket__stream.accept [*accept]]] 39023 [ 39024 Perform the WebSocket handshake in the server role. 39025 39026 Read and respond to a WebSocket HTTP Upgrade request. 39027 39028 Respond to a WebSocket HTTP Upgrade request. 39029 ] 39030 ] 39031 [ 39032 [[link beast.ref.boost__beast__websocket__stream.async_accept [*async_accept]]] 39033 [ 39034 Perform the WebSocket handshake asynchronously in the server role. 39035 ] 39036 ] 39037 [ 39038 [[link beast.ref.boost__beast__websocket__stream.async_close [*async_close]]] 39039 [ 39040 Send a websocket close control frame asynchronously. 39041 ] 39042 ] 39043 [ 39044 [[link beast.ref.boost__beast__websocket__stream.async_handshake [*async_handshake]]] 39045 [ 39046 Perform the WebSocket handshake asynchronously in the client role. 39047 ] 39048 ] 39049 [ 39050 [[link beast.ref.boost__beast__websocket__stream.async_ping [*async_ping]]] 39051 [ 39052 Send a websocket ping control frame asynchronously. 39053 ] 39054 ] 39055 [ 39056 [[link beast.ref.boost__beast__websocket__stream.async_pong [*async_pong]]] 39057 [ 39058 Send a websocket pong control frame asynchronously. 39059 ] 39060 ] 39061 [ 39062 [[link beast.ref.boost__beast__websocket__stream.async_read [*async_read]]] 39063 [ 39064 Read a complete message asynchronously. 39065 ] 39066 ] 39067 [ 39068 [[link beast.ref.boost__beast__websocket__stream.async_read_some [*async_read_some]]] 39069 [ 39070 Read some message data asynchronously. 39071 ] 39072 ] 39073 [ 39074 [[link beast.ref.boost__beast__websocket__stream.async_write [*async_write]]] 39075 [ 39076 Write a complete message asynchronously. 39077 ] 39078 ] 39079 [ 39080 [[link beast.ref.boost__beast__websocket__stream.async_write_some [*async_write_some]]] 39081 [ 39082 Write some message data asynchronously. 39083 ] 39084 ] 39085 [ 39086 [[link beast.ref.boost__beast__websocket__stream.auto_fragment [*auto_fragment]]] 39087 [ 39088 Set the automatic fragmentation option. 39089 39090 Returns true if the automatic fragmentation option is set. 39091 ] 39092 ] 39093 [ 39094 [[link beast.ref.boost__beast__websocket__stream.binary [*binary]]] 39095 [ 39096 Set the binary message write option. 39097 39098 Returns true if the binary message write option is set. 39099 ] 39100 ] 39101 [ 39102 [[link beast.ref.boost__beast__websocket__stream.close [*close]]] 39103 [ 39104 Send a websocket close control frame. 39105 ] 39106 ] 39107 [ 39108 [[link beast.ref.boost__beast__websocket__stream.control_callback [*control_callback]]] 39109 [ 39110 Set a callback to be invoked on each incoming control frame. 39111 39112 Reset the control frame callback. 39113 ] 39114 ] 39115 [ 39116 [[link beast.ref.boost__beast__websocket__stream.get_executor [*get_executor]]] 39117 [ 39118 Get the executor associated with the object. 39119 ] 39120 ] 39121 [ 39122 [[link beast.ref.boost__beast__websocket__stream.get_option [*get_option]]] 39123 [ 39124 39125 39126 Get the permessage-deflate extension options. 39127 ] 39128 ] 39129 [ 39130 [[link beast.ref.boost__beast__websocket__stream.got_binary [*got_binary]]] 39131 [ 39132 Returns true if the latest message data indicates binary. 39133 ] 39134 ] 39135 [ 39136 [[link beast.ref.boost__beast__websocket__stream.got_text [*got_text]]] 39137 [ 39138 Returns true if the latest message data indicates text. 39139 ] 39140 ] 39141 [ 39142 [[link beast.ref.boost__beast__websocket__stream.handshake [*handshake]]] 39143 [ 39144 Perform the WebSocket handshake in the client role. 39145 ] 39146 ] 39147 [ 39148 [[link beast.ref.boost__beast__websocket__stream.is_message_done [*is_message_done]]] 39149 [ 39150 Returns true if the last completed read finished the current message. 39151 ] 39152 ] 39153 [ 39154 [[link beast.ref.boost__beast__websocket__stream.is_open [*is_open]]] 39155 [ 39156 Returns true if the stream is open. 39157 ] 39158 ] 39159 [ 39160 [[link beast.ref.boost__beast__websocket__stream.next_layer [*next_layer]]] 39161 [ 39162 Get a reference to the next layer. 39163 ] 39164 ] 39165 [ 39166 [[link beast.ref.boost__beast__websocket__stream.operator_eq_ [*operator=]]] 39167 [ 39168 Move assignment (deleted) 39169 ] 39170 ] 39171 [ 39172 [[link beast.ref.boost__beast__websocket__stream.ping [*ping]]] 39173 [ 39174 Send a websocket ping control frame. 39175 ] 39176 ] 39177 [ 39178 [[link beast.ref.boost__beast__websocket__stream.pong [*pong]]] 39179 [ 39180 Send a websocket pong control frame. 39181 ] 39182 ] 39183 [ 39184 [[link beast.ref.boost__beast__websocket__stream.read [*read]]] 39185 [ 39186 Read a complete message. 39187 ] 39188 ] 39189 [ 39190 [[link beast.ref.boost__beast__websocket__stream.read_message_max [*read_message_max]]] 39191 [ 39192 Set the maximum incoming message size option. 39193 39194 Returns the maximum incoming message size setting. 39195 ] 39196 ] 39197 [ 39198 [[link beast.ref.boost__beast__websocket__stream.read_size_hint [*read_size_hint]]] 39199 [ 39200 Returns a suggested maximum buffer size for the next call to read. 39201 ] 39202 ] 39203 [ 39204 [[link beast.ref.boost__beast__websocket__stream.read_some [*read_some]]] 39205 [ 39206 Read some message data. 39207 ] 39208 ] 39209 [ 39210 [[link beast.ref.boost__beast__websocket__stream.reason [*reason]]] 39211 [ 39212 Returns the close reason received from the remote peer. 39213 ] 39214 ] 39215 [ 39216 [[link beast.ref.boost__beast__websocket__stream.secure_prng [*secure_prng]]] 39217 [ 39218 Set whether the PRNG is cryptographically secure. 39219 ] 39220 ] 39221 [ 39222 [[link beast.ref.boost__beast__websocket__stream.set_option [*set_option]]] 39223 [ 39224 39225 39226 Set the permessage-deflate extension options. 39227 ] 39228 ] 39229 [ 39230 [[link beast.ref.boost__beast__websocket__stream.stream [*stream]]] 39231 [ 39232 Constructor. 39233 ] 39234 ] 39235 [ 39236 [[link beast.ref.boost__beast__websocket__stream.text [*text]]] 39237 [ 39238 Set the text message write option. 39239 39240 Returns true if the text message write option is set. 39241 ] 39242 ] 39243 [ 39244 [[link beast.ref.boost__beast__websocket__stream.write [*write]]] 39245 [ 39246 Write a complete message. 39247 ] 39248 ] 39249 [ 39250 [[link beast.ref.boost__beast__websocket__stream.write_buffer_bytes [*write_buffer_bytes]]] 39251 [ 39252 Set the write buffer size option. 39253 39254 Returns the size of the write buffer. 39255 ] 39256 ] 39257 [ 39258 [[link beast.ref.boost__beast__websocket__stream.write_some [*write_some]]] 39259 [ 39260 Write some message data. 39261 ] 39262 ] 39263 [ 39264 [[link beast.ref.boost__beast__websocket__stream.stream_dtor_ [*~stream]]] 39265 [ 39266 Destructor. 39267 ] 39268 ] 39269] 39270 39271[heading Description] 39272The [link beast.ref.boost__beast__websocket__stream `websocket::stream`] class template provides asynchronous and blocking message-oriented functionality necessary for clients and servers to utilize the WebSocket protocol. 39273For asynchronous operations, the application must ensure that they are are all performed within the same implicit or explicit strand. 39274[heading Thread Safety] 39275['Distinct] ['objects:] Safe. 39276 39277['Shared] ['objects:] Unsafe. The application must also ensure that all asynchronous operations are performed within the same implicit or explicit strand. 39278[heading Example] 39279To declare the [link beast.ref.boost__beast__websocket__stream `websocket::stream`] object with a [link beast.ref.boost__beast__tcp_stream `tcp_stream`] in a multi-threaded asynchronous program using a strand, you may write: 39280``` 39281 websocket::stream<tcp_stream> ws{net::io_context::strand(ioc)}; 39282``` 39283Alternatively, for a single-threaded or synchronous application you may write: 39284``` 39285 websocket::stream<tcp_stream> ws(ioc); 39286``` 39287[heading Template Parameters] 39288[table [[Type][Description]] 39289 [[`NextLayer`][ 39290 39291The type representing the next layer, to which data will be read and written during operations. For synchronous operations, the type must support the ['SyncStream] concept. For asynchronous operations, the type must support the ['AsyncStream] concept. 39292 ]] 39293 [[`deflateSupported`][ 39294 39295A `bool` indicating whether or not the stream will be capable of negotiating the permessage-deflate websocket extension. Note that even if this is set to `true`, the permessage deflate options (set by the caller at runtime) must still have the feature enabled for a successful negotiation to occur. 39296 ]] 39297] 39298[heading Remarks] 39299A stream object must not be moved or destroyed while there are pending asynchronous operations associated with it. 39300[heading Concepts] 39301 39302* ['AsyncStream] 39303* ['DynamicBuffer] 39304* ['SyncStream] 39305 39306 39307[heading See Also] 39308 39309* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 39310* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39311* [@https://tools.ietf.org/html/rfc6455#section-7.1.2 Websocket Closing Handshake (RFC6455)] 39312* [@https://tools.ietf.org/html/rfc6455#section-5.5.1 Websocket Close (RFC6455)] 39313* [@https://tools.ietf.org/html/rfc6455#section-5.5.2 WebSocket Ping (RFC6455)] 39314* [@https://tools.ietf.org/html/rfc6455#section-5.5.3 WebSocket Pong (RFC6455)] 39315* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 39316* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 39317* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 39318 39319 39320[section:accept websocket::stream::accept] 39321[indexterm2 accept..websocket::stream] 39322Perform the WebSocket handshake in the server role. ``` 39323void 39324``[link beast.ref.boost__beast__websocket__stream.accept.overload1 accept]``(); 39325 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload1 more...]]`` 39326 39327``` 39328Read and respond to a WebSocket HTTP Upgrade request. ``` 39329void 39330``[link beast.ref.boost__beast__websocket__stream.accept.overload2 accept]``( 39331 error_code& ec); 39332 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload2 more...]]`` 39333 39334template< 39335 class __ConstBufferSequence__> 39336void 39337``[link beast.ref.boost__beast__websocket__stream.accept.overload3 accept]``( 39338 ConstBufferSequence const& buffers); 39339 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload3 more...]]`` 39340 39341template< 39342 class __ConstBufferSequence__> 39343void 39344``[link beast.ref.boost__beast__websocket__stream.accept.overload4 accept]``( 39345 ConstBufferSequence const& buffers, 39346 error_code& ec); 39347 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload4 more...]]`` 39348 39349``` 39350Respond to a WebSocket HTTP Upgrade request. ``` 39351template< 39352 class __Body__, 39353 class __Allocator__> 39354void 39355``[link beast.ref.boost__beast__websocket__stream.accept.overload5 accept]``( 39356 http::request< Body, http::basic_fields< Allocator >> const& req); 39357 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload5 more...]]`` 39358 39359template< 39360 class __Body__, 39361 class __Allocator__> 39362void 39363``[link beast.ref.boost__beast__websocket__stream.accept.overload6 accept]``( 39364 http::request< Body, http::basic_fields< Allocator >> const& req, 39365 error_code& ec); 39366 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.accept.overload6 more...]]`` 39367``` 39368[section:overload1 websocket::stream::accept (1 of 6 overloads)] 39369Perform the WebSocket handshake in the server role. 39370[heading Synopsis] 39371``` 39372void 39373accept(); 39374``` 39375 39376[heading Description] 39377This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39378The call blocks until one of the following conditions is true: 39379 39380* The request is received and the response is sent. 39381 39382 39383* An error occurs. 39384 39385The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39386If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39387If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__read `http::read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39388[heading Exceptions] 39389[table [[Type][Thrown On]] 39390 [[`system_error`][ 39391 39392Thrown on failure. 39393 ]] 39394] 39395[heading See Also] 39396 39397* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39398 39399 39400[endsect] 39401[section:overload2 websocket::stream::accept (2 of 6 overloads)] 39402Read and respond to a WebSocket HTTP Upgrade request. 39403[heading Synopsis] 39404``` 39405void 39406accept( 39407 error_code& ec); 39408``` 39409 39410[heading Description] 39411This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39412The call blocks until one of the following conditions is true: 39413 39414* The request is received and the response is sent. 39415 39416 39417* An error occurs. 39418 39419The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39420If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39421If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__read `http::read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39422[heading Parameters] 39423[table [[Name][Description]] 39424 [[`ec`][ 39425 39426Set to indicate what error occurred, if any. 39427 ]] 39428] 39429[heading See Also] 39430 39431* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39432 39433 39434[endsect] 39435[section:overload3 websocket::stream::accept (3 of 6 overloads)] 39436Read and respond to a WebSocket HTTP Upgrade request. 39437[heading Synopsis] 39438``` 39439template< 39440 class __ConstBufferSequence__> 39441void 39442accept( 39443 ConstBufferSequence const& buffers); 39444``` 39445 39446[heading Description] 39447This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39448The call blocks until one of the following conditions is true: 39449 39450* The request is received and the response is sent. 39451 39452 39453* An error occurs. 39454 39455The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39456If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39457If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__read `http::read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39458[heading Parameters] 39459[table [[Name][Description]] 39460 [[`buffers`][ 39461 39462Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns. 39463 ]] 39464] 39465[heading Exceptions] 39466[table [[Type][Thrown On]] 39467 [[`system_error`][ 39468 39469Thrown on failure. 39470 ]] 39471] 39472[heading See Also] 39473 39474* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39475 39476 39477[endsect] 39478[section:overload4 websocket::stream::accept (4 of 6 overloads)] 39479Read and respond to a WebSocket HTTP Upgrade request. 39480[heading Synopsis] 39481``` 39482template< 39483 class __ConstBufferSequence__> 39484void 39485accept( 39486 ConstBufferSequence const& buffers, 39487 error_code& ec); 39488``` 39489 39490[heading Description] 39491This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39492The call blocks until one of the following conditions is true: 39493 39494* The request is received and the response is sent. 39495 39496 39497* An error occurs. 39498 39499The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39500If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39501If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__read `http::read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39502[heading Parameters] 39503[table [[Name][Description]] 39504 [[`buffers`][ 39505 39506Caller provided data that has already been received on the stream. The implementation will copy the caller provided data before the function returns. 39507 ]] 39508 [[`ec`][ 39509 39510Set to indicate what error occurred, if any. 39511 ]] 39512] 39513[heading See Also] 39514 39515* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39516 39517 39518[endsect] 39519[section:overload5 websocket::stream::accept (5 of 6 overloads)] 39520Respond to a WebSocket HTTP Upgrade request. 39521[heading Synopsis] 39522``` 39523template< 39524 class __Body__, 39525 class __Allocator__> 39526void 39527accept( 39528 http::request< Body, http::basic_fields< Allocator >> const& req); 39529``` 39530 39531[heading Description] 39532This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39533The call blocks until one of the following conditions is true: 39534 39535* The response is sent. 39536 39537 39538* An error occurs. 39539 39540The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39541If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39542[heading Parameters] 39543[table [[Name][Description]] 39544 [[`req`][ 39545 39546An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads. 39547 ]] 39548] 39549[heading Exceptions] 39550[table [[Type][Thrown On]] 39551 [[`system_error`][ 39552 39553Thrown on failure. 39554 ]] 39555] 39556[heading See Also] 39557 39558* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39559 39560 39561[endsect] 39562[section:overload6 websocket::stream::accept (6 of 6 overloads)] 39563Respond to a WebSocket HTTP Upgrade request. 39564[heading Synopsis] 39565``` 39566template< 39567 class __Body__, 39568 class __Allocator__> 39569void 39570accept( 39571 http::request< Body, http::basic_fields< Allocator >> const& req, 39572 error_code& ec); 39573``` 39574 39575[heading Description] 39576This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39577The call blocks until one of the following conditions is true: 39578 39579* The response is sent. 39580 39581 39582* An error occurs. 39583 39584The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 39585If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39586[heading Parameters] 39587[table [[Name][Description]] 39588 [[`req`][ 39589 39590An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads. 39591 ]] 39592 [[`ec`][ 39593 39594Set to indicate what error occurred, if any. 39595 ]] 39596] 39597[heading See Also] 39598 39599* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39600 39601 39602[endsect] 39603[endsect] 39604 39605[section:async_accept websocket::stream::async_accept] 39606[indexterm2 async_accept..websocket::stream] 39607Perform the WebSocket handshake asynchronously in the server role. ``` 39608template< 39609 class AcceptHandler = net::default_completion_token_t<executor_type>> 39610``__deduced__`` 39611``[link beast.ref.boost__beast__websocket__stream.async_accept.overload1 async_accept]``( 39612 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39613 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_accept.overload1 more...]]`` 39614 39615template< 39616 class __ConstBufferSequence__, 39617 class AcceptHandler = net::default_completion_token_t<executor_type>> 39618``__deduced__`` 39619``[link beast.ref.boost__beast__websocket__stream.async_accept.overload2 async_accept]``( 39620 ConstBufferSequence const& buffers, 39621 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39622 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_accept.overload2 more...]]`` 39623 39624template< 39625 class __Body__, 39626 class __Allocator__, 39627 class AcceptHandler = net::default_completion_token_t<executor_type>> 39628``__deduced__`` 39629``[link beast.ref.boost__beast__websocket__stream.async_accept.overload3 async_accept]``( 39630 http::request< Body, http::basic_fields< Allocator >> const& req, 39631 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39632 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_accept.overload3 more...]]`` 39633``` 39634[section:overload1 websocket::stream::async_accept (1 of 3 overloads)] 39635Perform the WebSocket handshake asynchronously in the server role. 39636[heading Synopsis] 39637``` 39638template< 39639 class AcceptHandler = net::default_completion_token_t<executor_type>> 39640``__deduced__`` 39641async_accept( 39642 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39643``` 39644 39645[heading Description] 39646This initiating function is used to asynchronously begin performing the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39647This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39648 39649* The request is received and the response is sent. 39650 39651 39652* An error occurs. 39653 39654The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. No other operation may be performed on the stream until this operation completes. 39655If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39656If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__async_read `http::async_read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39657[heading Parameters] 39658[table [[Name][Description]] 39659 [[`handler`][ 39660 39661The 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: 39662``` 39663 void handler( 39664 error_code const& ec // Result of operation 39665 ); 39666``` 39667Regardless 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 `net::post`. 39668 ]] 39669] 39670[heading See Also] 39671 39672* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39673 39674 39675[endsect] 39676[section:overload2 websocket::stream::async_accept (2 of 3 overloads)] 39677Perform the WebSocket handshake asynchronously in the server role. 39678[heading Synopsis] 39679``` 39680template< 39681 class __ConstBufferSequence__, 39682 class AcceptHandler = net::default_completion_token_t<executor_type>> 39683``__deduced__`` 39684async_accept( 39685 ConstBufferSequence const& buffers, 39686 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39687``` 39688 39689[heading Description] 39690This initiating function is used to asynchronously begin performing the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39691This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39692 39693* The request is received and the response is sent. 39694 39695 39696* An error occurs. 39697 39698The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. No other operation may be performed on the stream until this operation completes. 39699If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39700If the request size exceeds the capacity of the stream's internal buffer, the error [link beast.ref.boost__beast__websocket__error `websocket::buffer_overflow`] will be indicated. To handle larger requests, an application should read the HTTP request directly using [link beast.ref.boost__beast__http__async_read `http::async_read`] and then pass the request to the appropriate overload of [link beast.ref.boost__beast__websocket__stream.accept `websocket::stream::accept`] or [link beast.ref.boost__beast__websocket__stream.async_accept `websocket::stream::async_accept`] 39701[heading Parameters] 39702[table [[Name][Description]] 39703 [[`buffers`][ 39704 39705Caller provided data that has already been received on the stream. This may be used for implementations allowing multiple protocols on the same stream. The buffered data will first be applied to the handshake, and then to received WebSocket frames. The implementation will copy the caller provided data before the function returns. 39706 ]] 39707 [[`handler`][ 39708 39709The 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: 39710``` 39711 void handler( 39712 error_code const& ec // Result of operation 39713 ); 39714``` 39715Regardless 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 `net::post`. 39716 ]] 39717] 39718[heading See Also] 39719 39720* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39721 39722 39723[endsect] 39724[section:overload3 websocket::stream::async_accept (3 of 3 overloads)] 39725Perform the WebSocket handshake asynchronously in the server role. 39726[heading Synopsis] 39727``` 39728template< 39729 class __Body__, 39730 class __Allocator__, 39731 class AcceptHandler = net::default_completion_token_t<executor_type>> 39732``__deduced__`` 39733async_accept( 39734 http::request< Body, http::basic_fields< Allocator >> const& req, 39735 AcceptHandler&& handler = net::default_completion_token_t< executor_type >{}); 39736``` 39737 39738[heading Description] 39739This initiating function is used to asynchronously begin performing the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39740This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39741 39742* The request is received and the response is sent. 39743 39744 39745* An error occurs. 39746 39747The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. No other operation may be performed on the stream until this operation completes. 39748If a valid upgrade request is received, an HTTP response with a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`] is sent to the peer, otherwise a non-successful error is associated with the operation. 39749[heading Parameters] 39750[table [[Name][Description]] 39751 [[`req`][ 39752 39753An object containing the HTTP Upgrade request. Ownership is not transferred, the implementation will not access this object from other threads. 39754 ]] 39755 [[`handler`][ 39756 39757The 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: 39758``` 39759 void handler( 39760 error_code const& ec // Result of operation 39761 ); 39762``` 39763Regardless 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 `net::post`. 39764 ]] 39765] 39766[heading See Also] 39767 39768* [@https://tools.ietf.org/html/rfc6455#section-4.2 Websocket Opening Handshake Server Requirements (RFC6455)] 39769 39770 39771[endsect] 39772[endsect] 39773 39774[section:async_close websocket::stream::async_close] 39775[indexterm2 async_close..websocket::stream] 39776Send a websocket close control frame asynchronously. 39777[heading Synopsis] 39778``` 39779template< 39780 class CloseHandler = net::default_completion_token_t<executor_type>> 39781``__deduced__`` 39782async_close( 39783 close_reason const& cr, 39784 CloseHandler&& handler = net::default_completion_token_t< executor_type >{}); 39785``` 39786 39787[heading Description] 39788This function is used to asynchronously send a [@https://tools.ietf.org/html/rfc6455#section-5.5.1 close frame], which begins the websocket closing handshake. The session ends when both ends of the connection have sent and received a close frame. 39789This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39790 39791* The close frame finishes sending. 39792 39793 39794* An error occurs. 39795 39796The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. No other operations except for message reading operations should be initiated on the stream after a close operation is started. 39797After beginning the closing handshake, the program should not write further message data, pings, or pongs. Instead, the program should continue reading message data until an error occurs. A read returning [link beast.ref.boost__beast__websocket__error `websocket::closed`] indicates a successful connection closure. 39798[heading Parameters] 39799[table [[Name][Description]] 39800 [[`cr`][ 39801 39802The reason for the close. If the close reason specifies a close code other than beast::websocket::close\_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload. 39803 ]] 39804 [[`handler`][ 39805 39806The 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: 39807``` 39808 void handler( 39809 error_code const& ec // Result of operation 39810 ); 39811``` 39812Regardless 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 `net::post`. 39813 ]] 39814] 39815[heading See Also] 39816 39817* [@https://tools.ietf.org/html/rfc6455#section-7.1.2 Websocket Closing Handshake (RFC6455)] 39818 39819 39820[endsect] 39821[section:async_handshake websocket::stream::async_handshake] 39822[indexterm2 async_handshake..websocket::stream] 39823Perform the WebSocket handshake asynchronously in the client role. ``` 39824template< 39825 class HandshakeHandler = net::default_completion_token_t<executor_type>> 39826``__deduced__`` 39827``[link beast.ref.boost__beast__websocket__stream.async_handshake.overload1 async_handshake]``( 39828 string_view host, 39829 string_view target, 39830 HandshakeHandler&& handler = net::default_completion_token_t< executor_type >{}); 39831 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_handshake.overload1 more...]]`` 39832 39833template< 39834 class HandshakeHandler = net::default_completion_token_t<executor_type>> 39835``__deduced__`` 39836``[link beast.ref.boost__beast__websocket__stream.async_handshake.overload2 async_handshake]``( 39837 response_type& res, 39838 string_view host, 39839 string_view target, 39840 HandshakeHandler&& handler = net::default_completion_token_t< executor_type >{}); 39841 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_handshake.overload2 more...]]`` 39842``` 39843[section:overload1 websocket::stream::async_handshake (1 of 2 overloads)] 39844Perform the WebSocket handshake asynchronously in the client role. 39845[heading Synopsis] 39846``` 39847template< 39848 class HandshakeHandler = net::default_completion_token_t<executor_type>> 39849``__deduced__`` 39850async_handshake( 39851 string_view host, 39852 string_view target, 39853 HandshakeHandler&& handler = net::default_completion_token_t< executor_type >{}); 39854``` 39855 39856[heading Description] 39857This initiating function is used to asynchronously begin performing the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39858This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39859 39860* The request is sent and the response is received. 39861 39862 39863* An error occurs. 39864 39865The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. No other operation may be performed on the stream until this operation completes. 39866The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 39867[heading Parameters] 39868[table [[Name][Description]] 39869 [[`host`][ 39870 39871The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. The implementation will not access the string data after the initiating function returns. 39872 ]] 39873 [[`target`][ 39874 39875The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. The implementation will not access the string data after the initiating function returns. 39876 ]] 39877 [[`handler`][ 39878 39879The 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: 39880``` 39881 void handler( 39882 error_code const& ec // Result of operation 39883 ); 39884``` 39885Regardless 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 `net::post`. 39886 ]] 39887] 39888[heading Example] 39889 39890``` 39891 ws.async_handshake("localhost", "/", 39892 [](error_code ec) 39893 { 39894 if(ec) 39895 std::cerr << "Error: " << ec.message() << "\n"; 39896 }); 39897``` 39898[heading See Also] 39899 39900* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 39901* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 39902* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 39903* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 39904 39905 39906[endsect] 39907[section:overload2 websocket::stream::async_handshake (2 of 2 overloads)] 39908Perform the WebSocket handshake asynchronously in the client role. 39909[heading Synopsis] 39910``` 39911template< 39912 class HandshakeHandler = net::default_completion_token_t<executor_type>> 39913``__deduced__`` 39914async_handshake( 39915 response_type& res, 39916 string_view host, 39917 string_view target, 39918 HandshakeHandler&& handler = net::default_completion_token_t< executor_type >{}); 39919``` 39920 39921[heading Description] 39922This initiating function is used to asynchronously begin performing the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 39923This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 39924 39925* The request is sent and the response is received. 39926 39927 39928* An error occurs. 39929 39930The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. No other operation may be performed on the stream until this operation completes. 39931The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 39932[heading Parameters] 39933[table [[Name][Description]] 39934 [[`res`][ 39935 39936The HTTP Upgrade response returned by the remote endpoint. The caller may use the response to access any additional information sent by the server. This object will be assigned before the completion handler is invoked. 39937 ]] 39938 [[`host`][ 39939 39940The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. The implementation will not access the string data after the initiating function returns. 39941 ]] 39942 [[`target`][ 39943 39944The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. The implementation will not access the string data after the initiating function returns. 39945 ]] 39946 [[`handler`][ 39947 39948The 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: 39949``` 39950 void handler( 39951 error_code const& ec // Result of operation 39952 ); 39953``` 39954Regardless 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 `net::post`. 39955 ]] 39956] 39957[heading Example] 39958 39959``` 39960 response_type res; 39961 ws.async_handshake(res, "localhost", "/", 39962 [&res](error_code ec) 39963 { 39964 if(ec) 39965 std::cerr << "Error: " << ec.message() << "\n"; 39966 else 39967 std::cout << res; 39968 39969 }); 39970``` 39971[heading See Also] 39972 39973* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 39974* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 39975* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 39976* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 39977 39978 39979[endsect] 39980[endsect] 39981 39982[section:async_ping websocket::stream::async_ping] 39983[indexterm2 async_ping..websocket::stream] 39984Send a websocket ping control frame asynchronously. 39985[heading Synopsis] 39986``` 39987template< 39988 class __WriteHandler__ = net::default_completion_token_t<executor_type>> 39989``__deduced__`` 39990async_ping( 39991 ping_data const& payload, 39992 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 39993``` 39994 39995[heading Description] 39996This function is used to asynchronously send a [@https://tools.ietf.org/html/rfc6455#section-5.5.2 ping frame], which usually elicits an automatic pong control frame response from the peer. 39997 39998* The ping frame is written. 39999 40000 40001* An error occurs. 40002 40003The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.ping `websocket::stream::ping`], [link beast.ref.boost__beast__websocket__stream.pong `websocket::stream::pong`], [link beast.ref.boost__beast__websocket__stream.async_ping `websocket::stream::async_ping`], or [link beast.ref.boost__beast__websocket__stream.async_pong `websocket::stream::async_pong`] are performed until this operation completes. 40004If a close frame is sent or received before the ping frame is sent, the error received by this completion handler will be `net::error::operation_aborted`. 40005[heading Parameters] 40006[table [[Name][Description]] 40007 [[`payload`][ 40008 40009The payload of the ping message, which may be empty. The implementation will not access the contents of this object after the initiating function returns. 40010 ]] 40011 [[`handler`][ 40012 40013The 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: 40014``` 40015 void handler( 40016 error_code const& ec // Result of operation 40017 ); 40018``` 40019Regardless 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 `net::post`. 40020 ]] 40021] 40022[endsect] 40023[section:async_pong websocket::stream::async_pong] 40024[indexterm2 async_pong..websocket::stream] 40025Send a websocket pong control frame asynchronously. 40026[heading Synopsis] 40027``` 40028template< 40029 class __WriteHandler__ = net::default_completion_token_t<executor_type>> 40030``__deduced__`` 40031async_pong( 40032 ping_data const& payload, 40033 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 40034``` 40035 40036[heading Description] 40037This function is used to asynchronously send a [@https://tools.ietf.org/html/rfc6455#section-5.5.3 pong frame], which is usually sent automatically in response to a ping frame from the remote peer. 40038 40039* The pong frame is written. 40040 40041 40042* An error occurs. 40043 40044The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.ping `websocket::stream::ping`], [link beast.ref.boost__beast__websocket__stream.pong `websocket::stream::pong`], [link beast.ref.boost__beast__websocket__stream.async_ping `websocket::stream::async_ping`], or [link beast.ref.boost__beast__websocket__stream.async_pong `websocket::stream::async_pong`] are performed until this operation completes. 40045If a close frame is sent or received before the pong frame is sent, the error received by this completion handler will be `net::error::operation_aborted`. 40046WebSocket allows pong frames to be sent at any time, without first receiving a ping. An unsolicited pong sent in this fashion may indicate to the remote peer that the connection is still active. 40047[heading Parameters] 40048[table [[Name][Description]] 40049 [[`payload`][ 40050 40051The payload of the pong message, which may be empty. The implementation will not access the contents of this object after the initiating function returns. 40052 ]] 40053 [[`handler`][ 40054 40055The 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: 40056``` 40057 void handler( 40058 error_code const& ec // Result of operation 40059 ); 40060``` 40061Regardless 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 `net::post`. 40062 ]] 40063] 40064[endsect] 40065[section:async_read websocket::stream::async_read] 40066[indexterm2 async_read..websocket::stream] 40067Read a complete message asynchronously. 40068[heading Synopsis] 40069``` 40070template< 40071 class __DynamicBuffer__, 40072 class __ReadHandler__ = net::default_completion_token_t< executor_type>> 40073``__deduced__`` 40074async_read( 40075 DynamicBuffer& buffer, 40076 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 40077``` 40078 40079[heading Description] 40080This function is used to asynchronously read a complete message. 40081This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 40082 40083* A complete message is received. 40084 40085 40086* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 40087 40088 40089* An error occurs. 40090 40091The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.read `websocket::stream::read`], [link beast.ref.boost__beast__websocket__stream.read_some `websocket::stream::read_some`], [link beast.ref.boost__beast__websocket__stream.async_read `websocket::stream::async_read`], or [link beast.ref.boost__beast__websocket__stream.async_read_some `websocket::stream::async_read_some`] are performed until this operation completes. 40092Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. 40093Until the operation completes, the implementation will read incoming control frames and handle them automatically as follows: 40094 40095* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 40096 40097 40098* For each received ping frame, a pong frame will be automatically sent. 40099 40100 40101* If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 40102 40103Pong frames and close frames sent by the implementation while the read operation is outstanding do not prevent the application from also writing message data, sending pings, sending pongs, or sending close frames. 40104[heading Parameters] 40105[table [[Name][Description]] 40106 [[`buffer`][ 40107 40108A dynamic buffer to append message data to. 40109 ]] 40110 [[`handler`][ 40111 40112The 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: 40113``` 40114 void handler( 40115 error_code const& ec, // Result of operation 40116 std::size_t bytes_written // Number of bytes appended to buffer 40117 ); 40118``` 40119Regardless 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 `net::post`. 40120 ]] 40121] 40122[endsect] 40123[section:async_read_some websocket::stream::async_read_some] 40124[indexterm2 async_read_some..websocket::stream] 40125Read some message data asynchronously. ``` 40126template< 40127 class __DynamicBuffer__, 40128 class __ReadHandler__ = net::default_completion_token_t< executor_type>> 40129``__deduced__`` 40130``[link beast.ref.boost__beast__websocket__stream.async_read_some.overload1 async_read_some]``( 40131 DynamicBuffer& buffer, 40132 std::size_t limit, 40133 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 40134 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_read_some.overload1 more...]]`` 40135 40136template< 40137 class __MutableBufferSequence__, 40138 class __ReadHandler__ = net::default_completion_token_t< executor_type>> 40139``__deduced__`` 40140``[link beast.ref.boost__beast__websocket__stream.async_read_some.overload2 async_read_some]``( 40141 MutableBufferSequence const& buffers, 40142 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 40143 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.async_read_some.overload2 more...]]`` 40144``` 40145[section:overload1 websocket::stream::async_read_some (1 of 2 overloads)] 40146Read some message data asynchronously. 40147[heading Synopsis] 40148``` 40149template< 40150 class __DynamicBuffer__, 40151 class __ReadHandler__ = net::default_completion_token_t< executor_type>> 40152``__deduced__`` 40153async_read_some( 40154 DynamicBuffer& buffer, 40155 std::size_t limit, 40156 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 40157``` 40158 40159[heading Description] 40160This function is used to asynchronously read some message data. 40161This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 40162 40163* Some message data is received. 40164 40165 40166* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 40167 40168 40169* An error occurs. 40170 40171The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.read `websocket::stream::read`], [link beast.ref.boost__beast__websocket__stream.read_some `websocket::stream::read_some`], [link beast.ref.boost__beast__websocket__stream.async_read `websocket::stream::async_read`], or [link beast.ref.boost__beast__websocket__stream.async_read_some `websocket::stream::async_read_some`] are performed until this operation completes. 40172Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. 40173Until the operation completes, the implementation will read incoming control frames and handle them automatically as follows: 40174 40175* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 40176 40177 40178* For each received ping frame, a pong frame will be automatically sent. 40179 40180 40181* If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 40182 40183Pong frames and close frames sent by the implementation while the read operation is outstanding do not prevent the application from also writing message data, sending pings, sending pongs, or sending close frames. 40184[heading Parameters] 40185[table [[Name][Description]] 40186 [[`buffer`][ 40187 40188A dynamic buffer to append message data to. 40189 ]] 40190 [[`limit`][ 40191 40192An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically. 40193 ]] 40194 [[`handler`][ 40195 40196The 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: 40197``` 40198 void handler( 40199 error_code const& ec, // Result of operation 40200 std::size_t bytes_written // Number of bytes appended to buffer 40201 ); 40202``` 40203Regardless 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 `net::post`. 40204 ]] 40205] 40206[endsect] 40207[section:overload2 websocket::stream::async_read_some (2 of 2 overloads)] 40208Read some message data asynchronously. 40209[heading Synopsis] 40210``` 40211template< 40212 class __MutableBufferSequence__, 40213 class __ReadHandler__ = net::default_completion_token_t< executor_type>> 40214``__deduced__`` 40215async_read_some( 40216 MutableBufferSequence const& buffers, 40217 ReadHandler&& handler = net::default_completion_token_t< executor_type >{}); 40218``` 40219 40220[heading Description] 40221This function is used to asynchronously read some message data. 40222This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 40223 40224* Some message data is received. 40225 40226 40227* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 40228 40229 40230* An error occurs. 40231 40232The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_read_some` and `async_write_some` functions. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.read `websocket::stream::read`], [link beast.ref.boost__beast__websocket__stream.read_some `websocket::stream::read_some`], [link beast.ref.boost__beast__websocket__stream.async_read `websocket::stream::async_read`], or [link beast.ref.boost__beast__websocket__stream.async_read_some `websocket::stream::async_read_some`] are performed until this operation completes. 40233Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. 40234Until the operation completes, the implementation will read incoming control frames and handle them automatically as follows: 40235 40236* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 40237 40238 40239* For each received ping frame, a pong frame will be automatically sent. 40240 40241 40242* If a close frame is received, the WebSocket close procedure is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 40243 40244Pong frames and close frames sent by the implementation while the read operation is outstanding do not prevent the application from also writing message data, sending pings, sending pongs, or sending close frames. 40245[heading Parameters] 40246[table [[Name][Description]] 40247 [[`buffers`][ 40248 40249A buffer sequence to write message data into. The previous contents of the buffers will be overwritten, starting from the beginning. The implementation will make copies of this object as needed, but but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by the buffer sequence remain valid until the completion handler is called. 40250 ]] 40251 [[`handler`][ 40252 40253The 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: 40254``` 40255 void handler( 40256 error_code const& ec, // Result of operation 40257 std::size_t bytes_written // Number of bytes written to the buffers 40258 ); 40259``` 40260Regardless 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 `net::post`. 40261 ]] 40262] 40263[endsect] 40264[endsect] 40265 40266[section:async_write websocket::stream::async_write] 40267[indexterm2 async_write..websocket::stream] 40268Write a complete message asynchronously. 40269[heading Synopsis] 40270``` 40271template< 40272 class __ConstBufferSequence__, 40273 class __WriteHandler__ = net::default_completion_token_t< executor_type>> 40274``__deduced__`` 40275async_write( 40276 ConstBufferSequence const& buffers, 40277 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 40278``` 40279 40280[heading Description] 40281This function is used to asynchronously write a complete message. 40282This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 40283 40284* The complete message is written. 40285 40286 40287* An error occurs. 40288 40289The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.write `websocket::stream::write`], [link beast.ref.boost__beast__websocket__stream.write_some `websocket::stream::write_some`], [link beast.ref.boost__beast__websocket__stream.async_write `websocket::stream::async_write`], or [link beast.ref.boost__beast__websocket__stream.async_write_some `websocket::stream::async_write_some`] are performed until this operation completes. 40290The current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] option controls whether the message opcode is set to text or binary. If the [link beast.ref.boost__beast__websocket__stream.auto_fragment `websocket::stream::auto_fragment`] option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings. 40291[heading Parameters] 40292[table [[Name][Description]] 40293 [[`buffers`][ 40294 40295A buffer sequence containing the entire message payload. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by buffers remains valid until the completion handler is called. 40296 ]] 40297 [[`handler`][ 40298 40299The 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: 40300``` 40301 void handler( 40302 error_code const& ec, // Result of operation 40303 std::size_t bytes_transferred // Number of bytes sent from the 40304 // buffers. If an error occurred, 40305 // this will be less than the buffer_size. 40306 ); 40307``` 40308Regardless 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 `net::post`. 40309 ]] 40310] 40311[endsect] 40312[section:async_write_some websocket::stream::async_write_some] 40313[indexterm2 async_write_some..websocket::stream] 40314Write some message data asynchronously. 40315[heading Synopsis] 40316``` 40317template< 40318 class __ConstBufferSequence__, 40319 class __WriteHandler__ = net::default_completion_token_t< executor_type>> 40320``__deduced__`` 40321async_write_some( 40322 bool fin, 40323 ConstBufferSequence const& buffers, 40324 WriteHandler&& handler = net::default_completion_token_t< executor_type >{}); 40325``` 40326 40327[heading Description] 40328This function is used to asynchronously write part of a message. 40329This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: 40330 40331* The message data is written. 40332 40333 40334* An error occurs. 40335 40336The algorithm, known as a ['composed asynchronous operation], is implemented in terms of calls to the next layer's `async_write_some` function. The program must ensure that no other calls to [link beast.ref.boost__beast__websocket__stream.write `websocket::stream::write`], [link beast.ref.boost__beast__websocket__stream.write_some `websocket::stream::write_some`], [link beast.ref.boost__beast__websocket__stream.async_write `websocket::stream::async_write`], or [link beast.ref.boost__beast__websocket__stream.async_write_some `websocket::stream::async_write_some`] are performed until this operation completes. 40337If this is the beginning of a new message, the message opcode will be set to text or binary based on the current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] (or [link beast.ref.boost__beast__websocket__stream.text `websocket::stream::text`]) option. The actual payload sent may be transformed as per the WebSocket protocol settings. 40338[heading Parameters] 40339[table [[Name][Description]] 40340 [[`fin`][ 40341 40342`true` if this is the last part of the message. 40343 ]] 40344 [[`buffers`][ 40345 40346The buffers containing the message part to send. The implementation will make copies of this object as needed, but ownership of the underlying memory is not transferred. The caller is responsible for ensuring that the memory locations pointed to by buffers remains valid until the completion handler is called. 40347 ]] 40348 [[`handler`][ 40349 40350The 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: 40351``` 40352 void handler( 40353 error_code const& ec, // Result of operation 40354 std::size_t bytes_transferred // Number of bytes sent from the 40355 // buffers. If an error occurred, 40356 // this will be less than the buffer_size. 40357 ); 40358``` 40359Regardless 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 `net::post`. 40360 ]] 40361] 40362[endsect] 40363[section:auto_fragment websocket::stream::auto_fragment] 40364[indexterm2 auto_fragment..websocket::stream] 40365Set the automatic fragmentation option. ``` 40366void 40367``[link beast.ref.boost__beast__websocket__stream.auto_fragment.overload1 auto_fragment]``( 40368 bool value); 40369 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.auto_fragment.overload1 more...]]`` 40370 40371``` 40372Returns `true` if the automatic fragmentation option is set. ``` 40373bool 40374``[link beast.ref.boost__beast__websocket__stream.auto_fragment.overload2 auto_fragment]``() const; 40375 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.auto_fragment.overload2 more...]]`` 40376``` 40377[section:overload1 websocket::stream::auto_fragment (1 of 2 overloads)] 40378Set the automatic fragmentation option. 40379[heading Synopsis] 40380``` 40381void 40382auto_fragment( 40383 bool value); 40384``` 40385 40386[heading Description] 40387Determines if outgoing message payloads are broken up into multiple pieces. 40388When the automatic fragmentation size is turned on, outgoing message payloads are broken up into multiple frames no larger than the write buffer size. 40389The default setting is to fragment messages. 40390[heading Parameters] 40391[table [[Name][Description]] 40392 [[`value`][ 40393 40394A `bool` indicating if auto fragmentation should be on. 40395 ]] 40396] 40397[heading Example] 40398Setting the automatic fragmentation option: 40399``` 40400 ws.auto_fragment(true); 40401``` 40402[endsect] 40403[section:overload2 websocket::stream::auto_fragment (2 of 2 overloads)] 40404Returns `true` if the automatic fragmentation option is set. 40405[heading Synopsis] 40406``` 40407bool 40408auto_fragment() const; 40409``` 40410 40411[heading Description] 40412[endsect] 40413[endsect] 40414 40415[section:binary websocket::stream::binary] 40416[indexterm2 binary..websocket::stream] 40417Set the binary message write option. ``` 40418void 40419``[link beast.ref.boost__beast__websocket__stream.binary.overload1 binary]``( 40420 bool value); 40421 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.binary.overload1 more...]]`` 40422 40423``` 40424Returns `true` if the binary message write option is set. ``` 40425bool 40426``[link beast.ref.boost__beast__websocket__stream.binary.overload2 binary]``() const; 40427 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.binary.overload2 more...]]`` 40428``` 40429[section:overload1 websocket::stream::binary (1 of 2 overloads)] 40430Set the binary message write option. 40431[heading Synopsis] 40432``` 40433void 40434binary( 40435 bool value); 40436``` 40437 40438[heading Description] 40439This controls whether or not outgoing message opcodes are set to binary or text. The setting is only applied at the start when a caller begins a new message. Changing the opcode after a message is started will only take effect after the current message being sent is complete. 40440The default setting is to send text messages. 40441[heading Parameters] 40442[table [[Name][Description]] 40443 [[`value`][ 40444 40445`true` if outgoing messages should indicate binary, or `false` if they should indicate text. 40446 ]] 40447] 40448[heading Example] 40449Setting the message type to binary. 40450``` 40451 ws.binary(true); 40452``` 40453[endsect] 40454[section:overload2 websocket::stream::binary (2 of 2 overloads)] 40455Returns `true` if the binary message write option is set. 40456[heading Synopsis] 40457``` 40458bool 40459binary() const; 40460``` 40461 40462[heading Description] 40463[endsect] 40464[endsect] 40465 40466[section:close websocket::stream::close] 40467[indexterm2 close..websocket::stream] 40468Send a websocket close control frame. ``` 40469void 40470``[link beast.ref.boost__beast__websocket__stream.close.overload1 close]``( 40471 close_reason const& cr); 40472 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.close.overload1 more...]]`` 40473 40474void 40475``[link beast.ref.boost__beast__websocket__stream.close.overload2 close]``( 40476 close_reason const& cr, 40477 error_code& ec); 40478 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.close.overload2 more...]]`` 40479``` 40480[section:overload1 websocket::stream::close (1 of 2 overloads)] 40481Send a websocket close control frame. 40482[heading Synopsis] 40483``` 40484void 40485close( 40486 close_reason const& cr); 40487``` 40488 40489[heading Description] 40490This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.1 close frame], which begins the websocket closing handshake. The session ends when both ends of the connection have sent and received a close frame. 40491The call blocks until one of the following conditions is true: 40492 40493* The close frame is written. 40494 40495 40496* An error occurs. 40497 40498The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 40499After beginning the closing handshake, the program should not write further message data, pings, or pongs. Instead, the program should continue reading message data until an error occurs. A read returning [link beast.ref.boost__beast__websocket__error `websocket::closed`] indicates a successful connection closure. 40500[heading Parameters] 40501[table [[Name][Description]] 40502 [[`cr`][ 40503 40504The reason for the close. If the close reason specifies a close code other than beast::websocket::close\_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload. 40505 ]] 40506] 40507[heading Exceptions] 40508[table [[Type][Thrown On]] 40509 [[`system_error`][ 40510 40511Thrown on failure. 40512 ]] 40513] 40514[heading See Also] 40515 40516* [@https://tools.ietf.org/html/rfc6455#section-7.1.2 Websocket Closing Handshake (RFC6455)] 40517 40518 40519[endsect] 40520[section:overload2 websocket::stream::close (2 of 2 overloads)] 40521Send a websocket close control frame. 40522[heading Synopsis] 40523``` 40524void 40525close( 40526 close_reason const& cr, 40527 error_code& ec); 40528``` 40529 40530[heading Description] 40531This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.1 close frame], which begins the websocket closing handshake. The session ends when both ends of the connection have sent and received a close frame. 40532The call blocks until one of the following conditions is true: 40533 40534* The close frame is written. 40535 40536 40537* An error occurs. 40538 40539The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 40540After beginning the closing handshake, the program should not write further message data, pings, or pongs. Instead, the program should continue reading message data until an error occurs. A read returning [link beast.ref.boost__beast__websocket__error `websocket::closed`] indicates a successful connection closure. 40541[heading Parameters] 40542[table [[Name][Description]] 40543 [[`cr`][ 40544 40545The reason for the close. If the close reason specifies a close code other than beast::websocket::close\_code::none, the close frame is sent with the close code and optional reason string. Otherwise, the close frame is sent with no payload. 40546 ]] 40547 [[`ec`][ 40548 40549Set to indicate what error occurred, if any. 40550 ]] 40551] 40552[heading See Also] 40553 40554* [@https://tools.ietf.org/html/rfc6455#section-7.1.2 Websocket Closing Handshake (RFC6455)] 40555 40556 40557[endsect] 40558[endsect] 40559 40560[section:control_callback websocket::stream::control_callback] 40561[indexterm2 control_callback..websocket::stream] 40562Set a callback to be invoked on each incoming control frame. ``` 40563void 40564``[link beast.ref.boost__beast__websocket__stream.control_callback.overload1 control_callback]``( 40565 std::function< void(frame_type, string_view)> cb); 40566 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.control_callback.overload1 more...]]`` 40567 40568``` 40569Reset the control frame callback. ``` 40570void 40571``[link beast.ref.boost__beast__websocket__stream.control_callback.overload2 control_callback]``(); 40572 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.control_callback.overload2 more...]]`` 40573``` 40574[section:overload1 websocket::stream::control_callback (1 of 2 overloads)] 40575Set a callback to be invoked on each incoming control frame. 40576[heading Synopsis] 40577``` 40578void 40579control_callback( 40580 std::function< void(frame_type, string_view)> cb); 40581``` 40582 40583[heading Description] 40584Sets the callback to be invoked whenever a ping, pong, or close control frame is received during a call to one of the following functions: 40585 40586* [link beast.ref.boost__beast__websocket__stream.read `websocket::stream::read`] 40587* [link beast.ref.boost__beast__websocket__stream.read_some `websocket::stream::read_some`] 40588* [link beast.ref.boost__beast__websocket__stream.async_read `websocket::stream::async_read`] 40589* [link beast.ref.boost__beast__websocket__stream.async_read_some `websocket::stream::async_read_some`] 40590 40591Unlike completion handlers, the callback will be invoked for each control frame during a call to any synchronous or asynchronous read function. The operation is passive, with no associated error code, and triggered by reads. 40592For close frames, the close reason code may be obtained by calling the function [link beast.ref.boost__beast__websocket__stream.reason `websocket::stream::reason`]. 40593[heading Parameters] 40594[table [[Name][Description]] 40595 [[`cb`][ 40596 40597The function object to call, which must be invocable with this equivalent signature: 40598``` 40599 void 40600 callback( 40601 frame_type kind, // The type of frame 40602 string_view payload // The payload in the frame 40603 ); 40604``` 40605The implementation type-erases the callback which may require a dynamic allocation. To prevent the possibility of a dynamic allocation, use `std::ref` to wrap the callback. If the read operation which receives the control frame is an asynchronous operation, the callback will be invoked using the same method as that used to invoke the final handler. 40606 ]] 40607] 40608[heading Remarks] 40609Incoming ping and close frames are automatically handled. Pings are responded to with pongs, and a close frame is responded to with a close frame leading to the closure of the stream. It is not necessary to manually send pings, pongs, or close frames from inside the control callback. Attempting to manually send a close frame from inside the control callback after receiving a close frame will result in undefined behavior. 40610[endsect] 40611[section:overload2 websocket::stream::control_callback (2 of 2 overloads)] 40612Reset the control frame callback. 40613[heading Synopsis] 40614``` 40615void 40616control_callback(); 40617``` 40618 40619[heading Description] 40620This function removes any previously set control frame callback. [endsect] 40621[endsect] 40622 40623[section:executor_type websocket::stream::executor_type] 40624[indexterm2 executor_type..websocket::stream] 40625The type of the executor associated with the object. 40626[heading Synopsis] 40627 40628``` 40629using executor_type = beast::executor_type< next_layer_type >; 40630``` 40631 40632[heading Description] 40633[endsect] 40634[section:get_executor websocket::stream::get_executor] 40635[indexterm2 get_executor..websocket::stream] 40636Get the executor associated with the object. 40637[heading Synopsis] 40638``` 40639executor_type 40640get_executor(); 40641``` 40642 40643[heading Description] 40644This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations. 40645[heading Return Value] 40646A copy of the executor that stream will use to dispatch handlers. 40647[endsect] 40648[section:get_option websocket::stream::get_option] 40649[indexterm2 get_option..websocket::stream] 40650``` 40651template< 40652 class Option> 40653void 40654``[link beast.ref.boost__beast__websocket__stream.get_option.overload1 get_option]``( 40655 Option& opt); 40656 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.get_option.overload1 more...]]`` 40657 40658``` 40659Get the permessage-deflate extension options. ``` 40660void 40661``[link beast.ref.boost__beast__websocket__stream.get_option.overload2 get_option]``( 40662 permessage_deflate& o); 40663 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.get_option.overload2 more...]]`` 40664``` 40665[section:overload1 websocket::stream::get_option (1 of 2 overloads)] 40666 40667[heading Synopsis] 40668``` 40669template< 40670 class Option> 40671void 40672get_option( 40673 Option& opt); 40674``` 40675 40676[heading Description] 40677[endsect] 40678[section:overload2 websocket::stream::get_option (2 of 2 overloads)] 40679Get the permessage-deflate extension options. 40680[heading Synopsis] 40681``` 40682void 40683get_option( 40684 permessage_deflate& o); 40685``` 40686 40687[heading Description] 40688[endsect] 40689[endsect] 40690 40691[section:got_binary websocket::stream::got_binary] 40692[indexterm2 got_binary..websocket::stream] 40693Returns `true` if the latest message data indicates binary. 40694[heading Synopsis] 40695``` 40696bool 40697got_binary() const; 40698``` 40699 40700[heading Description] 40701This function informs the caller of whether the last received message frame represents a message with the binary opcode. 40702If there is no last message frame, the return value is undefined. [endsect] 40703[section:got_text websocket::stream::got_text] 40704[indexterm2 got_text..websocket::stream] 40705Returns `true` if the latest message data indicates text. 40706[heading Synopsis] 40707``` 40708bool 40709got_text() const; 40710``` 40711 40712[heading Description] 40713This function informs the caller of whether the last received message frame represents a message with the text opcode. 40714If there is no last message frame, the return value is undefined. [endsect] 40715[section:handshake websocket::stream::handshake] 40716[indexterm2 handshake..websocket::stream] 40717Perform the WebSocket handshake in the client role. ``` 40718void 40719``[link beast.ref.boost__beast__websocket__stream.handshake.overload1 handshake]``( 40720 string_view host, 40721 string_view target); 40722 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.handshake.overload1 more...]]`` 40723 40724void 40725``[link beast.ref.boost__beast__websocket__stream.handshake.overload2 handshake]``( 40726 response_type& res, 40727 string_view host, 40728 string_view target); 40729 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.handshake.overload2 more...]]`` 40730 40731void 40732``[link beast.ref.boost__beast__websocket__stream.handshake.overload3 handshake]``( 40733 string_view host, 40734 string_view target, 40735 error_code& ec); 40736 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.handshake.overload3 more...]]`` 40737 40738void 40739``[link beast.ref.boost__beast__websocket__stream.handshake.overload4 handshake]``( 40740 response_type& res, 40741 string_view host, 40742 string_view target, 40743 error_code& ec); 40744 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.handshake.overload4 more...]]`` 40745``` 40746[section:overload1 websocket::stream::handshake (1 of 4 overloads)] 40747Perform the WebSocket handshake in the client role. 40748[heading Synopsis] 40749``` 40750void 40751handshake( 40752 string_view host, 40753 string_view target); 40754``` 40755 40756[heading Description] 40757This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 40758The call blocks until one of the following conditions is true: 40759 40760* The request is sent and the response is received. 40761 40762 40763* An error occurs. 40764 40765The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 40766The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 40767[heading Parameters] 40768[table [[Name][Description]] 40769 [[`host`][ 40770 40771The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. 40772 ]] 40773 [[`target`][ 40774 40775The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. 40776 ]] 40777] 40778[heading Exceptions] 40779[table [[Type][Thrown On]] 40780 [[`system_error`][ 40781 40782Thrown on failure. 40783 ]] 40784] 40785[heading Example] 40786 40787``` 40788 ws.handshake("localhost", "/"); 40789``` 40790[heading See Also] 40791 40792* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 40793* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 40794* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 40795* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 40796 40797 40798[endsect] 40799[section:overload2 websocket::stream::handshake (2 of 4 overloads)] 40800Perform the WebSocket handshake in the client role. 40801[heading Synopsis] 40802``` 40803void 40804handshake( 40805 response_type& res, 40806 string_view host, 40807 string_view target); 40808``` 40809 40810[heading Description] 40811This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 40812The call blocks until one of the following conditions is true: 40813 40814* The request is sent and the response is received. 40815 40816 40817* An error occurs. 40818 40819The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 40820The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 40821[heading Parameters] 40822[table [[Name][Description]] 40823 [[`res`][ 40824 40825The HTTP Upgrade response returned by the remote endpoint. The caller may use the response to access any additional information sent by the server. 40826 ]] 40827 [[`host`][ 40828 40829The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. 40830 ]] 40831 [[`target`][ 40832 40833The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. 40834 ]] 40835] 40836[heading Exceptions] 40837[table [[Type][Thrown On]] 40838 [[`system_error`][ 40839 40840Thrown on failure. 40841 ]] 40842] 40843[heading Example] 40844 40845``` 40846 response_type res; 40847 ws.handshake(res, "localhost", "/"); 40848 std::cout << res; 40849``` 40850[heading See Also] 40851 40852* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 40853* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 40854* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 40855* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 40856 40857 40858[endsect] 40859[section:overload3 websocket::stream::handshake (3 of 4 overloads)] 40860Perform the WebSocket handshake in the client role. 40861[heading Synopsis] 40862``` 40863void 40864handshake( 40865 string_view host, 40866 string_view target, 40867 error_code& ec); 40868``` 40869 40870[heading Description] 40871This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 40872The call blocks until one of the following conditions is true: 40873 40874* The request is sent and the response is received. 40875 40876 40877* An error occurs. 40878 40879The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 40880The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 40881[heading Parameters] 40882[table [[Name][Description]] 40883 [[`host`][ 40884 40885The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. 40886 ]] 40887 [[`target`][ 40888 40889The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. 40890 ]] 40891 [[`ec`][ 40892 40893Set to indicate what error occurred, if any. 40894 ]] 40895] 40896[heading Example] 40897 40898``` 40899 error_code ec; 40900 ws.handshake("localhost", "/", ec); 40901``` 40902[heading See Also] 40903 40904* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 40905* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 40906* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 40907* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 40908 40909 40910[endsect] 40911[section:overload4 websocket::stream::handshake (4 of 4 overloads)] 40912Perform the WebSocket handshake in the client role. 40913[heading Synopsis] 40914``` 40915void 40916handshake( 40917 response_type& res, 40918 string_view host, 40919 string_view target, 40920 error_code& ec); 40921``` 40922 40923[heading Description] 40924This function is used to perform the [@https://en.wikipedia.org/wiki/WebSocket#Protocol_handshake WebSocket handshake], required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. 40925The call blocks until one of the following conditions is true: 40926 40927* The request is sent and the response is received. 40928 40929 40930* An error occurs. 40931 40932The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 40933The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a [@https://tools.ietf.org/html/rfc7230#section-3.1.2 status-code] of [link beast.ref.boost__beast__http__status `http::switching_protocols`]. 40934[heading Parameters] 40935[table [[Name][Description]] 40936 [[`res`][ 40937 40938The HTTP Upgrade response returned by the remote endpoint. The caller may use the response to access any additional information sent by the server. 40939 ]] 40940 [[`host`][ 40941 40942The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. 40943 ]] 40944 [[`target`][ 40945 40946The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. 40947 ]] 40948 [[`ec`][ 40949 40950Set to indicate what error occurred, if any. 40951 ]] 40952] 40953[heading Example] 40954 40955``` 40956 error_code ec; 40957 response_type res; 40958 ws.handshake(res, "localhost", "/", ec); 40959 if(! ec) 40960 std::cout << res; 40961``` 40962[heading See Also] 40963 40964* [@https://tools.ietf.org/html/rfc6455#section-4.1 Websocket Opening Handshake Client Requirements (RFC6455)] 40965* [@https://tools.ietf.org/html/rfc7230#section-5.4 Host field (RFC7230)] 40966* [@https://tools.ietf.org/html/rfc7230#section-3.1.1 request-target (RFC7230)] 40967* [@https://tools.ietf.org/html/rfc7230#section-5.3.1 origin-form (RFC7230)] 40968 40969 40970[endsect] 40971[endsect] 40972 40973[section:is_deflate_supported websocket::stream::is_deflate_supported] 40974[indexterm2 is_deflate_supported..websocket::stream] 40975Indicates if the permessage-deflate extension is supported. 40976[heading Synopsis] 40977 40978``` 40979using is_deflate_supported = std::integral_constant< bool, deflateSupported >; 40980``` 40981 40982[heading Description] 40983[endsect] 40984[section:is_message_done websocket::stream::is_message_done] 40985[indexterm2 is_message_done..websocket::stream] 40986Returns `true` if the last completed read finished the current message. 40987[heading Synopsis] 40988``` 40989bool 40990is_message_done() const; 40991``` 40992 40993[heading Description] 40994[endsect] 40995[section:is_open websocket::stream::is_open] 40996[indexterm2 is_open..websocket::stream] 40997Returns `true` if the stream is open. 40998[heading Synopsis] 40999``` 41000bool 41001is_open() const; 41002``` 41003 41004[heading Description] 41005The stream is open after a successful handshake, and when no error has occurred. [endsect] 41006[section:next_layer websocket::stream::next_layer] 41007[indexterm2 next_layer..websocket::stream] 41008Get a reference to the next layer. ``` 41009next_layer_type& 41010``[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 next_layer]``(); 41011 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.next_layer.overload1 more...]]`` 41012 41013next_layer_type const & 41014``[link beast.ref.boost__beast__websocket__stream.next_layer.overload2 next_layer]``() const; 41015 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.next_layer.overload2 more...]]`` 41016``` 41017[section:overload1 websocket::stream::next_layer (1 of 2 overloads)] 41018Get a reference to the next layer. 41019[heading Synopsis] 41020``` 41021next_layer_type& 41022next_layer(); 41023``` 41024 41025[heading Description] 41026This function returns a reference to the next layer in a stack of stream layers. 41027[heading Return Value] 41028A reference to the next layer in the stack of stream layers. 41029[endsect] 41030[section:overload2 websocket::stream::next_layer (2 of 2 overloads)] 41031Get a reference to the next layer. 41032[heading Synopsis] 41033``` 41034next_layer_type const & 41035next_layer() const; 41036``` 41037 41038[heading Description] 41039This function returns a reference to the next layer in a stack of stream layers. 41040[heading Return Value] 41041A reference to the next layer in the stack of stream layers. 41042[endsect] 41043[endsect] 41044 41045[section:next_layer_type websocket::stream::next_layer_type] 41046[indexterm2 next_layer_type..websocket::stream] 41047The type of the next layer. 41048[heading Synopsis] 41049 41050``` 41051using next_layer_type = typename std::remove_reference< NextLayer >::type; 41052``` 41053 41054[heading Description] 41055[endsect] 41056[section:operator_eq_ websocket::stream::operator=] 41057[indexterm2 operator=..websocket::stream] 41058Move assignment (deleted) 41059[heading Synopsis] 41060``` 41061stream& 41062operator=( 41063 stream&&); 41064``` 41065 41066[heading Description] 41067[endsect] 41068[section:ping websocket::stream::ping] 41069[indexterm2 ping..websocket::stream] 41070Send a websocket ping control frame. ``` 41071void 41072``[link beast.ref.boost__beast__websocket__stream.ping.overload1 ping]``( 41073 ping_data const& payload); 41074 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.ping.overload1 more...]]`` 41075 41076void 41077``[link beast.ref.boost__beast__websocket__stream.ping.overload2 ping]``( 41078 ping_data const& payload, 41079 error_code& ec); 41080 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.ping.overload2 more...]]`` 41081``` 41082[section:overload1 websocket::stream::ping (1 of 2 overloads)] 41083Send a websocket ping control frame. 41084[heading Synopsis] 41085``` 41086void 41087ping( 41088 ping_data const& payload); 41089``` 41090 41091[heading Description] 41092This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.2 ping frame], which usually elicits an automatic pong control frame response from the peer. 41093The call blocks until one of the following conditions is true: 41094 41095* The ping frame is written. 41096 41097 41098* An error occurs. 41099 41100The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41101[heading Parameters] 41102[table [[Name][Description]] 41103 [[`payload`][ 41104 41105The payload of the ping message, which may be empty. 41106 ]] 41107] 41108[heading Exceptions] 41109[table [[Type][Thrown On]] 41110 [[`system_error`][ 41111 41112Thrown on failure. 41113 ]] 41114] 41115[endsect] 41116[section:overload2 websocket::stream::ping (2 of 2 overloads)] 41117Send a websocket ping control frame. 41118[heading Synopsis] 41119``` 41120void 41121ping( 41122 ping_data const& payload, 41123 error_code& ec); 41124``` 41125 41126[heading Description] 41127This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.2 ping frame], which usually elicits an automatic pong control frame response from the peer. 41128The call blocks until one of the following conditions is true: 41129 41130* The ping frame is written. 41131 41132 41133* An error occurs. 41134 41135The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41136[heading Parameters] 41137[table [[Name][Description]] 41138 [[`payload`][ 41139 41140The payload of the ping message, which may be empty. 41141 ]] 41142 [[`ec`][ 41143 41144Set to indicate what error occurred, if any. 41145 ]] 41146] 41147[endsect] 41148[endsect] 41149 41150[section:pong websocket::stream::pong] 41151[indexterm2 pong..websocket::stream] 41152Send a websocket pong control frame. ``` 41153void 41154``[link beast.ref.boost__beast__websocket__stream.pong.overload1 pong]``( 41155 ping_data const& payload); 41156 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.pong.overload1 more...]]`` 41157 41158void 41159``[link beast.ref.boost__beast__websocket__stream.pong.overload2 pong]``( 41160 ping_data const& payload, 41161 error_code& ec); 41162 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.pong.overload2 more...]]`` 41163``` 41164[section:overload1 websocket::stream::pong (1 of 2 overloads)] 41165Send a websocket pong control frame. 41166[heading Synopsis] 41167``` 41168void 41169pong( 41170 ping_data const& payload); 41171``` 41172 41173[heading Description] 41174This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.3 pong frame], which is usually sent automatically in response to a ping frame from the remote peer. 41175The call blocks until one of the following conditions is true: 41176 41177* The pong frame is written. 41178 41179 41180* An error occurs. 41181 41182The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41183WebSocket allows pong frames to be sent at any time, without first receiving a ping. An unsolicited pong sent in this fashion may indicate to the remote peer that the connection is still active. 41184[heading Parameters] 41185[table [[Name][Description]] 41186 [[`payload`][ 41187 41188The payload of the pong message, which may be empty. 41189 ]] 41190] 41191[heading Exceptions] 41192[table [[Type][Thrown On]] 41193 [[`system_error`][ 41194 41195Thrown on failure. 41196 ]] 41197] 41198[endsect] 41199[section:overload2 websocket::stream::pong (2 of 2 overloads)] 41200Send a websocket pong control frame. 41201[heading Synopsis] 41202``` 41203void 41204pong( 41205 ping_data const& payload, 41206 error_code& ec); 41207``` 41208 41209[heading Description] 41210This function is used to send a [@https://tools.ietf.org/html/rfc6455#section-5.5.3 pong frame], which is usually sent automatically in response to a ping frame from the remote peer. 41211The call blocks until one of the following conditions is true: 41212 41213* The pong frame is written. 41214 41215 41216* An error occurs. 41217 41218The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41219WebSocket allows pong frames to be sent at any time, without first receiving a ping. An unsolicited pong sent in this fashion may indicate to the remote peer that the connection is still active. 41220[heading Parameters] 41221[table [[Name][Description]] 41222 [[`payload`][ 41223 41224The payload of the pong message, which may be empty. 41225 ]] 41226 [[`ec`][ 41227 41228Set to indicate what error occurred, if any. 41229 ]] 41230] 41231[endsect] 41232[endsect] 41233 41234[section:read websocket::stream::read] 41235[indexterm2 read..websocket::stream] 41236Read a complete message. ``` 41237template< 41238 class __DynamicBuffer__> 41239std::size_t 41240``[link beast.ref.boost__beast__websocket__stream.read.overload1 read]``( 41241 DynamicBuffer& buffer); 41242 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read.overload1 more...]]`` 41243 41244template< 41245 class __DynamicBuffer__> 41246std::size_t 41247``[link beast.ref.boost__beast__websocket__stream.read.overload2 read]``( 41248 DynamicBuffer& buffer, 41249 error_code& ec); 41250 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read.overload2 more...]]`` 41251``` 41252[section:overload1 websocket::stream::read (1 of 2 overloads)] 41253Read a complete message. 41254[heading Synopsis] 41255``` 41256template< 41257 class __DynamicBuffer__> 41258std::size_t 41259read( 41260 DynamicBuffer& buffer); 41261``` 41262 41263[heading Description] 41264This function is used to read a complete message. 41265The call blocks until one of the following is true: 41266 41267* A complete message is received. 41268 41269 41270* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41271 41272 41273* An error occurs. 41274 41275The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41276Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. 41277Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41278 41279* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41280 41281 41282* For each received ping frame, a pong frame will be automatically sent. 41283 41284 41285* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41286 41287[heading Return Value] 41288The number of message payload bytes appended to the buffer. 41289[heading Parameters] 41290[table [[Name][Description]] 41291 [[`buffer`][ 41292 41293A dynamic buffer to append message data to. 41294 ]] 41295] 41296[heading Exceptions] 41297[table [[Type][Thrown On]] 41298 [[`system_error`][ 41299 41300Thrown on failure. 41301 ]] 41302] 41303[endsect] 41304[section:overload2 websocket::stream::read (2 of 2 overloads)] 41305Read a complete message. 41306[heading Synopsis] 41307``` 41308template< 41309 class __DynamicBuffer__> 41310std::size_t 41311read( 41312 DynamicBuffer& buffer, 41313 error_code& ec); 41314``` 41315 41316[heading Description] 41317This function is used to read a complete message. 41318The call blocks until one of the following is true: 41319 41320* A complete message is received. 41321 41322 41323* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41324 41325 41326* An error occurs. 41327 41328The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41329Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. 41330Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41331 41332* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41333 41334 41335* For each received ping frame, a pong frame will be automatically sent. 41336 41337 41338* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41339 41340[heading Return Value] 41341The number of message payload bytes appended to the buffer. 41342[heading Parameters] 41343[table [[Name][Description]] 41344 [[`buffer`][ 41345 41346A dynamic buffer to append message data to. 41347 ]] 41348 [[`ec`][ 41349 41350Set to indicate what error occurred, if any. 41351 ]] 41352] 41353[endsect] 41354[endsect] 41355 41356[section:read_message_max websocket::stream::read_message_max] 41357[indexterm2 read_message_max..websocket::stream] 41358Set the maximum incoming message size option. ``` 41359void 41360``[link beast.ref.boost__beast__websocket__stream.read_message_max.overload1 read_message_max]``( 41361 std::size_t amount); 41362 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_message_max.overload1 more...]]`` 41363 41364``` 41365Returns the maximum incoming message size setting. ``` 41366std::size_t 41367``[link beast.ref.boost__beast__websocket__stream.read_message_max.overload2 read_message_max]``() const; 41368 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_message_max.overload2 more...]]`` 41369``` 41370[section:overload1 websocket::stream::read_message_max (1 of 2 overloads)] 41371Set the maximum incoming message size option. 41372[heading Synopsis] 41373``` 41374void 41375read_message_max( 41376 std::size_t amount); 41377``` 41378 41379[heading Description] 41380Sets the largest permissible incoming message size. Message frame fields indicating a size that would bring the total message size over this limit will cause a protocol failure. 41381The default setting is 16 megabytes. A value of zero indicates a limit of the maximum value of a `std::uint64_t`. 41382[heading Example] 41383Setting the maximum read message size. 41384``` 41385 ws.read_message_max(65536); 41386``` 41387[heading Parameters] 41388[table [[Name][Description]] 41389 [[`amount`][ 41390 41391The limit on the size of incoming messages. 41392 ]] 41393] 41394[endsect] 41395[section:overload2 websocket::stream::read_message_max (2 of 2 overloads)] 41396Returns the maximum incoming message size setting. 41397[heading Synopsis] 41398``` 41399std::size_t 41400read_message_max() const; 41401``` 41402 41403[heading Description] 41404[endsect] 41405[endsect] 41406 41407[section:read_size_hint websocket::stream::read_size_hint] 41408[indexterm2 read_size_hint..websocket::stream] 41409Returns a suggested maximum buffer size for the next call to read. ``` 41410std::size_t 41411``[link beast.ref.boost__beast__websocket__stream.read_size_hint.overload1 read_size_hint]``( 41412 std::size_t initial_size = +tcp_frame_size) const; 41413 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_size_hint.overload1 more...]]`` 41414 41415template< 41416 class __DynamicBuffer__> 41417std::size_t 41418``[link beast.ref.boost__beast__websocket__stream.read_size_hint.overload2 read_size_hint]``( 41419 DynamicBuffer& buffer) const; 41420 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_size_hint.overload2 more...]]`` 41421``` 41422[section:overload1 websocket::stream::read_size_hint (1 of 2 overloads)] 41423Returns a suggested maximum buffer size for the next call to read. 41424[heading Synopsis] 41425``` 41426std::size_t 41427read_size_hint( 41428 std::size_t initial_size = +tcp_frame_size) const; 41429``` 41430 41431[heading Description] 41432This function returns a reasonable upper limit on the number of bytes for the size of the buffer passed in the next call to read. The number is determined by the state of the current frame and whether or not the permessage-deflate extension is enabled. 41433[heading Parameters] 41434[table [[Name][Description]] 41435 [[`initial_size`][ 41436 41437A non-zero size representing the caller's desired buffer size for when there is no information which may be used to calculate a more specific value. For example, when reading the first frame header of a message. 41438 ]] 41439] 41440[endsect] 41441[section:overload2 websocket::stream::read_size_hint (2 of 2 overloads)] 41442Returns a suggested maximum buffer size for the next call to read. 41443[heading Synopsis] 41444``` 41445template< 41446 class __DynamicBuffer__> 41447std::size_t 41448read_size_hint( 41449 DynamicBuffer& buffer) const; 41450``` 41451 41452[heading Description] 41453This function returns a reasonable upper limit on the number of bytes for the size of the buffer passed in the next call to read. The number is determined by the state of the current frame and whether or not the permessage-deflate extension is enabled. 41454[heading Parameters] 41455[table [[Name][Description]] 41456 [[`buffer`][ 41457 41458The buffer which will be used for reading. The implementation will query the buffer to obtain the optimum size of a subsequent call to `buffer.prepare` based on the state of the current frame, if any. 41459 ]] 41460] 41461[endsect] 41462[endsect] 41463 41464[section:read_some websocket::stream::read_some] 41465[indexterm2 read_some..websocket::stream] 41466Read some message data. ``` 41467template< 41468 class __DynamicBuffer__> 41469std::size_t 41470``[link beast.ref.boost__beast__websocket__stream.read_some.overload1 read_some]``( 41471 DynamicBuffer& buffer, 41472 std::size_t limit); 41473 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_some.overload1 more...]]`` 41474 41475template< 41476 class __DynamicBuffer__> 41477std::size_t 41478``[link beast.ref.boost__beast__websocket__stream.read_some.overload2 read_some]``( 41479 DynamicBuffer& buffer, 41480 std::size_t limit, 41481 error_code& ec); 41482 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_some.overload2 more...]]`` 41483 41484template< 41485 class __MutableBufferSequence__> 41486std::size_t 41487``[link beast.ref.boost__beast__websocket__stream.read_some.overload3 read_some]``( 41488 MutableBufferSequence const& buffers); 41489 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_some.overload3 more...]]`` 41490 41491template< 41492 class __MutableBufferSequence__> 41493std::size_t 41494``[link beast.ref.boost__beast__websocket__stream.read_some.overload4 read_some]``( 41495 MutableBufferSequence const& buffers, 41496 error_code& ec); 41497 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.read_some.overload4 more...]]`` 41498``` 41499[section:overload1 websocket::stream::read_some (1 of 4 overloads)] 41500Read some message data. 41501[heading Synopsis] 41502``` 41503template< 41504 class __DynamicBuffer__> 41505std::size_t 41506read_some( 41507 DynamicBuffer& buffer, 41508 std::size_t limit); 41509``` 41510 41511[heading Description] 41512This function is used to read some message data. 41513The call blocks until one of the following is true: 41514 41515* Some message data is received. 41516 41517 41518* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41519 41520 41521* An error occurs. 41522 41523The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41524Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. The function [link beast.ref.boost__beast__websocket__stream.is_message_done `websocket::stream::is_message_done`] may be called to determine if the message received by the last read operation is complete. 41525Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41526 41527* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41528 41529 41530* For each received ping frame, a pong frame will be automatically sent. 41531 41532 41533* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41534 41535[heading Return Value] 41536The number of message payload bytes appended to the buffer. 41537[heading Parameters] 41538[table [[Name][Description]] 41539 [[`buffer`][ 41540 41541A dynamic buffer to append message data to. 41542 ]] 41543 [[`limit`][ 41544 41545An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically. 41546 ]] 41547] 41548[heading Exceptions] 41549[table [[Type][Thrown On]] 41550 [[`system_error`][ 41551 41552Thrown on failure. 41553 ]] 41554] 41555[endsect] 41556[section:overload2 websocket::stream::read_some (2 of 4 overloads)] 41557Read some message data. 41558[heading Synopsis] 41559``` 41560template< 41561 class __DynamicBuffer__> 41562std::size_t 41563read_some( 41564 DynamicBuffer& buffer, 41565 std::size_t limit, 41566 error_code& ec); 41567``` 41568 41569[heading Description] 41570This function is used to read some message data. 41571The call blocks until one of the following is true: 41572 41573* Some message data is received. 41574 41575 41576* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41577 41578 41579* An error occurs. 41580 41581The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41582Received message data is appended to the buffer. The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. The function [link beast.ref.boost__beast__websocket__stream.is_message_done `websocket::stream::is_message_done`] may be called to determine if the message received by the last read operation is complete. 41583Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41584 41585* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41586 41587 41588* For each received ping frame, a pong frame will be automatically sent. 41589 41590 41591* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41592 41593[heading Return Value] 41594The number of message payload bytes appended to the buffer. 41595[heading Parameters] 41596[table [[Name][Description]] 41597 [[`buffer`][ 41598 41599A dynamic buffer to append message data to. 41600 ]] 41601 [[`limit`][ 41602 41603An upper limit on the number of bytes this function will append into the buffer. If this value is zero, then a reasonable size will be chosen automatically. 41604 ]] 41605 [[`ec`][ 41606 41607Set to indicate what error occurred, if any. 41608 ]] 41609] 41610[endsect] 41611[section:overload3 websocket::stream::read_some (3 of 4 overloads)] 41612Read some message data. 41613[heading Synopsis] 41614``` 41615template< 41616 class __MutableBufferSequence__> 41617std::size_t 41618read_some( 41619 MutableBufferSequence const& buffers); 41620``` 41621 41622[heading Description] 41623This function is used to read some message data. 41624The call blocks until one of the following is true: 41625 41626* Some message data is received. 41627 41628 41629* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41630 41631 41632* An error occurs. 41633 41634The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41635The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. The function [link beast.ref.boost__beast__websocket__stream.is_message_done `websocket::stream::is_message_done`] may be called to determine if the message received by the last read operation is complete. 41636Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41637 41638* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41639 41640 41641* For each received ping frame, a pong frame will be automatically sent. 41642 41643 41644* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41645 41646[heading Return Value] 41647The number of message payload bytes appended to the buffer. 41648[heading Parameters] 41649[table [[Name][Description]] 41650 [[`buffers`][ 41651 41652A buffer sequence to write message data into. The previous contents of the buffers will be overwritten, starting from the beginning. 41653 ]] 41654] 41655[heading Exceptions] 41656[table [[Type][Thrown On]] 41657 [[`system_error`][ 41658 41659Thrown on failure. 41660 ]] 41661] 41662[endsect] 41663[section:overload4 websocket::stream::read_some (4 of 4 overloads)] 41664Read some message data. 41665[heading Synopsis] 41666``` 41667template< 41668 class __MutableBufferSequence__> 41669std::size_t 41670read_some( 41671 MutableBufferSequence const& buffers, 41672 error_code& ec); 41673``` 41674 41675[heading Description] 41676This function is used to read some message data. 41677The call blocks until one of the following is true: 41678 41679* Some message data is received. 41680 41681 41682* A close frame is received. In this case the error indicated by the function will be [link beast.ref.boost__beast__websocket__error `websocket::closed`]. 41683 41684 41685* An error occurs. 41686 41687The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. 41688The functions [link beast.ref.boost__beast__websocket__stream.got_binary `websocket::stream::got_binary`] and [link beast.ref.boost__beast__websocket__stream.got_text `websocket::stream::got_text`] may be used to query the stream and determine the type of the last received message. The function [link beast.ref.boost__beast__websocket__stream.is_message_done `websocket::stream::is_message_done`] may be called to determine if the message received by the last read operation is complete. 41689Until the call returns, the implementation will read incoming control frames and handle them automatically as follows: 41690 41691* The [link beast.ref.boost__beast__websocket__stream.control_callback `websocket::stream::control_callback`] will be invoked for each control frame. 41692 41693 41694* For each received ping frame, a pong frame will be automatically sent. 41695 41696 41697* If a close frame is received, the WebSocket closing handshake is performed. In this case, when the function returns, the error [link beast.ref.boost__beast__websocket__error `websocket::closed`] will be indicated. 41698 41699[heading Return Value] 41700The number of message payload bytes appended to the buffer. 41701[heading Parameters] 41702[table [[Name][Description]] 41703 [[`buffers`][ 41704 41705A buffer sequence to write message data into. The previous contents of the buffers will be overwritten, starting from the beginning. 41706 ]] 41707 [[`ec`][ 41708 41709Set to indicate what error occurred, if any. 41710 ]] 41711] 41712[endsect] 41713[endsect] 41714 41715[section:reason websocket::stream::reason] 41716[indexterm2 reason..websocket::stream] 41717Returns the close reason received from the remote peer. 41718[heading Synopsis] 41719``` 41720close_reason const & 41721reason() const; 41722``` 41723 41724[heading Description] 41725This is only valid after a read completes with [link beast.ref.boost__beast__websocket__error `websocket::closed`]. [endsect] 41726[section:secure_prng websocket::stream::secure_prng] 41727[indexterm2 secure_prng..websocket::stream] 41728Set whether the PRNG is cryptographically secure. 41729[heading Synopsis] 41730``` 41731void 41732secure_prng( 41733 bool value); 41734``` 41735 41736[heading Description] 41737This controls whether or not the source of pseudo-random numbers used to produce the masks required by the WebSocket protocol are of cryptographic quality. When the setting is `true`, a strong algorithm is used which cannot be guessed by observing outputs. When the setting is `false`, a much faster algorithm is used. Masking is only performed by streams operating in the client mode. For streams operating in the server mode, this setting has no effect. By default, newly constructed streams use a secure PRNG. 41738If the WebSocket stream is used with an encrypted SSL or TLS next layer, if it is known to the application that intermediate proxies are not vulnerable to cache poisoning, or if the application is designed such that an attacker cannot send arbitrary inputs to the stream interface, then the faster algorithm may be used. 41739For more information please consult the WebSocket protocol RFC. 41740[heading Parameters] 41741[table [[Name][Description]] 41742 [[`value`][ 41743 41744`true` if the PRNG algorithm should be cryptographically secure. 41745 ]] 41746] 41747[endsect] 41748[section:set_option websocket::stream::set_option] 41749[indexterm2 set_option..websocket::stream] 41750``` 41751template< 41752 class Option> 41753void 41754``[link beast.ref.boost__beast__websocket__stream.set_option.overload1 set_option]``( 41755 Option opt); 41756 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.set_option.overload1 more...]]`` 41757 41758``` 41759Set the permessage-deflate extension options. ``` 41760void 41761``[link beast.ref.boost__beast__websocket__stream.set_option.overload2 set_option]``( 41762 permessage_deflate const& o); 41763 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.set_option.overload2 more...]]`` 41764``` 41765[section:overload1 websocket::stream::set_option (1 of 2 overloads)] 41766 41767[heading Synopsis] 41768``` 41769template< 41770 class Option> 41771void 41772set_option( 41773 Option opt); 41774``` 41775 41776[heading Description] 41777[endsect] 41778[section:overload2 websocket::stream::set_option (2 of 2 overloads)] 41779Set the permessage-deflate extension options. 41780[heading Synopsis] 41781``` 41782void 41783set_option( 41784 permessage_deflate const& o); 41785``` 41786 41787[heading Description] 41788[heading Exceptions] 41789[table [[Type][Thrown On]] 41790 [[`invalid_argument`][ 41791 41792if `deflateSupported == false`, and either `client_enable` or `server_enable` is `true`. 41793 ]] 41794] 41795[endsect] 41796[endsect] 41797 41798[section:stream websocket::stream::stream] 41799[indexterm2 stream..websocket::stream] 41800Constructor. ``` 41801``[link beast.ref.boost__beast__websocket__stream.stream.overload1 stream]``( 41802 stream&&); 41803 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.stream.overload1 more...]]`` 41804 41805template< 41806 class... Args> 41807explicit 41808``[link beast.ref.boost__beast__websocket__stream.stream.overload2 stream]``( 41809 Args&&... args); 41810 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.stream.overload2 more...]]`` 41811``` 41812[section:overload1 websocket::stream::stream (1 of 2 overloads)] 41813Constructor. 41814[heading Synopsis] 41815``` 41816stream( 41817 stream&&); 41818``` 41819 41820[heading Description] 41821If `NextLayer` is move constructible, this function will move-construct a new stream from the existing stream. 41822After the move, the only valid operation on the moved-from object is destruction. [endsect] 41823[section:overload2 websocket::stream::stream (2 of 2 overloads)] 41824Constructor. 41825[heading Synopsis] 41826``` 41827template< 41828 class... Args> 41829stream( 41830 Args&&... args); 41831``` 41832 41833[heading Description] 41834This constructor creates a websocket stream and initializes the next layer object. 41835[heading Exceptions] 41836[table [[Type][Thrown On]] 41837 [[`Any`][ 41838 41839exceptions thrown by the NextLayer constructor. 41840 ]] 41841] 41842[heading Parameters] 41843[table [[Name][Description]] 41844 [[`args`][ 41845 41846The arguments to be passed to initialize the next layer object. The arguments are forwarded to the next layer's constructor. 41847 ]] 41848] 41849[endsect] 41850[endsect] 41851 41852[section:text websocket::stream::text] 41853[indexterm2 text..websocket::stream] 41854Set the text message write option. ``` 41855void 41856``[link beast.ref.boost__beast__websocket__stream.text.overload1 text]``( 41857 bool value); 41858 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.text.overload1 more...]]`` 41859 41860``` 41861Returns `true` if the text message write option is set. ``` 41862bool 41863``[link beast.ref.boost__beast__websocket__stream.text.overload2 text]``() const; 41864 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.text.overload2 more...]]`` 41865``` 41866[section:overload1 websocket::stream::text (1 of 2 overloads)] 41867Set the text message write option. 41868[heading Synopsis] 41869``` 41870void 41871text( 41872 bool value); 41873``` 41874 41875[heading Description] 41876This controls whether or not outgoing message opcodes are set to binary or text. The setting is only applied at the start when a caller begins a new message. Changing the opcode after a message is started will only take effect after the current message being sent is complete. 41877The default setting is to send text messages. 41878[heading Parameters] 41879[table [[Name][Description]] 41880 [[`value`][ 41881 41882`true` if outgoing messages should indicate text, or `false` if they should indicate binary. 41883 ]] 41884] 41885[heading Example] 41886Setting the message type to text. 41887``` 41888 ws.text(true); 41889``` 41890[endsect] 41891[section:overload2 websocket::stream::text (2 of 2 overloads)] 41892Returns `true` if the text message write option is set. 41893[heading Synopsis] 41894``` 41895bool 41896text() const; 41897``` 41898 41899[heading Description] 41900[endsect] 41901[endsect] 41902 41903[section:write websocket::stream::write] 41904[indexterm2 write..websocket::stream] 41905Write a complete message. ``` 41906template< 41907 class __ConstBufferSequence__> 41908std::size_t 41909``[link beast.ref.boost__beast__websocket__stream.write.overload1 write]``( 41910 ConstBufferSequence const& buffers); 41911 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write.overload1 more...]]`` 41912 41913template< 41914 class __ConstBufferSequence__> 41915std::size_t 41916``[link beast.ref.boost__beast__websocket__stream.write.overload2 write]``( 41917 ConstBufferSequence const& buffers, 41918 error_code& ec); 41919 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write.overload2 more...]]`` 41920``` 41921[section:overload1 websocket::stream::write (1 of 2 overloads)] 41922Write a complete message. 41923[heading Synopsis] 41924``` 41925template< 41926 class __ConstBufferSequence__> 41927std::size_t 41928write( 41929 ConstBufferSequence const& buffers); 41930``` 41931 41932[heading Description] 41933This function is used to write a complete message. 41934The call blocks until one of the following is true: 41935 41936* The message is written. 41937 41938 41939* An error occurs. 41940 41941The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41942The current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] option controls whether the message opcode is set to text or binary. If the [link beast.ref.boost__beast__websocket__stream.auto_fragment `websocket::stream::auto_fragment`] option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings. 41943[heading Parameters] 41944[table [[Name][Description]] 41945 [[`buffers`][ 41946 41947The buffers containing the message to send. 41948 ]] 41949] 41950[heading Return Value] 41951The number of bytes sent from the buffers. 41952[heading Exceptions] 41953[table [[Type][Thrown On]] 41954 [[`system_error`][ 41955 41956Thrown on failure. 41957 ]] 41958] 41959[endsect] 41960[section:overload2 websocket::stream::write (2 of 2 overloads)] 41961Write a complete message. 41962[heading Synopsis] 41963``` 41964template< 41965 class __ConstBufferSequence__> 41966std::size_t 41967write( 41968 ConstBufferSequence const& buffers, 41969 error_code& ec); 41970``` 41971 41972[heading Description] 41973This function is used to write a complete message. 41974The call blocks until one of the following is true: 41975 41976* The complete message is written. 41977 41978 41979* An error occurs. 41980 41981The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 41982The current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] option controls whether the message opcode is set to text or binary. If the [link beast.ref.boost__beast__websocket__stream.auto_fragment `websocket::stream::auto_fragment`] option is set, the message will be split into one or more frames as necessary. The actual payload contents sent may be transformed as per the WebSocket protocol settings. 41983[heading Parameters] 41984[table [[Name][Description]] 41985 [[`buffers`][ 41986 41987The buffers containing the message to send. 41988 ]] 41989 [[`ec`][ 41990 41991Set to indicate what error occurred, if any. 41992 ]] 41993] 41994[heading Return Value] 41995The number of bytes sent from the buffers. 41996[endsect] 41997[endsect] 41998 41999[section:write_buffer_bytes websocket::stream::write_buffer_bytes] 42000[indexterm2 write_buffer_bytes..websocket::stream] 42001Set the write buffer size option. ``` 42002void 42003``[link beast.ref.boost__beast__websocket__stream.write_buffer_bytes.overload1 write_buffer_bytes]``( 42004 std::size_t amount); 42005 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write_buffer_bytes.overload1 more...]]`` 42006 42007``` 42008Returns the size of the write buffer. ``` 42009std::size_t 42010``[link beast.ref.boost__beast__websocket__stream.write_buffer_bytes.overload2 write_buffer_bytes]``() const; 42011 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write_buffer_bytes.overload2 more...]]`` 42012``` 42013[section:overload1 websocket::stream::write_buffer_bytes (1 of 2 overloads)] 42014Set the write buffer size option. 42015[heading Synopsis] 42016``` 42017void 42018write_buffer_bytes( 42019 std::size_t amount); 42020``` 42021 42022[heading Description] 42023Sets the size of the write buffer used by the implementation to send frames. The write buffer is needed when masking payload data in the client role, compressing frames, or auto-fragmenting message data. 42024Lowering the size of the buffer can decrease the memory requirements for each connection, while increasing the size of the buffer can reduce the number of calls made to the next layer to write data. 42025The default setting is 4096. The minimum value is 8. 42026The write buffer size can only be changed when the stream is not open. Undefined behavior results if the option is modified after a successful WebSocket handshake. 42027[heading Example] 42028Setting the write buffer size. 42029``` 42030 ws.write_buffer_bytes(8192); 42031``` 42032[heading Parameters] 42033[table [[Name][Description]] 42034 [[`amount`][ 42035 42036The size of the write buffer in bytes. 42037 ]] 42038] 42039[endsect] 42040[section:overload2 websocket::stream::write_buffer_bytes (2 of 2 overloads)] 42041Returns the size of the write buffer. 42042[heading Synopsis] 42043``` 42044std::size_t 42045write_buffer_bytes() const; 42046``` 42047 42048[heading Description] 42049[endsect] 42050[endsect] 42051 42052[section:write_some websocket::stream::write_some] 42053[indexterm2 write_some..websocket::stream] 42054Write some message data. ``` 42055template< 42056 class __ConstBufferSequence__> 42057std::size_t 42058``[link beast.ref.boost__beast__websocket__stream.write_some.overload1 write_some]``( 42059 bool fin, 42060 ConstBufferSequence const& buffers); 42061 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write_some.overload1 more...]]`` 42062 42063template< 42064 class __ConstBufferSequence__> 42065std::size_t 42066``[link beast.ref.boost__beast__websocket__stream.write_some.overload2 write_some]``( 42067 bool fin, 42068 ConstBufferSequence const& buffers, 42069 error_code& ec); 42070 ``[''''»''' [link beast.ref.boost__beast__websocket__stream.write_some.overload2 more...]]`` 42071``` 42072[section:overload1 websocket::stream::write_some (1 of 2 overloads)] 42073Write some message data. 42074[heading Synopsis] 42075``` 42076template< 42077 class __ConstBufferSequence__> 42078std::size_t 42079write_some( 42080 bool fin, 42081 ConstBufferSequence const& buffers); 42082``` 42083 42084[heading Description] 42085This function is used to send part of a message. 42086The call blocks until one of the following is true: 42087 42088* The message data is written. 42089 42090 42091* An error occurs. 42092 42093The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 42094If this is the beginning of a new message, the message opcode will be set to text or binary based on the current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] (or [link beast.ref.boost__beast__websocket__stream.text `websocket::stream::text`]) option. The actual payload sent may be transformed as per the WebSocket protocol settings. 42095[heading Parameters] 42096[table [[Name][Description]] 42097 [[`fin`][ 42098 42099`true` if this is the last part of the message. 42100 ]] 42101 [[`buffers`][ 42102 42103The buffers containing the message part to send. 42104 ]] 42105] 42106[heading Return Value] 42107The number of bytes sent from the buffers. 42108[heading Exceptions] 42109[table [[Type][Thrown On]] 42110 [[`system_error`][ 42111 42112Thrown on failure. 42113 ]] 42114] 42115[endsect] 42116[section:overload2 websocket::stream::write_some (2 of 2 overloads)] 42117Write some message data. 42118[heading Synopsis] 42119``` 42120template< 42121 class __ConstBufferSequence__> 42122std::size_t 42123write_some( 42124 bool fin, 42125 ConstBufferSequence const& buffers, 42126 error_code& ec); 42127``` 42128 42129[heading Description] 42130This function is used to send part of a message. 42131The call blocks until one of the following is true: 42132 42133* The message data is written. 42134 42135 42136* An error occurs. 42137 42138The algorithm, known as a ['composed operation], is implemented in terms of calls to the next layer's `write_some` function. 42139If this is the beginning of a new message, the message opcode will be set to text or binary based on the current setting of the [link beast.ref.boost__beast__websocket__stream.binary `websocket::stream::binary`] (or [link beast.ref.boost__beast__websocket__stream.text `websocket::stream::text`]) option. The actual payload sent may be transformed as per the WebSocket protocol settings. 42140[heading Parameters] 42141[table [[Name][Description]] 42142 [[`fin`][ 42143 42144`true` if this is the last part of the message. 42145 ]] 42146 [[`buffers`][ 42147 42148The buffers containing the message part to send. 42149 ]] 42150 [[`ec`][ 42151 42152Set to indicate what error occurred, if any. 42153 ]] 42154] 42155[heading Return Value] 42156The number of bytes sent from the buffers. 42157[heading Return Value] 42158The number of bytes consumed in the input buffers. 42159[endsect] 42160[endsect] 42161 42162[section:stream_dtor_ websocket::stream::~stream] 42163[indexterm2 ~stream..websocket::stream] 42164Destructor. 42165[heading Synopsis] 42166``` 42167~stream(); 42168``` 42169 42170[heading Description] 42171Destroys the stream and all associated resources. 42172[heading Remarks] 42173A stream object must not be destroyed while there are pending asynchronous operations associated with it. 42174[endsect] 42175 42176 42177 42178Convenience header [include_file boost/beast/websocket.hpp] 42179 42180[endsect] 42181 42182 42183 42184[section:boost__beast__websocket__stream__accept_op websocket::stream::accept_op] 42185 42186[heading Synopsis] 42187 42188Defined in header [include_file boost/beast/websocket/stream.hpp] 42189 42190 42191 42192``` 42193template< 42194 [role red error.class-detail-template.1][role red error.class-detail-template.2], 42195 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42196class accept_op 42197``` 42198 42199[heading Description] 42200 42201 42202 42203Convenience header [include_file boost/beast/websocket.hpp] 42204 42205[endsect] 42206 42207 42208 42209[section:boost__beast__websocket__stream__close_op websocket::stream::close_op] 42210 42211[heading Synopsis] 42212 42213Defined in header [include_file boost/beast/websocket/stream.hpp] 42214 42215 42216 42217``` 42218template< 42219 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42220class close_op 42221``` 42222 42223[heading Description] 42224 42225 42226 42227Convenience header [include_file boost/beast/websocket.hpp] 42228 42229[endsect] 42230 42231 42232 42233[section:boost__beast__websocket__stream__handshake_op websocket::stream::handshake_op] 42234 42235[heading Synopsis] 42236 42237Defined in header [include_file boost/beast/websocket/stream.hpp] 42238 42239 42240 42241``` 42242template< 42243 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42244class handshake_op 42245``` 42246 42247[heading Description] 42248 42249 42250 42251Convenience header [include_file boost/beast/websocket.hpp] 42252 42253[endsect] 42254 42255 42256 42257[section:boost__beast__websocket__stream__idle_ping_op websocket::stream::idle_ping_op] 42258 42259[heading Synopsis] 42260 42261Defined in header [include_file boost/beast/websocket/stream.hpp] 42262 42263 42264 42265``` 42266template< 42267 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42268class idle_ping_op 42269``` 42270 42271[heading Description] 42272 42273 42274 42275Convenience header [include_file boost/beast/websocket.hpp] 42276 42277[endsect] 42278 42279 42280 42281[section:boost__beast__websocket__stream__ping_op websocket::stream::ping_op] 42282 42283[heading Synopsis] 42284 42285Defined in header [include_file boost/beast/websocket/stream.hpp] 42286 42287 42288 42289``` 42290template< 42291 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42292class ping_op 42293``` 42294 42295[heading Description] 42296 42297 42298 42299Convenience header [include_file boost/beast/websocket.hpp] 42300 42301[endsect] 42302 42303 42304 42305[section:boost__beast__websocket__stream__read_op websocket::stream::read_op] 42306 42307[heading Synopsis] 42308 42309Defined in header [include_file boost/beast/websocket/stream.hpp] 42310 42311 42312 42313``` 42314template< 42315 [role red error.class-detail-template.1][role red error.class-detail-template.2], 42316 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42317class read_op 42318``` 42319 42320[heading Description] 42321 42322 42323 42324Convenience header [include_file boost/beast/websocket.hpp] 42325 42326[endsect] 42327 42328 42329 42330[section:boost__beast__websocket__stream__read_some_op websocket::stream::read_some_op] 42331 42332[heading Synopsis] 42333 42334Defined in header [include_file boost/beast/websocket/stream.hpp] 42335 42336 42337 42338``` 42339template< 42340 [role red error.class-detail-template.1][role red error.class-detail-template.2], 42341 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42342class read_some_op 42343``` 42344 42345[heading Description] 42346 42347 42348 42349Convenience header [include_file boost/beast/websocket.hpp] 42350 42351[endsect] 42352 42353 42354 42355[section:boost__beast__websocket__stream__response_op websocket::stream::response_op] 42356 42357[heading Synopsis] 42358 42359Defined in header [include_file boost/beast/websocket/stream.hpp] 42360 42361 42362 42363``` 42364template< 42365 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42366class response_op 42367``` 42368 42369[heading Description] 42370 42371 42372 42373Convenience header [include_file boost/beast/websocket.hpp] 42374 42375[endsect] 42376 42377 42378 42379[section:boost__beast__websocket__stream__write_op websocket::stream::write_op] 42380 42381[heading Synopsis] 42382 42383Defined in header [include_file boost/beast/websocket/stream.hpp] 42384 42385 42386 42387``` 42388template< 42389 [role red error.class-detail-template.1][role red error.class-detail-template.2], 42390 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42391class write_op 42392``` 42393 42394[heading Description] 42395 42396 42397 42398Convenience header [include_file boost/beast/websocket.hpp] 42399 42400[endsect] 42401 42402 42403 42404[section:boost__beast__websocket__stream__write_some_op websocket::stream::write_some_op] 42405 42406[heading Synopsis] 42407 42408Defined in header [include_file boost/beast/websocket/stream.hpp] 42409 42410 42411 42412``` 42413template< 42414 [role red error.class-detail-template.1][role red error.class-detail-template.2], 42415 [role red error.class-detail-template.1][role red error.class-detail-template.2]> 42416class write_some_op 42417``` 42418 42419[heading Description] 42420 42421 42422 42423Convenience header [include_file boost/beast/websocket.hpp] 42424 42425[endsect] 42426 42427 42428 42429[section:boost__beast__websocket__stream_base websocket::stream_base] 42430This class is used as a base for the [link beast.ref.boost__beast__websocket__stream `websocket::stream`] class template to group common types and constants. 42431[heading Synopsis] 42432 42433Defined in header [include_file boost/beast/websocket/stream_base.hpp] 42434 42435 42436 42437``` 42438struct stream_base 42439``` 42440[heading Types] 42441[table [[Name][Description]] 42442 [ 42443 [[link beast.ref.boost__beast__websocket__stream_base__decorator [*decorator]]] 42444 [ 42445 Stream option used to adjust HTTP fields of WebSocket upgrade request and responses. 42446 ] 42447 ] 42448 [ 42449 [[link beast.ref.boost__beast__websocket__stream_base__timeout [*timeout]]] 42450 [ 42451 Stream option to control the behavior of websocket timeouts. 42452 ] 42453 ] 42454 [ 42455 [[link beast.ref.boost__beast__websocket__stream_base.duration [*duration]]] 42456 [ 42457 The type used to represent durations. 42458 ] 42459 ] 42460 [ 42461 [[link beast.ref.boost__beast__websocket__stream_base.time_point [*time_point]]] 42462 [ 42463 The type used to represent time points. 42464 ] 42465 ] 42466] 42467[heading Member Functions] 42468[table [[Name][Description]] 42469 [ 42470 [[link beast.ref.boost__beast__websocket__stream_base.never [*never]]] 42471 [ 42472 Returns the special time_point value meaning "never". 42473 ] 42474 ] 42475 [ 42476 [[link beast.ref.boost__beast__websocket__stream_base.none [*none]]] 42477 [ 42478 Returns the special duration value meaning "none". 42479 ] 42480 ] 42481] 42482 42483[heading Description] 42484[section:duration websocket::stream_base::duration] 42485[indexterm2 duration..websocket::stream_base] 42486The type used to represent durations. 42487[heading Synopsis] 42488 42489``` 42490using duration = std::chrono::steady_clock::duration; 42491``` 42492 42493[heading Description] 42494[endsect] 42495[section:never websocket::stream_base::never] 42496[indexterm2 never..websocket::stream_base] 42497Returns the special time\_point value meaning "never". 42498[heading Synopsis] 42499``` 42500static 42501time_point 42502never(); 42503``` 42504 42505[heading Description] 42506[endsect] 42507[section:none websocket::stream_base::none] 42508[indexterm2 none..websocket::stream_base] 42509Returns the special duration value meaning "none". 42510[heading Synopsis] 42511``` 42512static 42513duration 42514none(); 42515``` 42516 42517[heading Description] 42518[endsect] 42519[section:time_point websocket::stream_base::time_point] 42520[indexterm2 time_point..websocket::stream_base] 42521The type used to represent time points. 42522[heading Synopsis] 42523 42524``` 42525using time_point = std::chrono::steady_clock::time_point; 42526``` 42527 42528[heading Description] 42529[endsect] 42530 42531 42532 42533Convenience header [include_file boost/beast/websocket.hpp] 42534 42535[endsect] 42536 42537 42538 42539[section:boost__beast__websocket__stream_base__decorator websocket::stream_base::decorator] 42540Stream option used to adjust HTTP fields of WebSocket upgrade request and responses. 42541[heading Synopsis] 42542 42543Defined in header [include_file boost/beast/websocket/stream_base.hpp] 42544 42545 42546 42547``` 42548class decorator 42549``` 42550[heading Member Functions] 42551[table [[Name][Description]] 42552 [ 42553 [[link beast.ref.boost__beast__websocket__stream_base__decorator.decorator [*decorator]]] 42554 [ 42555 42556 42557 Construct a decorator option. 42558 ] 42559 ] 42560] 42561 42562[heading Description] 42563[section:decorator websocket::stream_base::decorator::decorator] 42564[indexterm2 decorator..websocket::stream_base::decorator] 42565``` 42566``[link beast.ref.boost__beast__websocket__stream_base__decorator.decorator.overload1 decorator]``( 42567 decorator&&); 42568 ``[''''»''' [link beast.ref.boost__beast__websocket__stream_base__decorator.decorator.overload1 more...]]`` 42569 42570``` 42571Construct a decorator option. ``` 42572template< 42573 class Decorator> 42574explicit 42575``[link beast.ref.boost__beast__websocket__stream_base__decorator.decorator.overload2 decorator]``( 42576 Decorator&& f); 42577 ``[''''»''' [link beast.ref.boost__beast__websocket__stream_base__decorator.decorator.overload2 more...]]`` 42578``` 42579[section:overload1 websocket::stream_base::decorator::decorator (1 of 2 overloads)] 42580 42581[heading Synopsis] 42582``` 42583decorator( 42584 decorator&&); 42585``` 42586 42587[heading Description] 42588[endsect] 42589[section:overload2 websocket::stream_base::decorator::decorator (2 of 2 overloads)] 42590Construct a decorator option. 42591[heading Synopsis] 42592``` 42593template< 42594 class Decorator> 42595decorator( 42596 Decorator&& f); 42597``` 42598 42599[heading Description] 42600[heading Parameters] 42601[table [[Name][Description]] 42602 [[`f`][ 42603 42604An invocable function object. Ownership of the function object is transferred by decay-copy. 42605 ]] 42606] 42607[endsect] 42608[endsect] 42609 42610 42611 42612 42613Convenience header [include_file boost/beast/websocket.hpp] 42614 42615[endsect] 42616 42617 42618 42619[section:boost__beast__websocket__stream_base__timeout websocket::stream_base::timeout] 42620Stream option to control the behavior of websocket timeouts. 42621[heading Synopsis] 42622 42623Defined in header [include_file boost/beast/websocket/stream_base.hpp] 42624 42625 42626 42627``` 42628struct timeout 42629``` 42630[heading Member Functions] 42631[table [[Name][Description]] 42632 [ 42633 [[link beast.ref.boost__beast__websocket__stream_base__timeout.suggested [*suggested]]] 42634 [ 42635 Construct timeout settings with suggested values for a role. 42636 ] 42637 ] 42638] 42639[heading Data Members] 42640[table [[Name][Description]] 42641 [ 42642 [[link beast.ref.boost__beast__websocket__stream_base__timeout.handshake_timeout [*handshake_timeout]]] 42643 [ 42644 Time limit on handshake, accept, and close operations: 42645 ] 42646 ] 42647 [ 42648 [[link beast.ref.boost__beast__websocket__stream_base__timeout.idle_timeout [*idle_timeout]]] 42649 [ 42650 The time limit after which a connection is considered idle. 42651 ] 42652 ] 42653 [ 42654 [[link beast.ref.boost__beast__websocket__stream_base__timeout.keep_alive_pings [*keep_alive_pings]]] 42655 [ 42656 Automatic ping setting. 42657 ] 42658 ] 42659] 42660 42661[heading Description] 42662Timeout features are available for asynchronous operations only. [section:handshake_timeout websocket::stream_base::timeout::handshake_timeout] 42663[indexterm2 handshake_timeout..websocket::stream_base::timeout] 42664Time limit on handshake, accept, and close operations: 42665[heading Synopsis] 42666``` 42667duration handshake_timeout; 42668``` 42669 42670[heading Description] 42671This value whether or not there is a time limit, and the duration of that time limit, for asynchronous handshake, accept, and close operations. If this is equal to the value [link beast.ref.boost__beast__websocket__stream_base.none `websocket::stream_base::none`] then there will be no time limit. Otherwise, if any of the applicable operations takes longer than this amount of time, the operation will be canceled and a timeout error delivered to the completion handler. [endsect] 42672[section:idle_timeout websocket::stream_base::timeout::idle_timeout] 42673[indexterm2 idle_timeout..websocket::stream_base::timeout] 42674The time limit after which a connection is considered idle. 42675[heading Synopsis] 42676``` 42677duration idle_timeout; 42678``` 42679 42680[heading Description] 42681[endsect] 42682[section:keep_alive_pings websocket::stream_base::timeout::keep_alive_pings] 42683[indexterm2 keep_alive_pings..websocket::stream_base::timeout] 42684Automatic ping setting. 42685[heading Synopsis] 42686``` 42687bool keep_alive_pings; 42688``` 42689 42690[heading Description] 42691If the idle interval is set, this setting affects the behavior of the stream when no data is received for the timeout interval as follows: 42692 42693* When `keep_alive_pings` is `true`, an idle ping will be sent automatically. If another timeout interval elapses with no received data then the connection will be closed. An outstanding read operation must be pending, which will complete immediately the error [link beast.ref.boost__beast__error `timeout`]. 42694 42695 42696* When `keep_alive_pings` is `false`, the connection will be closed. An outstanding read operation must be pending, which will complete immediately the error [link beast.ref.boost__beast__error `timeout`]. 42697 42698[endsect] 42699[section:suggested websocket::stream_base::timeout::suggested] 42700[indexterm2 suggested..websocket::stream_base::timeout] 42701Construct timeout settings with suggested values for a role. 42702[heading Synopsis] 42703``` 42704static 42705timeout 42706suggested( 42707 role_type role); 42708``` 42709 42710[heading Description] 42711This constructs the timeout settings with a predefined set of values which varies depending on the desired role. The values are selected upon construction, regardless of the current or actual role in use on the stream. 42712[heading Example] 42713This statement sets the timeout settings of the stream to the suggested values for the server role: 42714``` 42715``` 42716[heading Parameters] 42717[table [[Name][Description]] 42718 [[`role`][ 42719 42720The role of the websocket stream ([link beast.ref.boost__beast__role_type `client`] or [link beast.ref.boost__beast__role_type `server`]). 42721 ]] 42722] 42723[endsect] 42724 42725 42726 42727Convenience header [include_file boost/beast/websocket.hpp] 42728 42729[endsect] 42730 42731 42732 42733[section:boost__beast__websocket__teardown websocket::teardown] 42734[indexterm1 websocket::teardown] 42735Tear down a connection. ``` 42736template< 42737 class Socket> 42738void 42739``[link beast.ref.boost__beast__websocket__teardown.overload1 teardown]``( 42740 role_type role, 42741 Socket& socket, 42742 error_code& ec); 42743 ``[''''»''' [link beast.ref.boost__beast__websocket__teardown.overload1 more...]]`` 42744 42745``` 42746Tear down a `net::ip::tcp::socket`. ``` 42747template< 42748 class __Protocol__, 42749 class __Executor__> 42750void 42751``[link beast.ref.boost__beast__websocket__teardown.overload2 teardown]``( 42752 role_type role, 42753 net::basic_stream_socket< Protocol, Executor >& socket, 42754 error_code& ec); 42755 ``[''''»''' [link beast.ref.boost__beast__websocket__teardown.overload2 more...]]`` 42756``` 42757[section:overload1 websocket::teardown (1 of 2 overloads)] 42758Tear down a connection. 42759[heading Synopsis] 42760 42761Defined in header [include_file boost/beast/websocket/teardown.hpp] 42762 42763 42764 42765``` 42766template< 42767 class Socket> 42768void 42769teardown( 42770 role_type role, 42771 Socket& socket, 42772 error_code& ec); 42773 42774``` 42775 42776[heading Description] 42777This tears down a connection. The implementation will call the overload of this function based on the `Socket` parameter used to consruct the socket. When `Socket` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 42778[heading Parameters] 42779[table [[Name][Description]] 42780 [[`role`][ 42781 42782The role of the local endpoint 42783 ]] 42784 [[`socket`][ 42785 42786The socket to tear down. 42787 ]] 42788 [[`ec`][ 42789 42790Set to the error if any occurred. 42791 ]] 42792] 42793 42794 42795 42796Convenience header [include_file boost/beast/websocket.hpp] 42797 42798[endsect] 42799[section:overload2 websocket::teardown (2 of 2 overloads)] 42800Tear down a `net::ip::tcp::socket`. 42801[heading Synopsis] 42802 42803Defined in header [include_file boost/beast/websocket/teardown.hpp] 42804 42805 42806 42807``` 42808template< 42809 class __Protocol__, 42810 class __Executor__> 42811void 42812teardown( 42813 role_type role, 42814 net::basic_stream_socket< Protocol, Executor >& socket, 42815 error_code& ec); 42816 42817``` 42818 42819[heading Description] 42820This tears down a connection. The implementation will call the overload of this function based on the `Stream` parameter used to consruct the socket. When `Stream` is a user defined type, and not a `net::ip::tcp::socket` or any `net::ssl::stream`, callers are responsible for providing a suitable overload of this function. 42821[heading Parameters] 42822[table [[Name][Description]] 42823 [[`role`][ 42824 42825The role of the local endpoint 42826 ]] 42827 [[`socket`][ 42828 42829The socket to tear down. 42830 ]] 42831 [[`ec`][ 42832 42833Set to the error if any occurred. 42834 ]] 42835] 42836 42837 42838 42839Convenience header [include_file boost/beast/websocket.hpp] 42840 42841[endsect] 42842[endsect] 42843 42844 42845 42846[section:boost__beast__zlib__Byte zlib::Byte] 42847[indexterm1 zlib::Byte] 42848 42849[heading Synopsis] 42850 42851Defined in header [include_file boost/beast/zlib/zlib.hpp] 42852 42853 42854 42855``` 42856using Byte = unsigned char; 42857``` 42858 42859[heading Description] 42860 42861 42862 42863Convenience header [include_file boost/beast/zlib.hpp] 42864 42865[endsect] 42866[section:boost__beast__zlib__Flush zlib::Flush] 42867[indexterm1 zlib::Flush] 42868Flush option. 42869[heading Synopsis] 42870 42871Defined in header [include_file boost/beast/zlib/zlib.hpp] 42872 42873 42874``` 42875enum Flush 42876``` 42877 42878[indexterm2 none..zlib::Flush] 42879[indexterm2 block..zlib::Flush] 42880[indexterm2 partial..zlib::Flush] 42881[indexterm2 sync..zlib::Flush] 42882[indexterm2 full..zlib::Flush] 42883[indexterm2 finish..zlib::Flush] 42884[indexterm2 trees..zlib::Flush] 42885[heading Values] 42886[table [[Name][Description]] 42887 [[[^none]][ 42888 42889]] 42890 [[[^block]][ 42891 42892]] 42893 [[[^partial]][ 42894 42895]] 42896 [[[^sync]][ 42897 42898]] 42899 [[[^full]][ 42900 42901]] 42902 [[[^finish]][ 42903 42904]] 42905 [[[^trees]][ 42906 42907]] 42908] 42909 42910[heading Description] 42911 42912 42913 42914Convenience header [include_file boost/beast/zlib.hpp] 42915 42916[endsect] 42917[section:boost__beast__zlib__Strategy zlib::Strategy] 42918[indexterm1 zlib::Strategy] 42919Compression strategy. 42920[heading Synopsis] 42921 42922Defined in header [include_file boost/beast/zlib/zlib.hpp] 42923 42924 42925``` 42926enum Strategy 42927``` 42928 42929[indexterm2 normal..zlib::Strategy] 42930[indexterm2 filtered..zlib::Strategy] 42931[indexterm2 huffman..zlib::Strategy] 42932[indexterm2 rle..zlib::Strategy] 42933[indexterm2 fixed..zlib::Strategy] 42934[heading Values] 42935[table [[Name][Description]] 42936 [[[^normal]][Default strategy. 42937 42938This is suitable for general purpose compression, and works 42939well in the majority of cases. 42940 ]] 42941 [[[^filtered]][Filtered strategy. 42942 42943This strategy should be used when the data be compressed 42944is produced by a filter or predictor. 42945 ]] 42946 [[[^huffman]][Huffman-only strategy. 42947 42948This strategy only performs Huffman encoding, without doing 42949any string matching. 42950 ]] 42951 [[[^rle]][Run Length Encoding strategy. 42952 42953This strategy limits match distances to one, making it 42954equivalent to run length encoding. This can give better 42955performance for things like PNG image data. 42956 ]] 42957 [[[^fixed]][Fixed table strategy. 42958 42959This strategy prevents the use of dynamic Huffman codes, 42960allowing for a simpler decoder for special applications. 42961 ]] 42962] 42963 42964[heading Description] 42965These are used when compressing streams. 42966 42967 42968Convenience header [include_file boost/beast/zlib.hpp] 42969 42970[endsect] 42971[section:boost__beast__zlib__compression zlib::compression] 42972[indexterm1 zlib::compression] 42973 42974[heading Synopsis] 42975 42976Defined in header [include_file boost/beast/zlib/zlib.hpp] 42977 42978 42979``` 42980enum compression 42981``` 42982 42983[indexterm2 none..zlib::compression] 42984[indexterm2 none..zlib::compression] 42985[indexterm2 best_speed..zlib::compression] 42986[indexterm2 best_size..zlib::compression] 42987[indexterm2 default_size..zlib::compression] 42988[heading Values] 42989[table [[Name][Description]] 42990 [[[^none]][ 42991 42992]] 42993 [[[^none]][ 42994 42995]] 42996 [[[^best_speed]][ 42997 42998]] 42999 [[[^best_size]][ 43000 43001]] 43002 [[[^default_size]][ 43003 43004]] 43005] 43006 43007[heading Description] 43008 43009 43010 43011Convenience header [include_file boost/beast/zlib.hpp] 43012 43013[endsect] 43014[section:boost__beast__zlib__deflate_stream zlib::deflate_stream] 43015Raw deflate compressor. 43016[heading Synopsis] 43017 43018Defined in header [include_file boost/beast/zlib/deflate_stream.hpp] 43019 43020 43021 43022``` 43023class deflate_stream : 43024 private deflate_stream 43025``` 43026[heading Member Functions] 43027[table [[Name][Description]] 43028 [ 43029 [[link beast.ref.boost__beast__zlib__deflate_stream.clear [*clear]]] 43030 [ 43031 Clear the stream. 43032 ] 43033 ] 43034 [ 43035 [[link beast.ref.boost__beast__zlib__deflate_stream.deflate_stream [*deflate_stream]]] 43036 [ 43037 Construct a default deflate stream. 43038 ] 43039 ] 43040 [ 43041 [[link beast.ref.boost__beast__zlib__deflate_stream.params [*params]]] 43042 [ 43043 Update the compression level and strategy. 43044 ] 43045 ] 43046 [ 43047 [[link beast.ref.boost__beast__zlib__deflate_stream.pending [*pending]]] 43048 [ 43049 Return bits pending in the output. 43050 ] 43051 ] 43052 [ 43053 [[link beast.ref.boost__beast__zlib__deflate_stream.prime [*prime]]] 43054 [ 43055 Insert bits into the compressed output stream. 43056 ] 43057 ] 43058 [ 43059 [[link beast.ref.boost__beast__zlib__deflate_stream.reset [*reset]]] 43060 [ 43061 Reset the stream and compression settings. 43062 43063 Reset the stream without deallocating memory. 43064 ] 43065 ] 43066 [ 43067 [[link beast.ref.boost__beast__zlib__deflate_stream.tune [*tune]]] 43068 [ 43069 Fine tune internal compression parameters. 43070 ] 43071 ] 43072 [ 43073 [[link beast.ref.boost__beast__zlib__deflate_stream.upper_bound [*upper_bound]]] 43074 [ 43075 Returns the upper limit on the size of a compressed block. 43076 ] 43077 ] 43078 [ 43079 [[link beast.ref.boost__beast__zlib__deflate_stream.write [*write]]] 43080 [ 43081 Compress input and write output. 43082 ] 43083 ] 43084] 43085 43086[heading Description] 43087This is a port of zlib's "deflate" functionality to C++. [section:clear zlib::deflate_stream::clear] 43088[indexterm2 clear..zlib::deflate_stream] 43089Clear the stream. 43090[heading Synopsis] 43091``` 43092void 43093clear(); 43094``` 43095 43096[heading Description] 43097This function resets the stream and frees all dynamically allocated internal buffers. The compression settings are left unchanged. 43098[heading Remarks] 43099Any unprocessed input or pending output from previous calls are discarded. 43100[endsect] 43101[section:deflate_stream zlib::deflate_stream::deflate_stream] 43102[indexterm2 deflate_stream..zlib::deflate_stream] 43103Construct a default deflate stream. 43104[heading Synopsis] 43105``` 43106deflate_stream(); 43107``` 43108 43109[heading Description] 43110Upon construction, the stream settings will be set to these default values: 43111 43112* `level = 6` 43113 43114 43115* `windowBits = 15` 43116 43117 43118* `memLevel = 8` 43119 43120 43121* `strategy = Strategy::normal` 43122 43123Although the stream is ready to be used immediately after construction, any required internal buffers are not dynamically allocated until needed. [endsect] 43124[section:params zlib::deflate_stream::params] 43125[indexterm2 params..zlib::deflate_stream] 43126Update the compression level and strategy. 43127[heading Synopsis] 43128``` 43129void 43130params( 43131 z_params& zs, 43132 int level, 43133 Strategy strategy, 43134 error_code& ec); 43135``` 43136 43137[heading Description] 43138This function dynamically updates the compression level and compression strategy. The interpretation of level and strategy is as in [link beast.ref.boost__beast__zlib__deflate_stream.reset `zlib::deflate_stream::reset`]. This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. If the compression level is changed, the input available so far is compressed with the old level (and may be flushed); the new level will take effect only at the next call of [link beast.ref.boost__beast__zlib__deflate_stream.write `zlib::deflate_stream::write`]. 43139Before the call of `params`, the stream state must be set as for a call of [link beast.ref.boost__beast__zlib__deflate_stream.write `zlib::deflate_stream::write`], since the currently available input may have to be compressed and flushed. In particular, `zs.avail_out` must be non-zero. 43140[heading Return Value] 43141`Z_OK` if success, `Z_STREAM_ERROR` if the source stream state was inconsistent or if a parameter was invalid, `error::need_buffers` if `zs.avail_out` was zero. 43142[endsect] 43143[section:pending zlib::deflate_stream::pending] 43144[indexterm2 pending..zlib::deflate_stream] 43145Return bits pending in the output. 43146[heading Synopsis] 43147``` 43148void 43149pending( 43150 unsigned* value, 43151 int* bits); 43152``` 43153 43154[heading Description] 43155This function returns the number of bytes and bits of output that have been generated, but not yet provided in the available output. The bytes not provided would be due to the available output space having being consumed. The number of bits of output not provided are between 0 and 7, where they await more bits to join them in order to fill out a full byte. If pending or bits are `nullptr`, then those values are not set. 43156[heading Return Value] 43157`Z_OK` if success, or `Z_STREAM_ERROR` if the source stream state was inconsistent. 43158[endsect] 43159[section:prime zlib::deflate_stream::prime] 43160[indexterm2 prime..zlib::deflate_stream] 43161Insert bits into the compressed output stream. 43162[heading Synopsis] 43163``` 43164void 43165prime( 43166 int bits, 43167 int value, 43168 error_code& ec); 43169``` 43170 43171[heading Description] 43172This function inserts bits in the deflate output stream. The intent is that this function is used to start off the deflate output with the bits leftover from a previous deflate stream when appending to it. As such, this function can only be used for raw deflate, and must be used before the first `write` call after an initialization. `bits` must be less than or equal to 16, and that many of the least significant bits of `value` will be inserted in the output. 43173[heading Return Value] 43174`error::need_buffers` if there was not enough room in the internal buffer to insert the bits. 43175[endsect] 43176[section:reset zlib::deflate_stream::reset] 43177[indexterm2 reset..zlib::deflate_stream] 43178Reset the stream and compression settings. ``` 43179void 43180``[link beast.ref.boost__beast__zlib__deflate_stream.reset.overload1 reset]``( 43181 int level, 43182 int windowBits, 43183 int memLevel, 43184 Strategy strategy); 43185 ``[''''»''' [link beast.ref.boost__beast__zlib__deflate_stream.reset.overload1 more...]]`` 43186 43187``` 43188Reset the stream without deallocating memory. ``` 43189void 43190``[link beast.ref.boost__beast__zlib__deflate_stream.reset.overload2 reset]``(); 43191 ``[''''»''' [link beast.ref.boost__beast__zlib__deflate_stream.reset.overload2 more...]]`` 43192``` 43193[section:overload1 zlib::deflate_stream::reset (1 of 2 overloads)] 43194Reset the stream and compression settings. 43195[heading Synopsis] 43196``` 43197void 43198reset( 43199 int level, 43200 int windowBits, 43201 int memLevel, 43202 Strategy strategy); 43203``` 43204 43205[heading Description] 43206This function initializes the stream to the specified compression settings. 43207Although the stream is ready to be used immediately after a reset, any required internal buffers are not dynamically allocated until needed. 43208[heading Remarks] 43209Any unprocessed input or pending output from previous calls are discarded. 43210[endsect] 43211[section:overload2 zlib::deflate_stream::reset (2 of 2 overloads)] 43212Reset the stream without deallocating memory. 43213[heading Synopsis] 43214``` 43215void 43216reset(); 43217``` 43218 43219[heading Description] 43220This function performs the equivalent of calling `clear` followed by `reset` with the same compression settings, without deallocating the internal buffers. 43221[heading Remarks] 43222Any unprocessed input or pending output from previous calls are discarded. 43223[endsect] 43224[endsect] 43225 43226[section:tune zlib::deflate_stream::tune] 43227[indexterm2 tune..zlib::deflate_stream] 43228Fine tune internal compression parameters. 43229[heading Synopsis] 43230``` 43231void 43232tune( 43233 int good_length, 43234 int max_lazy, 43235 int nice_length, 43236 int max_chain); 43237``` 43238 43239[heading Description] 43240Compression parameters should only be tuned by someone who understands the algorithm used by zlib's deflate for searching for the best matching string, and even then only by the most fanatic optimizer trying to squeeze out the last compressed bit for their specific input data. Read the deflate.c source code (ZLib) for the meaning of the max\_lazy, good\_length, nice\_length, and max\_chain parameters. [endsect] 43241[section:upper_bound zlib::deflate_stream::upper_bound] 43242[indexterm2 upper_bound..zlib::deflate_stream] 43243Returns the upper limit on the size of a compressed block. 43244[heading Synopsis] 43245``` 43246std::size_t 43247upper_bound( 43248 std::size_t sourceLen) const; 43249``` 43250 43251[heading Description] 43252This function makes a conservative estimate of the maximum number of bytes needed to store the result of compressing a block of data based on the current compression level and strategy. 43253[heading Parameters] 43254[table [[Name][Description]] 43255 [[`sourceLen`][ 43256 43257The size of the uncompressed data. 43258 ]] 43259] 43260[heading Return Value] 43261The maximum number of resulting compressed bytes. 43262[endsect] 43263[section:write zlib::deflate_stream::write] 43264[indexterm2 write..zlib::deflate_stream] 43265Compress input and write output. 43266[heading Synopsis] 43267``` 43268void 43269write( 43270 z_params& zs, 43271 Flush flush, 43272 error_code& ec); 43273``` 43274 43275[heading Description] 43276This function compresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush. 43277In each call, one or both of these actions are performed: 43278 43279* Compress more input starting at `zs.next_in` and update `zs.next_in` and `zs.avail_in` accordingly. If not all input can be processed (because there is not enough room in the output buffer), `zs.next_in` and `zs.avail_in` are updated and processing will resume at this point for the next call. 43280 43281 43282* Provide more output starting at `zs.next_out` and update `zs.next_out` and `zs.avail_out` accordingly. This action is forced if the parameter flush is not `Flush::none`. Forcing flush frequently degrades the compression ratio, so this parameter should be set only when necessary (in interactive applications). Some output may be provided even if flush is not set. 43283 43284Before the call, the application must ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating `zs.avail_in` or `zs.avail_out` accordingly; `zs.avail_out` should never be zero before the call. The application can consume the compressed output when it wants, for example when the output buffer is full (`zs.avail_out == 0`), or after each call of `write`. If `write` returns no error with zero `zs.avail_out`, it must be called again after making room in the output buffer because there might be more output pending. 43285Normally the parameter flush is set to `Flush::none`, which allows deflate to decide how much data to accumulate before producing output, in order to maximize compression. 43286If the parameter flush is set to `Flush::sync`, all pending output is flushed to the output buffer and the output is aligned on a byte boundary, so that the decompressor can get all input data available so far. In particular `zs.avail_in` is zero after the call if enough output space has been provided before the call. Flushing may degrade compression for some compression algorithms and so it should be used only when necessary. This completes the current deflate block and follows it with an empty stored block that is three bits plus filler bits to the next byte, followed by the four bytes `{ 0x00, 0x00 0xff 0xff }`. 43287If flush is set to `Flush::partial`, all pending output is flushed to the output buffer, but the output is not aligned to a byte boundary. All of the input data so far will be available to the decompressor, as for Z\_SYNC\_FLUSH. This completes the current deflate block and follows it with an empty fixed codes block that is 10 bits long. This assures that enough bytes are output in order for the decompressor to finish the block before the empty fixed code block. 43288If flush is set to `Flush::block`, a deflate block is completed and emitted, as for `Flush::sync`, but the output is not aligned on a byte boundary, and up to seven bits of the current block are held to be written as the next byte after the next deflate block is completed. In this case, the decompressor may not be provided enough bits at this point in order to complete decompression of the data provided so far to the compressor. It may need to wait for the next block to be emitted. This is for advanced applications that need to control the emission of deflate blocks. 43289If flush is set to `Flush::full`, all output is flushed as with `Flush::sync`, and the compression state is reset so that decompression can restart from this point if previous compressed data has been damaged or if random access is desired. Using `Flush::full` too often can seriously degrade compression. 43290If `write` returns with `zs.avail_out == 0`, this function must be called again with the same value of the flush parameter and more output space (updated `zs.avail_out`), until the flush is complete (`write` returns with non-zero `zs.avail_out`). In the case of a `Flush::full`or `Flush::sync`, make sure that `zs.avail_out` is greater than six to avoid repeated flush markers due to `zs.avail_out == 0` on return. 43291If the parameter flush is set to `Flush::finish`, pending input is processed, pending output is flushed and deflate returns the error `error::end_of_stream` if there was enough output space; if deflate returns with no error, this function must be called again with `Flush::finish` and more output space (updated `zs.avail_out`) but no more input data, until it returns the error `error::end_of_stream` or another error. After `write` has returned the `error::end_of_stream` error, the only possible operations on the stream are to reset or destroy. 43292`Flush::finish` can be used immediately after initialization if all the compression is to be done in a single step. In this case, `zs.avail_out` must be at least value returned by `upper_bound` (see below). Then `write` is guaranteed to return the `error::end_of_stream` error. If not enough output space is provided, deflate will not return `error::end_of_stream`, and it must be called again as described above. 43293`write` returns no error if some progress has been made (more input processed or more output produced), `error::end_of_stream` if all input has been consumed and all output has been produced (only when flush is set to `Flush::finish`), `error::stream_error` if the stream state was inconsistent (for example if `zs.next_in` or `zs.next_out` was `nullptr`), `error::need_buffers` if no progress is possible (for example `zs.avail_in` or `zs.avail_out` was zero). Note that `error::need_buffers` is not fatal, and `write` can be called again with more input and more output space to continue compressing. [endsect] 43294 43295 43296 43297Convenience header [include_file boost/beast/zlib.hpp] 43298 43299[endsect] 43300 43301 43302 43303[section:boost__beast__zlib__deflate_upper_bound zlib::deflate_upper_bound] 43304[indexterm1 zlib::deflate_upper_bound] 43305Returns the upper limit on the size of a compressed block. 43306[heading Synopsis] 43307 43308Defined in header [include_file boost/beast/zlib/deflate_stream.hpp] 43309 43310 43311 43312``` 43313std::size_t 43314deflate_upper_bound( 43315 std::size_t bytes); 43316 43317``` 43318 43319[heading Description] 43320This function makes a conservative estimate of the maximum number of bytes needed to store the result of compressing a block of data. 43321[heading Parameters] 43322[table [[Name][Description]] 43323 [[`bytes`][ 43324 43325The size of the uncompressed data. 43326 ]] 43327] 43328[heading Return Value] 43329The maximum number of resulting compressed bytes. 43330 43331 43332 43333Convenience header [include_file boost/beast/zlib.hpp] 43334 43335[endsect] 43336[section:boost__beast__zlib__error zlib::error] 43337[indexterm1 zlib::error] 43338Error codes returned by the deflate codecs. 43339[heading Synopsis] 43340 43341Defined in header [include_file boost/beast/zlib/error.hpp] 43342 43343 43344``` 43345enum error 43346``` 43347 43348[indexterm2 need_buffers..zlib::error] 43349[indexterm2 end_of_stream..zlib::error] 43350[indexterm2 need_dict..zlib::error] 43351[indexterm2 stream_error..zlib::error] 43352[indexterm2 invalid_block_type..zlib::error] 43353[indexterm2 invalid_stored_length..zlib::error] 43354[indexterm2 too_many_symbols..zlib::error] 43355[indexterm2 invalid_code_lengths..zlib::error] 43356[indexterm2 invalid_code_lenths..zlib::error] 43357[indexterm2 invalid_bit_length_repeat..zlib::error] 43358[indexterm2 missing_eob..zlib::error] 43359[indexterm2 invalid_literal_length..zlib::error] 43360[indexterm2 invalid_distance_code..zlib::error] 43361[indexterm2 invalid_distance..zlib::error] 43362[indexterm2 over_subscribed_length..zlib::error] 43363[indexterm2 incomplete_length_set..zlib::error] 43364[indexterm2 general..zlib::error] 43365[heading Values] 43366[table [[Name][Description]] 43367 [[[^need_buffers]][Additional buffers are required. 43368 43369This error indicates that one or both of the buffers 43370provided buffers do not have sufficient available bytes 43371to make forward progress. 43372 43373This does not always indicate a failure condition. 43374 43375@note This is the same as `Z_BUF_ERROR` returned by ZLib. 43376 ]] 43377 [[[^end_of_stream]][End of stream reached. 43378 43379@note This is the same as `Z_STREAM_END` returned by ZLib. 43380 ]] 43381 [[[^need_dict]][Preset dictionary required. 43382 43383This error indicates that a preset dictionary was not provided and is now 43384needed at this point. 43385 43386This does not always indicate a failure condition. 43387 43388@note This is the same as `Z_NEED_DICT` returned by ZLib. 43389 ]] 43390 [[[^stream_error]][Invalid stream or parameters. 43391 43392This error is returned when invalid parameters are passed, 43393or the operation being performed is not consistent with the 43394state of the stream. For example, attempting to write data 43395when the end of stream is already reached. 43396 43397@note This is the same as `Z_STREAM_ERROR` returned by ZLib. 43398 ]] 43399 [[[^invalid_block_type]][Invalid block type. 43400 43401]] 43402 [[[^invalid_stored_length]][Invalid stored block length. 43403 43404]] 43405 [[[^too_many_symbols]][Too many length or distance symbols. 43406 43407]] 43408 [[[^invalid_code_lengths]][Invalid code lengths. 43409 43410]] 43411 [[[^invalid_code_lenths]][ 43412 43413]] 43414 [[[^invalid_bit_length_repeat]][Invalid bit length repeat. 43415 43416]] 43417 [[[^missing_eob]][Missing end of block code. 43418 43419]] 43420 [[[^invalid_literal_length]][Invalid literal/length code. 43421 43422]] 43423 [[[^invalid_distance_code]][Invalid distance code. 43424 43425]] 43426 [[[^invalid_distance]][Invalid distance too far back. 43427 43428]] 43429 [[[^over_subscribed_length]][Over-subscribed length code. 43430 43431]] 43432 [[[^incomplete_length_set]][Incomplete length set. 43433 43434]] 43435 [[[^general]][general error 43436 43437]] 43438] 43439 43440[heading Description] 43441 43442 43443 43444Convenience header [include_file boost/beast/zlib.hpp] 43445 43446[endsect] 43447[section:boost__beast__zlib__inflate_stream zlib::inflate_stream] 43448Raw deflate stream decompressor. 43449[heading Synopsis] 43450 43451Defined in header [include_file boost/beast/zlib/inflate_stream.hpp] 43452 43453 43454 43455``` 43456class inflate_stream : 43457 private inflate_stream 43458``` 43459[heading Member Functions] 43460[table [[Name][Description]] 43461 [ 43462 [[link beast.ref.boost__beast__zlib__inflate_stream.clear [*clear]]] 43463 [ 43464 Put the stream in a newly constructed state. 43465 ] 43466 ] 43467 [ 43468 [[link beast.ref.boost__beast__zlib__inflate_stream.inflate_stream [*inflate_stream]]] 43469 [ 43470 Construct a raw deflate decompression stream. 43471 ] 43472 ] 43473 [ 43474 [[link beast.ref.boost__beast__zlib__inflate_stream.reset [*reset]]] 43475 [ 43476 Reset the stream. 43477 ] 43478 ] 43479 [ 43480 [[link beast.ref.boost__beast__zlib__inflate_stream.write [*write]]] 43481 [ 43482 Decompress input and produce output. 43483 ] 43484 ] 43485] 43486 43487[heading Description] 43488This implements a raw deflate stream decompressor. The deflate protocol is a compression protocol described in "DEFLATE Compressed Data Format Specification version 1.3" located here: [@https://tools.ietf.org/html/rfc1951 https://tools.ietf.org/html/rfc1951] 43489The implementation is a refactored port to C++ of ZLib's "inflate". A more detailed description of ZLib is at [@http://zlib.net/ http://zlib.net/]. 43490Compression can be done in a single step if the buffers are large enough (for example if an input file is memory mapped), or can be done by repeated calls of the compression function. In the latter case, the application must provide more input and/or consume the output (providing more output space) before each call. [section:clear zlib::inflate_stream::clear] 43491[indexterm2 clear..zlib::inflate_stream] 43492Put the stream in a newly constructed state. 43493[heading Synopsis] 43494``` 43495void 43496clear(); 43497``` 43498 43499[heading Description] 43500All dynamically allocated memory is de-allocated. [endsect] 43501[section:inflate_stream zlib::inflate_stream::inflate_stream] 43502[indexterm2 inflate_stream..zlib::inflate_stream] 43503Construct a raw deflate decompression stream. 43504[heading Synopsis] 43505``` 43506inflate_stream(); 43507``` 43508 43509[heading Description] 43510The window size is set to the default of 15 bits. [endsect] 43511[section:reset zlib::inflate_stream::reset] 43512[indexterm2 reset..zlib::inflate_stream] 43513Reset the stream. ``` 43514void 43515``[link beast.ref.boost__beast__zlib__inflate_stream.reset.overload1 reset]``(); 43516 ``[''''»''' [link beast.ref.boost__beast__zlib__inflate_stream.reset.overload1 more...]]`` 43517 43518void 43519``[link beast.ref.boost__beast__zlib__inflate_stream.reset.overload2 reset]``( 43520 int windowBits); 43521 ``[''''»''' [link beast.ref.boost__beast__zlib__inflate_stream.reset.overload2 more...]]`` 43522``` 43523[section:overload1 zlib::inflate_stream::reset (1 of 2 overloads)] 43524Reset the stream. 43525[heading Synopsis] 43526``` 43527void 43528reset(); 43529``` 43530 43531[heading Description] 43532This puts the stream in a newly constructed state with the previously specified window size, but without de-allocating any dynamically created structures. [endsect] 43533[section:overload2 zlib::inflate_stream::reset (2 of 2 overloads)] 43534Reset the stream. 43535[heading Synopsis] 43536``` 43537void 43538reset( 43539 int windowBits); 43540``` 43541 43542[heading Description] 43543This puts the stream in a newly constructed state with the specified window size, but without de-allocating any dynamically created structures. [endsect] 43544[endsect] 43545 43546[section:write zlib::inflate_stream::write] 43547[indexterm2 write..zlib::inflate_stream] 43548Decompress input and produce output. 43549[heading Synopsis] 43550``` 43551void 43552write( 43553 z_params& zs, 43554 Flush flush, 43555 error_code& ec); 43556``` 43557 43558[heading Description] 43559This function decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush. 43560One or both of the following actions are performed: 43561 43562* Decompress more input starting at `zs.next_in` and update `zs.next_in` and `zs.avail_in` accordingly. If not all input can be processed (because there is not enough room in the output buffer), `zs.next_in` is updated and processing will resume at this point for the next call. 43563 43564 43565* Provide more output starting at `zs.next_out` and update `zs.next_out` and `zs.avail_out` accordingly. `write` provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter). 43566 43567Before the call, the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating the values in `zs` accordingly. The application can consume the uncompressed output when it wants, for example when the output buffer is full (`zs.avail_out == 0`), or after each call. If `write` returns no error and with zero `zs.avail_out`, it must be called again after making room in the output buffer because there might be more output pending. 43568The flush parameter may be `Flush::none`, `Flush::sync`, `Flush::finish`, `Flush::block`, or `Flush::trees`. `Flush::sync` requests to flush as much output as possible to the output buffer. `Flush::block` requests to stop if and when it gets to the next deflate block boundary. When decoding the zlib or gzip format, this will cause `write` to return immediately after the header and before the first block. When doing a raw inflate, `write` will go ahead and process the first block, and will return when it gets to the end of that block, or when it runs out of data. 43569The `Flush::block` option assists in appending to or combining deflate streams. Also to assist in this, on return `write` will set `zs.data_type` to the number of unused bits in the last byte taken from `zs.next_in`, plus 64 if `write` is currently decoding the last block in the deflate stream, plus 128 if `write` returned immediately after decoding an end-of-block code or decoding the complete header up to just before the first byte of the deflate stream. The end-of-block will not be indicated until all of the uncompressed data from that block has been written to `zs.next_out`. The number of unused bits may in general be greater than seven, except when bit 7 of `zs.data_type` is set, in which case the number of unused bits will be less than eight. `zs.data_type` is set as noted here every time `write` returns for all flush options, and so can be used to determine the amount of currently consumed input in bits. 43570The `Flush::trees` option behaves as `Flush::block` does, but it also returns when the end of each deflate block header is reached, before any actual data in that block is decoded. This allows the caller to determine the length of the deflate block header for later use in random access within a deflate block. 256 is added to the value of `zs.data_type` when `write` returns immediately after reaching the end of the deflate block header. 43571`write` should normally be called until it returns `error::end_of_stream` or another error. However if all decompression is to be performed in a single step (a single call of `write`), the parameter flush should be set to `Flush::finish`. In this case all pending input is processed and all pending output is flushed; `zs.avail_out` must be large enough to hold all of the uncompressed data for the operation to complete. (The size of the uncompressed data may have been saved by the compressor for this purpose.) The use of `Flush::finish` is not required to perform an inflation in one step. However it may be used to inform inflate that a faster approach can be used for the single call. `Flush::finish` also informs inflate to not maintain a sliding window if the stream completes, which reduces inflate's memory footprint. If the stream does not complete, either because not all of the stream is provided or not enough output space is provided, then a sliding window will be allocated and `write` can be called again to continue the operation as if `Flush::none` had been used. 43572In this implementation, `write` always flushes as much output as possible to the output buffer, and always uses the faster approach on the first call. So the effects of the flush parameter in this implementation are on the return value of `write` as noted below, when `write` returns early when `Flush::block` or `Flush::trees` is used, and when `write` avoids the allocation of memory for a sliding window when `Flush::finish` is used. 43573If a preset dictionary is needed after this call, `write` sets `zs.adler` to the Adler-32 checksum of the dictionary chosen by the compressor and returns `error::need_dictionary`; otherwise it sets `zs.adler` to the Adler-32 checksum of all output produced so far (that is, `zs.total_out bytes`) and returns no error, `error::end_of_stream`, or an error code as described below. At the end of the stream, `write` checks that its computed adler32 checksum is equal to that saved by the compressor and returns `error::end_of_stream` only if the checksum is correct. 43574This function returns no error if some progress has been made (more input processed or more output produced), `error::end_of_stream` if the end of the compressed data has been reached and all uncompressed output has been produced, `error::need_dictionary` if a preset dictionary is needed at this point, `error::invalid_data` if the input data was corrupted (input stream not conforming to the zlib format or incorrect check value), `error::stream_error` if the stream structure was inconsistent (for example if `zs.next_in` or `zs.next_out` was null), `error::need_buffers` if no progress is possible or if there was not enough room in the output buffer when `Flush::finish` is used. Note that `error::need_buffers` is not fatal, and `write` can be called again with more input and more output space to continue decompressing. [endsect] 43575 43576 43577 43578Convenience header [include_file boost/beast/zlib.hpp] 43579 43580[endsect] 43581 43582 43583 43584[section:boost__beast__zlib__kind zlib::kind] 43585[indexterm1 zlib::kind] 43586 43587[heading Synopsis] 43588 43589Defined in header [include_file boost/beast/zlib/zlib.hpp] 43590 43591 43592``` 43593enum kind 43594``` 43595 43596[indexterm2 binary..zlib::kind] 43597[indexterm2 text..zlib::kind] 43598[indexterm2 unknown..zlib::kind] 43599[heading Values] 43600[table [[Name][Description]] 43601 [[[^binary]][ 43602 43603]] 43604 [[[^text]][ 43605 43606]] 43607 [[[^unknown]][ 43608 43609]] 43610] 43611 43612[heading Description] 43613 43614 43615 43616Convenience header [include_file boost/beast/zlib.hpp] 43617 43618[endsect] 43619[section:boost__beast__zlib__uInt zlib::uInt] 43620[indexterm1 zlib::uInt] 43621 43622[heading Synopsis] 43623 43624Defined in header [include_file boost/beast/zlib/zlib.hpp] 43625 43626 43627 43628``` 43629using uInt = unsigned int; 43630``` 43631 43632[heading Description] 43633 43634 43635 43636Convenience header [include_file boost/beast/zlib.hpp] 43637 43638[endsect] 43639[section:boost__beast__zlib__z_params zlib::z_params] 43640Deflate codec parameters. 43641[heading Synopsis] 43642 43643Defined in header [include_file boost/beast/zlib/zlib.hpp] 43644 43645 43646 43647``` 43648struct z_params 43649``` 43650[heading Data Members] 43651[table [[Name][Description]] 43652 [ 43653 [[link beast.ref.boost__beast__zlib__z_params.avail_in [*avail_in]]] 43654 [ 43655 The number of bytes of input available at next_in. 43656 ] 43657 ] 43658 [ 43659 [[link beast.ref.boost__beast__zlib__z_params.avail_out [*avail_out]]] 43660 [ 43661 The remaining bytes of space at next_out. 43662 ] 43663 ] 43664 [ 43665 [[link beast.ref.boost__beast__zlib__z_params.data_type [*data_type]]] 43666 [ 43667 43668 ] 43669 ] 43670 [ 43671 [[link beast.ref.boost__beast__zlib__z_params.next_in [*next_in]]] 43672 [ 43673 A pointer to the next input byte. 43674 ] 43675 ] 43676 [ 43677 [[link beast.ref.boost__beast__zlib__z_params.next_out [*next_out]]] 43678 [ 43679 A pointer to the next output byte. 43680 ] 43681 ] 43682 [ 43683 [[link beast.ref.boost__beast__zlib__z_params.total_in [*total_in]]] 43684 [ 43685 The total number of input bytes read so far. 43686 ] 43687 ] 43688 [ 43689 [[link beast.ref.boost__beast__zlib__z_params.total_out [*total_out]]] 43690 [ 43691 The total number of bytes output so far. 43692 ] 43693 ] 43694] 43695 43696[heading Description] 43697Objects of this type are filled in by callers and provided to the deflate codec to define the input and output areas for the next compress or decompress operation. 43698The application must update next\_in and avail\_in when avail\_in has dropped to zero. It must update next\_out and avail\_out when avail\_out has dropped to zero. The application must initialize zalloc, zfree and opaque before calling the init function. All other fields are set by the compression library and must not be updated by the application. 43699The fields total\_in and total\_out can be used for statistics or progress reports. After compression, total\_in holds the total size of the uncompressed data and may be saved for use in the decompressor (particularly if the decompressor wants to decompress everything in a single step). [section:avail_in zlib::z_params::avail_in] 43700[indexterm2 avail_in..zlib::z_params] 43701The number of bytes of input available at `next_in`. 43702[heading Synopsis] 43703``` 43704std::size_t avail_in; 43705``` 43706 43707[heading Description] 43708If there is no more input, this should be set to zero. [endsect] 43709[section:avail_out zlib::z_params::avail_out] 43710[indexterm2 avail_out..zlib::z_params] 43711The remaining bytes of space at `next_out`. 43712[heading Synopsis] 43713``` 43714std::size_t avail_out; 43715``` 43716 43717[heading Description] 43718[endsect] 43719[section:data_type zlib::z_params::data_type] 43720[indexterm2 data_type..zlib::z_params] 43721 43722[heading Synopsis] 43723``` 43724int data_type = unknown; 43725``` 43726 43727[heading Description] 43728[endsect] 43729[section:next_in zlib::z_params::next_in] 43730[indexterm2 next_in..zlib::z_params] 43731A pointer to the next input byte. 43732[heading Synopsis] 43733``` 43734void const * next_in; 43735``` 43736 43737[heading Description] 43738If there is no more input, this may be set to `nullptr`. [endsect] 43739[section:next_out zlib::z_params::next_out] 43740[indexterm2 next_out..zlib::z_params] 43741A pointer to the next output byte. 43742[heading Synopsis] 43743``` 43744void * next_out; 43745``` 43746 43747[heading Description] 43748[endsect] 43749[section:total_in zlib::z_params::total_in] 43750[indexterm2 total_in..zlib::z_params] 43751The total number of input bytes read so far. 43752[heading Synopsis] 43753``` 43754std::size_t total_in = 0; 43755``` 43756 43757[heading Description] 43758[endsect] 43759[section:total_out zlib::z_params::total_out] 43760[indexterm2 total_out..zlib::z_params] 43761The total number of bytes output so far. 43762[heading Synopsis] 43763``` 43764std::size_t total_out = 0; 43765``` 43766 43767[heading Description] 43768[endsect] 43769 43770 43771 43772Convenience header [include_file boost/beast/zlib.hpp] 43773 43774[endsect] 43775 43776 43777 43778