[/ / Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com) / / Distributed under the Boost Software License, Version 1.0. (See accompanying / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /] [section:reference Reference] [xinclude quickref.xml] [include requirements/asynchronous_operations.qbk] [include requirements/read_write_operations.qbk] [include requirements/synchronous_socket_operations.qbk] [include requirements/asynchronous_socket_operations.qbk] [include requirements/AcceptableProtocol.qbk] [include requirements/AcceptHandler.qbk] [include requirements/AsyncRandomAccessReadDevice.qbk] [include requirements/AsyncRandomAccessWriteDevice.qbk] [include requirements/AsyncReadStream.qbk] [include requirements/AsyncWriteStream.qbk] [include requirements/BufferedHandshakeHandler.qbk] [include requirements/CompletionCondition.qbk] [include requirements/CompletionHandler.qbk] [include requirements/ConnectCondition.qbk] [include requirements/ConnectHandler.qbk] [include requirements/ConstBufferSequence.qbk] [include requirements/DynamicBuffer.qbk] [include requirements/DynamicBuffer_v1.qbk] [include requirements/DynamicBuffer_v2.qbk] [include requirements/Endpoint.qbk] [include requirements/EndpointSequence.qbk] [include requirements/ExecutionContext.qbk] [include requirements/Executor.qbk] [include requirements/GettableSerialPortOption.qbk] [include requirements/GettableSocketOption.qbk] [include requirements/Handler.qbk] [include requirements/HandshakeHandler.qbk] [include requirements/InternetProtocol.qbk] [include requirements/IoControlCommand.qbk] [include requirements/IoObjectService.qbk] [include requirements/IteratorConnectHandler.qbk] [include requirements/LegacyCompletionHandler.qbk] [include requirements/MoveAcceptHandler.qbk] [include requirements/MutableBufferSequence.qbk] [include requirements/ProtoAllocator.qbk] [include requirements/Protocol.qbk] [include requirements/RangeConnectHandler.qbk] [include requirements/ReadHandler.qbk] [include requirements/ResolveHandler.qbk] [include requirements/Service.qbk] [include requirements/SettableSerialPortOption.qbk] [include requirements/SettableSocketOption.qbk] [include requirements/ShutdownHandler.qbk] [include requirements/SignalHandler.qbk] [include requirements/SyncRandomAccessReadDevice.qbk] [include requirements/SyncRandomAccessWriteDevice.qbk] [include requirements/SyncReadStream.qbk] [include requirements/SyncWriteStream.qbk] [include requirements/TimeTraits.qbk] [include requirements/WaitHandler.qbk] [include requirements/WaitTraits.qbk] [include requirements/WriteHandler.qbk] [section:asio_handler_allocate asio_handler_allocate] [indexterm1 boost_asio.indexterm.asio_handler_allocate..asio_handler_allocate] Default allocation function for handlers. void * asio_handler_allocate( std::size_t size, ... ); Asynchronous operations may need to allocate temporary objects. Since asynchronous operations have a handler function object, these temporary objects can be said to be associated with the handler. Implement asio\_handler\_allocate and asio\_handler\_deallocate for your own handlers to provide custom allocation for these temporary objects. The default implementation of these allocation hooks uses `operator new` and `operator delete`. [heading Remarks] All temporary objects associated with a handler will be deallocated before the upcall to the handler is performed. This allows the same memory to be reused for a subsequent asynchronous operation initiated by the handler. [heading Example] class my_handler; void* asio_handler_allocate(std::size_t size, my_handler* context) { return ::operator new(size); } void asio_handler_deallocate(void* pointer, std::size_t size, my_handler* context) { ::operator delete(pointer); } [heading Requirements] ['Header: ][^boost/asio/handler_alloc_hook.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:asio_handler_deallocate asio_handler_deallocate] [indexterm1 boost_asio.indexterm.asio_handler_deallocate..asio_handler_deallocate] Default deallocation function for handlers. void asio_handler_deallocate( void * pointer, std::size_t size, ... ); Implement asio\_handler\_allocate and asio\_handler\_deallocate for your own handlers to provide custom allocation for the associated temporary objects. The default implementation of these allocation hooks uses `operator new` and `operator delete`. [heading Requirements] ['Header: ][^boost/asio/handler_alloc_hook.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:asio_handler_invoke asio_handler_invoke] [indexterm1 boost_asio.indexterm.asio_handler_invoke..asio_handler_invoke] Default invoke function for handlers. Default handler invocation hook used for non-const function objects. template< typename Function> void ``[link boost_asio.reference.asio_handler_invoke.overload1 asio_handler_invoke]``( Function & function, ... ); `` [''''»''' [link boost_asio.reference.asio_handler_invoke.overload1 more...]]`` Default handler invocation hook used for const function objects. template< typename Function> void ``[link boost_asio.reference.asio_handler_invoke.overload2 asio_handler_invoke]``( const Function & function, ... ); `` [''''»''' [link boost_asio.reference.asio_handler_invoke.overload2 more...]]`` Completion handlers for asynchronous operations are invoked by the [link boost_asio.reference.io_context `io_context`] associated with the corresponding object (e.g. a socket or deadline\_timer). Certain guarantees are made on when the handler may be invoked, in particular that a handler can only be invoked from a thread that is currently calling `run()` on the corresponding [link boost_asio.reference.io_context `io_context`] object. Handlers may subsequently be invoked through other objects (such as [link boost_asio.reference.io_context__strand `io_context::strand`] objects) that provide additional guarantees. When asynchronous operations are composed from other asynchronous operations, all intermediate handlers should be invoked using the same method as the final handler. This is required to ensure that user-defined objects are not accessed in a way that may violate the guarantees. This hooking function ensures that the invoked method used for the final handler is accessible at each intermediate step. Implement asio\_handler\_invoke for your own handlers to specify a custom invocation strategy. This default implementation invokes the function object like so: function(); If necessary, the default implementation makes a copy of the function object so that the non-const operator() can be used. [heading Example] class my_handler; template void asio_handler_invoke(Function function, my_handler* context) { context->strand_.dispatch(function); } [heading Requirements] ['Header: ][^boost/asio/handler_invoke_hook.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 asio_handler_invoke (1 of 2 overloads)] Default handler invocation hook used for non-const function objects. template< typename Function> void asio_handler_invoke( Function & function, ... ); [endsect] [section:overload2 asio_handler_invoke (2 of 2 overloads)] Default handler invocation hook used for const function objects. template< typename Function> void asio_handler_invoke( const Function & function, ... ); [endsect] [endsect] [section:asio_handler_is_continuation asio_handler_is_continuation] [indexterm1 boost_asio.indexterm.asio_handler_is_continuation..asio_handler_is_continuation] Default continuation function for handlers. bool asio_handler_is_continuation( ... ); Asynchronous operations may represent a continuation of the asynchronous control flow associated with the current handler. The implementation can use this knowledge to optimise scheduling of the handler. Implement asio\_handler\_is\_continuation for your own handlers to indicate when a handler represents a continuation. The default implementation of the continuation hook returns `false`. [heading Example] class my_handler; bool asio_handler_is_continuation(my_handler* context) { return true; } [heading Requirements] ['Header: ][^boost/asio/handler_continuation_hook.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:associated_allocator associated_allocator] Traits type used to obtain the allocator associated with an object. template< typename T, typename Allocator = std::allocator> struct associated_allocator [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.associated_allocator.type [*type]]] [If T has a nested type allocator_type, T::allocator_type. Otherwise Allocator. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.associated_allocator.get [*get]]] [If T has a nested type allocator_type, returns t.get_allocator(). Otherwise returns a. ] ] ] A program may specialise this traits type if the `T` template parameter in the specialisation is a user-defined type. The template parameter `Allocator` shall be a type meeting the Allocator requirements. Specialisations shall meet the following requirements, where `t` is a const reference to an object of type `T`, and `a` is an object of type `Allocator`. * Provide a nested typedef `type` that identifies a type meeting the Allocator requirements. * Provide a noexcept static member function named `get`, callable as `get(t)` and with return type `type`. * Provide a noexcept static member function named `get`, callable as `get(t,a)` and with return type `type`. [heading Requirements] ['Header: ][^boost/asio/associated_allocator.hpp] ['Convenience header: ][^boost/asio.hpp] [section:get associated_allocator::get] [indexterm2 boost_asio.indexterm.associated_allocator.get..get..associated_allocator] If `T` has a nested type `allocator_type`, returns `t.get_allocator()`. Otherwise returns `a`. static type get( const T & t, const Allocator & a = Allocator()); [endsect] [section:type associated_allocator::type] [indexterm2 boost_asio.indexterm.associated_allocator.type..type..associated_allocator] If `T` has a nested type `allocator_type`, `T::allocator_type`. Otherwise `Allocator`. typedef see_below type; [heading Requirements] ['Header: ][^boost/asio/associated_allocator.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [endsect] [section:associated_executor associated_executor] Traits type used to obtain the executor associated with an object. template< typename T, typename ``[link boost_asio.reference.Executor1 Executor]`` = system_executor> struct associated_executor [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.associated_executor.type [*type]]] [If T has a nested type executor_type, T::executor_type. Otherwise Executor. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.associated_executor.get [*get]]] [If T has a nested type executor_type, returns t.get_executor(). Otherwise returns ex. ] ] ] A program may specialise this traits type if the `T` template parameter in the specialisation is a user-defined type. The template parameter `Executor` shall be a type meeting the Executor requirements. Specialisations shall meet the following requirements, where `t` is a const reference to an object of type `T`, and `e` is an object of type `Executor`. * Provide a nested typedef `type` that identifies a type meeting the Executor requirements. * Provide a noexcept static member function named `get`, callable as `get(t)` and with return type `type`. * Provide a noexcept static member function named `get`, callable as `get(t,e)` and with return type `type`. [heading Requirements] ['Header: ][^boost/asio/associated_executor.hpp] ['Convenience header: ][^boost/asio.hpp] [section:get associated_executor::get] [indexterm2 boost_asio.indexterm.associated_executor.get..get..associated_executor] If `T` has a nested type `executor_type`, returns `t.get_executor()`. Otherwise returns `ex`. static type get( const T & t, const Executor & ex = Executor()); [endsect] [section:type associated_executor::type] [indexterm2 boost_asio.indexterm.associated_executor.type..type..associated_executor] If `T` has a nested type `executor_type`, `T::executor_type`. Otherwise `Executor`. typedef see_below type; [heading Requirements] ['Header: ][^boost/asio/associated_executor.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [endsect] [section:async_completion async_completion] Helper template to deduce the handler type from a CompletionToken, capture a local copy of the handler, and then create an [link boost_asio.reference.async_result `async_result`] for the handler. template< typename CompletionToken, typename Signature> struct async_completion [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.async_completion.completion_handler_type [*completion_handler_type]]] [The real handler type to be used for the asynchronous operation. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.async_completion.async_completion [*async_completion]]] [Constructor. ] ] ] [heading Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.async_completion.completion_handler [*completion_handler]]] [A copy of, or reference to, a real handler object. ] ] [ [[link boost_asio.reference.async_completion.result [*result]]] [The result of the asynchronous operation's initiating function. ] ] ] [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [section:async_completion async_completion::async_completion] [indexterm2 boost_asio.indexterm.async_completion.async_completion..async_completion..async_completion] Constructor. async_completion( CompletionToken & token); The constructor creates the concrete completion handler and makes the link between the handler and the asynchronous result. [endsect] [section:completion_handler async_completion::completion_handler] [indexterm2 boost_asio.indexterm.async_completion.completion_handler..completion_handler..async_completion] A copy of, or reference to, a real handler object. conditional< is_same< CompletionToken, completion_handler_type >::value, completion_handler_type &, completion_handler_type >::type completion_handler; [endsect] [section:completion_handler_type async_completion::completion_handler_type] [indexterm2 boost_asio.indexterm.async_completion.completion_handler_type..completion_handler_type..async_completion] The real handler type to be used for the asynchronous operation. typedef boost::asio::async_result< typename decay< CompletionToken >::type, Signature >::completion_handler_type completion_handler_type; [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.async_result.completion_handler_type [*completion_handler_type]]] [The concrete completion handler type for the specific signature. ] ] [ [[link boost_asio.reference.async_result.return_type [*return_type]]] [The return type of the initiating function. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.async_result.async_result [*async_result]]] [Construct an async result from a given handler. ] ] [ [[link boost_asio.reference.async_result.get [*get]]] [Obtain the value to be returned from the initiating function. ] ] [ [[link boost_asio.reference.async_result.initiate [*initiate]]] [Initiate the asynchronous operation that will produce the result, and obtain the value to be returned from the initiating function. ] ] ] The [link boost_asio.reference.async_result `async_result`] traits class is used for determining: * the concrete completion handler type to be called at the end of the asynchronous operation; * the initiating function return type; and * how the return value of the initiating function is obtained. The trait allows the handler and return types to be determined at the point where the specific completion handler signature is known. This template may be specialised for user-defined completion token types. The primary template assumes that the CompletionToken is the completion handler. [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:result async_completion::result] [indexterm2 boost_asio.indexterm.async_completion.result..result..async_completion] The result of the asynchronous operation's initiating function. async_result< typename decay< CompletionToken >::type, Signature > result; [endsect] [endsect] [section:async_compose async_compose] [indexterm1 boost_asio.indexterm.async_compose..async_compose] Launch an asynchronous operation with a stateful implementation. template< typename CompletionToken, typename Signature, typename Implementation, typename... IoObjectsOrExecutors> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_compose( Implementation && implementation, CompletionToken & token, IoObjectsOrExecutors &&... io_objects_or_executors); The async\_compose function simplifies the implementation of composed asynchronous operations automatically wrapping a stateful function object with a conforming intermediate completion handler. [heading Parameters] [variablelist [[implementation][A function object that contains the implementation of the composed asynchronous operation. The first argument to the function object is a non-const reference to the enclosing intermediate completion handler. The remaining arguments are any arguments that originate from the completion handlers of any asynchronous operations performed by the implementation.]] [[token][The completion token.]] [[io_objects_or_executors][Zero or more I/O objects or I/O executors for which outstanding work must be maintained.]] ] [heading Example:] struct async_echo_implementation { tcp::socket& socket_; boost::asio::mutable_buffer buffer_; enum { starting, reading, writing } state_; template void operator()(Self& self, boost::system::error_code error = {}, std::size_t n = 0) { switch (state_) { case starting: state_ = reading; socket_.async_read_some( buffer_, std::move(self)); break; case reading: if (error) { self.complete(error, 0); } else { state_ = writing; boost::asio::async_write(socket_, buffer_, boost::asio::transfer_exactly(n), std::move(self)); } break; case writing: self.complete(error, n); break; } } }; template auto async_echo(tcp::socket& socket, boost::asio::mutable_buffer buffer, CompletionToken&& token) -> typename boost::asio::async_result< typename std::decay::type, void(boost::system::error_code, std::size_t)>::return_type { return boost::asio::async_compose( async_echo_implementation{socket, buffer, async_echo_implementation::starting}, token, socket); } [heading Requirements] ['Header: ][^boost/asio/compose.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:async_connect async_connect] [indexterm1 boost_asio.indexterm.async_connect..async_connect] The `async_connect` function is a composed asynchronous operation that establishes a socket connection by trying each endpoint in a sequence. Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload1 async_connect]``( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_endpoint_sequence< EndpointSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload1 more...]]`` (Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload2 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload2 more...]]`` Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload3 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_connect.overload3 more...]]`` template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload4 async_connect]``( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, ConnectCondition connect_condition, RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_endpoint_sequence< EndpointSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload4 more...]]`` (Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload5 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, ConnectCondition connect_condition, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_connect.overload5 more...]]`` Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_connect.overload6 async_connect]``( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_connect.overload6 more...]]`` [heading Requirements] ['Header: ][^boost/asio/connect.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_connect (1 of 6 overloads)] Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_endpoint_sequence< EndpointSequence >::value >::type * = 0); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[endpoints][A sequence of endpoints.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, the successfully connected endpoint. // Otherwise, a default-constructed endpoint. const typename Protocol::endpoint& endpoint ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] tcp::resolver r(my_context); tcp::resolver::query q("host", "service"); tcp::socket s(my_context); // ... r.async_resolve(q, resolve_handler); // ... void resolve_handler( const boost::system::error_code& ec, tcp::resolver::results_type results) { if (!ec) { boost::asio::async_connect(s, results, connect_handler); } } // ... void connect_handler( const boost::system::error_code& ec, const tcp::endpoint& endpoint) { // ... } [endsect] [section:overload2 async_connect (2 of 6 overloads)] (Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if::value >::type * = 0); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[begin][An iterator pointing to the start of a sequence of endpoints.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, an iterator denoting the successfully // connected endpoint. Otherwise, the end iterator. Iterator iterator ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload assumes that a default constructed object of type `Iterator` represents the end of the sequence. This is a valid assumption for iterator types such as `boost::asio::ip::tcp::resolver::iterator`. [endsect] [section:overload3 async_connect (3 of 6 overloads)] Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[begin][An iterator pointing to the start of a sequence of endpoints.]] [[end][An iterator pointing to the end of a sequence of endpoints.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, an iterator denoting the successfully // connected endpoint. Otherwise, the end iterator. Iterator iterator ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] std::vector endpoints = ...; tcp::socket s(my_context); boost::asio::async_connect(s, endpoints.begin(), endpoints.end(), connect_handler); // ... void connect_handler( const boost::system::error_code& ec, std::vector::iterator i) { // ... } [endsect] [section:overload4 async_connect (4 of 6 overloads)] Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename ``[link boost_asio.reference.EndpointSequence EndpointSequence]``, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.RangeConnectHandler RangeConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, const EndpointSequence & endpoints, ConnectCondition connect_condition, RangeConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_endpoint_sequence< EndpointSequence >::value >::type * = 0); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[endpoints][A sequence of endpoints.]] [[connect_condition][A function object that is called prior to each connection attempt. The signature of the function object must be: `` bool connect_condition( const boost::system::error_code& ec, const typename Protocol::endpoint& next); `` The `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.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, an iterator denoting the successfully // connected endpoint. Otherwise, the end iterator. Iterator iterator ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] The following connect condition function object can be used to output information about the individual connection attempts: struct my_connect_condition { bool operator()( const boost::system::error_code& ec, const::tcp::endpoint& next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next << std::endl; return true; } }; It would be used with the `boost::asio::connect` function as follows: tcp::resolver r(my_context); tcp::resolver::query q("host", "service"); tcp::socket s(my_context); // ... r.async_resolve(q, resolve_handler); // ... void resolve_handler( const boost::system::error_code& ec, tcp::resolver::results_type results) { if (!ec) { boost::asio::async_connect(s, results, my_connect_condition(), connect_handler); } } // ... void connect_handler( const boost::system::error_code& ec, const tcp::endpoint& endpoint) { if (ec) { // An error occurred. } else { std::cout << "Connected to: " << endpoint << std::endl; } } [endsect] [section:overload5 async_connect (5 of 6 overloads)] (Deprecated: Use range overload.) Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, ConnectCondition connect_condition, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if::value >::type * = 0); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[begin][An iterator pointing to the start of a sequence of endpoints.]] [[connect_condition][A function object that is called prior to each connection attempt. The signature of the function object must be: `` bool connect_condition( const boost::system::error_code& ec, const typename Protocol::endpoint& next); `` The `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.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, an iterator denoting the successfully // connected endpoint. Otherwise, the end iterator. Iterator iterator ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload assumes that a default constructed object of type `Iterator` represents the end of the sequence. This is a valid assumption for iterator types such as `boost::asio::ip::tcp::resolver::iterator`. [endsect] [section:overload6 async_connect (6 of 6 overloads)] Asynchronously establishes a socket connection by trying each endpoint in a sequence. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``, typename Iterator, typename ``[link boost_asio.reference.ConnectCondition ConnectCondition]``, typename ``[link boost_asio.reference.IteratorConnectHandler IteratorConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( basic_socket< Protocol, Executor > & s, Iterator begin, Iterator end, ConnectCondition connect_condition, IteratorConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's `async_connect` member function, once for each endpoint in the sequence, until a connection is successfully established. [heading Parameters] [variablelist [[s][The socket to be connected. If the socket is already open, it will be closed.]] [[begin][An iterator pointing to the start of a sequence of endpoints.]] [[end][An iterator pointing to the end of a sequence of endpoints.]] [[connect_condition][A function object that is called prior to each connection attempt. The signature of the function object must be: `` bool connect_condition( const boost::system::error_code& ec, const typename Protocol::endpoint& next); `` The `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.]] [[handler][The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. if the sequence is empty, set to // boost::asio::error::not_found. Otherwise, contains the // error from the last connection attempt. const boost::system::error_code& error, // On success, an iterator denoting the successfully // connected endpoint. Otherwise, the end iterator. Iterator iterator ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] The following connect condition function object can be used to output information about the individual connection attempts: struct my_connect_condition { bool operator()( const boost::system::error_code& ec, const::tcp::endpoint& next) { if (ec) std::cout << "Error: " << ec.message() << std::endl; std::cout << "Trying: " << next << std::endl; return true; } }; It would be used with the `boost::asio::connect` function as follows: tcp::resolver r(my_context); tcp::resolver::query q("host", "service"); tcp::socket s(my_context); // ... r.async_resolve(q, resolve_handler); // ... void resolve_handler( const boost::system::error_code& ec, tcp::resolver::iterator i) { if (!ec) { tcp::resolver::iterator end; boost::asio::async_connect(s, i, end, my_connect_condition(), connect_handler); } } // ... void connect_handler( const boost::system::error_code& ec, tcp::resolver::iterator i) { if (ec) { // An error occurred. } else { std::cout << "Connected to: " << i->endpoint() << std::endl; } } [endsect] [endsect] [section:async_initiate async_initiate] [indexterm1 boost_asio.indexterm.async_initiate..async_initiate] template< typename CompletionToken, completion_signature Signature, typename Initiation, typename... Args> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_initiate( Initiation && initiation, CompletionToken & , Args &&... args); [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:async_read async_read] [indexterm1 boost_asio.indexterm.async_read..async_read] The `async_read` function is a composed asynchronous operation that reads a certain amount of data from a stream before completion. Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload1 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload1 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload2 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload2 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload3 async_read]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload3 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload4 async_read]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload4 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload5 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read.overload5 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload6 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read.overload6 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload7 async_read]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload7 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read.overload8 async_read]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read.overload8 more...]]`` [heading Requirements] ['Header: ][^boost/asio/read.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_read (1 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from 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.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read(s, boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] This overload is equivalent to calling: boost::asio::async_read( s, buffers, boost::asio::transfer_all(), handler); [endsect] [section:overload2 async_read (2 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_mutable_buffer_sequence< MutableBufferSequence >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. * The completion\_condition function object returns 0. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from 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.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read(s, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload3 async_read (3 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v1 && buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload is equivalent to calling: boost::asio::async_read( s, buffers, boost::asio::transfer_all(), handler); [endsect] [section:overload4 async_read (4 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload5 async_read (5 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, basic_streambuf< Allocator > & b, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffer is full (that is, it has reached maximum size). * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload is equivalent to calling: boost::asio::async_read( s, b, boost::asio::transfer_all(), handler); [endsect] [section:overload6 async_read (6 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffer is full (that is, it has reached maximum size). * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload7 async_read (7 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v2 buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload is equivalent to calling: boost::asio::async_read( s, buffers, boost::asio::transfer_all(), handler); [endsect] [section:overload8 async_read (8 of 8 overloads)] Start an asynchronous operation to read a certain amount of data from a stream. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read( AsyncReadStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The specified dynamic buffer sequence is full (that is, it has reached maximum size). * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. The program must ensure that the stream performs no other read operations (such as async\_read, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the stream's async\_read\_some function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes copied into the // buffers. If an error occurred, // this will be the number of // bytes successfully transferred // prior to the error. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:async_read_at async_read_at] [indexterm1 boost_asio.indexterm.async_read_at..async_read_at] The `async_read_at` function is a composed asynchronous operation that reads a certain amount of data at the specified offset. Start an asynchronous operation to read a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload1 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload1 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload2 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload2 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload3 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload3 more...]]`` template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_at.overload4 async_read_at]``( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_at.overload4 more...]]`` [heading Requirements] ['Header: ][^boost/asio/read_at.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_read_at (1 of 4 overloads)] Start an asynchronous operation to read a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. * An error occurred. This operation is implemented in terms of zero or more calls to the device's async\_read\_some\_at function. [heading Parameters] [variablelist [[d][The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.]] [[offset][The offset at which the data will be read.]] [[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. 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.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes copied into the buffers. If an error // occurred, this will be the number of bytes successfully // transferred prior to the error. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [heading Remarks] This overload is equivalent to calling: boost::asio::async_read_at( d, 42, buffers, boost::asio::transfer_all(), handler); [endsect] [section:overload2 async_read_at (2 of 4 overloads)] Start an asynchronous operation to read a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes. * The completion\_condition function object returns 0. [heading Parameters] [variablelist [[d][The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.]] [[offset][The offset at which the data will be read.]] [[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the device. 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.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some_at operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async\_read\_some\_at function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes copied into the buffers. If an error // occurred, this will be the number of bytes successfully // transferred prior to the error. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To read into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload3 async_read_at (3 of 4 overloads)] Start an asynchronous operation to read a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * An error occurred. This operation is implemented in terms of zero or more calls to the device's async\_read\_some\_at function. [heading Parameters] [variablelist [[d][The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.]] [[offset][The offset at which the data will be read.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes copied into the buffers. If an error // occurred, this will be the number of bytes successfully // transferred prior to the error. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] This overload is equivalent to calling: boost::asio::async_read_at( d, 42, b, boost::asio::transfer_all(), handler); [endsect] [section:overload4 async_read_at (4 of 4 overloads)] Start an asynchronous operation to read a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_at( AsyncRandomAccessReadDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read a certain number of bytes of data from a random access device at the specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the device's async\_read\_some\_at function. [heading Parameters] [variablelist [[d][The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.]] [[offset][The offset at which the data will be read.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_read_some_at operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the read operation is complete. A non-zero return value indicates the maximum number of bytes to be read on the next call to the device's async\_read\_some\_at function.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes copied into the buffers. If an error // occurred, this will be the number of bytes successfully // transferred prior to the error. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:async_read_until async_read_until] [indexterm1 boost_asio.indexterm.async_read_until..async_read_until] The `async_read_until` function is a composed asynchronous operation that reads data into a dynamic buffer sequence, or into a streambuf, until it contains a delimiter, matches a regular expression, or a function object indicates a match. Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload1 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload1 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload2 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload2 more...]]`` Start an asynchronous operation to read data into a dynamic buffer sequence until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload3 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload3 more...]]`` Start an asynchronous operation to read data into a dynamic buffer sequence until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload4 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v1 && buffers, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value &&is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload4 more...]]`` Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload5 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload5 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload6 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload6 more...]]`` Start an asynchronous operation to read data into a streambuf until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload7 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_read_until.overload7 more...]]`` Start an asynchronous operation to read data into a streambuf until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload8 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload8 more...]]`` Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload9 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload9 more...]]`` template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload10 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload10 more...]]`` Start an asynchronous operation to read data into a dynamic buffer sequence until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload11 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload11 more...]]`` Start an asynchronous operation to read data into a dynamic buffer sequence until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_read_until.overload12 async_read_until]``( AsyncReadStream & s, DynamicBuffer_v2 buffers, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value &&is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_read_until.overload12 more...]]`` [heading Requirements] ['Header: ][^boost/asio/read_until.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_read_until (1 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[delim][The delimiter character.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a newline is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, '\n', handler); After the `async_read_until` operation completes successfully, the buffer `data` contains the delimiter: { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the delimiter, so that the string `line` contains: { 'a', 'b', ..., 'c', '\n' } After the call to `erase`, the remaining data is left in the buffer `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload2 async_read_until (2 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[delim][The delimiter string.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a CR-LF sequence is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, "\r\n", handler); After the `async_read_until` operation completes successfully, the string `data` contains the delimiter: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the delimiter, so that the string `line` contains: { 'a', 'b', ..., 'c', '\r', '\n' } After the call to `erase`, the remaining data is left in the string `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload3 async_read_until (3 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the dynamic buffer sequence's get area matches the regular expression. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[expr][The regular expression.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer // sequence's get area up to and including the // substring that matches the regular expression. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a CR-LF sequence is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, boost::regex("\r\n"), handler); After the `async_read_until` operation completes successfully, the string `data` contains the data which matched the regular expression: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the match, so that the string `line` contains: { 'a', 'b', ..., 'c', '\r', '\n' } After the call to `erase`, the remaining data is left in the string `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload4 async_read_until (4 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v1 && buffers, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value &&is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[match_condition][The function object to be called to determine whether a match exists. The signature of the function object must be: `` pair match_condition(iterator begin, iterator end); `` where `iterator` represents the type: `` buffers_iterator `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area that have been fully consumed by the match // function. O if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the function object. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. [heading Examples] To asynchronously read data into a `std::string` until whitespace is encountered: typedef boost::asio::buffers_iterator< boost::asio::const_buffers_1> iterator; std::pair match_whitespace(iterator begin, iterator end) { iterator i = begin; while (i != end) if (std::isspace(*i++)) return std::make_pair(i, true); return std::make_pair(i, false); } ... void handler(const boost::system::error_code& e, std::size_t size); ... std::string data; boost::asio::async_read_until(s, data, match_whitespace, handler); To asynchronously read data into a `std::string` until a matching character is found: class match_char { public: explicit match_char(char c) : c_(c) {} template std::pair operator()( Iterator begin, Iterator end) const { Iterator i = begin; while (i != end) if (c_ == *i++) return std::make_pair(i, true); return std::make_pair(i, false); } private: char c_; }; namespace asio { template <> struct is_match_condition : public boost::true_type {}; } // namespace asio ... void handler(const boost::system::error_code& e, std::size_t size); ... std::string data; boost::asio::async_read_until(s, data, match_char('a'), handler); [endsect] [section:overload5 async_read_until (5 of 12 overloads)] Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the streambuf contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[delim][The delimiter character.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the streambuf's get // area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a streambuf until a newline is encountered: boost::asio::streambuf b; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::istream is(&b); std::string line; std::getline(is, line); ... } } ... boost::asio::async_read_until(s, b, '\n', handler); After the `async_read_until` operation completes successfully, the buffer `b` contains the delimiter: { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } The call to `std::getline` then extracts the data up to and including the newline (which is discarded), so that the string `line` contains: { 'a', 'b', ..., 'c' } The remaining data is left in the buffer `b` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload6 async_read_until (6 of 12 overloads)] Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the streambuf contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[delim][The delimiter string.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the streambuf's get // area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond the delimiter. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a streambuf until a newline is encountered: boost::asio::streambuf b; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::istream is(&b); std::string line; std::getline(is, line); ... } } ... boost::asio::async_read_until(s, b, "\r\n", handler); After the `async_read_until` operation completes successfully, the buffer `b` contains the delimiter: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `std::getline` then extracts the data up to and including the newline (which is discarded), so that the string `line` contains: { 'a', 'b', ..., 'c', '\r' } The remaining data is left in the buffer `b` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload7 async_read_until (7 of 12 overloads)] Start an asynchronous operation to read data into a streambuf until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the streambuf's get area matches the regular expression. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the streambuf's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[expr][The regular expression.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the streambuf's get // area up to and including the substring // that matches the regular. expression. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a streambuf until a CR-LF sequence is encountered: boost::asio::streambuf b; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::istream is(&b); std::string line; std::getline(is, line); ... } } ... boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); After the `async_read_until` operation completes successfully, the buffer `b` contains the data which matched the regular expression: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `std::getline` then extracts the data up to and including the newline (which is discarded), so that the string `line` contains: { 'a', 'b', ..., 'c', '\r' } The remaining data is left in the buffer `b` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload8 async_read_until (8 of 12 overloads)] Start an asynchronous operation to read data into a streambuf until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value >::type * = 0); This function is used to asynchronously read data into the specified streambuf until a user-defined match condition function object, when applied to the data contained in the streambuf, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A streambuf object into which the data will be read.]] [[match_condition][The function object to be called to determine whether a match exists. The signature of the function object must be: `` pair match_condition(iterator begin, iterator end); `` where `iterator` represents the type: `` buffers_iterator::const_buffers_type> `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the streambuf's get // area that have been fully consumed by the // match function. O if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the streambuf may contain additional data beyond that which matched the function object. An application will typically leave that data in the streambuf for a subsequent async\_read\_until operation to examine. The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. [heading Examples] To asynchronously read data into a streambuf until whitespace is encountered: typedef boost::asio::buffers_iterator< boost::asio::streambuf::const_buffers_type> iterator; std::pair match_whitespace(iterator begin, iterator end) { iterator i = begin; while (i != end) if (std::isspace(*i++)) return std::make_pair(i, true); return std::make_pair(i, false); } ... void handler(const boost::system::error_code& e, std::size_t size); ... boost::asio::streambuf b; boost::asio::async_read_until(s, b, match_whitespace, handler); To asynchronously read data into a streambuf until a matching character is found: class match_char { public: explicit match_char(char c) : c_(c) {} template std::pair operator()( Iterator begin, Iterator end) const { Iterator i = begin; while (i != end) if (c_ == *i++) return std::make_pair(i, true); return std::make_pair(i, false); } private: char c_; }; namespace asio { template <> struct is_match_condition : public boost::true_type {}; } // namespace asio ... void handler(const boost::system::error_code& e, std::size_t size); ... boost::asio::streambuf b; boost::asio::async_read_until(s, b, match_char('a'), handler); [endsect] [section:overload9 async_read_until (9 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, char delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[delim][The delimiter character.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a newline is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, '\n', handler); After the `async_read_until` operation completes successfully, the buffer `data` contains the delimiter: { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the delimiter, so that the string `line` contains: { 'a', 'b', ..., 'c', '\n' } After the call to `erase`, the remaining data is left in the buffer `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload10 async_read_until (10 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until it contains a specified delimiter. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, string_view delim, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The get area of the dynamic buffer sequence contains the specified delimiter. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[delim][The delimiter string.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area up to and including the delimiter. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond the delimiter. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a CR-LF sequence is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, "\r\n", handler); After the `async_read_until` operation completes successfully, the string `data` contains the delimiter: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the delimiter, so that the string `line` contains: { 'a', 'b', ..., 'c', '\r', '\n' } After the call to `erase`, the remaining data is left in the string `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload11 async_read_until (11 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until some part of its data matches a regular expression. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, const boost::regex & expr, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until the dynamic buffer sequence's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * A substring of the dynamic buffer sequence's get area matches the regular expression. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the dynamic buffer sequence's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[expr][The regular expression.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer // sequence's get area up to and including the // substring that matches the regular expression. // 0 if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the regular expression. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. [heading Example] To asynchronously read data into a `std::string` until a CR-LF sequence is encountered: std::string data; ... void handler(const boost::system::error_code& e, std::size_t size) { if (!e) { std::string line = data.substr(0, n); data.erase(0, n); ... } } ... boost::asio::async_read_until(s, data, boost::regex("\r\n"), handler); After the `async_read_until` operation completes successfully, the string `data` contains the data which matched the regular expression: { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } The call to `substr` then extracts the data up to and including the match, so that the string `line` contains: { 'a', 'b', ..., 'c', '\r', '\n' } After the call to `erase`, the remaining data is left in the string `data` as follows: { 'd', 'e', ... } This data may be the start of a new line, to be extracted by a subsequent `async_read_until` operation. [endsect] [section:overload12 async_read_until (12 of 12 overloads)] Start an asynchronous operation to read data into a dynamic buffer sequence until a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_read_until( AsyncReadStream & s, DynamicBuffer_v2 buffers, MatchCondition match_condition, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_match_condition< MatchCondition >::value &&is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously read data into the specified dynamic buffer sequence until a user-defined match condition function object, when applied to the data contained in the dynamic buffer sequence, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * The match condition function object returns a std::pair where the second element evaluates to true. * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function, and is known as a ['composed operation]. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async\_read, async\_read\_until, the stream's async\_read\_some function, or any other composed operations that perform reads) until this operation completes. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[buffers][The dynamic buffer sequence 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.]] [[match_condition][The function object to be called to determine whether a match exists. The signature of the function object must be: `` pair match_condition(iterator begin, iterator end); `` where `iterator` represents the type: `` buffers_iterator `` The iterator parameters `begin` and `end` define the range of bytes to be scanned to determine whether there is a match. The `first` member of the return value is an iterator marking one-past-the-end of the bytes that have been consumed by the match function. This iterator is used to calculate the `begin` parameter for any subsequent invocation of the match condition. The `second` member of the return value is true if a match has been found, false otherwise.]] [[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // The number of bytes in the dynamic buffer sequence's // get area that have been fully consumed by the match // function. O if an error occurred. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] After a successful async\_read\_until operation, the dynamic buffer sequence may contain additional data beyond that which matched the function object. An application will typically leave that data in the dynamic buffer sequence for a subsequent async\_read\_until operation to examine. The default implementation of the `is_match_condition` type trait evaluates to true for function pointers and function objects with a `result_type` typedef. It must be specialised for other user-defined function objects. [heading Examples] To asynchronously read data into a `std::string` until whitespace is encountered: typedef boost::asio::buffers_iterator< boost::asio::const_buffers_1> iterator; std::pair match_whitespace(iterator begin, iterator end) { iterator i = begin; while (i != end) if (std::isspace(*i++)) return std::make_pair(i, true); return std::make_pair(i, false); } ... void handler(const boost::system::error_code& e, std::size_t size); ... std::string data; boost::asio::async_read_until(s, data, match_whitespace, handler); To asynchronously read data into a `std::string` until a matching character is found: class match_char { public: explicit match_char(char c) : c_(c) {} template std::pair operator()( Iterator begin, Iterator end) const { Iterator i = begin; while (i != end) if (c_ == *i++) return std::make_pair(i, true); return std::make_pair(i, false); } private: char c_; }; namespace asio { template <> struct is_match_condition : public boost::true_type {}; } // namespace asio ... void handler(const boost::system::error_code& e, std::size_t size); ... std::string data; boost::asio::async_read_until(s, data, match_char('a'), handler); [endsect] [endsect] [section:async_result async_result] An interface for customising the behaviour of an initiating function. template< typename CompletionToken, typename Signature> class async_result [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.async_result.completion_handler_type [*completion_handler_type]]] [The concrete completion handler type for the specific signature. ] ] [ [[link boost_asio.reference.async_result.return_type [*return_type]]] [The return type of the initiating function. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.async_result.async_result [*async_result]]] [Construct an async result from a given handler. ] ] [ [[link boost_asio.reference.async_result.get [*get]]] [Obtain the value to be returned from the initiating function. ] ] [ [[link boost_asio.reference.async_result.initiate [*initiate]]] [Initiate the asynchronous operation that will produce the result, and obtain the value to be returned from the initiating function. ] ] ] The [link boost_asio.reference.async_result `async_result`] traits class is used for determining: * the concrete completion handler type to be called at the end of the asynchronous operation; * the initiating function return type; and * how the return value of the initiating function is obtained. The trait allows the handler and return types to be determined at the point where the specific completion handler signature is known. This template may be specialised for user-defined completion token types. The primary template assumes that the CompletionToken is the completion handler. [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [section:async_result async_result::async_result] [indexterm2 boost_asio.indexterm.async_result.async_result..async_result..async_result] Construct an async result from a given handler. async_result( completion_handler_type & h); When using a specalised [link boost_asio.reference.async_result `async_result`], the constructor has an opportunity to initialise some state associated with the completion handler, which is then returned from the initiating function. [endsect] [section:completion_handler_type async_result::completion_handler_type] [indexterm2 boost_asio.indexterm.async_result.completion_handler_type..completion_handler_type..async_result] The concrete completion handler type for the specific signature. typedef CompletionToken completion_handler_type; [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:get async_result::get] [indexterm2 boost_asio.indexterm.async_result.get..get..async_result] Obtain the value to be returned from the initiating function. return_type get(); [endsect] [section:initiate async_result::initiate] [indexterm2 boost_asio.indexterm.async_result.initiate..initiate..async_result] Initiate the asynchronous operation that will produce the result, and obtain the value to be returned from the initiating function. template< typename Initiation, typename RawCompletionToken, typename... Args> static return_type initiate( Initiation && initiation, RawCompletionToken && token, Args &&... args); [endsect] [section:return_type async_result::return_type] [indexterm2 boost_asio.indexterm.async_result.return_type..return_type..async_result] The return type of the initiating function. typedef void return_type; [heading Requirements] ['Header: ][^boost/asio/async_result.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [endsect] [section:async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_ async_result< std::packaged_task< Result(Args...)>, Signature >] Partial specialisation of `async_result` for `std::packaged_task`. template< typename Result, typename... Args, typename Signature> class async_result< std::packaged_task< Result(Args...)>, Signature > [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.completion_handler_type [*completion_handler_type]]] [The packaged task is the concrete completion handler type. ] ] [ [[link boost_asio.reference.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.return_type [*return_type]]] [The return type of the initiating function is the future obtained from the packaged task. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.async_result [*async_result]]] [The constructor extracts the future from the packaged task. ] ] [ [[link boost_asio.reference.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.get [*get]]] [Returns the packaged task's future. ] ] ] [heading Requirements] ['Header: ][^boost/asio/packaged_task.hpp] ['Convenience header: ][^boost/asio.hpp] [section:async_result async_result< std::packaged_task< Result(Args...)>, Signature >::async_result] [indexterm2 boost_asio.indexterm.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.async_result..async_result..async_result< std::packaged_task< Result(Args\.\.\.)>, Signature >] The constructor extracts the future from the packaged task. async_result( completion_handler_type & h); [endsect] [section:completion_handler_type async_result< std::packaged_task< Result(Args...)>, Signature >::completion_handler_type] [indexterm2 boost_asio.indexterm.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.completion_handler_type..completion_handler_type..async_result< std::packaged_task< Result(Args\.\.\.)>, Signature >] The packaged task is the concrete completion handler type. typedef std::packaged_task< Result(Args...)> completion_handler_type; [heading Requirements] ['Header: ][^boost/asio/packaged_task.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:get async_result< std::packaged_task< Result(Args...)>, Signature >::get] [indexterm2 boost_asio.indexterm.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.get..get..async_result< std::packaged_task< Result(Args\.\.\.)>, Signature >] Returns the packaged task's future. return_type get(); [endsect] [section:return_type async_result< std::packaged_task< Result(Args...)>, Signature >::return_type] [indexterm2 boost_asio.indexterm.async_result_lt__std__packaged_task_lt__Result_lp_Args_ellipsis__rp__gt__comma__Signature__gt_.return_type..return_type..async_result< std::packaged_task< Result(Args\.\.\.)>, Signature >] The return type of the initiating function is the future obtained from the packaged task. typedef std::future< Result > return_type; [heading Requirements] ['Header: ][^boost/asio/packaged_task.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [endsect] [section:async_write async_write] [indexterm1 boost_asio.indexterm.async_write..async_write] The `async_write` function is a composed asynchronous operation that writes a certain amount of data to a stream before completion. Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload1 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_const_buffer_sequence< ConstBufferSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload1 more...]]`` Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload2 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_const_buffer_sequence< ConstBufferSequence >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload2 more...]]`` Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload3 async_write]``( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload3 more...]]`` Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload4 async_write]``( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload4 more...]]`` Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload5 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write.overload5 more...]]`` Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload6 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler && handler); `` [''''»''' [link boost_asio.reference.async_write.overload6 more...]]`` Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload7 async_write]``( AsyncWriteStream & s, DynamicBuffer_v2 buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload7 more...]]`` Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write.overload8 async_write]``( AsyncWriteStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.async_write.overload8 more...]]`` [heading Requirements] ['Header: ][^boost/asio/write.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_write (1 of 8 overloads)] Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_const_buffer_sequence< ConstBufferSequence >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. * An error occurred. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][One or more buffers containing the data to be written. 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.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write(s, boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 async_write (2 of 8 overloads)] Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_const_buffer_sequence< ConstBufferSequence >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. * The completion\_condition function object returns 0. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][One or more buffers containing the data to be written. 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.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write(s, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload3 async_write (3 of 8 overloads)] Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. * An error occurred. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][The dynamic buffer sequence from which data will be written. 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. Successfully written data is automatically consumed from the buffers.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload4 async_write (4 of 8 overloads)] Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v1 DynamicBuffer_v1]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v1 && buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_dynamic_buffer_v1< typename decay< DynamicBuffer_v1 >::type >::value &&!is_dynamic_buffer_v2< typename decay< DynamicBuffer_v1 >::type >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. * The completion\_condition function object returns 0. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][The dynamic buffer sequence from which data will be written. 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. Successfully written data is automatically consumed from the buffers.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload5 async_write (5 of 8 overloads)] Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, basic_streambuf< Allocator > & b, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. * An error occurred. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload6 async_write (6 of 8 overloads)] Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler && handler); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. * The completion\_condition function object returns 0. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload7 async_write (7 of 8 overloads)] Start an asynchronous operation to write all of the supplied data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v2 buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. * An error occurred. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][The dynamic buffer sequence from which data will be written. 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. Successfully written data is automatically consumed from the buffers.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload8 async_write (8 of 8 overloads)] Start an asynchronous operation to write a certain amount of data to a stream. template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.DynamicBuffer_v2 DynamicBuffer_v2]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write( AsyncWriteStream & s, DynamicBuffer_v2 buffers, CompletionCondition completion_condition, WriteHandler && handler, typename enable_if< is_dynamic_buffer_v2< DynamicBuffer_v2 >::value >::type * = 0); This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied dynamic buffer sequence has been written. * The completion\_condition function object returns 0. This 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 write operations (such as async\_write, the stream's async\_write\_some function, or any other composed operations that perform writes) until this operation completes. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[buffers][The dynamic buffer sequence from which data will be written. 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. Successfully written data is automatically consumed from the buffers.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the stream's async\_write\_some function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes written from the // buffers. If an error occurred, // this will be less than the sum // of the buffer sizes. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:async_write_at async_write_at] [indexterm1 boost_asio.indexterm.async_write_at..async_write_at] The `async_write_at` function is a composed asynchronous operation that writes a certain amount of data at the specified offset before completion. Start an asynchronous operation to write all of the supplied data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload1 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload1 more...]]`` Start an asynchronous operation to write a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload2 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload2 more...]]`` Start an asynchronous operation to write all of the supplied data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload3 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload3 more...]]`` Start an asynchronous operation to write a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.async_write_at.overload4 async_write_at]``( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.async_write_at.overload4 more...]]`` [heading Requirements] ['Header: ][^boost/asio/write_at.hpp] ['Convenience header: ][^boost/asio.hpp] [section:overload1 async_write_at (1 of 4 overloads)] Start an asynchronous operation to write all of the supplied data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. * An error occurred. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function, and is known as a ['composed operation]. The program must ensure that the device performs no ['overlapping] write operations (such as async\_write\_at, the device's async\_write\_some\_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect. [heading Parameters] [variablelist [[d][The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.]] [[offset][The offset at which the data will be written.]] [[buffers][One or more buffers containing the data to be written. 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.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes written from the buffers. If an error // occurred, this will be less than the sum of the buffer sizes. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 async_write_at (2 of 4 overloads)] Start an asynchronous operation to write a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function, and is known as a ['composed operation]. The program must ensure that the device performs no ['overlapping] write operations (such as async\_write\_at, the device's async\_write\_some\_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect. [heading Parameters] [variablelist [[d][The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.]] [[offset][The offset at which the data will be written.]] [[buffers][One or more buffers containing the data to be written. 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.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some_at operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async\_write\_some\_at function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes written from the buffers. If an error // occurred, this will be less than the sum of the buffer sizes. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To write a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), boost::asio::transfer_at_least(32), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload3 async_write_at (3 of 4 overloads)] Start an asynchronous operation to write all of the supplied data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. * An error occurred. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function, and is known as a ['composed operation]. The program must ensure that the device performs no ['overlapping] write operations (such as async\_write\_at, the device's async\_write\_some\_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect. [heading Parameters] [variablelist [[d][The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.]] [[offset][The offset at which the data will be written.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes written from the buffers. If an error // occurred, this will be less than the sum of the buffer sizes. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [section:overload4 async_write_at (4 of 4 overloads)] Start an asynchronous operation to write a certain amount of data at the specified offset. template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.CompletionCondition CompletionCondition]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_write_at( AsyncRandomAccessWriteDevice & d, uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously write a certain number of bytes of data to a random access device at a specified offset. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true: * All of the data in the supplied [link boost_asio.reference.basic_streambuf `basic_streambuf`] has been written. * The completion\_condition function object returns 0. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function, and is known as a ['composed operation]. The program must ensure that the device performs no ['overlapping] write operations (such as async\_write\_at, the device's async\_write\_some\_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect. [heading Parameters] [variablelist [[d][The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.]] [[offset][The offset at which the data will be written.]] [[b][A [link boost_asio.reference.basic_streambuf `basic_streambuf`] object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]] [[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be: `` std::size_t completion_condition( // Result of latest async_write_some_at operation. const boost::system::error_code& error, // Number of bytes transferred so far. std::size_t bytes_transferred ); `` A return value of 0 indicates that the write operation is complete. A non-zero return value indicates the maximum number of bytes to be written on the next call to the device's async\_write\_some\_at function.]] [[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( // Result of operation. const boost::system::error_code& error, // Number of bytes written from the buffers. If an error // occurred, this will be less than the sum of the buffer sizes. std::size_t bytes_transferred ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:awaitable awaitable] The return type of a coroutine or asynchronous operation. template< typename T, typename ``[link boost_asio.reference.Executor1 Executor]`` = executor> class awaitable [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.awaitable.executor_type [*executor_type]]] [The executor type that will be used for the coroutine. ] ] [ [[link boost_asio.reference.awaitable.value_type [*value_type]]] [The type of the awaited value. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.awaitable.awaitable [*awaitable]]] [Default constructor. [hr] Move constructor. ] ] [ [[link boost_asio.reference.awaitable.valid [*valid]]] [Checks if the awaitable refers to a future result. ] ] [ [[link boost_asio.reference.awaitable._awaitable [*~awaitable]]] [Destructor. ] ] ] [heading Requirements] ['Header: ][^boost/asio/awaitable.hpp] ['Convenience header: ][^boost/asio.hpp] [section:awaitable awaitable::awaitable] [indexterm2 boost_asio.indexterm.awaitable.awaitable..awaitable..awaitable] Default constructor. constexpr ``[link boost_asio.reference.awaitable.awaitable.overload1 awaitable]``(); `` [''''»''' [link boost_asio.reference.awaitable.awaitable.overload1 more...]]`` Move constructor. ``[link boost_asio.reference.awaitable.awaitable.overload2 awaitable]``( awaitable && other); `` [''''»''' [link boost_asio.reference.awaitable.awaitable.overload2 more...]]`` [section:overload1 awaitable::awaitable (1 of 2 overloads)] Default constructor. constexpr awaitable(); [endsect] [section:overload2 awaitable::awaitable (2 of 2 overloads)] Move constructor. awaitable( awaitable && other); [endsect] [endsect] [section:executor_type awaitable::executor_type] [indexterm2 boost_asio.indexterm.awaitable.executor_type..executor_type..awaitable] The executor type that will be used for the coroutine. typedef Executor executor_type; [heading Requirements] ['Header: ][^boost/asio/awaitable.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:valid awaitable::valid] [indexterm2 boost_asio.indexterm.awaitable.valid..valid..awaitable] Checks if the awaitable refers to a future result. bool valid() const; [endsect] [section:value_type awaitable::value_type] [indexterm2 boost_asio.indexterm.awaitable.value_type..value_type..awaitable] The type of the awaited value. typedef T value_type; [heading Requirements] ['Header: ][^boost/asio/awaitable.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:_awaitable awaitable::~awaitable] [indexterm2 boost_asio.indexterm.awaitable._awaitable..~awaitable..awaitable] Destructor. ~awaitable(); [endsect] [endsect] [section:bad_executor bad_executor] Exception thrown when trying to access an empty polymorphic executor. class bad_executor : public std::exception [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.bad_executor.bad_executor [*bad_executor]]] [Constructor. ] ] [ [[link boost_asio.reference.bad_executor.what [*what]]] [Obtain message associated with exception. ] ] ] [heading Requirements] ['Header: ][^boost/asio/executor.hpp] ['Convenience header: ][^boost/asio.hpp] [section:bad_executor bad_executor::bad_executor] [indexterm2 boost_asio.indexterm.bad_executor.bad_executor..bad_executor..bad_executor] Constructor. bad_executor(); [endsect] [section:what bad_executor::what] [indexterm2 boost_asio.indexterm.bad_executor.what..what..bad_executor] Obtain message associated with exception. virtual const char * what() const; [endsect] [endsect] [section:basic_datagram_socket basic_datagram_socket] Provides datagram-oriented socket functionality. template< typename ``[link boost_asio.reference.Protocol Protocol]``, typename ``[link boost_asio.reference.Executor1 Executor]``> class basic_datagram_socket : public basic_socket< Protocol, Executor > [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket__rebind_executor [*rebind_executor]]] [Rebinds the socket type to another executor. ] ] [ [[link boost_asio.reference.basic_datagram_socket.broadcast [*broadcast]]] [Socket option to permit sending of broadcast messages. ] ] [ [[link boost_asio.reference.basic_datagram_socket.bytes_readable [*bytes_readable]]] [IO control command to get the amount of data that can be read without blocking. ] ] [ [[link boost_asio.reference.basic_datagram_socket.debug [*debug]]] [Socket option to enable socket-level debugging. ] ] [ [[link boost_asio.reference.basic_datagram_socket.do_not_route [*do_not_route]]] [Socket option to prevent routing, use local interfaces only. ] ] [ [[link boost_asio.reference.basic_datagram_socket.enable_connection_aborted [*enable_connection_aborted]]] [Socket option to report aborted connections on accept. ] ] [ [[link boost_asio.reference.basic_datagram_socket.endpoint_type [*endpoint_type]]] [The endpoint type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.executor_type [*executor_type]]] [The type of the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_datagram_socket.keep_alive [*keep_alive]]] [Socket option to send keep-alives. ] ] [ [[link boost_asio.reference.basic_datagram_socket.linger [*linger]]] [Socket option to specify whether the socket lingers on close if unsent data is present. ] ] [ [[link boost_asio.reference.basic_datagram_socket.lowest_layer_type [*lowest_layer_type]]] [A basic_socket is always the lowest layer. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_flags [*message_flags]]] [Bitmask type for flags that can be passed to send and receive operations. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_handle_type [*native_handle_type]]] [The native representation of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.out_of_band_inline [*out_of_band_inline]]] [Socket option for putting received out-of-band data inline. ] ] [ [[link boost_asio.reference.basic_datagram_socket.protocol_type [*protocol_type]]] [The protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_buffer_size [*receive_buffer_size]]] [Socket option for the receive buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_low_watermark [*receive_low_watermark]]] [Socket option for the receive low watermark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.reuse_address [*reuse_address]]] [Socket option to allow the socket to be bound to an address that is already in use. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_buffer_size [*send_buffer_size]]] [Socket option for the send buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_low_watermark [*send_low_watermark]]] [Socket option for the send low watermark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.shutdown_type [*shutdown_type]]] [Different ways a socket may be shutdown. ] ] [ [[link boost_asio.reference.basic_datagram_socket.wait_type [*wait_type]]] [Wait types. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.assign [*assign]]] [Assign an existing native socket to the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_connect [*async_connect]]] [Start an asynchronous connect. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_receive [*async_receive]]] [Start an asynchronous receive on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_receive_from [*async_receive_from]]] [Start an asynchronous receive. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_send [*async_send]]] [Start an asynchronous send on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_send_to [*async_send_to]]] [Start an asynchronous send. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_wait [*async_wait]]] [Asynchronously wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] [ [[link boost_asio.reference.basic_datagram_socket.at_mark [*at_mark]]] [Determine whether the socket is at the out-of-band data mark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.available [*available]]] [Determine the number of bytes available for reading. ] ] [ [[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket [*basic_datagram_socket]]] [Construct a basic_datagram_socket without opening it. [hr] Construct and open a basic_datagram_socket. [hr] Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. [hr] Construct a basic_datagram_socket on an existing native socket. [hr] Move-construct a basic_datagram_socket from another. [hr] Move-construct a basic_datagram_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.bind [*bind]]] [Bind the socket to the given local endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.cancel [*cancel]]] [Cancel all asynchronous operations associated with the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.close [*close]]] [Close the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.connect [*connect]]] [Connect the socket to the specified endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.get_executor [*get_executor]]] [Get the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_datagram_socket.get_option [*get_option]]] [Get an option from the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.io_control [*io_control]]] [Perform an IO control command on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.is_open [*is_open]]] [Determine whether the socket is open. ] ] [ [[link boost_asio.reference.basic_datagram_socket.local_endpoint [*local_endpoint]]] [Get the local endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.lowest_layer [*lowest_layer]]] [Get a reference to the lowest layer. [hr] Get a const reference to the lowest layer. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_handle [*native_handle]]] [Get the native socket representation. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_non_blocking [*native_non_blocking]]] [Gets the non-blocking mode of the native socket implementation. [hr] Sets the non-blocking mode of the native socket implementation. ] ] [ [[link boost_asio.reference.basic_datagram_socket.non_blocking [*non_blocking]]] [Gets the non-blocking mode of the socket. [hr] Sets the non-blocking mode of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.open [*open]]] [Open the socket using the specified protocol. ] ] [ [[link boost_asio.reference.basic_datagram_socket.operator_eq_ [*operator=]]] [Move-assign a basic_datagram_socket from another. [hr] Move-assign a basic_datagram_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive [*receive]]] [Receive some data on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_from [*receive_from]]] [Receive a datagram with the endpoint of the sender. ] ] [ [[link boost_asio.reference.basic_datagram_socket.release [*release]]] [Release ownership of the underlying native socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.remote_endpoint [*remote_endpoint]]] [Get the remote endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send [*send]]] [Send some data on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_to [*send_to]]] [Send a datagram to the specified endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.set_option [*set_option]]] [Set an option on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.shutdown [*shutdown]]] [Disable sends or receives on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.wait [*wait]]] [Wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] [ [[link boost_asio.reference.basic_datagram_socket._basic_datagram_socket [*~basic_datagram_socket]]] [Destroys the socket. ] ] ] [heading Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.max_connections [*max_connections]]] [(Deprecated: Use max_listen_connections.) The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_datagram_socket.max_listen_connections [*max_listen_connections]]] [The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_do_not_route [*message_do_not_route]]] [Specify that the data should not be subject to routing. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_end_of_record [*message_end_of_record]]] [Specifies that the data marks the end of a record. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_out_of_band [*message_out_of_band]]] [Process out-of-band data. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_peek [*message_peek]]] [Peek at incoming data without removing it from the input queue. ] ] ] [heading Protected Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.impl_ [*impl_]]] [] ] ] The [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] class template provides asynchronous and blocking datagram-oriented socket functionality. [heading Thread Safety] ['Distinct] ['objects:] Safe. ['Shared] ['objects:] Unsafe. [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [section:assign basic_datagram_socket::assign] [indexterm2 boost_asio.indexterm.basic_datagram_socket.assign..assign..basic_datagram_socket] Assign an existing native socket to the socket. void ``[link boost_asio.reference.basic_datagram_socket.assign.overload1 assign]``( const protocol_type & protocol, const native_handle_type & native_socket); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.assign.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.assign.overload2 assign]``( const protocol_type & protocol, const native_handle_type & native_socket, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.assign.overload2 more...]]`` [section:overload1 basic_datagram_socket::assign (1 of 2 overloads)] ['Inherited from basic_socket.] Assign an existing native socket to the socket. void assign( const protocol_type & protocol, const native_handle_type & native_socket); [endsect] [section:overload2 basic_datagram_socket::assign (2 of 2 overloads)] ['Inherited from basic_socket.] Assign an existing native socket to the socket. void assign( const protocol_type & protocol, const native_handle_type & native_socket, boost::system::error_code & ec); [endsect] [endsect] [section:async_connect basic_datagram_socket::async_connect] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_connect..async_connect..basic_datagram_socket] Start an asynchronous connect. template< typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_connect( const endpoint_type & peer_endpoint, ConnectHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately. The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is not returned to the closed state. [heading Parameters] [variablelist [[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]] [[handler][The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error // Result of operation ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] void connect_handler(const boost::system::error_code& error) { if (!error) { // Connect succeeded. } } ... boost::asio::ip::tcp::socket socket(my_context); boost::asio::ip::tcp::endpoint endpoint( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.async_connect(endpoint, connect_handler); [endsect] [section:async_receive basic_datagram_socket::async_receive] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_receive..async_receive..basic_datagram_socket] Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive.overload2 more...]]`` [section:overload1 basic_datagram_socket::async_receive (1 of 2 overloads)] Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received. 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.]] [[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes received. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] The async\_receive operation can only be used with a connected socket. Use the async\_receive\_from function to receive data on an unconnected datagram socket. [heading Example] To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive(boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::async_receive (2 of 2 overloads)] Start an asynchronous receive on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received. 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.]] [[flags][Flags specifying how the receive call is to be made.]] [[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes received. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] The async\_receive operation can only be used with a connected socket. Use the async\_receive\_from function to receive data on an unconnected datagram socket. [endsect] [endsect] [section:async_receive_from basic_datagram_socket::async_receive_from] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_receive_from..async_receive_from..basic_datagram_socket] Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload2 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_receive_from.overload2 more...]]`` [section:overload1 basic_datagram_socket::async_receive_from (1 of 2 overloads)] Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously receive a datagram. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received. 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.]] [[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram. Ownership of the sender\_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.]] [[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes received. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_receive_from( boost::asio::buffer(data, size), sender_endpoint, handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::async_receive_from (2 of 2 overloads)] Start an asynchronous receive. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, ReadHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously receive a datagram. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received. 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.]] [[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram. Ownership of the sender\_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.]] [[flags][Flags specifying how the receive call is to be made.]] [[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes received. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:async_send basic_datagram_socket::async_send] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_send..async_send..basic_datagram_socket] Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send.overload1 async_send]``( const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send.overload2 async_send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send.overload2 more...]]`` [section:overload1 basic_datagram_socket::async_send (1 of 2 overloads)] Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously send data on the datagram socket. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent on the socket. 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.]] [[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes sent. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] The async\_send operation can only be used with a connected socket. Use the async\_send\_to function to send data on an unconnected datagram socket. [heading Example] To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.async_send(boost::asio::buffer(data, size), handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::async_send (2 of 2 overloads)] Start an asynchronous send on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously send data on the datagram socket. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent on the socket. 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.]] [[flags][Flags specifying how the send call is to be made.]] [[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes sent. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Remarks] The async\_send operation can only be used with a connected socket. Use the async\_send\_to function to send data on an unconnected datagram socket. [endsect] [endsect] [section:async_send_to basic_datagram_socket::async_send_to] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_send_to..async_send_to..basic_datagram_socket] Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload2 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.async_send_to.overload2 more...]]`` [section:overload1 basic_datagram_socket::async_send_to (1 of 2 overloads)] Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent to the remote endpoint. 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.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] [[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes sent. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.async_send_to( boost::asio::buffer(data, size), destination, handler); See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::async_send_to (2 of 2 overloads)] Start an asynchronous send. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, WriteHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent to the remote endpoint. 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.]] [[flags][Flags specifying how the send call is to be made.]] [[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]] [[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error, // Result of operation. std::size_t bytes_transferred // Number of bytes sent. ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`]. ]] ] [endsect] [endsect] [section:async_wait basic_datagram_socket::async_wait] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.async_wait..async_wait..basic_datagram_socket] Asynchronously wait for the socket to become ready to read, ready to write, or to have pending error conditions. template< typename ``[link boost_asio.reference.WaitHandler WaitHandler]`` = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``> ``[link boost_asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]`` async_wait( wait_type w, WaitHandler && handler = ``[link boost_asio.reference.asynchronous_operations.default_completion_tokens ['DEFAULT]]``); This function is used to perform an asynchronous wait for a socket to enter a ready to read, write or error condition state. [heading Parameters] [variablelist [[w][Specifies the desired socket state.]] [[handler][The handler to be called when the wait operation completes. Copies will be made of the handler as required. The function signature of the handler must be: `` void handler( const boost::system::error_code& error // Result of operation ); `` Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using [link boost_asio.reference.post `post`].]] ] [heading Example] void wait_handler(const boost::system::error_code& error) { if (!error) { // Wait succeeded. } } ... boost::asio::ip::tcp::socket socket(my_context); ... socket.async_wait(boost::asio::ip::tcp::socket::wait_read, wait_handler); [endsect] [section:at_mark basic_datagram_socket::at_mark] [indexterm2 boost_asio.indexterm.basic_datagram_socket.at_mark..at_mark..basic_datagram_socket] Determine whether the socket is at the out-of-band data mark. bool ``[link boost_asio.reference.basic_datagram_socket.at_mark.overload1 at_mark]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.at_mark.overload1 more...]]`` bool ``[link boost_asio.reference.basic_datagram_socket.at_mark.overload2 at_mark]``( boost::system::error_code & ec) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.at_mark.overload2 more...]]`` [section:overload1 basic_datagram_socket::at_mark (1 of 2 overloads)] ['Inherited from basic_socket.] Determine whether the socket is at the out-of-band data mark. bool at_mark() const; This function is used to check whether the socket input is currently positioned at the out-of-band data mark. [heading Return Value] A bool indicating whether the socket is at the out-of-band data mark. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload2 basic_datagram_socket::at_mark (2 of 2 overloads)] ['Inherited from basic_socket.] Determine whether the socket is at the out-of-band data mark. bool at_mark( boost::system::error_code & ec) const; This function is used to check whether the socket input is currently positioned at the out-of-band data mark. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] A bool indicating whether the socket is at the out-of-band data mark. [endsect] [endsect] [section:available basic_datagram_socket::available] [indexterm2 boost_asio.indexterm.basic_datagram_socket.available..available..basic_datagram_socket] Determine the number of bytes available for reading. std::size_t ``[link boost_asio.reference.basic_datagram_socket.available.overload1 available]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.available.overload1 more...]]`` std::size_t ``[link boost_asio.reference.basic_datagram_socket.available.overload2 available]``( boost::system::error_code & ec) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.available.overload2 more...]]`` [section:overload1 basic_datagram_socket::available (1 of 2 overloads)] ['Inherited from basic_socket.] Determine the number of bytes available for reading. std::size_t available() const; This function is used to determine the number of bytes that may be read without blocking. [heading Return Value] The number of bytes that may be read without blocking, or 0 if an error occurs. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload2 basic_datagram_socket::available (2 of 2 overloads)] ['Inherited from basic_socket.] Determine the number of bytes available for reading. std::size_t available( boost::system::error_code & ec) const; This function is used to determine the number of bytes that may be read without blocking. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] The number of bytes that may be read without blocking, or 0 if an error occurs. [endsect] [endsect] [section:basic_datagram_socket basic_datagram_socket::basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket.basic_datagram_socket..basic_datagram_socket..basic_datagram_socket] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] without opening it. explicit ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload1 basic_datagram_socket]``( const executor_type & ex); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload1 more...]]`` template< typename ExecutionContext> explicit ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload2 basic_datagram_socket]``( ExecutionContext & context, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload2 more...]]`` Construct and open a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`]. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload3 basic_datagram_socket]``( const executor_type & ex, const protocol_type & protocol); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload3 more...]]`` template< typename ExecutionContext> ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload4 basic_datagram_socket]``( ExecutionContext & context, const protocol_type & protocol, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload4 more...]]`` Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`], opening it and binding it to the given local endpoint. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload5 basic_datagram_socket]``( const executor_type & ex, const endpoint_type & endpoint); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload5 more...]]`` template< typename ExecutionContext> ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload6 basic_datagram_socket]``( ExecutionContext & context, const endpoint_type & endpoint, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload6 more...]]`` Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] on an existing native socket. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload7 basic_datagram_socket]``( const executor_type & ex, const protocol_type & protocol, const native_handle_type & native_socket); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload7 more...]]`` template< typename ExecutionContext> ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload8 basic_datagram_socket]``( ExecutionContext & context, const protocol_type & protocol, const native_handle_type & native_socket, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload8 more...]]`` Move-construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from another. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload9 basic_datagram_socket]``( basic_datagram_socket && other); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload9 more...]]`` Move-construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from a socket of another protocol type. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``> ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload10 basic_datagram_socket]``( basic_datagram_socket< Protocol1, Executor1 > && other, typename enable_if< is_convertible< Protocol1, Protocol >::value &&is_convertible< Executor1, Executor >::value >::type * = 0); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload10 more...]]`` [section:overload1 basic_datagram_socket::basic_datagram_socket (1 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] without opening it. basic_datagram_socket( const executor_type & ex); This constructor creates a datagram socket without opening it. The `open()` function must be called before data can be sent or received on the socket. [heading Parameters] [variablelist [[ex][The I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket. ]] ] [endsect] [section:overload2 basic_datagram_socket::basic_datagram_socket (2 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] without opening it. template< typename ExecutionContext> basic_datagram_socket( ExecutionContext & context, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); This constructor creates a datagram socket without opening it. The `open()` function must be called before data can be sent or received on the socket. [heading Parameters] [variablelist [[context][An execution context which provides the I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket. ]] ] [endsect] [section:overload3 basic_datagram_socket::basic_datagram_socket (3 of 10 overloads)] Construct and open a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`]. basic_datagram_socket( const executor_type & ex, const protocol_type & protocol); This constructor creates and opens a datagram socket. [heading Parameters] [variablelist [[ex][The I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[protocol][An object specifying protocol parameters to be used.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload4 basic_datagram_socket::basic_datagram_socket (4 of 10 overloads)] Construct and open a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`]. template< typename ExecutionContext> basic_datagram_socket( ExecutionContext & context, const protocol_type & protocol, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); This constructor creates and opens a datagram socket. [heading Parameters] [variablelist [[context][An execution context which provides the I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[protocol][An object specifying protocol parameters to be used.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload5 basic_datagram_socket::basic_datagram_socket (5 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`], opening it and binding it to the given local endpoint. basic_datagram_socket( const executor_type & ex, const endpoint_type & endpoint); This constructor creates a datagram socket and automatically opens it bound to the specified endpoint on the local machine. The protocol used is the protocol associated with the given endpoint. [heading Parameters] [variablelist [[ex][The I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[endpoint][An endpoint on the local machine to which the datagram socket will be bound.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload6 basic_datagram_socket::basic_datagram_socket (6 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`], opening it and binding it to the given local endpoint. template< typename ExecutionContext> basic_datagram_socket( ExecutionContext & context, const endpoint_type & endpoint, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); This constructor creates a datagram socket and automatically opens it bound to the specified endpoint on the local machine. The protocol used is the protocol associated with the given endpoint. [heading Parameters] [variablelist [[context][An execution context which provides the I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[endpoint][An endpoint on the local machine to which the datagram socket will be bound.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload7 basic_datagram_socket::basic_datagram_socket (7 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] on an existing native socket. basic_datagram_socket( const executor_type & ex, const protocol_type & protocol, const native_handle_type & native_socket); This constructor creates a datagram socket object to hold an existing native socket. [heading Parameters] [variablelist [[ex][The I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[protocol][An object specifying protocol parameters to be used.]] [[native_socket][The new underlying socket implementation.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload8 basic_datagram_socket::basic_datagram_socket (8 of 10 overloads)] Construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] on an existing native socket. template< typename ExecutionContext> basic_datagram_socket( ExecutionContext & context, const protocol_type & protocol, const native_handle_type & native_socket, typename enable_if< is_convertible< ExecutionContext &, execution_context & >::value >::type * = 0); This constructor creates a datagram socket object to hold an existing native socket. [heading Parameters] [variablelist [[context][An execution context which provides the I/O executor that the socket will use, by default, to dispatch handlers for any asynchronous operations performed on the socket.]] [[protocol][An object specifying protocol parameters to be used.]] [[native_socket][The new underlying socket implementation.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload9 basic_datagram_socket::basic_datagram_socket (9 of 10 overloads)] Move-construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from another. basic_datagram_socket( basic_datagram_socket && other); This constructor moves a datagram socket from one object to another. [heading Parameters] [variablelist [[other][The other [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] object from which the move will occur.]] ] [heading Remarks] Following the move, the moved-from object is in the same state as if constructed using the `basic_datagram_socket(const executor_type&)` constructor. [endsect] [section:overload10 basic_datagram_socket::basic_datagram_socket (10 of 10 overloads)] Move-construct a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from a socket of another protocol type. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``> basic_datagram_socket( basic_datagram_socket< Protocol1, Executor1 > && other, typename enable_if< is_convertible< Protocol1, Protocol >::value &&is_convertible< Executor1, Executor >::value >::type * = 0); This constructor moves a datagram socket from one object to another. [heading Parameters] [variablelist [[other][The other [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] object from which the move will occur.]] ] [heading Remarks] Following the move, the moved-from object is in the same state as if constructed using the `basic_datagram_socket(const executor_type&)` constructor. [endsect] [endsect] [section:bind basic_datagram_socket::bind] [indexterm2 boost_asio.indexterm.basic_datagram_socket.bind..bind..basic_datagram_socket] Bind the socket to the given local endpoint. void ``[link boost_asio.reference.basic_datagram_socket.bind.overload1 bind]``( const endpoint_type & endpoint); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.bind.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.bind.overload2 bind]``( const endpoint_type & endpoint, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.bind.overload2 more...]]`` [section:overload1 basic_datagram_socket::bind (1 of 2 overloads)] ['Inherited from basic_socket.] Bind the socket to the given local endpoint. void bind( const endpoint_type & endpoint); This function binds the socket to the specified endpoint on the local machine. [heading Parameters] [variablelist [[endpoint][An endpoint on the local machine to which the socket will be bound.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); socket.open(boost::asio::ip::tcp::v4()); socket.bind(boost::asio::ip::tcp::endpoint( boost::asio::ip::tcp::v4(), 12345)); [endsect] [section:overload2 basic_datagram_socket::bind (2 of 2 overloads)] ['Inherited from basic_socket.] Bind the socket to the given local endpoint. void bind( const endpoint_type & endpoint, boost::system::error_code & ec); This function binds the socket to the specified endpoint on the local machine. [heading Parameters] [variablelist [[endpoint][An endpoint on the local machine to which the socket will be bound.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); socket.open(boost::asio::ip::tcp::v4()); boost::system::error_code ec; socket.bind(boost::asio::ip::tcp::endpoint( boost::asio::ip::tcp::v4(), 12345), ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:broadcast basic_datagram_socket::broadcast] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.broadcast..broadcast..basic_datagram_socket] Socket option to permit sending of broadcast messages. typedef implementation_defined broadcast; Implements the SOL\_SOCKET/SO\_BROADCAST socket option. [heading Examples] Setting the option: boost::asio::ip::udp::socket socket(my_context); ... boost::asio::socket_base::broadcast option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::udp::socket socket(my_context); ... boost::asio::socket_base::broadcast option; socket.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:bytes_readable basic_datagram_socket::bytes_readable] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.bytes_readable..bytes_readable..basic_datagram_socket] IO control command to get the amount of data that can be read without blocking. typedef implementation_defined bytes_readable; Implements the FIONREAD IO control command. [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::bytes_readable command(true); socket.io_control(command); std::size_t bytes_readable = command.get(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:cancel basic_datagram_socket::cancel] [indexterm2 boost_asio.indexterm.basic_datagram_socket.cancel..cancel..basic_datagram_socket] Cancel all asynchronous operations associated with the socket. void ``[link boost_asio.reference.basic_datagram_socket.cancel.overload1 cancel]``(); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.cancel.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.cancel.overload2 cancel]``( boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.cancel.overload2 more...]]`` [section:overload1 basic_datagram_socket::cancel (1 of 2 overloads)] ['Inherited from basic_socket.] Cancel all asynchronous operations associated with the socket. void cancel(); This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the `boost::asio::error::operation_aborted` error. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] Calls to `cancel()` will always fail with `boost::asio::error::operation_not_supported` when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use: * It will only cancel asynchronous operations that were initiated in the current thread. * It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed. For portable cancellation, consider using one of the following alternatives: * Disable asio's I/O completion port backend by defining BOOST\_ASIO\_DISABLE\_IOCP. * Use the `close()` function to simultaneously cancel the outstanding operations and close the socket. When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above. [endsect] [section:overload2 basic_datagram_socket::cancel (2 of 2 overloads)] ['Inherited from basic_socket.] Cancel all asynchronous operations associated with the socket. void cancel( boost::system::error_code & ec); This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the `boost::asio::error::operation_aborted` error. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Remarks] Calls to `cancel()` will always fail with `boost::asio::error::operation_not_supported` when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use: * It will only cancel asynchronous operations that were initiated in the current thread. * It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed. For portable cancellation, consider using one of the following alternatives: * Disable asio's I/O completion port backend by defining BOOST\_ASIO\_DISABLE\_IOCP. * Use the `close()` function to simultaneously cancel the outstanding operations and close the socket. When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above. [endsect] [endsect] [section:close basic_datagram_socket::close] [indexterm2 boost_asio.indexterm.basic_datagram_socket.close..close..basic_datagram_socket] Close the socket. void ``[link boost_asio.reference.basic_datagram_socket.close.overload1 close]``(); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.close.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.close.overload2 close]``( boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.close.overload2 more...]]`` [section:overload1 basic_datagram_socket::close (1 of 2 overloads)] ['Inherited from basic_socket.] Close the socket. void close(); This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the `boost::asio::error::operation_aborted` error. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. Note that, even if the function indicates an error, the underlying descriptor is closed.]] ] [heading Remarks] For portable behaviour with respect to graceful closure of a connected socket, call `shutdown()` before closing the socket. [endsect] [section:overload2 basic_datagram_socket::close (2 of 2 overloads)] ['Inherited from basic_socket.] Close the socket. void close( boost::system::error_code & ec); This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the `boost::asio::error::operation_aborted` error. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any. Note that, even if the function indicates an error, the underlying descriptor is closed.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::system::error_code ec; socket.close(ec); if (ec) { // An error occurred. } [heading Remarks] For portable behaviour with respect to graceful closure of a connected socket, call `shutdown()` before closing the socket. [endsect] [endsect] [section:connect basic_datagram_socket::connect] [indexterm2 boost_asio.indexterm.basic_datagram_socket.connect..connect..basic_datagram_socket] Connect the socket to the specified endpoint. void ``[link boost_asio.reference.basic_datagram_socket.connect.overload1 connect]``( const endpoint_type & peer_endpoint); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.connect.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.connect.overload2 connect]``( const endpoint_type & peer_endpoint, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.connect.overload2 more...]]`` [section:overload1 basic_datagram_socket::connect (1 of 2 overloads)] ['Inherited from basic_socket.] Connect the socket to the specified endpoint. void connect( const endpoint_type & peer_endpoint); This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs. The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is not returned to the closed state. [heading Parameters] [variablelist [[peer_endpoint][The remote endpoint to which the socket will be connected.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); boost::asio::ip::tcp::endpoint endpoint( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.connect(endpoint); [endsect] [section:overload2 basic_datagram_socket::connect (2 of 2 overloads)] ['Inherited from basic_socket.] Connect the socket to the specified endpoint. void connect( const endpoint_type & peer_endpoint, boost::system::error_code & ec); This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs. The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is not returned to the closed state. [heading Parameters] [variablelist [[peer_endpoint][The remote endpoint to which the socket will be connected.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); boost::asio::ip::tcp::endpoint endpoint( boost::asio::ip::address::from_string("1.2.3.4"), 12345); boost::system::error_code ec; socket.connect(endpoint, ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:debug basic_datagram_socket::debug] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.debug..debug..basic_datagram_socket] Socket option to enable socket-level debugging. typedef implementation_defined debug; Implements the SOL\_SOCKET/SO\_DEBUG socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::debug option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::debug option; socket.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:do_not_route basic_datagram_socket::do_not_route] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.do_not_route..do_not_route..basic_datagram_socket] Socket option to prevent routing, use local interfaces only. typedef implementation_defined do_not_route; Implements the SOL\_SOCKET/SO\_DONTROUTE socket option. [heading Examples] Setting the option: boost::asio::ip::udp::socket socket(my_context); ... boost::asio::socket_base::do_not_route option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::udp::socket socket(my_context); ... boost::asio::socket_base::do_not_route option; socket.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:enable_connection_aborted basic_datagram_socket::enable_connection_aborted] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.enable_connection_aborted..enable_connection_aborted..basic_datagram_socket] Socket option to report aborted connections on accept. typedef implementation_defined enable_connection_aborted; Implements a custom socket option that determines whether or not an accept operation is permitted to fail with `boost::asio::error::connection_aborted`. By default the option is false. [heading Examples] Setting the option: boost::asio::ip::tcp::acceptor acceptor(my_context); ... boost::asio::socket_base::enable_connection_aborted option(true); acceptor.set_option(option); Getting the current option value: boost::asio::ip::tcp::acceptor acceptor(my_context); ... boost::asio::socket_base::enable_connection_aborted option; acceptor.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:endpoint_type basic_datagram_socket::endpoint_type] [indexterm2 boost_asio.indexterm.basic_datagram_socket.endpoint_type..endpoint_type..basic_datagram_socket] The endpoint type. typedef Protocol::endpoint endpoint_type; [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:executor_type basic_datagram_socket::executor_type] [indexterm2 boost_asio.indexterm.basic_datagram_socket.executor_type..executor_type..basic_datagram_socket] The type of the executor associated with the object. typedef Executor executor_type; [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:get_executor basic_datagram_socket::get_executor] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.get_executor..get_executor..basic_datagram_socket] Get the executor associated with the object. executor_type get_executor(); [endsect] [section:get_option basic_datagram_socket::get_option] [indexterm2 boost_asio.indexterm.basic_datagram_socket.get_option..get_option..basic_datagram_socket] Get an option from the socket. template< typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``> void ``[link boost_asio.reference.basic_datagram_socket.get_option.overload1 get_option]``( GettableSocketOption & option) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.get_option.overload1 more...]]`` template< typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``> void ``[link boost_asio.reference.basic_datagram_socket.get_option.overload2 get_option]``( GettableSocketOption & option, boost::system::error_code & ec) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.get_option.overload2 more...]]`` [section:overload1 basic_datagram_socket::get_option (1 of 2 overloads)] ['Inherited from basic_socket.] Get an option from the socket. template< typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``> void get_option( GettableSocketOption & option) const; This function is used to get the current value of an option on the socket. [heading Parameters] [variablelist [[option][The option value to be obtained from the socket.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::socket::keep_alive option; socket.get_option(option); bool is_set = option.value(); [endsect] [section:overload2 basic_datagram_socket::get_option (2 of 2 overloads)] ['Inherited from basic_socket.] Get an option from the socket. template< typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``> void get_option( GettableSocketOption & option, boost::system::error_code & ec) const; This function is used to get the current value of an option on the socket. [heading Parameters] [variablelist [[option][The option value to be obtained from the socket.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::socket::keep_alive option; boost::system::error_code ec; socket.get_option(option, ec); if (ec) { // An error occurred. } bool is_set = option.value(); [endsect] [endsect] [section:impl_ basic_datagram_socket::impl_] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.impl_..impl_..basic_datagram_socket] detail::io_object_impl< detail::reactive_socket_service< Protocol >, Executor > impl_; [endsect] [section:io_control basic_datagram_socket::io_control] [indexterm2 boost_asio.indexterm.basic_datagram_socket.io_control..io_control..basic_datagram_socket] Perform an IO control command on the socket. template< typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``> void ``[link boost_asio.reference.basic_datagram_socket.io_control.overload1 io_control]``( IoControlCommand & command); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.io_control.overload1 more...]]`` template< typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``> void ``[link boost_asio.reference.basic_datagram_socket.io_control.overload2 io_control]``( IoControlCommand & command, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.io_control.overload2 more...]]`` [section:overload1 basic_datagram_socket::io_control (1 of 2 overloads)] ['Inherited from basic_socket.] Perform an IO control command on the socket. template< typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``> void io_control( IoControlCommand & command); This function is used to execute an IO control command on the socket. [heading Parameters] [variablelist [[command][The IO control command to be performed on the socket.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] Getting the number of bytes ready to read: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::socket::bytes_readable command; socket.io_control(command); std::size_t bytes_readable = command.get(); [endsect] [section:overload2 basic_datagram_socket::io_control (2 of 2 overloads)] ['Inherited from basic_socket.] Perform an IO control command on the socket. template< typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``> void io_control( IoControlCommand & command, boost::system::error_code & ec); This function is used to execute an IO control command on the socket. [heading Parameters] [variablelist [[command][The IO control command to be performed on the socket.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] Getting the number of bytes ready to read: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::socket::bytes_readable command; boost::system::error_code ec; socket.io_control(command, ec); if (ec) { // An error occurred. } std::size_t bytes_readable = command.get(); [endsect] [endsect] [section:is_open basic_datagram_socket::is_open] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.is_open..is_open..basic_datagram_socket] Determine whether the socket is open. bool is_open() const; [endsect] [section:keep_alive basic_datagram_socket::keep_alive] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.keep_alive..keep_alive..basic_datagram_socket] Socket option to send keep-alives. typedef implementation_defined keep_alive; Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::keep_alive option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::keep_alive option; socket.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:linger basic_datagram_socket::linger] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.linger..linger..basic_datagram_socket] Socket option to specify whether the socket lingers on close if unsent data is present. typedef implementation_defined linger; Implements the SOL\_SOCKET/SO\_LINGER socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::linger option(true, 30); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::linger option; socket.get_option(option); bool is_set = option.enabled(); unsigned short timeout = option.timeout(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:local_endpoint basic_datagram_socket::local_endpoint] [indexterm2 boost_asio.indexterm.basic_datagram_socket.local_endpoint..local_endpoint..basic_datagram_socket] Get the local endpoint of the socket. endpoint_type ``[link boost_asio.reference.basic_datagram_socket.local_endpoint.overload1 local_endpoint]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.local_endpoint.overload1 more...]]`` endpoint_type ``[link boost_asio.reference.basic_datagram_socket.local_endpoint.overload2 local_endpoint]``( boost::system::error_code & ec) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.local_endpoint.overload2 more...]]`` [section:overload1 basic_datagram_socket::local_endpoint (1 of 2 overloads)] ['Inherited from basic_socket.] Get the local endpoint of the socket. endpoint_type local_endpoint() const; This function is used to obtain the locally bound endpoint of the socket. [heading Return Value] An object that represents the local endpoint of the socket. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(); [endsect] [section:overload2 basic_datagram_socket::local_endpoint (2 of 2 overloads)] ['Inherited from basic_socket.] Get the local endpoint of the socket. endpoint_type local_endpoint( boost::system::error_code & ec) const; This function is used to obtain the locally bound endpoint of the socket. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] An object that represents the local endpoint of the socket. Returns a default-constructed endpoint object if an error occurred. [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::system::error_code ec; boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:lowest_layer basic_datagram_socket::lowest_layer] [indexterm2 boost_asio.indexterm.basic_datagram_socket.lowest_layer..lowest_layer..basic_datagram_socket] Get a reference to the lowest layer. lowest_layer_type & ``[link boost_asio.reference.basic_datagram_socket.lowest_layer.overload1 lowest_layer]``(); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.lowest_layer.overload1 more...]]`` Get a const reference to the lowest layer. const lowest_layer_type & ``[link boost_asio.reference.basic_datagram_socket.lowest_layer.overload2 lowest_layer]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.lowest_layer.overload2 more...]]`` [section:overload1 basic_datagram_socket::lowest_layer (1 of 2 overloads)] ['Inherited from basic_socket.] Get a reference to the lowest layer. lowest_layer_type & lowest_layer(); This function returns a reference to the lowest layer in a stack of layers. Since a [link boost_asio.reference.basic_socket `basic_socket`] cannot contain any further layers, it simply returns a reference to itself. [heading Return Value] A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller. [endsect] [section:overload2 basic_datagram_socket::lowest_layer (2 of 2 overloads)] ['Inherited from basic_socket.] Get a const reference to the lowest layer. const lowest_layer_type & lowest_layer() const; This function returns a const reference to the lowest layer in a stack of layers. Since a [link boost_asio.reference.basic_socket `basic_socket`] cannot contain any further layers, it simply returns a reference to itself. [heading Return Value] A const reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller. [endsect] [endsect] [section:lowest_layer_type basic_datagram_socket::lowest_layer_type] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.lowest_layer_type..lowest_layer_type..basic_datagram_socket] A [link boost_asio.reference.basic_socket `basic_socket`] is always the lowest layer. typedef basic_socket< Protocol, Executor > lowest_layer_type; [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.basic_socket__rebind_executor [*rebind_executor]]] [Rebinds the socket type to another executor. ] ] [ [[link boost_asio.reference.basic_socket.broadcast [*broadcast]]] [Socket option to permit sending of broadcast messages. ] ] [ [[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]] [IO control command to get the amount of data that can be read without blocking. ] ] [ [[link boost_asio.reference.basic_socket.debug [*debug]]] [Socket option to enable socket-level debugging. ] ] [ [[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]] [Socket option to prevent routing, use local interfaces only. ] ] [ [[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]] [Socket option to report aborted connections on accept. ] ] [ [[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]] [The endpoint type. ] ] [ [[link boost_asio.reference.basic_socket.executor_type [*executor_type]]] [The type of the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]] [Socket option to send keep-alives. ] ] [ [[link boost_asio.reference.basic_socket.linger [*linger]]] [Socket option to specify whether the socket lingers on close if unsent data is present. ] ] [ [[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]] [A basic_socket is always the lowest layer. ] ] [ [[link boost_asio.reference.basic_socket.message_flags [*message_flags]]] [Bitmask type for flags that can be passed to send and receive operations. ] ] [ [[link boost_asio.reference.basic_socket.native_handle_type [*native_handle_type]]] [The native representation of a socket. ] ] [ [[link boost_asio.reference.basic_socket.out_of_band_inline [*out_of_band_inline]]] [Socket option for putting received out-of-band data inline. ] ] [ [[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]] [The protocol type. ] ] [ [[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]] [Socket option for the receive buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]] [Socket option for the receive low watermark. ] ] [ [[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]] [Socket option to allow the socket to be bound to an address that is already in use. ] ] [ [[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]] [Socket option for the send buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]] [Socket option for the send low watermark. ] ] [ [[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]] [Different ways a socket may be shutdown. ] ] [ [[link boost_asio.reference.basic_socket.wait_type [*wait_type]]] [Wait types. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.basic_socket.assign [*assign]]] [Assign an existing native socket to the socket. ] ] [ [[link boost_asio.reference.basic_socket.async_connect [*async_connect]]] [Start an asynchronous connect. ] ] [ [[link boost_asio.reference.basic_socket.async_wait [*async_wait]]] [Asynchronously wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] [ [[link boost_asio.reference.basic_socket.at_mark [*at_mark]]] [Determine whether the socket is at the out-of-band data mark. ] ] [ [[link boost_asio.reference.basic_socket.available [*available]]] [Determine the number of bytes available for reading. ] ] [ [[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]] [Construct a basic_socket without opening it. [hr] Construct and open a basic_socket. [hr] Construct a basic_socket, opening it and binding it to the given local endpoint. [hr] Construct a basic_socket on an existing native socket. [hr] Move-construct a basic_socket from another. [hr] Move-construct a basic_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_socket.bind [*bind]]] [Bind the socket to the given local endpoint. ] ] [ [[link boost_asio.reference.basic_socket.cancel [*cancel]]] [Cancel all asynchronous operations associated with the socket. ] ] [ [[link boost_asio.reference.basic_socket.close [*close]]] [Close the socket. ] ] [ [[link boost_asio.reference.basic_socket.connect [*connect]]] [Connect the socket to the specified endpoint. ] ] [ [[link boost_asio.reference.basic_socket.get_executor [*get_executor]]] [Get the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_socket.get_option [*get_option]]] [Get an option from the socket. ] ] [ [[link boost_asio.reference.basic_socket.io_control [*io_control]]] [Perform an IO control command on the socket. ] ] [ [[link boost_asio.reference.basic_socket.is_open [*is_open]]] [Determine whether the socket is open. ] ] [ [[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]] [Get the local endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]] [Get a reference to the lowest layer. [hr] Get a const reference to the lowest layer. ] ] [ [[link boost_asio.reference.basic_socket.native_handle [*native_handle]]] [Get the native socket representation. ] ] [ [[link boost_asio.reference.basic_socket.native_non_blocking [*native_non_blocking]]] [Gets the non-blocking mode of the native socket implementation. [hr] Sets the non-blocking mode of the native socket implementation. ] ] [ [[link boost_asio.reference.basic_socket.non_blocking [*non_blocking]]] [Gets the non-blocking mode of the socket. [hr] Sets the non-blocking mode of the socket. ] ] [ [[link boost_asio.reference.basic_socket.open [*open]]] [Open the socket using the specified protocol. ] ] [ [[link boost_asio.reference.basic_socket.operator_eq_ [*operator=]]] [Move-assign a basic_socket from another. [hr] Move-assign a basic_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_socket.release [*release]]] [Release ownership of the underlying native socket. ] ] [ [[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]] [Get the remote endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_socket.set_option [*set_option]]] [Set an option on the socket. ] ] [ [[link boost_asio.reference.basic_socket.shutdown [*shutdown]]] [Disable sends or receives on the socket. ] ] [ [[link boost_asio.reference.basic_socket.wait [*wait]]] [Wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] ] [heading Protected Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.basic_socket._basic_socket [*~basic_socket]]] [Protected destructor to prevent deletion through this type. ] ] ] [heading Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_socket.max_connections [*max_connections]]] [(Deprecated: Use max_listen_connections.) The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_socket.max_listen_connections [*max_listen_connections]]] [The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]] [Specify that the data should not be subject to routing. ] ] [ [[link boost_asio.reference.basic_socket.message_end_of_record [*message_end_of_record]]] [Specifies that the data marks the end of a record. ] ] [ [[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]] [Process out-of-band data. ] ] [ [[link boost_asio.reference.basic_socket.message_peek [*message_peek]]] [Peek at incoming data without removing it from the input queue. ] ] ] [heading Protected Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_socket.impl_ [*impl_]]] [] ] ] The [link boost_asio.reference.basic_socket `basic_socket`] class template provides functionality that is common to both stream-oriented and datagram-oriented sockets. [heading Thread Safety] ['Distinct] ['objects:] Safe. ['Shared] ['objects:] Unsafe. [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:max_connections basic_datagram_socket::max_connections] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.max_connections..max_connections..basic_datagram_socket] (Deprecated: Use max\_listen\_connections.) The maximum length of the queue of pending incoming connections. static const int max_connections = implementation_defined; [endsect] [section:max_listen_connections basic_datagram_socket::max_listen_connections] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.max_listen_connections..max_listen_connections..basic_datagram_socket] The maximum length of the queue of pending incoming connections. static const int max_listen_connections = implementation_defined; [endsect] [section:message_do_not_route basic_datagram_socket::message_do_not_route] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.message_do_not_route..message_do_not_route..basic_datagram_socket] Specify that the data should not be subject to routing. static const int message_do_not_route = implementation_defined; [endsect] [section:message_end_of_record basic_datagram_socket::message_end_of_record] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.message_end_of_record..message_end_of_record..basic_datagram_socket] Specifies that the data marks the end of a record. static const int message_end_of_record = implementation_defined; [endsect] [section:message_flags basic_datagram_socket::message_flags] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.message_flags..message_flags..basic_datagram_socket] Bitmask type for flags that can be passed to send and receive operations. typedef int message_flags; [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:message_out_of_band basic_datagram_socket::message_out_of_band] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.message_out_of_band..message_out_of_band..basic_datagram_socket] Process out-of-band data. static const int message_out_of_band = implementation_defined; [endsect] [section:message_peek basic_datagram_socket::message_peek] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.message_peek..message_peek..basic_datagram_socket] Peek at incoming data without removing it from the input queue. static const int message_peek = implementation_defined; [endsect] [section:native_handle basic_datagram_socket::native_handle] ['Inherited from basic_socket.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.native_handle..native_handle..basic_datagram_socket] Get the native socket representation. native_handle_type native_handle(); This function may be used to obtain the underlying representation of the socket. This is intended to allow access to native socket functionality that is not otherwise provided. [endsect] [section:native_handle_type basic_datagram_socket::native_handle_type] [indexterm2 boost_asio.indexterm.basic_datagram_socket.native_handle_type..native_handle_type..basic_datagram_socket] The native representation of a socket. typedef implementation_defined native_handle_type; [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:native_non_blocking basic_datagram_socket::native_non_blocking] [indexterm2 boost_asio.indexterm.basic_datagram_socket.native_non_blocking..native_non_blocking..basic_datagram_socket] Gets the non-blocking mode of the native socket implementation. bool ``[link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload1 native_non_blocking]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload1 more...]]`` Sets the non-blocking mode of the native socket implementation. void ``[link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload2 native_non_blocking]``( bool mode); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload2 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload3 native_non_blocking]``( bool mode, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.native_non_blocking.overload3 more...]]`` [section:overload1 basic_datagram_socket::native_non_blocking (1 of 3 overloads)] ['Inherited from basic_socket.] Gets the non-blocking mode of the native socket implementation. bool native_non_blocking() const; This function is used to retrieve the non-blocking mode of the underlying native socket. This mode has no effect on the behaviour of the socket object's synchronous operations. [heading Return Value] `true` if the underlying socket is in non-blocking mode and direct system calls may fail with `boost::asio::error::would_block` (or the equivalent system error). [heading Remarks] The current non-blocking mode is cached by the socket object. Consequently, the return value may be incorrect if the non-blocking mode was set directly on the native socket. [heading Example] This function is intended to allow the encapsulation of arbitrary non-blocking system calls as asynchronous operations, in a way that is transparent to the user of the socket object. The following example illustrates how Linux's `sendfile` system call might be encapsulated: template struct sendfile_op { tcp::socket& sock_; int fd_; Handler handler_; off_t offset_; std::size_t total_bytes_transferred_; // Function call operator meeting WriteHandler requirements. // Used as the handler for the async_write_some operation. void operator()(boost::system::error_code ec, std::size_t) { // Put the underlying socket into non-blocking mode. if (!ec) if (!sock_.native_non_blocking()) sock_.native_non_blocking(true, ec); if (!ec) { for (;;) { // Try the system call. errno = 0; int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); ec = boost::system::error_code(n < 0 ? errno : 0, boost::asio::error::get_system_category()); total_bytes_transferred_ += ec ? 0 : n; // Retry operation immediately if interrupted by signal. if (ec == boost::asio::error::interrupted) continue; // Check if we need to run the operation again. if (ec == boost::asio::error::would_block || ec == boost::asio::error::try_again) { // We have to wait for the socket to become ready again. sock_.async_wait(tcp::socket::wait_write, *this); return; } if (ec || n == 0) { // An error occurred, or we have reached the end of the file. // Either way we must exit the loop so we can call the handler. break; } // Loop around to try calling sendfile again. } } // Pass result back to user's handler. handler_(ec, total_bytes_transferred_); } }; template void async_sendfile(tcp::socket& sock, int fd, Handler h) { sendfile_op op = { sock, fd, h, 0, 0 }; sock.async_wait(tcp::socket::wait_write, op); } [endsect] [section:overload2 basic_datagram_socket::native_non_blocking (2 of 3 overloads)] ['Inherited from basic_socket.] Sets the non-blocking mode of the native socket implementation. void native_non_blocking( bool mode); This function is used to modify the non-blocking mode of the underlying native socket. It has no effect on the behaviour of the socket object's synchronous operations. [heading Parameters] [variablelist [[mode][If `true`, the underlying socket is put into non-blocking mode and direct system calls may fail with `boost::asio::error::would_block` (or the equivalent system error).]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. If the `mode` is `false`, but the current value of `non_blocking()` is `true`, this function fails with `boost::asio::error::invalid_argument`, as the combination does not make sense.]] ] [heading Example] This function is intended to allow the encapsulation of arbitrary non-blocking system calls as asynchronous operations, in a way that is transparent to the user of the socket object. The following example illustrates how Linux's `sendfile` system call might be encapsulated: template struct sendfile_op { tcp::socket& sock_; int fd_; Handler handler_; off_t offset_; std::size_t total_bytes_transferred_; // Function call operator meeting WriteHandler requirements. // Used as the handler for the async_write_some operation. void operator()(boost::system::error_code ec, std::size_t) { // Put the underlying socket into non-blocking mode. if (!ec) if (!sock_.native_non_blocking()) sock_.native_non_blocking(true, ec); if (!ec) { for (;;) { // Try the system call. errno = 0; int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); ec = boost::system::error_code(n < 0 ? errno : 0, boost::asio::error::get_system_category()); total_bytes_transferred_ += ec ? 0 : n; // Retry operation immediately if interrupted by signal. if (ec == boost::asio::error::interrupted) continue; // Check if we need to run the operation again. if (ec == boost::asio::error::would_block || ec == boost::asio::error::try_again) { // We have to wait for the socket to become ready again. sock_.async_wait(tcp::socket::wait_write, *this); return; } if (ec || n == 0) { // An error occurred, or we have reached the end of the file. // Either way we must exit the loop so we can call the handler. break; } // Loop around to try calling sendfile again. } } // Pass result back to user's handler. handler_(ec, total_bytes_transferred_); } }; template void async_sendfile(tcp::socket& sock, int fd, Handler h) { sendfile_op op = { sock, fd, h, 0, 0 }; sock.async_wait(tcp::socket::wait_write, op); } [endsect] [section:overload3 basic_datagram_socket::native_non_blocking (3 of 3 overloads)] ['Inherited from basic_socket.] Sets the non-blocking mode of the native socket implementation. void native_non_blocking( bool mode, boost::system::error_code & ec); This function is used to modify the non-blocking mode of the underlying native socket. It has no effect on the behaviour of the socket object's synchronous operations. [heading Parameters] [variablelist [[mode][If `true`, the underlying socket is put into non-blocking mode and direct system calls may fail with `boost::asio::error::would_block` (or the equivalent system error).]] [[ec][Set to indicate what error occurred, if any. If the `mode` is `false`, but the current value of `non_blocking()` is `true`, this function fails with `boost::asio::error::invalid_argument`, as the combination does not make sense.]] ] [heading Example] This function is intended to allow the encapsulation of arbitrary non-blocking system calls as asynchronous operations, in a way that is transparent to the user of the socket object. The following example illustrates how Linux's `sendfile` system call might be encapsulated: template struct sendfile_op { tcp::socket& sock_; int fd_; Handler handler_; off_t offset_; std::size_t total_bytes_transferred_; // Function call operator meeting WriteHandler requirements. // Used as the handler for the async_write_some operation. void operator()(boost::system::error_code ec, std::size_t) { // Put the underlying socket into non-blocking mode. if (!ec) if (!sock_.native_non_blocking()) sock_.native_non_blocking(true, ec); if (!ec) { for (;;) { // Try the system call. errno = 0; int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); ec = boost::system::error_code(n < 0 ? errno : 0, boost::asio::error::get_system_category()); total_bytes_transferred_ += ec ? 0 : n; // Retry operation immediately if interrupted by signal. if (ec == boost::asio::error::interrupted) continue; // Check if we need to run the operation again. if (ec == boost::asio::error::would_block || ec == boost::asio::error::try_again) { // We have to wait for the socket to become ready again. sock_.async_wait(tcp::socket::wait_write, *this); return; } if (ec || n == 0) { // An error occurred, or we have reached the end of the file. // Either way we must exit the loop so we can call the handler. break; } // Loop around to try calling sendfile again. } } // Pass result back to user's handler. handler_(ec, total_bytes_transferred_); } }; template void async_sendfile(tcp::socket& sock, int fd, Handler h) { sendfile_op op = { sock, fd, h, 0, 0 }; sock.async_wait(tcp::socket::wait_write, op); } [endsect] [endsect] [section:non_blocking basic_datagram_socket::non_blocking] [indexterm2 boost_asio.indexterm.basic_datagram_socket.non_blocking..non_blocking..basic_datagram_socket] Gets the non-blocking mode of the socket. bool ``[link boost_asio.reference.basic_datagram_socket.non_blocking.overload1 non_blocking]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.non_blocking.overload1 more...]]`` Sets the non-blocking mode of the socket. void ``[link boost_asio.reference.basic_datagram_socket.non_blocking.overload2 non_blocking]``( bool mode); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.non_blocking.overload2 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.non_blocking.overload3 non_blocking]``( bool mode, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.non_blocking.overload3 more...]]`` [section:overload1 basic_datagram_socket::non_blocking (1 of 3 overloads)] ['Inherited from basic_socket.] Gets the non-blocking mode of the socket. bool non_blocking() const; [heading Return Value] `true` if the socket's synchronous operations will fail with `boost::asio::error::would_block` if they are unable to perform the requested operation immediately. If `false`, synchronous operations will block until complete. [heading Remarks] The non-blocking mode has no effect on the behaviour of asynchronous operations. Asynchronous operations will never fail with the error `boost::asio::error::would_block`. [endsect] [section:overload2 basic_datagram_socket::non_blocking (2 of 3 overloads)] ['Inherited from basic_socket.] Sets the non-blocking mode of the socket. void non_blocking( bool mode); [heading Parameters] [variablelist [[mode][If `true`, the socket's synchronous operations will fail with `boost::asio::error::would_block` if they are unable to perform the requested operation immediately. If `false`, synchronous operations will block until complete.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] The non-blocking mode has no effect on the behaviour of asynchronous operations. Asynchronous operations will never fail with the error `boost::asio::error::would_block`. [endsect] [section:overload3 basic_datagram_socket::non_blocking (3 of 3 overloads)] ['Inherited from basic_socket.] Sets the non-blocking mode of the socket. void non_blocking( bool mode, boost::system::error_code & ec); [heading Parameters] [variablelist [[mode][If `true`, the socket's synchronous operations will fail with `boost::asio::error::would_block` if they are unable to perform the requested operation immediately. If `false`, synchronous operations will block until complete.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Remarks] The non-blocking mode has no effect on the behaviour of asynchronous operations. Asynchronous operations will never fail with the error `boost::asio::error::would_block`. [endsect] [endsect] [section:open basic_datagram_socket::open] [indexterm2 boost_asio.indexterm.basic_datagram_socket.open..open..basic_datagram_socket] Open the socket using the specified protocol. void ``[link boost_asio.reference.basic_datagram_socket.open.overload1 open]``( const protocol_type & protocol = protocol_type()); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.open.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.open.overload2 open]``( const protocol_type & protocol, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.open.overload2 more...]]`` [section:overload1 basic_datagram_socket::open (1 of 2 overloads)] ['Inherited from basic_socket.] Open the socket using the specified protocol. void open( const protocol_type & protocol = protocol_type()); This function opens the socket so that it will use the specified protocol. [heading Parameters] [variablelist [[protocol][An object specifying protocol parameters to be used.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); socket.open(boost::asio::ip::tcp::v4()); [endsect] [section:overload2 basic_datagram_socket::open (2 of 2 overloads)] ['Inherited from basic_socket.] Open the socket using the specified protocol. void open( const protocol_type & protocol, boost::system::error_code & ec); This function opens the socket so that it will use the specified protocol. [heading Parameters] [variablelist [[protocol][An object specifying which protocol is to be used.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); boost::system::error_code ec; socket.open(boost::asio::ip::tcp::v4(), ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:operator_eq_ basic_datagram_socket::operator=] [indexterm2 boost_asio.indexterm.basic_datagram_socket.operator_eq_..operator=..basic_datagram_socket] Move-assign a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from another. basic_datagram_socket & ``[link boost_asio.reference.basic_datagram_socket.operator_eq_.overload1 operator=]``( basic_datagram_socket && other); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.operator_eq_.overload1 more...]]`` Move-assign a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from a socket of another protocol type. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``> enable_if< is_convertible< Protocol1, Protocol >::value &&is_convertible< Executor1, Executor >::value, basic_datagram_socket & >::type ``[link boost_asio.reference.basic_datagram_socket.operator_eq_.overload2 operator=]``( basic_datagram_socket< Protocol1, Executor1 > && other); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.operator_eq_.overload2 more...]]`` [section:overload1 basic_datagram_socket::operator= (1 of 2 overloads)] Move-assign a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from another. basic_datagram_socket & operator=( basic_datagram_socket && other); This assignment operator moves a datagram socket from one object to another. [heading Parameters] [variablelist [[other][The other [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] object from which the move will occur.]] ] [heading Remarks] Following the move, the moved-from object is in the same state as if constructed using the `basic_datagram_socket(const executor_type&)` constructor. [endsect] [section:overload2 basic_datagram_socket::operator= (2 of 2 overloads)] Move-assign a [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] from a socket of another protocol type. template< typename ``[link boost_asio.reference.Protocol Protocol1]``, typename ``[link boost_asio.reference.Executor1 Executor1]``> enable_if< is_convertible< Protocol1, Protocol >::value &&is_convertible< Executor1, Executor >::value, basic_datagram_socket & >::type operator=( basic_datagram_socket< Protocol1, Executor1 > && other); This assignment operator moves a datagram socket from one object to another. [heading Parameters] [variablelist [[other][The other [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] object from which the move will occur.]] ] [heading Remarks] Following the move, the moved-from object is in the same state as if constructed using the `basic_datagram_socket(const executor_type&)` constructor. [endsect] [endsect] [section:out_of_band_inline basic_datagram_socket::out_of_band_inline] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.out_of_band_inline..out_of_band_inline..basic_datagram_socket] Socket option for putting received out-of-band data inline. typedef implementation_defined out_of_band_inline; Implements the SOL\_SOCKET/SO\_OOBINLINE socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::out_of_band_inline option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::out_of_band_inline option; socket.get_option(option); bool value = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:protocol_type basic_datagram_socket::protocol_type] [indexterm2 boost_asio.indexterm.basic_datagram_socket.protocol_type..protocol_type..basic_datagram_socket] The protocol type. typedef Protocol protocol_type; [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:receive basic_datagram_socket::receive] [indexterm2 boost_asio.indexterm.basic_datagram_socket.receive..receive..basic_datagram_socket] Receive some data on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload1 receive]``( const MutableBufferSequence & buffers); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload2 receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive.overload2 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload3 receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive.overload3 more...]]`` [section:overload1 basic_datagram_socket::receive (1 of 3 overloads)] Receive some data on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive( const MutableBufferSequence & buffers); This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] ] [heading Return Value] The number of bytes received. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket. [heading Example] To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.receive(boost::asio::buffer(data, size)); See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::receive (2 of 3 overloads)] Receive some data on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive( const MutableBufferSequence & buffers, socket_base::message_flags flags); This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] [[flags][Flags specifying how the receive call is to be made.]] ] [heading Return Value] The number of bytes received. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket. [endsect] [section:overload3 basic_datagram_socket::receive (3 of 3 overloads)] Receive some data on a connected socket. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, boost::system::error_code & ec); This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] [[flags][Flags specifying how the receive call is to be made.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] The number of bytes received. [heading Remarks] The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket. [endsect] [endsect] [section:receive_buffer_size basic_datagram_socket::receive_buffer_size] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.receive_buffer_size..receive_buffer_size..basic_datagram_socket] Socket option for the receive buffer size of a socket. typedef implementation_defined receive_buffer_size; Implements the SOL\_SOCKET/SO\_RCVBUF socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::receive_buffer_size option(8192); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::receive_buffer_size option; socket.get_option(option); int size = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:receive_from basic_datagram_socket::receive_from] [indexterm2 boost_asio.indexterm.basic_datagram_socket.receive_from..receive_from..basic_datagram_socket] Receive a datagram with the endpoint of the sender. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload1 receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive_from.overload1 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload2 receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive_from.overload2 more...]]`` template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload3 receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.receive_from.overload3 more...]]`` [section:overload1 basic_datagram_socket::receive_from (1 of 3 overloads)] Receive a datagram with the endpoint of the sender. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint); This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] [[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]] ] [heading Return Value] The number of bytes received. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] To receive into a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint sender_endpoint; socket.receive_from( boost::asio::buffer(data, size), sender_endpoint); See the [link boost_asio.reference.buffer `buffer`] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::receive_from (2 of 3 overloads)] Receive a datagram with the endpoint of the sender. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags); This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] [[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]] [[flags][Flags specifying how the receive call is to be made.]] ] [heading Return Value] The number of bytes received. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload3 basic_datagram_socket::receive_from (3 of 3 overloads)] Receive a datagram with the endpoint of the sender. template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``> std::size_t receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, boost::system::error_code & ec); This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more buffers into which the data will be received.]] [[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]] [[flags][Flags specifying how the receive call is to be made.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] The number of bytes received. [endsect] [endsect] [section:receive_low_watermark basic_datagram_socket::receive_low_watermark] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.receive_low_watermark..receive_low_watermark..basic_datagram_socket] Socket option for the receive low watermark. typedef implementation_defined receive_low_watermark; Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::receive_low_watermark option(1024); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::receive_low_watermark option; socket.get_option(option); int size = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:release basic_datagram_socket::release] [indexterm2 boost_asio.indexterm.basic_datagram_socket.release..release..basic_datagram_socket] Release ownership of the underlying native socket. native_handle_type ``[link boost_asio.reference.basic_datagram_socket.release.overload1 release]``(); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.release.overload1 more...]]`` native_handle_type ``[link boost_asio.reference.basic_datagram_socket.release.overload2 release]``( boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.release.overload2 more...]]`` [section:overload1 basic_datagram_socket::release (1 of 2 overloads)] ['Inherited from basic_socket.] Release ownership of the underlying native socket. native_handle_type release(); This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the `boost::asio::error::operation_aborted` error. Ownership of the native socket is then transferred to the caller. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] This function is unsupported on Windows versions prior to Windows 8.1, and will fail with `boost::asio::error::operation_not_supported` on these platforms. [endsect] [section:overload2 basic_datagram_socket::release (2 of 2 overloads)] ['Inherited from basic_socket.] Release ownership of the underlying native socket. native_handle_type release( boost::system::error_code & ec); This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the `boost::asio::error::operation_aborted` error. Ownership of the native socket is then transferred to the caller. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Remarks] This function is unsupported on Windows versions prior to Windows 8.1, and will fail with `boost::asio::error::operation_not_supported` on these platforms. [endsect] [endsect] [section:remote_endpoint basic_datagram_socket::remote_endpoint] [indexterm2 boost_asio.indexterm.basic_datagram_socket.remote_endpoint..remote_endpoint..basic_datagram_socket] Get the remote endpoint of the socket. endpoint_type ``[link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload1 remote_endpoint]``() const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload1 more...]]`` endpoint_type ``[link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload2 remote_endpoint]``( boost::system::error_code & ec) const; `` [''''»''' [link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload2 more...]]`` [section:overload1 basic_datagram_socket::remote_endpoint (1 of 2 overloads)] ['Inherited from basic_socket.] Get the remote endpoint of the socket. endpoint_type remote_endpoint() const; This function is used to obtain the remote endpoint of the socket. [heading Return Value] An object that represents the remote endpoint of the socket. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(); [endsect] [section:overload2 basic_datagram_socket::remote_endpoint (2 of 2 overloads)] ['Inherited from basic_socket.] Get the remote endpoint of the socket. endpoint_type remote_endpoint( boost::system::error_code & ec) const; This function is used to obtain the remote endpoint of the socket. [heading Parameters] [variablelist [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] An object that represents the remote endpoint of the socket. Returns a default-constructed endpoint object if an error occurred. [heading Example] boost::asio::ip::tcp::socket socket(my_context); ... boost::system::error_code ec; boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:reuse_address basic_datagram_socket::reuse_address] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.reuse_address..reuse_address..basic_datagram_socket] Socket option to allow the socket to be bound to an address that is already in use. typedef implementation_defined reuse_address; Implements the SOL\_SOCKET/SO\_REUSEADDR socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::acceptor acceptor(my_context); ... boost::asio::socket_base::reuse_address option(true); acceptor.set_option(option); Getting the current option value: boost::asio::ip::tcp::acceptor acceptor(my_context); ... boost::asio::socket_base::reuse_address option; acceptor.get_option(option); bool is_set = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:send basic_datagram_socket::send] [indexterm2 boost_asio.indexterm.basic_datagram_socket.send..send..basic_datagram_socket] Send some data on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload1 send]``( const ConstBufferSequence & buffers); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload2 send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send.overload2 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload3 send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send.overload3 more...]]`` [section:overload1 basic_datagram_socket::send (1 of 3 overloads)] Send some data on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send( const ConstBufferSequence & buffers); This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One ore more data buffers to be sent on the socket.]] ] [heading Return Value] The number of bytes sent. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket. [heading Example] To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: socket.send(boost::asio::buffer(data, size)); See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::send (2 of 3 overloads)] Send some data on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send( const ConstBufferSequence & buffers, socket_base::message_flags flags); This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One ore more data buffers to be sent on the socket.]] [[flags][Flags specifying how the send call is to be made.]] ] [heading Return Value] The number of bytes sent. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Remarks] The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket. [endsect] [section:overload3 basic_datagram_socket::send (3 of 3 overloads)] Send some data on a connected socket. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send( const ConstBufferSequence & buffers, socket_base::message_flags flags, boost::system::error_code & ec); This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent on the socket.]] [[flags][Flags specifying how the send call is to be made.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] The number of bytes sent. [heading Remarks] The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket. [endsect] [endsect] [section:send_buffer_size basic_datagram_socket::send_buffer_size] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.send_buffer_size..send_buffer_size..basic_datagram_socket] Socket option for the send buffer size of a socket. typedef implementation_defined send_buffer_size; Implements the SOL\_SOCKET/SO\_SNDBUF socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::send_buffer_size option(8192); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::send_buffer_size option; socket.get_option(option); int size = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:send_low_watermark basic_datagram_socket::send_low_watermark] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.send_low_watermark..send_low_watermark..basic_datagram_socket] Socket option for the send low watermark. typedef implementation_defined send_low_watermark; Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option. [heading Examples] Setting the option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::send_low_watermark option(1024); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::socket_base::send_low_watermark option; socket.get_option(option); int size = option.value(); [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [section:send_to basic_datagram_socket::send_to] [indexterm2 boost_asio.indexterm.basic_datagram_socket.send_to..send_to..basic_datagram_socket] Send a datagram to the specified endpoint. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload1 send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send_to.overload1 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload2 send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send_to.overload2 more...]]`` template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload3 send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.send_to.overload3 more...]]`` [section:overload1 basic_datagram_socket::send_to (1 of 3 overloads)] Send a datagram to the specified endpoint. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send_to( const ConstBufferSequence & buffers, const endpoint_type & destination); This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent to the remote endpoint.]] [[destination][The remote endpoint to which the data will be sent.]] ] [heading Return Value] The number of bytes sent. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] To send a single data buffer use the [link boost_asio.reference.buffer `buffer`] function as follows: boost::asio::ip::udp::endpoint destination( boost::asio::ip::address::from_string("1.2.3.4"), 12345); socket.send_to(boost::asio::buffer(data, size), destination); See the [link boost_asio.reference.buffer `buffer`] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector. [endsect] [section:overload2 basic_datagram_socket::send_to (2 of 3 overloads)] Send a datagram to the specified endpoint. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags); This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent to the remote endpoint.]] [[destination][The remote endpoint to which the data will be sent.]] [[flags][Flags specifying how the send call is to be made.]] ] [heading Return Value] The number of bytes sent. [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure. ]] ] [endsect] [section:overload3 basic_datagram_socket::send_to (3 of 3 overloads)] Send a datagram to the specified endpoint. template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``> std::size_t send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, boost::system::error_code & ec); This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs. [heading Parameters] [variablelist [[buffers][One or more data buffers to be sent to the remote endpoint.]] [[destination][The remote endpoint to which the data will be sent.]] [[flags][Flags specifying how the send call is to be made.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Return Value] The number of bytes sent. [endsect] [endsect] [section:set_option basic_datagram_socket::set_option] [indexterm2 boost_asio.indexterm.basic_datagram_socket.set_option..set_option..basic_datagram_socket] Set an option on the socket. template< typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``> void ``[link boost_asio.reference.basic_datagram_socket.set_option.overload1 set_option]``( const SettableSocketOption & option); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.set_option.overload1 more...]]`` template< typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``> void ``[link boost_asio.reference.basic_datagram_socket.set_option.overload2 set_option]``( const SettableSocketOption & option, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.set_option.overload2 more...]]`` [section:overload1 basic_datagram_socket::set_option (1 of 2 overloads)] ['Inherited from basic_socket.] Set an option on the socket. template< typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``> void set_option( const SettableSocketOption & option); This function is used to set an option on the socket. [heading Parameters] [variablelist [[option][The new option value to be set on the socket.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] Setting the IPPROTO\_TCP/TCP\_NODELAY option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::no_delay option(true); socket.set_option(option); [endsect] [section:overload2 basic_datagram_socket::set_option (2 of 2 overloads)] ['Inherited from basic_socket.] Set an option on the socket. template< typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``> void set_option( const SettableSocketOption & option, boost::system::error_code & ec); This function is used to set an option on the socket. [heading Parameters] [variablelist [[option][The new option value to be set on the socket.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] Setting the IPPROTO\_TCP/TCP\_NODELAY option: boost::asio::ip::tcp::socket socket(my_context); ... boost::asio::ip::tcp::no_delay option(true); boost::system::error_code ec; socket.set_option(option, ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:shutdown basic_datagram_socket::shutdown] [indexterm2 boost_asio.indexterm.basic_datagram_socket.shutdown..shutdown..basic_datagram_socket] Disable sends or receives on the socket. void ``[link boost_asio.reference.basic_datagram_socket.shutdown.overload1 shutdown]``( shutdown_type what); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.shutdown.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.shutdown.overload2 shutdown]``( shutdown_type what, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.shutdown.overload2 more...]]`` [section:overload1 basic_datagram_socket::shutdown (1 of 2 overloads)] ['Inherited from basic_socket.] Disable sends or receives on the socket. void shutdown( shutdown_type what); This function is used to disable send operations, receive operations, or both. [heading Parameters] [variablelist [[what][Determines what types of operation will no longer be allowed.]] ] [heading Exceptions] [variablelist [[boost::system::system_error][Thrown on failure.]] ] [heading Example] Shutting down the send side of the socket: boost::asio::ip::tcp::socket socket(my_context); ... socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send); [endsect] [section:overload2 basic_datagram_socket::shutdown (2 of 2 overloads)] ['Inherited from basic_socket.] Disable sends or receives on the socket. void shutdown( shutdown_type what, boost::system::error_code & ec); This function is used to disable send operations, receive operations, or both. [heading Parameters] [variablelist [[what][Determines what types of operation will no longer be allowed.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] Shutting down the send side of the socket: boost::asio::ip::tcp::socket socket(my_context); ... boost::system::error_code ec; socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:shutdown_type basic_datagram_socket::shutdown_type] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.shutdown_type..shutdown_type..basic_datagram_socket] Different ways a socket may be shutdown. enum shutdown_type [indexterm2 boost_asio.indexterm.basic_datagram_socket.shutdown_type.shutdown_receive..shutdown_receive..basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket.shutdown_type.shutdown_send..shutdown_send..basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket.shutdown_type.shutdown_both..shutdown_both..basic_datagram_socket] [heading Values] [variablelist [ [shutdown_receive] [Shutdown the receive side of the socket. ] ] [ [shutdown_send] [Shutdown the send side of the socket. ] ] [ [shutdown_both] [Shutdown both send and receive on the socket. ] ] ] [endsect] [section:wait basic_datagram_socket::wait] [indexterm2 boost_asio.indexterm.basic_datagram_socket.wait..wait..basic_datagram_socket] Wait for the socket to become ready to read, ready to write, or to have pending error conditions. void ``[link boost_asio.reference.basic_datagram_socket.wait.overload1 wait]``( wait_type w); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.wait.overload1 more...]]`` void ``[link boost_asio.reference.basic_datagram_socket.wait.overload2 wait]``( wait_type w, boost::system::error_code & ec); `` [''''»''' [link boost_asio.reference.basic_datagram_socket.wait.overload2 more...]]`` [section:overload1 basic_datagram_socket::wait (1 of 2 overloads)] ['Inherited from basic_socket.] Wait for the socket to become ready to read, ready to write, or to have pending error conditions. void wait( wait_type w); This function is used to perform a blocking wait for a socket to enter a ready to read, write or error condition state. [heading Parameters] [variablelist [[w][Specifies the desired socket state.]] ] [heading Example] Waiting for a socket to become readable. boost::asio::ip::tcp::socket socket(my_context); ... socket.wait(boost::asio::ip::tcp::socket::wait_read); [endsect] [section:overload2 basic_datagram_socket::wait (2 of 2 overloads)] ['Inherited from basic_socket.] Wait for the socket to become ready to read, ready to write, or to have pending error conditions. void wait( wait_type w, boost::system::error_code & ec); This function is used to perform a blocking wait for a socket to enter a ready to read, write or error condition state. [heading Parameters] [variablelist [[w][Specifies the desired socket state.]] [[ec][Set to indicate what error occurred, if any.]] ] [heading Example] Waiting for a socket to become readable. boost::asio::ip::tcp::socket socket(my_context); ... boost::system::error_code ec; socket.wait(boost::asio::ip::tcp::socket::wait_read, ec); [endsect] [endsect] [section:wait_type basic_datagram_socket::wait_type] ['Inherited from socket_base.] [indexterm2 boost_asio.indexterm.basic_datagram_socket.wait_type..wait_type..basic_datagram_socket] Wait types. enum wait_type [indexterm2 boost_asio.indexterm.basic_datagram_socket.wait_type.wait_read..wait_read..basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket.wait_type.wait_write..wait_write..basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket.wait_type.wait_error..wait_error..basic_datagram_socket] [heading Values] [variablelist [ [wait_read] [Wait for a socket to become ready to read. ] ] [ [wait_write] [Wait for a socket to become ready to write. ] ] [ [wait_error] [Wait for a socket to have error conditions pending. ] ] ] For use with `basic_socket::wait()` and `basic_socket::async_wait()`. [endsect] [section:_basic_datagram_socket basic_datagram_socket::~basic_datagram_socket] [indexterm2 boost_asio.indexterm.basic_datagram_socket._basic_datagram_socket..~basic_datagram_socket..basic_datagram_socket] Destroys the socket. ~basic_datagram_socket(); This function destroys the socket, cancelling any outstanding asynchronous operations associated with the socket as if by calling `cancel`. [endsect] [endsect] [section:basic_datagram_socket__rebind_executor basic_datagram_socket::rebind_executor] Rebinds the socket type to another executor. template< typename ``[link boost_asio.reference.Executor1 Executor1]``> struct rebind_executor [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket__rebind_executor.other [*other]]] [The socket type when rebound to the specified executor. ] ] ] [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [section:other basic_datagram_socket::rebind_executor::other] [indexterm2 boost_asio.indexterm.basic_datagram_socket__rebind_executor.other..other..basic_datagram_socket::rebind_executor] The socket type when rebound to the specified executor. typedef basic_datagram_socket< Protocol, Executor1 > other; [heading Types] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket__rebind_executor [*rebind_executor]]] [Rebinds the socket type to another executor. ] ] [ [[link boost_asio.reference.basic_datagram_socket.broadcast [*broadcast]]] [Socket option to permit sending of broadcast messages. ] ] [ [[link boost_asio.reference.basic_datagram_socket.bytes_readable [*bytes_readable]]] [IO control command to get the amount of data that can be read without blocking. ] ] [ [[link boost_asio.reference.basic_datagram_socket.debug [*debug]]] [Socket option to enable socket-level debugging. ] ] [ [[link boost_asio.reference.basic_datagram_socket.do_not_route [*do_not_route]]] [Socket option to prevent routing, use local interfaces only. ] ] [ [[link boost_asio.reference.basic_datagram_socket.enable_connection_aborted [*enable_connection_aborted]]] [Socket option to report aborted connections on accept. ] ] [ [[link boost_asio.reference.basic_datagram_socket.endpoint_type [*endpoint_type]]] [The endpoint type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.executor_type [*executor_type]]] [The type of the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_datagram_socket.keep_alive [*keep_alive]]] [Socket option to send keep-alives. ] ] [ [[link boost_asio.reference.basic_datagram_socket.linger [*linger]]] [Socket option to specify whether the socket lingers on close if unsent data is present. ] ] [ [[link boost_asio.reference.basic_datagram_socket.lowest_layer_type [*lowest_layer_type]]] [A basic_socket is always the lowest layer. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_flags [*message_flags]]] [Bitmask type for flags that can be passed to send and receive operations. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_handle_type [*native_handle_type]]] [The native representation of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.out_of_band_inline [*out_of_band_inline]]] [Socket option for putting received out-of-band data inline. ] ] [ [[link boost_asio.reference.basic_datagram_socket.protocol_type [*protocol_type]]] [The protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_buffer_size [*receive_buffer_size]]] [Socket option for the receive buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_low_watermark [*receive_low_watermark]]] [Socket option for the receive low watermark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.reuse_address [*reuse_address]]] [Socket option to allow the socket to be bound to an address that is already in use. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_buffer_size [*send_buffer_size]]] [Socket option for the send buffer size of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_low_watermark [*send_low_watermark]]] [Socket option for the send low watermark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.shutdown_type [*shutdown_type]]] [Different ways a socket may be shutdown. ] ] [ [[link boost_asio.reference.basic_datagram_socket.wait_type [*wait_type]]] [Wait types. ] ] ] [heading Member Functions] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.assign [*assign]]] [Assign an existing native socket to the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_connect [*async_connect]]] [Start an asynchronous connect. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_receive [*async_receive]]] [Start an asynchronous receive on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_receive_from [*async_receive_from]]] [Start an asynchronous receive. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_send [*async_send]]] [Start an asynchronous send on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_send_to [*async_send_to]]] [Start an asynchronous send. ] ] [ [[link boost_asio.reference.basic_datagram_socket.async_wait [*async_wait]]] [Asynchronously wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] [ [[link boost_asio.reference.basic_datagram_socket.at_mark [*at_mark]]] [Determine whether the socket is at the out-of-band data mark. ] ] [ [[link boost_asio.reference.basic_datagram_socket.available [*available]]] [Determine the number of bytes available for reading. ] ] [ [[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket [*basic_datagram_socket]]] [Construct a basic_datagram_socket without opening it. [hr] Construct and open a basic_datagram_socket. [hr] Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. [hr] Construct a basic_datagram_socket on an existing native socket. [hr] Move-construct a basic_datagram_socket from another. [hr] Move-construct a basic_datagram_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.bind [*bind]]] [Bind the socket to the given local endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.cancel [*cancel]]] [Cancel all asynchronous operations associated with the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.close [*close]]] [Close the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.connect [*connect]]] [Connect the socket to the specified endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.get_executor [*get_executor]]] [Get the executor associated with the object. ] ] [ [[link boost_asio.reference.basic_datagram_socket.get_option [*get_option]]] [Get an option from the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.io_control [*io_control]]] [Perform an IO control command on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.is_open [*is_open]]] [Determine whether the socket is open. ] ] [ [[link boost_asio.reference.basic_datagram_socket.local_endpoint [*local_endpoint]]] [Get the local endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.lowest_layer [*lowest_layer]]] [Get a reference to the lowest layer. [hr] Get a const reference to the lowest layer. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_handle [*native_handle]]] [Get the native socket representation. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native_non_blocking [*native_non_blocking]]] [Gets the non-blocking mode of the native socket implementation. [hr] Sets the non-blocking mode of the native socket implementation. ] ] [ [[link boost_asio.reference.basic_datagram_socket.non_blocking [*non_blocking]]] [Gets the non-blocking mode of the socket. [hr] Sets the non-blocking mode of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.open [*open]]] [Open the socket using the specified protocol. ] ] [ [[link boost_asio.reference.basic_datagram_socket.operator_eq_ [*operator=]]] [Move-assign a basic_datagram_socket from another. [hr] Move-assign a basic_datagram_socket from a socket of another protocol type. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive [*receive]]] [Receive some data on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.receive_from [*receive_from]]] [Receive a datagram with the endpoint of the sender. ] ] [ [[link boost_asio.reference.basic_datagram_socket.release [*release]]] [Release ownership of the underlying native socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.remote_endpoint [*remote_endpoint]]] [Get the remote endpoint of the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send [*send]]] [Send some data on a connected socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.send_to [*send_to]]] [Send a datagram to the specified endpoint. ] ] [ [[link boost_asio.reference.basic_datagram_socket.set_option [*set_option]]] [Set an option on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.shutdown [*shutdown]]] [Disable sends or receives on the socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.wait [*wait]]] [Wait for the socket to become ready to read, ready to write, or to have pending error conditions. ] ] [ [[link boost_asio.reference.basic_datagram_socket._basic_datagram_socket [*~basic_datagram_socket]]] [Destroys the socket. ] ] ] [heading Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.max_connections [*max_connections]]] [(Deprecated: Use max_listen_connections.) The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_datagram_socket.max_listen_connections [*max_listen_connections]]] [The maximum length of the queue of pending incoming connections. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_do_not_route [*message_do_not_route]]] [Specify that the data should not be subject to routing. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_end_of_record [*message_end_of_record]]] [Specifies that the data marks the end of a record. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_out_of_band [*message_out_of_band]]] [Process out-of-band data. ] ] [ [[link boost_asio.reference.basic_datagram_socket.message_peek [*message_peek]]] [Peek at incoming data without removing it from the input queue. ] ] ] [heading Protected Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.impl_ [*impl_]]] [] ] ] The [link boost_asio.reference.basic_datagram_socket `basic_datagram_socket`] class template provides asynchronous and blocking datagram-oriented socket functionality. [heading Thread Safety] ['Distinct] ['objects:] Safe. ['Shared] ['objects:] Unsafe. [heading Requirements] ['Header: ][^boost/asio/basic_datagram_socket.hpp] ['Convenience header: ][^boost/asio.hpp] [endsect] [endsect] [section:basic_deadline_timer basic_deadline_timer] Provides waitable timer functionality. template< typename Time, typename ``[link boost_asio.reference.TimeTraits TimeTraits]`` = boost::asio::time_traits