| Home | Libraries | People | FAQ | More |
Networking | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Classes
|
Free Functions
Class Templates
Services
|
Socket Options
|
I/O Control Commands
Type Requirements
|
Timers |
SSL |
Serial Ports |
Signal Handling |
|||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Classes
Class Templates
Services
Type Requirements
|
Classes
Class Templates
Type Requirements
|
Classes
Class Templates
Services
Serial Port Options
Type Requirements
|
Classes
Class Templates
Services
Type Requirements
|
POSIX-specific |
Windows-specific |
||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Classes
Free Functions
|
Class Templates
Services
Type Requirements
|
Classes
Class Templates
Services
Type Requirements
|
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:
bch
for the handler, as described below.
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.
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:
handler_type
template, which
is used to determine the true handler type based on the asynchronous
operation's handler's signature.
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
.
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 |
|---|---|---|
|
|
|
Returns the |
|
|
|
Initiates an asynchronous operation to read one or more bytes of
data from the device |
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 |
|---|---|---|
|
|
|
Returns the |
|
|
|
Initiates an asynchronous operation to write one or more bytes
of data to the device |
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 |
|---|---|---|
|
|
|
Returns the |
|
|
|
Initiates an asynchronous operation to read one or more bytes of
data from the stream |
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 |
|---|---|---|
|
|
|
Returns the |
|
|
|
Initiates an asynchronous operation to write one or more bytes
of data to the stream |
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
.
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()
.
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.
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
.
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 |
|---|---|---|
|
|
|
|
|
|
iterator type pointing to |
|
|
|
post: 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 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); }
|
|
|
|
post: distance(a.begin(), a.end()) == distance(u.begin(), u.end()) && equal(a.begin(), a.end(), u.begin(), equal_buffer)
where the binary predicate 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); }
|
|
|
|
|
note: the destructor is applied to every element of |
|
|
|
|
|
|
|
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.send_to(b, cb, u, f, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.async_send(b, cb, u, f, wh);
|
|
pre: |
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 |
|---|---|---|
|
|
The implementation-defined native representation of a descriptor.
Must satisfy the requirements of |
|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations, as if
by calling |
|
|
a.move_construct(b, c);
|
From IoObjectService
requirements. The underlying native representation is moved from
|
|
|
a.move_assign(b, ao, c);
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations associated
with |
|
|
a.assign(b, n, ec);
|
|
pre: |
|
a.is_open(b);
|
|
|
|
const X& u = a; const X::implementation_type& v = b; u.is_open(v);
|
|
|
|
a.close(b, ec);
|
|
If |
|
a.native_handle(b);
|
|
|
|
a.cancel(b, ec);
|
|
pre: |
|
a.io_control(b, i, ec);
|
|
pre: |
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 |
|---|---|---|
|
|
type meeting protocol requirements |
|
|
|
||
|
|
||
|
|
|
|
|
|
a pointer |
Returns a pointer suitable for passing as the address
argument to POSIX functions such as |
|
|
a pointer |
Returns a pointer suitable for passing as the address
argument to POSIX functions such as |
|
|
|
Returns a value suitable for passing as the address_len
argument to POSIX functions such as |
|
|
post: |
|
|
|
|
Returns a value suitable for passing as the address_len
argument to POSIX functions such as |
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 |
|---|---|---|
|
|
|
Retrieves the value of the serial port option from the storage. |
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 |
|---|---|---|
|
|
|
Returns a value suitable for passing as the level
argument to POSIX |
|
|
|
Returns a value suitable for passing as the option_name
argument to POSIX |
|
|
a pointer, convertible to |
Returns a pointer suitable for passing as the option_value
argument to POSIX |
|
|
|
Returns a value suitable for passing as the option_len
argument to POSIX |
|
|
post: |
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 |
|---|---|---|
|
using boost::asio::asio_handler_allocate; asio_handler_allocate(s, &h);
|
|
Returns a pointer to a block of memory of size |
|
using boost::asio::asio_handler_deallocate; asio_handler_deallocate(p, s, &h);
|
Frees a block of memory associated with a pointer |
|
|
using boost::asio::asio_handler_invoke; asio_handler_invoke(f, &h);
|
Causes the function object |
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 |
|---|---|---|
|
|
The implementation-defined native representation of a handle. Must
satisfy the requirements of |
|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations, as if
by calling |
|
|
a.move_construct(b, c);
|
From IoObjectService
requirements. The underlying native representation is moved from
|
|
|
a.move_assign(b, ao, c);
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations associated
with |
|
|
a.assign(b, n, ec);
|
|
pre: |
|
a.is_open(b);
|
|
|
|
const X& u = a; const X::implementation_type& v = b; u.is_open(v);
|
|
|
|
a.close(b, ec);
|
|
If |
|
a.native_handle(b);
|
|
|
|
a.cancel(b, ec);
|
|
pre: |
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
.
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 |
|---|---|---|
|
|
|
The type of a resolver for the protocol. |
|
|
|
Returns an object representing the IP version 4 protocol. |
|
|
|
Returns an object representing the IP version 6 protocol. |
|
|
convertible to |
Returns whether two protocol objects are equal. |
|
|
convertible to |
Returns |
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 |
|---|---|---|
|
|
|
Returns a value suitable for passing as the request
argument to POSIX |
|
|
a pointer, convertible to |
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 |
|---|---|---|
|
|
||
|
|
note: |
|
|
a.construct(b);
|
||
|
a.destroy(b);
|
note: |
|
|
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 |
|---|---|---|
|
|
|
|
|
|
iterator type pointing to |
|
|
|
post: 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 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); }
|
|
|
|
post: distance(a.begin(), a.end()) == distance(u.begin(), u.end()) && equal(a.begin(), a.end(), u.begin(), equal_buffer)
where the binary predicate 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); }
|
|
|
|
|
note: the destructor is applied to every element of |
|
|
|
|
|
|
|
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: |
|
|
|
pre: |
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 |
|---|---|---|
|
|
type meeting endpoint requirements |
|
|
|
|
Returns a value suitable for passing as the domain
argument to POSIX |
|
|
|
Returns a value suitable for passing as the type
argument to POSIX |
|
|
|
Returns a value suitable for passing as the protocol
argument to POSIX |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.send_to(b, cb, u, f, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.async_send(b, cb, u, f, wh);
|
|
pre: |
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
.
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.
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 |
|---|---|---|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous resolve operations,
as if by calling |
|
|
a.cancel(b, ec);
|
|
Causes any outstanding asynchronous resolve operations to complete
as soon as possible. Handlers for cancelled operations shall be
passed the error code |
|
a.resolve(b, q, ec);
|
ip::basic_resolver_iterator< InternetProtocol>
|
On success, returns an iterator |
|
a.async_resolve(b, q, h);
|
Initiates an asynchronous resolve operation that is performed via
the |
|
|
a.resolve(b, e, ec);
|
ip::basic_resolver_iterator< InternetProtocol>
|
On success, returns an iterator |
|
a.async_resolve(b, e, h);
|
Initiates an asynchronous resolve operation that is performed via
the |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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 |
|---|---|---|
|
|
The implementation-defined native representation of a serial port.
Must satisfy the requirements of |
|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations, as if
by calling |
|
|
a.move_construct(b, c);
|
From IoObjectService
requirements. The underlying native representation is moved from
|
|
|
a.move_assign(b, ao, c);
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations associated
with |
|
|
const std::string& u = d; a.open(b, u, ec);
|
|
pre: |
|
a.assign(b, n, ec);
|
|
pre: |
|
a.is_open(b);
|
|
|
|
const X& u = a; const X::implementation_type& v = b; u.is_open(v);
|
|
|
|
a.close(b, ec);
|
|
If |
|
a.native_handle(b);
|
|
|
|
a.cancel(b, ec);
|
|
pre: |
|
a.set_option(b, s, ec);
|
|
pre: |
|
a.get_option(b, g, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);
|
|
pre: |
|
a.send_break(b, ec);
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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 |
|---|---|---|
|
|
|
Saves the value of the serial port option to the storage. |
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 |
|---|---|---|
|
|
|
Returns a value suitable for passing as the level
argument to POSIX |
|
|
|
Returns a value suitable for passing as the option_name
argument to POSIX |
|
|
a pointer, convertible to |
Returns a pointer suitable for passing as the option_value
argument to POSIX |
|
|
|
Returns a value suitable for passing as the option_len
argument to POSIX |
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
.
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
.
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 |
|---|---|---|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly clears the registered signals as if by
calling |
|
|
a.add(b, n, ec);
|
|
|
|
a.remove(b, n, ec);
|
|
|
|
a.clear(b, ec);
|
|
|
|
a.cancel(b, ec);
|
|
|
|
|
|
pre: |
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 |
|---|---|---|
|
|
The implementation-defined native representation of a socket acceptor.
Must satisfy the requirements of |
|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations, as if
by calling |
|
|
a.move_construct(b, c);
|
From IoObjectService
requirements. The underlying native representation is moved from
|
|
|
a.move_assign(b, ao, c);
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations associated
with |
|
|
a.open(b, p, ec);
|
|
pre: |
|
a.assign(b, p, n, ec);
|
|
pre: |
|
a.is_open(b);
|
|
|
|
const X& u = a; const X::implementation_type& v = b; u.is_open(v);
|
|
|
|
a.close(b, ec);
|
|
If |
|
a.native_handle(b);
|
|
|
|
a.cancel(b, ec);
|
|
pre: |
|
a.set_option(b, s, ec);
|
|
pre: |
|
a.get_option(b, g, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);
|
|
pre: |
|
a.io_control(b, i, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.bind(b, u, ec);
|
|
pre: |
|
a.local_endpoint(b, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.local_endpoint(v, ec);
|
|
pre: |
|
a.accept(b, k, &e, ec);
|
|
pre: |
|
a.accept(b, k, 0, ec);
|
|
pre: |
|
a.async_accept(b, k, &e, ah);
|
pre: |
|
|
a.async_accept(b, k, 0, ah);
|
pre: |
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 |
|---|---|---|
|
|
The implementation-defined native representation of a socket. Must
satisfy the requirements of |
|
|
|
From IoObjectService
requirements. |
|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations, as if
by calling |
|
|
a.move_construct(b, c);
|
From IoObjectService
requirements. The underlying native representation is moved from
|
|
|
a.move_assign(b, ao, c);
|
From IoObjectService
requirements. Implicitly cancels asynchronous operations associated
with |
|
|
a.open(b, p, ec);
|
|
pre: |
|
a.assign(b, p, n, ec);
|
|
pre: |
|
a.is_open(b);
|
|
|
|
const X& u = a; const X::implementation_type& v = b; u.is_open(v);
|
|
|
|
a.close(b, ec);
|
|
If |
|
a.native_handle(b);
|
|
|
|
a.cancel(b, ec);
|
|
pre: |
|
a.set_option(b, s, ec);
|
|
pre: |
|
a.get_option(b, g, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.get_option(v, g, ec);
|
|
pre: |
|
a.io_control(b, i, ec);
|
|
pre: |
|
a.at_mark(b, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.at_mark(v, ec);
|
|
pre: |
|
a.available(b, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.available(v, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.bind(b, u, ec);
|
|
pre: |
|
a.shutdown(b, h, ec);
|
|
pre: |
|
a.local_endpoint(b, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.local_endpoint(v, ec);
|
|
pre: |
|
a.remote_endpoint(b, ec);
|
|
pre: |
|
const X& u = a; const X::implementation_type& v = b; u.remote_endpoint(v, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.connect(b, u, ec);
|
|
pre: |
|
const typename Protocol::endpoint& u = e; a.async_connect(b, u, ch);
|
pre: |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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: |
|
|
|
pre: |
|
|
|
pre: |
|
|
|
pre: |
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 |
|---|---|---|
|
|
|
Equivalent to: error_code ec; size_t s = a.read_some_at(o, mb, ec); if (ec) throw system_error(ec); return s;
|
|
|
|
Reads one or more bytes of data from the device |
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 |
|---|---|---|
|
|
|
Equivalent to: error_code ec; size_t s = a.write_some(o, cb, ec); if (ec) throw system_error(ec); return s;
|
|
|
|
Writes one or more bytes of data to the device |
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 |
|---|---|---|
|
|
|
Equivalent to: error_code ec; size_t s = a.read_some(mb, ec); if (ec) throw system_error(ec); return s;
|
|
|
|
Reads one or more bytes of data from the stream |
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 |
|---|---|---|
|
|
|
Equivalent to: error_code ec; size_t s = a.write_some(cb, ec); if (ec) throw system_error(ec); return s;
|
|
|
|
Writes one or more bytes of data to the stream |
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 |
|---|---|---|
|
|
|
Represents an absolute time. Must support default construction,
and meet the requirements for |
|
|
Represents the difference between two absolute times. Must support
default construction, and meet the requirements for |
|
|
|
|
Returns the current time. |
|
|
|
Returns a new absolute time resulting from adding the duration
|
|
|
|
Returns the duration resulting from subtracting |
|
|
|
Returns whether |
|
|
|
Returns the |
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 |
|---|---|---|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous wait operations,
as if by calling |
|
|
a.cancel(b, e);
|
|
Causes any outstanding asynchronous wait operations to complete
as soon as possible. Handlers for cancelled operations shall be
passed the error code |
|
|
|
|
|
a.expires_at(b, t, e);
|
|
Implicitly cancels asynchronous wait operations, as if by calling
|
|
|
|
Returns a value equivalent to |
|
a.expires_from_now(b, d, e);
|
|
Equivalent to |
|
a.wait(b, e);
|
|
Sets |
|
a.async_wait(b, h);
|
Initiates an asynchronous wait operation that is performed via
the |
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 |
|---|---|---|
|
|
From IoObjectService
requirements. Implicitly cancels asynchronous wait operations,
as if by calling |
|
|
a.cancel(b, e);
|
|
Causes any outstanding asynchronous wait operations to complete
as soon as possible. Handlers for cancelled operations shall be
passed the error code |
|
|
|
|
|
a.expires_at(b, t, e);
|
|
Implicitly cancels asynchronous wait operations, as if by calling
|
|
|
|
Returns a value equivalent to |
|
a.expires_from_now(b, d, e);
|
|
Equivalent to |
|
a.wait(b, e);
|
|
Sets |
|
a.async_wait(b, h);
|
Initiates an asynchronous wait operation that is performed via
the |
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
.
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 |
|---|---|---|
|
|
|
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
.
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
.
The io_service
object that owns the service.
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)
Thrown if a service of the given type is already present in the io_service
.
Thrown if the service's owning io_service
is not the io_service
object specified by the ios parameter.
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
.
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.
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); }
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
.
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.
class my_handler; template <typename Function> void asio_handler_invoke(Function function, my_handler* context) { context->strand_.dispatch(function); }
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
.
class my_handler; bool asio_handler_is_continuation(my_handler* context) { return true; }
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...
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.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
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()
.
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
.
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.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
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()
.
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.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
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.
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()
.
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
.
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.
The socket to be connected. If the socket is already open, it will be closed.
An iterator pointing to the start of a sequence of endpoints.
An iterator pointing to the end of a sequence of endpoints.
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.
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()
.
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...
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
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()
.
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.
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 stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
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.
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()
.
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
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()
.
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
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.
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...
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:
This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.
The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.
The offset at which the data will be read.
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.
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()
.
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.
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 device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.
The offset at which the data will be read.
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.
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.
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()
.
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:
This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.
The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.
The offset at which the data will be read.
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.
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()
.
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:
This operation is implemented in terms of zero or more calls to the device's async_read_some_at function.
The device from which the data is to be read. The type must support the AsyncRandomAccessReadDevice concept.
The offset at which the data will be read.
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.
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.
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...
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
The delimiter character.
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()
.
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.
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
The delimiter string.
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()
.
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.
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
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.
The regular expression.
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()
.
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.
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:
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.
The stream from which the data is to be read. The type must support the AsyncReadStream concept.
A streambuf object into which the data will be read.
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.
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()
.
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.
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
|
Name |
Description |
|---|---|
|
The return type of the initiating function. |
|
Name |
Description |
|---|---|
|
Construct an async result from a given handler. |
|
|
Obtain the value to be returned from the initiating function. |
This template may be specialised for user-defined handler types.
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.
The return type of the initiating function.
typedef void type;
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...
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:
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.
The stream to which the data is to be written. The type must support the AsyncWriteStream concept.
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.
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()
.
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:
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.
The stream to which the data is to be written. The type must support the AsyncWriteStream concept.
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.
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.
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()
.
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:
basic_streambuf
has been written.
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.
The stream to which the data is to be written. The type must support the AsyncWriteStream concept.
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.
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:
basic_streambuf
has been written.
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.
The stream to which the data is to be written. The type must support the AsyncWriteStream concept.
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.
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.
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...
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:
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.
The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.
The offset at which the data will be written.
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.
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()
.
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:
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.
The device to which the data is to be written. The type must support the AsyncRandomAccessWriteDevice concept.
The offset at which the data will be written.
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.
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.
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()
.
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:
basic_streambuf
has been written.