Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Reference

Requirements on asynchronous operations
Accept handler requirements
Buffer-oriented asynchronous random-access read device requirements
Buffer-oriented asynchronous random-access write device requirements
Buffer-oriented asynchronous read stream requirements
Buffer-oriented asynchronous write stream requirements
Buffered handshake handler requirements
Completion handler requirements
Composed connect handler requirements
Connect handler requirements
Constant buffer sequence requirements
Convertible to const buffer requirements
Convertible to mutable buffer requirements
Datagram socket service requirements
Descriptor service requirements
Endpoint requirements
Gettable serial port option requirements
Gettable socket option requirements
Handlers
Handle service requirements
SSL handshake handler requirements
Internet protocol requirements
I/O control command requirements
I/O object service requirements
Mutable buffer sequence requirements
Object handle service requirements
Protocol requirements
Random access handle service requirements
Raw socket service requirements
Read handler requirements
Resolve handler requirements
Resolver service requirements
Sequenced packet socket service requirements
Serial port service requirements
Service requirements
Settable serial port option requirements
Settable socket option requirements
SSL shutdown handler requirements
Signal handler requirements
Signal set service requirements
Socket acceptor service requirements
Socket service requirements
Stream descriptor service requirements
Stream handle service requirements
Stream socket service requirements
Buffer-oriented synchronous random-access read device requirements
Buffer-oriented synchronous random-access write device requirements
Buffer-oriented synchronous read stream requirements
Buffer-oriented synchronous write stream requirements
Time traits requirements
Timer service requirements
Waitable timer service requirements
Wait handler requirements
Wait traits requirements
Write handler requirements
add_service
asio_handler_allocate
asio_handler_deallocate
asio_handler_invoke
asio_handler_is_continuation
async_connect
async_read
async_read_at
async_read_until
async_result
async_write
async_write_at
basic_datagram_socket
basic_deadline_timer
basic_io_object
basic_raw_socket
basic_seq_packet_socket
basic_serial_port
basic_signal_set
basic_socket
basic_socket_acceptor
basic_socket_iostream
basic_socket_streambuf
basic_stream_socket
basic_streambuf
basic_waitable_timer
basic_yield_context
buffer
buffer_cast
buffer_copy
buffer_size
buffered_read_stream
buffered_stream
buffered_write_stream
buffers_begin
buffers_end
buffers_iterator
connect
const_buffer
const_buffers_1
coroutine
datagram_socket_service
deadline_timer
deadline_timer_service
error::addrinfo_category
error::addrinfo_errors
error::basic_errors
error::get_addrinfo_category
error::get_misc_category
error::get_netdb_category
error::get_ssl_category
error::get_system_category
error::make_error_code
error::misc_category
error::misc_errors
error::netdb_category
error::netdb_errors
error::ssl_category
error::ssl_errors
error::system_category
generic::basic_endpoint
generic::datagram_protocol
generic::raw_protocol
generic::seq_packet_protocol
generic::stream_protocol
handler_type
has_service
high_resolution_timer
invalid_service_owner
io_service
io_service::id
io_service::service
io_service::strand
io_service::work
ip::address
ip::address_v4
ip::address_v6
ip::basic_endpoint
ip::basic_resolver
ip::basic_resolver_entry
ip::basic_resolver_iterator
ip::basic_resolver_query
ip::host_name
ip::icmp
ip::multicast::enable_loopback
ip::multicast::hops
ip::multicast::join_group
ip::multicast::leave_group
ip::multicast::outbound_interface
ip::resolver_query_base
ip::resolver_service
ip::tcp
ip::udp
ip::unicast::hops
ip::v6_only
is_match_condition
is_read_buffered
is_write_buffered
local::basic_endpoint
local::connect_pair
local::datagram_protocol
local::stream_protocol
mutable_buffer
mutable_buffers_1
null_buffers
placeholders::bytes_transferred
placeholders::error
placeholders::iterator
placeholders::signal_number
posix::basic_descriptor
posix::basic_stream_descriptor
posix::descriptor_base
posix::stream_descriptor
posix::stream_descriptor_service
raw_socket_service
read
read_at
read_until
seq_packet_socket_service
serial_port
serial_port_base
serial_port_base::baud_rate
serial_port_base::character_size
serial_port_base::flow_control
serial_port_base::parity
serial_port_base::stop_bits
serial_port_service
service_already_exists
signal_set
signal_set_service
socket_acceptor_service
socket_base
spawn
ssl::context
ssl::context_base
ssl::error::get_stream_category
ssl::error::make_error_code
ssl::error::stream_category
ssl::error::stream_errors
ssl::rfc2818_verification
ssl::stream
ssl::stream::impl_struct
ssl::stream_base
ssl::verify_client_once
ssl::verify_context
ssl::verify_fail_if_no_peer_cert
ssl::verify_mode
ssl::verify_none
ssl::verify_peer
steady_timer
strand
stream_socket_service
streambuf
system_timer
time_traits< boost::posix_time::ptime >
transfer_all
transfer_at_least
transfer_exactly
use_future
use_future_t
use_service
wait_traits
waitable_timer_service
windows::basic_handle
windows::basic_object_handle
windows::basic_random_access_handle
windows::basic_stream_handle
windows::object_handle
windows::object_handle_service
windows::overlapped_ptr
windows::random_access_handle
windows::random_access_handle_service
windows::stream_handle
windows::stream_handle_service
write
write_at
yield_context
boost::system::is_error_code_enum< boost::asio::error::addrinfo_errors >
boost::system::is_error_code_enum< boost::asio::error::basic_errors >
boost::system::is_error_code_enum< boost::asio::error::misc_errors >
boost::system::is_error_code_enum< boost::asio::error::netdb_errors >
boost::system::is_error_code_enum< boost::asio::error::ssl_errors >
boost::system::is_error_code_enum< boost::asio::ssl::error::stream_errors >

Core

Classes

const_buffer
const_buffers_1
coroutine
invalid_service_owner
io_service
io_service::id
io_service::service
io_service::strand
io_service::work
mutable_buffer
mutable_buffers_1
null_buffers
service_already_exists
streambuf
use_future_t
yield_context

Class Templates

basic_io_object
basic_streambuf
basic_yield_context
buffered_read_stream
buffered_stream
buffered_write_stream
buffers_iterator

Free Functions

add_service
asio_handler_allocate
asio_handler_deallocate
asio_handler_invoke
asio_handler_is_continuation
async_read
async_read_at
async_read_until
async_write
async_write_at
buffer
buffer_cast
buffer_copy
buffer_size
buffers_begin
buffers_end
has_service
read
read_at
read_until
spawn
transfer_all
transfer_at_least
transfer_exactly
use_service
write
write_at

Special Values

use_future

Boost.Bind Placeholders

placeholders::bytes_transferred
placeholders::error
placeholders::iterator
placeholders::signal_number

Error Codes

error::basic_errors
error::netdb_errors
error::addrinfo_errors
error::misc_errors

Type Traits

async_result
handler_type
is_match_condition
is_read_buffered
is_write_buffered

Type Requirements

Asynchronous operations
AsyncRandomAccessReadDevice
AsyncRandomAccessWriteDevice
AsyncReadStream
AsyncWriteStream
CompletionHandler
ConstBufferSequence
ConvertibleToConstBuffer
ConvertibleToMutableBuffer
Handler
IoObjectService
MutableBufferSequence
ReadHandler
Service
SyncRandomAccessReadDevice
SyncRandomAccessWriteDevice
SyncReadStream
SyncWriteStream
WriteHandler

Networking

Classes

generic::datagram_protocol
generic::datagram_protocol::endpoint
generic::datagram_protocol::socket
generic::raw_protocol
generic::raw_protocol::endpoint
generic::raw_protocol::socket
generic::seq_packet_protocol
generic::seq_packet_protocol::endpoint
generic::seq_packet_protocol::socket
generic::stream_protocol
generic::stream_protocol::endpoint
generic::stream_protocol::iostream
generic::stream_protocol::socket
ip::address
ip::address_v4
ip::address_v6
ip::icmp
ip::icmp::endpoint
ip::icmp::resolver
ip::icmp::socket
ip::resolver_query_base
ip::tcp
ip::tcp::acceptor
ip::tcp::endpoint
ip::tcp::iostream
ip::tcp::resolver
ip::tcp::socket
ip::udp
ip::udp::endpoint
ip::udp::resolver
ip::udp::socket
socket_base

Free Functions

async_connect
connect
ip::host_name

Class Templates

basic_datagram_socket
basic_raw_socket
basic_seq_packet_socket
basic_socket
basic_socket_acceptor
basic_socket_iostream
basic_socket_streambuf
basic_stream_socket
generic::basic_endpoint
ip::basic_endpoint
ip::basic_resolver
ip::basic_resolver_entry
ip::basic_resolver_iterator
ip::basic_resolver_query

Services

datagram_socket_service
ip::resolver_service
raw_socket_service
seq_packet_socket_service
socket_acceptor_service
stream_socket_service

Socket Options

ip::multicast::enable_loopback
ip::multicast::hops
ip::multicast::join_group
ip::multicast::leave_group
ip::multicast::outbound_interface
ip::tcp::no_delay
ip::unicast::hops
ip::v6_only
socket_base::broadcast
socket_base::debug
socket_base::do_not_route
socket_base::enable_connection_aborted
socket_base::keep_alive
socket_base::linger
socket_base::receive_buffer_size
socket_base::receive_low_watermark
socket_base::reuse_address
socket_base::send_buffer_size
socket_base::send_low_watermark

I/O Control Commands

socket_base::bytes_readable
socket_base::non_blocking_io

Type Requirements

AcceptHandler
ComposedConnectHandler
ConnectHandler
DatagramSocketService
Endpoint
GettableSocketOption
InternetProtocol
IoControlCommand
Protocol
RawSocketService
ResolveHandler
ResolverService
SeqPacketSocketService
SettableSocketOption
SocketAcceptorService
SocketService
StreamSocketService

Timers

SSL

Serial Ports

Signal Handling

Classes

deadline_timer
high_resolution_timer
steady_timer
system_timer

Class Templates

basic_deadline_timer
basic_waitable_timer
time_traits
wait_traits

Services

deadline_timer_service
waitable_timer_service

Type Requirements

TimerService
TimeTraits
WaitableTimerService
WaitHandler
WaitTraits

Classes

ssl::context
ssl::context_base
ssl::rfc2818_verification
ssl::stream_base
ssl::verify_context

Class Templates

ssl::stream

Type Requirements

BufferedHandshakeHandler
HandshakeHandler
ShutdownHandler

Classes

serial_port
serial_port_base

Class Templates

basic_serial_port

Services

serial_port_service

Serial Port Options

serial_port_base::baud_rate
serial_port_base::flow_control
serial_port_base::parity
serial_port_base::stop_bits
serial_port_base::character_size

Type Requirements

GettableSerialPortOption
SerialPortService
SettableSerialPortOption

Classes

signal_set

Class Templates

basic_signal_set

Services

signal_set_service

Type Requirements

SignalSetService
SignalHandler

POSIX-specific

Windows-specific

Classes

local::stream_protocol
local::stream_protocol::acceptor
local::stream_protocol::endpoint
local::stream_protocol::iostream
local::stream_protocol::socket
local::datagram_protocol
local::datagram_protocol::endpoint
local::datagram_protocol::socket
posix::descriptor_base
posix::stream_descriptor

Free Functions

local::connect_pair

Class Templates

local::basic_endpoint
posix::basic_descriptor
posix::basic_stream_descriptor

Services

posix::stream_descriptor_service

Type Requirements

DescriptorService
StreamDescriptorService

Classes

windows::object_handle
windows::overlapped_ptr
windows::random_access_handle
windows::stream_handle

Class Templates

windows::basic_handle
windows::basic_object_handle
windows::basic_random_access_handle
windows::basic_stream_handle

Services

windows::object_handle_service
windows::random_access_handle_service
windows::stream_handle_service

Type Requirements

HandleService
ObjectHandleService
RandomAccessHandleService
StreamHandleService

In Boost.Asio, an asynchronous operation is initiated by a function that is named with the prefix async_. These functions will be referred to as initiating functions.

All initiating functions in Boost.Asio take a function object meeting handler requirements as the final parameter. These handlers accept as their first parameter an lvalue of type const error_code.

Implementations of asynchronous operations in Boost.Asio may call the application programming interface (API) provided by the operating system. If such an operating system API call results in an error, the handler will be invoked with a const error_code lvalue that evaluates to true. Otherwise the handler will be invoked with a const error_code lvalue that evaluates to false.

Unless otherwise noted, when the behaviour of an asynchronous operation is defined "as if" implemented by a POSIX function, the handler will be invoked with a value of type error_code that corresponds to the failure condition described by POSIX for that function, if any. Otherwise the handler will be invoked with an implementation-defined error_code value that reflects the operating system error.

Asynchronous operations will not fail with an error condition that indicates interruption by a signal (POSIX EINTR). Asynchronous operations will not fail with any error condition associated with non-blocking operations (POSIX EWOULDBLOCK, EAGAIN or EINPROGRESS; Windows WSAEWOULDBLOCK or WSAEINPROGRESS).

All asynchronous operations have an associated io_service object. Where the initiating function is a member function, the associated io_service is that returned by the get_io_service() member function on the same object. Where the initiating function is not a member function, the associated io_service is that returned by the get_io_service() member function of the first argument to the initiating function.

Arguments to initiating functions will be treated as follows:

— If the parameter is declared as a const reference or by-value, the program is not required to guarantee the validity of the argument after the initiating function completes. The implementation may make copies of the argument, and all copies will be destroyed no later than immediately after invocation of the handler.

— If the parameter is declared as a non-const reference, const pointer or non-const pointer, the program must guarantee the validity of the argument until the handler is invoked.

The library implementation is only permitted to make calls to an initiating function's arguments' copy constructors or destructors from a thread that satisfies one of the following conditions:

— The thread is executing any member function of the associated io_service object.

— The thread is executing the destructor of the associated io_service object.

— The thread is executing one of the io_service service access functions use_service, add_service or has_service, where the first argument is the associated io_service object.

— The thread is executing any member function, constructor or destructor of an object of a class defined in this clause, where the object's get_io_service() member function returns the associated io_service object.

— The thread is executing any function defined in this clause, where any argument to the function has an get_io_service() member function that returns the associated io_service object.

The io_service object associated with an asynchronous operation will have unfinished work, as if by maintaining the existence of one or more objects of class io_service::work constructed using the io_service, until immediately after the handler for the asynchronous operation has been invoked.

When an asynchronous operation is complete, the handler for the operation will be invoked as if by:

  1. Constructing a bound completion handler bch for the handler, as described below.
  2. Calling ios.post(bch) to schedule the handler for deferred invocation, where ios is the associated io_service.

This implies that the handler must not be called directly from within the initiating function, even if the asynchronous operation completes immediately.

A bound completion handler is a handler object that contains a copy of a user-supplied handler, where the user-supplied handler accepts one or more arguments. The bound completion handler does not accept any arguments, and contains values to be passed as arguments to the user-supplied handler. The bound completion handler forwards the asio_handler_allocate(), asio_handler_deallocate(), and asio_handler_invoke() calls to the corresponding functions for the user-supplied handler. A bound completion handler meets the requirements for a completion handler.

For example, a bound completion handler for a ReadHandler may be implemented as follows:

template<class ReadHandler>
struct bound_read_handler
{
  bound_read_handler(ReadHandler handler, const error_code& ec, size_t s)
    : handler_(handler), ec_(ec), s_(s)
  {
  }

  void operator()()
  {
    handler_(ec_, s_);
  }

  ReadHandler handler_;
  const error_code ec_;
  const size_t s_;
};

template<class ReadHandler>
void* asio_handler_allocate(size_t size,
                            bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_allocate;
  return asio_handler_allocate(size, &this_handler->handler_);
}

template<class ReadHandler>
void asio_handler_deallocate(void* pointer, std::size_t size,
                             bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_deallocate;
  asio_handler_deallocate(pointer, size, &this_handler->handler_);
}

template<class F, class ReadHandler>
void asio_handler_invoke(const F& f,
                         bound_read_handler<ReadHandler>* this_handler)
{
  using boost::asio::asio_handler_invoke;
  asio_handler_invoke(f, &this_handler->handler_);
}

If the thread that initiates an asynchronous operation terminates before the associated handler is invoked, the behaviour is implementation-defined. Specifically, on Windows versions prior to Vista, unfinished operations are cancelled when the initiating thread exits.

The handler argument to an initiating function defines a handler identity. That is, the original handler argument and any copies of the handler argument will be considered equivalent. If the implementation needs to allocate storage for an asynchronous operation, the implementation will perform asio_handler_allocate(size, &h), where size is the required size in bytes, and h is the handler. The implementation will perform asio_handler_deallocate(p, size, &h), where p is a pointer to the storage, to deallocate the storage prior to the invocation of the handler via asio_handler_invoke. Multiple storage blocks may be allocated for a single asynchronous operation.

Return type of an initiating function

By default, initiating functions return void. This is always the case when the handler is a function pointer, C++11 lambda, or a function object produced by boost::bind or std::bind.

For other types, the return type may be customised via a two-step process:

  1. A specialisation of the handler_type template, which is used to determine the true handler type based on the asynchronous operation's handler's signature.
  2. A specialisation of the async_result template, which is used both to determine the return type and to extract the return value from the handler.

These two templates have been specialised to provide support for stackful coroutines and the C++11 std::future class.

As an example, consider what happens when enabling std::future support by using the boost::asio::use_future special value, as in:

std::future<std::size_t> length =
  my_socket.async_read_some(my_buffer, boost::asio::use_future);

When a handler signature has the form:

void handler(error_code ec, result_type result);

the initiating function returns a std::future templated on result_type. In the above async_read_some example, this is std::size_t. If the asynchronous operation fails, the error_code is converted into a system_error exception and passed back to the caller through the future.

Where a handler signature has the form:

void handler(error_code ec);

the initiating function instead returns std::future<void>.

An accept handler must meet the requirements for a handler. A value h of an accept handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as an accept handler:

void accept_handler(
    const boost::system::error_code& ec)
{
  ...
}

An accept handler function object:

struct accept_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to an accept handler using bind():

void my_class::accept_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
acceptor.async_accept(...,
    boost::bind(&my_class::accept_handler,
      this, boost::asio::placeholders::error));

In the table below, a denotes an asynchronous random access read device object, o denotes an offset of type boost::uint64_t, mb denotes an object satisfying mutable buffer sequence requirements, and h denotes an object satisfying read handler requirements.

Table 7.1. Buffer-oriented asynchronous random-access read device requirements

operation

type

semantics, pre/post-conditions

a.get_io_service();

io_service&

Returns the io_service object through which the async_read_some_at handler h will be invoked.

a.async_read_some_at(o, mb, h);

void

Initiates an asynchronous operation to read one or more bytes of data from the device a at the offset o. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The async_read_some_at operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous read operation is invoked,

whichever comes first.

If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.


In the table below, a denotes an asynchronous write stream object, o denotes an offset of type boost::uint64_t, cb denotes an object satisfying constant buffer sequence requirements, and h denotes an object satisfying write handler requirements.

Table 7.2. Buffer-oriented asynchronous random-access write device requirements

operation

type

semantics, pre/post-conditions

a.get_io_service();

io_service&

Returns the io_service object through which the async_write_some_at handler h will be invoked.

a.async_write_some_at(o, cb, h);

void

Initiates an asynchronous operation to write one or more bytes of data to the device a at offset o. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The async_write_some_at operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous write operation is invoked,

whichever comes first.

If the total size of all buffers in the sequence cb is 0, the asynchronous write operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes written.


In the table below, a denotes an asynchronous read stream object, mb denotes an object satisfying mutable buffer sequence requirements, and h denotes an object satisfying read handler requirements.

Table 7.3. Buffer-oriented asynchronous read stream requirements

operation

type

semantics, pre/post-conditions

a.get_io_service();

io_service&

Returns the io_service object through which the async_read_some handler h will be invoked.

a.async_read_some(mb, h);

void

Initiates an asynchronous operation to read one or more bytes of data from the stream a. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The async_read_some operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous read operation is invoked,

whichever comes first.

If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.


In the table below, a denotes an asynchronous write stream object, cb denotes an object satisfying constant buffer sequence requirements, and h denotes an object satisfying write handler requirements.

Table 7.4. Buffer-oriented asynchronous write stream requirements

operation

type

semantics, pre/post-conditions

a.get_io_service();

io_service&

Returns the io_service object through which the async_write_some handler h will be invoked.

a.async_write_some(cb, h);

void

Initiates an asynchronous operation to write one or more bytes of data to the stream a. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The async_write_some operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous write operation is invoked,

whichever comes first.

If the total size of all buffers in the sequence cb is 0, the asynchronous write operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes written.


A buffered handshake handler must meet the requirements for a handler. A value h of a buffered handshake handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a buffered handshake handler:

void handshake_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A buffered handshake handler function object:

struct handshake_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a buffered handshake handler using bind():

void my_class::handshake_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_handshake(...,
    boost::bind(&my_class::handshake_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

A completion handler must meet the requirements for a handler. A value h of a completion handler class should work correctly in the expression h().

Examples

A free function as a completion handler:

void completion_handler()
{
  ...
}

A completion handler function object:

struct completion_handler
{
  ...
  void operator()()
  {
    ...
  }
  ...
};

A non-static class member function adapted to a completion handler using bind():

void my_class::completion_handler()
{
  ...
}
...
my_io_service.post(boost::bind(&my_class::completion_handler, this));

A composed connect handler must meet the requirements for a handler. A value h of a composed connect handler class should work correctly in the expression h(ec, i), where ec is an lvalue of type const error_code and i is an lvalue of the type Iterator used in the corresponding connect() or async_connect()` function.

Examples

A free function as a composed connect handler:

void connect_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}

A composed connect handler function object:

struct connect_handler
{
  ...
  template <typename Iterator>
  void operator()(
      const boost::system::error_code& ec,
      Iterator iterator)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a composed connect handler using bind():

void my_class::connect_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}
...
boost::asio::async_connect(...,
    boost::bind(&my_class::connect_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::iterator));

A connect handler must meet the requirements for a handler. A value h of a connect handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a connect handler:

void connect_handler(
    const boost::system::error_code& ec)
{
  ...
}

A connect handler function object:

struct connect_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a connect handler using bind():

void my_class::connect_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
socket.async_connect(...,
    boost::bind(&my_class::connect_handler,
      this, boost::asio::placeholders::error));

In the table below, X denotes a class containing objects of type T, a denotes a value of type X and u denotes an identifier.

Table 7.5. ConstBufferSequence requirements

expression

return type

assertion/note
pre/post-condition

X::value_type

T

T meets the requirements for ConvertibleToConstBuffer.

X::const_iterator

iterator type pointing to T

const_iterator meets the requirements for bidirectional iterators (C++ Std, 24.1.4).

X(a);

post: equal_const_buffer_seq(a, X(a)) where the binary predicate equal_const_buffer_seq is defined as

bool equal_const_buffer_seq(
  const X& x1, const X& x2)
{
  return
    distance(x1.begin(), x1.end())
      == distance(x2.begin(), x2.end())
        && equal(x1.begin(), x1.end(),
                 x2.begin(), equal_buffer);
}

and the binary predicate equal_buffer is defined as

bool equal_buffer(
  const X::value_type& v1,
  const X::value_type& v2)
{
  const_buffer b1(v1);
  const_buffer b2(v2);
  return
    buffer_cast<const void*>(b1)
      == buffer_cast<const void*>(b2)
        && buffer_size(b1) == buffer_size(b2);
}

X u(a);

post:

distance(a.begin(), a.end())
  == distance(u.begin(), u.end())
    && equal(a.begin(), a.end(),
             u.begin(), equal_buffer)

where the binary predicate equal_buffer is defined as

bool equal_buffer(
  const X::value_type& v1,
  const X::value_type& v2)
{
  const_buffer b1(v1);
  const_buffer b2(v2);
  return
    buffer_cast<const void*>(b1)
      == buffer_cast<const void*>(b2)
        && buffer_size(b1) == buffer_size(b2);
}

(&a)->~X();

void

note: the destructor is applied to every element of a; all the memory is deallocated.

a.begin();

const_iterator or convertible to const_iterator

a.end();

const_iterator or convertible to const_iterator


A type that meets the requirements for convertibility to a const buffer must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a class meeting the requirements for convertibility to a const buffer, a and b denote values of type X, and u, v and w denote identifiers.

Table 7.6. ConvertibleToConstBuffer requirements

expression

postcondition

const_buffer u(a);
const_buffer v(a);

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const_buffer v = a;

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const_buffer v; v = a;

buffer_cast<const void*>(u) == buffer_cast<const void*>(v)
  && buffer_size(u) == buffer_size(v)

const_buffer u(a);
const X& v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v(a);
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)

const_buffer u(a);
X v(b); v = a;
const_buffer w(v);

buffer_cast<const void*>(u) == buffer_cast<const void*>(w)
  && buffer_size(u) == buffer_size(w)


A type that meets the requirements for convertibility to a mutable buffer must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a class meeting the requirements for convertibility to a mutable buffer, a and b denote values of type X, and u, v and w denote identifiers.

Table 7.7. ConvertibleToMutableBuffer requirements

expression

postcondition

mutable_buffer u(a);
mutable_buffer v(a);

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
mutable_buffer v = a;

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
mutable_buffer v; v = a;

buffer_cast<void*>(u) == buffer_cast<void*>(v)
  && buffer_size(u) == buffer_size(v)

mutable_buffer u(a);
const X& v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v(a);
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)

mutable_buffer u(a);
X v(b); v = a;
mutable_buffer w(v);

buffer_cast<void*>(u) == buffer_cast<void*>(w)
  && buffer_size(u) == buffer_size(w)


A datagram socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a datagram socket service class for protocol Protocol, a denotes a value of type X, b denotes a value of type X::implementation_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.8. DatagramSocketService requirements

expression

return type

assertion/note
pre/post-condition

a.receive(b, mb, f, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a connected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0.

a.async_receive(b, mb, f, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.receive_from(b, mb, e, f, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from an unconnected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0.

a.async_receive_from(b, mb, e, f, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from an unconnected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

The program must ensure the object e is valid until the handler for the asynchronous operation is invoked.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.send(b, cb, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a connected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0.

a.async_send(b, cb, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

const typename Protocol::endpoint& u = e;
a.send_to(b, cb, u, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to an unconnected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0.

const typename Protocol::endpoint& u = e;
a.async_send(b, cb, u, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to an unconnected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A descriptor service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a descriptor service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, i denotes a value meeting IoControlCommand requirements, and u and v denote identifiers.

Table 7.9. DescriptorService requirements

expression

return type

assertion/note
pre/post-condition

X::native_handle_type

The implementation-defined native representation of a descriptor. Must satisfy the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

a.construct(b);

From IoObjectService requirements.
post: !a.is_open(b).

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling a.close(b, ec).

a.move_construct(b, c);

From IoObjectService requirements. The underlying native representation is moved from c to b.

a.move_assign(b, ao, c);

From IoObjectService requirements. Implicitly cancels asynchronous operations associated with b, as if by calling a.close(b, ec). Then the underlying native representation is moved from c to b.

a.assign(b, n, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.is_open(b);

bool

const X& u = a;
const X::implementation_type& v = b;
u.is_open(v);

bool

a.close(b, ec);

error_code

If a.is_open() is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.
post: !a.is_open(b).

a.native_handle(b);

X::native_handle_type

a.cancel(b, ec);

error_code

pre: a.is_open(b).
Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.

a.io_control(b, i, ec);

error_code

pre: a.is_open(b).


An endpoint must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes an endpoint class, a denotes a value of type X, s denotes a size in bytes, and u denotes an identifier.

Table 7.10. Endpoint requirements

expression

type

assertion/note
pre/post-conditions

X::protocol_type

type meeting protocol requirements

X u;

X();

a.protocol();

protocol_type

a.data();

a pointer

Returns a pointer suitable for passing as the address argument to POSIX functions such as accept(), getpeername(), getsockname() and recvfrom(). The implementation shall perform a reinterpret_cast on the pointer to convert it to sockaddr*.

const X& u = a; u.data();

a pointer

Returns a pointer suitable for passing as the address argument to POSIX functions such as connect(), or as the dest_addr argument to POSIX functions such as sendto(). The implementation shall perform a reinterpret_cast on the pointer to convert it to const sockaddr*.

a.size();

size_t

Returns a value suitable for passing as the address_len argument to POSIX functions such as connect(), or as the dest_len argument to POSIX functions such as sendto(), after appropriate integer conversion has been performed.

a.resize(s);

post: a.size() == s
Passed the value contained in the address_len argument to POSIX functions such as accept(), getpeername(), getsockname() and recvfrom(), after successful completion of the function. Permitted to throw an exception if the protocol associated with the endpoint object a does not support the specified size.

a.capacity();

size_t

Returns a value suitable for passing as the address_len argument to POSIX functions such as accept(), getpeername(), getsockname() and recvfrom(), after appropriate integer conversion has been performed.


In the table below, X denotes a serial port option class, a denotes a value of X, ec denotes a value of type error_code, and s denotes a value of implementation-defined type storage (where storage is the type DCB on Windows and termios on POSIX platforms), and u denotes an identifier.

Table 7.11. GettableSerialPortOption requirements

expression

type

assertion/note
pre/post-conditions

const storage& u = s;
a.load(u, ec);

error_code

Retrieves the value of the serial port option from the storage.

If successful, sets ec such that !ec is true. If an error occurred, sets ec such that !!ec is true. Returns ec.


In the table below, X denotes a socket option class, a denotes a value of X, p denotes a value that meets the protocol requirements, and u denotes an identifier.

Table 7.12. GettableSocketOption requirements

expression

type

assertion/note
pre/post-conditions

a.level(p);

int

Returns a value suitable for passing as the level argument to POSIX getsockopt() (or equivalent).

a.name(p);

int

Returns a value suitable for passing as the option_name argument to POSIX getsockopt() (or equivalent).

a.data(p);

a pointer, convertible to void*

Returns a pointer suitable for passing as the option_value argument to POSIX getsockopt() (or equivalent).

a.size(p);

size_t

Returns a value suitable for passing as the option_len argument to POSIX getsockopt() (or equivalent), after appropriate integer conversion has been performed.

a.resize(p, s);

post: a.size(p) == s.
Passed the value contained in the option_len argument to POSIX getsockopt() (or equivalent) after successful completion of the function. Permitted to throw an exception if the socket option object a does not support the specified size.


A handler must meet the requirements of CopyConstructible types (C++ Std, 20.1.3).

In the table below, X denotes a handler class, h denotes a value of X, p denotes a pointer to a block of allocated memory of type void*, s denotes the size for a block of allocated memory, and f denotes a function object taking no arguments.

Table 7.13. Handler requirements

expression

return type

assertion/note
pre/post-conditions

using boost::asio::asio_handler_allocate;
asio_handler_allocate(s, &h);

void*

Returns a pointer to a block of memory of size s. The pointer must satisfy the same alignment requirements as a pointer returned by ::operator new(). Throws bad_alloc on failure.

The asio_handler_allocate() function is located using argument-dependent lookup. The function boost::asio::asio_handler_allocate() serves as a default if no user-supplied function is available.

using boost::asio::asio_handler_deallocate;
asio_handler_deallocate(p, s, &h);

Frees a block of memory associated with a pointer p, of at least size s, that was previously allocated using asio_handler_allocate().

The asio_handler_deallocate() function is located using argument-dependent lookup. The function boost::asio::asio_handler_deallocate() serves as a default if no user-supplied function is available.

using boost::asio::asio_handler_invoke;
asio_handler_invoke(f, &h);

Causes the function object f to be executed as if by calling f().

The asio_handler_invoke() function is located using argument-dependent lookup. The function boost::asio::asio_handler_invoke() serves as a default if no user-supplied function is available.


A handle service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a handle service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, and u and v denote identifiers.

Table 7.14. HandleService requirements

expression

return type

assertion/note
pre/post-condition

X::native_handle_type

The implementation-defined native representation of a handle. Must satisfy the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

a.construct(b);

From IoObjectService requirements.
post: !a.is_open(b).

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling a.close(b, ec).

a.move_construct(b, c);

From IoObjectService requirements. The underlying native representation is moved from c to b.

a.move_assign(b, ao, c);

From IoObjectService requirements. Implicitly cancels asynchronous operations associated with b, as if by calling a.close(b, ec). Then the underlying native representation is moved from c to b.

a.assign(b, n, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.is_open(b);

bool

const X& u = a;
const X::implementation_type& v = b;
u.is_open(v);

bool

a.close(b, ec);

error_code

If a.is_open() is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.
post: !a.is_open(b).

a.native_handle(b);

X::native_handle_type

a.cancel(b, ec);

error_code

pre: a.is_open(b).
Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.


A handshake handler must meet the requirements for a handler. A value h of a handshake handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a handshake handler:

void handshake_handler(
    const boost::system::error_code& ec)
{
  ...
}

A handshake handler function object:

struct handshake_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a handshake handler using bind():

void my_class::handshake_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
ssl_stream.async_handshake(...,
    boost::bind(&my_class::handshake_handler,
      this, boost::asio::placeholders::error));

An internet protocol must meet the requirements for a protocol as well as the additional requirements listed below.

In the table below, X denotes an internet protocol class, a denotes a value of type X, and b denotes a value of type X.

Table 7.15. InternetProtocol requirements

expression

return type

assertion/note
pre/post-conditions

X::resolver

ip::basic_resolver<X>

The type of a resolver for the protocol.

X::v4()

X

Returns an object representing the IP version 4 protocol.

X::v6()

X

Returns an object representing the IP version 6 protocol.

a == b

convertible to bool

Returns whether two protocol objects are equal.

a != b

convertible to bool

Returns !(a == b).


In the table below, X denotes an I/O control command class, a denotes a value of X, and u denotes an identifier.

Table 7.16. IoControlCommand requirements

expression

type

assertion/note
pre/post-conditions

a.name();

int

Returns a value suitable for passing as the request argument to POSIX ioctl() (or equivalent).

a.data();

a pointer, convertible to void*


An I/O object service must meet the requirements for a service, as well as the requirements listed below.

In the table below, X denotes an I/O object service class, a and ao denote values of type X, b and c denote values of type X::implementation_type, and u denotes an identifier.

Table 7.17. IoObjectService requirements

expression

return type

assertion/note
pre/post-condition

X::implementation_type

X::implementation_type u;

note: X::implementation_type has a public default constructor and destructor.

a.construct(b);

a.destroy(b);

note: destroy() will only be called on a value that has previously been initialised with construct() or move_construct().

a.move_construct(b, c);

note: only required for I/O objects that support movability.

a.move_assign(b, ao, c);

note: only required for I/O objects that support movability.


In the table below, X denotes a class containing objects of type T, a denotes a value of type X and u denotes an identifier.

Table 7.18. MutableBufferSequence requirements

expression

return type

assertion/note
pre/post-condition

X::value_type

T

T meets the requirements for ConvertibleToMutableBuffer.

X::const_iterator

iterator type pointing to T

const_iterator meets the requirements for bidirectional iterators (C++ Std, 24.1.4).

X(a);

post: equal_mutable_buffer_seq(a, X(a)) where the binary predicate equal_mutable_buffer_seq is defined as

bool equal_mutable_buffer_seq(
  const X& x1, const X& x2)
{
  return
    distance(x1.begin(), x1.end())
      == distance(x2.begin(), x2.end())
        && equal(x1.begin(), x1.end(),
                 x2.begin(), equal_buffer);
}

and the binary predicate equal_buffer is defined as

bool equal_buffer(
  const X::value_type& v1,
  const X::value_type& v2)
{
  mutable_buffer b1(v1);
  mutable_buffer b2(v2);
  return
    buffer_cast<const void*>(b1)
      == buffer_cast<const void*>(b2)
        && buffer_size(b1) == buffer_size(b2);
}

X u(a);

post:

distance(a.begin(), a.end())
  == distance(u.begin(), u.end())
    && equal(a.begin(), a.end(),
             u.begin(), equal_buffer)

where the binary predicate equal_buffer is defined as

bool equal_buffer(
  const X::value_type& v1,
  const X::value_type& v2)
{
  mutable_buffer b1(v1);
  mutable_buffer b2(v2);
  return
    buffer_cast<const void*>(b1)
      == buffer_cast<const void*>(b2)
        && buffer_size(b1) == buffer_size(b2);
}

(&a)->~X();

void

note: the destructor is applied to every element of a; all the memory is deallocated.

a.begin();

const_iterator or convertible to const_iterator

a.end();

const_iterator or convertible to const_iterator


An object handle service must meet the requirements for a handle service, as well as the additional requirements listed below.

In the table below, X denotes an object handle service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, and wh denotes a value meeting WaitHandler requirements.

Table 7.19. ObjectHandleService requirements

expression

return type

assertion/note
pre/post-condition

a.wait(b, ec);

error_code

pre: a.is_open(b).

Synchronously waits for the object represented by handle b to become signalled.

a.async_wait(b, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to wait for the object represented by handle b to become signalled. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.


A protocol must meet the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

In the table below, X denotes a protocol class, and a denotes a value of X.

Table 7.20. Protocol requirements

expression

return type

assertion/note
pre/post-conditions

X::endpoint

type meeting endpoint requirements

a.family()

int

Returns a value suitable for passing as the domain argument to POSIX socket() (or equivalent).

a.type()

int

Returns a value suitable for passing as the type argument to POSIX socket() (or equivalent).

a.protocol()

int

Returns a value suitable for passing as the protocol argument to POSIX socket() (or equivalent).


A random access handle service must meet the requirements for a handle service, as well as the additional requirements listed below.

In the table below, X denotes a random access handle service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, o denotes an offset of type boost::uint64_t, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.21. RandomAccessHandleService requirements

expression

return type

assertion/note
pre/post-condition

a.read_some_at(b, o, mb, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a handle b at offset o.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0. If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

a.async_read_some_at(b, o, mb, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a handle b at offset o. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.write_some_at(b, o, cb, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a handle b at offset o.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0. If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

a.async_write_some_at(b, o, cb, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a handle b at offset o. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence cb is 0, the asynchronous operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A raw socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a raw socket service class for protocol Protocol, a denotes a value of type X, b denotes a value of type X::implementation_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.22. RawSocketService requirements

expression

return type

assertion/note
pre/post-condition

a.receive(b, mb, f, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a connected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0.

a.async_receive(b, mb, f, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.receive_from(b, mb, e, f, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from an unconnected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0.

a.async_receive_from(b, mb, e, f, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from an unconnected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

The program must ensure the object e is valid until the handler for the asynchronous operation is invoked.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.send(b, cb, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a connected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0.

a.async_send(b, cb, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

const typename Protocol::endpoint& u = e;
a.send_to(b, cb, u, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to an unconnected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0.

const typename Protocol::endpoint& u = e;
a.async_send(b, cb, u, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to an unconnected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A read handler must meet the requirements for a handler. A value h of a read handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a read handler:

void read_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A read handler function object:

struct read_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a read handler using bind():

void my_class::read_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_read(...,
    boost::bind(&my_class::read_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

A resolve handler must meet the requirements for a handler. A value h of a resolve handler class should work correctly in the expression h(ec, i), where ec is an lvalue of type const error_code and i is an lvalue of type const ip::basic_resolver_iterator<InternetProtocol>. InternetProtocol is the template parameter of the resolver_service which is used to initiate the asynchronous operation.

Examples

A free function as a resolve handler:

void resolve_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}

A resolve handler function object:

struct resolve_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      boost::asio::ip::tcp::resolver::iterator iterator)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a resolve handler using bind():

void my_class::resolve_handler(
    const boost::system::error_code& ec,
    boost::asio::ip::tcp::resolver::iterator iterator)
{
  ...
}
...
resolver.async_resolve(...,
    boost::bind(&my_class::resolve_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::iterator));

A resolver service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a resolver service class for protocol InternetProtocol, a denotes a value of type X, b denotes a value of type X::implementation_type, q denotes a value of type ip::basic_resolver_query<InternetProtocol>, e denotes a value of type ip::basic_endpoint<InternetProtocol>, ec denotes a value of type error_code, and h denotes a value meeting ResolveHandler requirements.

Table 7.23. ResolverService requirements

expression

return type

assertion/note
pre/post-condition

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous resolve operations, as if by calling a.cancel(b, ec).

a.cancel(b, ec);

error_code

Causes any outstanding asynchronous resolve operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.

a.resolve(b, q, ec);

ip::basic_resolver_iterator<
  InternetProtocol>

On success, returns an iterator i such that i != ip::basic_resolver_iterator<InternetProtocol>(). Otherwise returns ip::basic_resolver_iterator<InternetProtocol>().

a.async_resolve(b, q, h);

Initiates an asynchronous resolve operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

If the operation completes successfully, the ResolveHandler object h shall be invoked with an iterator object i such that the condition i != ip::basic_resolver_iterator<InternetProtocol>() holds. Otherwise it is invoked with ip::basic_resolver_iterator<InternetProtocol>().

a.resolve(b, e, ec);

ip::basic_resolver_iterator<
  InternetProtocol>

On success, returns an iterator i such that i != ip::basic_resolver_iterator<InternetProtocol>(). Otherwise returns ip::basic_resolver_iterator<InternetProtocol>().

a.async_resolve(b, e, h);

Initiates an asynchronous resolve operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

If the operation completes successfully, the ResolveHandler object h shall be invoked with an iterator object i such that the condition i != ip::basic_resolver_iterator<InternetProtocol>() holds. Otherwise it is invoked with ip::basic_resolver_iterator<InternetProtocol>().


A sequenced packet socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a stream socket service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, g denotes an lvalue of type socket_base::message_flags, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.24. StreamSocketService requirements

expression

return type

assertion/note
pre/post-condition

a.receive(b, mb, f, g, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a connected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, sets g to the flags associated with the received data, and returns the number of bytes read. Otherwise, sets g to 0 and returns 0.

a.async_receive(b, mb, f, g, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, sets g to the flags associated with the received data, then invokes the ReadHandler object rh with the number of bytes transferred. Otherwise, sets g to 0 and invokes rh with 0 bytes transferred.

a.send(b, cb, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a connected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0.

a.async_send(b, cb, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A serial port service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a serial port service class, a and ao denote values of type X, d denotes a serial port device name of type std::string, b and c denote values of type X::implementation_type, n denotes a value of type X::native_handle_type, ec denotes a value of type error_code, s denotes a value meeting SettableSerialPortOption requirements, g denotes a value meeting GettableSerialPortOption requirements, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements. and u and v denote identifiers.

Table 7.25. SerialPortService requirements

expression

return type

assertion/note
pre/post-condition

X::native_handle_type

The implementation-defined native representation of a serial port. Must satisfy the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

a.construct(b);

From IoObjectService requirements.
post: !a.is_open(b).

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling a.close(b, ec).

a.move_construct(b, c);

From IoObjectService requirements. The underlying native representation is moved from c to b.

a.move_assign(b, ao, c);

From IoObjectService requirements. Implicitly cancels asynchronous operations associated with b, as if by calling a.close(b, ec). Then the underlying native representation is moved from c to b.

const std::string& u = d;
a.open(b, u, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.assign(b, n, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.is_open(b);

bool

const X& u = a;
const X::implementation_type& v = b;
u.is_open(v);

bool

a.close(b, ec);

error_code

If a.is_open() is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.
post: !a.is_open(b).

a.native_handle(b);

X::native_handle_type

a.cancel(b, ec);

error_code

pre: a.is_open(b).
Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.

a.set_option(b, s, ec);

error_code

pre: a.is_open(b).

a.get_option(b, g, ec);

error_code

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.get_option(v, g, ec);

error_code

pre: a.is_open(b).

a.send_break(b, ec);

error_code

pre: a.is_open(b).

a.read_some(b, mb, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a serial port b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0. If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

a.async_read_some(b, mb, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a serial port b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.write_some(b, cb, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a serial port b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0. If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

a.async_write_some(b, cb, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a serial port b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence cb is 0, the asynchronous operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A class is a service if it is publicly derived from another service, or if it is a class derived from io_service::service and contains a publicly-accessible declaration as follows:

static io_service::id id;

All services define a one-argument constructor that takes a reference to the io_service object that owns the service. This constructor is explicit, preventing its participation in automatic conversions. For example:

class my_service : public io_service::service
{
public:
  static io_service::id id;
  explicit my_service(io_service& ios);
private:
  virtual void shutdown_service();
  ...
};

A service's shutdown_service member function must cause all copies of user-defined handler objects that are held by the service to be destroyed.

In the table below, X denotes a serial port option class, a denotes a value of X, ec denotes a value of type error_code, and s denotes a value of implementation-defined type storage (where storage is the type DCB on Windows and termios on POSIX platforms), and u denotes an identifier.

Table 7.26. SettableSerialPortOption requirements

expression

type

assertion/note
pre/post-conditions

const X& u = a;
u.store(s, ec);

error_code

Saves the value of the serial port option to the storage.

If successful, sets ec such that !ec is true. If an error occurred, sets ec such that !!ec is true. Returns ec.


In the table below, X denotes a socket option class, a denotes a value of X, p denotes a value that meets the protocol requirements, and u denotes an identifier.

Table 7.27. SettableSocketOption requirements

expression

type

assertion/note
pre/post-conditions

a.level(p);

int

Returns a value suitable for passing as the level argument to POSIX setsockopt() (or equivalent).

a.name(p);

int

Returns a value suitable for passing as the option_name argument to POSIX setsockopt() (or equivalent).

const X& u = a; u.data(p);

a pointer, convertible to const void*

Returns a pointer suitable for passing as the option_value argument to POSIX setsockopt() (or equivalent).

a.size(p);

size_t

Returns a value suitable for passing as the option_len argument to POSIX setsockopt() (or equivalent), after appropriate integer conversion has been performed.


A shutdown handler must meet the requirements for a handler. A value h of a shutdown handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a shutdown handler:

void shutdown_handler(
    const boost::system::error_code& ec)
{
  ...
}

A shutdown handler function object:

struct shutdown_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a shutdown handler using bind():

void my_class::shutdown_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
ssl_stream.async_shutdown(
    boost::bind(&my_class::shutdown_handler,
      this, boost::asio::placeholders::error));

A signal handler must meet the requirements for a handler. A value h of a signal handler class should work correctly in the expression h(ec, n), where ec is an lvalue of type const error_code and n is an lvalue of type const int.

Examples

A free function as a signal handler:

void signal_handler(
    const boost::system::error_code& ec,
    int signal_number)
{
  ...
}

A signal handler function object:

struct signal_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      int signal_number)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a signal handler using bind():

void my_class::signal_handler(
    const boost::system::error_code& ec,
    int signal_number)
{
  ...
}
...
my_signal_set.async_wait(
    boost::bind(&my_class::signal_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::signal_number));

A signal set service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a signal set service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, n denotes a value of type int, and sh denotes a value meeting SignalHandler requirements.

Table 7.28. SignalSetService requirements

expression

return type

assertion/note
pre/post-condition

a.construct(b);

From IoObjectService requirements.

a.destroy(b);

From IoObjectService requirements. Implicitly clears the registered signals as if by calling a.clear(b, ec), then implicitly cancels outstanding asynchronous operations as if by calling a.cancel(b, ec).

a.add(b, n, ec);

error_code

a.remove(b, n, ec);

error_code

a.clear(b, ec);

error_code

a.cancel(b, ec);

error_code

a.async_wait(b, sh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to wait for the delivery of one of the signals registered for the signal set b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

If the operation completes successfully, the SignalHandler object sh is invoked with the number identifying the delivered signal. Otherwise it is invoked with 0.


A socket acceptor service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a socket acceptor service class for protocol Protocol, a and ao denote values of type X, b and c denote values of type X::implementation_type, p denotes a value of type Protocol, n denotes a value of type X::native_handle_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, s denotes a value meeting SettableSocketOption requirements, g denotes a value meeting GettableSocketOption requirements, i denotes a value meeting IoControlCommand requirements, k denotes a value of type basic_socket<Protocol, SocketService> where SocketService is a type meeting socket service requirements, ah denotes a value meeting AcceptHandler requirements, and u and v denote identifiers.

Table 7.29. SocketAcceptorService requirements

expression

return type

assertion/note
pre/post-condition

X::native_handle_type

The implementation-defined native representation of a socket acceptor. Must satisfy the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

a.construct(b);

From IoObjectService requirements.
post: !a.is_open(b).

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling a.close(b, ec).

a.move_construct(b, c);

From IoObjectService requirements. The underlying native representation is moved from c to b.

a.move_assign(b, ao, c);

From IoObjectService requirements. Implicitly cancels asynchronous operations associated with b, as if by calling a.close(b, ec). Then the underlying native representation is moved from c to b.

a.open(b, p, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.assign(b, p, n, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.is_open(b);

bool

const X& u = a;
const X::implementation_type& v = b;
u.is_open(v);

bool

a.close(b, ec);

error_code

If a.is_open() is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.
post: !a.is_open(b).

a.native_handle(b);

X::native_handle_type

a.cancel(b, ec);

error_code

pre: a.is_open(b).
Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.

a.set_option(b, s, ec);

error_code

pre: a.is_open(b).

a.get_option(b, g, ec);

error_code

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.get_option(v, g, ec);

error_code

pre: a.is_open(b).

a.io_control(b, i, ec);

error_code

pre: a.is_open(b).

const typename Protocol::endpoint& u = e;
a.bind(b, u, ec);

error_code

pre: a.is_open(b).

a.local_endpoint(b, ec);

Protocol::endpoint

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.local_endpoint(v, ec);

Protocol::endpoint

pre: a.is_open(b).

a.accept(b, k, &e, ec);

error_code

pre: a.is_open(b) && !k.is_open().
post: k.is_open()

a.accept(b, k, 0, ec);

error_code

pre: a.is_open(b) && !k.is_open().
post: k.is_open()

a.async_accept(b, k, &e, ah);

pre: a.is_open(b) && !k.is_open().
Initiates an asynchronous accept operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The program must ensure the objects k and e are valid until the handler for the asynchronous operation is invoked.

a.async_accept(b, k, 0, ah);

pre: a.is_open(b) && !k.is_open().
Initiates an asynchronous accept operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The program must ensure the object k is valid until the handler for the asynchronous operation is invoked.


A socket service must meet the requirements for an I/O object service with support for movability, as well as the additional requirements listed below.

In the table below, X denotes a socket service class for protocol Protocol, a and ao denote values of type X, b and c denote values of type X::implementation_type, p denotes a value of type Protocol, n denotes a value of type X::native_handle_type, e denotes a value of type Protocol::endpoint, ec denotes a value of type error_code, s denotes a value meeting SettableSocketOption requirements, g denotes a value meeting GettableSocketOption requirements, i denotes a value meeting IoControlCommand requirements, h denotes a value of type socket_base::shutdown_type, ch denotes a value meeting ConnectHandler requirements, and u and v denote identifiers.

Table 7.30. SocketService requirements

expression

return type

assertion/note
pre/post-condition

X::native_handle_type

The implementation-defined native representation of a socket. Must satisfy the requirements of CopyConstructible types (C++ Std, 20.1.3), and the requirements of Assignable types (C++ Std, 23.1).

a.construct(b);

From IoObjectService requirements.
post: !a.is_open(b).

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous operations, as if by calling a.close(b, ec).

a.move_construct(b, c);

From IoObjectService requirements. The underlying native representation is moved from c to b.

a.move_assign(b, ao, c);

From IoObjectService requirements. Implicitly cancels asynchronous operations associated with b, as if by calling a.close(b, ec). Then the underlying native representation is moved from c to b.

a.open(b, p, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.assign(b, p, n, ec);

error_code

pre: !a.is_open(b).
post: !!ec || a.is_open(b).

a.is_open(b);

bool

const X& u = a;
const X::implementation_type& v = b;
u.is_open(v);

bool

a.close(b, ec);

error_code

If a.is_open() is true, causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.
post: !a.is_open(b).

a.native_handle(b);

X::native_handle_type

a.cancel(b, ec);

error_code

pre: a.is_open(b).
Causes any outstanding asynchronous operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted.

a.set_option(b, s, ec);

error_code

pre: a.is_open(b).

a.get_option(b, g, ec);

error_code

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.get_option(v, g, ec);

error_code

pre: a.is_open(b).

a.io_control(b, i, ec);

error_code

pre: a.is_open(b).

a.at_mark(b, ec);

bool

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.at_mark(v, ec);

bool

pre: a.is_open(b).

a.available(b, ec);

size_t

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.available(v, ec);

size_t

pre: a.is_open(b).

const typename Protocol::endpoint& u = e;
a.bind(b, u, ec);

error_code

pre: a.is_open(b).

a.shutdown(b, h, ec);

error_code

pre: a.is_open(b).

a.local_endpoint(b, ec);

Protocol::endpoint

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.local_endpoint(v, ec);

Protocol::endpoint

pre: a.is_open(b).

a.remote_endpoint(b, ec);

Protocol::endpoint

pre: a.is_open(b).

const X& u = a;
const X::implementation_type& v = b;
u.remote_endpoint(v, ec);

Protocol::endpoint

pre: a.is_open(b).

const typename Protocol::endpoint& u = e;
a.connect(b, u, ec);

error_code

pre: a.is_open(b).

const typename Protocol::endpoint& u = e;
a.async_connect(b, u, ch);

pre: a.is_open(b).
Initiates an asynchronous connect operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.


A stream descriptor service must meet the requirements for a descriptor service, as well as the additional requirements listed below.

In the table below, X denotes a stream descriptor service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.31. StreamDescriptorService requirements

expression

return type

assertion/note
pre/post-condition

a.read_some(b, mb, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a descriptor b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0. If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

a.async_read_some(b, mb, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a descriptor b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.write_some(b, cb, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a descriptor b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0. If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

a.async_write_some(b, cb, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a descriptor b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence cb is 0, the asynchronous operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A stream handle service must meet the requirements for a handle service, as well as the additional requirements listed below.

In the table below, X denotes a stream handle service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.32. StreamHandleService requirements

expression

return type

assertion/note
pre/post-condition

a.read_some(b, mb, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a handle b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0. If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

a.async_read_some(b, mb, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a handle b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.write_some(b, cb, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a handle b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0. If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

a.async_write_some(b, cb, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a handle b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence cb is 0, the asynchronous operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


A stream socket service must meet the requirements for a socket service, as well as the additional requirements listed below.

In the table below, X denotes a stream socket service class, a denotes a value of type X, b denotes a value of type X::implementation_type, ec denotes a value of type error_code, f denotes a value of type socket_base::message_flags, mb denotes a value satisfying mutable buffer sequence requirements, rh denotes a value meeting ReadHandler requirements, cb denotes a value satisfying constant buffer sequence requirements, and wh denotes a value meeting WriteHandler requirements.

Table 7.33. StreamSocketService requirements

expression

return type

assertion/note
pre/post-condition

a.receive(b, mb, f, ec);

size_t

pre: a.is_open(b).

Reads one or more bytes of data from a connected socket b.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read. Otherwise returns 0. If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

a.async_receive(b, mb, f, rh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to read one or more bytes of data from a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The mutable buffer sequence mb specifies memory where the data should be placed. The operation shall always fill a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of mb until such time as the read operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of mb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence mb is 0, the asynchronous read operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes due to graceful connection closure by the peer, the operation shall fail with error::eof.

If the operation completes successfully, the ReadHandler object rh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.

a.send(b, cb, f, ec);

size_t

pre: a.is_open(b).

Writes one or more bytes of data to a connected socket b.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written. Otherwise returns 0. If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.

a.async_send(b, cb, f, wh);

void

pre: a.is_open(b).

Initiates an asynchronous operation to write one or more bytes of data to a connected socket b. The operation is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The constant buffer sequence cb specifies memory where the data to be written is located. The operation shall always write a buffer in the sequence completely before proceeding to the next.

The implementation shall maintain one or more copies of cb until such time as the write operation no longer requires access to the memory specified by the buffers in the sequence. The program must ensure the memory is valid until:

— the last copy of cb is destroyed, or

— the handler for the asynchronous operation is invoked,

whichever comes first. If the total size of all buffers in the sequence cb is 0, the asynchronous operation shall complete immediately and pass 0 as the argument to the handler that specifies the number of bytes read.

If the operation completes successfully, the WriteHandler object wh is invoked with the number of bytes transferred. Otherwise it is invoked with 0.


In the table below, a denotes a synchronous random-access read device object, o denotes an offset of type boost::uint64_t, mb denotes an object satisfying mutable buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.34. Buffer-oriented synchronous random-access read device requirements

operation

type

semantics, pre/post-conditions

a.read_some_at(o, mb);

size_t

Equivalent to:

error_code ec;
size_t s = a.read_some_at(o, mb, ec);
if (ec) throw system_error(ec);
return s;

a.read_some_at(o, mb, ec);

size_t

Reads one or more bytes of data from the device a at offset o.

The mutable buffer sequence mb specifies memory where the data should be placed. The read_some_at operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.


In the table below, a denotes a synchronous random-access write device object, o denotes an offset of type boost::uint64_t, cb denotes an object satisfying constant buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.35. Buffer-oriented synchronous random-access write device requirements

operation

type

semantics, pre/post-conditions

a.write_some_at(o, cb);

size_t

Equivalent to:

error_code ec;
size_t s = a.write_some(o, cb, ec);
if (ec) throw system_error(ec);
return s;

a.write_some_at(o, cb, ec);

size_t

Writes one or more bytes of data to the device a at offset o.

The constant buffer sequence cb specifies memory where the data to be written is located. The write_some_at operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.


In the table below, a denotes a synchronous read stream object, mb denotes an object satisfying mutable buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.36. Buffer-oriented synchronous read stream requirements

operation

type

semantics, pre/post-conditions

a.read_some(mb);

size_t

Equivalent to:

error_code ec;
size_t s = a.read_some(mb, ec);
if (ec) throw system_error(ec);
return s;

a.read_some(mb, ec);

size_t

Reads one or more bytes of data from the stream a.

The mutable buffer sequence mb specifies memory where the data should be placed. The read_some operation shall always fill a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes read and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence mb is 0, the function shall return 0 immediately.


In the table below, a denotes a synchronous write stream object, cb denotes an object satisfying constant buffer sequence requirements, and ec denotes an object of type error_code.

Table 7.37. Buffer-oriented synchronous write stream requirements

operation

type

semantics, pre/post-conditions

a.write_some(cb);

size_t

Equivalent to:

error_code ec;
size_t s = a.write_some(cb, ec);
if (ec) throw system_error(ec);
return s;

a.write_some(cb, ec);

size_t

Writes one or more bytes of data to the stream a.

The constant buffer sequence cb specifies memory where the data to be written is located. The write_some operation shall always write a buffer in the sequence completely before proceeding to the next.

If successful, returns the number of bytes written and sets ec such that !ec is true. If an error occurred, returns 0 and sets ec such that !!ec is true.

If the total size of all buffers in the sequence cb is 0, the function shall return 0 immediately.


In the table below, X denotes a time traits class for time type Time, t, t1, and t2 denote values of type Time, and d denotes a value of type X::duration_type.

Table 7.38. TimeTraits requirements

expression

return type

assertion/note
pre/post-condition

X::time_type

Time

Represents an absolute time. Must support default construction, and meet the requirements for CopyConstructible and Assignable.

X::duration_type

Represents the difference between two absolute times. Must support default construction, and meet the requirements for CopyConstructible and Assignable. A duration can be positive, negative, or zero.

X::now();

time_type

Returns the current time.

X::add(t, d);

time_type

Returns a new absolute time resulting from adding the duration d to the absolute time t.

X::subtract(t1, t2);

duration_type

Returns the duration resulting from subtracting t2 from t1.

X::less_than(t1, t2);

bool

Returns whether t1 is to be treated as less than t2.

X::to_posix_duration(d);

date_time::time_duration_type

Returns the date_time::time_duration_type value that most closely represents the duration d.


A timer service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a timer service class for time type Time and traits type TimeTraits, a denotes a value of type X, b denotes a value of type X::implementation_type, t denotes a value of type Time, d denotes a value of type TimeTraits::duration_type, e denotes a value of type error_code, and h denotes a value meeting WaitHandler requirements.

Table 7.39. TimerService requirements

expression

return type

assertion/note
pre/post-condition

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous wait operations, as if by calling a.cancel(b, e).

a.cancel(b, e);

size_t

Causes any outstanding asynchronous wait operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted. Sets e to indicate success or failure. Returns the number of operations that were cancelled.

a.expires_at(b);

Time

a.expires_at(b, t, e);

size_t

Implicitly cancels asynchronous wait operations, as if by calling a.cancel(b, e). Returns the number of operations that were cancelled.
post: a.expires_at(b) == t.

a.expires_from_now(b);

TimeTraits::duration_type

Returns a value equivalent to TimeTraits::subtract(a.expires_at(b), TimeTraits::now()).

a.expires_from_now(b, d, e);

size_t

Equivalent to a.expires_at(b, TimeTraits::add(TimeTraits::now(), d), e).

a.wait(b, e);

error_code

Sets e to indicate success or failure. Returns e.
post: !!e || !TimeTraits::lt(TimeTraits::now(), a.expires_at(b)).

a.async_wait(b, h);

Initiates an asynchronous wait operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The handler shall be posted for execution only if the condition !!ec || !TimeTraits::lt(TimeTraits::now(), a.expires_at(b)) holds, where ec is the error code to be passed to the handler.


A waitable timer service must meet the requirements for an I/O object service, as well as the additional requirements listed below.

In the table below, X denotes a waitable timer service class for clock type Clock, where Clock meets the C++11 clock type requirements, a denotes a value of type X, b denotes a value of type X::implementation_type, t denotes a value of type Clock::time_point, d denotes a value of type Clock::duration, e denotes a value of type error_code, and h denotes a value meeting WaitHandler requirements.

Table 7.40. WaitableTimerService requirements

expression

return type

assertion/note
pre/post-condition

a.destroy(b);

From IoObjectService requirements. Implicitly cancels asynchronous wait operations, as if by calling a.cancel(b, e).

a.cancel(b, e);

size_t

Causes any outstanding asynchronous wait operations to complete as soon as possible. Handlers for cancelled operations shall be passed the error code error::operation_aborted. Sets e to indicate success or failure. Returns the number of operations that were cancelled.

a.expires_at(b);

Clock::time_point

a.expires_at(b, t, e);

size_t

Implicitly cancels asynchronous wait operations, as if by calling a.cancel(b, e). Returns the number of operations that were cancelled.
post: a.expires_at(b) == t.

a.expires_from_now(b);

Clock::duration

Returns a value equivalent to a.expires_at(b) - Clock::now().

a.expires_from_now(b, d, e);

size_t

Equivalent to a.expires_at(b, Clock::now() + d, e).

a.wait(b, e);

error_code

Sets e to indicate success or failure. Returns e.
post: !!e || !(Clock::now() < a.expires_at(b)).

a.async_wait(b, h);

Initiates an asynchronous wait operation that is performed via the io_service object a.get_io_service() and behaves according to asynchronous operation requirements.

The handler shall be posted for execution only if the condition !!ec || !(Clock::now() < a.expires_at(b)) holds, where ec is the error code to be passed to the handler.


A wait handler must meet the requirements for a handler. A value h of a wait handler class should work correctly in the expression h(ec), where ec is an lvalue of type const error_code.

Examples

A free function as a wait handler:

void wait_handler(
    const boost::system::error_code& ec)
{
  ...
}

A wait handler function object:

struct wait_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a wait handler using bind():

void my_class::wait_handler(
    const boost::system::error_code& ec)
{
  ...
}
...
socket.async_wait(...,
    boost::bind(&my_class::wait_handler,
      this, boost::asio::placeholders::error));

In the table below, X denotes a wait traits class for clock type Clock, where Clock meets the C++11 type requirements for a clock, and d denotes a value of type Clock::duration.

Table 7.41. WaitTraits requirements

expression

return type

assertion/note
pre/post-condition

X::to_wait_duration(d);

Clock::duration

Returns the maximum duration to be used for an individual, implementation-defined wait operation.


A write handler must meet the requirements for a handler. A value h of a write handler class should work correctly in the expression h(ec, s), where ec is an lvalue of type const error_code and s is an lvalue of type const size_t.

Examples

A free function as a write handler:

void write_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}

A write handler function object:

struct write_handler
{
  ...
  void operator()(
      const boost::system::error_code& ec,
      std::size_t bytes_transferred)
  {
    ...
  }
  ...
};

A non-static class member function adapted to a write handler using bind():

void my_class::write_handler(
    const boost::system::error_code& ec,
    std::size_t bytes_transferred)
{
  ...
}
...
socket.async_write(...,
    boost::bind(&my_class::write_handler,
      this, boost::asio::placeholders::error,
      boost::asio::placeholders::bytes_transferred));

template<
    typename Service>
void add_service(
    io_service & ios,
    Service * svc);

This function is used to add a service to the io_service.

Parameters

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<io_service::service*>(svc)

Exceptions

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.

Requirements

Header: boost/asio/io_service.hpp

Convenience header: boost/asio.hpp

Default allocation function for handlers.

void * asio_handler_allocate(
    std::size_t size,
    ... );

Asynchronous operations may need to allocate temporary objects. Since asynchronous operations have a handler function object, these temporary objects can be said to be associated with the handler.

Implement asio_handler_allocate and asio_handler_deallocate for your own handlers to provide custom allocation for these temporary objects.

The default implementation of these allocation hooks uses operator new and operator delete.

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.

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);
}
Requirements

Header: boost/asio/handler_alloc_hook.hpp

Convenience header: boost/asio.hpp

Default deallocation function for handlers.

void asio_handler_deallocate(
    void * pointer,
    std::size_t size,
    ... );

Implement asio_handler_allocate and asio_handler_deallocate for your own handlers to provide custom allocation for the associated temporary objects.

The default implementation of these allocation hooks uses operator new and operator delete.

Requirements

Header: boost/asio/handler_alloc_hook.hpp

Convenience header: boost/asio.hpp

Default invoke function for handlers.

template<
    typename Function>
void asio_handler_invoke(
    Function & function,
    ... );
  » more...

template<
    typename Function>
void asio_handler_invoke(
    const Function & function,
    ... );
  » more...

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 run() on the corresponding io_service object. Handlers may subsequently be invoked through other objects (such as io_service::strand objects) that provide additional guarantees.

When asynchronous operations are composed from other asynchronous operations, all intermediate handlers should be invoked using the same method as the final handler. This is required to ensure that user-defined objects are not accessed in a way that may violate the guarantees. This hooking function ensures that the invoked method used for the final handler is accessible at each intermediate step.

Implement asio_handler_invoke for your own handlers to specify a custom invocation strategy.

This default implementation invokes the function object like so:

function();

If necessary, the default implementation makes a copy of the function object so that the non-const operator() can be used.

Example
class my_handler;

template <typename Function>
void asio_handler_invoke(Function function, my_handler* context)
{
  context->strand_.dispatch(function);
}
Requirements

Header: boost/asio/handler_invoke_hook.hpp

Convenience header: boost/asio.hpp

Default handler invocation hook used for non-const function objects.

template<
    typename Function>
void asio_handler_invoke(
    Function & function,
    ... );

Default handler invocation hook used for const function objects.

template<
    typename Function>
void asio_handler_invoke(
    const Function & function,
    ... );

Default continuation function for handlers.

bool asio_handler_is_continuation(
    ... );

Asynchronous operations may represent a continuation of the asynchronous control flow associated with the current handler. The implementation can use this knowledge to optimise scheduling of the handler.

Implement asio_handler_is_continuation for your own handlers to indicate when a handler represents a continuation.

The default implementation of the continuation hook returns false.

Example
class my_handler;

bool asio_handler_is_continuation(my_handler* context)
{
  return true;
}
Requirements

Header: boost/asio/handler_continuation_hook.hpp

Convenience header: boost/asio.hpp

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);
  » more...

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);
  » more...
Requirements

Header: boost/asio/connect.hpp

Convenience header: boost/asio.hpp

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload assumes that a default constructed object of type Iterator represents the end of the sequence. This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator.

Example
tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    boost::asio::async_connect(s, i, connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  // ...
}

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

end

An iterator pointing to the end of a sequence of endpoints.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example
tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    tcp::resolver::iterator end;
    boost::asio::async_connect(s, i, end, connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  // ...
}

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

connect_condition

A function object that is called prior to each connection attempt. The signature of the function object must be:

Iterator connect_condition(
    const boost::system::error_code& ec,
    Iterator next);

The ec parameter contains the result from the most recent connect operation. Before the first connection attempt, ec is always set to indicate success. The next parameter is an iterator pointing to the next endpoint to be tried. The function object should return the next iterator, but is permitted to return a different iterator so that endpoints may be skipped. The implementation guarantees that the function object will never be called with the end iterator.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Remarks

This overload assumes that a default constructed object of type Iterator represents the end of the sequence. This is a valid assumption for iterator types such as boost::asio::ip::tcp::resolver::iterator.

Example

The following connect condition function object can be used to output information about the individual connection attempts:

struct my_connect_condition
{
  template <typename Iterator>
  Iterator operator()(
      const boost::system::error_code& ec,
      Iterator next)
  {
    if (ec) std::cout << "Error: " << ec.message() << std::endl;
    std::cout << "Trying: " << next->endpoint() << std::endl;
    return next;
  }
};

It would be used with the boost::asio::connect function as follows:

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    boost::asio::async_connect(s, i,
        my_connect_condition(),
        connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (ec)
  {
    // An error occurred.
  }
  else
  {
    std::cout << "Connected to: " << i->endpoint() << std::endl;
  }
}

Asynchronously establishes a socket connection by trying each endpoint in a sequence.

template<
    typename Protocol,
    typename SocketService,
    typename Iterator,
    typename ConnectCondition,
    typename ComposedConnectHandler>
void-or-deduced async_connect(
    basic_socket< Protocol, SocketService > & s,
    Iterator begin,
    Iterator end,
    ConnectCondition connect_condition,
    ComposedConnectHandler handler);

This function attempts to connect a socket to one of a sequence of endpoints. It does this by repeated calls to the socket's async_connect member function, once for each endpoint in the sequence, until a connection is successfully established.

Parameters

s

The socket to be connected. If the socket is already open, it will be closed.

begin

An iterator pointing to the start of a sequence of endpoints.

end

An iterator pointing to the end of a sequence of endpoints.

connect_condition

A function object that is called prior to each connection attempt. The signature of the function object must be:

Iterator connect_condition(
    const boost::system::error_code& ec,
    Iterator next);

The ec parameter contains the result from the most recent connect operation. Before the first connection attempt, ec is always set to indicate success. The next parameter is an iterator pointing to the next endpoint to be tried. The function object should return the next iterator, but is permitted to return a different iterator so that endpoints may be skipped. The implementation guarantees that the function object will never be called with the end iterator.

handler

The handler to be called when the connect operation completes. Copies will be made of the handler as required. The function signature of the handler must be:

void handler(
  // Result of operation. if the sequence is empty, set to
  // boost::asio::error::not_found. Otherwise, contains the
  // error from the last connection attempt.
  const boost::system::error_code& error,

  // On success, an iterator denoting the successfully
  // connected endpoint. Otherwise, the end iterator.
  Iterator iterator
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io_service::post().

Example

The following connect condition function object can be used to output information about the individual connection attempts:

struct my_connect_condition
{
  template <typename Iterator>
  Iterator operator()(
      const boost::system::error_code& ec,
      Iterator next)
  {
    if (ec) std::cout << "Error: " << ec.message() << std::endl;
    std::cout << "Trying: " << next->endpoint() << std::endl;
    return next;
  }
};

It would be used with the boost::asio::connect function as follows:

tcp::resolver r(io_service);
tcp::resolver::query q("host", "service");
tcp::socket s(io_service);

// ...

r.async_resolve(q, resolve_handler);

// ...

void resolve_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (!ec)
  {
    tcp::resolver::iterator end;
    boost::asio::async_connect(s, i, end,
        my_connect_condition(),
        connect_handler);
  }
}

// ...

void connect_handler(
    const boost::system::error_code& ec,
    tcp::resolver::iterator i)
{
  if (ec)
  {
    // An error occurred.
  }
  else
  {
    std::cout << "Connected to: " << i->endpoint() << std::endl;
  }
}

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read(
    AsyncReadStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...
Requirements

Header: boost/asio/read.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced 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, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read(s, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Remarks

This overload is equivalent to calling:

boost::asio::async_read(
    s, buffers,
    boost::asio::transfer_all(),
    handler);

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced 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 0.
Parameters

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().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read(s,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced 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:

  • The supplied buffer is full (that is, it has reached maximum size).
  • An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

Remarks

This overload is equivalent to calling:

boost::asio::async_read(
    s, b,
    boost::asio::transfer_all(),
    handler);

Start an asynchronous operation to read a certain amount of data from a stream.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced 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 supplied buffer is full (that is, it has reached maximum size).
  • The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other read operations (such as async_read, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    const MutableBufferSequence & buffers,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    ReadHandler handler);
  » more...

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    ReadHandler handler);
  » more...
Requirements

Header: boost/asio/read_at.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    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.

Parameters

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().

Example

To read into a single data buffer use the buffer function as follows:

boost::asio::async_read_at(d, 42, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Remarks

This overload is equivalent to calling:

boost::asio::async_read_at(
    d, 42, buffers,
    boost::asio::transfer_all(),
    handler);

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename MutableBufferSequence,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    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 0.
Parameters

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().

Example

To read into a single data buffer use the 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 buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    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.

Parameters

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().

Remarks

This overload is equivalent to calling:

boost::asio::async_read_at(
    d, 42, b,
    boost::asio::transfer_all(),
    handler);

Start an asynchronous operation to read a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessReadDevice,
    typename Allocator,
    typename CompletionCondition,
    typename ReadHandler>
void-or-deduced async_read_at(
    AsyncRandomAccessReadDevice & d,
    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 0.

This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.

Parameters

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().

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 AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    char delim,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const std::string & delim,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    const boost::regex & expr,
    ReadHandler handler);
  » more...

template<
    typename AsyncReadStream,
    typename Allocator,
    typename MatchCondition,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    MatchCondition match_condition,
    ReadHandler handler,
    typename enable_if< is_match_condition< MatchCondition >::value >::type *  = 0);
  » more...
Requirements

Header: boost/asio/read_until.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced 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, and is known as a composed operation. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

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.

Example

To asynchronously read data into a streambuf until a newline is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, '\n', handler);

After the async_read_until operation completes successfully, the buffer b contains the delimiter:

{ 'a', 'b', ..., 'c', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the delimiter, so that the string line contains:

{ 'a', 'b', ..., 'c', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

Start an asynchronous operation to read data into a streambuf until it contains a specified delimiter.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced 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, and is known as a composed operation. If the streambuf's get area already contains the delimiter, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

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.

Example

To asynchronously read data into a streambuf until a newline is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, "\r\n", handler);

After the async_read_until operation completes successfully, the buffer b contains the delimiter:

{ 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the delimiter, so that the string line contains:

{ 'a', 'b', ..., 'c', '\r', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

Start an asynchronous operation to read data into a streambuf until some part of its data matches a regular expression.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename ReadHandler>
void-or-deduced 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, and is known as a composed operation. If the streambuf's get area already contains data that matches the regular expression, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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().

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.

Example

To asynchronously read data into a streambuf until a CR-LF sequence is encountered:

boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
  if (!e)
  {
    std::istream is(&b);
    std::string line;
    std::getline(is, line);
    ...
  }
}
...
boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler);

After the async_read_until operation completes successfully, the buffer b contains the data which matched the regular expression:

{ 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... }

The call to std::getline then extracts the data up to and including the match, so that the string line contains:

{ 'a', 'b', ..., 'c', '\r', '\n' }

The remaining data is left in the buffer b as follows:

{ 'd', 'e', ... }

This data may be the start of a new line, to be extracted by a subsequent async_read_until operation.

Start an asynchronous operation to read data into a streambuf until a function object indicates a match.

template<
    typename AsyncReadStream,
    typename Allocator,
    typename MatchCondition,
    typename ReadHandler>
void-or-deduced async_read_until(
    AsyncReadStream & s,
    boost::asio::basic_streambuf< Allocator > & b,
    MatchCondition match_condition,
    ReadHandler handler,
    typename enable_if< is_match_condition< MatchCondition >::value >::type *  = 0);

This function is used to asynchronously read data into the specified streambuf until a user-defined match condition function object, when applied to the data contained in the streambuf, indicates a successful match. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

  • The match condition function object returns a std::pair where the second element evaluates to true.
  • An error occurred.

This operation is implemented in terms of zero or more calls to the stream's async_read_some function, and is known as a composed operation. If the match condition function object already indicates a match, this asynchronous operation completes immediately. The program must ensure that the stream performs no other read operations (such as async_read, async_read_until, the stream's async_read_some function, or any other composed operations that perform reads) until this operation completes.

Parameters

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<iterator, bool> match_condition(iterator begin, iterator end);

where iterator represents the type:

buffers_iterator<basic_streambuf<Allocator>::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().

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.

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<iterator, bool>
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 <typename Iterator>
  std::pair<Iterator, bool> 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<match_char>
    : 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);

An interface for customising the behaviour of an initiating function.

template<
    typename Handler>
class async_result
Types

Name

Description

type

The return type of the initiating function.

Member Functions

Name

Description

async_result

Construct an async result from a given handler.

get

Obtain the value to be returned from the initiating function.

This template may be specialised for user-defined handler types.

Requirements

Header: boost/asio/async_result.hpp

Convenience header: boost/asio.hpp

Construct an async result from a given handler.

async_result(
    Handler & );

When using a specalised async_result, the constructor has an opportunity to initialise some state associated with the handler, which is then returned from the initiating function.

Obtain the value to be returned from the initiating function.

type get();

The return type of the initiating function.

typedef void type;
Requirements

Header: boost/asio/async_result.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);
  » more...

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...
Requirements

Header: boost/asio/write.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to write all of the supplied data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced 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, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

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().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write(s, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced 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 0.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

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().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write(s,
    boost::asio::buffer(data, size),
    boost::asio::transfer_at_least(32),
    handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to write all of the supplied data to a stream.

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename WriteHandler>
void-or-deduced 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, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

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().

Start an asynchronous operation to write a certain amount of data to a stream.

template<
    typename AsyncWriteStream,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write(
    AsyncWriteStream & s,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);

This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

  • All of the data in the supplied basic_streambuf has been written.
  • The completion_condition function object returns 0.

This operation is implemented in terms of zero or more calls to the stream's async_write_some function, and is known as a composed operation. The program must ensure that the stream performs no other write operations (such as async_write, the stream's async_write_some function, or any other composed operations that perform writes) until this operation completes.

Parameters

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().

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    const ConstBufferSequence & buffers,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    WriteHandler handler);
  » more...

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    uint64_t offset,
    basic_streambuf< Allocator > & b,
    CompletionCondition completion_condition,
    WriteHandler handler);
  » more...
Requirements

Header: boost/asio/write_at.hpp

Convenience header: boost/asio.hpp

Start an asynchronous operation to write all of the supplied data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    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, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

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().

Example

To write a single data buffer use the buffer function as follows:

boost::asio::async_write_at(d, 42, boost::asio::buffer(data, size), handler);

See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename ConstBufferSequence,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    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 0.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

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().

Example

To write a single data buffer use the 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 buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous operation to write all of the supplied data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    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, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

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().

Start an asynchronous operation to write a certain amount of data at the specified offset.

template<
    typename AsyncRandomAccessWriteDevice,
    typename Allocator,
    typename CompletionCondition,
    typename WriteHandler>
void-or-deduced async_write_at(
    AsyncRandomAccessWriteDevice & d,
    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 0.

This operation is implemented in terms of zero or more calls to the device's async_write_some_at function, and is known as a composed operation. The program must ensure that the device performs no overlapping write operations (such as async_write_at, the device's async_write_some_at function, or any other composed operations that perform writes) until this operation completes. Operations are overlapping if the regions defined by their offsets, and the numbers of bytes to write, intersect.

Parameters

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().

basic_datagram_socket::assign
basic_datagram_socket::async_connect
basic_datagram_socket::async_receive
basic_datagram_socket::async_receive_from
basic_datagram_socket::async_send
basic_datagram_socket::async_send_to
basic_datagram_socket::at_mark
basic_datagram_socket::available
basic_datagram_socket::basic_datagram_socket
basic_datagram_socket::bind
basic_datagram_socket::broadcast
basic_datagram_socket::bytes_readable
basic_datagram_socket::cancel
basic_datagram_socket::close
basic_datagram_socket::connect
basic_datagram_socket::debug
basic_datagram_socket::do_not_route
basic_datagram_socket::enable_connection_aborted
basic_datagram_socket::endpoint_type
basic_datagram_socket::get_implementation
basic_datagram_socket::get_io_service
basic_datagram_socket::get_option
basic_datagram_socket::get_service
basic_datagram_socket::implementation
basic_datagram_socket::implementation_type
basic_datagram_socket::io_control
basic_datagram_socket::is_open
basic_datagram_socket::keep_alive
basic_datagram_socket::linger
basic_datagram_socket::local_endpoint
basic_datagram_socket::lowest_layer
basic_datagram_socket::lowest_layer_type
basic_datagram_socket::max_connections
basic_datagram_socket::message_do_not_route
basic_datagram_socket::message_end_of_record
basic_datagram_socket::message_flags
basic_datagram_socket::message_out_of_band
basic_datagram_socket::message_peek
basic_datagram_socket::native
basic_datagram_socket::native_handle
basic_datagram_socket::native_handle_type
basic_datagram_socket::native_non_blocking
basic_datagram_socket::native_type
basic_datagram_socket::non_blocking
basic_datagram_socket::non_blocking_io
basic_datagram_socket::open
basic_datagram_socket::operator=
basic_datagram_socket::protocol_type
basic_datagram_socket::receive
basic_datagram_socket::receive_buffer_size
basic_datagram_socket::receive_from
basic_datagram_socket::receive_low_watermark
basic_datagram_socket::remote_endpoint
basic_datagram_socket::reuse_address
basic_datagram_socket::send
basic_datagram_socket::send_buffer_size
basic_datagram_socket::send_low_watermark
basic_datagram_socket::send_to
basic_datagram_socket::service
basic_datagram_socket::service_type
basic_datagram_socket::set_option
basic_datagram_socket::shutdown
basic_datagram_socket::shutdown_type

Provides datagram-oriented socket functionality.

template<
    typename Protocol,
    typename DatagramSocketService = datagram_socket_service<Protocol>>
class basic_datagram_socket :
  public basic_socket< Protocol, DatagramSocketService >
Types

Name

Description

broadcast

Socket option to permit sending of broadcast messages.

bytes_readable

IO control command to get the amount of data that can be read without blocking.

debug

Socket option to enable socket-level debugging.

do_not_route

Socket option to prevent routing, use local interfaces only.

enable_connection_aborted

Socket option to report aborted connections on accept.

endpoint_type

The endpoint type.

implementation_type

The underlying implementation type of I/O object.

keep_alive

Socket option to send keep-alives.

linger

Socket option to specify whether the socket lingers on close if unsent data is present.

lowest_layer_type

A basic_socket is always the lowest layer.

message_flags

Bitmask type for flags that can be passed to send and receive operations.

native_handle_type

The native representation of a socket.

native_type

(Deprecated: Use native_handle_type.) The native representation of a socket.

non_blocking_io

(Deprecated: Use non_blocking().) IO control command to set the blocking mode of the socket.

protocol_type

The protocol type.

receive_buffer_size

Socket option for the receive buffer size of a socket.

receive_low_watermark

Socket option for the receive low watermark.

reuse_address

Socket option to allow the socket to be bound to an address that is already in use.

send_buffer_size

Socket option for the send buffer size of a socket.

send_low_watermark

Socket option for the send low watermark.

service_type

The type of the service that will be used to provide I/O operations.

shutdown_type

Different ways a socket may be shutdown.

Member Functions

Name

Description

assign

Assign an existing native socket to the socket.

async_connect

Start an asynchronous connect.

async_receive

Start an asynchronous receive on a connected socket.

async_receive_from

Start an asynchronous receive.

async_send

Start an asynchronous send on a connected socket.

async_send_to

Start an asynchronous send.

at_mark

Determine whether the socket is at the out-of-band data mark.

available

Determine the number of bytes available for reading.

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.

Move-construct a basic_datagram_socket from another.

Move-construct a basic_datagram_socket from a socket of another protocol type.

bind

Bind the socket to the given local endpoint.

cancel

Cancel all asynchronous operations associated with the socket.

close

Close the socket.

connect

Connect the socket to the specified endpoint.

get_io_service

Get the io_service associated with the object.

get_option

Get an option from the socket.

io_control

Perform an IO control command on the socket.

is_open

Determine whether the socket is open.

local_endpoint

Get the local endpoint of the socket.

lowest_layer

Get a reference to the lowest layer.

Get a const reference to the lowest layer.

native

(Deprecated: Use native_handle().) Get the native socket representation.

native_handle

Get the native socket representation.

native_non_blocking

Gets the non-blocking mode of the native socket implementation.

Sets the non-blocking mode of the native socket implementation.

non_blocking

Gets the non-blocking mode of the socket.

Sets the non-blocking mode of the socket.

open

Open the socket using the specified protocol.

operator=

Move-assign a basic_datagram_socket from another.

Move-assign a basic_datagram_socket from a socket of another protocol type.

receive

Receive some data on a connected socket.

receive_from

Receive a datagram with the endpoint of the sender.

remote_endpoint

Get the remote endpoint of the socket.

send

Send some data on a connected socket.

send_to

Send a datagram to the specified endpoint.

set_option

Set an option on the socket.

shutdown

Disable sends or receives on the socket.

Protected Member Functions

Name

Description

get_implementation

Get the underlying implementation of the I/O object.

get_service

Get the service associated with the I/O object.

Data Members

Name

Description

max_connections

The maximum length of the queue of pending incoming connections.

message_do_not_route

Specify that the data should not be subject to routing.

message_end_of_record

Specifies that the data marks the end of a record.

message_out_of_band

Process out-of-band data.

message_peek

Peek at incoming data without removing it from the input queue.

Protected Data Members

Name

Description

implementation

(Deprecated: Use get_implementation().) The underlying implementation of the I/O object.

service

(Deprecated: Use get_service().) The service associated with the I/O object.

The basic_datagram_socket class template provides asynchronous and blocking datagram-oriented socket functionality.

Thread Safety

Distinct objects: Safe.

Shared objects: Unsafe.

Requirements

Header: boost/asio/basic_datagram_socket.hpp

Convenience header: boost/asio.hpp

Assign an existing native socket to the socket.

void assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket);
  » more...

boost::system::error_code assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket,
    boost::system::error_code & ec);
  » more...

Inherited from basic_socket.

Assign an existing native socket to the socket.

void assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket);

Inherited from basic_socket.

Assign an existing native socket to the socket.

boost::system::error_code assign(
    const protocol_type & protocol,
    const native_handle_type & native_socket,
    boost::system::error_code & ec);

Inherited from basic_socket.

Start an asynchronous connect.

template<
    typename ConnectHandler>
void-or-deduced 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.

Parameters

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().

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);

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    ReadHandler handler);
  » more...

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive(
    const MutableBufferSequence & buffers,
    socket_base::message_flags flags,
    ReadHandler handler);
  » more...

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced 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.

Parameters

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().

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.

Example

To receive into a single data buffer use the buffer function as follows:

socket.async_receive(boost::asio::buffer(data, size), handler);

See the buffer documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

Start an asynchronous receive on a connected socket.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced 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.

Parameters

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().

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.

Start an asynchronous receive.

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive_from(
    const MutableBufferSequence & buffers,
    endpoint_type & sender_endpoint,
    ReadHandler handler);
  » more...

template<
    typename MutableBufferSequence,
    typename ReadHandler>
void-or-deduced async_receive_from(
    const MutableBufferSequence & buffers,
    endpoint_type & sender_endpoint,
    socket_base::message_flags flags,
    ReadHandler handler);
  » more...

Start an asynchronous receive.

template<