[/ / Copyright (c) 2003-2008 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/AcceptHandler.qbk] [include requirements/AsyncRandomAccessReadDevice.qbk] [include requirements/AsyncRandomAccessWriteDevice.qbk] [include requirements/AsyncReadStream.qbk] [include requirements/AsyncWriteStream.qbk] [include requirements/CompletionHandler.qbk] [include requirements/ConnectHandler.qbk] [include requirements/ConstBufferSequence.qbk] [include requirements/ConvertibleToConstBuffer.qbk] [include requirements/ConvertibleToMutableBuffer.qbk] [include requirements/DatagramSocketService.qbk] [include requirements/DescriptorService.qbk] [include requirements/Endpoint.qbk] [include requirements/GettableSerialPortOption.qbk] [include requirements/GettableSocketOption.qbk] [include requirements/Handler.qbk] [include requirements/HandleService.qbk] [include requirements/InternetProtocol.qbk] [include requirements/IoControlCommand.qbk] [include requirements/IoObjectService.qbk] [include requirements/MutableBufferSequence.qbk] [include requirements/Protocol.qbk] [include requirements/RandomAccessHandleService.qbk] [include requirements/RawSocketService.qbk] [include requirements/ReadHandler.qbk] [include requirements/ResolveHandler.qbk] [include requirements/ResolverService.qbk] [include requirements/SerialPortService.qbk] [include requirements/Service.qbk] [include requirements/SettableSerialPortOption.qbk] [include requirements/SettableSocketOption.qbk] [include requirements/SocketAcceptorService.qbk] [include requirements/SocketService.qbk] [include requirements/StreamDescriptorService.qbk] [include requirements/StreamHandleService.qbk] [include requirements/StreamSocketService.qbk] [include requirements/SyncRandomAccessReadDevice.qbk] [include requirements/SyncRandomAccessWriteDevice.qbk] [include requirements/SyncReadStream.qbk] [include requirements/SyncWriteStream.qbk] [include requirements/TimeTraits.qbk] [include requirements/TimerService.qbk] [include requirements/WaitHandler.qbk] [include requirements/WriteHandler.qbk] [section:add_service add_service] [indexterm1 add_service] template< typename ``[link boost_asio.reference.Service Service]``> void add_service( io_service & ios, Service * svc); This function is used to add a service to the io_service. [heading Parameters] [variablelist [[ios][The io\_service object that owns the service.]] [[svc][The service object. On success, ownership of the service object is transferred to the io\_service. When the io\_service object is destroyed, it will destroy the service object by performing: `` delete static_cast(svc) `` ]] ] [heading Exceptions] [variablelist [[boost::asio::service_already_exists][Thrown if a service of the given type is already present in the io\_service.]] [[boost::asio::invalid_service_owner][Thrown if the service's owning io\_service is not the io\_service object specified by the ios parameter. ]] ] [endsect] [section:asio_handler_allocate asio_handler_allocate] [indexterm1 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. This default implementation is simply: return ::operator new(size); [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); } [endsect] [section:asio_handler_deallocate asio_handler_deallocate] [indexterm1 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. This default implementation is simply: ::operator delete(pointer); [endsect] [section:asio_handler_invoke asio_handler_invoke] [indexterm1 asio_handler_invoke] Default invoke function for handlers. template< typename Function> void asio_handler_invoke( Function function, ... ); Completion handlers for asynchronous operations are invoked by the io_service 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 boost::asio::io\_service::run() on the corresponding io_service object. Handlers may subsequently be invoked through other objects (such as boost::asio::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 is simply: function(); [heading Example] class my_handler; template void asio_handler_invoke(Function function, my_handler* context) { context->strand_.dispatch(function); } [endsect] [section:async_read async_read] [indexterm1 async_read] 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]``> void ``[link boost_asio.reference.async_read.overload1 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read.overload2 async_read]``( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read.overload3 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read.overload4 async_read]``( AsyncReadStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler handler); [section:overload1 async_read (1 of 4 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]``> void async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, ReadHandler handler); 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. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 4 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 CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void async_read( AsyncReadStream & s, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler handler); 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 true. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 4 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]``> void async_read( AsyncReadStream & s, basic_streambuf< Allocator > & b, ReadHandler handler); 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: * An error occurred. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]] ] [heading Remarks] This overload is equivalent to calling: boost::asio::async_read( s, b, boost::asio::transfer_all(), handler); [endsect] [section:overload4 async_read (4 of 4 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 CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void async_read( AsyncReadStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler handler); 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 completion_condition function object returns true. This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. [heading Parameters] [variablelist [[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]] [[b][A 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [endsect] [section:async_read_at async_read_at] [indexterm1 async_read_at] 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]``> void ``[link boost_asio.reference.async_read_at.overload1 async_read_at]``( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, const MutableBufferSequence & buffers, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_at.overload2 async_read_at]``( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_at.overload3 async_read_at]``( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessReadDevice AsyncRandomAccessReadDevice]``, typename Allocator, typename CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_at.overload4 async_read_at]``( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler handler); [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]``> void async_read_at( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, const MutableBufferSequence & buffers, ReadHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void async_read_at( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, const MutableBufferSequence & buffers, CompletionCondition completion_condition, ReadHandler handler); 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 true. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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]``> void async_read_at( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, ReadHandler handler); 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 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 CompletionCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void async_read_at( AsyncRandomAccessReadDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, ReadHandler handler); 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 true. 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 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [endsect] [section:async_read_until async_read_until] [indexterm1 async_read_until] Start an asynchronous operation to read data into a streambuf until it contains a delimiter, matches a regular expression, or a function object indicates a match. template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_until.overload1 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_until.overload2 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const std::string & delim, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_until.overload3 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, ReadHandler handler); template< typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``, typename Allocator, typename MatchCondition, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.async_read_until.overload4 async_read_until]``( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, ReadHandler handler, typename boost::enable_if< is_match_condition< MatchCondition > >::type * = 0); [section:overload1 async_read_until (1 of 4 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]``> void async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, char delim, ReadHandler handler); 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. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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); [endsect] [section:overload2 async_read_until (2 of 4 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]``> void async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const std::string & delim, ReadHandler handler); 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. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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); [endsect] [section:overload3 async_read_until (3 of 4 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]``> void async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, const boost::regex & expr, ReadHandler handler); 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. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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); [endsect] [section:overload4 async_read_until (4 of 4 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]``> void async_read_until( AsyncReadStream & s, boost::asio::basic_streambuf< Allocator > & b, MatchCondition match_condition, ReadHandler handler, typename boost::enable_if< is_match_condition< MatchCondition > >::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. If the match condition function object already indicates a match, the operation completes immediately. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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] [endsect] [section:async_write async_write] [indexterm1 async_write] 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.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write.overload1 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write.overload2 async_write]``( AsyncWriteStream & s, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write.overload3 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``, typename Allocator, typename CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write.overload4 async_write]``( AsyncWriteStream & s, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler handler); [section:overload1 async_write (1 of 4 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]``> void async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, 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 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. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 4 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 CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void async_write( AsyncWriteStream & s, const ConstBufferSequence & buffers, 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 buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes. * The completion_condition function object returns true. This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 4 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]``> void async_write( AsyncWriteStream & s, basic_streambuf< Allocator > & b, 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 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. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[b][A 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [section:overload4 async_write (4 of 4 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 CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void 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 basic_streambuf has been written. * The completion_condition function object returns true. This operation is implemented in terms of zero or more calls to the stream's async\_write\_some function. [heading Parameters] [variablelist [[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]] [[b][A 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [endsect] [section:async_write_at async_write_at] [indexterm1 async_write_at] 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.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write_at.overload1 async_write_at]``( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, const ConstBufferSequence & buffers, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write_at.overload2 async_write_at]``( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write_at.overload3 async_write_at]``( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, WriteHandler handler); template< typename ``[link boost_asio.reference.AsyncRandomAccessWriteDevice AsyncRandomAccessWriteDevice]``, typename Allocator, typename CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.async_write_at.overload4 async_write_at]``( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, CompletionCondition completion_condition, WriteHandler handler); [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]``> void async_write_at( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, const ConstBufferSequence & buffers, WriteHandler handler); 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. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void async_write_at( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, const ConstBufferSequence & buffers, CompletionCondition completion_condition, WriteHandler handler); 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 true. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function. [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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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]``> void async_write_at( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, basic_streambuf< Allocator > & b, WriteHandler handler); 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 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. [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 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 CompletionCondition, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void async_write_at( AsyncRandomAccessWriteDevice & d, boost::uint64_t offset, 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 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 basic_streambuf has been written. * The completion_condition function object returns true. This operation is implemented in terms of zero or more calls to the device's async\_write\_some\_at function. [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 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [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.DatagramSocketService DatagramSocketService]`` = datagram_socket_service> class basic_datagram_socket : public basic_socket< Protocol, DatagramSocketService > [heading Types] [table [[Name][Description]] [ [[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.implementation_type [*implementation_type]]] [The underlying implementation type of I/O 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_type [*native_type]]] [The native representation of a socket. ] ] [ [[link boost_asio.reference.basic_datagram_socket.non_blocking_io [*non_blocking_io]]] [IO control command to set the blocking mode of the socket. ] ] [ [[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.service_type [*service_type]]] [The type of the service that will be used to provide I/O operations. ] ] [ [[link boost_asio.reference.basic_datagram_socket.shutdown_type [*shutdown_type]]] [Different ways a socket may be shutdown. ] ] ] [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.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. Construct and open a basic_datagram_socket. Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. Construct a basic_datagram_socket on an existing native socket. ] ] [ [[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_io_service [*get_io_service]]] [Get the io_service 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.io_service [*io_service]]] [(Deprecated: use get_io_service().) Get the io_service associated with the object. ] ] [ [[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. Get a const reference to the lowest layer. ] ] [ [[link boost_asio.reference.basic_datagram_socket.native [*native]]] [Get the native socket representation. ] ] [ [[link boost_asio.reference.basic_datagram_socket.open [*open]]] [Open the socket using the specified protocol. ] ] [ [[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.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. ] ] ] [heading Data Members] [table [[Name][Description]] [ [[link boost_asio.reference.basic_datagram_socket.max_connections [*max_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_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.implementation [*implementation]]] [The underlying implementation of the I/O object. ] ] [ [[link boost_asio.reference.basic_datagram_socket.service [*service]]] [The service associated with the I/O object. ] ] ] The basic_datagram_socket class template provides asynchronous and blocking datagram-oriented socket functionality. [heading Thread Safety] [*Distinct] [*objects:] Safe. [*Shared] [*objects:] Unsafe. [section:assign basic_datagram_socket::assign] [indexterm2 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_type & native_socket); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.assign.overload2 assign]``( const protocol_type & protocol, const native_type & native_socket, boost::system::error_code & ec); [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_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. boost::system::error_code assign( const protocol_type & protocol, const native_type & native_socket, boost::system::error_code & ec); [endsect] [endsect] [section:async_connect basic_datagram_socket::async_connect] ['Inherited from basic_socket.] [indexterm2 async_connect..basic_datagram_socket] Start an asynchronous connect. void async_connect( const endpoint_type & peer_endpoint, ConnectHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]] ] [heading Example] void connect_handler(const boost::system::error_code& error) { if (!error) { // Connect succeeded. } } ... boost::asio::ip::tcp::socket socket(io_service); 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 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]``> void ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload1 async_receive]``( const MutableBufferSequence & buffers, ReadHandler handler); template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload2 async_receive]``( const MutableBufferSequence & buffers, socket_base::message_flags flags, ReadHandler handler); [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]``> void async_receive( const MutableBufferSequence & buffers, ReadHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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]``> void async_receive( const MutableBufferSequence & buffers, socket_base::message_flags flags, ReadHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 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]``> void ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 async_receive_from]``( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, ReadHandler handler); template< typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``, typename ``[link boost_asio.reference.ReadHandler ReadHandler]``> void ``[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); [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]``> void async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, ReadHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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), 0, 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]``> void async_receive_from( const MutableBufferSequence & buffers, endpoint_type & sender_endpoint, socket_base::message_flags flags, ReadHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [endsect] [section:async_send basic_datagram_socket::async_send] [indexterm2 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]``> void ``[link boost_asio.reference.basic_datagram_socket.async_send.overload1 async_send]``( const ConstBufferSequence & buffers, WriteHandler handler); template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[link boost_asio.reference.basic_datagram_socket.async_send.overload2 async_send]``( const ConstBufferSequence & buffers, socket_base::message_flags flags, WriteHandler handler); [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]``> void async_send( const ConstBufferSequence & buffers, WriteHandler handler); 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. 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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]``> void async_send( const ConstBufferSequence & buffers, socket_base::message_flags flags, WriteHandler handler); 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. 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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 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]``> void ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 async_send_to]``( const ConstBufferSequence & buffers, const endpoint_type & destination, WriteHandler handler); template< typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``, typename ``[link boost_asio.reference.WriteHandler WriteHandler]``> void ``[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); [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]``> void async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, WriteHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::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]``> void async_send_to( const ConstBufferSequence & buffers, const endpoint_type & destination, socket_base::message_flags flags, WriteHandler handler); 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. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]] ] [endsect] [endsect] [section:at_mark basic_datagram_socket::at_mark] [indexterm2 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; bool ``[link boost_asio.reference.basic_datagram_socket.at_mark.overload2 at_mark]``( boost::system::error_code & ec) const; [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 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; std::size_t ``[link boost_asio.reference.basic_datagram_socket.available.overload2 available]``( boost::system::error_code & ec) const; [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 basic_datagram_socket..basic_datagram_socket] Construct a basic_datagram_socket without opening it. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload1 basic_datagram_socket]``( boost::asio::io_service & io_service); Construct and open a basic_datagram_socket. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload2 basic_datagram_socket]``( boost::asio::io_service & io_service, const protocol_type & protocol); Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload3 basic_datagram_socket]``( boost::asio::io_service & io_service, const endpoint_type & endpoint); Construct a basic_datagram_socket on an existing native socket. ``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload4 basic_datagram_socket]``( boost::asio::io_service & io_service, const protocol_type & protocol, const native_type & native_socket); [section:overload1 basic_datagram_socket::basic_datagram_socket (1 of 4 overloads)] Construct a basic_datagram_socket without opening it. basic_datagram_socket( boost::asio::io_service & io_service); 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 [[io_service][The io\_service object that the datagram socket will use to dispatch handlers for any asynchronous operations performed on the socket. ]] ] [endsect] [section:overload2 basic_datagram_socket::basic_datagram_socket (2 of 4 overloads)] Construct and open a basic_datagram_socket. basic_datagram_socket( boost::asio::io_service & io_service, const protocol_type & protocol); This constructor creates and opens a datagram socket. [heading Parameters] [variablelist [[io_service][The io\_service object that the datagram socket will use 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:overload3 basic_datagram_socket::basic_datagram_socket (3 of 4 overloads)] Construct a basic_datagram_socket, opening it and binding it to the given local endpoint. basic_datagram_socket( boost::asio::io_service & io_service, 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 [[io_service][The io\_service object that the datagram socket will use 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:overload4 basic_datagram_socket::basic_datagram_socket (4 of 4 overloads)] Construct a basic_datagram_socket on an existing native socket. basic_datagram_socket( boost::asio::io_service & io_service, const protocol_type & protocol, const native_type & native_socket); This constructor creates a datagram socket object to hold an existing native socket. [heading Parameters] [variablelist [[io_service][The io\_service object that the datagram socket will use 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] [endsect] [section:bind basic_datagram_socket::bind] [indexterm2 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); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.bind.overload2 bind]``( const endpoint_type & endpoint, boost::system::error_code & ec); [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(io_service); 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. boost::system::error_code 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(io_service); 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 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(io_service); ... boost::asio::socket_base::broadcast option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::udp::socket socket(io_service); ... boost::asio::socket_base::broadcast option; socket.get_option(option); bool is_set = option.value(); [endsect] [section:bytes_readable basic_datagram_socket::bytes_readable] ['Inherited from socket_base.] [indexterm2 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(io_service); ... boost::asio::socket_base::bytes_readable command(true); socket.io_control(command); std::size_t bytes_readable = command.get(); [endsect] [section:cancel basic_datagram_socket::cancel] [indexterm2 cancel..basic_datagram_socket] Cancel all asynchronous operations associated with the socket. void ``[link boost_asio.reference.basic_datagram_socket.cancel.overload1 cancel]``(); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.cancel.overload2 cancel]``( boost::system::error_code & ec); [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. boost::system::error_code 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 close..basic_datagram_socket] Close the socket. void ``[link boost_asio.reference.basic_datagram_socket.close.overload1 close]``(); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.close.overload2 close]``( boost::system::error_code & ec); [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.]] ] [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. boost::system::error_code 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.]] ] [heading Example] boost::asio::ip::tcp::socket socket(io_service); ... 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 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); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.connect.overload2 connect]``( const endpoint_type & peer_endpoint, boost::system::error_code & ec); [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(io_service); 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. boost::system::error_code 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(io_service); 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 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(io_service); ... boost::asio::socket_base::debug option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::debug option; socket.get_option(option); bool is_set = option.value(); [endsect] [section:do_not_route basic_datagram_socket::do_not_route] ['Inherited from socket_base.] [indexterm2 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(io_service); ... boost::asio::socket_base::do_not_route option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::udp::socket socket(io_service); ... boost::asio::socket_base::do_not_route option; socket.get_option(option); bool is_set = option.value(); [endsect] [section:enable_connection_aborted basic_datagram_socket::enable_connection_aborted] ['Inherited from socket_base.] [indexterm2 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(io_service); ... boost::asio::socket_base::enable_connection_aborted option(true); acceptor.set_option(option); Getting the current option value: boost::asio::ip::tcp::acceptor acceptor(io_service); ... boost::asio::socket_base::enable_connection_aborted option; acceptor.get_option(option); bool is_set = option.value(); [endsect] [section:endpoint_type basic_datagram_socket::endpoint_type] [indexterm2 endpoint_type..basic_datagram_socket] The endpoint type. typedef Protocol::endpoint endpoint_type; [endsect] [section:get_io_service basic_datagram_socket::get_io_service] ['Inherited from basic_io_object.] [indexterm2 get_io_service..basic_datagram_socket] Get the io_service associated with the object. boost::asio::io_service & get_io_service(); This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations. [heading Return Value] A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller. [endsect] [section:get_option basic_datagram_socket::get_option] [indexterm2 get_option..basic_datagram_socket] Get an option from the socket. void ``[link boost_asio.reference.basic_datagram_socket.get_option.overload1 get_option]``( GettableSocketOption & option) const; boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.get_option.overload2 get_option]``( GettableSocketOption & option, boost::system::error_code & ec) const; [section:overload1 basic_datagram_socket::get_option (1 of 2 overloads)] ['Inherited from basic_socket.] Get an option from the socket. 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(io_service); ... boost::asio::ip::tcp::socket::keep_alive option; socket.get_option(option); bool is_set = option.get(); [endsect] [section:overload2 basic_datagram_socket::get_option (2 of 2 overloads)] ['Inherited from basic_socket.] Get an option from the socket. boost::system::error_code 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(io_service); ... 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.get(); [endsect] [endsect] [section:implementation basic_datagram_socket::implementation] ['Inherited from basic_io_object.] [indexterm2 implementation..basic_datagram_socket] The underlying implementation of the I/O object. implementation_type implementation; [endsect] [section:implementation_type basic_datagram_socket::implementation_type] ['Inherited from basic_io_object.] [indexterm2 implementation_type..basic_datagram_socket] The underlying implementation type of I/O object. typedef service_type::implementation_type implementation_type; [endsect] [section:io_control basic_datagram_socket::io_control] [indexterm2 io_control..basic_datagram_socket] Perform an IO control command on the socket. void ``[link boost_asio.reference.basic_datagram_socket.io_control.overload1 io_control]``( IoControlCommand & command); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.io_control.overload2 io_control]``( IoControlCommand & command, boost::system::error_code & ec); [section:overload1 basic_datagram_socket::io_control (1 of 2 overloads)] ['Inherited from basic_socket.] Perform an IO control command on the socket. 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(io_service); ... 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. boost::system::error_code 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(io_service); ... 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:io_service basic_datagram_socket::io_service] ['Inherited from basic_io_object.] [indexterm2 io_service..basic_datagram_socket] (Deprecated: use get_io_service().) Get the io_service associated with the object. boost::asio::io_service & io_service(); This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations. [heading Return Value] A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller. [endsect] [section:is_open basic_datagram_socket::is_open] ['Inherited from basic_socket.] [indexterm2 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 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(io_service); ... boost::asio::socket_base::keep_alive option(true); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::keep_alive option; socket.get_option(option); bool is_set = option.value(); [endsect] [section:linger basic_datagram_socket::linger] ['Inherited from socket_base.] [indexterm2 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(io_service); ... boost::asio::socket_base::linger option(true, 30); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::linger option; socket.get_option(option); bool is_set = option.enabled(); unsigned short timeout = option.timeout(); [endsect] [section:local_endpoint basic_datagram_socket::local_endpoint] [indexterm2 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; endpoint_type ``[link boost_asio.reference.basic_datagram_socket.local_endpoint.overload2 local_endpoint]``( boost::system::error_code & ec) const; [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(io_service); ... 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(io_service); ... 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 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]``(); 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; [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 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 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 lowest_layer_type..basic_datagram_socket] A basic_socket is always the lowest layer. typedef basic_socket< Protocol, DatagramSocketService > lowest_layer_type; [heading Types] [table [[Name][Description]] [ [[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.implementation_type [*implementation_type]]] [The underlying implementation type of I/O 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_type [*native_type]]] [The native representation of a socket. ] ] [ [[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]] [IO control command to set the blocking mode of the socket. ] ] [ [[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.service_type [*service_type]]] [The type of the service that will be used to provide I/O operations. ] ] [ [[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]] [Different ways a socket may be shutdown. ] ] ] [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.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. Construct and open a basic_socket. Construct a basic_socket, opening it and binding it to the given local endpoint. Construct a basic_socket on an existing native socket. ] ] [ [[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_io_service [*get_io_service]]] [Get the io_service 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.io_service [*io_service]]] [(Deprecated: use get_io_service().) Get the io_service associated with the object. ] ] [ [[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. Get a const reference to the lowest layer. ] ] [ [[link boost_asio.reference.basic_socket.native [*native]]] [Get the native socket representation. ] ] [ [[link boost_asio.reference.basic_socket.open [*open]]] [Open the socket using the specified protocol. ] ] [ [[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. ] ] ] [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]]] [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_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.implementation [*implementation]]] [The underlying implementation of the I/O object. ] ] [ [[link boost_asio.reference.basic_socket.service [*service]]] [The service associated with the I/O object. ] ] ] The 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. [endsect] [section:max_connections basic_datagram_socket::max_connections] ['Inherited from socket_base.] [indexterm2 max_connections..basic_datagram_socket] The maximum length of the queue of pending incoming connections. static const int max_connections = implementation_defined; [endsect] [section:message_do_not_route basic_datagram_socket::message_do_not_route] ['Inherited from socket_base.] [indexterm2 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_flags basic_datagram_socket::message_flags] ['Inherited from socket_base.] [indexterm2 message_flags..basic_datagram_socket] Bitmask type for flags that can be passed to send and receive operations. typedef int message_flags; [endsect] [section:message_out_of_band basic_datagram_socket::message_out_of_band] ['Inherited from socket_base.] [indexterm2 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 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 basic_datagram_socket::native] ['Inherited from basic_socket.] [indexterm2 native..basic_datagram_socket] Get the native socket representation. native_type native(); 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_type basic_datagram_socket::native_type] [indexterm2 native_type..basic_datagram_socket] The native representation of a socket. typedef DatagramSocketService::native_type native_type; [endsect] [section:non_blocking_io basic_datagram_socket::non_blocking_io] ['Inherited from socket_base.] [indexterm2 non_blocking_io..basic_datagram_socket] IO control command to set the blocking mode of the socket. typedef implementation_defined non_blocking_io; Implements the FIONBIO IO control command. [heading Example] boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::non_blocking_io command(true); socket.io_control(command); [endsect] [section:open basic_datagram_socket::open] [indexterm2 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()); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.open.overload2 open]``( const protocol_type & protocol, boost::system::error_code & ec); [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(io_service); 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. boost::system::error_code 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(io_service); boost::system::error_code ec; socket.open(boost::asio::ip::tcp::v4(), ec); if (ec) { // An error occurred. } [endsect] [endsect] [section:protocol_type basic_datagram_socket::protocol_type] [indexterm2 protocol_type..basic_datagram_socket] The protocol type. typedef Protocol protocol_type; [endsect] [section:receive basic_datagram_socket::receive] [indexterm2 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); 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); 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); [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 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(io_service); ... boost::asio::socket_base::receive_buffer_size option(8192); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::receive_buffer_size option; socket.get_option(option); int size = option.value(); [endsect] [section:receive_from basic_datagram_socket::receive_from] [indexterm2 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); 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); 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); [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 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(io_service); ... boost::asio::socket_base::receive_low_watermark option(1024); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::receive_low_watermark option; socket.get_option(option); int size = option.value(); [endsect] [section:remote_endpoint basic_datagram_socket::remote_endpoint] [indexterm2 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; endpoint_type ``[link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload2 remote_endpoint]``( boost::system::error_code & ec) const; [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(io_service); ... 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(io_service); ... 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 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(io_service); ... boost::asio::socket_base::reuse_address option(true); acceptor.set_option(option); Getting the current option value: boost::asio::ip::tcp::acceptor acceptor(io_service); ... boost::asio::socket_base::reuse_address option; acceptor.get_option(option); bool is_set = option.value(); [endsect] [section:send basic_datagram_socket::send] [indexterm2 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); 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); 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); [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 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(io_service); ... boost::asio::socket_base::send_buffer_size option(8192); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::send_buffer_size option; socket.get_option(option); int size = option.value(); [endsect] [section:send_low_watermark basic_datagram_socket::send_low_watermark] ['Inherited from socket_base.] [indexterm2 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(io_service); ... boost::asio::socket_base::send_low_watermark option(1024); socket.set_option(option); Getting the current option value: boost::asio::ip::tcp::socket socket(io_service); ... boost::asio::socket_base::send_low_watermark option; socket.get_option(option); int size = option.value(); [endsect] [section:send_to basic_datagram_socket::send_to] [indexterm2 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); 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); 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); [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:service basic_datagram_socket::service] ['Inherited from basic_io_object.] [indexterm2 service..basic_datagram_socket] The service associated with the I/O object. service_type & service; [endsect] [section:service_type basic_datagram_socket::service_type] ['Inherited from basic_io_object.] [indexterm2 service_type..basic_datagram_socket] The type of the service that will be used to provide I/O operations. typedef DatagramSocketService service_type; [endsect] [section:set_option basic_datagram_socket::set_option] [indexterm2 set_option..basic_datagram_socket] Set an option on the socket. void ``[link boost_asio.reference.basic_datagram_socket.set_option.overload1 set_option]``( const SettableSocketOption & option); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.set_option.overload2 set_option]``( const SettableSocketOption & option, boost::system::error_code & ec); [section:overload1 basic_datagram_socket::set_option (1 of 2 overloads)] ['Inherited from basic_socket.] Set an option on the socket. 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(io_service); ... 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. boost::system::error_code 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(io_service); ... 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 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); boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.shutdown.overload2 shutdown]``( shutdown_type what, boost::system::error_code & ec); [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(io_service); ... 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. boost::system::error_code 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(io_service); ... 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 shutdown_type..basic_datagram_socket] Different ways a socket may be shutdown. enum shutdown_type [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] [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