boost/asio
2
0
Fork 0
mirror of https://github.com/boostorg/asio.git synced 2026-01-28 06:42:08 +00:00
Code Issues Projects Releases Wiki Activity
Files
boost-1.35.0
asio/doc/reference.qbk
Christopher Kohlhoff 2b5306585d Merge fixes from trunk. 
........
  r43377 | chris_kohlhoff | 2008-02-23 09:43:54 +1100 (Sat, 23 Feb 2008) | 2 lines
  
  Use the correct vector of timer queues when dispatching timers.
........
  r43437 | chris_kohlhoff | 2008-02-29 23:57:57 +1100 (Fri, 29 Feb 2008) | 2 lines
  
  Add missing tie().
........
  r43469 | chris_kohlhoff | 2008-03-04 00:21:05 +1100 (Tue, 04 Mar 2008) | 4 lines
  
  Disable use of CancelIo by default, due to the possibility of silent
  failure on some system configurations. Swallow error returned by CancelIoEx
  if there are no operations to be cancelled.
........
  r43470 | chris_kohlhoff | 2008-03-04 00:27:06 +1100 (Tue, 04 Mar 2008) | 2 lines
  
  Add missing 'boost_' prefix to helper namespace.
........
  r43471 | chris_kohlhoff | 2008-03-04 00:36:35 +1100 (Tue, 04 Mar 2008) | 2 lines
  
  Regenerate documentation.
........
  r43472 | chris_kohlhoff | 2008-03-04 01:05:35 +1100 (Tue, 04 Mar 2008) | 1 line
  
  Update copyright notices.
........
  r43473 | chris_kohlhoff | 2008-03-04 01:13:01 +1100 (Tue, 04 Mar 2008) | 2 lines
  
  Update copyright notices.
........
  r43569 | chris_kohlhoff | 2008-03-13 00:25:49 +1100 (Thu, 13 Mar 2008) | 4 lines
  
  Revert to having the windows-bug workaround (short timeout on
  GetQueuedCompletionStatus) on all threads as there are still scenarios
  where threads can get stuck indefinitely.
........


[SVN r43571]
2008-03-12 14:12:08 +00:00

39363 lines
825 KiB
Plaintext
Raw Permalink Blame History

[/
/ Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
/
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[section:reference Reference]
[xinclude quickref.xml]
[include requirements/asynchronous_operations.qbk]
[include requirements/AcceptHandler.qbk]
[include requirements/AsyncReadStream.qbk]
[include requirements/AsyncWriteStream.qbk]
[include requirements/CompletionHandler.qbk]
[include requirements/ConnectHandler.qbk]
[include requirements/ConstBufferSequence.qbk]
[include requirements/ConvertibleToConstBuffer.qbk]
[include requirements/ConvertibleToMutableBuffer.qbk]
[include requirements/DatagramSocketService.qbk]
[include requirements/Endpoint.qbk]
[include requirements/GettableSocketOption.qbk]
[include requirements/Handler.qbk]
[include requirements/InternetProtocol.qbk]
[include requirements/IoControlCommand.qbk]
[include requirements/IoObjectService.qbk]
[include requirements/MutableBufferSequence.qbk]
[include requirements/Protocol.qbk]
[include requirements/ReadHandler.qbk]
[include requirements/ResolveHandler.qbk]
[include requirements/ResolverService.qbk]
[include requirements/Service.qbk]
[include requirements/SettableSocketOption.qbk]
[include requirements/SocketAcceptorService.qbk]
[include requirements/SocketService.qbk]
[include requirements/StreamSocketService.qbk]
[include requirements/SyncReadStream.qbk]
[include requirements/SyncWriteStream.qbk]
[include requirements/TimeTraits.qbk]
[include requirements/TimerService.qbk]
[include requirements/WaitHandler.qbk]
[include requirements/WriteHandler.qbk]
[section:add_service add_service]
template<
typename ``[link boost_asio.reference.Service Service]``>
void add_service(
io_service & ios,
Service * svc);
This function is used to add a service to the io_service.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
[[svc][The service object. On success, ownership of the service object is transferred to the io\_service. When the io\_service object is destroyed, it will destroy the service object by performing:
``
delete static_cast<io_service::service*>(svc)
``
]]
]
[heading Exceptions]
[variablelist
[[boost::asio::service_already_exists][Thrown if a service of the given type is already present in the io\_service.]]
[[boost::asio::invalid_service_owner][Thrown if the service's owning io\_service is not the io\_service object specified by the ios parameter. ]]
]
[endsect]
[section:asio_handler_allocate asio_handler_allocate]
Default allocation function for handlers.
void * asio_handler_allocate(
std::size_t size,
... );
Asynchronous operations may need to allocate temporary objects. Since asynchronous operations have a handler function object, these temporary objects can be said to be associated with the handler.
Implement asio\_handler\_allocate and asio\_handler\_deallocate for your own handlers to provide custom allocation for these temporary objects.
This default implementation is simply:
return ::operator new(bytes);
[heading Remarks]
All temporary objects associated with a handler will be deallocated before the upcall to the handler is performed. This allows the same memory to be reused for a subsequent asynchronous operation initiated by the handler.
[heading Example]
class my_handler;
void* asio_handler_allocate(std::size_t size, my_handler* context)
{
return ::operator new(size);
}
void asio_handler_deallocate(void* pointer, std::size_t size,
my_handler* context)
{
::operator delete(pointer);
}
[endsect]
[section:asio_handler_deallocate asio_handler_deallocate]
Default deallocation function for handlers.
void asio_handler_deallocate(
void * pointer,
std::size_t size,
... );
Implement asio\_handler\_allocate and asio\_handler\_deallocate for your own handlers to provide custom allocation for the associated temporary objects.
This default implementation is simply:
::operator delete(pointer);
[endsect]
[section:asio_handler_invoke asio_handler_invoke]
Default invoke function for handlers.
template<
typename Function>
void asio_handler_invoke(
Function function,
... );
Completion handlers for asynchronous operations are invoked by the io_service associated with the corresponding object (e.g. a socket or deadline\_timer). Certain guarantees are made on when the handler may be invoked, in particular that a handler can only be invoked from a thread that is currently calling boost::asio::io\_service::run() on the corresponding io_service object. Handlers may subsequently be invoked through other objects (such as boost::asio::strand objects) that provide additional guarantees.
When asynchronous operations are composed from other asynchronous operations, all intermediate handlers should be invoked using the same method as the final handler. This is required to ensure that user-defined objects are not accessed in a way that may violate the guarantees. This hooking function ensures that the invoked method used for the final handler is accessible at each intermediate step.
Implement asio\_handler\_invoke for your own handlers to specify a custom invocation strategy.
This default implementation is simply:
function();
[heading Example]
class my_handler;
template <typename Function>
void asio_handler_invoke(Function function, my_handler* context)
{
context->strand_.dispatch(function);
}
[endsect]
[section:async_read async_read]
Start an asynchronous operation to read a certain amount of data from a stream.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read.overload1 async_read]``(
AsyncReadStream & s,
const MutableBufferSequence & buffers,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read.overload2 async_read]``(
AsyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read.overload3 async_read]``(
AsyncReadStream & s,
basic_streambuf< Allocator > & b,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename CompletionCondition,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read.overload4 async_read]``(
AsyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
ReadHandler handler);
[section:overload1 async_read (1 of 4 overloads)]
Start an asynchronous operation to read a certain amount of data from a stream.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read(
AsyncReadStream & s,
const MutableBufferSequence & buffers,
ReadHandler handler);
This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's async\_read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes copied into the
// buffers. If an error occurred,
// this will be the number of
// bytes successfully transferred
// prior to the error.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[heading Remarks]
This overload is equivalent to calling:
boost::asio::async_read(
s, buffers,
boost::asio::transfer_all(),
handler);
[endsect]
[section:overload2 async_read (2 of 4 overloads)]
Start an asynchronous operation to read a certain amount of data from a stream.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read(
AsyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition,
ReadHandler handler);
This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's async\_read\_some function are required.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes copied into the
// buffers. If an error occurred,
// this will be the number of
// bytes successfully transferred
// prior to the error.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::async_read(s,
boost::asio::buffer(data, size),
boost::asio::transfer_at_least(32),
handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 async_read (3 of 4 overloads)]
Start an asynchronous operation to read a certain amount of data from a stream.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read(
AsyncReadStream & s,
basic_streambuf< Allocator > & b,
ReadHandler handler);
This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's async\_read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[b][A basic\_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes copied into the
// buffers. If an error occurred,
// this will be the number of
// bytes successfully transferred
// prior to the error.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
This overload is equivalent to calling:
boost::asio::async_read(
s, b,
boost::asio::transfer_all(),
handler);
[endsect]
[section:overload4 async_read (4 of 4 overloads)]
Start an asynchronous operation to read a certain amount of data from a stream.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename CompletionCondition,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read(
AsyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
ReadHandler handler);
This function is used to asynchronously read a certain number of bytes of data from a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's async\_read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[b][A basic\_streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's async\_read\_some function are required.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes copied into the
// buffers. If an error occurred,
// this will be the number of
// bytes successfully transferred
// prior to the error.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[endsect]
[section:async_read_until async_read_until]
Start an asynchronous operation to read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read_until.overload1 async_read_until]``(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read_until.overload2 async_read_until]``(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.async_read_until.overload3 async_read_until]``(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr,
ReadHandler handler);
[section:overload1 async_read_until (1 of 3 overloads)]
Start an asynchronous operation to read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_until(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim,
ReadHandler handler);
This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[delim][The delimiter character.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // The number of bytes in the
// streambuf's get area up to
// and including the delimiter.
// 0 if an error occurred.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To asynchronously read data into a streambuf until a newline is encountered:
boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
if (!e)
{
std::istream is(&b);
std::string line;
std::getline(is, line);
...
}
}
...
boost::asio::async_read_until(s, b, '\n', handler);
[endsect]
[section:overload2 async_read_until (2 of 3 overloads)]
Start an asynchronous operation to read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_until(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim,
ReadHandler handler);
This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains the delimiter, the asynchronous operation completes immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[delim][The delimiter string.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // The number of bytes in the
// streambuf's get area up to
// and including the delimiter.
// 0 if an error occurred.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To asynchronously read data into a streambuf until a newline is encountered:
boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
if (!e)
{
std::istream is(&b);
std::string line;
std::getline(is, line);
...
}
}
...
boost::asio::async_read_until(s, b, "\r\n", handler);
[endsect]
[section:overload3 async_read_until (3 of 3 overloads)]
Start an asynchronous operation to read data into a streambuf until a regular expression is located.
template<
typename ``[link boost_asio.reference.AsyncReadStream AsyncReadStream]``,
typename Allocator,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_until(
AsyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr,
ReadHandler handler);
This function is used to asynchronously read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* A substring of the streambuf's get area matches the regular expression.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's async\_read\_some function. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the AsyncReadStream concept.]]
[[b][A streambuf object into which the data will be read. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[expr][The regular expression.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // 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.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To asynchronously read data into a streambuf until a CR-LF sequence is encountered:
boost::asio::streambuf b;
...
void handler(const boost::system::error_code& e, std::size_t size)
{
if (!e)
{
std::istream is(&b);
std::string line;
std::getline(is, line);
...
}
}
...
boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler);
[endsect]
[endsect]
[section:async_write async_write]
Start an asynchronous operation to write of all of the supplied data to a stream.
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.async_write.overload1 async_write]``(
AsyncWriteStream & s,
const ConstBufferSequence & buffers,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.async_write.overload2 async_write]``(
AsyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename Allocator,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.async_write.overload3 async_write]``(
AsyncWriteStream & s,
basic_streambuf< Allocator > & b,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename Allocator,
typename CompletionCondition,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.async_write.overload4 async_write]``(
AsyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
WriteHandler handler);
[section:overload1 async_write (1 of 4 overloads)]
Start an asynchronous operation to write of all of the supplied data to a stream.
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write(
AsyncWriteStream & s,
const ConstBufferSequence & buffers,
WriteHandler handler);
This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's async\_write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]]
[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes written from the
// buffers. If an error occurred,
// this will be less than the sum
// of the buffer sizes.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::async_write(s, boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 async_write (2 of 4 overloads)]
Start an asynchronous operation to write a certain amount of data to a stream.
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write(
AsyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition,
WriteHandler handler);
This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's async\_write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]]
[[buffers][One or more buffers containing the data to be written. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's async\_write\_some function are required.]]
[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes written from the
// buffers. If an error occurred,
// this will be less than the sum
// of the buffer sizes.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::async_write(s,
boost::asio::buffer(data, size),
boost::asio::transfer_at_least(32),
handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 async_write (3 of 4 overloads)]
Start an asynchronous operation to write a certain amount of data to a stream.
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename Allocator,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write(
AsyncWriteStream & s,
basic_streambuf< Allocator > & b,
WriteHandler handler);
This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* All of the data in the supplied basic_streambuf has been written.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's async\_write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]]
[[b][A basic\_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes written from the
// buffers. If an error occurred,
// this will be less than the sum
// of the buffer sizes.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[section:overload4 async_write (4 of 4 overloads)]
Start an asynchronous operation to write a certain amount of data to a stream.
template<
typename ``[link boost_asio.reference.AsyncWriteStream AsyncWriteStream]``,
typename Allocator,
typename CompletionCondition,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write(
AsyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
WriteHandler handler);
This function is used to asynchronously write a certain number of bytes of data to a stream. The function call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:
* All of the data in the supplied basic_streambuf has been written.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's async\_write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the AsyncWriteStream concept.]]
[[b][A basic\_streambuf object from which data will be written. Ownership of the streambuf is retained by the caller, which must guarantee that it remains valid until the handler is called.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's async\_write\_some function are required.]]
[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes written from the
// buffers. If an error occurred,
// this will be less than the sum
// of the buffer sizes.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[endsect]
[section:basic_datagram_socket basic_datagram_socket]
Provides datagram-oriented socket functionality.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.DatagramSocketService DatagramSocketService]`` = datagram_socket_service<Protocol>>
class basic_datagram_socket :
public basic_socket< Protocol, DatagramSocketService >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_receive [*async_receive]]]
[Start an asynchronous receive on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_receive_from [*async_receive_from]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_send [*async_send]]]
[Start an asynchronous send on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_send_to [*async_send_to]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket [*basic_datagram_socket]]]
[Construct a basic_datagram_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive [*receive]]]
[Receive some data on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_from [*receive_from]]]
[Receive a datagram with the endpoint of the sender. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send [*send]]]
[Send some data on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_to [*send_to]]]
[Send a datagram to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_datagram_socket class template provides asynchronous and blocking datagram-oriented socket functionality.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:assign basic_datagram_socket::assign]
Assign an existing native socket to the socket.
void ``[link boost_asio.reference.basic_datagram_socket.assign.overload1 assign]``(
const protocol_type & protocol,
const native_type & native_socket);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.assign.overload2 assign]``(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::assign (1 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
void assign(
const protocol_type & protocol,
const native_type & native_socket);
[endsect]
[section:overload2 basic_datagram_socket::assign (2 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
boost::system::error_code assign(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:async_connect basic_datagram_socket::async_connect]
['Inherited from basic_socket.]
Start an asynchronous connect.
void async_connect(
const endpoint_type & peer_endpoint,
ConnectHandler handler);
This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]]
[[handler][The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
void connect_handler(const boost::system::error_code& error)
{
if (!error)
{
// Connect succeeded.
}
}
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_connect(endpoint, connect_handler);
[endsect]
[section:async_receive basic_datagram_socket::async_receive]
Start an asynchronous receive on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload1 async_receive]``(
const MutableBufferSequence & buffers,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_receive.overload2 async_receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
[section:overload1 basic_datagram_socket::async_receive (1 of 2 overloads)]
Start an asynchronous receive on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
const MutableBufferSequence & buffers,
ReadHandler handler);
This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The async\_receive operation can only be used with a connected socket. Use the async\_receive\_from function to receive data on an unconnected datagram socket.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_receive(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::async_receive (2 of 2 overloads)]
Start an asynchronous receive on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
This function is used to asynchronously receive data from the datagram socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The async\_receive operation can only be used with a connected socket. Use the async\_receive\_from function to receive data on an unconnected datagram socket.
[endsect]
[endsect]
[section:async_receive_from basic_datagram_socket::async_receive_from]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload1 async_receive_from]``(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_receive_from.overload2 async_receive_from]``(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
ReadHandler handler);
[section:overload1 basic_datagram_socket::async_receive_from (1 of 2 overloads)]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive_from(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
ReadHandler handler);
This function is used to asynchronously receive a datagram. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram. Ownership of the sender\_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_receive_from(
boost::asio::buffer(data, size), 0, sender_endpoint, handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::async_receive_from (2 of 2 overloads)]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive_from(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
ReadHandler handler);
This function is used to asynchronously receive a datagram. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram. Ownership of the sender\_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[endsect]
[section:async_send basic_datagram_socket::async_send]
Start an asynchronous send on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_send.overload1 async_send]``(
const ConstBufferSequence & buffers,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_send.overload2 async_send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
[section:overload1 basic_datagram_socket::async_send (1 of 2 overloads)]
Start an asynchronous send on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
const ConstBufferSequence & buffers,
WriteHandler handler);
This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The async\_send operation can only be used with a connected socket. Use the async\_send\_to function to send data on an unconnected datagram socket.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_send(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::async_send (2 of 2 overloads)]
Start an asynchronous send on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[flags][Flags specifying how the send call is to be made.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The async\_send operation can only be used with a connected socket. Use the async\_send\_to function to send data on an unconnected datagram socket.
[endsect]
[endsect]
[section:async_send_to basic_datagram_socket::async_send_to]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload1 async_send_to]``(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_datagram_socket.async_send_to.overload2 async_send_to]``(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
WriteHandler handler);
[section:overload1 basic_datagram_socket::async_send_to (1 of 2 overloads)]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send_to(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
WriteHandler handler);
This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent to the remote endpoint. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::ip::udp::endpoint destination(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_send_to(
boost::asio::buffer(data, size), destination, handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::async_send_to (2 of 2 overloads)]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send_to(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
WriteHandler handler);
This function is used to asynchronously send a datagram to the specified remote endpoint. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent to the remote endpoint. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[flags][Flags specifying how the send call is to be made.]]
[[destination][The remote endpoint to which the data will be sent. Copies will be made of the endpoint as required.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[endsect]
[section:at_mark basic_datagram_socket::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool ``[link boost_asio.reference.basic_datagram_socket.at_mark.overload1 at_mark]``() const;
bool ``[link boost_asio.reference.basic_datagram_socket.at_mark.overload2 at_mark]``(
boost::system::error_code & ec) const;
[section:overload1 basic_datagram_socket::at_mark (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark() const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_datagram_socket::at_mark (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
boost::system::error_code & ec) const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[endsect]
[endsect]
[section:available basic_datagram_socket::available]
Determine the number of bytes available for reading.
std::size_t ``[link boost_asio.reference.basic_datagram_socket.available.overload1 available]``() const;
std::size_t ``[link boost_asio.reference.basic_datagram_socket.available.overload2 available]``(
boost::system::error_code & ec) const;
[section:overload1 basic_datagram_socket::available (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available() const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_datagram_socket::available (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available(
boost::system::error_code & ec) const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[endsect]
[endsect]
[section:basic_datagram_socket basic_datagram_socket::basic_datagram_socket]
Construct a basic_datagram_socket without opening it.
``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload1 basic_datagram_socket]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload2 basic_datagram_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol);
``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload3 basic_datagram_socket]``(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
``[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket.overload4 basic_datagram_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
[section:overload1 basic_datagram_socket::basic_datagram_socket (1 of 4 overloads)]
Construct a basic_datagram_socket without opening it.
basic_datagram_socket(
boost::asio::io_service & io_service);
This constructor creates a datagram socket without opening it. The open() function must be called before data can be sent or received on the socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the datagram socket will use to dispatch handlers for any asynchronous operations performed on the socket. ]]
]
[endsect]
[section:overload2 basic_datagram_socket::basic_datagram_socket (2 of 4 overloads)]
Construct and open a basic_datagram_socket.
basic_datagram_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol);
This constructor creates and opens a datagram socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the datagram socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_datagram_socket::basic_datagram_socket (3 of 4 overloads)]
Construct a basic_datagram_socket, opening it and binding it to the given local endpoint.
basic_datagram_socket(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
This constructor creates a datagram socket and automatically opens it bound to the specified endpoint on the local machine. The protocol used is the protocol associated with the given endpoint.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the datagram socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[endpoint][An endpoint on the local machine to which the datagram socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload4 basic_datagram_socket::basic_datagram_socket (4 of 4 overloads)]
Construct a basic_datagram_socket on an existing native socket.
basic_datagram_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
This constructor creates a datagram socket object to hold an existing native socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the datagram socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
[[native_socket][The new underlying socket implementation.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[endsect]
[section:bind basic_datagram_socket::bind]
Bind the socket to the given local endpoint.
void ``[link boost_asio.reference.basic_datagram_socket.bind.overload1 bind]``(
const endpoint_type & endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.bind.overload2 bind]``(
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::bind (1 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
void bind(
const endpoint_type & endpoint);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345));
[endsect]
[section:overload2 basic_datagram_socket::bind (2 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
boost::system::error_code bind(
const endpoint_type & endpoint,
boost::system::error_code & ec);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
boost::system::error_code ec;
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:broadcast basic_datagram_socket::broadcast]
['Inherited from socket_base.]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable basic_datagram_socket::bytes_readable]
['Inherited from socket_base.]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:cancel basic_datagram_socket::cancel]
Cancel all asynchronous operations associated with the socket.
void ``[link boost_asio.reference.basic_datagram_socket.cancel.overload1 cancel]``();
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::cancel (1 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
void cancel();
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[section:overload2 basic_datagram_socket::cancel (2 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
boost::system::error_code & ec);
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[endsect]
[section:close basic_datagram_socket::close]
Close the socket.
void ``[link boost_asio.reference.basic_datagram_socket.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::close (1 of 2 overloads)]
['Inherited from basic_socket.]
Close the socket.
void close();
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[section:overload2 basic_datagram_socket::close (2 of 2 overloads)]
['Inherited from basic_socket.]
Close the socket.
boost::system::error_code close(
boost::system::error_code & ec);
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.close(ec);
if (ec)
{
// An error occurred.
}
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[endsect]
[section:connect basic_datagram_socket::connect]
Connect the socket to the specified endpoint.
void ``[link boost_asio.reference.basic_datagram_socket.connect.overload1 connect]``(
const endpoint_type & peer_endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.connect.overload2 connect]``(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::connect (1 of 2 overloads)]
['Inherited from basic_socket.]
Connect the socket to the specified endpoint.
void connect(
const endpoint_type & peer_endpoint);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.connect(endpoint);
[endsect]
[section:overload2 basic_datagram_socket::connect (2 of 2 overloads)]
['Inherited from basic_socket.]
Connect the socket to the specified endpoint.
boost::system::error_code connect(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
boost::system::error_code ec;
socket.connect(endpoint, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:debug basic_datagram_socket::debug]
['Inherited from socket_base.]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route basic_datagram_socket::do_not_route]
['Inherited from socket_base.]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted basic_datagram_socket::enable_connection_aborted]
['Inherited from socket_base.]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:endpoint_type basic_datagram_socket::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service basic_datagram_socket::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:get_option basic_datagram_socket::get_option]
Get an option from the socket.
void ``[link boost_asio.reference.basic_datagram_socket.get_option.overload1 get_option]``(
GettableSocketOption & option) const;
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.get_option.overload2 get_option]``(
GettableSocketOption & option,
boost::system::error_code & ec) const;
[section:overload1 basic_datagram_socket::get_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
void get_option(
GettableSocketOption & option) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
socket.get_option(option);
bool is_set = option.get();
[endsect]
[section:overload2 basic_datagram_socket::get_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
boost::system::error_code get_option(
GettableSocketOption & option,
boost::system::error_code & ec) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
boost::system::error_code ec;
socket.get_option(option, ec);
if (ec)
{
// An error occurred.
}
bool is_set = option.get();
[endsect]
[endsect]
[section:implementation_type basic_datagram_socket::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_control basic_datagram_socket::io_control]
Perform an IO control command on the socket.
void ``[link boost_asio.reference.basic_datagram_socket.io_control.overload1 io_control]``(
IoControlCommand & command);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.io_control.overload2 io_control]``(
IoControlCommand & command,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::io_control (1 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
void io_control(
IoControlCommand & command);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:overload2 basic_datagram_socket::io_control (2 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
boost::system::error_code io_control(
IoControlCommand & command,
boost::system::error_code & ec);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
boost::system::error_code ec;
socket.io_control(command, ec);
if (ec)
{
// An error occurred.
}
std::size_t bytes_readable = command.get();
[endsect]
[endsect]
[section:io_service basic_datagram_socket::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:is_open basic_datagram_socket::is_open]
['Inherited from basic_socket.]
Determine whether the socket is open.
bool is_open() const;
[endsect]
[section:keep_alive basic_datagram_socket::keep_alive]
['Inherited from socket_base.]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger basic_datagram_socket::linger]
['Inherited from socket_base.]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:local_endpoint basic_datagram_socket::local_endpoint]
Get the local endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_datagram_socket.local_endpoint.overload1 local_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_datagram_socket.local_endpoint.overload2 local_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_datagram_socket::local_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint() const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Return Value]
An object that represents the local endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
[endsect]
[section:overload2 basic_datagram_socket::local_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the local endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:lowest_layer basic_datagram_socket::lowest_layer]
['Inherited from basic_socket.]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
This function returns a reference to the lowest layer in a stack of layers. Since a basic_socket cannot contain any further layers, it simply returns a reference to itself.
[heading Return Value]
A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer_type basic_datagram_socket::lowest_layer_type]
['Inherited from basic_socket.]
A basic_socket is always the lowest layer.
typedef basic_socket< Protocol, DatagramSocketService > lowest_layer_type;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]]
[Construct a basic_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket class template provides functionality that is common to both stream-oriented and datagram-oriented sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:max_connections basic_datagram_socket::max_connections]
['Inherited from socket_base.]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route basic_datagram_socket::message_do_not_route]
['Inherited from socket_base.]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags basic_datagram_socket::message_flags]
['Inherited from socket_base.]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band basic_datagram_socket::message_out_of_band]
['Inherited from socket_base.]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek basic_datagram_socket::message_peek]
['Inherited from socket_base.]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:native basic_datagram_socket::native]
['Inherited from basic_socket.]
Get the native socket representation.
native_type native();
This function may be used to obtain the underlying representation of the socket. This is intended to allow access to native socket functionality that is not otherwise provided.
[endsect]
[section:native_type basic_datagram_socket::native_type]
The native representation of a socket.
typedef DatagramSocketService::native_type native_type;
[endsect]
[section:non_blocking_io basic_datagram_socket::non_blocking_io]
['Inherited from socket_base.]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:open basic_datagram_socket::open]
Open the socket using the specified protocol.
void ``[link boost_asio.reference.basic_datagram_socket.open.overload1 open]``(
const protocol_type & protocol = protocol_type());
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.open.overload2 open]``(
const protocol_type & protocol,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::open (1 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
void open(
const protocol_type & protocol = protocol_type());
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
[endsect]
[section:overload2 basic_datagram_socket::open (2 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
boost::system::error_code open(
const protocol_type & protocol,
boost::system::error_code & ec);
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::system::error_code ec;
socket.open(boost::asio::ip::tcp::v4(), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:protocol_type basic_datagram_socket::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive basic_datagram_socket::receive]
Receive some data on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload1 receive]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload2 receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive.overload3 receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::receive (1 of 3 overloads)]
Receive some data on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers);
This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.receive(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::receive (2 of 3 overloads)]
Receive some data on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags);
This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[flags][Flags specifying how the receive call is to be made.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket.
[endsect]
[section:overload3 basic_datagram_socket::receive (3 of 3 overloads)]
Receive some data on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to receive data on the datagram socket. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes received.
[heading Remarks]
The receive operation can only be used with a connected socket. Use the receive\_from function to receive data on an unconnected datagram socket.
[endsect]
[endsect]
[section:receive_buffer_size basic_datagram_socket::receive_buffer_size]
['Inherited from socket_base.]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_from basic_datagram_socket::receive_from]
Receive a datagram with the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload1 receive_from]``(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload2 receive_from]``(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.receive_from.overload3 receive_from]``(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::receive_from (1 of 3 overloads)]
Receive a datagram with the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive_from(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint);
This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::ip::udp::endpoint sender_endpoint;
socket.receive_from(
boost::asio::buffer(data, size), sender_endpoint);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::receive_from (2 of 3 overloads)]
Receive a datagram with the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive_from(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags);
This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]]
[[flags][Flags specifying how the receive call is to be made.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_datagram_socket::receive_from (3 of 3 overloads)]
Receive a datagram with the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive_from(
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to receive a datagram. The function call will block until data has been received successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[sender_endpoint][An endpoint object that receives the endpoint of the remote sender of the datagram.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes received.
[endsect]
[endsect]
[section:receive_low_watermark basic_datagram_socket::receive_low_watermark]
['Inherited from socket_base.]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:remote_endpoint basic_datagram_socket::remote_endpoint]
Get the remote endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload1 remote_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_datagram_socket.remote_endpoint.overload2 remote_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_datagram_socket::remote_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint() const;
This function is used to obtain the remote endpoint of the socket.
[heading Return Value]
An object that represents the remote endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
[endsect]
[section:overload2 basic_datagram_socket::remote_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the remote endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the remote endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:reuse_address basic_datagram_socket::reuse_address]
['Inherited from socket_base.]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send basic_datagram_socket::send]
Send some data on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload1 send]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload2 send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send.overload3 send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::send (1 of 3 overloads)]
Send some data on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers);
This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One ore more data buffers to be sent on the socket.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.send(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::send (2 of 3 overloads)]
Send some data on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags);
This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One ore more data buffers to be sent on the socket.]]
[[flags][Flags specifying how the send call is to be made.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket.
[endsect]
[section:overload3 basic_datagram_socket::send (3 of 3 overloads)]
Send some data on a connected socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to send data on the datagram socket. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket.]]
[[flags][Flags specifying how the send call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes sent.
[heading Remarks]
The send operation can only be used with a connected socket. Use the send\_to function to send data on an unconnected datagram socket.
[endsect]
[endsect]
[section:send_buffer_size basic_datagram_socket::send_buffer_size]
['Inherited from socket_base.]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark basic_datagram_socket::send_low_watermark]
['Inherited from socket_base.]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_to basic_datagram_socket::send_to]
Send a datagram to the specified endpoint.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload1 send_to]``(
const ConstBufferSequence & buffers,
const endpoint_type & destination);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload2 send_to]``(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_datagram_socket.send_to.overload3 send_to]``(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::send_to (1 of 3 overloads)]
Send a datagram to the specified endpoint.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send_to(
const ConstBufferSequence & buffers,
const endpoint_type & destination);
This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent to the remote endpoint.]]
[[destination][The remote endpoint to which the data will be sent.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::ip::udp::endpoint destination(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.send_to(boost::asio::buffer(data, size), destination);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_datagram_socket::send_to (2 of 3 overloads)]
Send a datagram to the specified endpoint.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send_to(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags);
This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent to the remote endpoint.]]
[[destination][The remote endpoint to which the data will be sent.]]
[[flags][Flags specifying how the send call is to be made.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_datagram_socket::send_to (3 of 3 overloads)]
Send a datagram to the specified endpoint.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send_to(
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to send a datagram to the specified remote endpoint. The function call will block until the data has been sent successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent to the remote endpoint.]]
[[destination][The remote endpoint to which the data will be sent.]]
[[flags][Flags specifying how the send call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes sent.
[endsect]
[endsect]
[section:service_type basic_datagram_socket::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef DatagramSocketService service_type;
[endsect]
[section:set_option basic_datagram_socket::set_option]
Set an option on the socket.
void ``[link boost_asio.reference.basic_datagram_socket.set_option.overload1 set_option]``(
const SettableSocketOption & option);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.set_option.overload2 set_option]``(
const SettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::set_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
void set_option(
const SettableSocketOption & option);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
socket.set_option(option);
[endsect]
[section:overload2 basic_datagram_socket::set_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
boost::system::error_code set_option(
const SettableSocketOption & option,
boost::system::error_code & ec);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
boost::system::error_code ec;
socket.set_option(option, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown basic_datagram_socket::shutdown]
Disable sends or receives on the socket.
void ``[link boost_asio.reference.basic_datagram_socket.shutdown.overload1 shutdown]``(
shutdown_type what);
boost::system::error_code ``[link boost_asio.reference.basic_datagram_socket.shutdown.overload2 shutdown]``(
shutdown_type what,
boost::system::error_code & ec);
[section:overload1 basic_datagram_socket::shutdown (1 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
void shutdown(
shutdown_type what);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
[endsect]
[section:overload2 basic_datagram_socket::shutdown (2 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
shutdown_type what,
boost::system::error_code & ec);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown_type basic_datagram_socket::shutdown_type]
['Inherited from socket_base.]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[endsect]
[section:basic_deadline_timer basic_deadline_timer]
Provides waitable timer functionality.
template<
typename Time,
typename ``[link boost_asio.reference.TimeTraits TimeTraits]`` = boost::asio::time_traits<Time>,
typename ``[link boost_asio.reference.TimerService TimerService]`` = deadline_timer_service<Time, TimeTraits>>
class basic_deadline_timer :
public basic_io_object< TimerService >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_deadline_timer.duration_type [*duration_type]]]
[The duration type. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.time_type [*time_type]]]
[The time type. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.traits_type [*traits_type]]]
[The time traits type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_deadline_timer.async_wait [*async_wait]]]
[Start an asynchronous wait on the timer. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.basic_deadline_timer [*basic_deadline_timer]]]
[Constructor. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.cancel [*cancel]]]
[Cancel any asynchronous operations that are waiting on the timer. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.expires_at [*expires_at]]]
[Get the timer's expiry time as an absolute time. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.expires_from_now [*expires_from_now]]]
[Get the timer's expiry time relative to now. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.wait [*wait]]]
[Perform a blocking wait on the timer. ]
]
]
The basic_deadline_timer class template provides the ability to perform a blocking or asynchronous wait for a timer to expire.
Most applications will use the boost::asio::deadline\_timer typedef.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[heading Examples]
Performing a blocking wait:
// Construct a timer without setting an expiry time.
boost::asio::deadline_timer timer(io_service);
// Set an expiry time relative to now.
timer.expires_from_now(boost::posix_time::seconds(5));
// Wait for the timer to expire.
timer.wait();
Performing an asynchronous wait:
void handler(const boost::system::error_code& error)
{
if (!error)
{
// Timer expired.
}
}
...
// Construct a timer with an absolute expiry time.
boost::asio::deadline_timer timer(io_service,
boost::posix_time::time_from_string("2005-12-07 23:59:59.000"));
// Start an asynchronous wait.
timer.async_wait(handler);
[heading Changing an active deadline_timer's expiry time]
Changing the expiry time of a timer while there are pending asynchronous waits causes those wait operations to be cancelled. To ensure that the action associated with the timer is performed only once, use something like this: used:
void on_some_event()
{
if (my_timer.expires_from_now(seconds(5)) > 0)
{
// We managed to cancel the timer. Start new asynchronous wait.
my_timer.async_wait(on_timeout);
}
else
{
// Too late, timer has already expired!
}
}
void on_timeout(const boost::system::error_code& e)
{
if (e != boost::asio::error::operation_aborted)
{
// Timer was not cancelled, take necessary action.
}
}
* The boost::asio::basic_deadline_timer::expires_from_now() function cancels any pending asynchronous waits, and returns the number of asynchronous waits that were cancelled. If it returns 0 then you were too late and the wait handler has already been executed, or will soon be executed. If it returns 1 then the wait handler was successfully cancelled.
* If a wait handler is cancelled, the boost::system::error_code passed to it contains the value boost::asio::error::operation_aborted.
[section:async_wait basic_deadline_timer::async_wait]
Start an asynchronous wait on the timer.
template<
typename ``[link boost_asio.reference.WaitHandler WaitHandler]``>
void async_wait(
WaitHandler handler);
This function may be used to initiate an asynchronous wait against the timer. It always returns immediately.
For each call to async\_wait(), the supplied handler will be called exactly once. The handler will be called when:
* The timer has expired.
* The timer was cancelled, in which case the handler is passed the error code boost::asio::error::operation_aborted.
[heading Parameters]
[variablelist
[[handler][The handler to be called when the timer expires. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[section:basic_deadline_timer basic_deadline_timer::basic_deadline_timer]
Constructor.
``[link boost_asio.reference.basic_deadline_timer.basic_deadline_timer.overload1 basic_deadline_timer]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.basic_deadline_timer.basic_deadline_timer.overload2 basic_deadline_timer]``(
boost::asio::io_service & io_service,
const time_type & expiry_time);
``[link boost_asio.reference.basic_deadline_timer.basic_deadline_timer.overload3 basic_deadline_timer]``(
boost::asio::io_service & io_service,
const duration_type & expiry_time);
[section:overload1 basic_deadline_timer::basic_deadline_timer (1 of 3 overloads)]
Constructor.
basic_deadline_timer(
boost::asio::io_service & io_service);
This constructor creates a timer without setting an expiry time. The expires\_at() or expires\_from\_now() functions must be called to set an expiry time before the timer can be waited on.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer. ]]
]
[endsect]
[section:overload2 basic_deadline_timer::basic_deadline_timer (2 of 3 overloads)]
Constructor to set a particular expiry time as an absolute time.
basic_deadline_timer(
boost::asio::io_service & io_service,
const time_type & expiry_time);
This constructor creates a timer and sets the expiry time.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer.]]
[[expiry_time][The expiry time to be used for the timer, expressed as an absolute time. ]]
]
[endsect]
[section:overload3 basic_deadline_timer::basic_deadline_timer (3 of 3 overloads)]
Constructor to set a particular expiry time relative to now.
basic_deadline_timer(
boost::asio::io_service & io_service,
const duration_type & expiry_time);
This constructor creates a timer and sets the expiry time.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the timer will use to dispatch handlers for any asynchronous operations performed on the timer.]]
[[expiry_time][The expiry time to be used for the timer, relative to now. ]]
]
[endsect]
[endsect]
[section:cancel basic_deadline_timer::cancel]
Cancel any asynchronous operations that are waiting on the timer.
std::size_t ``[link boost_asio.reference.basic_deadline_timer.cancel.overload1 cancel]``();
std::size_t ``[link boost_asio.reference.basic_deadline_timer.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_deadline_timer::cancel (1 of 2 overloads)]
Cancel any asynchronous operations that are waiting on the timer.
std::size_t cancel();
This function forces the completion of any pending asynchronous wait operations against the timer. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
Cancelling the timer does not change the expiry time.
[heading Return Value]
The number of asynchronous operations that were cancelled.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_deadline_timer::cancel (2 of 2 overloads)]
Cancel any asynchronous operations that are waiting on the timer.
std::size_t cancel(
boost::system::error_code & ec);
This function forces the completion of any pending asynchronous wait operations against the timer. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
Cancelling the timer does not change the expiry time.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of asynchronous operations that were cancelled.
[endsect]
[endsect]
[section:duration_type basic_deadline_timer::duration_type]
The duration type.
typedef traits_type::duration_type duration_type;
[endsect]
[section:expires_at basic_deadline_timer::expires_at]
Get the timer's expiry time as an absolute time.
time_type ``[link boost_asio.reference.basic_deadline_timer.expires_at.overload1 expires_at]``() const;
std::size_t ``[link boost_asio.reference.basic_deadline_timer.expires_at.overload2 expires_at]``(
const time_type & expiry_time);
std::size_t ``[link boost_asio.reference.basic_deadline_timer.expires_at.overload3 expires_at]``(
const time_type & expiry_time,
boost::system::error_code & ec);
[section:overload1 basic_deadline_timer::expires_at (1 of 3 overloads)]
Get the timer's expiry time as an absolute time.
time_type expires_at() const;
This function may be used to obtain the timer's current expiry time. Whether the timer has expired or not does not affect this value.
[endsect]
[section:overload2 basic_deadline_timer::expires_at (2 of 3 overloads)]
Set the timer's expiry time as an absolute time.
std::size_t expires_at(
const time_type & expiry_time);
This function sets the expiry time. Any pending asynchronous wait operations will be cancelled. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
[heading Parameters]
[variablelist
[[expiry_time][The expiry time to be used for the timer.]]
]
[heading Return Value]
The number of asynchronous operations that were cancelled.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_deadline_timer::expires_at (3 of 3 overloads)]
Set the timer's expiry time as an absolute time.
std::size_t expires_at(
const time_type & expiry_time,
boost::system::error_code & ec);
This function sets the expiry time. Any pending asynchronous wait operations will be cancelled. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
[heading Parameters]
[variablelist
[[expiry_time][The expiry time to be used for the timer.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of asynchronous operations that were cancelled.
[endsect]
[endsect]
[section:expires_from_now basic_deadline_timer::expires_from_now]
Get the timer's expiry time relative to now.
duration_type ``[link boost_asio.reference.basic_deadline_timer.expires_from_now.overload1 expires_from_now]``() const;
std::size_t ``[link boost_asio.reference.basic_deadline_timer.expires_from_now.overload2 expires_from_now]``(
const duration_type & expiry_time);
std::size_t ``[link boost_asio.reference.basic_deadline_timer.expires_from_now.overload3 expires_from_now]``(
const duration_type & expiry_time,
boost::system::error_code & ec);
[section:overload1 basic_deadline_timer::expires_from_now (1 of 3 overloads)]
Get the timer's expiry time relative to now.
duration_type expires_from_now() const;
This function may be used to obtain the timer's current expiry time. Whether the timer has expired or not does not affect this value.
[endsect]
[section:overload2 basic_deadline_timer::expires_from_now (2 of 3 overloads)]
Set the timer's expiry time relative to now.
std::size_t expires_from_now(
const duration_type & expiry_time);
This function sets the expiry time. Any pending asynchronous wait operations will be cancelled. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
[heading Parameters]
[variablelist
[[expiry_time][The expiry time to be used for the timer.]]
]
[heading Return Value]
The number of asynchronous operations that were cancelled.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_deadline_timer::expires_from_now (3 of 3 overloads)]
Set the timer's expiry time relative to now.
std::size_t expires_from_now(
const duration_type & expiry_time,
boost::system::error_code & ec);
This function sets the expiry time. Any pending asynchronous wait operations will be cancelled. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
[heading Parameters]
[variablelist
[[expiry_time][The expiry time to be used for the timer.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of asynchronous operations that were cancelled.
[endsect]
[endsect]
[section:get_io_service basic_deadline_timer::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:implementation_type basic_deadline_timer::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_service basic_deadline_timer::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:service_type basic_deadline_timer::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef TimerService service_type;
[endsect]
[section:time_type basic_deadline_timer::time_type]
The time type.
typedef traits_type::time_type time_type;
[endsect]
[section:traits_type basic_deadline_timer::traits_type]
The time traits type.
typedef TimeTraits traits_type;
[endsect]
[section:wait basic_deadline_timer::wait]
Perform a blocking wait on the timer.
void ``[link boost_asio.reference.basic_deadline_timer.wait.overload1 wait]``();
void ``[link boost_asio.reference.basic_deadline_timer.wait.overload2 wait]``(
boost::system::error_code & ec);
[section:overload1 basic_deadline_timer::wait (1 of 2 overloads)]
Perform a blocking wait on the timer.
void wait();
This function is used to wait for the timer to expire. This function blocks and does not return until the timer has expired.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_deadline_timer::wait (2 of 2 overloads)]
Perform a blocking wait on the timer.
void wait(
boost::system::error_code & ec);
This function is used to wait for the timer to expire. This function blocks and does not return until the timer has expired.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[endsect]
[section:basic_io_object basic_io_object]
Base class for all I/O objects.
template<
typename ``[link boost_asio.reference.IoObjectService IoObjectService]``>
class basic_io_object :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_io_object.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_io_object.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_io_object.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_io_object.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
]
[section:get_io_service basic_io_object::get_io_service]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:implementation_type basic_io_object::implementation_type]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_service basic_io_object::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:service_type basic_io_object::service_type]
The type of the service that will be used to provide I/O operations.
typedef IoObjectService service_type;
[endsect]
[endsect]
[section:basic_socket basic_socket]
Provides socket functionality.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.SocketService SocketService]``>
class basic_socket :
public basic_io_object< SocketService >,
public socket_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]]
[Construct a basic_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket class template provides functionality that is common to both stream-oriented and datagram-oriented sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:assign basic_socket::assign]
Assign an existing native socket to the socket.
void ``[link boost_asio.reference.basic_socket.assign.overload1 assign]``(
const protocol_type & protocol,
const native_type & native_socket);
boost::system::error_code ``[link boost_asio.reference.basic_socket.assign.overload2 assign]``(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[section:overload1 basic_socket::assign (1 of 2 overloads)]
Assign an existing native socket to the socket.
void assign(
const protocol_type & protocol,
const native_type & native_socket);
[endsect]
[section:overload2 basic_socket::assign (2 of 2 overloads)]
Assign an existing native socket to the socket.
boost::system::error_code assign(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:async_connect basic_socket::async_connect]
Start an asynchronous connect.
template<
typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]``>
void async_connect(
const endpoint_type & peer_endpoint,
ConnectHandler handler);
This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]]
[[handler][The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
void connect_handler(const boost::system::error_code& error)
{
if (!error)
{
// Connect succeeded.
}
}
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_connect(endpoint, connect_handler);
[endsect]
[section:at_mark basic_socket::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool ``[link boost_asio.reference.basic_socket.at_mark.overload1 at_mark]``() const;
bool ``[link boost_asio.reference.basic_socket.at_mark.overload2 at_mark]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket::at_mark (1 of 2 overloads)]
Determine whether the socket is at the out-of-band data mark.
bool at_mark() const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket::at_mark (2 of 2 overloads)]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
boost::system::error_code & ec) const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[endsect]
[endsect]
[section:available basic_socket::available]
Determine the number of bytes available for reading.
std::size_t ``[link boost_asio.reference.basic_socket.available.overload1 available]``() const;
std::size_t ``[link boost_asio.reference.basic_socket.available.overload2 available]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket::available (1 of 2 overloads)]
Determine the number of bytes available for reading.
std::size_t available() const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket::available (2 of 2 overloads)]
Determine the number of bytes available for reading.
std::size_t available(
boost::system::error_code & ec) const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[endsect]
[endsect]
[section:basic_socket basic_socket::basic_socket]
Construct a basic_socket without opening it.
``[link boost_asio.reference.basic_socket.basic_socket.overload1 basic_socket]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.basic_socket.basic_socket.overload2 basic_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol);
``[link boost_asio.reference.basic_socket.basic_socket.overload3 basic_socket]``(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
``[link boost_asio.reference.basic_socket.basic_socket.overload4 basic_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
[section:overload1 basic_socket::basic_socket (1 of 4 overloads)]
Construct a basic_socket without opening it.
basic_socket(
boost::asio::io_service & io_service);
This constructor creates a socket without opening it.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the socket will use to dispatch handlers for any asynchronous operations performed on the socket. ]]
]
[endsect]
[section:overload2 basic_socket::basic_socket (2 of 4 overloads)]
Construct and open a basic_socket.
basic_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol);
This constructor creates and opens a socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_socket::basic_socket (3 of 4 overloads)]
Construct a basic_socket, opening it and binding it to the given local endpoint.
basic_socket(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
This constructor creates a socket and automatically opens it bound to the specified endpoint on the local machine. The protocol used is the protocol associated with the given endpoint.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload4 basic_socket::basic_socket (4 of 4 overloads)]
Construct a basic_socket on an existing native socket.
basic_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
This constructor creates a socket object to hold an existing native socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
[[native_socket][A native socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[endsect]
[section:bind basic_socket::bind]
Bind the socket to the given local endpoint.
void ``[link boost_asio.reference.basic_socket.bind.overload1 bind]``(
const endpoint_type & endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_socket.bind.overload2 bind]``(
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket::bind (1 of 2 overloads)]
Bind the socket to the given local endpoint.
void bind(
const endpoint_type & endpoint);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345));
[endsect]
[section:overload2 basic_socket::bind (2 of 2 overloads)]
Bind the socket to the given local endpoint.
boost::system::error_code bind(
const endpoint_type & endpoint,
boost::system::error_code & ec);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
boost::system::error_code ec;
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:broadcast basic_socket::broadcast]
['Inherited from socket_base.]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable basic_socket::bytes_readable]
['Inherited from socket_base.]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:cancel basic_socket::cancel]
Cancel all asynchronous operations associated with the socket.
void ``[link boost_asio.reference.basic_socket.cancel.overload1 cancel]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_socket::cancel (1 of 2 overloads)]
Cancel all asynchronous operations associated with the socket.
void cancel();
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[section:overload2 basic_socket::cancel (2 of 2 overloads)]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
boost::system::error_code & ec);
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[endsect]
[section:close basic_socket::close]
Close the socket.
void ``[link boost_asio.reference.basic_socket.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 basic_socket::close (1 of 2 overloads)]
Close the socket.
void close();
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[section:overload2 basic_socket::close (2 of 2 overloads)]
Close the socket.
boost::system::error_code close(
boost::system::error_code & ec);
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.close(ec);
if (ec)
{
// An error occurred.
}
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[endsect]
[section:connect basic_socket::connect]
Connect the socket to the specified endpoint.
void ``[link boost_asio.reference.basic_socket.connect.overload1 connect]``(
const endpoint_type & peer_endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_socket.connect.overload2 connect]``(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket::connect (1 of 2 overloads)]
Connect the socket to the specified endpoint.
void connect(
const endpoint_type & peer_endpoint);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.connect(endpoint);
[endsect]
[section:overload2 basic_socket::connect (2 of 2 overloads)]
Connect the socket to the specified endpoint.
boost::system::error_code connect(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
boost::system::error_code ec;
socket.connect(endpoint, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:debug basic_socket::debug]
['Inherited from socket_base.]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route basic_socket::do_not_route]
['Inherited from socket_base.]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted basic_socket::enable_connection_aborted]
['Inherited from socket_base.]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:endpoint_type basic_socket::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service basic_socket::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:get_option basic_socket::get_option]
Get an option from the socket.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
void ``[link boost_asio.reference.basic_socket.get_option.overload1 get_option]``(
GettableSocketOption & option) const;
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket.get_option.overload2 get_option]``(
GettableSocketOption & option,
boost::system::error_code & ec) const;
[section:overload1 basic_socket::get_option (1 of 2 overloads)]
Get an option from the socket.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
void get_option(
GettableSocketOption & option) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
socket.get_option(option);
bool is_set = option.get();
[endsect]
[section:overload2 basic_socket::get_option (2 of 2 overloads)]
Get an option from the socket.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code get_option(
GettableSocketOption & option,
boost::system::error_code & ec) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
boost::system::error_code ec;
socket.get_option(option, ec);
if (ec)
{
// An error occurred.
}
bool is_set = option.get();
[endsect]
[endsect]
[section:implementation_type basic_socket::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_control basic_socket::io_control]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
void ``[link boost_asio.reference.basic_socket.io_control.overload1 io_control]``(
IoControlCommand & command);
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket.io_control.overload2 io_control]``(
IoControlCommand & command,
boost::system::error_code & ec);
[section:overload1 basic_socket::io_control (1 of 2 overloads)]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
void io_control(
IoControlCommand & command);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:overload2 basic_socket::io_control (2 of 2 overloads)]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
boost::system::error_code io_control(
IoControlCommand & command,
boost::system::error_code & ec);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
boost::system::error_code ec;
socket.io_control(command, ec);
if (ec)
{
// An error occurred.
}
std::size_t bytes_readable = command.get();
[endsect]
[endsect]
[section:io_service basic_socket::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:is_open basic_socket::is_open]
Determine whether the socket is open.
bool is_open() const;
[endsect]
[section:keep_alive basic_socket::keep_alive]
['Inherited from socket_base.]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger basic_socket::linger]
['Inherited from socket_base.]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:local_endpoint basic_socket::local_endpoint]
Get the local endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_socket.local_endpoint.overload1 local_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_socket.local_endpoint.overload2 local_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket::local_endpoint (1 of 2 overloads)]
Get the local endpoint of the socket.
endpoint_type local_endpoint() const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Return Value]
An object that represents the local endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
[endsect]
[section:overload2 basic_socket::local_endpoint (2 of 2 overloads)]
Get the local endpoint of the socket.
endpoint_type local_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the local endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:lowest_layer basic_socket::lowest_layer]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
This function returns a reference to the lowest layer in a stack of layers. Since a basic_socket cannot contain any further layers, it simply returns a reference to itself.
[heading Return Value]
A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer_type basic_socket::lowest_layer_type]
A basic_socket is always the lowest layer.
typedef basic_socket< Protocol, SocketService > lowest_layer_type;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]]
[Construct a basic_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket class template provides functionality that is common to both stream-oriented and datagram-oriented sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:max_connections basic_socket::max_connections]
['Inherited from socket_base.]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route basic_socket::message_do_not_route]
['Inherited from socket_base.]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags basic_socket::message_flags]
['Inherited from socket_base.]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band basic_socket::message_out_of_band]
['Inherited from socket_base.]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek basic_socket::message_peek]
['Inherited from socket_base.]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:native basic_socket::native]
Get the native socket representation.
native_type native();
This function may be used to obtain the underlying representation of the socket. This is intended to allow access to native socket functionality that is not otherwise provided.
[endsect]
[section:native_type basic_socket::native_type]
The native representation of a socket.
typedef SocketService::native_type native_type;
[endsect]
[section:non_blocking_io basic_socket::non_blocking_io]
['Inherited from socket_base.]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:open basic_socket::open]
Open the socket using the specified protocol.
void ``[link boost_asio.reference.basic_socket.open.overload1 open]``(
const protocol_type & protocol = protocol_type());
boost::system::error_code ``[link boost_asio.reference.basic_socket.open.overload2 open]``(
const protocol_type & protocol,
boost::system::error_code & ec);
[section:overload1 basic_socket::open (1 of 2 overloads)]
Open the socket using the specified protocol.
void open(
const protocol_type & protocol = protocol_type());
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
[endsect]
[section:overload2 basic_socket::open (2 of 2 overloads)]
Open the socket using the specified protocol.
boost::system::error_code open(
const protocol_type & protocol,
boost::system::error_code & ec);
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::system::error_code ec;
socket.open(boost::asio::ip::tcp::v4(), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:protocol_type basic_socket::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive_buffer_size basic_socket::receive_buffer_size]
['Inherited from socket_base.]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_low_watermark basic_socket::receive_low_watermark]
['Inherited from socket_base.]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:remote_endpoint basic_socket::remote_endpoint]
Get the remote endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_socket.remote_endpoint.overload1 remote_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_socket.remote_endpoint.overload2 remote_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket::remote_endpoint (1 of 2 overloads)]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint() const;
This function is used to obtain the remote endpoint of the socket.
[heading Return Value]
An object that represents the remote endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
[endsect]
[section:overload2 basic_socket::remote_endpoint (2 of 2 overloads)]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the remote endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the remote endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:reuse_address basic_socket::reuse_address]
['Inherited from socket_base.]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send_buffer_size basic_socket::send_buffer_size]
['Inherited from socket_base.]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark basic_socket::send_low_watermark]
['Inherited from socket_base.]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:service_type basic_socket::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef SocketService service_type;
[endsect]
[section:set_option basic_socket::set_option]
Set an option on the socket.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
void ``[link boost_asio.reference.basic_socket.set_option.overload1 set_option]``(
const SettableSocketOption & option);
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket.set_option.overload2 set_option]``(
const SettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_socket::set_option (1 of 2 overloads)]
Set an option on the socket.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
void set_option(
const SettableSocketOption & option);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
socket.set_option(option);
[endsect]
[section:overload2 basic_socket::set_option (2 of 2 overloads)]
Set an option on the socket.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code set_option(
const SettableSocketOption & option,
boost::system::error_code & ec);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
boost::system::error_code ec;
socket.set_option(option, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown basic_socket::shutdown]
Disable sends or receives on the socket.
void ``[link boost_asio.reference.basic_socket.shutdown.overload1 shutdown]``(
shutdown_type what);
boost::system::error_code ``[link boost_asio.reference.basic_socket.shutdown.overload2 shutdown]``(
shutdown_type what,
boost::system::error_code & ec);
[section:overload1 basic_socket::shutdown (1 of 2 overloads)]
Disable sends or receives on the socket.
void shutdown(
shutdown_type what);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
[endsect]
[section:overload2 basic_socket::shutdown (2 of 2 overloads)]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
shutdown_type what,
boost::system::error_code & ec);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown_type basic_socket::shutdown_type]
['Inherited from socket_base.]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[endsect]
[section:basic_socket_acceptor basic_socket_acceptor]
Provides the ability to accept new connections.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.SocketAcceptorService SocketAcceptorService]`` = socket_acceptor_service<Protocol>>
class basic_socket_acceptor :
public basic_io_object< SocketAcceptorService >,
public socket_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.native_type [*native_type]]]
[The native representation of an acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.accept [*accept]]]
[Accept a new connection. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.assign [*assign]]]
[Assigns an existing native acceptor to the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.async_accept [*async_accept]]]
[Start an asynchronous accept. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor [*basic_socket_acceptor]]]
[Construct an acceptor without opening it. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.bind [*bind]]]
[Bind the acceptor to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.close [*close]]]
[Close the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.get_option [*get_option]]]
[Get an option from the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.is_open [*is_open]]]
[Determine whether the acceptor is open. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.listen [*listen]]]
[Place the acceptor into the state where it will listen for new connections. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.native [*native]]]
[Get the native acceptor representation. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.open [*open]]]
[Open the acceptor using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.set_option [*set_option]]]
[Set an option on the acceptor. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket_acceptor class template is used for accepting new socket connections.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[heading Example]
Opening a socket acceptor with the SO\_REUSEADDR option enabled:
boost::asio::ip::tcp::acceptor acceptor(io_service);
boost::asio::ip::tcp::endpoint endpoint(boost::asio::ip::tcp::v4(), port);
acceptor.open(endpoint.protocol());
acceptor.set_option(boost::asio::ip::tcp::acceptor::reuse_address(true));
acceptor.bind(endpoint);
acceptor.listen();
[section:accept basic_socket_acceptor::accept]
Accept a new connection.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
void ``[link boost_asio.reference.basic_socket_acceptor.accept.overload1 accept]``(
basic_socket< protocol_type, SocketService > & peer);
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.accept.overload2 accept]``(
basic_socket< protocol_type, SocketService > & peer,
boost::system::error_code & ec);
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
void ``[link boost_asio.reference.basic_socket_acceptor.accept.overload3 accept]``(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint);
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.accept.overload4 accept]``(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::accept (1 of 4 overloads)]
Accept a new connection.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
void accept(
basic_socket< protocol_type, SocketService > & peer);
This function is used to accept a new connection from a peer into the given socket. The function call will block until a new connection has been accepted successfully or an error occurs.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::socket socket(io_service);
acceptor.accept(socket);
[endsect]
[section:overload2 basic_socket_acceptor::accept (2 of 4 overloads)]
Accept a new connection.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
boost::system::error_code accept(
basic_socket< protocol_type, SocketService > & peer,
boost::system::error_code & ec);
This function is used to accept a new connection from a peer into the given socket. The function call will block until a new connection has been accepted successfully or an error occurs.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::soocket socket(io_service);
boost::system::error_code ec;
acceptor.accept(socket, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[section:overload3 basic_socket_acceptor::accept (3 of 4 overloads)]
Accept a new connection and obtain the endpoint of the peer.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
void accept(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint);
This function is used to accept a new connection from a peer into the given socket, and additionally provide the endpoint of the remote peer. The function call will block until a new connection has been accepted successfully or an error occurs.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted.]]
[[peer_endpoint][An endpoint object which will receive the endpoint of the remote peer.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint;
acceptor.accept(socket, endpoint);
[endsect]
[section:overload4 basic_socket_acceptor::accept (4 of 4 overloads)]
Accept a new connection and obtain the endpoint of the peer.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
boost::system::error_code accept(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint,
boost::system::error_code & ec);
This function is used to accept a new connection from a peer into the given socket, and additionally provide the endpoint of the remote peer. The function call will block until a new connection has been accepted successfully or an error occurs.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted.]]
[[peer_endpoint][An endpoint object which will receive the endpoint of the remote peer.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint;
boost::system::error_code ec;
acceptor.accept(socket, endpoint, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:assign basic_socket_acceptor::assign]
Assigns an existing native acceptor to the acceptor.
void ``[link boost_asio.reference.basic_socket_acceptor.assign.overload1 assign]``(
const protocol_type & protocol,
const native_type & native_acceptor);
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.assign.overload2 assign]``(
const protocol_type & protocol,
const native_type & native_acceptor,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::assign (1 of 2 overloads)]
Assigns an existing native acceptor to the acceptor.
void assign(
const protocol_type & protocol,
const native_type & native_acceptor);
[endsect]
[section:overload2 basic_socket_acceptor::assign (2 of 2 overloads)]
Assigns an existing native acceptor to the acceptor.
boost::system::error_code assign(
const protocol_type & protocol,
const native_type & native_acceptor,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:async_accept basic_socket_acceptor::async_accept]
Start an asynchronous accept.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``,
typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]``>
void ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload1 async_accept]``(
basic_socket< protocol_type, SocketService > & peer,
AcceptHandler handler);
template<
typename ``[link boost_asio.reference.SocketService SocketService]``,
typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]``>
void ``[link boost_asio.reference.basic_socket_acceptor.async_accept.overload2 async_accept]``(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint,
AcceptHandler handler);
[section:overload1 basic_socket_acceptor::async_accept (1 of 2 overloads)]
Start an asynchronous accept.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``,
typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]``>
void async_accept(
basic_socket< protocol_type, SocketService > & peer,
AcceptHandler handler);
This function is used to asynchronously accept a new connection into a socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted. Ownership of the peer object is retained by the caller, which must guarantee that it is valid until the handler is called.]]
[[handler][The handler to be called when the accept operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
void accept_handler(const boost::system::error_code& error)
{
if (!error)
{
// Accept succeeded.
}
}
...
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::socket socket(io_service);
acceptor.async_accept(socket, accept_handler);
[endsect]
[section:overload2 basic_socket_acceptor::async_accept (2 of 2 overloads)]
Start an asynchronous accept.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``,
typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]``>
void async_accept(
basic_socket< protocol_type, SocketService > & peer,
endpoint_type & peer_endpoint,
AcceptHandler handler);
This function is used to asynchronously accept a new connection into a socket, and additionally obtain the endpoint of the remote peer. The function call always returns immediately.
[heading Parameters]
[variablelist
[[peer][The socket into which the new connection will be accepted. Ownership of the peer object is retained by the caller, which must guarantee that it is valid until the handler is called.]]
[[peer_endpoint][An endpoint object into which the endpoint of the remote peer will be written. Ownership of the peer\_endpoint object is retained by the caller, which must guarantee that it is valid until the handler is called.]]
[[handler][The handler to be called when the accept operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post(). ]]
]
[endsect]
[endsect]
[section:basic_socket_acceptor basic_socket_acceptor::basic_socket_acceptor]
Construct an acceptor without opening it.
``[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor.overload1 basic_socket_acceptor]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor.overload2 basic_socket_acceptor]``(
boost::asio::io_service & io_service,
const protocol_type & protocol);
``[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor.overload3 basic_socket_acceptor]``(
boost::asio::io_service & io_service,
const endpoint_type & endpoint,
bool reuse_addr = true);
``[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor.overload4 basic_socket_acceptor]``(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_acceptor);
[section:overload1 basic_socket_acceptor::basic_socket_acceptor (1 of 4 overloads)]
Construct an acceptor without opening it.
basic_socket_acceptor(
boost::asio::io_service & io_service);
This constructor creates an acceptor without opening it to listen for new connections. The open() function must be called before the acceptor can accept new socket connections.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the acceptor will use to dispatch handlers for any asynchronous operations performed on the acceptor. ]]
]
[endsect]
[section:overload2 basic_socket_acceptor::basic_socket_acceptor (2 of 4 overloads)]
Construct an open acceptor.
basic_socket_acceptor(
boost::asio::io_service & io_service,
const protocol_type & protocol);
This constructor creates an acceptor and automatically opens it.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the acceptor will use to dispatch handlers for any asynchronous operations performed on the acceptor.]]
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_socket_acceptor::basic_socket_acceptor (3 of 4 overloads)]
Construct an acceptor opened on the given endpoint.
basic_socket_acceptor(
boost::asio::io_service & io_service,
const endpoint_type & endpoint,
bool reuse_addr = true);
This constructor creates an acceptor and automatically opens it to listen for new connections on the specified endpoint.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the acceptor will use to dispatch handlers for any asynchronous operations performed on the acceptor.]]
[[endpoint][An endpoint on the local machine on which the acceptor will listen for new connections.]]
[[reuse_addr][Whether the constructor should set the socket option socket\_base::reuse\_address.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
This constructor is equivalent to the following code:
basic_socket_acceptor<Protocol> acceptor(io_service);
acceptor.open(endpoint.protocol());
if (reuse_addr)
acceptor.set_option(socket_base::reuse_address(true));
acceptor.bind(endpoint);
acceptor.listen(listen_backlog);
[endsect]
[section:overload4 basic_socket_acceptor::basic_socket_acceptor (4 of 4 overloads)]
Construct a basic_socket_acceptor on an existing native acceptor.
basic_socket_acceptor(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_acceptor);
This constructor creates an acceptor object to hold an existing native acceptor.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the acceptor will use to dispatch handlers for any asynchronous operations performed on the acceptor.]]
[[protocol][An object specifying protocol parameters to be used.]]
[[native_acceptor][A native acceptor.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[endsect]
[section:bind basic_socket_acceptor::bind]
Bind the acceptor to the given local endpoint.
void ``[link boost_asio.reference.basic_socket_acceptor.bind.overload1 bind]``(
const endpoint_type & endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.bind.overload2 bind]``(
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::bind (1 of 2 overloads)]
Bind the acceptor to the given local endpoint.
void bind(
const endpoint_type & endpoint);
This function binds the socket acceptor to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket acceptor will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
acceptor.open(boost::asio::ip::tcp::v4());
acceptor.bind(boost::asio::ip::tcp::endpoint(12345));
[endsect]
[section:overload2 basic_socket_acceptor::bind (2 of 2 overloads)]
Bind the acceptor to the given local endpoint.
boost::system::error_code bind(
const endpoint_type & endpoint,
boost::system::error_code & ec);
This function binds the socket acceptor to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket acceptor will be bound.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
acceptor.open(boost::asio::ip::tcp::v4());
boost::system::error_code ec;
acceptor.bind(boost::asio::ip::tcp::endpoint(12345), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:broadcast basic_socket_acceptor::broadcast]
['Inherited from socket_base.]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable basic_socket_acceptor::bytes_readable]
['Inherited from socket_base.]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:cancel basic_socket_acceptor::cancel]
Cancel all asynchronous operations associated with the acceptor.
void ``[link boost_asio.reference.basic_socket_acceptor.cancel.overload1 cancel]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::cancel (1 of 2 overloads)]
Cancel all asynchronous operations associated with the acceptor.
void cancel();
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket_acceptor::cancel (2 of 2 overloads)]
Cancel all asynchronous operations associated with the acceptor.
boost::system::error_code cancel(
boost::system::error_code & ec);
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:close basic_socket_acceptor::close]
Close the acceptor.
void ``[link boost_asio.reference.basic_socket_acceptor.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::close (1 of 2 overloads)]
Close the acceptor.
void close();
This function is used to close the acceptor. Any asynchronous accept operations will be cancelled immediately.
A subsequent call to open() is required before the acceptor can again be used to again perform socket accept operations.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket_acceptor::close (2 of 2 overloads)]
Close the acceptor.
boost::system::error_code close(
boost::system::error_code & ec);
This function is used to close the acceptor. Any asynchronous accept operations will be cancelled immediately.
A subsequent call to open() is required before the acceptor can again be used to again perform socket accept operations.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::system::error_code ec;
acceptor.close(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:debug basic_socket_acceptor::debug]
['Inherited from socket_base.]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route basic_socket_acceptor::do_not_route]
['Inherited from socket_base.]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted basic_socket_acceptor::enable_connection_aborted]
['Inherited from socket_base.]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:endpoint_type basic_socket_acceptor::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service basic_socket_acceptor::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:get_option basic_socket_acceptor::get_option]
Get an option from the acceptor.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
void ``[link boost_asio.reference.basic_socket_acceptor.get_option.overload1 get_option]``(
GettableSocketOption & option);
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.get_option.overload2 get_option]``(
GettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::get_option (1 of 2 overloads)]
Get an option from the acceptor.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
void get_option(
GettableSocketOption & option);
This function is used to get the current value of an option on the acceptor.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the acceptor.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_REUSEADDR option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::acceptor::reuse_address option;
acceptor.get_option(option);
bool is_set = option.get();
[endsect]
[section:overload2 basic_socket_acceptor::get_option (2 of 2 overloads)]
Get an option from the acceptor.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code get_option(
GettableSocketOption & option,
boost::system::error_code & ec);
This function is used to get the current value of an option on the acceptor.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the acceptor.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_REUSEADDR option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::acceptor::reuse_address option;
boost::system::error_code ec;
acceptor.get_option(option, ec);
if (ec)
{
// An error occurred.
}
bool is_set = option.get();
[endsect]
[endsect]
[section:implementation_type basic_socket_acceptor::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_service basic_socket_acceptor::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:is_open basic_socket_acceptor::is_open]
Determine whether the acceptor is open.
bool is_open() const;
[endsect]
[section:keep_alive basic_socket_acceptor::keep_alive]
['Inherited from socket_base.]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger basic_socket_acceptor::linger]
['Inherited from socket_base.]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:listen basic_socket_acceptor::listen]
Place the acceptor into the state where it will listen for new connections.
void ``[link boost_asio.reference.basic_socket_acceptor.listen.overload1 listen]``(
int backlog = socket_base::max_connections);
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.listen.overload2 listen]``(
int backlog,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::listen (1 of 2 overloads)]
Place the acceptor into the state where it will listen for new connections.
void listen(
int backlog = socket_base::max_connections);
This function puts the socket acceptor into the state where it may accept new connections.
[heading Parameters]
[variablelist
[[backlog][The maximum length of the queue of pending connections.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket_acceptor::listen (2 of 2 overloads)]
Place the acceptor into the state where it will listen for new connections.
boost::system::error_code listen(
int backlog,
boost::system::error_code & ec);
This function puts the socket acceptor into the state where it may accept new connections.
[heading Parameters]
[variablelist
[[backlog][The maximum length of the queue of pending connections.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::system::error_code ec;
acceptor.listen(boost::asio::socket_base::max_connections, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:local_endpoint basic_socket_acceptor::local_endpoint]
Get the local endpoint of the acceptor.
endpoint_type ``[link boost_asio.reference.basic_socket_acceptor.local_endpoint.overload1 local_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_socket_acceptor.local_endpoint.overload2 local_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket_acceptor::local_endpoint (1 of 2 overloads)]
Get the local endpoint of the acceptor.
endpoint_type local_endpoint() const;
This function is used to obtain the locally bound endpoint of the acceptor.
[heading Return Value]
An object that represents the local endpoint of the acceptor.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = acceptor.local_endpoint();
[endsect]
[section:overload2 basic_socket_acceptor::local_endpoint (2 of 2 overloads)]
Get the local endpoint of the acceptor.
endpoint_type local_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the locally bound endpoint of the acceptor.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the local endpoint of the acceptor. Returns a default-constructed endpoint object if an error occurred and the error handler did not throw an exception.
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = acceptor.local_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:max_connections basic_socket_acceptor::max_connections]
['Inherited from socket_base.]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route basic_socket_acceptor::message_do_not_route]
['Inherited from socket_base.]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags basic_socket_acceptor::message_flags]
['Inherited from socket_base.]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band basic_socket_acceptor::message_out_of_band]
['Inherited from socket_base.]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek basic_socket_acceptor::message_peek]
['Inherited from socket_base.]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:native basic_socket_acceptor::native]
Get the native acceptor representation.
native_type native();
This function may be used to obtain the underlying representation of the acceptor. This is intended to allow access to native acceptor functionality that is not otherwise provided.
[endsect]
[section:native_type basic_socket_acceptor::native_type]
The native representation of an acceptor.
typedef SocketAcceptorService::native_type native_type;
[endsect]
[section:non_blocking_io basic_socket_acceptor::non_blocking_io]
['Inherited from socket_base.]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:open basic_socket_acceptor::open]
Open the acceptor using the specified protocol.
void ``[link boost_asio.reference.basic_socket_acceptor.open.overload1 open]``(
const protocol_type & protocol = protocol_type());
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.open.overload2 open]``(
const protocol_type & protocol,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::open (1 of 2 overloads)]
Open the acceptor using the specified protocol.
void open(
const protocol_type & protocol = protocol_type());
This function opens the socket acceptor so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
acceptor.open(boost::asio::ip::tcp::v4());
[endsect]
[section:overload2 basic_socket_acceptor::open (2 of 2 overloads)]
Open the acceptor using the specified protocol.
boost::system::error_code open(
const protocol_type & protocol,
boost::system::error_code & ec);
This function opens the socket acceptor so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::acceptor acceptor(io_service);
boost::system::error_code ec;
acceptor.open(boost::asio::ip::tcp::v4(), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:protocol_type basic_socket_acceptor::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive_buffer_size basic_socket_acceptor::receive_buffer_size]
['Inherited from socket_base.]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_low_watermark basic_socket_acceptor::receive_low_watermark]
['Inherited from socket_base.]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:reuse_address basic_socket_acceptor::reuse_address]
['Inherited from socket_base.]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send_buffer_size basic_socket_acceptor::send_buffer_size]
['Inherited from socket_base.]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark basic_socket_acceptor::send_low_watermark]
['Inherited from socket_base.]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:service_type basic_socket_acceptor::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef SocketAcceptorService service_type;
[endsect]
[section:set_option basic_socket_acceptor::set_option]
Set an option on the acceptor.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
void ``[link boost_asio.reference.basic_socket_acceptor.set_option.overload1 set_option]``(
const SettableSocketOption & option);
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code ``[link boost_asio.reference.basic_socket_acceptor.set_option.overload2 set_option]``(
const SettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_socket_acceptor::set_option (1 of 2 overloads)]
Set an option on the acceptor.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
void set_option(
const SettableSocketOption & option);
This function is used to set an option on the acceptor.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the acceptor.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Setting the SOL\_SOCKET/SO\_REUSEADDR option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::acceptor::reuse_address option(true);
acceptor.set_option(option);
[endsect]
[section:overload2 basic_socket_acceptor::set_option (2 of 2 overloads)]
Set an option on the acceptor.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code set_option(
const SettableSocketOption & option,
boost::system::error_code & ec);
This function is used to set an option on the acceptor.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the acceptor.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Setting the SOL\_SOCKET/SO\_REUSEADDR option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::ip::tcp::acceptor::reuse_address option(true);
boost::system::error_code ec;
acceptor.set_option(option, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown_type basic_socket_acceptor::shutdown_type]
['Inherited from socket_base.]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[endsect]
[section:basic_socket_iostream basic_socket_iostream]
Iostream interface for a socket.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.StreamSocketService StreamSocketService]`` = stream_socket_service<Protocol>>
class basic_socket_iostream
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_iostream.basic_socket_iostream [*basic_socket_iostream]]]
[Construct a basic_socket_iostream without establishing a connection. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.close [*close]]]
[Close the connection. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.connect [*connect]]]
[Establish a connection to an endpoint corresponding to a resolver query. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.rdbuf [*rdbuf]]]
[Return a pointer to the underlying streambuf. ]
]
]
[section:basic_socket_iostream basic_socket_iostream::basic_socket_iostream]
Construct a basic_socket_iostream without establishing a connection.
``[link boost_asio.reference.basic_socket_iostream.basic_socket_iostream.overload1 basic_socket_iostream]``();
template<
typename T1,
... ,
typename TN>
``[link boost_asio.reference.basic_socket_iostream.basic_socket_iostream.overload2 basic_socket_iostream]``(
T1 t1,
... ,
TN tn);
[section:overload1 basic_socket_iostream::basic_socket_iostream (1 of 2 overloads)]
Construct a basic_socket_iostream without establishing a connection.
basic_socket_iostream();
[endsect]
[section:overload2 basic_socket_iostream::basic_socket_iostream (2 of 2 overloads)]
Establish a connection to an endpoint corresponding to a resolver query.
template<
typename T1,
... ,
typename TN>
basic_socket_iostream(
T1 t1,
... ,
TN tn);
This constructor automatically establishes a connection based on the supplied resolver query parameters. The arguments are used to construct a resolver query object.
[endsect]
[endsect]
[section:close basic_socket_iostream::close]
Close the connection.
void close();
[endsect]
[section:connect basic_socket_iostream::connect]
Establish a connection to an endpoint corresponding to a resolver query.
template<
typename T1,
... ,
typename TN>
void connect(
T1 t1,
... ,
TN tn);
This function automatically establishes a connection based on the supplied resolver query parameters. The arguments are used to construct a resolver query object.
[endsect]
[section:rdbuf basic_socket_iostream::rdbuf]
Return a pointer to the underlying streambuf.
basic_socket_streambuf< Protocol, StreamSocketService > * rdbuf() const;
[endsect]
[endsect]
[section:basic_socket_streambuf basic_socket_streambuf]
Iostream streambuf for a socket.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.StreamSocketService StreamSocketService]`` = stream_socket_service<Protocol>>
class basic_socket_streambuf :
public basic_socket< Protocol, StreamSocketService >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_streambuf.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_streambuf.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.basic_socket_streambuf [*basic_socket_streambuf]]]
[Construct a basic_socket_streambuf without establishing a connection. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.close [*close]]]
[Close the connection. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.connect [*connect]]]
[Establish a connection. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf._basic_socket_streambuf [*~basic_socket_streambuf]]]
[Destructor flushes buffered data. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_streambuf.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket_streambuf.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
[section:assign basic_socket_streambuf::assign]
Assign an existing native socket to the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.assign.overload1 assign]``(
const protocol_type & protocol,
const native_type & native_socket);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.assign.overload2 assign]``(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::assign (1 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
void assign(
const protocol_type & protocol,
const native_type & native_socket);
[endsect]
[section:overload2 basic_socket_streambuf::assign (2 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
boost::system::error_code assign(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:async_connect basic_socket_streambuf::async_connect]
['Inherited from basic_socket.]
Start an asynchronous connect.
void async_connect(
const endpoint_type & peer_endpoint,
ConnectHandler handler);
This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]]
[[handler][The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
void connect_handler(const boost::system::error_code& error)
{
if (!error)
{
// Connect succeeded.
}
}
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_connect(endpoint, connect_handler);
[endsect]
[section:at_mark basic_socket_streambuf::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool ``[link boost_asio.reference.basic_socket_streambuf.at_mark.overload1 at_mark]``() const;
bool ``[link boost_asio.reference.basic_socket_streambuf.at_mark.overload2 at_mark]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket_streambuf::at_mark (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark() const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket_streambuf::at_mark (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
boost::system::error_code & ec) const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[endsect]
[endsect]
[section:available basic_socket_streambuf::available]
Determine the number of bytes available for reading.
std::size_t ``[link boost_asio.reference.basic_socket_streambuf.available.overload1 available]``() const;
std::size_t ``[link boost_asio.reference.basic_socket_streambuf.available.overload2 available]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket_streambuf::available (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available() const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_socket_streambuf::available (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available(
boost::system::error_code & ec) const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[endsect]
[endsect]
[section:basic_socket_streambuf basic_socket_streambuf::basic_socket_streambuf]
Construct a basic_socket_streambuf without establishing a connection.
basic_socket_streambuf();
[endsect]
[section:bind basic_socket_streambuf::bind]
Bind the socket to the given local endpoint.
void ``[link boost_asio.reference.basic_socket_streambuf.bind.overload1 bind]``(
const endpoint_type & endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.bind.overload2 bind]``(
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::bind (1 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
void bind(
const endpoint_type & endpoint);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345));
[endsect]
[section:overload2 basic_socket_streambuf::bind (2 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
boost::system::error_code bind(
const endpoint_type & endpoint,
boost::system::error_code & ec);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
boost::system::error_code ec;
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:broadcast basic_socket_streambuf::broadcast]
['Inherited from socket_base.]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable basic_socket_streambuf::bytes_readable]
['Inherited from socket_base.]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:cancel basic_socket_streambuf::cancel]
Cancel all asynchronous operations associated with the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.cancel.overload1 cancel]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::cancel (1 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
void cancel();
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[section:overload2 basic_socket_streambuf::cancel (2 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
boost::system::error_code & ec);
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[endsect]
[section:close basic_socket_streambuf::close]
Close the connection.
basic_socket_streambuf< Protocol, StreamSocketService > * ``[link boost_asio.reference.basic_socket_streambuf.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::close (1 of 2 overloads)]
Close the connection.
basic_socket_streambuf< Protocol, StreamSocketService > * close();
[heading Return Value]
this if a connection was successfully established, a null pointer otherwise.
[endsect]
[section:overload2 basic_socket_streambuf::close (2 of 2 overloads)]
['Inherited from basic_socket.]
Close the socket.
boost::system::error_code close(
boost::system::error_code & ec);
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.close(ec);
if (ec)
{
// An error occurred.
}
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[endsect]
[section:connect basic_socket_streambuf::connect]
Establish a connection.
basic_socket_streambuf< Protocol, StreamSocketService > * ``[link boost_asio.reference.basic_socket_streambuf.connect.overload1 connect]``(
const endpoint_type & endpoint);
template<
typename T1,
... ,
typename TN>
basic_socket_streambuf< Protocol, StreamSocketService > * ``[link boost_asio.reference.basic_socket_streambuf.connect.overload2 connect]``(
T1 t1,
... ,
TN tn);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.connect.overload3 connect]``(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::connect (1 of 3 overloads)]
Establish a connection.
basic_socket_streambuf< Protocol, StreamSocketService > * connect(
const endpoint_type & endpoint);
This function establishes a connection to the specified endpoint.
[heading Return Value]
this if a connection was successfully established, a null pointer otherwise.
[endsect]
[section:overload2 basic_socket_streambuf::connect (2 of 3 overloads)]
Establish a connection.
template<
typename T1,
... ,
typename TN>
basic_socket_streambuf< Protocol, StreamSocketService > * connect(
T1 t1,
... ,
TN tn);
This function automatically establishes a connection based on the supplied resolver query parameters. The arguments are used to construct a resolver query object.
[heading Return Value]
this if a connection was successfully established, a null pointer otherwise.
[endsect]
[section:overload3 basic_socket_streambuf::connect (3 of 3 overloads)]
['Inherited from basic_socket.]
Connect the socket to the specified endpoint.
boost::system::error_code connect(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
boost::system::error_code ec;
socket.connect(endpoint, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:debug basic_socket_streambuf::debug]
['Inherited from socket_base.]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route basic_socket_streambuf::do_not_route]
['Inherited from socket_base.]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted basic_socket_streambuf::enable_connection_aborted]
['Inherited from socket_base.]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:endpoint_type basic_socket_streambuf::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service basic_socket_streambuf::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:get_option basic_socket_streambuf::get_option]
Get an option from the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.get_option.overload1 get_option]``(
GettableSocketOption & option) const;
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.get_option.overload2 get_option]``(
GettableSocketOption & option,
boost::system::error_code & ec) const;
[section:overload1 basic_socket_streambuf::get_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
void get_option(
GettableSocketOption & option) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
socket.get_option(option);
bool is_set = option.get();
[endsect]
[section:overload2 basic_socket_streambuf::get_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
boost::system::error_code get_option(
GettableSocketOption & option,
boost::system::error_code & ec) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
boost::system::error_code ec;
socket.get_option(option, ec);
if (ec)
{
// An error occurred.
}
bool is_set = option.get();
[endsect]
[endsect]
[section:implementation_type basic_socket_streambuf::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_control basic_socket_streambuf::io_control]
Perform an IO control command on the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.io_control.overload1 io_control]``(
IoControlCommand & command);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.io_control.overload2 io_control]``(
IoControlCommand & command,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::io_control (1 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
void io_control(
IoControlCommand & command);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:overload2 basic_socket_streambuf::io_control (2 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
boost::system::error_code io_control(
IoControlCommand & command,
boost::system::error_code & ec);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
boost::system::error_code ec;
socket.io_control(command, ec);
if (ec)
{
// An error occurred.
}
std::size_t bytes_readable = command.get();
[endsect]
[endsect]
[section:io_service basic_socket_streambuf::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:is_open basic_socket_streambuf::is_open]
['Inherited from basic_socket.]
Determine whether the socket is open.
bool is_open() const;
[endsect]
[section:keep_alive basic_socket_streambuf::keep_alive]
['Inherited from socket_base.]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger basic_socket_streambuf::linger]
['Inherited from socket_base.]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:local_endpoint basic_socket_streambuf::local_endpoint]
Get the local endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_socket_streambuf.local_endpoint.overload1 local_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_socket_streambuf.local_endpoint.overload2 local_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket_streambuf::local_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint() const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Return Value]
An object that represents the local endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
[endsect]
[section:overload2 basic_socket_streambuf::local_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the local endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:lowest_layer basic_socket_streambuf::lowest_layer]
['Inherited from basic_socket.]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
This function returns a reference to the lowest layer in a stack of layers. Since a basic_socket cannot contain any further layers, it simply returns a reference to itself.
[heading Return Value]
A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer_type basic_socket_streambuf::lowest_layer_type]
['Inherited from basic_socket.]
A basic_socket is always the lowest layer.
typedef basic_socket< Protocol, StreamSocketService > lowest_layer_type;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]]
[Construct a basic_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket class template provides functionality that is common to both stream-oriented and datagram-oriented sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:max_connections basic_socket_streambuf::max_connections]
['Inherited from socket_base.]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route basic_socket_streambuf::message_do_not_route]
['Inherited from socket_base.]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags basic_socket_streambuf::message_flags]
['Inherited from socket_base.]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band basic_socket_streambuf::message_out_of_band]
['Inherited from socket_base.]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek basic_socket_streambuf::message_peek]
['Inherited from socket_base.]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:native basic_socket_streambuf::native]
['Inherited from basic_socket.]
Get the native socket representation.
native_type native();
This function may be used to obtain the underlying representation of the socket. This is intended to allow access to native socket functionality that is not otherwise provided.
[endsect]
[section:native_type basic_socket_streambuf::native_type]
['Inherited from basic_socket.]
The native representation of a socket.
typedef StreamSocketService::native_type native_type;
[endsect]
[section:non_blocking_io basic_socket_streambuf::non_blocking_io]
['Inherited from socket_base.]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:open basic_socket_streambuf::open]
Open the socket using the specified protocol.
void ``[link boost_asio.reference.basic_socket_streambuf.open.overload1 open]``(
const protocol_type & protocol = protocol_type());
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.open.overload2 open]``(
const protocol_type & protocol,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::open (1 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
void open(
const protocol_type & protocol = protocol_type());
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
[endsect]
[section:overload2 basic_socket_streambuf::open (2 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
boost::system::error_code open(
const protocol_type & protocol,
boost::system::error_code & ec);
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::system::error_code ec;
socket.open(boost::asio::ip::tcp::v4(), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:protocol_type basic_socket_streambuf::protocol_type]
['Inherited from basic_socket.]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive_buffer_size basic_socket_streambuf::receive_buffer_size]
['Inherited from socket_base.]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_low_watermark basic_socket_streambuf::receive_low_watermark]
['Inherited from socket_base.]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:remote_endpoint basic_socket_streambuf::remote_endpoint]
Get the remote endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_socket_streambuf.remote_endpoint.overload1 remote_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_socket_streambuf.remote_endpoint.overload2 remote_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_socket_streambuf::remote_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint() const;
This function is used to obtain the remote endpoint of the socket.
[heading Return Value]
An object that represents the remote endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
[endsect]
[section:overload2 basic_socket_streambuf::remote_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the remote endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the remote endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:reuse_address basic_socket_streambuf::reuse_address]
['Inherited from socket_base.]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send_buffer_size basic_socket_streambuf::send_buffer_size]
['Inherited from socket_base.]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark basic_socket_streambuf::send_low_watermark]
['Inherited from socket_base.]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:service_type basic_socket_streambuf::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef StreamSocketService service_type;
[endsect]
[section:set_option basic_socket_streambuf::set_option]
Set an option on the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.set_option.overload1 set_option]``(
const SettableSocketOption & option);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.set_option.overload2 set_option]``(
const SettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::set_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
void set_option(
const SettableSocketOption & option);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
socket.set_option(option);
[endsect]
[section:overload2 basic_socket_streambuf::set_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
boost::system::error_code set_option(
const SettableSocketOption & option,
boost::system::error_code & ec);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
boost::system::error_code ec;
socket.set_option(option, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown basic_socket_streambuf::shutdown]
Disable sends or receives on the socket.
void ``[link boost_asio.reference.basic_socket_streambuf.shutdown.overload1 shutdown]``(
shutdown_type what);
boost::system::error_code ``[link boost_asio.reference.basic_socket_streambuf.shutdown.overload2 shutdown]``(
shutdown_type what,
boost::system::error_code & ec);
[section:overload1 basic_socket_streambuf::shutdown (1 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
void shutdown(
shutdown_type what);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
[endsect]
[section:overload2 basic_socket_streambuf::shutdown (2 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
shutdown_type what,
boost::system::error_code & ec);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown_type basic_socket_streambuf::shutdown_type]
['Inherited from socket_base.]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[section:_basic_socket_streambuf basic_socket_streambuf::~basic_socket_streambuf]
Destructor flushes buffered data.
virtual ~basic_socket_streambuf();
[endsect]
[endsect]
[section:basic_stream_socket basic_stream_socket]
Provides stream-oriented socket functionality.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``,
typename ``[link boost_asio.reference.StreamSocketService StreamSocketService]`` = stream_socket_service<Protocol>>
class basic_stream_socket :
public basic_socket< Protocol, StreamSocketService >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_stream_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_stream_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_stream_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_stream_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_stream_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_stream_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_stream_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_stream_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_stream_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_stream_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_read_some [*async_read_some]]]
[Start an asynchronous read. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_receive [*async_receive]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_send [*async_send]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_write_some [*async_write_some]]]
[Start an asynchronous write. ]
]
[
[[link boost_asio.reference.basic_stream_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_stream_socket.basic_stream_socket [*basic_stream_socket]]]
[Construct a basic_stream_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_stream_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_stream_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_stream_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_stream_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_stream_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_stream_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_stream_socket.read_some [*read_some]]]
[Read some data from the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive [*receive]]]
[Receive some data on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send [*send]]]
[Send some data on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.write_some [*write_some]]]
[Write some data to the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_stream_socket class template provides asynchronous and blocking stream-oriented socket functionality.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:assign basic_stream_socket::assign]
Assign an existing native socket to the socket.
void ``[link boost_asio.reference.basic_stream_socket.assign.overload1 assign]``(
const protocol_type & protocol,
const native_type & native_socket);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.assign.overload2 assign]``(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::assign (1 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
void assign(
const protocol_type & protocol,
const native_type & native_socket);
[endsect]
[section:overload2 basic_stream_socket::assign (2 of 2 overloads)]
['Inherited from basic_socket.]
Assign an existing native socket to the socket.
boost::system::error_code assign(
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:async_connect basic_stream_socket::async_connect]
['Inherited from basic_socket.]
Start an asynchronous connect.
void async_connect(
const endpoint_type & peer_endpoint,
ConnectHandler handler);
This function is used to asynchronously connect a socket to the specified remote endpoint. The function call always returns immediately.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected. Copies will be made of the endpoint object as required.]]
[[handler][The handler to be called when the connection operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Example]
void connect_handler(const boost::system::error_code& error)
{
if (!error)
{
// Connect succeeded.
}
}
...
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.async_connect(endpoint, connect_handler);
[endsect]
[section:async_read_some basic_stream_socket::async_read_some]
Start an asynchronous read.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
const MutableBufferSequence & buffers,
ReadHandler handler);
This function is used to asynchronously read data from the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes read.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The read operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.async_read async_read] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_read_some(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:async_receive basic_stream_socket::async_receive]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_stream_socket.async_receive.overload1 async_receive]``(
const MutableBufferSequence & buffers,
ReadHandler handler);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void ``[link boost_asio.reference.basic_stream_socket.async_receive.overload2 async_receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
[section:overload1 basic_stream_socket::async_receive (1 of 2 overloads)]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
const MutableBufferSequence & buffers,
ReadHandler handler);
This function is used to asynchronously receive data from the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The receive operation may not receive all of the requested number of bytes. Consider using the
[link boost_asio.reference.async_read async_read] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_receive(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::async_receive (2 of 2 overloads)]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
This function is used to asynchronously receive data from the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[handler][The handler to be called when the receive operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes received.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The receive operation may not receive all of the requested number of bytes. Consider using the
[link boost_asio.reference.async_read async_read] function if you need to ensure that the requested amount of data is received before the asynchronous operation completes.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_receive(boost::asio::buffer(data, size), 0, handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[endsect]
[section:async_send basic_stream_socket::async_send]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_stream_socket.async_send.overload1 async_send]``(
const ConstBufferSequence & buffers,
WriteHandler handler);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void ``[link boost_asio.reference.basic_stream_socket.async_send.overload2 async_send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
[section:overload1 basic_stream_socket::async_send (1 of 2 overloads)]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
const ConstBufferSequence & buffers,
WriteHandler handler);
This function is used to asynchronously send data on the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The send operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.async_write async_write] function if you need to ensure that all data is written before the asynchronous operation completes.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_send(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::async_send (2 of 2 overloads)]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
This function is used to asynchronously send data on the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[flags][Flags specifying how the send call is to be made.]]
[[handler][The handler to be called when the send operation completes. Copies will be made of the handler as required. The function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes sent.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The send operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.async_write async_write] function if you need to ensure that all data is written before the asynchronous operation completes.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_send(boost::asio::buffer(data, size), 0, handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[endsect]
[section:async_write_some basic_stream_socket::async_write_some]
Start an asynchronous write.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
const ConstBufferSequence & buffers,
WriteHandler handler);
This function is used to asynchronously write data to the stream socket. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be written to the socket. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the 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.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
The write operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.async_write async_write] function if you need to ensure that all data is written before the asynchronous operation completes.
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.async_write_some(boost::asio::buffer(data, size), handler);
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:at_mark basic_stream_socket::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool ``[link boost_asio.reference.basic_stream_socket.at_mark.overload1 at_mark]``() const;
bool ``[link boost_asio.reference.basic_stream_socket.at_mark.overload2 at_mark]``(
boost::system::error_code & ec) const;
[section:overload1 basic_stream_socket::at_mark (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark() const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_stream_socket::at_mark (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
boost::system::error_code & ec) const;
This function is used to check whether the socket input is currently positioned at the out-of-band data mark.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A bool indicating whether the socket is at the out-of-band data mark.
[endsect]
[endsect]
[section:available basic_stream_socket::available]
Determine the number of bytes available for reading.
std::size_t ``[link boost_asio.reference.basic_stream_socket.available.overload1 available]``() const;
std::size_t ``[link boost_asio.reference.basic_stream_socket.available.overload2 available]``(
boost::system::error_code & ec) const;
[section:overload1 basic_stream_socket::available (1 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available() const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 basic_stream_socket::available (2 of 2 overloads)]
['Inherited from basic_socket.]
Determine the number of bytes available for reading.
std::size_t available(
boost::system::error_code & ec) const;
This function is used to determine the number of bytes that may be read without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes that may be read without blocking, or 0 if an error occurs.
[endsect]
[endsect]
[section:basic_stream_socket basic_stream_socket::basic_stream_socket]
Construct a basic_stream_socket without opening it.
``[link boost_asio.reference.basic_stream_socket.basic_stream_socket.overload1 basic_stream_socket]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.basic_stream_socket.basic_stream_socket.overload2 basic_stream_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol);
``[link boost_asio.reference.basic_stream_socket.basic_stream_socket.overload3 basic_stream_socket]``(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
``[link boost_asio.reference.basic_stream_socket.basic_stream_socket.overload4 basic_stream_socket]``(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
[section:overload1 basic_stream_socket::basic_stream_socket (1 of 4 overloads)]
Construct a basic_stream_socket without opening it.
basic_stream_socket(
boost::asio::io_service & io_service);
This constructor creates a stream socket without opening it. The socket needs to be opened and then connected or accepted before data can be sent or received on it.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the stream socket will use to dispatch handlers for any asynchronous operations performed on the socket. ]]
]
[endsect]
[section:overload2 basic_stream_socket::basic_stream_socket (2 of 4 overloads)]
Construct and open a basic_stream_socket.
basic_stream_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol);
This constructor creates and opens a stream socket. The socket needs to be connected or accepted before data can be sent or received on it.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the stream socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload3 basic_stream_socket::basic_stream_socket (3 of 4 overloads)]
Construct a basic_stream_socket, opening it and binding it to the given local endpoint.
basic_stream_socket(
boost::asio::io_service & io_service,
const endpoint_type & endpoint);
This constructor creates a stream socket and automatically opens it bound to the specified endpoint on the local machine. The protocol used is the protocol associated with the given endpoint.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the stream socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[endpoint][An endpoint on the local machine to which the stream socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload4 basic_stream_socket::basic_stream_socket (4 of 4 overloads)]
Construct a basic_stream_socket on an existing native socket.
basic_stream_socket(
boost::asio::io_service & io_service,
const protocol_type & protocol,
const native_type & native_socket);
This constructor creates a stream socket object to hold an existing native socket.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the stream socket will use to dispatch handlers for any asynchronous operations performed on the socket.]]
[[protocol][An object specifying protocol parameters to be used.]]
[[native_socket][The new underlying socket implementation.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[endsect]
[section:bind basic_stream_socket::bind]
Bind the socket to the given local endpoint.
void ``[link boost_asio.reference.basic_stream_socket.bind.overload1 bind]``(
const endpoint_type & endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.bind.overload2 bind]``(
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::bind (1 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
void bind(
const endpoint_type & endpoint);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345));
[endsect]
[section:overload2 basic_stream_socket::bind (2 of 2 overloads)]
['Inherited from basic_socket.]
Bind the socket to the given local endpoint.
boost::system::error_code bind(
const endpoint_type & endpoint,
boost::system::error_code & ec);
This function binds the socket to the specified endpoint on the local machine.
[heading Parameters]
[variablelist
[[endpoint][An endpoint on the local machine to which the socket will be bound.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
boost::system::error_code ec;
socket.bind(boost::asio::ip::tcp::endpoint(
boost::asio::ip::tcp::v4(), 12345), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:broadcast basic_stream_socket::broadcast]
['Inherited from socket_base.]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable basic_stream_socket::bytes_readable]
['Inherited from socket_base.]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:cancel basic_stream_socket::cancel]
Cancel all asynchronous operations associated with the socket.
void ``[link boost_asio.reference.basic_stream_socket.cancel.overload1 cancel]``();
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.cancel.overload2 cancel]``(
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::cancel (1 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
void cancel();
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[section:overload2 basic_stream_socket::cancel (2 of 2 overloads)]
['Inherited from basic_socket.]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
boost::system::error_code & ec);
This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Remarks]
Calls to cancel() will always fail with boost::asio::error::operation\_not\_supported when run on Windows XP, Windows Server 2003, and earlier versions of Windows, unless BOOST\_ASIO\_ENABLE\_CANCELIO is defined. However, the CancelIo function has two issues that should be considered before enabling its use:
* It will only cancel asynchronous operations that were initiated in the current thread.
* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.
For portable cancellation, consider using one of the following alternatives:
* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.
* Use the close() function to simultaneously cancel the outstanding operations and close the socket.
When running on Windows Vista, Windows Server 2008, and later, the CancelIoEx function is always used. This function does not have the problems described above.
[endsect]
[endsect]
[section:close basic_stream_socket::close]
Close the socket.
void ``[link boost_asio.reference.basic_stream_socket.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::close (1 of 2 overloads)]
['Inherited from basic_socket.]
Close the socket.
void close();
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[section:overload2 basic_stream_socket::close (2 of 2 overloads)]
['Inherited from basic_socket.]
Close the socket.
boost::system::error_code close(
boost::system::error_code & ec);
This function is used to close the socket. Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation\_aborted error.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.close(ec);
if (ec)
{
// An error occurred.
}
[heading Remarks]
For portable behaviour with respect to graceful closure of a connected socket, call shutdown() before closing the socket.
[endsect]
[endsect]
[section:connect basic_stream_socket::connect]
Connect the socket to the specified endpoint.
void ``[link boost_asio.reference.basic_stream_socket.connect.overload1 connect]``(
const endpoint_type & peer_endpoint);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.connect.overload2 connect]``(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::connect (1 of 2 overloads)]
['Inherited from basic_socket.]
Connect the socket to the specified endpoint.
void connect(
const endpoint_type & peer_endpoint);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
socket.connect(endpoint);
[endsect]
[section:overload2 basic_stream_socket::connect (2 of 2 overloads)]
['Inherited from basic_socket.]
Connect the socket to the specified endpoint.
boost::system::error_code connect(
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
This function is used to connect a socket to the specified remote endpoint. The function call will block until the connection is successfully made or an error occurs.
The socket is automatically opened if it is not already open. If the connect fails, and the socket was automatically opened, the socket is returned to the closed state.
[heading Parameters]
[variablelist
[[peer_endpoint][The remote endpoint to which the socket will be connected.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::asio::ip::tcp::endpoint endpoint(
boost::asio::ip::address::from_string("1.2.3.4"), 12345);
boost::system::error_code ec;
socket.connect(endpoint, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:debug basic_stream_socket::debug]
['Inherited from socket_base.]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route basic_stream_socket::do_not_route]
['Inherited from socket_base.]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted basic_stream_socket::enable_connection_aborted]
['Inherited from socket_base.]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:endpoint_type basic_stream_socket::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service basic_stream_socket::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:get_option basic_stream_socket::get_option]
Get an option from the socket.
void ``[link boost_asio.reference.basic_stream_socket.get_option.overload1 get_option]``(
GettableSocketOption & option) const;
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.get_option.overload2 get_option]``(
GettableSocketOption & option,
boost::system::error_code & ec) const;
[section:overload1 basic_stream_socket::get_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
void get_option(
GettableSocketOption & option) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
socket.get_option(option);
bool is_set = option.get();
[endsect]
[section:overload2 basic_stream_socket::get_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Get an option from the socket.
boost::system::error_code get_option(
GettableSocketOption & option,
boost::system::error_code & ec) const;
This function is used to get the current value of an option on the socket.
[heading Parameters]
[variablelist
[[option][The option value to be obtained from the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the value of the SOL\_SOCKET/SO\_KEEPALIVE option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::keep_alive option;
boost::system::error_code ec;
socket.get_option(option, ec);
if (ec)
{
// An error occurred.
}
bool is_set = option.get();
[endsect]
[endsect]
[section:implementation_type basic_stream_socket::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_control basic_stream_socket::io_control]
Perform an IO control command on the socket.
void ``[link boost_asio.reference.basic_stream_socket.io_control.overload1 io_control]``(
IoControlCommand & command);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.io_control.overload2 io_control]``(
IoControlCommand & command,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::io_control (1 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
void io_control(
IoControlCommand & command);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:overload2 basic_stream_socket::io_control (2 of 2 overloads)]
['Inherited from basic_socket.]
Perform an IO control command on the socket.
boost::system::error_code io_control(
IoControlCommand & command,
boost::system::error_code & ec);
This function is used to execute an IO control command on the socket.
[heading Parameters]
[variablelist
[[command][The IO control command to be performed on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Getting the number of bytes ready to read:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::socket::bytes_readable command;
boost::system::error_code ec;
socket.io_control(command, ec);
if (ec)
{
// An error occurred.
}
std::size_t bytes_readable = command.get();
[endsect]
[endsect]
[section:io_service basic_stream_socket::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:is_open basic_stream_socket::is_open]
['Inherited from basic_socket.]
Determine whether the socket is open.
bool is_open() const;
[endsect]
[section:keep_alive basic_stream_socket::keep_alive]
['Inherited from socket_base.]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger basic_stream_socket::linger]
['Inherited from socket_base.]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:local_endpoint basic_stream_socket::local_endpoint]
Get the local endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_stream_socket.local_endpoint.overload1 local_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_stream_socket.local_endpoint.overload2 local_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_stream_socket::local_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint() const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Return Value]
An object that represents the local endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
[endsect]
[section:overload2 basic_stream_socket::local_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the local endpoint of the socket.
endpoint_type local_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the locally bound endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the local endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:lowest_layer basic_stream_socket::lowest_layer]
['Inherited from basic_socket.]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
This function returns a reference to the lowest layer in a stack of layers. Since a basic_socket cannot contain any further layers, it simply returns a reference to itself.
[heading Return Value]
A reference to the lowest layer in the stack of layers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer_type basic_stream_socket::lowest_layer_type]
['Inherited from basic_socket.]
A basic_socket is always the lowest layer.
typedef basic_socket< Protocol, StreamSocketService > lowest_layer_type;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_socket.basic_socket [*basic_socket]]]
[Construct a basic_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket class template provides functionality that is common to both stream-oriented and datagram-oriented sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:max_connections basic_stream_socket::max_connections]
['Inherited from socket_base.]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route basic_stream_socket::message_do_not_route]
['Inherited from socket_base.]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags basic_stream_socket::message_flags]
['Inherited from socket_base.]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band basic_stream_socket::message_out_of_band]
['Inherited from socket_base.]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek basic_stream_socket::message_peek]
['Inherited from socket_base.]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:native basic_stream_socket::native]
['Inherited from basic_socket.]
Get the native socket representation.
native_type native();
This function may be used to obtain the underlying representation of the socket. This is intended to allow access to native socket functionality that is not otherwise provided.
[endsect]
[section:native_type basic_stream_socket::native_type]
The native representation of a socket.
typedef StreamSocketService::native_type native_type;
[endsect]
[section:non_blocking_io basic_stream_socket::non_blocking_io]
['Inherited from socket_base.]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:open basic_stream_socket::open]
Open the socket using the specified protocol.
void ``[link boost_asio.reference.basic_stream_socket.open.overload1 open]``(
const protocol_type & protocol = protocol_type());
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.open.overload2 open]``(
const protocol_type & protocol,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::open (1 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
void open(
const protocol_type & protocol = protocol_type());
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying protocol parameters to be used.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
socket.open(boost::asio::ip::tcp::v4());
[endsect]
[section:overload2 basic_stream_socket::open (2 of 2 overloads)]
['Inherited from basic_socket.]
Open the socket using the specified protocol.
boost::system::error_code open(
const protocol_type & protocol,
boost::system::error_code & ec);
This function opens the socket so that it will use the specified protocol.
[heading Parameters]
[variablelist
[[protocol][An object specifying which protocol is to be used.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
boost::system::error_code ec;
socket.open(boost::asio::ip::tcp::v4(), ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:protocol_type basic_stream_socket::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:read_some basic_stream_socket::read_some]
Read some data from the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.read_some.overload1 read_some]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.read_some.overload2 read_some]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::read_some (1 of 2 overloads)]
Read some data from the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers);
This function is used to read data from the stream socket. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be read.]]
]
[heading Return Value]
The number of bytes read.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the peer.]]
]
[heading Remarks]
The read\_some operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.read_some(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::read_some (2 of 2 overloads)]
Read some data from the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
This function is used to read data from the stream socket. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be read.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes read. Returns 0 if an error occurred.
[heading Remarks]
The read\_some operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[endsect]
[endsect]
[section:receive basic_stream_socket::receive]
Receive some data on the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.receive.overload1 receive]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.receive.overload2 receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.receive.overload3 receive]``(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::receive (1 of 3 overloads)]
Receive some data on the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers);
This function is used to receive data on the stream socket. The function call will block until one or more bytes of data has been received successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the peer.]]
]
[heading Remarks]
The receive operation may not receive all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.receive(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::receive (2 of 3 overloads)]
Receive some data on the socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags);
This function is used to receive data on the stream socket. The function call will block until one or more bytes of data has been received successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[flags][Flags specifying how the receive call is to be made.]]
]
[heading Return Value]
The number of bytes received.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the peer.]]
]
[heading Remarks]
The receive operation may not receive all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[heading Example]
To receive into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.receive(boost::asio::buffer(data, size), 0);
See the
[link boost_asio.reference.buffer buffer] documentation for information on receiving into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 basic_stream_socket::receive (3 of 3 overloads)]
Receive some data on a connected socket.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to receive data on the stream socket. The function call will block until one or more bytes of data has been received successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more buffers into which the data will be received.]]
[[flags][Flags specifying how the receive call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes received. Returns 0 if an error occurred.
[heading Remarks]
The receive operation may not receive all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[endsect]
[endsect]
[section:receive_buffer_size basic_stream_socket::receive_buffer_size]
['Inherited from socket_base.]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_low_watermark basic_stream_socket::receive_low_watermark]
['Inherited from socket_base.]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:remote_endpoint basic_stream_socket::remote_endpoint]
Get the remote endpoint of the socket.
endpoint_type ``[link boost_asio.reference.basic_stream_socket.remote_endpoint.overload1 remote_endpoint]``() const;
endpoint_type ``[link boost_asio.reference.basic_stream_socket.remote_endpoint.overload2 remote_endpoint]``(
boost::system::error_code & ec) const;
[section:overload1 basic_stream_socket::remote_endpoint (1 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint() const;
This function is used to obtain the remote endpoint of the socket.
[heading Return Value]
An object that represents the remote endpoint of the socket.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
[endsect]
[section:overload2 basic_stream_socket::remote_endpoint (2 of 2 overloads)]
['Inherited from basic_socket.]
Get the remote endpoint of the socket.
endpoint_type remote_endpoint(
boost::system::error_code & ec) const;
This function is used to obtain the remote endpoint of the socket.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
An object that represents the remote endpoint of the socket. Returns a default-constructed endpoint object if an error occurred.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:reuse_address basic_stream_socket::reuse_address]
['Inherited from socket_base.]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send basic_stream_socket::send]
Send some data on the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.send.overload1 send]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.send.overload2 send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.send.overload3 send]``(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::send (1 of 3 overloads)]
Send some data on the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers);
This function is used to send data on the stream socket. The function call will block until one or more bytes of the data has been sent successfully, or an until error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The send operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.send(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::send (2 of 3 overloads)]
Send some data on the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags);
This function is used to send data on the stream socket. The function call will block until one or more bytes of the data has been sent successfully, or an until error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket.]]
[[flags][Flags specifying how the send call is to be made.]]
]
[heading Return Value]
The number of bytes sent.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The send operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[heading Example]
To send a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.send(boost::asio::buffer(data, size), 0);
See the
[link boost_asio.reference.buffer buffer] documentation for information on sending multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 basic_stream_socket::send (3 of 3 overloads)]
Send some data on the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
This function is used to send data on the stream socket. The function call will block until one or more bytes of the data has been sent successfully, or an until error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be sent on the socket.]]
[[flags][Flags specifying how the send call is to be made.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes sent. Returns 0 if an error occurred.
[heading Remarks]
The send operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[endsect]
[endsect]
[section:send_buffer_size basic_stream_socket::send_buffer_size]
['Inherited from socket_base.]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark basic_stream_socket::send_low_watermark]
['Inherited from socket_base.]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:service_type basic_stream_socket::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef StreamSocketService service_type;
[endsect]
[section:set_option basic_stream_socket::set_option]
Set an option on the socket.
void ``[link boost_asio.reference.basic_stream_socket.set_option.overload1 set_option]``(
const SettableSocketOption & option);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.set_option.overload2 set_option]``(
const SettableSocketOption & option,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::set_option (1 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
void set_option(
const SettableSocketOption & option);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
socket.set_option(option);
[endsect]
[section:overload2 basic_stream_socket::set_option (2 of 2 overloads)]
['Inherited from basic_socket.]
Set an option on the socket.
boost::system::error_code set_option(
const SettableSocketOption & option,
boost::system::error_code & ec);
This function is used to set an option on the socket.
[heading Parameters]
[variablelist
[[option][The new option value to be set on the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Setting the IPPROTO\_TCP/TCP\_NODELAY option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
boost::system::error_code ec;
socket.set_option(option, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown basic_stream_socket::shutdown]
Disable sends or receives on the socket.
void ``[link boost_asio.reference.basic_stream_socket.shutdown.overload1 shutdown]``(
shutdown_type what);
boost::system::error_code ``[link boost_asio.reference.basic_stream_socket.shutdown.overload2 shutdown]``(
shutdown_type what,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::shutdown (1 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
void shutdown(
shutdown_type what);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
[endsect]
[section:overload2 basic_stream_socket::shutdown (2 of 2 overloads)]
['Inherited from basic_socket.]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
shutdown_type what,
boost::system::error_code & ec);
This function is used to disable send operations, receive operations, or both.
[heading Parameters]
[variablelist
[[what][Determines what types of operation will no longer be allowed.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Example]
Shutting down the send side of the socket:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::system::error_code ec;
socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
if (ec)
{
// An error occurred.
}
[endsect]
[endsect]
[section:shutdown_type basic_stream_socket::shutdown_type]
['Inherited from socket_base.]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[section:write_some basic_stream_socket::write_some]
Write some data to the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.write_some.overload1 write_some]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.basic_stream_socket.write_some.overload2 write_some]``(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 basic_stream_socket::write_some (1 of 2 overloads)]
Write some data to the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers);
This function is used to write data to the stream socket. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be written to the socket.]]
]
[heading Return Value]
The number of bytes written.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the peer.]]
]
[heading Remarks]
The write\_some operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
socket.write_some(boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload2 basic_stream_socket::write_some (2 of 2 overloads)]
Write some data to the socket.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
This function is used to write data to the stream socket. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][One or more data buffers to be written to the socket.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes written. Returns 0 if an error occurred.
[heading Remarks]
The write\_some operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[endsect]
[endsect]
[endsect]
[section:basic_streambuf basic_streambuf]
Automatically resizable buffer class based on std::streambuf.
template<
typename Allocator = std::allocator<char>>
class basic_streambuf :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_streambuf.const_buffers_type [*const_buffers_type]]]
[The type used to represent the get area as a list of buffers. ]
]
[
[[link boost_asio.reference.basic_streambuf.mutable_buffers_type [*mutable_buffers_type]]]
[The type used to represent the put area as a list of buffers. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_streambuf.basic_streambuf [*basic_streambuf]]]
[Construct a buffer with a specified maximum size. ]
]
[
[[link boost_asio.reference.basic_streambuf.commit [*commit]]]
[Move the start of the put area by the specified number of characters. ]
]
[
[[link boost_asio.reference.basic_streambuf.consume [*consume]]]
[Move the start of the get area by the specified number of characters. ]
]
[
[[link boost_asio.reference.basic_streambuf.data [*data]]]
[Get a list of buffers that represents the get area. ]
]
[
[[link boost_asio.reference.basic_streambuf.max_size [*max_size]]]
[Return the maximum size of the buffer. ]
]
[
[[link boost_asio.reference.basic_streambuf.prepare [*prepare]]]
[Get a list of buffers that represents the put area, with the given size. ]
]
[
[[link boost_asio.reference.basic_streambuf.size [*size]]]
[Return the size of the get area in characters. ]
]
]
[section:basic_streambuf basic_streambuf::basic_streambuf]
Construct a buffer with a specified maximum size.
basic_streambuf(
std::size_t max_size = (std::numeric_limits< std::size_t >::max)(),
const Allocator & allocator = Allocator());
[endsect]
[section:commit basic_streambuf::commit]
Move the start of the put area by the specified number of characters.
void commit(
std::size_t n);
[endsect]
[section:const_buffers_type basic_streambuf::const_buffers_type]
The type used to represent the get area as a list of buffers.
typedef implementation_defined const_buffers_type;
[endsect]
[section:consume basic_streambuf::consume]
Move the start of the get area by the specified number of characters.
void consume(
std::size_t n);
[endsect]
[section:data basic_streambuf::data]
Get a list of buffers that represents the get area.
const_buffers_type data() const;
[endsect]
[section:max_size basic_streambuf::max_size]
Return the maximum size of the buffer.
std::size_t max_size() const;
[endsect]
[section:mutable_buffers_type basic_streambuf::mutable_buffers_type]
The type used to represent the put area as a list of buffers.
typedef implementation_defined mutable_buffers_type;
[endsect]
[section:prepare basic_streambuf::prepare]
Get a list of buffers that represents the put area, with the given size.
mutable_buffers_type prepare(
std::size_t size);
[endsect]
[section:size basic_streambuf::size]
Return the size of the get area in characters.
std::size_t size() const;
[endsect]
[endsect]
[section:buffer buffer]
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload1 buffer]``(
const mutable_buffer & b);
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload2 buffer]``(
const mutable_buffer & b,
std::size_t max_size_in_bytes);
const_buffers_1 ``[link boost_asio.reference.buffer.overload3 buffer]``(
const const_buffer & b);
const_buffers_1 ``[link boost_asio.reference.buffer.overload4 buffer]``(
const const_buffer & b,
std::size_t max_size_in_bytes);
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload5 buffer]``(
void * data,
std::size_t size_in_bytes);
const_buffers_1 ``[link boost_asio.reference.buffer.overload6 buffer]``(
const void * data,
std::size_t size_in_bytes);
template<
typename PodType,
std::size_t N>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload7 buffer]``(
PodType & data);
template<
typename PodType,
std::size_t N>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload8 buffer]``(
PodType & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload9 buffer]``(
const PodType & data);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload10 buffer]``(
const PodType & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
std::size_t N>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload11 buffer]``(
boost::array< PodType, N > & data);
template<
typename PodType,
std::size_t N>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload12 buffer]``(
boost::array< PodType, N > & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload13 buffer]``(
boost::array< const PodType, N > & data);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload14 buffer]``(
boost::array< const PodType, N > & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload15 buffer]``(
const boost::array< PodType, N > & data);
template<
typename PodType,
std::size_t N>
const_buffers_1 ``[link boost_asio.reference.buffer.overload16 buffer]``(
const boost::array< PodType, N > & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
typename Allocator>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload17 buffer]``(
std::vector< PodType, Allocator > & data);
template<
typename PodType,
typename Allocator>
mutable_buffers_1 ``[link boost_asio.reference.buffer.overload18 buffer]``(
std::vector< PodType, Allocator > & data,
std::size_t max_size_in_bytes);
template<
typename PodType,
typename Allocator>
const_buffers_1 ``[link boost_asio.reference.buffer.overload19 buffer]``(
const std::vector< PodType, Allocator > & data);
template<
typename PodType,
typename Allocator>
const_buffers_1 ``[link boost_asio.reference.buffer.overload20 buffer]``(
const std::vector< PodType, Allocator > & data,
std::size_t max_size_in_bytes);
const_buffers_1 ``[link boost_asio.reference.buffer.overload21 buffer]``(
const std::string & data);
const_buffers_1 ``[link boost_asio.reference.buffer.overload22 buffer]``(
const std::string & data,
std::size_t max_size_in_bytes);
The simplest use case involves reading or writing a single buffer of a specified size:
sock.write(boost::asio::buffer(data, size));
In the above example, the return value of boost::asio::buffer meets the requirements of the ConstBufferSequence concept so that it may be directly passed to the socket's write function. A buffer created for modifiable memory also meets the requirements of the MutableBufferSequence concept.
An individual buffer may be created from a builtin array, std::vector or boost::array of POD elements. This helps prevent buffer overruns by automatically determining the size of the buffer:
char d1[128];
size_t bytes_transferred = sock.read(boost::asio::buffer(d1));
std::vector<char> d2(128);
bytes_transferred = sock.read(boost::asio::buffer(d2));
boost::array<char, 128> d3;
bytes_transferred = sock.read(boost::asio::buffer(d3));
To read or write using multiple buffers (i.e. scatter-gather I/O), multiple buffer objects may be assigned into a container that supports the MutableBufferSequence (for read) or ConstBufferSequence (for write) concepts:
char d1[128];
std::vector<char> d2(128);
boost::array<char, 128> d3;
boost::array<mutable_buffer, 3> bufs1 = {
boost::asio::buffer(d1),
boost::asio::buffer(d2),
boost::asio::buffer(d3) };
bytes_transferred = sock.read(bufs1);
std::vector<const_buffer> bufs2;
bufs2.push_back(boost::asio::buffer(d1));
bufs2.push_back(boost::asio::buffer(d2));
bufs2.push_back(boost::asio::buffer(d3));
bytes_transferred = sock.write(bufs2);
[section:overload1 buffer (1 of 22 overloads)]
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 buffer(
const mutable_buffer & b);
[endsect]
[section:overload2 buffer (2 of 22 overloads)]
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1 buffer(
const mutable_buffer & b,
std::size_t max_size_in_bytes);
[endsect]
[section:overload3 buffer (3 of 22 overloads)]
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1 buffer(
const const_buffer & b);
[endsect]
[section:overload4 buffer (4 of 22 overloads)]
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1 buffer(
const const_buffer & b,
std::size_t max_size_in_bytes);
[endsect]
[section:overload5 buffer (5 of 22 overloads)]
Create a new modifiable buffer that represents the given memory range.
mutable_buffers_1 buffer(
void * data,
std::size_t size_in_bytes);
[endsect]
[section:overload6 buffer (6 of 22 overloads)]
Create a new non-modifiable buffer that represents the given memory range.
const_buffers_1 buffer(
const void * data,
std::size_t size_in_bytes);
[endsect]
[section:overload7 buffer (7 of 22 overloads)]
Create a new modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
mutable_buffers_1 buffer(
PodType & data);
[endsect]
[section:overload8 buffer (8 of 22 overloads)]
Create a new modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
mutable_buffers_1 buffer(
PodType & data,
std::size_t max_size_in_bytes);
[endsect]
[section:overload9 buffer (9 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
const PodType & data);
[endsect]
[section:overload10 buffer (10 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
const PodType & data,
std::size_t max_size_in_bytes);
[endsect]
[section:overload11 buffer (11 of 22 overloads)]
Create a new modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
mutable_buffers_1 buffer(
boost::array< PodType, N > & data);
[endsect]
[section:overload12 buffer (12 of 22 overloads)]
Create a new modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
mutable_buffers_1 buffer(
boost::array< PodType, N > & data,
std::size_t max_size_in_bytes);
[endsect]
[section:overload13 buffer (13 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
boost::array< const PodType, N > & data);
[endsect]
[section:overload14 buffer (14 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
boost::array< const PodType, N > & data,
std::size_t max_size_in_bytes);
[endsect]
[section:overload15 buffer (15 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
const boost::array< PodType, N > & data);
[endsect]
[section:overload16 buffer (16 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD array.
template<
typename PodType,
std::size_t N>
const_buffers_1 buffer(
const boost::array< PodType, N > & data,
std::size_t max_size_in_bytes);
[endsect]
[section:overload17 buffer (17 of 22 overloads)]
Create a new modifiable buffer that represents the given POD vector.
template<
typename PodType,
typename Allocator>
mutable_buffers_1 buffer(
std::vector< PodType, Allocator > & data);
[heading Remarks]
The buffer is invalidated by any vector operation that would also invalidate iterators.
[endsect]
[section:overload18 buffer (18 of 22 overloads)]
Create a new modifiable buffer that represents the given POD vector.
template<
typename PodType,
typename Allocator>
mutable_buffers_1 buffer(
std::vector< PodType, Allocator > & data,
std::size_t max_size_in_bytes);
[heading Remarks]
The buffer is invalidated by any vector operation that would also invalidate iterators.
[endsect]
[section:overload19 buffer (19 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD vector.
template<
typename PodType,
typename Allocator>
const_buffers_1 buffer(
const std::vector< PodType, Allocator > & data);
[heading Remarks]
The buffer is invalidated by any vector operation that would also invalidate iterators.
[endsect]
[section:overload20 buffer (20 of 22 overloads)]
Create a new non-modifiable buffer that represents the given POD vector.
template<
typename PodType,
typename Allocator>
const_buffers_1 buffer(
const std::vector< PodType, Allocator > & data,
std::size_t max_size_in_bytes);
[heading Remarks]
The buffer is invalidated by any vector operation that would also invalidate iterators.
[endsect]
[section:overload21 buffer (21 of 22 overloads)]
Create a new non-modifiable buffer that represents the given string.
const_buffers_1 buffer(
const std::string & data);
[heading Remarks]
The buffer is invalidated by any non-const operation called on the given string object.
[endsect]
[section:overload22 buffer (22 of 22 overloads)]
Create a new non-modifiable buffer that represents the given string.
const_buffers_1 buffer(
const std::string & data,
std::size_t max_size_in_bytes);
[heading Remarks]
The buffer is invalidated by any non-const operation called on the given string object.
[endsect]
[endsect]
[section:buffered_read_stream buffered_read_stream]
Adds buffering to the read-related operations of a stream.
template<
typename Stream>
class buffered_read_stream :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_read_stream.lowest_layer_type [*lowest_layer_type]]]
[The type of the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_read_stream.next_layer_type [*next_layer_type]]]
[The type of the next layer. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_read_stream.async_fill [*async_fill]]]
[Start an asynchronous fill. ]
]
[
[[link boost_asio.reference.buffered_read_stream.async_read_some [*async_read_some]]]
[Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_read_stream.async_write_some [*async_write_some]]]
[Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_read_stream.buffered_read_stream [*buffered_read_stream]]]
[Construct, passing the specified argument to initialise the next layer. ]
]
[
[[link boost_asio.reference.buffered_read_stream.close [*close]]]
[Close the stream. ]
]
[
[[link boost_asio.reference.buffered_read_stream.fill [*fill]]]
[Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_read_stream.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_read_stream.in_avail [*in_avail]]]
[Determine the amount of data that may be read without blocking. ]
]
[
[[link boost_asio.reference.buffered_read_stream.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_read_stream.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_read_stream.next_layer [*next_layer]]]
[Get a reference to the next layer. ]
]
[
[[link boost_asio.reference.buffered_read_stream.peek [*peek]]]
[Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_read_stream.read_some [*read_some]]]
[Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_read_stream.write_some [*write_some]]]
[Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_read_stream.default_buffer_size [*default_buffer_size]]]
[The default buffer size. ]
]
]
The buffered_read_stream class template can be used to add buffering to the synchronous and asynchronous read operations of a stream.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:async_fill buffered_read_stream::async_fill]
Start an asynchronous fill.
template<
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_fill(
ReadHandler handler);
[endsect]
[section:async_read_some buffered_read_stream::async_read_some]
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
const MutableBufferSequence & buffers,
ReadHandler handler);
[endsect]
[section:async_write_some buffered_read_stream::async_write_some]
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
const ConstBufferSequence & buffers,
WriteHandler handler);
[endsect]
[section:buffered_read_stream buffered_read_stream::buffered_read_stream]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
``[link boost_asio.reference.buffered_read_stream.buffered_read_stream.overload1 buffered_read_stream]``(
Arg & a);
template<
typename Arg>
``[link boost_asio.reference.buffered_read_stream.buffered_read_stream.overload2 buffered_read_stream]``(
Arg & a,
std::size_t buffer_size);
[section:overload1 buffered_read_stream::buffered_read_stream (1 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_read_stream(
Arg & a);
[endsect]
[section:overload2 buffered_read_stream::buffered_read_stream (2 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_read_stream(
Arg & a,
std::size_t buffer_size);
[endsect]
[endsect]
[section:close buffered_read_stream::close]
Close the stream.
void ``[link boost_asio.reference.buffered_read_stream.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.buffered_read_stream.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::close (1 of 2 overloads)]
Close the stream.
void close();
[endsect]
[section:overload2 buffered_read_stream::close (2 of 2 overloads)]
Close the stream.
boost::system::error_code close(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:default_buffer_size buffered_read_stream::default_buffer_size]
The default buffer size.
static const std::size_t default_buffer_size = implementation_defined;
[endsect]
[section:fill buffered_read_stream::fill]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t ``[link boost_asio.reference.buffered_read_stream.fill.overload1 fill]``();
std::size_t ``[link boost_asio.reference.buffered_read_stream.fill.overload2 fill]``(
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::fill (1 of 2 overloads)]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill();
[endsect]
[section:overload2 buffered_read_stream::fill (2 of 2 overloads)]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:get_io_service buffered_read_stream::get_io_service]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
[endsect]
[section:in_avail buffered_read_stream::in_avail]
Determine the amount of data that may be read without blocking.
std::size_t ``[link boost_asio.reference.buffered_read_stream.in_avail.overload1 in_avail]``();
std::size_t ``[link boost_asio.reference.buffered_read_stream.in_avail.overload2 in_avail]``(
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::in_avail (1 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
[endsect]
[section:overload2 buffered_read_stream::in_avail (2 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:io_service buffered_read_stream::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
[endsect]
[section:lowest_layer buffered_read_stream::lowest_layer]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
[endsect]
[section:lowest_layer_type buffered_read_stream::lowest_layer_type]
The type of the lowest layer.
typedef next_layer_type::lowest_layer_type lowest_layer_type;
[endsect]
[section:next_layer buffered_read_stream::next_layer]
Get a reference to the next layer.
next_layer_type & next_layer();
[endsect]
[section:next_layer_type buffered_read_stream::next_layer_type]
The type of the next layer.
typedef boost::remove_reference< Stream >::type next_layer_type;
[endsect]
[section:peek buffered_read_stream::peek]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.peek.overload1 peek]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.peek.overload2 peek]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::peek (1 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_read_stream::peek (2 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:read_some buffered_read_stream::read_some]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.read_some.overload1 read_some]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.read_some.overload2 read_some]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::read_some (1 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_read_stream::read_some (2 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:write_some buffered_read_stream::write_some]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.write_some.overload1 write_some]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_read_stream.write_some.overload2 write_some]``(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_read_stream::write_some (1 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers);
[endsect]
[section:overload2 buffered_read_stream::write_some (2 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[endsect]
[section:buffered_stream buffered_stream]
Adds buffering to the read- and write-related operations of a stream.
template<
typename Stream>
class buffered_stream :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_stream.lowest_layer_type [*lowest_layer_type]]]
[The type of the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_stream.next_layer_type [*next_layer_type]]]
[The type of the next layer. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_stream.async_fill [*async_fill]]]
[Start an asynchronous fill. ]
]
[
[[link boost_asio.reference.buffered_stream.async_flush [*async_flush]]]
[Start an asynchronous flush. ]
]
[
[[link boost_asio.reference.buffered_stream.async_read_some [*async_read_some]]]
[Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_stream.async_write_some [*async_write_some]]]
[Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_stream.buffered_stream [*buffered_stream]]]
[Construct, passing the specified argument to initialise the next layer. ]
]
[
[[link boost_asio.reference.buffered_stream.close [*close]]]
[Close the stream. ]
]
[
[[link boost_asio.reference.buffered_stream.fill [*fill]]]
[Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_stream.flush [*flush]]]
[Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_stream.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_stream.in_avail [*in_avail]]]
[Determine the amount of data that may be read without blocking. ]
]
[
[[link boost_asio.reference.buffered_stream.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_stream.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_stream.next_layer [*next_layer]]]
[Get a reference to the next layer. ]
]
[
[[link boost_asio.reference.buffered_stream.peek [*peek]]]
[Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_stream.read_some [*read_some]]]
[Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_stream.write_some [*write_some]]]
[Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. ]
]
]
The buffered_stream class template can be used to add buffering to the synchronous and asynchronous read and write operations of a stream.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:async_fill buffered_stream::async_fill]
Start an asynchronous fill.
template<
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_fill(
ReadHandler handler);
[endsect]
[section:async_flush buffered_stream::async_flush]
Start an asynchronous flush.
template<
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_flush(
WriteHandler handler);
[endsect]
[section:async_read_some buffered_stream::async_read_some]
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
const MutableBufferSequence & buffers,
ReadHandler handler);
[endsect]
[section:async_write_some buffered_stream::async_write_some]
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
const ConstBufferSequence & buffers,
WriteHandler handler);
[endsect]
[section:buffered_stream buffered_stream::buffered_stream]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
``[link boost_asio.reference.buffered_stream.buffered_stream.overload1 buffered_stream]``(
Arg & a);
template<
typename Arg>
``[link boost_asio.reference.buffered_stream.buffered_stream.overload2 buffered_stream]``(
Arg & a,
std::size_t read_buffer_size,
std::size_t write_buffer_size);
[section:overload1 buffered_stream::buffered_stream (1 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_stream(
Arg & a);
[endsect]
[section:overload2 buffered_stream::buffered_stream (2 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_stream(
Arg & a,
std::size_t read_buffer_size,
std::size_t write_buffer_size);
[endsect]
[endsect]
[section:close buffered_stream::close]
Close the stream.
void ``[link boost_asio.reference.buffered_stream.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.buffered_stream.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 buffered_stream::close (1 of 2 overloads)]
Close the stream.
void close();
[endsect]
[section:overload2 buffered_stream::close (2 of 2 overloads)]
Close the stream.
boost::system::error_code close(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:fill buffered_stream::fill]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t ``[link boost_asio.reference.buffered_stream.fill.overload1 fill]``();
std::size_t ``[link boost_asio.reference.buffered_stream.fill.overload2 fill]``(
boost::system::error_code & ec);
[section:overload1 buffered_stream::fill (1 of 2 overloads)]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation. Throws an exception on failure.
std::size_t fill();
[endsect]
[section:overload2 buffered_stream::fill (2 of 2 overloads)]
Fill the buffer with some data. Returns the number of bytes placed in the buffer as a result of the operation, or 0 if an error occurred.
std::size_t fill(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:flush buffered_stream::flush]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t ``[link boost_asio.reference.buffered_stream.flush.overload1 flush]``();
std::size_t ``[link boost_asio.reference.buffered_stream.flush.overload2 flush]``(
boost::system::error_code & ec);
[section:overload1 buffered_stream::flush (1 of 2 overloads)]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush();
[endsect]
[section:overload2 buffered_stream::flush (2 of 2 overloads)]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:get_io_service buffered_stream::get_io_service]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
[endsect]
[section:in_avail buffered_stream::in_avail]
Determine the amount of data that may be read without blocking.
std::size_t ``[link boost_asio.reference.buffered_stream.in_avail.overload1 in_avail]``();
std::size_t ``[link boost_asio.reference.buffered_stream.in_avail.overload2 in_avail]``(
boost::system::error_code & ec);
[section:overload1 buffered_stream::in_avail (1 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
[endsect]
[section:overload2 buffered_stream::in_avail (2 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:io_service buffered_stream::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
[endsect]
[section:lowest_layer buffered_stream::lowest_layer]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
[endsect]
[section:lowest_layer_type buffered_stream::lowest_layer_type]
The type of the lowest layer.
typedef next_layer_type::lowest_layer_type lowest_layer_type;
[endsect]
[section:next_layer buffered_stream::next_layer]
Get a reference to the next layer.
next_layer_type & next_layer();
[endsect]
[section:next_layer_type buffered_stream::next_layer_type]
The type of the next layer.
typedef boost::remove_reference< Stream >::type next_layer_type;
[endsect]
[section:peek buffered_stream::peek]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.peek.overload1 peek]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.peek.overload2 peek]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_stream::peek (1 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_stream::peek (2 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:read_some buffered_stream::read_some]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.read_some.overload1 read_some]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.read_some.overload2 read_some]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_stream::read_some (1 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_stream::read_some (2 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:write_some buffered_stream::write_some]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.write_some.overload1 write_some]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_stream.write_some.overload2 write_some]``(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_stream::write_some (1 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers);
[endsect]
[section:overload2 buffered_stream::write_some (2 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[endsect]
[section:buffered_write_stream buffered_write_stream]
Adds buffering to the write-related operations of a stream.
template<
typename Stream>
class buffered_write_stream :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_write_stream.lowest_layer_type [*lowest_layer_type]]]
[The type of the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_write_stream.next_layer_type [*next_layer_type]]]
[The type of the next layer. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_write_stream.async_flush [*async_flush]]]
[Start an asynchronous flush. ]
]
[
[[link boost_asio.reference.buffered_write_stream.async_read_some [*async_read_some]]]
[Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_write_stream.async_write_some [*async_write_some]]]
[Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation. ]
]
[
[[link boost_asio.reference.buffered_write_stream.buffered_write_stream [*buffered_write_stream]]]
[Construct, passing the specified argument to initialise the next layer. ]
]
[
[[link boost_asio.reference.buffered_write_stream.close [*close]]]
[Close the stream. ]
]
[
[[link boost_asio.reference.buffered_write_stream.flush [*flush]]]
[Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_write_stream.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_write_stream.in_avail [*in_avail]]]
[Determine the amount of data that may be read without blocking. ]
]
[
[[link boost_asio.reference.buffered_write_stream.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.buffered_write_stream.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.buffered_write_stream.next_layer [*next_layer]]]
[Get a reference to the next layer. ]
]
[
[[link boost_asio.reference.buffered_write_stream.peek [*peek]]]
[Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_write_stream.read_some [*read_some]]]
[Read some data from the stream. Returns the number of bytes read. Throws an exception on failure. ]
]
[
[[link boost_asio.reference.buffered_write_stream.write_some [*write_some]]]
[Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.buffered_write_stream.default_buffer_size [*default_buffer_size]]]
[The default buffer size. ]
]
]
The buffered_write_stream class template can be used to add buffering to the synchronous and asynchronous write operations of a stream.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:async_flush buffered_write_stream::async_flush]
Start an asynchronous flush.
template<
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_flush(
WriteHandler handler);
[endsect]
[section:async_read_some buffered_write_stream::async_read_some]
Start an asynchronous read. The buffer into which the data will be read must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
const MutableBufferSequence & buffers,
ReadHandler handler);
[endsect]
[section:async_write_some buffered_write_stream::async_write_some]
Start an asynchronous write. The data being written must be valid for the lifetime of the asynchronous operation.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
const ConstBufferSequence & buffers,
WriteHandler handler);
[endsect]
[section:buffered_write_stream buffered_write_stream::buffered_write_stream]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
``[link boost_asio.reference.buffered_write_stream.buffered_write_stream.overload1 buffered_write_stream]``(
Arg & a);
template<
typename Arg>
``[link boost_asio.reference.buffered_write_stream.buffered_write_stream.overload2 buffered_write_stream]``(
Arg & a,
std::size_t buffer_size);
[section:overload1 buffered_write_stream::buffered_write_stream (1 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_write_stream(
Arg & a);
[endsect]
[section:overload2 buffered_write_stream::buffered_write_stream (2 of 2 overloads)]
Construct, passing the specified argument to initialise the next layer.
template<
typename Arg>
buffered_write_stream(
Arg & a,
std::size_t buffer_size);
[endsect]
[endsect]
[section:close buffered_write_stream::close]
Close the stream.
void ``[link boost_asio.reference.buffered_write_stream.close.overload1 close]``();
boost::system::error_code ``[link boost_asio.reference.buffered_write_stream.close.overload2 close]``(
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::close (1 of 2 overloads)]
Close the stream.
void close();
[endsect]
[section:overload2 buffered_write_stream::close (2 of 2 overloads)]
Close the stream.
boost::system::error_code close(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:default_buffer_size buffered_write_stream::default_buffer_size]
The default buffer size.
static const std::size_t default_buffer_size = implementation_defined;
[endsect]
[section:flush buffered_write_stream::flush]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t ``[link boost_asio.reference.buffered_write_stream.flush.overload1 flush]``();
std::size_t ``[link boost_asio.reference.buffered_write_stream.flush.overload2 flush]``(
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::flush (1 of 2 overloads)]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation. Throws an exception on failure.
std::size_t flush();
[endsect]
[section:overload2 buffered_write_stream::flush (2 of 2 overloads)]
Flush all data from the buffer to the next layer. Returns the number of bytes written to the next layer on the last write operation, or 0 if an error occurred.
std::size_t flush(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:get_io_service buffered_write_stream::get_io_service]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
[endsect]
[section:in_avail buffered_write_stream::in_avail]
Determine the amount of data that may be read without blocking.
std::size_t ``[link boost_asio.reference.buffered_write_stream.in_avail.overload1 in_avail]``();
std::size_t ``[link boost_asio.reference.buffered_write_stream.in_avail.overload2 in_avail]``(
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::in_avail (1 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
[endsect]
[section:overload2 buffered_write_stream::in_avail (2 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:io_service buffered_write_stream::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
[endsect]
[section:lowest_layer buffered_write_stream::lowest_layer]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
[endsect]
[section:lowest_layer_type buffered_write_stream::lowest_layer_type]
The type of the lowest layer.
typedef next_layer_type::lowest_layer_type lowest_layer_type;
[endsect]
[section:next_layer buffered_write_stream::next_layer]
Get a reference to the next layer.
next_layer_type & next_layer();
[endsect]
[section:next_layer_type buffered_write_stream::next_layer_type]
The type of the next layer.
typedef boost::remove_reference< Stream >::type next_layer_type;
[endsect]
[section:peek buffered_write_stream::peek]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.peek.overload1 peek]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.peek.overload2 peek]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::peek (1 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_write_stream::peek (2 of 2 overloads)]
Peek at the incoming data on the stream. Returns the number of bytes read, or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:read_some buffered_write_stream::read_some]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.read_some.overload1 read_some]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.read_some.overload2 read_some]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::read_some (1 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers);
[endsect]
[section:overload2 buffered_write_stream::read_some (2 of 2 overloads)]
Read some data from the stream. Returns the number of bytes read or 0 if an error occurred.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:write_some buffered_write_stream::write_some]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.write_some.overload1 write_some]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.buffered_write_stream.write_some.overload2 write_some]``(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 buffered_write_stream::write_some (1 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written. Throws an exception on failure.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers);
[endsect]
[section:overload2 buffered_write_stream::write_some (2 of 2 overloads)]
Write the given data to the stream. Returns the number of bytes written, or 0 if an error occurred and the error handler did not throw.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[endsect]
[section:const_buffer const_buffer]
Holds a buffer that cannot be modified.
class const_buffer
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffer.const_buffer [*const_buffer]]]
[Construct an empty buffer. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffer.buffer_cast_helper [*buffer_cast_helper]]]
[]
]
[
[[link boost_asio.reference.const_buffer.buffer_size_helper [*buffer_size_helper]]]
[]
]
]
The const_buffer class provides a safe representation of a buffer that cannot be modified. It does not own the underlying data, and so is cheap to copy or assign.
[section:buffer_cast_helper const_buffer::buffer_cast_helper]
friend const void * buffer_cast_helper(
const const_buffer & b);
[endsect]
[section:buffer_size_helper const_buffer::buffer_size_helper]
friend std::size_t buffer_size_helper(
const const_buffer & b);
[endsect]
[section:const_buffer const_buffer::const_buffer]
Construct an empty buffer.
``[link boost_asio.reference.const_buffer.const_buffer.overload1 const_buffer]``();
``[link boost_asio.reference.const_buffer.const_buffer.overload2 const_buffer]``(
const void * data,
std::size_t size);
``[link boost_asio.reference.const_buffer.const_buffer.overload3 const_buffer]``(
const mutable_buffer & b);
[section:overload1 const_buffer::const_buffer (1 of 3 overloads)]
Construct an empty buffer.
const_buffer();
[endsect]
[section:overload2 const_buffer::const_buffer (2 of 3 overloads)]
Construct a buffer to represent a given memory range.
const_buffer(
const void * data,
std::size_t size);
[endsect]
[section:overload3 const_buffer::const_buffer (3 of 3 overloads)]
Construct a non-modifiable buffer from a modifiable one.
const_buffer(
const mutable_buffer & b);
[endsect]
[endsect]
[endsect]
[section:const_buffers_1 const_buffers_1]
Adapts a single non-modifiable buffer so that it meets the requirements of the ConstBufferSequence concept.
class const_buffers_1 :
public const_buffer
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffers_1.const_iterator [*const_iterator]]]
[A random-access iterator type that may be used to read elements. ]
]
[
[[link boost_asio.reference.const_buffers_1.value_type [*value_type]]]
[The type for each element in the list of buffers. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffers_1.begin [*begin]]]
[Get a random-access iterator to the first element. ]
]
[
[[link boost_asio.reference.const_buffers_1.const_buffers_1 [*const_buffers_1]]]
[Construct to represent a single non-modifiable buffer. ]
]
[
[[link boost_asio.reference.const_buffers_1.end [*end]]]
[Get a random-access iterator for one past the last element. ]
]
]
[section:begin const_buffers_1::begin]
Get a random-access iterator to the first element.
const_iterator begin() const;
[endsect]
[section:const_buffers_1 const_buffers_1::const_buffers_1]
Construct to represent a single non-modifiable buffer.
const_buffers_1(
const const_buffer & b);
[endsect]
[section:const_iterator const_buffers_1::const_iterator]
A random-access iterator type that may be used to read elements.
typedef const const_buffer * const_iterator;
[endsect]
[section:end const_buffers_1::end]
Get a random-access iterator for one past the last element.
const_iterator end() const;
[endsect]
[section:value_type const_buffers_1::value_type]
The type for each element in the list of buffers.
typedef const_buffer value_type;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffer.const_buffer [*const_buffer]]]
[Construct an empty buffer. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.const_buffer.buffer_cast_helper [*buffer_cast_helper]]]
[]
]
[
[[link boost_asio.reference.const_buffer.buffer_size_helper [*buffer_size_helper]]]
[]
]
]
The const_buffer class provides a safe representation of a buffer that cannot be modified. It does not own the underlying data, and so is cheap to copy or assign.
[endsect]
[endsect]
[section:datagram_socket_service datagram_socket_service]
Default service implementation for a datagram socket.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``>
class datagram_socket_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.datagram_socket_service.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.datagram_socket_service.implementation_type [*implementation_type]]]
[The type of a datagram socket. ]
]
[
[[link boost_asio.reference.datagram_socket_service.native_type [*native_type]]]
[The native socket type. ]
]
[
[[link boost_asio.reference.datagram_socket_service.protocol_type [*protocol_type]]]
[The protocol type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.datagram_socket_service.assign [*assign]]]
[Assign an existing native socket to a datagram socket. ]
]
[
[[link boost_asio.reference.datagram_socket_service.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.datagram_socket_service.async_receive [*async_receive]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.datagram_socket_service.async_receive_from [*async_receive_from]]]
[Start an asynchronous receive that will get the endpoint of the sender. ]
]
[
[[link boost_asio.reference.datagram_socket_service.async_send [*async_send]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.datagram_socket_service.async_send_to [*async_send_to]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.datagram_socket_service.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.datagram_socket_service.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.datagram_socket_service.bind [*bind]]]
[]
]
[
[[link boost_asio.reference.datagram_socket_service.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.datagram_socket_service.close [*close]]]
[Close a datagram socket implementation. ]
]
[
[[link boost_asio.reference.datagram_socket_service.connect [*connect]]]
[Connect the datagram socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.datagram_socket_service.construct [*construct]]]
[Construct a new datagram socket implementation. ]
]
[
[[link boost_asio.reference.datagram_socket_service.datagram_socket_service [*datagram_socket_service]]]
[Construct a new datagram socket service for the specified io_service. ]
]
[
[[link boost_asio.reference.datagram_socket_service.destroy [*destroy]]]
[Destroy a datagram socket implementation. ]
]
[
[[link boost_asio.reference.datagram_socket_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.datagram_socket_service.get_option [*get_option]]]
[Get a socket option. ]
]
[
[[link boost_asio.reference.datagram_socket_service.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.datagram_socket_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.datagram_socket_service.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.datagram_socket_service.local_endpoint [*local_endpoint]]]
[Get the local endpoint. ]
]
[
[[link boost_asio.reference.datagram_socket_service.native [*native]]]
[Get the native socket implementation. ]
]
[
[[link boost_asio.reference.datagram_socket_service.open [*open]]]
[]
]
[
[[link boost_asio.reference.datagram_socket_service.receive [*receive]]]
[Receive some data from the peer. ]
]
[
[[link boost_asio.reference.datagram_socket_service.receive_from [*receive_from]]]
[Receive a datagram with the endpoint of the sender. ]
]
[
[[link boost_asio.reference.datagram_socket_service.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint. ]
]
[
[[link boost_asio.reference.datagram_socket_service.send [*send]]]
[Send the given data to the peer. ]
]
[
[[link boost_asio.reference.datagram_socket_service.send_to [*send_to]]]
[Send a datagram to the specified endpoint. ]
]
[
[[link boost_asio.reference.datagram_socket_service.set_option [*set_option]]]
[Set a socket option. ]
]
[
[[link boost_asio.reference.datagram_socket_service.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
[
[[link boost_asio.reference.datagram_socket_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.datagram_socket_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:assign datagram_socket_service::assign]
Assign an existing native socket to a datagram socket.
boost::system::error_code assign(
implementation_type & impl,
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[section:async_connect datagram_socket_service::async_connect]
Start an asynchronous connect.
template<
typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]``>
void async_connect(
implementation_type & impl,
const endpoint_type & peer_endpoint,
ConnectHandler handler);
[endsect]
[section:async_receive datagram_socket_service::async_receive]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
implementation_type & impl,
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
[endsect]
[section:async_receive_from datagram_socket_service::async_receive_from]
Start an asynchronous receive that will get the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive_from(
implementation_type & impl,
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
ReadHandler handler);
[endsect]
[section:async_send datagram_socket_service::async_send]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
implementation_type & impl,
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
[endsect]
[section:async_send_to datagram_socket_service::async_send_to]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send_to(
implementation_type & impl,
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
WriteHandler handler);
[endsect]
[section:at_mark datagram_socket_service::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:available datagram_socket_service::available]
Determine the number of bytes available for reading.
std::size_t available(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:bind datagram_socket_service::bind]
boost::system::error_code bind(
implementation_type & impl,
const endpoint_type & endpoint,
boost::system::error_code & ec);
[endsect]
[section:cancel datagram_socket_service::cancel]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:close datagram_socket_service::close]
Close a datagram socket implementation.
boost::system::error_code close(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:connect datagram_socket_service::connect]
Connect the datagram socket to the specified endpoint.
boost::system::error_code connect(
implementation_type & impl,
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[endsect]
[section:construct datagram_socket_service::construct]
Construct a new datagram socket implementation.
void construct(
implementation_type & impl);
[endsect]
[section:datagram_socket_service datagram_socket_service::datagram_socket_service]
Construct a new datagram socket service for the specified io_service.
datagram_socket_service(
boost::asio::io_service & io_service);
[endsect]
[section:destroy datagram_socket_service::destroy]
Destroy a datagram socket implementation.
void destroy(
implementation_type & impl);
[endsect]
[section:endpoint_type datagram_socket_service::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service datagram_socket_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:get_option datagram_socket_service::get_option]
Get a socket option.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code get_option(
const implementation_type & impl,
GettableSocketOption & option,
boost::system::error_code & ec) const;
[endsect]
[section:id datagram_socket_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:implementation_type datagram_socket_service::implementation_type]
The type of a datagram socket.
typedef implementation_defined implementation_type;
[endsect]
[section:io_control datagram_socket_service::io_control]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
boost::system::error_code io_control(
implementation_type & impl,
IoControlCommand & command,
boost::system::error_code & ec);
[endsect]
[section:io_service datagram_socket_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:is_open datagram_socket_service::is_open]
Determine whether the socket is open.
bool is_open(
const implementation_type & impl) const;
[endsect]
[section:local_endpoint datagram_socket_service::local_endpoint]
Get the local endpoint.
endpoint_type local_endpoint(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:native datagram_socket_service::native]
Get the native socket implementation.
native_type native(
implementation_type & impl);
[endsect]
[section:native_type datagram_socket_service::native_type]
The native socket type.
typedef implementation_defined native_type;
[endsect]
[section:open datagram_socket_service::open]
boost::system::error_code open(
implementation_type & impl,
const protocol_type & protocol,
boost::system::error_code & ec);
[endsect]
[section:protocol_type datagram_socket_service::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive datagram_socket_service::receive]
Receive some data from the peer.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
implementation_type & impl,
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:receive_from datagram_socket_service::receive_from]
Receive a datagram with the endpoint of the sender.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive_from(
implementation_type & impl,
const MutableBufferSequence & buffers,
endpoint_type & sender_endpoint,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:remote_endpoint datagram_socket_service::remote_endpoint]
Get the remote endpoint.
endpoint_type remote_endpoint(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:send datagram_socket_service::send]
Send the given data to the peer.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
implementation_type & impl,
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:send_to datagram_socket_service::send_to]
Send a datagram to the specified endpoint.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send_to(
implementation_type & impl,
const ConstBufferSequence & buffers,
const endpoint_type & destination,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:set_option datagram_socket_service::set_option]
Set a socket option.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code set_option(
implementation_type & impl,
const SettableSocketOption & option,
boost::system::error_code & ec);
[endsect]
[section:shutdown datagram_socket_service::shutdown]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
implementation_type & impl,
socket_base::shutdown_type what,
boost::system::error_code & ec);
[endsect]
[section:shutdown_service datagram_socket_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[endsect]
[section:deadline_timer deadline_timer]
Typedef for the typical usage of timer.
typedef basic_deadline_timer< boost::posix_time::ptime > deadline_timer;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_deadline_timer.duration_type [*duration_type]]]
[The duration type. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.time_type [*time_type]]]
[The time type. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.traits_type [*traits_type]]]
[The time traits type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_deadline_timer.async_wait [*async_wait]]]
[Start an asynchronous wait on the timer. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.basic_deadline_timer [*basic_deadline_timer]]]
[Constructor. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.cancel [*cancel]]]
[Cancel any asynchronous operations that are waiting on the timer. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.expires_at [*expires_at]]]
[Get the timer's expiry time as an absolute time. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.expires_from_now [*expires_from_now]]]
[Get the timer's expiry time relative to now. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_deadline_timer.wait [*wait]]]
[Perform a blocking wait on the timer. ]
]
]
The basic_deadline_timer class template provides the ability to perform a blocking or asynchronous wait for a timer to expire.
Most applications will use the boost::asio::deadline\_timer typedef.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[heading Examples]
Performing a blocking wait:
// Construct a timer without setting an expiry time.
boost::asio::deadline_timer timer(io_service);
// Set an expiry time relative to now.
timer.expires_from_now(boost::posix_time::seconds(5));
// Wait for the timer to expire.
timer.wait();
Performing an asynchronous wait:
void handler(const boost::system::error_code& error)
{
if (!error)
{
// Timer expired.
}
}
...
// Construct a timer with an absolute expiry time.
boost::asio::deadline_timer timer(io_service,
boost::posix_time::time_from_string("2005-12-07 23:59:59.000"));
// Start an asynchronous wait.
timer.async_wait(handler);
[heading Changing an active deadline_timer's expiry time]
Changing the expiry time of a timer while there are pending asynchronous waits causes those wait operations to be cancelled. To ensure that the action associated with the timer is performed only once, use something like this: used:
void on_some_event()
{
if (my_timer.expires_from_now(seconds(5)) > 0)
{
// We managed to cancel the timer. Start new asynchronous wait.
my_timer.async_wait(on_timeout);
}
else
{
// Too late, timer has already expired!
}
}
void on_timeout(const boost::system::error_code& e)
{
if (e != boost::asio::error::operation_aborted)
{
// Timer was not cancelled, take necessary action.
}
}
* The boost::asio::basic_deadline_timer::expires_from_now() function cancels any pending asynchronous waits, and returns the number of asynchronous waits that were cancelled. If it returns 0 then you were too late and the wait handler has already been executed, or will soon be executed. If it returns 1 then the wait handler was successfully cancelled.
* If a wait handler is cancelled, the boost::system::error_code passed to it contains the value boost::asio::error::operation_aborted.
[endsect]
[section:deadline_timer_service deadline_timer_service]
Default service implementation for a timer.
template<
typename ``[link boost_asio.reference.TimeType TimeType]``,
typename ``[link boost_asio.reference.TimeTraits TimeTraits]`` = boost::asio::time_traits<TimeType>>
class deadline_timer_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.deadline_timer_service.duration_type [*duration_type]]]
[The duration type. ]
]
[
[[link boost_asio.reference.deadline_timer_service.implementation_type [*implementation_type]]]
[The implementation type of the deadline timer. ]
]
[
[[link boost_asio.reference.deadline_timer_service.time_type [*time_type]]]
[The time type. ]
]
[
[[link boost_asio.reference.deadline_timer_service.traits_type [*traits_type]]]
[The time traits type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.deadline_timer_service.async_wait [*async_wait]]]
[]
]
[
[[link boost_asio.reference.deadline_timer_service.cancel [*cancel]]]
[Cancel any asynchronous wait operations associated with the timer. ]
]
[
[[link boost_asio.reference.deadline_timer_service.construct [*construct]]]
[Construct a new timer implementation. ]
]
[
[[link boost_asio.reference.deadline_timer_service.deadline_timer_service [*deadline_timer_service]]]
[Construct a new timer service for the specified io_service. ]
]
[
[[link boost_asio.reference.deadline_timer_service.destroy [*destroy]]]
[Destroy a timer implementation. ]
]
[
[[link boost_asio.reference.deadline_timer_service.expires_at [*expires_at]]]
[Get the expiry time for the timer as an absolute time. ]
]
[
[[link boost_asio.reference.deadline_timer_service.expires_from_now [*expires_from_now]]]
[Get the expiry time for the timer relative to now. ]
]
[
[[link boost_asio.reference.deadline_timer_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.deadline_timer_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.deadline_timer_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
[
[[link boost_asio.reference.deadline_timer_service.wait [*wait]]]
[]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.deadline_timer_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:async_wait deadline_timer_service::async_wait]
template<
typename ``[link boost_asio.reference.WaitHandler WaitHandler]``>
void async_wait(
implementation_type & impl,
WaitHandler handler);
[endsect]
[section:cancel deadline_timer_service::cancel]
Cancel any asynchronous wait operations associated with the timer.
std::size_t cancel(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:construct deadline_timer_service::construct]
Construct a new timer implementation.
void construct(
implementation_type & impl);
[endsect]
[section:deadline_timer_service deadline_timer_service::deadline_timer_service]
Construct a new timer service for the specified io_service.
deadline_timer_service(
boost::asio::io_service & io_service);
[endsect]
[section:destroy deadline_timer_service::destroy]
Destroy a timer implementation.
void destroy(
implementation_type & impl);
[endsect]
[section:duration_type deadline_timer_service::duration_type]
The duration type.
typedef traits_type::duration_type duration_type;
[endsect]
[section:expires_at deadline_timer_service::expires_at]
Get the expiry time for the timer as an absolute time.
time_type ``[link boost_asio.reference.deadline_timer_service.expires_at.overload1 expires_at]``(
const implementation_type & impl) const;
std::size_t ``[link boost_asio.reference.deadline_timer_service.expires_at.overload2 expires_at]``(
implementation_type & impl,
const time_type & expiry_time,
boost::system::error_code & ec);
[section:overload1 deadline_timer_service::expires_at (1 of 2 overloads)]
Get the expiry time for the timer as an absolute time.
time_type expires_at(
const implementation_type & impl) const;
[endsect]
[section:overload2 deadline_timer_service::expires_at (2 of 2 overloads)]
Set the expiry time for the timer as an absolute time.
std::size_t expires_at(
implementation_type & impl,
const time_type & expiry_time,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:expires_from_now deadline_timer_service::expires_from_now]
Get the expiry time for the timer relative to now.
duration_type ``[link boost_asio.reference.deadline_timer_service.expires_from_now.overload1 expires_from_now]``(
const implementation_type & impl) const;
std::size_t ``[link boost_asio.reference.deadline_timer_service.expires_from_now.overload2 expires_from_now]``(
implementation_type & impl,
const duration_type & expiry_time,
boost::system::error_code & ec);
[section:overload1 deadline_timer_service::expires_from_now (1 of 2 overloads)]
Get the expiry time for the timer relative to now.
duration_type expires_from_now(
const implementation_type & impl) const;
[endsect]
[section:overload2 deadline_timer_service::expires_from_now (2 of 2 overloads)]
Set the expiry time for the timer relative to now.
std::size_t expires_from_now(
implementation_type & impl,
const duration_type & expiry_time,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:get_io_service deadline_timer_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:id deadline_timer_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:implementation_type deadline_timer_service::implementation_type]
The implementation type of the deadline timer.
typedef implementation_defined implementation_type;
[endsect]
[section:io_service deadline_timer_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:shutdown_service deadline_timer_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[section:time_type deadline_timer_service::time_type]
The time type.
typedef traits_type::time_type time_type;
[endsect]
[section:traits_type deadline_timer_service::traits_type]
The time traits type.
typedef TimeTraits traits_type;
[endsect]
[section:wait deadline_timer_service::wait]
void wait(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:error__addrinfo_category error::addrinfo_category]
static const boost::system::error_category & addrinfo_category = boost::asio::error::get_addrinfo_category();
[endsect]
[section:error__addrinfo_errors error::addrinfo_errors]
enum addrinfo_errors
[heading Values]
[variablelist
[
[service_not_found]
[The service is not supported for the given socket type. ]
]
[
[socket_type_not_supported]
[The socket type is not supported. ]
]
]
[endsect]
[section:error__basic_errors error::basic_errors]
enum basic_errors
[heading Values]
[variablelist
[
[access_denied]
[Permission denied. ]
]
[
[address_family_not_supported]
[Address family not supported by protocol. ]
]
[
[address_in_use]
[Address already in use. ]
]
[
[already_connected]
[Transport endpoint is already connected. ]
]
[
[already_started]
[Operation already in progress. ]
]
[
[broken_pipe]
[Broken pipe. ]
]
[
[connection_aborted]
[A connection has been aborted. ]
]
[
[connection_refused]
[Connection refused. ]
]
[
[connection_reset]
[Connection reset by peer. ]
]
[
[bad_descriptor]
[Bad file descriptor. ]
]
[
[fault]
[Bad address. ]
]
[
[host_unreachable]
[No route to host. ]
]
[
[in_progress]
[Operation now in progress. ]
]
[
[interrupted]
[Interrupted system call. ]
]
[
[invalid_argument]
[Invalid argument. ]
]
[
[message_size]
[Message too long. ]
]
[
[network_down]
[Network is down. ]
]
[
[network_reset]
[Network dropped connection on reset. ]
]
[
[network_unreachable]
[Network is unreachable. ]
]
[
[no_descriptors]
[Too many open files. ]
]
[
[no_buffer_space]
[No buffer space available. ]
]
[
[no_memory]
[Cannot allocate memory. ]
]
[
[no_permission]
[Operation not permitted. ]
]
[
[no_protocol_option]
[Protocol not available. ]
]
[
[not_connected]
[Transport endpoint is not connected. ]
]
[
[not_socket]
[Socket operation on non-socket. ]
]
[
[operation_aborted]
[Operation cancelled. ]
]
[
[operation_not_supported]
[Operation not supported. ]
]
[
[shut_down]
[Cannot send after transport endpoint shutdown. ]
]
[
[timed_out]
[Connection timed out. ]
]
[
[try_again]
[Resource temporarily unavailable. ]
]
[
[would_block]
[The socket is marked non-blocking and the requested operation would block. ]
]
]
[endsect]
[section:error__get_addrinfo_category error::get_addrinfo_category]
const boost::system::error_category & get_addrinfo_category();
[endsect]
[section:error__get_misc_category error::get_misc_category]
const boost::system::error_category & get_misc_category();
[endsect]
[section:error__get_netdb_category error::get_netdb_category]
const boost::system::error_category & get_netdb_category();
[endsect]
[section:error__get_ssl_category error::get_ssl_category]
const boost::system::error_category & get_ssl_category();
[endsect]
[section:error__get_system_category error::get_system_category]
const boost::system::error_category & get_system_category();
[endsect]
[section:error__make_error_code error::make_error_code]
boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload1 make_error_code]``(
basic_errors e);
boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload2 make_error_code]``(
netdb_errors e);
boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload3 make_error_code]``(
addrinfo_errors e);
boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload4 make_error_code]``(
misc_errors e);
boost::system::error_code ``[link boost_asio.reference.error__make_error_code.overload5 make_error_code]``(
ssl_errors e);
[section:overload1 error::make_error_code (1 of 5 overloads)]
boost::system::error_code make_error_code(
basic_errors e);
[endsect]
[section:overload2 error::make_error_code (2 of 5 overloads)]
boost::system::error_code make_error_code(
netdb_errors e);
[endsect]
[section:overload3 error::make_error_code (3 of 5 overloads)]
boost::system::error_code make_error_code(
addrinfo_errors e);
[endsect]
[section:overload4 error::make_error_code (4 of 5 overloads)]
boost::system::error_code make_error_code(
misc_errors e);
[endsect]
[section:overload5 error::make_error_code (5 of 5 overloads)]
boost::system::error_code make_error_code(
ssl_errors e);
[endsect]
[endsect]
[section:error__misc_category error::misc_category]
static const boost::system::error_category & misc_category = boost::asio::error::get_misc_category();
[endsect]
[section:error__misc_errors error::misc_errors]
enum misc_errors
[heading Values]
[variablelist
[
[already_open]
[Already open. ]
]
[
[eof]
[End of file or stream. ]
]
[
[not_found]
[Element not found. ]
]
[
[fd_set_failure]
[The descriptor cannot fit into the select system call's fd_set. ]
]
]
[endsect]
[section:error__netdb_category error::netdb_category]
static const boost::system::error_category & netdb_category = boost::asio::error::get_netdb_category();
[endsect]
[section:error__netdb_errors error::netdb_errors]
enum netdb_errors
[heading Values]
[variablelist
[
[host_not_found]
[Host not found (authoritative). ]
]
[
[host_not_found_try_again]
[Host not found (non-authoritative). ]
]
[
[no_data]
[The query is valid but does not have associated address data. ]
]
[
[no_recovery]
[A non-recoverable error occurred. ]
]
]
[endsect]
[section:error__ssl_category error::ssl_category]
static const boost::system::error_category & ssl_category = boost::asio::error::get_ssl_category();
[endsect]
[section:error__ssl_errors error::ssl_errors]
enum ssl_errors
[heading Values]
[variablelist
]
[endsect]
[section:error__system_category error::system_category]
static const boost::system::error_category & system_category = boost::asio::error::get_system_category();
[endsect]
[section:has_service has_service]
template<
typename ``[link boost_asio.reference.Service Service]``>
bool has_service(
io_service & ios);
This function is used to determine whether the io_service contains a service object corresponding to the given service type.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
]
[heading Return Value]
A boolean indicating whether the io_service contains the service.
[endsect]
[section:invalid_service_owner invalid_service_owner]
Exception thrown when trying to add a service object to an io_service where the service has a different owner.
class invalid_service_owner
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.invalid_service_owner.invalid_service_owner [*invalid_service_owner]]]
[]
]
]
[section:invalid_service_owner invalid_service_owner::invalid_service_owner]
invalid_service_owner();
[endsect]
[endsect]
[section:io_service io_service]
Provides core I/O functionality.
class io_service :
noncopyable
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__id [*id]]]
[Class used to uniquely identify a service. ]
]
[
[[link boost_asio.reference.io_service__service [*service]]]
[Base class for all io_service services. ]
]
[
[[link boost_asio.reference.io_service__strand [*strand]]]
[Provides serialised handler execution. ]
]
[
[[link boost_asio.reference.io_service__work [*work]]]
[Class to inform the io_service when it has work to do. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service.dispatch [*dispatch]]]
[Request the io_service to invoke the given handler. ]
]
[
[[link boost_asio.reference.io_service.io_service [*io_service]]]
[Constructor. ]
]
[
[[link boost_asio.reference.io_service.poll [*poll]]]
[Run the io_service's event processing loop to execute ready handlers. ]
]
[
[[link boost_asio.reference.io_service.poll_one [*poll_one]]]
[Run the io_service's event processing loop to execute one ready handler. ]
]
[
[[link boost_asio.reference.io_service.post [*post]]]
[Request the io_service to invoke the given handler and return immediately. ]
]
[
[[link boost_asio.reference.io_service.reset [*reset]]]
[Reset the io_service in preparation for a subsequent run() invocation. ]
]
[
[[link boost_asio.reference.io_service.run [*run]]]
[Run the io_service's event processing loop. ]
]
[
[[link boost_asio.reference.io_service.run_one [*run_one]]]
[Run the io_service's event processing loop to execute at most one handler. ]
]
[
[[link boost_asio.reference.io_service.stop [*stop]]]
[Stop the io_service's event processing loop. ]
]
[
[[link boost_asio.reference.io_service.wrap [*wrap]]]
[Create a new handler that automatically dispatches the wrapped handler on the io_service. ]
]
[
[[link boost_asio.reference.io_service._io_service [*~io_service]]]
[Destructor. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service.add_service [*add_service]]]
[Add a service object to the io_service. ]
]
[
[[link boost_asio.reference.io_service.has_service [*has_service]]]
[Determine if an io_service contains a specified service type. ]
]
[
[[link boost_asio.reference.io_service.use_service [*use_service]]]
[Obtain the service object corresponding to the given type. ]
]
]
The io_service class provides the core I/O functionality for users of the asynchronous I/O objects, including:
* boost::asio::ip::tcp::socket
* boost::asio::ip::tcp::acceptor
* boost::asio::ip::udp::socket
* boost::asio::deadline_timer.
The io_service class also includes facilities intended for developers of custom asynchronous services.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Safe, with the exception that calling reset() while there are unfinished run() calls results in undefined behaviour.
[heading Effect of exceptions thrown from handlers]
If an exception is thrown from a handler, the exception is allowed to propagate through the throwing thread's invocation of boost::asio::io\_service::run(), boost::asio::io\_service::run\_one(), boost::asio::io\_service::poll() or boost::asio::io\_service::poll\_one(). No other threads that are calling any of these functions are affected. It is then the responsibility of the application to catch the exception.
After the exception has been caught, the boost::asio::io\_service::run(), boost::asio::io\_service::run\_one(), boost::asio::io\_service::poll() or boost::asio::io\_service::poll\_one() call may be restarted [*without] the need for an intervening call to boost::asio::io\_service::reset(). This allows the thread to rejoin the io\_service's thread pool without impacting any other threads in the pool.
For example:
boost::asio::io_service io_service;
...
for (;;)
{
try
{
io_service.run();
break; // run() exited normally
}
catch (my_exception& e)
{
// Deal with exception as appropriate.
}
}
[section:add_service io_service::add_service]
Add a service object to the io_service.
template<
typename ``[link boost_asio.reference.Service Service]``>
friend void add_service(
io_service & ios,
Service * svc);
This function is used to add a service to the io_service.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
[[svc][The service object. On success, ownership of the service object is transferred to the io\_service. When the io\_service object is destroyed, it will destroy the service object by performing:
``
delete static_cast<io_service::service*>(svc)
``
]]
]
[heading Exceptions]
[variablelist
[[boost::asio::service_already_exists][Thrown if a service of the given type is already present in the io\_service.]]
[[boost::asio::invalid_service_owner][Thrown if the service's owning io\_service is not the io\_service object specified by the ios parameter. ]]
]
[endsect]
[section:dispatch io_service::dispatch]
Request the io_service to invoke the given handler.
template<
typename ``[link boost_asio.reference.CompletionHandler CompletionHandler]``>
void dispatch(
CompletionHandler handler);
This function is used to ask the io_service to execute the given handler.
The io_service guarantees that the handler will only be called in a thread in which the run(), run\_one(), poll() or poll\_one() member functions is currently being invoked. The handler may be executed inside this function if the guarantee can be met.
[heading Parameters]
[variablelist
[[handler][The handler to be called. The io\_service will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler();
``
]]
]
[endsect]
[section:has_service io_service::has_service]
Determine if an io_service contains a specified service type.
template<
typename ``[link boost_asio.reference.Service Service]``>
friend bool has_service(
io_service & ios);
This function is used to determine whether the io_service contains a service object corresponding to the given service type.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
]
[heading Return Value]
A boolean indicating whether the io_service contains the service.
[endsect]
[section:io_service io_service::io_service]
Constructor.
``[link boost_asio.reference.io_service.io_service.overload1 io_service]``();
``[link boost_asio.reference.io_service.io_service.overload2 io_service]``(
std::size_t concurrency_hint);
[section:overload1 io_service::io_service (1 of 2 overloads)]
Constructor.
io_service();
[endsect]
[section:overload2 io_service::io_service (2 of 2 overloads)]
Constructor.
io_service(
std::size_t concurrency_hint);
Construct with a hint about the required level of concurrency.
[heading Parameters]
[variablelist
[[concurrency_hint][A suggestion to the implementation on how many threads it should allow to run simultaneously. ]]
]
[endsect]
[endsect]
[section:poll io_service::poll]
Run the io_service's event processing loop to execute ready handlers.
std::size_t ``[link boost_asio.reference.io_service.poll.overload1 poll]``();
std::size_t ``[link boost_asio.reference.io_service.poll.overload2 poll]``(
boost::system::error_code & ec);
[section:overload1 io_service::poll (1 of 2 overloads)]
Run the io_service's event processing loop to execute ready handlers.
std::size_t poll();
The poll() function runs handlers that are ready to run, without blocking, until the io_service has been stopped or there are no more ready handlers.
[heading Return Value]
The number of handlers that were executed.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 io_service::poll (2 of 2 overloads)]
Run the io_service's event processing loop to execute ready handlers.
std::size_t poll(
boost::system::error_code & ec);
The poll() function runs handlers that are ready to run, without blocking, until the io_service has been stopped or there are no more ready handlers.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of handlers that were executed.
[endsect]
[endsect]
[section:poll_one io_service::poll_one]
Run the io_service's event processing loop to execute one ready handler.
std::size_t ``[link boost_asio.reference.io_service.poll_one.overload1 poll_one]``();
std::size_t ``[link boost_asio.reference.io_service.poll_one.overload2 poll_one]``(
boost::system::error_code & ec);
[section:overload1 io_service::poll_one (1 of 2 overloads)]
Run the io_service's event processing loop to execute one ready handler.
std::size_t poll_one();
The poll\_one() function runs at most one handler that is ready to run, without blocking.
[heading Return Value]
The number of handlers that were executed.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 io_service::poll_one (2 of 2 overloads)]
Run the io_service's event processing loop to execute one ready handler.
std::size_t poll_one(
boost::system::error_code & ec);
The poll\_one() function runs at most one handler that is ready to run, without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of handlers that were executed.
[endsect]
[endsect]
[section:post io_service::post]
Request the io_service to invoke the given handler and return immediately.
template<
typename ``[link boost_asio.reference.CompletionHandler CompletionHandler]``>
void post(
CompletionHandler handler);
This function is used to ask the io_service to execute the given handler, but without allowing the io_service to call the handler from inside this function.
The io_service guarantees that the handler will only be called in a thread in which the run(), run\_one(), poll() or poll\_one() member functions is currently being invoked.
[heading Parameters]
[variablelist
[[handler][The handler to be called. The io\_service will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler();
``
]]
]
[endsect]
[section:reset io_service::reset]
Reset the io_service in preparation for a subsequent run() invocation.
void reset();
This function must be called prior to any second or later set of invocations of the run(), run\_one(), poll() or poll\_one() functions when a previous invocation of these functions returned due to the io_service being stopped or running out of work. This function allows the io_service to reset any internal state, such as a "stopped" flag.
This function must not be called while there are any unfinished calls to the run(), run\_one(), poll() or poll\_one() functions.
[endsect]
[section:run io_service::run]
Run the io_service's event processing loop.
std::size_t ``[link boost_asio.reference.io_service.run.overload1 run]``();
std::size_t ``[link boost_asio.reference.io_service.run.overload2 run]``(
boost::system::error_code & ec);
[section:overload1 io_service::run (1 of 2 overloads)]
Run the io_service's event processing loop.
std::size_t run();
The run() function blocks until all work has finished and there are no more handlers to be dispatched, or until the io_service has been stopped.
Multiple threads may call the run() function to set up a pool of threads from which the io_service may execute handlers. All threads that are waiting in the pool are equivalent and the io_service may choose any one of them to invoke a handler.
The run() function may be safely called again once it has completed only after a call to reset().
[heading Return Value]
The number of handlers that were executed.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 io_service::run (2 of 2 overloads)]
Run the io_service's event processing loop.
std::size_t run(
boost::system::error_code & ec);
The run() function blocks until all work has finished and there are no more handlers to be dispatched, or until the io_service has been stopped.
Multiple threads may call the run() function to set up a pool of threads from which the io_service may execute handlers. All threads that are waiting in the pool are equivalent and the io_service may choose any one of them to invoke a handler.
The run() function may be safely called again once it has completed only after a call to reset().
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of handlers that were executed.
[endsect]
[endsect]
[section:run_one io_service::run_one]
Run the io_service's event processing loop to execute at most one handler.
std::size_t ``[link boost_asio.reference.io_service.run_one.overload1 run_one]``();
std::size_t ``[link boost_asio.reference.io_service.run_one.overload2 run_one]``(
boost::system::error_code & ec);
[section:overload1 io_service::run_one (1 of 2 overloads)]
Run the io_service's event processing loop to execute at most one handler.
std::size_t run_one();
The run\_one() function blocks until one handler has been dispatched, or until the io_service has been stopped.
[heading Return Value]
The number of handlers that were executed.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 io_service::run_one (2 of 2 overloads)]
Run the io_service's event processing loop to execute at most one handler.
std::size_t run_one(
boost::system::error_code & ec);
The run\_one() function blocks until one handler has been dispatched, or until the io_service has been stopped.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of handlers that were executed.
[endsect]
[endsect]
[section:stop io_service::stop]
Stop the io_service's event processing loop.
void stop();
This function does not block, but instead simply signals the io_service to stop. All invocations of its run() or run\_one() member functions should return as soon as possible. Subsequent calls to run(), run\_one(), poll() or poll\_one() will return immediately until reset() is called.
[endsect]
[section:use_service io_service::use_service]
Obtain the service object corresponding to the given type.
template<
typename ``[link boost_asio.reference.Service Service]``>
friend Service & use_service(
io_service & ios);
This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, then the io_service will create a new instance of the service.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
]
[heading Return Value]
The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.
[endsect]
[section:wrap io_service::wrap]
Create a new handler that automatically dispatches the wrapped handler on the io_service.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
unspecified wrap(
Handler handler);
This function is used to create a new handler function object that, when invoked, will automatically pass the wrapped handler to the io\_service's dispatch function.
[heading Parameters]
[variablelist
[[handler][The handler to be wrapped. The io\_service will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler(A1 a1, ... An an);
``
]]
]
[heading Return Value]
A function object that, when invoked, passes the wrapped handler to the io\_service's dispatch function. Given a function object with the signature:
R f(A1 a1, ... An an);
If this function object is passed to the wrap function like so:
io_service.wrap(f);
then the return value is a function object with the signature
void g(A1 a1, ... An an);
that, when invoked, executes code equivalent to:
io_service.dispatch(boost::bind(f, a1, ... an));
[endsect]
[section:_io_service io_service::~io_service]
Destructor.
~io_service();
[endsect]
[endsect]
[section:io_service__id io_service::id]
Class used to uniquely identify a service.
class id :
noncopyable
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__id.id [*id]]]
[Constructor. ]
]
]
[section:id io_service::id::id]
Constructor.
id();
[endsect]
[endsect]
[section:io_service__service io_service::service]
Base class for all io_service services.
class service :
noncopyable
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.io_service__service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
]
[section:get_io_service io_service::service::get_io_service]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:io_service io_service::service::io_service]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[endsect]
[section:io_service__strand io_service::strand]
Provides serialised handler execution.
class strand
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__strand.dispatch [*dispatch]]]
[Request the strand to invoke the given handler. ]
]
[
[[link boost_asio.reference.io_service__strand.get_io_service [*get_io_service]]]
[Get the io_service associated with the strand. ]
]
[
[[link boost_asio.reference.io_service__strand.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the strand. ]
]
[
[[link boost_asio.reference.io_service__strand.post [*post]]]
[Request the strand to invoke the given handler and return immediately. ]
]
[
[[link boost_asio.reference.io_service__strand.strand [*strand]]]
[Constructor. ]
]
[
[[link boost_asio.reference.io_service__strand.wrap [*wrap]]]
[Create a new handler that automatically dispatches the wrapped handler on the strand. ]
]
[
[[link boost_asio.reference.io_service__strand._strand [*~strand]]]
[Destructor. ]
]
]
The io_service::strand class provides the ability to post and dispatch handlers with the guarantee that none of those handlers will execute concurrently.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Safe.
[section:dispatch io_service::strand::dispatch]
Request the strand to invoke the given handler.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
void dispatch(
Handler handler);
This function is used to ask the strand to execute the given handler.
The strand object guarantees that handlers posted or dispatched through the strand will not be executed concurrently. The handler may be executed inside this function if the guarantee can be met. If this function is called from within a handler that was posted or dispatched through the same strand, then the new handler will be executed immediately.
The strand's guarantee is in addition to the guarantee provided by the underlying io_service. The io_service guarantees that the handler will only be called in a thread in which the io\_service's run member function is currently being invoked.
[heading Parameters]
[variablelist
[[handler][The handler to be called. The strand will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler();
``
]]
]
[endsect]
[section:get_io_service io_service::strand::get_io_service]
Get the io_service associated with the strand.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the strand uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the strand will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:io_service io_service::strand::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the strand.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the strand uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the strand will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:post io_service::strand::post]
Request the strand to invoke the given handler and return immediately.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
void post(
Handler handler);
This function is used to ask the strand to execute the given handler, but without allowing the strand to call the handler from inside this function.
The strand object guarantees that handlers posted or dispatched through the strand will not be executed concurrently. The strand's guarantee is in addition to the guarantee provided by the underlying io_service. The io_service guarantees that the handler will only be called in a thread in which the io\_service's run member function is currently being invoked.
[heading Parameters]
[variablelist
[[handler][The handler to be called. The strand will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler();
``
]]
]
[endsect]
[section:strand io_service::strand::strand]
Constructor.
strand(
boost::asio::io_service & io_service);
Constructs the strand.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the strand will use to dispatch handlers that are ready to be run. ]]
]
[endsect]
[section:wrap io_service::strand::wrap]
Create a new handler that automatically dispatches the wrapped handler on the strand.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
unspecified wrap(
Handler handler);
This function is used to create a new handler function object that, when invoked, will automatically pass the wrapped handler to the strand's dispatch function.
[heading Parameters]
[variablelist
[[handler][The handler to be wrapped. The strand will make a copy of the handler object as required. The function signature of the handler must be:
``
void handler(A1 a1, ... An an);
``
]]
]
[heading Return Value]
A function object that, when invoked, passes the wrapped handler to the strand's dispatch function. Given a function object with the signature:
R f(A1 a1, ... An an);
If this function object is passed to the wrap function like so:
strand.wrap(f);
then the return value is a function object with the signature
void g(A1 a1, ... An an);
that, when invoked, executes code equivalent to:
strand.dispatch(boost::bind(f, a1, ... an));
[endsect]
[section:_strand io_service::strand::~strand]
Destructor.
~strand();
Destroys a strand.
Handlers posted through the strand that have not yet been invoked will still be dispatched in a way that meets the guarantee of non-concurrency.
[endsect]
[endsect]
[section:io_service__work io_service::work]
Class to inform the io_service when it has work to do.
class work
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__work.get_io_service [*get_io_service]]]
[Get the io_service associated with the work. ]
]
[
[[link boost_asio.reference.io_service__work.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the work. ]
]
[
[[link boost_asio.reference.io_service__work.work [*work]]]
[Constructor notifies the io_service that work is starting. ]
]
[
[[link boost_asio.reference.io_service__work._work [*~work]]]
[Destructor notifies the io_service that the work is complete. ]
]
]
The work class is used to inform the io_service when work starts and finishes. This ensures that the io\_service's run() function will not exit while work is underway, and that it does exit when there is no unfinished work remaining.
The work class is copy-constructible so that it may be used as a data member in a handler class. It is not assignable.
[section:get_io_service io_service::work::get_io_service]
Get the io_service associated with the work.
boost::asio::io_service & get_io_service();
[endsect]
[section:io_service io_service::work::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the work.
boost::asio::io_service & io_service();
[endsect]
[section:work io_service::work::work]
Constructor notifies the io_service that work is starting.
``[link boost_asio.reference.io_service__work.work.overload1 work]``(
boost::asio::io_service & io_service);
``[link boost_asio.reference.io_service__work.work.overload2 work]``(
const work & other);
[section:overload1 io_service::work::work (1 of 2 overloads)]
Constructor notifies the io_service that work is starting.
work(
boost::asio::io_service & io_service);
The constructor is used to inform the io_service that some work has begun. This ensures that the io\_service's run() function will not exit while the work is underway.
[endsect]
[section:overload2 io_service::work::work (2 of 2 overloads)]
Copy constructor notifies the io_service that work is starting.
work(
const work & other);
The constructor is used to inform the io_service that some work has begun. This ensures that the io\_service's run() function will not exit while the work is underway.
[endsect]
[endsect]
[section:_work io_service::work::~work]
Destructor notifies the io_service that the work is complete.
~work();
The destructor is used to inform the io_service that some work has finished. Once the count of unfinished work reaches zero, the io\_service's run() function is permitted to exit.
[endsect]
[endsect]
[section:ip__address ip::address]
Implements version-independent IP addresses.
class address
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address.address [*address]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__address.from_string [*from_string]]]
[Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation. ]
]
[
[[link boost_asio.reference.ip__address.is_v4 [*is_v4]]]
[Get whether the address is an IP version 4 address. ]
]
[
[[link boost_asio.reference.ip__address.is_v6 [*is_v6]]]
[Get whether the address is an IP version 6 address. ]
]
[
[[link boost_asio.reference.ip__address.operator_eq_ [*operator=]]]
[Assign from another address. ]
]
[
[[link boost_asio.reference.ip__address.to_string [*to_string]]]
[Get the address as a string in dotted decimal format. ]
]
[
[[link boost_asio.reference.ip__address.to_v4 [*to_v4]]]
[Get the address as an IP version 4 address. ]
]
[
[[link boost_asio.reference.ip__address.to_v6 [*to_v6]]]
[Get the address as an IP version 6 address. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address.operator_not__eq_ [*operator!=]]]
[Compare two addresses for inequality. ]
]
[
[[link boost_asio.reference.ip__address.operator_lt_ [*operator<]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address.operator_eq__eq_ [*operator==]]]
[Compare two addresses for equality. ]
]
]
The
[link boost_asio.reference.ip__address ip::address] class provides the ability to use either IP version 4 or version 6 addresses.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:address ip::address::address]
Default constructor.
``[link boost_asio.reference.ip__address.address.overload1 address]``();
``[link boost_asio.reference.ip__address.address.overload2 address]``(
const boost::asio::ip::address_v4 & ipv4_address);
``[link boost_asio.reference.ip__address.address.overload3 address]``(
const boost::asio::ip::address_v6 & ipv6_address);
``[link boost_asio.reference.ip__address.address.overload4 address]``(
const address & other);
[section:overload1 ip::address::address (1 of 4 overloads)]
Default constructor.
address();
[endsect]
[section:overload2 ip::address::address (2 of 4 overloads)]
Construct an address from an IPv4 address.
address(
const boost::asio::ip::address_v4 & ipv4_address);
[endsect]
[section:overload3 ip::address::address (3 of 4 overloads)]
Construct an address from an IPv6 address.
address(
const boost::asio::ip::address_v6 & ipv6_address);
[endsect]
[section:overload4 ip::address::address (4 of 4 overloads)]
Copy constructor.
address(
const address & other);
[endsect]
[endsect]
[section:from_string ip::address::from_string]
Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation.
static address ``[link boost_asio.reference.ip__address.from_string.overload1 from_string]``(
const char * str);
static address ``[link boost_asio.reference.ip__address.from_string.overload2 from_string]``(
const char * str,
boost::system::error_code & ec);
static address ``[link boost_asio.reference.ip__address.from_string.overload3 from_string]``(
const std::string & str);
static address ``[link boost_asio.reference.ip__address.from_string.overload4 from_string]``(
const std::string & str,
boost::system::error_code & ec);
[section:overload1 ip::address::from_string (1 of 4 overloads)]
Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation.
static address from_string(
const char * str);
[endsect]
[section:overload2 ip::address::from_string (2 of 4 overloads)]
Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation.
static address from_string(
const char * str,
boost::system::error_code & ec);
[endsect]
[section:overload3 ip::address::from_string (3 of 4 overloads)]
Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation.
static address from_string(
const std::string & str);
[endsect]
[section:overload4 ip::address::from_string (4 of 4 overloads)]
Create an address from an IPv4 address string in dotted decimal form, or from an IPv6 address in hexadecimal notation.
static address from_string(
const std::string & str,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:is_v4 ip::address::is_v4]
Get whether the address is an IP version 4 address.
bool is_v4() const;
[endsect]
[section:is_v6 ip::address::is_v6]
Get whether the address is an IP version 6 address.
bool is_v6() const;
[endsect]
[section:operator_not__eq_ ip::address::operator!=]
Compare two addresses for inequality.
friend bool operator!=(
const address & a1,
const address & a2);
[endsect]
[section:operator_lt_ ip::address::operator<]
Compare addresses for ordering.
friend bool operator<(
const address & a1,
const address & a2);
[endsect]
[section:operator_eq_ ip::address::operator=]
Assign from another address.
address & ``[link boost_asio.reference.ip__address.operator_eq_.overload1 operator=]``(
const address & other);
address & ``[link boost_asio.reference.ip__address.operator_eq_.overload2 operator=]``(
const boost::asio::ip::address_v4 & ipv4_address);
address & ``[link boost_asio.reference.ip__address.operator_eq_.overload3 operator=]``(
const boost::asio::ip::address_v6 & ipv6_address);
[section:overload1 ip::address::operator= (1 of 3 overloads)]
Assign from another address.
address & operator=(
const address & other);
[endsect]
[section:overload2 ip::address::operator= (2 of 3 overloads)]
Assign from an IPv4 address.
address & operator=(
const boost::asio::ip::address_v4 & ipv4_address);
[endsect]
[section:overload3 ip::address::operator= (3 of 3 overloads)]
Assign from an IPv6 address.
address & operator=(
const boost::asio::ip::address_v6 & ipv6_address);
[endsect]
[endsect]
[section:operator_eq__eq_ ip::address::operator==]
Compare two addresses for equality.
friend bool operator==(
const address & a1,
const address & a2);
[endsect]
[section:to_string ip::address::to_string]
Get the address as a string in dotted decimal format.
std::string ``[link boost_asio.reference.ip__address.to_string.overload1 to_string]``() const;
std::string ``[link boost_asio.reference.ip__address.to_string.overload2 to_string]``(
boost::system::error_code & ec) const;
[section:overload1 ip::address::to_string (1 of 2 overloads)]
Get the address as a string in dotted decimal format.
std::string to_string() const;
[endsect]
[section:overload2 ip::address::to_string (2 of 2 overloads)]
Get the address as a string in dotted decimal format.
std::string to_string(
boost::system::error_code & ec) const;
[endsect]
[endsect]
[section:to_v4 ip::address::to_v4]
Get the address as an IP version 4 address.
boost::asio::ip::address_v4 to_v4() const;
[endsect]
[section:to_v6 ip::address::to_v6]
Get the address as an IP version 6 address.
boost::asio::ip::address_v6 to_v6() const;
[endsect]
[endsect]
[section:ip__address_v4 ip::address_v4]
Implements IP version 4 style addresses.
class address_v4
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v4.bytes_type [*bytes_type]]]
[The type used to represent an address as an array of bytes. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v4.address_v4 [*address_v4]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__address_v4.any [*any]]]
[Obtain an address object that represents any address. ]
]
[
[[link boost_asio.reference.ip__address_v4.broadcast [*broadcast]]]
[Obtain an address object that represents the broadcast address. ]
]
[
[[link boost_asio.reference.ip__address_v4.from_string [*from_string]]]
[Create an address from an IP address string in dotted decimal form. ]
]
[
[[link boost_asio.reference.ip__address_v4.is_class_a [*is_class_a]]]
[Determine whether the address is a class A address. ]
]
[
[[link boost_asio.reference.ip__address_v4.is_class_b [*is_class_b]]]
[Determine whether the address is a class B address. ]
]
[
[[link boost_asio.reference.ip__address_v4.is_class_c [*is_class_c]]]
[Determine whether the address is a class C address. ]
]
[
[[link boost_asio.reference.ip__address_v4.is_multicast [*is_multicast]]]
[Determine whether the address is a multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v4.loopback [*loopback]]]
[Obtain an address object that represents the loopback address. ]
]
[
[[link boost_asio.reference.ip__address_v4.netmask [*netmask]]]
[Obtain the netmask that corresponds to the address, based on its address class. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_eq_ [*operator=]]]
[Assign from another address. ]
]
[
[[link boost_asio.reference.ip__address_v4.to_bytes [*to_bytes]]]
[Get the address in bytes. ]
]
[
[[link boost_asio.reference.ip__address_v4.to_string [*to_string]]]
[Get the address as a string in dotted decimal format. ]
]
[
[[link boost_asio.reference.ip__address_v4.to_ulong [*to_ulong]]]
[Get the address as an unsigned long in host byte order. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v4.operator_not__eq_ [*operator!=]]]
[Compare two addresses for inequality. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_lt_ [*operator<]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_lt__eq_ [*operator<=]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_eq__eq_ [*operator==]]]
[Compare two addresses for equality. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_gt_ [*operator>]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v4.operator_gt__eq_ [*operator>=]]]
[Compare addresses for ordering. ]
]
]
The
[link boost_asio.reference.ip__address_v4 ip::address_v4] class provides the ability to use and manipulate IP version 4 addresses.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:address_v4 ip::address_v4::address_v4]
Default constructor.
``[link boost_asio.reference.ip__address_v4.address_v4.overload1 address_v4]``();
``[link boost_asio.reference.ip__address_v4.address_v4.overload2 address_v4]``(
const bytes_type & bytes);
``[link boost_asio.reference.ip__address_v4.address_v4.overload3 address_v4]``(
unsigned long addr);
``[link boost_asio.reference.ip__address_v4.address_v4.overload4 address_v4]``(
const address_v4 & other);
[section:overload1 ip::address_v4::address_v4 (1 of 4 overloads)]
Default constructor.
address_v4();
[endsect]
[section:overload2 ip::address_v4::address_v4 (2 of 4 overloads)]
Construct an address from raw bytes.
address_v4(
const bytes_type & bytes);
[endsect]
[section:overload3 ip::address_v4::address_v4 (3 of 4 overloads)]
Construct an address from a unsigned long in host byte order.
address_v4(
unsigned long addr);
[endsect]
[section:overload4 ip::address_v4::address_v4 (4 of 4 overloads)]
Copy constructor.
address_v4(
const address_v4 & other);
[endsect]
[endsect]
[section:any ip::address_v4::any]
Obtain an address object that represents any address.
static address_v4 any();
[endsect]
[section:broadcast ip::address_v4::broadcast]
Obtain an address object that represents the broadcast address.
static address_v4 ``[link boost_asio.reference.ip__address_v4.broadcast.overload1 broadcast]``();
static address_v4 ``[link boost_asio.reference.ip__address_v4.broadcast.overload2 broadcast]``(
const address_v4 & addr,
const address_v4 & mask);
[section:overload1 ip::address_v4::broadcast (1 of 2 overloads)]
Obtain an address object that represents the broadcast address.
static address_v4 broadcast();
[endsect]
[section:overload2 ip::address_v4::broadcast (2 of 2 overloads)]
Obtain an address object that represents the broadcast address that corresponds to the specified address and netmask.
static address_v4 broadcast(
const address_v4 & addr,
const address_v4 & mask);
[endsect]
[endsect]
[section:bytes_type ip::address_v4::bytes_type]
The type used to represent an address as an array of bytes.
typedef boost::array< unsigned char, 4 > bytes_type;
[endsect]
[section:from_string ip::address_v4::from_string]
Create an address from an IP address string in dotted decimal form.
static address_v4 ``[link boost_asio.reference.ip__address_v4.from_string.overload1 from_string]``(
const char * str);
static address_v4 ``[link boost_asio.reference.ip__address_v4.from_string.overload2 from_string]``(
const char * str,
boost::system::error_code & ec);
static address_v4 ``[link boost_asio.reference.ip__address_v4.from_string.overload3 from_string]``(
const std::string & str);
static address_v4 ``[link boost_asio.reference.ip__address_v4.from_string.overload4 from_string]``(
const std::string & str,
boost::system::error_code & ec);
[section:overload1 ip::address_v4::from_string (1 of 4 overloads)]
Create an address from an IP address string in dotted decimal form.
static address_v4 from_string(
const char * str);
[endsect]
[section:overload2 ip::address_v4::from_string (2 of 4 overloads)]
Create an address from an IP address string in dotted decimal form.
static address_v4 from_string(
const char * str,
boost::system::error_code & ec);
[endsect]
[section:overload3 ip::address_v4::from_string (3 of 4 overloads)]
Create an address from an IP address string in dotted decimal form.
static address_v4 from_string(
const std::string & str);
[endsect]
[section:overload4 ip::address_v4::from_string (4 of 4 overloads)]
Create an address from an IP address string in dotted decimal form.
static address_v4 from_string(
const std::string & str,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:is_class_a ip::address_v4::is_class_a]
Determine whether the address is a class A address.
bool is_class_a() const;
[endsect]
[section:is_class_b ip::address_v4::is_class_b]
Determine whether the address is a class B address.
bool is_class_b() const;
[endsect]
[section:is_class_c ip::address_v4::is_class_c]
Determine whether the address is a class C address.
bool is_class_c() const;
[endsect]
[section:is_multicast ip::address_v4::is_multicast]
Determine whether the address is a multicast address.
bool is_multicast() const;
[endsect]
[section:loopback ip::address_v4::loopback]
Obtain an address object that represents the loopback address.
static address_v4 loopback();
[endsect]
[section:netmask ip::address_v4::netmask]
Obtain the netmask that corresponds to the address, based on its address class.
static address_v4 netmask(
const address_v4 & addr);
[endsect]
[section:operator_not__eq_ ip::address_v4::operator!=]
Compare two addresses for inequality.
friend bool operator!=(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:operator_lt_ ip::address_v4::operator<]
Compare addresses for ordering.
friend bool operator<(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:operator_lt__eq_ ip::address_v4::operator<=]
Compare addresses for ordering.
friend bool operator<=(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:operator_eq_ ip::address_v4::operator=]
Assign from another address.
address_v4 & operator=(
const address_v4 & other);
[endsect]
[section:operator_eq__eq_ ip::address_v4::operator==]
Compare two addresses for equality.
friend bool operator==(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:operator_gt_ ip::address_v4::operator>]
Compare addresses for ordering.
friend bool operator>(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:operator_gt__eq_ ip::address_v4::operator>=]
Compare addresses for ordering.
friend bool operator>=(
const address_v4 & a1,
const address_v4 & a2);
[endsect]
[section:to_bytes ip::address_v4::to_bytes]
Get the address in bytes.
bytes_type to_bytes() const;
[endsect]
[section:to_string ip::address_v4::to_string]
Get the address as a string in dotted decimal format.
std::string ``[link boost_asio.reference.ip__address_v4.to_string.overload1 to_string]``() const;
std::string ``[link boost_asio.reference.ip__address_v4.to_string.overload2 to_string]``(
boost::system::error_code & ec) const;
[section:overload1 ip::address_v4::to_string (1 of 2 overloads)]
Get the address as a string in dotted decimal format.
std::string to_string() const;
[endsect]
[section:overload2 ip::address_v4::to_string (2 of 2 overloads)]
Get the address as a string in dotted decimal format.
std::string to_string(
boost::system::error_code & ec) const;
[endsect]
[endsect]
[section:to_ulong ip::address_v4::to_ulong]
Get the address as an unsigned long in host byte order.
unsigned long to_ulong() const;
[endsect]
[endsect]
[section:ip__address_v6 ip::address_v6]
Implements IP version 6 style addresses.
class address_v6
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v6.bytes_type [*bytes_type]]]
[The type used to represent an address as an array of bytes. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v6.address_v6 [*address_v6]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__address_v6.any [*any]]]
[Obtain an address object that represents any address. ]
]
[
[[link boost_asio.reference.ip__address_v6.from_string [*from_string]]]
[Create an address from an IP address string. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_link_local [*is_link_local]]]
[Determine whether the address is link local. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_loopback [*is_loopback]]]
[Determine whether the address is a loopback address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast [*is_multicast]]]
[Determine whether the address is a multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast_global [*is_multicast_global]]]
[Determine whether the address is a global multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast_link_local [*is_multicast_link_local]]]
[Determine whether the address is a link-local multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast_node_local [*is_multicast_node_local]]]
[Determine whether the address is a node-local multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast_org_local [*is_multicast_org_local]]]
[Determine whether the address is a org-local multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_multicast_site_local [*is_multicast_site_local]]]
[Determine whether the address is a site-local multicast address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_site_local [*is_site_local]]]
[Determine whether the address is site local. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_unspecified [*is_unspecified]]]
[Determine whether the address is unspecified. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_v4_compatible [*is_v4_compatible]]]
[Determine whether the address is an IPv4-compatible address. ]
]
[
[[link boost_asio.reference.ip__address_v6.is_v4_mapped [*is_v4_mapped]]]
[Determine whether the address is a mapped IPv4 address. ]
]
[
[[link boost_asio.reference.ip__address_v6.loopback [*loopback]]]
[Obtain an address object that represents the loopback address. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_eq_ [*operator=]]]
[Assign from another address. ]
]
[
[[link boost_asio.reference.ip__address_v6.scope_id [*scope_id]]]
[The scope ID of the address. ]
]
[
[[link boost_asio.reference.ip__address_v6.to_bytes [*to_bytes]]]
[Get the address in bytes. ]
]
[
[[link boost_asio.reference.ip__address_v6.to_string [*to_string]]]
[Get the address as a string. ]
]
[
[[link boost_asio.reference.ip__address_v6.to_v4 [*to_v4]]]
[Converts an IPv4-mapped or IPv4-compatible address to an IPv4 address. ]
]
[
[[link boost_asio.reference.ip__address_v6.v4_compatible [*v4_compatible]]]
[Create an IPv4-compatible IPv6 address. ]
]
[
[[link boost_asio.reference.ip__address_v6.v4_mapped [*v4_mapped]]]
[Create an IPv4-mapped IPv6 address. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__address_v6.operator_not__eq_ [*operator!=]]]
[Compare two addresses for inequality. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_lt_ [*operator<]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_lt__eq_ [*operator<=]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_eq__eq_ [*operator==]]]
[Compare two addresses for equality. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_gt_ [*operator>]]]
[Compare addresses for ordering. ]
]
[
[[link boost_asio.reference.ip__address_v6.operator_gt__eq_ [*operator>=]]]
[Compare addresses for ordering. ]
]
]
The
[link boost_asio.reference.ip__address_v6 ip::address_v6] class provides the ability to use and manipulate IP version 6 addresses.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:address_v6 ip::address_v6::address_v6]
Default constructor.
``[link boost_asio.reference.ip__address_v6.address_v6.overload1 address_v6]``();
``[link boost_asio.reference.ip__address_v6.address_v6.overload2 address_v6]``(
const bytes_type & bytes,
unsigned long scope_id = 0);
``[link boost_asio.reference.ip__address_v6.address_v6.overload3 address_v6]``(
const address_v6 & other);
[section:overload1 ip::address_v6::address_v6 (1 of 3 overloads)]
Default constructor.
address_v6();
[endsect]
[section:overload2 ip::address_v6::address_v6 (2 of 3 overloads)]
Construct an address from raw bytes and scope ID.
address_v6(
const bytes_type & bytes,
unsigned long scope_id = 0);
[endsect]
[section:overload3 ip::address_v6::address_v6 (3 of 3 overloads)]
Copy constructor.
address_v6(
const address_v6 & other);
[endsect]
[endsect]
[section:any ip::address_v6::any]
Obtain an address object that represents any address.
static address_v6 any();
[endsect]
[section:bytes_type ip::address_v6::bytes_type]
The type used to represent an address as an array of bytes.
typedef boost::array< unsigned char, 16 > bytes_type;
[endsect]
[section:from_string ip::address_v6::from_string]
Create an address from an IP address string.
static address_v6 ``[link boost_asio.reference.ip__address_v6.from_string.overload1 from_string]``(
const char * str);
static address_v6 ``[link boost_asio.reference.ip__address_v6.from_string.overload2 from_string]``(
const char * str,
boost::system::error_code & ec);
static address_v6 ``[link boost_asio.reference.ip__address_v6.from_string.overload3 from_string]``(
const std::string & str);
static address_v6 ``[link boost_asio.reference.ip__address_v6.from_string.overload4 from_string]``(
const std::string & str,
boost::system::error_code & ec);
[section:overload1 ip::address_v6::from_string (1 of 4 overloads)]
Create an address from an IP address string.
static address_v6 from_string(
const char * str);
[endsect]
[section:overload2 ip::address_v6::from_string (2 of 4 overloads)]
Create an address from an IP address string.
static address_v6 from_string(
const char * str,
boost::system::error_code & ec);
[endsect]
[section:overload3 ip::address_v6::from_string (3 of 4 overloads)]
Create an address from an IP address string.
static address_v6 from_string(
const std::string & str);
[endsect]
[section:overload4 ip::address_v6::from_string (4 of 4 overloads)]
Create an address from an IP address string.
static address_v6 from_string(
const std::string & str,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:is_link_local ip::address_v6::is_link_local]
Determine whether the address is link local.
bool is_link_local() const;
[endsect]
[section:is_loopback ip::address_v6::is_loopback]
Determine whether the address is a loopback address.
bool is_loopback() const;
[endsect]
[section:is_multicast ip::address_v6::is_multicast]
Determine whether the address is a multicast address.
bool is_multicast() const;
[endsect]
[section:is_multicast_global ip::address_v6::is_multicast_global]
Determine whether the address is a global multicast address.
bool is_multicast_global() const;
[endsect]
[section:is_multicast_link_local ip::address_v6::is_multicast_link_local]
Determine whether the address is a link-local multicast address.
bool is_multicast_link_local() const;
[endsect]
[section:is_multicast_node_local ip::address_v6::is_multicast_node_local]
Determine whether the address is a node-local multicast address.
bool is_multicast_node_local() const;
[endsect]
[section:is_multicast_org_local ip::address_v6::is_multicast_org_local]
Determine whether the address is a org-local multicast address.
bool is_multicast_org_local() const;
[endsect]
[section:is_multicast_site_local ip::address_v6::is_multicast_site_local]
Determine whether the address is a site-local multicast address.
bool is_multicast_site_local() const;
[endsect]
[section:is_site_local ip::address_v6::is_site_local]
Determine whether the address is site local.
bool is_site_local() const;
[endsect]
[section:is_unspecified ip::address_v6::is_unspecified]
Determine whether the address is unspecified.
bool is_unspecified() const;
[endsect]
[section:is_v4_compatible ip::address_v6::is_v4_compatible]
Determine whether the address is an IPv4-compatible address.
bool is_v4_compatible() const;
[endsect]
[section:is_v4_mapped ip::address_v6::is_v4_mapped]
Determine whether the address is a mapped IPv4 address.
bool is_v4_mapped() const;
[endsect]
[section:loopback ip::address_v6::loopback]
Obtain an address object that represents the loopback address.
static address_v6 loopback();
[endsect]
[section:operator_not__eq_ ip::address_v6::operator!=]
Compare two addresses for inequality.
friend bool operator!=(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:operator_lt_ ip::address_v6::operator<]
Compare addresses for ordering.
friend bool operator<(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:operator_lt__eq_ ip::address_v6::operator<=]
Compare addresses for ordering.
friend bool operator<=(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:operator_eq_ ip::address_v6::operator=]
Assign from another address.
address_v6 & operator=(
const address_v6 & other);
[endsect]
[section:operator_eq__eq_ ip::address_v6::operator==]
Compare two addresses for equality.
friend bool operator==(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:operator_gt_ ip::address_v6::operator>]
Compare addresses for ordering.
friend bool operator>(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:operator_gt__eq_ ip::address_v6::operator>=]
Compare addresses for ordering.
friend bool operator>=(
const address_v6 & a1,
const address_v6 & a2);
[endsect]
[section:scope_id ip::address_v6::scope_id]
The scope ID of the address.
unsigned long ``[link boost_asio.reference.ip__address_v6.scope_id.overload1 scope_id]``() const;
void ``[link boost_asio.reference.ip__address_v6.scope_id.overload2 scope_id]``(
unsigned long id);
[section:overload1 ip::address_v6::scope_id (1 of 2 overloads)]
The scope ID of the address.
unsigned long scope_id() const;
Returns the scope ID associated with the IPv6 address.
[endsect]
[section:overload2 ip::address_v6::scope_id (2 of 2 overloads)]
The scope ID of the address.
void scope_id(
unsigned long id);
Modifies the scope ID associated with the IPv6 address.
[endsect]
[endsect]
[section:to_bytes ip::address_v6::to_bytes]
Get the address in bytes.
bytes_type to_bytes() const;
[endsect]
[section:to_string ip::address_v6::to_string]
Get the address as a string.
std::string ``[link boost_asio.reference.ip__address_v6.to_string.overload1 to_string]``() const;
std::string ``[link boost_asio.reference.ip__address_v6.to_string.overload2 to_string]``(
boost::system::error_code & ec) const;
[section:overload1 ip::address_v6::to_string (1 of 2 overloads)]
Get the address as a string.
std::string to_string() const;
[endsect]
[section:overload2 ip::address_v6::to_string (2 of 2 overloads)]
Get the address as a string.
std::string to_string(
boost::system::error_code & ec) const;
[endsect]
[endsect]
[section:to_v4 ip::address_v6::to_v4]
Converts an IPv4-mapped or IPv4-compatible address to an IPv4 address.
address_v4 to_v4() const;
[endsect]
[section:v4_compatible ip::address_v6::v4_compatible]
Create an IPv4-compatible IPv6 address.
static address_v6 v4_compatible(
const address_v4 & addr);
[endsect]
[section:v4_mapped ip::address_v6::v4_mapped]
Create an IPv4-mapped IPv6 address.
static address_v6 v4_mapped(
const address_v4 & addr);
[endsect]
[endsect]
[section:ip__basic_endpoint ip::basic_endpoint]
Describes an endpoint for a version-independent IP socket.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``>
class basic_endpoint
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.data_type [*data_type]]]
[The type of the endpoint structure. This type is dependent on the underlying implementation of the socket layer. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.address [*address]]]
[Get the IP address associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.basic_endpoint [*basic_endpoint]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.capacity [*capacity]]]
[Get the capacity of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.data [*data]]]
[Get the underlying endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq_ [*operator=]]]
[Assign from another endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.port [*port]]]
[Get the port associated with the endpoint. The port number is always in the host's byte order. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol [*protocol]]]
[The protocol associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.resize [*resize]]]
[Set the underlying size of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.size [*size]]]
[Get the underlying size of the endpoint in the native type. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_not__eq_ [*operator!=]]]
[Compare two endpoints for inequality. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_lt_ [*operator<]]]
[Compare endpoints for ordering. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq__eq_ [*operator==]]]
[Compare two endpoints for equality. ]
]
]
The
[link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] class template describes an endpoint that may be associated with a particular socket.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:address ip::basic_endpoint::address]
Get the IP address associated with the endpoint.
boost::asio::ip::address ``[link boost_asio.reference.ip__basic_endpoint.address.overload1 address]``() const;
void ``[link boost_asio.reference.ip__basic_endpoint.address.overload2 address]``(
const boost::asio::ip::address & addr);
[section:overload1 ip::basic_endpoint::address (1 of 2 overloads)]
Get the IP address associated with the endpoint.
boost::asio::ip::address address() const;
[endsect]
[section:overload2 ip::basic_endpoint::address (2 of 2 overloads)]
Set the IP address associated with the endpoint.
void address(
const boost::asio::ip::address & addr);
[endsect]
[endsect]
[section:basic_endpoint ip::basic_endpoint::basic_endpoint]
Default constructor.
``[link boost_asio.reference.ip__basic_endpoint.basic_endpoint.overload1 basic_endpoint]``();
``[link boost_asio.reference.ip__basic_endpoint.basic_endpoint.overload2 basic_endpoint]``(
const InternetProtocol & protocol,
unsigned short port_num);
``[link boost_asio.reference.ip__basic_endpoint.basic_endpoint.overload3 basic_endpoint]``(
const boost::asio::ip::address & addr,
unsigned short port_num);
``[link boost_asio.reference.ip__basic_endpoint.basic_endpoint.overload4 basic_endpoint]``(
const basic_endpoint & other);
[section:overload1 ip::basic_endpoint::basic_endpoint (1 of 4 overloads)]
Default constructor.
basic_endpoint();
[endsect]
[section:overload2 ip::basic_endpoint::basic_endpoint (2 of 4 overloads)]
Construct an endpoint using a port number, specified in the host's byte order. The IP address will be the any address (i.e. INADDR_ANY or in6addr_any). This constructor would typically be used for accepting new connections.
basic_endpoint(
const InternetProtocol & protocol,
unsigned short port_num);
[heading Examples]
To initialise an IPv4 TCP endpoint for port 1234, use:
boost::asio::ip::tcp::endpoint ep(boost::asio::ip::tcp::v4(), 1234);
To specify an IPv6 UDP endpoint for port 9876, use:
boost::asio::ip::udp::endpoint ep(boost::asio::ip::udp::v6(), 9876);
[endsect]
[section:overload3 ip::basic_endpoint::basic_endpoint (3 of 4 overloads)]
Construct an endpoint using a port number and an IP address. This constructor may be used for accepting connections on a specific interface or for making a connection to a remote endpoint.
basic_endpoint(
const boost::asio::ip::address & addr,
unsigned short port_num);
[endsect]
[section:overload4 ip::basic_endpoint::basic_endpoint (4 of 4 overloads)]
Copy constructor.
basic_endpoint(
const basic_endpoint & other);
[endsect]
[endsect]
[section:capacity ip::basic_endpoint::capacity]
Get the capacity of the endpoint in the native type.
std::size_t capacity() const;
[endsect]
[section:data ip::basic_endpoint::data]
Get the underlying endpoint in the native type.
data_type * ``[link boost_asio.reference.ip__basic_endpoint.data.overload1 data]``();
const data_type * ``[link boost_asio.reference.ip__basic_endpoint.data.overload2 data]``() const;
[section:overload1 ip::basic_endpoint::data (1 of 2 overloads)]
Get the underlying endpoint in the native type.
data_type * data();
[endsect]
[section:overload2 ip::basic_endpoint::data (2 of 2 overloads)]
Get the underlying endpoint in the native type.
const data_type * data() const;
[endsect]
[endsect]
[section:data_type ip::basic_endpoint::data_type]
The type of the endpoint structure. This type is dependent on the underlying implementation of the socket layer.
typedef implementation_defined data_type;
[endsect]
[section:operator_not__eq_ ip::basic_endpoint::operator!=]
Compare two endpoints for inequality.
friend bool operator!=(
const basic_endpoint< InternetProtocol > & e1,
const basic_endpoint< InternetProtocol > & e2);
[endsect]
[section:operator_lt_ ip::basic_endpoint::operator<]
Compare endpoints for ordering.
friend bool operator<(
const basic_endpoint< InternetProtocol > & e1,
const basic_endpoint< InternetProtocol > & e2);
[endsect]
[section:operator_eq_ ip::basic_endpoint::operator=]
Assign from another endpoint.
basic_endpoint & operator=(
const basic_endpoint & other);
[endsect]
[section:operator_eq__eq_ ip::basic_endpoint::operator==]
Compare two endpoints for equality.
friend bool operator==(
const basic_endpoint< InternetProtocol > & e1,
const basic_endpoint< InternetProtocol > & e2);
[endsect]
[section:port ip::basic_endpoint::port]
Get the port associated with the endpoint. The port number is always in the host's byte order.
unsigned short ``[link boost_asio.reference.ip__basic_endpoint.port.overload1 port]``() const;
void ``[link boost_asio.reference.ip__basic_endpoint.port.overload2 port]``(
unsigned short port_num);
[section:overload1 ip::basic_endpoint::port (1 of 2 overloads)]
Get the port associated with the endpoint. The port number is always in the host's byte order.
unsigned short port() const;
[endsect]
[section:overload2 ip::basic_endpoint::port (2 of 2 overloads)]
Set the port associated with the endpoint. The port number is always in the host's byte order.
void port(
unsigned short port_num);
[endsect]
[endsect]
[section:protocol ip::basic_endpoint::protocol]
The protocol associated with the endpoint.
protocol_type protocol() const;
[endsect]
[section:protocol_type ip::basic_endpoint::protocol_type]
The protocol type associated with the endpoint.
typedef InternetProtocol protocol_type;
[endsect]
[section:resize ip::basic_endpoint::resize]
Set the underlying size of the endpoint in the native type.
void resize(
std::size_t size);
[endsect]
[section:size ip::basic_endpoint::size]
Get the underlying size of the endpoint in the native type.
std::size_t size() const;
[endsect]
[endsect]
[section:ip__basic_resolver ip::basic_resolver]
Provides endpoint resolution functionality.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``,
typename ``[link boost_asio.reference.ResolverService ResolverService]`` = resolver_service<InternetProtocol>>
class basic_resolver :
public basic_io_object< ResolverService >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.iterator [*iterator]]]
[The iterator type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.query [*query]]]
[The query type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.async_resolve [*async_resolve]]]
[Asynchronously resolve a query to a list of entries. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.basic_resolver [*basic_resolver]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.cancel [*cancel]]]
[Cancel any asynchronous operations that are waiting on the resolver. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.resolve [*resolve]]]
[Resolve a query to a list of entries. ]
]
]
The basic_resolver class template provides the ability to resolve a query to a list of endpoints.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:async_resolve ip::basic_resolver::async_resolve]
Asynchronously resolve a query to a list of entries.
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload1 async_resolve]``(
const query & q,
ResolveHandler handler);
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void ``[link boost_asio.reference.ip__basic_resolver.async_resolve.overload2 async_resolve]``(
const endpoint_type & e,
ResolveHandler handler);
[section:overload1 ip::basic_resolver::async_resolve (1 of 2 overloads)]
Asynchronously resolve a query to a list of entries.
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void async_resolve(
const query & q,
ResolveHandler handler);
This function is used to asynchronously resolve a query into a list of endpoint entries.
[heading Parameters]
[variablelist
[[q][A query object that determines what endpoints will be returned.]]
[[handler][The handler to be called when the resolve 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.
resolver::iterator iterator // Forward-only iterator that can
// be used to traverse the list
// of endpoint entries.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful resolve operation is guaranteed to pass at least one entry to the handler.
[endsect]
[section:overload2 ip::basic_resolver::async_resolve (2 of 2 overloads)]
Asynchronously resolve an endpoint to a list of entries.
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void async_resolve(
const endpoint_type & e,
ResolveHandler handler);
This function is used to asynchronously resolve an endpoint into a list of endpoint entries.
[heading Parameters]
[variablelist
[[e][An endpoint object that determines what endpoints will be returned.]]
[[handler][The handler to be called when the resolve 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.
resolver::iterator iterator // Forward-only iterator that can
// be used to traverse the list
// of endpoint entries.
);
``
Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using boost::asio::io\_service::post().]]
]
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful resolve operation is guaranteed to pass at least one entry to the handler.
[endsect]
[endsect]
[section:basic_resolver ip::basic_resolver::basic_resolver]
Constructor.
basic_resolver(
boost::asio::io_service & io_service);
This constructor creates a basic_resolver.
[heading Parameters]
[variablelist
[[io_service][The io\_service object that the resolver will use to dispatch handlers for any asynchronous operations performed on the timer. ]]
]
[endsect]
[section:cancel ip::basic_resolver::cancel]
Cancel any asynchronous operations that are waiting on the resolver.
void cancel();
This function forces the completion of any pending asynchronous operations on the host resolver. The handler for each cancelled operation will be invoked with the boost::asio::error::operation\_aborted error code.
[endsect]
[section:endpoint_type ip::basic_resolver::endpoint_type]
The endpoint type.
typedef InternetProtocol::endpoint endpoint_type;
[endsect]
[section:get_io_service ip::basic_resolver::get_io_service]
['Inherited from basic_io_object.]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:implementation_type ip::basic_resolver::implementation_type]
['Inherited from basic_io_object.]
The underlying implementation type of I/O object.
typedef service_type::implementation_type implementation_type;
[endsect]
[section:io_service ip::basic_resolver::io_service]
['Inherited from basic_io_object.]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the I/O object uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that the I/O object will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:iterator ip::basic_resolver::iterator]
The iterator type.
typedef InternetProtocol::resolver_iterator iterator;
[endsect]
[section:protocol_type ip::basic_resolver::protocol_type]
The protocol type.
typedef InternetProtocol protocol_type;
[endsect]
[section:query ip::basic_resolver::query]
The query type.
typedef InternetProtocol::resolver_query query;
[endsect]
[section:resolve ip::basic_resolver::resolve]
Resolve a query to a list of entries.
iterator ``[link boost_asio.reference.ip__basic_resolver.resolve.overload1 resolve]``(
const query & q);
iterator ``[link boost_asio.reference.ip__basic_resolver.resolve.overload2 resolve]``(
const query & q,
boost::system::error_code & ec);
iterator ``[link boost_asio.reference.ip__basic_resolver.resolve.overload3 resolve]``(
const endpoint_type & e);
iterator ``[link boost_asio.reference.ip__basic_resolver.resolve.overload4 resolve]``(
const endpoint_type & e,
boost::system::error_code & ec);
[section:overload1 ip::basic_resolver::resolve (1 of 4 overloads)]
Resolve a query to a list of entries.
iterator resolve(
const query & q);
This function is used to resolve a query into a list of endpoint entries.
[heading Parameters]
[variablelist
[[q][A query object that determines what endpoints will be returned.]]
]
[heading Return Value]
A forward-only iterator that can be used to traverse the list of endpoint entries.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful call to this function is guaranteed to return at least one entry.
[endsect]
[section:overload2 ip::basic_resolver::resolve (2 of 4 overloads)]
Resolve a query to a list of entries.
iterator resolve(
const query & q,
boost::system::error_code & ec);
This function is used to resolve a query into a list of endpoint entries.
[heading Parameters]
[variablelist
[[q][A query object that determines what endpoints will be returned.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A forward-only iterator that can be used to traverse the list of endpoint entries. Returns a default constructed iterator if an error occurs.
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful call to this function is guaranteed to return at least one entry.
[endsect]
[section:overload3 ip::basic_resolver::resolve (3 of 4 overloads)]
Resolve an endpoint to a list of entries.
iterator resolve(
const endpoint_type & e);
This function is used to resolve an endpoint into a list of endpoint entries.
[heading Parameters]
[variablelist
[[e][An endpoint object that determines what endpoints will be returned.]]
]
[heading Return Value]
A forward-only iterator that can be used to traverse the list of endpoint entries.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful call to this function is guaranteed to return at least one entry.
[endsect]
[section:overload4 ip::basic_resolver::resolve (4 of 4 overloads)]
Resolve an endpoint to a list of entries.
iterator resolve(
const endpoint_type & e,
boost::system::error_code & ec);
This function is used to resolve an endpoint into a list of endpoint entries.
[heading Parameters]
[variablelist
[[e][An endpoint object that determines what endpoints will be returned.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
A forward-only iterator that can be used to traverse the list of endpoint entries. Returns a default constructed iterator if an error occurs.
[heading Remarks]
A default constructed iterator represents the end of the list.
A successful call to this function is guaranteed to return at least one entry.
[endsect]
[endsect]
[section:service_type ip::basic_resolver::service_type]
['Inherited from basic_io_object.]
The type of the service that will be used to provide I/O operations.
typedef ResolverService service_type;
[endsect]
[endsect]
[section:ip__basic_resolver_entry ip::basic_resolver_entry]
An entry produced by a resolver.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``>
class basic_resolver_entry
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_entry.endpoint_type [*endpoint_type]]]
[The endpoint type associated with the endpoint entry. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_entry.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint entry. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_entry.basic_resolver_entry [*basic_resolver_entry]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_entry.endpoint [*endpoint]]]
[Get the endpoint associated with the entry. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_entry.host_name [*host_name]]]
[Get the host name associated with the entry. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_entry.operator_endpoint_type [*operator endpoint_type]]]
[Convert to the endpoint associated with the entry. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_entry.service_name [*service_name]]]
[Get the service name associated with the entry. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_entry ip::basic_resolver_entry] class template describes an entry as returned by a resolver.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:basic_resolver_entry ip::basic_resolver_entry::basic_resolver_entry]
Default constructor.
``[link boost_asio.reference.ip__basic_resolver_entry.basic_resolver_entry.overload1 basic_resolver_entry]``();
``[link boost_asio.reference.ip__basic_resolver_entry.basic_resolver_entry.overload2 basic_resolver_entry]``(
const endpoint_type & endpoint,
const std::string & host_name,
const std::string & service_name);
[section:overload1 ip::basic_resolver_entry::basic_resolver_entry (1 of 2 overloads)]
Default constructor.
basic_resolver_entry();
[endsect]
[section:overload2 ip::basic_resolver_entry::basic_resolver_entry (2 of 2 overloads)]
Construct with specified endpoint, host name and service name.
basic_resolver_entry(
const endpoint_type & endpoint,
const std::string & host_name,
const std::string & service_name);
[endsect]
[endsect]
[section:endpoint ip::basic_resolver_entry::endpoint]
Get the endpoint associated with the entry.
endpoint_type endpoint() const;
[endsect]
[section:endpoint_type ip::basic_resolver_entry::endpoint_type]
The endpoint type associated with the endpoint entry.
typedef InternetProtocol::endpoint endpoint_type;
[endsect]
[section:host_name ip::basic_resolver_entry::host_name]
Get the host name associated with the entry.
std::string host_name() const;
[endsect]
[section:operator_endpoint_type ip::basic_resolver_entry::operator endpoint_type]
Convert to the endpoint associated with the entry.
operator endpoint_type() const;
[endsect]
[section:protocol_type ip::basic_resolver_entry::protocol_type]
The protocol type associated with the endpoint entry.
typedef InternetProtocol protocol_type;
[endsect]
[section:service_name ip::basic_resolver_entry::service_name]
Get the service name associated with the entry.
std::string service_name() const;
[endsect]
[endsect]
[section:ip__basic_resolver_iterator ip::basic_resolver_iterator]
An iterator over the entries produced by a resolver.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``>
class basic_resolver_iterator
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.basic_resolver_iterator [*basic_resolver_iterator]]]
[Default constructor creates an end iterator. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.create [*create]]]
[Create an iterator from an addrinfo list returned by getaddrinfo. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_iterator ip::basic_resolver_iterator] class template is used to define iterators over the results returned by a resolver.
The iterator's value\_type, obtained when the iterator is dereferenced, is:
const basic_resolver_entry<InternetProtocol>
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:basic_resolver_iterator ip::basic_resolver_iterator::basic_resolver_iterator]
Default constructor creates an end iterator.
basic_resolver_iterator();
[endsect]
[section:create ip::basic_resolver_iterator::create]
Create an iterator from an addrinfo list returned by getaddrinfo.
static basic_resolver_iterator ``[link boost_asio.reference.ip__basic_resolver_iterator.create.overload1 create]``(
boost::asio::detail::addrinfo_type * address_info,
const std::string & host_name,
const std::string & service_name);
static basic_resolver_iterator ``[link boost_asio.reference.ip__basic_resolver_iterator.create.overload2 create]``(
const typename InternetProtocol::endpoint & endpoint,
const std::string & host_name,
const std::string & service_name);
[section:overload1 ip::basic_resolver_iterator::create (1 of 2 overloads)]
Create an iterator from an addrinfo list returned by getaddrinfo.
static basic_resolver_iterator create(
boost::asio::detail::addrinfo_type * address_info,
const std::string & host_name,
const std::string & service_name);
[endsect]
[section:overload2 ip::basic_resolver_iterator::create (2 of 2 overloads)]
Create an iterator from an endpoint, host name and service name.
static basic_resolver_iterator create(
const typename InternetProtocol::endpoint & endpoint,
const std::string & host_name,
const std::string & service_name);
[endsect]
[endsect]
[endsect]
[section:ip__basic_resolver_query ip::basic_resolver_query]
An query to be passed to a resolver.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``>
class basic_resolver_query :
public ip::resolver_query_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint query. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query [*basic_resolver_query]]]
[Construct with specified service name for any protocol. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.hints [*hints]]]
[Get the hints associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.host_name [*host_name]]]
[Get the host name associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.service_name [*service_name]]]
[Get the service name associated with the query. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.address_configured [*address_configured]]]
[Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.all_matching [*all_matching]]]
[If used with v4_mapped, return all matching IPv6 and IPv4 addresses. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.canonical_name [*canonical_name]]]
[Determine the canonical name of the host specified in the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_host [*numeric_host]]]
[Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_service [*numeric_service]]]
[Service name should be treated as a numeric string defining a port number and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.passive [*passive]]]
[Indicate that returned endpoint is intended for use as a locally bound socket endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.v4_mapped [*v4_mapped]]]
[If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_query ip::basic_resolver_query] class template describes a query that can be passed to a resolver.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[section:address_configured ip::basic_resolver_query::address_configured]
['Inherited from ip::resolver_query_base.]
Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system.
static const int address_configured = implementation_defined;
[endsect]
[section:all_matching ip::basic_resolver_query::all_matching]
['Inherited from ip::resolver_query_base.]
If used with v4_mapped, return all matching IPv6 and IPv4 addresses.
static const int all_matching = implementation_defined;
[endsect]
[section:basic_resolver_query ip::basic_resolver_query::basic_resolver_query]
Construct with specified service name for any protocol.
``[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query.overload1 basic_resolver_query]``(
const std::string & service_name,
int flags = passive|address_configured);
``[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query.overload2 basic_resolver_query]``(
const protocol_type & protocol,
const std::string & service_name,
int flags = passive|address_configured);
``[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query.overload3 basic_resolver_query]``(
const std::string & host_name,
const std::string & service_name,
int flags = address_configured);
``[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query.overload4 basic_resolver_query]``(
const protocol_type & protocol,
const std::string & host_name,
const std::string & service_name,
int flags = address_configured);
[section:overload1 ip::basic_resolver_query::basic_resolver_query (1 of 4 overloads)]
Construct with specified service name for any protocol.
basic_resolver_query(
const std::string & service_name,
int flags = passive|address_configured);
[endsect]
[section:overload2 ip::basic_resolver_query::basic_resolver_query (2 of 4 overloads)]
Construct with specified service name for a given protocol.
basic_resolver_query(
const protocol_type & protocol,
const std::string & service_name,
int flags = passive|address_configured);
[endsect]
[section:overload3 ip::basic_resolver_query::basic_resolver_query (3 of 4 overloads)]
Construct with specified host name and service name for any protocol.
basic_resolver_query(
const std::string & host_name,
const std::string & service_name,
int flags = address_configured);
[endsect]
[section:overload4 ip::basic_resolver_query::basic_resolver_query (4 of 4 overloads)]
Construct with specified host name and service name for a given protocol.
basic_resolver_query(
const protocol_type & protocol,
const std::string & host_name,
const std::string & service_name,
int flags = address_configured);
[endsect]
[endsect]
[section:canonical_name ip::basic_resolver_query::canonical_name]
['Inherited from ip::resolver_query_base.]
Determine the canonical name of the host specified in the query.
static const int canonical_name = implementation_defined;
[endsect]
[section:hints ip::basic_resolver_query::hints]
Get the hints associated with the query.
const boost::asio::detail::addrinfo_type & hints() const;
[endsect]
[section:host_name ip::basic_resolver_query::host_name]
Get the host name associated with the query.
std::string host_name() const;
[endsect]
[section:numeric_host ip::basic_resolver_query::numeric_host]
['Inherited from ip::resolver_query_base.]
Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.
static const int numeric_host = implementation_defined;
[endsect]
[section:numeric_service ip::basic_resolver_query::numeric_service]
['Inherited from ip::resolver_query_base.]
Service name should be treated as a numeric string defining a port number and no name resolution should be attempted.
static const int numeric_service = implementation_defined;
[endsect]
[section:passive ip::basic_resolver_query::passive]
['Inherited from ip::resolver_query_base.]
Indicate that returned endpoint is intended for use as a locally bound socket endpoint.
static const int passive = implementation_defined;
[endsect]
[section:protocol_type ip::basic_resolver_query::protocol_type]
The protocol type associated with the endpoint query.
typedef InternetProtocol protocol_type;
[endsect]
[section:service_name ip::basic_resolver_query::service_name]
Get the service name associated with the query.
std::string service_name() const;
[endsect]
[section:v4_mapped ip::basic_resolver_query::v4_mapped]
['Inherited from ip::resolver_query_base.]
If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses.
static const int v4_mapped = implementation_defined;
[endsect]
[endsect]
[section:ip__host_name ip::host_name]
Get the current host name.
std::string ``[link boost_asio.reference.ip__host_name.overload1 host_name]``();
std::string ``[link boost_asio.reference.ip__host_name.overload2 host_name]``(
boost::system::error_code & ec);
[section:overload1 ip::host_name (1 of 2 overloads)]
Get the current host name.
std::string host_name();
[endsect]
[section:overload2 ip::host_name (2 of 2 overloads)]
Get the current host name.
std::string host_name(
boost::system::error_code & ec);
[endsect]
[endsect]
[section:ip__multicast__enable_loopback ip::multicast::enable_loopback]
Socket option determining whether outgoing multicast packets will be received on the same socket if it is a member of the multicast group.
typedef implementation_defined enable_loopback;
Implements the IPPROTO\_IP/IP\_MULTICAST\_LOOP socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::multicast::enable_loopback option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::multicast::enable_loopback option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:ip__multicast__hops ip::multicast::hops]
Socket option for time-to-live associated with outgoing multicast packets.
typedef implementation_defined hops;
Implements the IPPROTO\_IP/IP\_MULTICAST\_TTL socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::multicast::hops option(4);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::multicast::hops option;
socket.get_option(option);
int ttl = option.value();
[endsect]
[section:ip__multicast__join_group ip::multicast::join_group]
Socket option to join a multicast group on a specified interface.
typedef implementation_defined join_group;
Implements the IPPROTO\_IP/IP\_ADD\_MEMBERSHIP socket option.
[heading Examples]
Setting the option to join a multicast group:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::address multicast_address =
boost::asio::ip::address::from_string("225.0.0.1");
boost::asio::ip::multicast::join_group option(multicast_address);
socket.set_option(option);
[endsect]
[section:ip__multicast__leave_group ip::multicast::leave_group]
Socket option to leave a multicast group on a specified interface.
typedef implementation_defined leave_group;
Implements the IPPROTO\_IP/IP\_DROP\_MEMBERSHIP socket option.
[heading Examples]
Setting the option to leave a multicast group:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::address multicast_address =
boost::asio::ip::address::from_string("225.0.0.1");
boost::asio::ip::multicast::leave_group option(multicast_address);
socket.set_option(option);
[endsect]
[section:ip__multicast__outbound_interface ip::multicast::outbound_interface]
Socket option for local interface to use for outgoing multicast packets.
typedef implementation_defined outbound_interface;
Implements the IPPROTO\_IP/IP\_MULTICAST\_IF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::address_v4 local_interface =
boost::asio::ip::address_v4::from_string("1.2.3.4");
boost::asio::ip::multicast::outbound_interface option(local_interface);
socket.set_option(option);
[endsect]
[section:ip__resolver_query_base ip::resolver_query_base]
The resolver_query_base class is used as a base for the basic_resolver_query class templates to provide a common place to define the flag constants.
class resolver_query_base
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__resolver_query_base.address_configured [*address_configured]]]
[Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.all_matching [*all_matching]]]
[If used with v4_mapped, return all matching IPv6 and IPv4 addresses. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.canonical_name [*canonical_name]]]
[Determine the canonical name of the host specified in the query. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.numeric_host [*numeric_host]]]
[Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.numeric_service [*numeric_service]]]
[Service name should be treated as a numeric string defining a port number and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.passive [*passive]]]
[Indicate that returned endpoint is intended for use as a locally bound socket endpoint. ]
]
[
[[link boost_asio.reference.ip__resolver_query_base.v4_mapped [*v4_mapped]]]
[If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses. ]
]
]
[section:address_configured ip::resolver_query_base::address_configured]
Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system.
static const int address_configured = implementation_defined;
[endsect]
[section:all_matching ip::resolver_query_base::all_matching]
If used with v4_mapped, return all matching IPv6 and IPv4 addresses.
static const int all_matching = implementation_defined;
[endsect]
[section:canonical_name ip::resolver_query_base::canonical_name]
Determine the canonical name of the host specified in the query.
static const int canonical_name = implementation_defined;
[endsect]
[section:numeric_host ip::resolver_query_base::numeric_host]
Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.
static const int numeric_host = implementation_defined;
[endsect]
[section:numeric_service ip::resolver_query_base::numeric_service]
Service name should be treated as a numeric string defining a port number and no name resolution should be attempted.
static const int numeric_service = implementation_defined;
[endsect]
[section:passive ip::resolver_query_base::passive]
Indicate that returned endpoint is intended for use as a locally bound socket endpoint.
static const int passive = implementation_defined;
[endsect]
[section:v4_mapped ip::resolver_query_base::v4_mapped]
If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses.
static const int v4_mapped = implementation_defined;
[endsect]
[endsect]
[section:ip__resolver_service ip::resolver_service]
Default service implementation for a resolver.
template<
typename ``[link boost_asio.reference.InternetProtocol InternetProtocol]``>
class resolver_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__resolver_service.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.ip__resolver_service.implementation_type [*implementation_type]]]
[The type of a resolver implementation. ]
]
[
[[link boost_asio.reference.ip__resolver_service.iterator_type [*iterator_type]]]
[The iterator type. ]
]
[
[[link boost_asio.reference.ip__resolver_service.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.ip__resolver_service.query_type [*query_type]]]
[The query type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__resolver_service.async_resolve [*async_resolve]]]
[Asynchronously resolve a query to a list of entries. ]
]
[
[[link boost_asio.reference.ip__resolver_service.cancel [*cancel]]]
[Cancel pending asynchronous operations. ]
]
[
[[link boost_asio.reference.ip__resolver_service.construct [*construct]]]
[Construct a new resolver implementation. ]
]
[
[[link boost_asio.reference.ip__resolver_service.destroy [*destroy]]]
[Destroy a resolver implementation. ]
]
[
[[link boost_asio.reference.ip__resolver_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ip__resolver_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ip__resolver_service.resolve [*resolve]]]
[Resolve a query to a list of entries. ]
]
[
[[link boost_asio.reference.ip__resolver_service.resolver_service [*resolver_service]]]
[Construct a new resolver service for the specified io_service. ]
]
[
[[link boost_asio.reference.ip__resolver_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__resolver_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:async_resolve ip::resolver_service::async_resolve]
Asynchronously resolve a query to a list of entries.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
void ``[link boost_asio.reference.ip__resolver_service.async_resolve.overload1 async_resolve]``(
implementation_type & impl,
const query_type & query,
Handler handler);
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void ``[link boost_asio.reference.ip__resolver_service.async_resolve.overload2 async_resolve]``(
implementation_type & impl,
const endpoint_type & endpoint,
ResolveHandler handler);
[section:overload1 ip::resolver_service::async_resolve (1 of 2 overloads)]
Asynchronously resolve a query to a list of entries.
template<
typename ``[link boost_asio.reference.Handler Handler]``>
void async_resolve(
implementation_type & impl,
const query_type & query,
Handler handler);
[endsect]
[section:overload2 ip::resolver_service::async_resolve (2 of 2 overloads)]
Asynchronously resolve an endpoint to a list of entries.
template<
typename ``[link boost_asio.reference.ResolveHandler ResolveHandler]``>
void async_resolve(
implementation_type & impl,
const endpoint_type & endpoint,
ResolveHandler handler);
[endsect]
[endsect]
[section:cancel ip::resolver_service::cancel]
Cancel pending asynchronous operations.
void cancel(
implementation_type & impl);
[endsect]
[section:construct ip::resolver_service::construct]
Construct a new resolver implementation.
void construct(
implementation_type & impl);
[endsect]
[section:destroy ip::resolver_service::destroy]
Destroy a resolver implementation.
void destroy(
implementation_type & impl);
[endsect]
[section:endpoint_type ip::resolver_service::endpoint_type]
The endpoint type.
typedef InternetProtocol::endpoint endpoint_type;
[endsect]
[section:get_io_service ip::resolver_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:id ip::resolver_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:implementation_type ip::resolver_service::implementation_type]
The type of a resolver implementation.
typedef implementation_defined implementation_type;
[endsect]
[section:io_service ip::resolver_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:iterator_type ip::resolver_service::iterator_type]
The iterator type.
typedef InternetProtocol::resolver_iterator iterator_type;
[endsect]
[section:protocol_type ip::resolver_service::protocol_type]
The protocol type.
typedef InternetProtocol protocol_type;
[endsect]
[section:query_type ip::resolver_service::query_type]
The query type.
typedef InternetProtocol::resolver_query query_type;
[endsect]
[section:resolve ip::resolver_service::resolve]
Resolve a query to a list of entries.
iterator_type ``[link boost_asio.reference.ip__resolver_service.resolve.overload1 resolve]``(
implementation_type & impl,
const query_type & query,
boost::system::error_code & ec);
iterator_type ``[link boost_asio.reference.ip__resolver_service.resolve.overload2 resolve]``(
implementation_type & impl,
const endpoint_type & endpoint,
boost::system::error_code & ec);
[section:overload1 ip::resolver_service::resolve (1 of 2 overloads)]
Resolve a query to a list of entries.
iterator_type resolve(
implementation_type & impl,
const query_type & query,
boost::system::error_code & ec);
[endsect]
[section:overload2 ip::resolver_service::resolve (2 of 2 overloads)]
Resolve an endpoint to a list of entries.
iterator_type resolve(
implementation_type & impl,
const endpoint_type & endpoint,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:resolver_service ip::resolver_service::resolver_service]
Construct a new resolver service for the specified io_service.
resolver_service(
boost::asio::io_service & io_service);
[endsect]
[section:shutdown_service ip::resolver_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[endsect]
[section:ip__tcp ip::tcp]
Encapsulates the flags needed for TCP.
class tcp
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__tcp.acceptor [*acceptor]]]
[The TCP acceptor type. ]
]
[
[[link boost_asio.reference.ip__tcp.endpoint [*endpoint]]]
[The type of a TCP endpoint. ]
]
[
[[link boost_asio.reference.ip__tcp.iostream [*iostream]]]
[The TCP iostream type. ]
]
[
[[link boost_asio.reference.ip__tcp.no_delay [*no_delay]]]
[Socket option for disabling the Nagle algorithm. ]
]
[
[[link boost_asio.reference.ip__tcp.resolver [*resolver]]]
[The TCP resolver type. ]
]
[
[[link boost_asio.reference.ip__tcp.resolver_iterator [*resolver_iterator]]]
[The type of a resolver iterator. ]
]
[
[[link boost_asio.reference.ip__tcp.resolver_query [*resolver_query]]]
[The type of a resolver query. ]
]
[
[[link boost_asio.reference.ip__tcp.socket [*socket]]]
[The TCP socket type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__tcp.family [*family]]]
[Obtain an identifier for the protocol family. ]
]
[
[[link boost_asio.reference.ip__tcp.protocol [*protocol]]]
[Obtain an identifier for the protocol. ]
]
[
[[link boost_asio.reference.ip__tcp.type [*type]]]
[Obtain an identifier for the type of the protocol. ]
]
[
[[link boost_asio.reference.ip__tcp.v4 [*v4]]]
[Construct to represent the IPv4 TCP protocol. ]
]
[
[[link boost_asio.reference.ip__tcp.v6 [*v6]]]
[Construct to represent the IPv6 TCP protocol. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__tcp.operator_not__eq_ [*operator!=]]]
[Compare two protocols for inequality. ]
]
[
[[link boost_asio.reference.ip__tcp.operator_eq__eq_ [*operator==]]]
[Compare two protocols for equality. ]
]
]
The
[link boost_asio.reference.ip__tcp ip::tcp] class contains flags necessary for TCP sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Safe.
[section:acceptor ip::tcp::acceptor]
The TCP acceptor type.
typedef basic_socket_acceptor< tcp > acceptor;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.native_type [*native_type]]]
[The native representation of an acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.accept [*accept]]]
[Accept a new connection. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.assign [*assign]]]
[Assigns an existing native acceptor to the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.async_accept [*async_accept]]]
[Start an asynchronous accept. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.basic_socket_acceptor [*basic_socket_acceptor]]]
[Construct an acceptor without opening it. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.bind [*bind]]]
[Bind the acceptor to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.close [*close]]]
[Close the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.get_option [*get_option]]]
[Get an option from the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.is_open [*is_open]]]
[Determine whether the acceptor is open. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.listen [*listen]]]
[Place the acceptor into the state where it will listen for new connections. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the acceptor. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.native [*native]]]
[Get the native acceptor representation. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.open [*open]]]
[Open the acceptor using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.set_option [*set_option]]]
[Set an option on the acceptor. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_acceptor.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_socket_acceptor.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_socket_acceptor class template is used for accepting new socket connections.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[heading Example]
Opening a socket acceptor with the SO\_REUSEADDR option enabled:
boost::asio::ip::tcp::acceptor acceptor(io_service);
boost::asio::ip::tcp::endpoint endpoint(boost::asio::ip::tcp::v4(), port);
acceptor.open(endpoint.protocol());
acceptor.set_option(boost::asio::ip::tcp::acceptor::reuse_address(true));
acceptor.bind(endpoint);
acceptor.listen();
[endsect]
[section:endpoint ip::tcp::endpoint]
The type of a TCP endpoint.
typedef basic_endpoint< tcp > endpoint;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.data_type [*data_type]]]
[The type of the endpoint structure. This type is dependent on the underlying implementation of the socket layer. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.address [*address]]]
[Get the IP address associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.basic_endpoint [*basic_endpoint]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.capacity [*capacity]]]
[Get the capacity of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.data [*data]]]
[Get the underlying endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq_ [*operator=]]]
[Assign from another endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.port [*port]]]
[Get the port associated with the endpoint. The port number is always in the host's byte order. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol [*protocol]]]
[The protocol associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.resize [*resize]]]
[Set the underlying size of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.size [*size]]]
[Get the underlying size of the endpoint in the native type. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_not__eq_ [*operator!=]]]
[Compare two endpoints for inequality. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_lt_ [*operator<]]]
[Compare endpoints for ordering. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq__eq_ [*operator==]]]
[Compare two endpoints for equality. ]
]
]
The
[link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] class template describes an endpoint that may be associated with a particular socket.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:family ip::tcp::family]
Obtain an identifier for the protocol family.
int family() const;
[endsect]
[section:iostream ip::tcp::iostream]
The TCP iostream type.
typedef basic_socket_iostream< tcp > iostream;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_socket_iostream.basic_socket_iostream [*basic_socket_iostream]]]
[Construct a basic_socket_iostream without establishing a connection. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.close [*close]]]
[Close the connection. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.connect [*connect]]]
[Establish a connection to an endpoint corresponding to a resolver query. ]
]
[
[[link boost_asio.reference.basic_socket_iostream.rdbuf [*rdbuf]]]
[Return a pointer to the underlying streambuf. ]
]
]
[endsect]
[section:no_delay ip::tcp::no_delay]
Socket option for disabling the Nagle algorithm.
typedef implementation_defined no_delay;
Implements the IPPROTO\_TCP/TCP\_NODELAY socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::tcp::no_delay option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:operator_not__eq_ ip::tcp::operator!=]
Compare two protocols for inequality.
friend bool operator!=(
const tcp & p1,
const tcp & p2);
[endsect]
[section:operator_eq__eq_ ip::tcp::operator==]
Compare two protocols for equality.
friend bool operator==(
const tcp & p1,
const tcp & p2);
[endsect]
[section:protocol ip::tcp::protocol]
Obtain an identifier for the protocol.
int protocol() const;
[endsect]
[section:resolver ip::tcp::resolver]
The TCP resolver type.
typedef basic_resolver< tcp > resolver;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.iterator [*iterator]]]
[The iterator type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.query [*query]]]
[The query type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.async_resolve [*async_resolve]]]
[Asynchronously resolve a query to a list of entries. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.basic_resolver [*basic_resolver]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.cancel [*cancel]]]
[Cancel any asynchronous operations that are waiting on the resolver. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.resolve [*resolve]]]
[Resolve a query to a list of entries. ]
]
]
The basic_resolver class template provides the ability to resolve a query to a list of endpoints.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:resolver_iterator ip::tcp::resolver_iterator]
The type of a resolver iterator.
typedef basic_resolver_iterator< tcp > resolver_iterator;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.basic_resolver_iterator [*basic_resolver_iterator]]]
[Default constructor creates an end iterator. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.create [*create]]]
[Create an iterator from an addrinfo list returned by getaddrinfo. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_iterator ip::basic_resolver_iterator] class template is used to define iterators over the results returned by a resolver.
The iterator's value\_type, obtained when the iterator is dereferenced, is:
const basic_resolver_entry<InternetProtocol>
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:resolver_query ip::tcp::resolver_query]
The type of a resolver query.
typedef basic_resolver_query< tcp > resolver_query;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint query. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query [*basic_resolver_query]]]
[Construct with specified service name for any protocol. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.hints [*hints]]]
[Get the hints associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.host_name [*host_name]]]
[Get the host name associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.service_name [*service_name]]]
[Get the service name associated with the query. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.address_configured [*address_configured]]]
[Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.all_matching [*all_matching]]]
[If used with v4_mapped, return all matching IPv6 and IPv4 addresses. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.canonical_name [*canonical_name]]]
[Determine the canonical name of the host specified in the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_host [*numeric_host]]]
[Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_service [*numeric_service]]]
[Service name should be treated as a numeric string defining a port number and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.passive [*passive]]]
[Indicate that returned endpoint is intended for use as a locally bound socket endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.v4_mapped [*v4_mapped]]]
[If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_query ip::basic_resolver_query] class template describes a query that can be passed to a resolver.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:socket ip::tcp::socket]
The TCP socket type.
typedef basic_stream_socket< tcp > socket;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_stream_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_stream_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_stream_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_stream_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_stream_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_stream_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_stream_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_stream_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_stream_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_stream_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_read_some [*async_read_some]]]
[Start an asynchronous read. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_receive [*async_receive]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_send [*async_send]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.basic_stream_socket.async_write_some [*async_write_some]]]
[Start an asynchronous write. ]
]
[
[[link boost_asio.reference.basic_stream_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_stream_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_stream_socket.basic_stream_socket [*basic_stream_socket]]]
[Construct a basic_stream_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_stream_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_stream_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_stream_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_stream_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_stream_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_stream_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_stream_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_stream_socket.read_some [*read_some]]]
[Read some data from the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.receive [*receive]]]
[Receive some data on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.send [*send]]]
[Send some data on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
[
[[link boost_asio.reference.basic_stream_socket.write_some [*write_some]]]
[Write some data to the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_stream_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_stream_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_stream_socket class template provides asynchronous and blocking stream-oriented socket functionality.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:type ip::tcp::type]
Obtain an identifier for the type of the protocol.
int type() const;
[endsect]
[section:v4 ip::tcp::v4]
Construct to represent the IPv4 TCP protocol.
static tcp v4();
[endsect]
[section:v6 ip::tcp::v6]
Construct to represent the IPv6 TCP protocol.
static tcp v6();
[endsect]
[endsect]
[section:ip__udp ip::udp]
Encapsulates the flags needed for UDP.
class udp
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__udp.endpoint [*endpoint]]]
[The type of a UDP endpoint. ]
]
[
[[link boost_asio.reference.ip__udp.resolver [*resolver]]]
[The UDP resolver type. ]
]
[
[[link boost_asio.reference.ip__udp.resolver_iterator [*resolver_iterator]]]
[The type of a resolver iterator. ]
]
[
[[link boost_asio.reference.ip__udp.resolver_query [*resolver_query]]]
[The type of a resolver query. ]
]
[
[[link boost_asio.reference.ip__udp.socket [*socket]]]
[The UDP socket type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__udp.family [*family]]]
[Obtain an identifier for the protocol family. ]
]
[
[[link boost_asio.reference.ip__udp.protocol [*protocol]]]
[Obtain an identifier for the protocol. ]
]
[
[[link boost_asio.reference.ip__udp.type [*type]]]
[Obtain an identifier for the type of the protocol. ]
]
[
[[link boost_asio.reference.ip__udp.v4 [*v4]]]
[Construct to represent the IPv4 UDP protocol. ]
]
[
[[link boost_asio.reference.ip__udp.v6 [*v6]]]
[Construct to represent the IPv6 UDP protocol. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__udp.operator_not__eq_ [*operator!=]]]
[Compare two protocols for inequality. ]
]
[
[[link boost_asio.reference.ip__udp.operator_eq__eq_ [*operator==]]]
[Compare two protocols for equality. ]
]
]
The
[link boost_asio.reference.ip__udp ip::udp] class contains flags necessary for UDP sockets.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Safe.
[section:endpoint ip::udp::endpoint]
The type of a UDP endpoint.
typedef basic_endpoint< udp > endpoint;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.data_type [*data_type]]]
[The type of the endpoint structure. This type is dependent on the underlying implementation of the socket layer. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.address [*address]]]
[Get the IP address associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.basic_endpoint [*basic_endpoint]]]
[Default constructor. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.capacity [*capacity]]]
[Get the capacity of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.data [*data]]]
[Get the underlying endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq_ [*operator=]]]
[Assign from another endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.port [*port]]]
[Get the port associated with the endpoint. The port number is always in the host's byte order. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.protocol [*protocol]]]
[The protocol associated with the endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.resize [*resize]]]
[Set the underlying size of the endpoint in the native type. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.size [*size]]]
[Get the underlying size of the endpoint in the native type. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_not__eq_ [*operator!=]]]
[Compare two endpoints for inequality. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_lt_ [*operator<]]]
[Compare endpoints for ordering. ]
]
[
[[link boost_asio.reference.ip__basic_endpoint.operator_eq__eq_ [*operator==]]]
[Compare two endpoints for equality. ]
]
]
The
[link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] class template describes an endpoint that may be associated with a particular socket.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:family ip::udp::family]
Obtain an identifier for the protocol family.
int family() const;
[endsect]
[section:operator_not__eq_ ip::udp::operator!=]
Compare two protocols for inequality.
friend bool operator!=(
const udp & p1,
const udp & p2);
[endsect]
[section:operator_eq__eq_ ip::udp::operator==]
Compare two protocols for equality.
friend bool operator==(
const udp & p1,
const udp & p2);
[endsect]
[section:protocol ip::udp::protocol]
Obtain an identifier for the protocol.
int protocol() const;
[endsect]
[section:resolver ip::udp::resolver]
The UDP resolver type.
typedef basic_resolver< udp > resolver;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.iterator [*iterator]]]
[The iterator type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.query [*query]]]
[The query type. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver.async_resolve [*async_resolve]]]
[Asynchronously resolve a query to a list of entries. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.basic_resolver [*basic_resolver]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.cancel [*cancel]]]
[Cancel any asynchronous operations that are waiting on the resolver. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ip__basic_resolver.resolve [*resolve]]]
[Resolve a query to a list of entries. ]
]
]
The basic_resolver class template provides the ability to resolve a query to a list of endpoints.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:resolver_iterator ip::udp::resolver_iterator]
The type of a resolver iterator.
typedef basic_resolver_iterator< udp > resolver_iterator;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.basic_resolver_iterator [*basic_resolver_iterator]]]
[Default constructor creates an end iterator. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_iterator.create [*create]]]
[Create an iterator from an addrinfo list returned by getaddrinfo. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_iterator ip::basic_resolver_iterator] class template is used to define iterators over the results returned by a resolver.
The iterator's value\_type, obtained when the iterator is dereferenced, is:
const basic_resolver_entry<InternetProtocol>
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:resolver_query ip::udp::resolver_query]
The type of a resolver query.
typedef basic_resolver_query< udp > resolver_query;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.protocol_type [*protocol_type]]]
[The protocol type associated with the endpoint query. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.basic_resolver_query [*basic_resolver_query]]]
[Construct with specified service name for any protocol. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.hints [*hints]]]
[Get the hints associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.host_name [*host_name]]]
[Get the host name associated with the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.service_name [*service_name]]]
[Get the service name associated with the query. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ip__basic_resolver_query.address_configured [*address_configured]]]
[Only return IPv4 addresses if a non-loopback IPv4 address is configured for the system. Only return IPv6 addresses if a non-loopback IPv6 address is configured for the system. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.all_matching [*all_matching]]]
[If used with v4_mapped, return all matching IPv6 and IPv4 addresses. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.canonical_name [*canonical_name]]]
[Determine the canonical name of the host specified in the query. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_host [*numeric_host]]]
[Host name should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.numeric_service [*numeric_service]]]
[Service name should be treated as a numeric string defining a port number and no name resolution should be attempted. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.passive [*passive]]]
[Indicate that returned endpoint is intended for use as a locally bound socket endpoint. ]
]
[
[[link boost_asio.reference.ip__basic_resolver_query.v4_mapped [*v4_mapped]]]
[If the query protocol family is specified as IPv6, return IPv4-mapped IPv6 addresses on finding no IPv6 addresses. ]
]
]
The
[link boost_asio.reference.ip__basic_resolver_query ip::basic_resolver_query] class template describes a query that can be passed to a resolver.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:socket ip::udp::socket]
The UDP socket type.
typedef basic_datagram_socket< udp > socket;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.implementation_type [*implementation_type]]]
[The underlying implementation type of I/O object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.lowest_layer_type [*lowest_layer_type]]]
[A basic_socket is always the lowest layer. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.native_type [*native_type]]]
[The native representation of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.protocol_type [*protocol_type]]]
[The protocol type. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.service_type [*service_type]]]
[The type of the service that will be used to provide I/O operations. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.assign [*assign]]]
[Assign an existing native socket to the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_receive [*async_receive]]]
[Start an asynchronous receive on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_receive_from [*async_receive_from]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_send [*async_send]]]
[Start an asynchronous send on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.async_send_to [*async_send_to]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.basic_datagram_socket [*basic_datagram_socket]]]
[Construct a basic_datagram_socket without opening it. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.bind [*bind]]]
[Bind the socket to the given local endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.close [*close]]]
[Close the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.connect [*connect]]]
[Connect the socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.get_option [*get_option]]]
[Get an option from the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.local_endpoint [*local_endpoint]]]
[Get the local endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.native [*native]]]
[Get the native socket representation. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.open [*open]]]
[Open the socket using the specified protocol. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive [*receive]]]
[Receive some data on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.receive_from [*receive_from]]]
[Receive a datagram with the endpoint of the sender. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint of the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send [*send]]]
[Send some data on a connected socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.send_to [*send_to]]]
[Send a datagram to the specified endpoint. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.set_option [*set_option]]]
[Set an option on the socket. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_datagram_socket.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.basic_datagram_socket.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
The basic_datagram_socket class template provides asynchronous and blocking datagram-oriented socket functionality.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[endsect]
[section:type ip::udp::type]
Obtain an identifier for the type of the protocol.
int type() const;
[endsect]
[section:v4 ip::udp::v4]
Construct to represent the IPv4 UDP protocol.
static udp v4();
[endsect]
[section:v6 ip::udp::v6]
Construct to represent the IPv6 UDP protocol.
static udp v6();
[endsect]
[endsect]
[section:ip__unicast__hops ip::unicast::hops]
Socket option for time-to-live associated with outgoing unicast packets.
typedef implementation_defined hops;
Implements the IPPROTO\_IP/IP\_UNICAST\_TTL socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::unicast::hops option(4);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::ip::unicast::hops option;
socket.get_option(option);
int ttl = option.value();
[endsect]
[section:ip__v6_only ip::v6_only]
Socket option for determining whether an IPv6 socket supports IPv6 communication only.
typedef implementation_defined v6_only;
Implements the IPPROTO\_IPV6/IP\_V6ONLY socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::v6_only option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::ip::v6_only option;
socket.get_option(option);
bool v6_only = option.value();
[endsect]
[section:is_read_buffered is_read_buffered]
The is_read_buffered class is a traits class that may be used to determine whether a stream type supports buffering of read data.
template<
typename Stream>
class is_read_buffered
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_read_buffered.value [*value]]]
[The value member is true only if the Stream type supports buffering of read data. ]
]
]
[section:value is_read_buffered::value]
The value member is true only if the Stream type supports buffering of read data.
static const bool value;
[endsect]
[endsect]
[section:is_write_buffered is_write_buffered]
The is_write_buffered class is a traits class that may be used to determine whether a stream type supports buffering of written data.
template<
typename Stream>
class is_write_buffered
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_write_buffered.value [*value]]]
[The value member is true only if the Stream type supports buffering of written data. ]
]
]
[section:value is_write_buffered::value]
The value member is true only if the Stream type supports buffering of written data.
static const bool value;
[endsect]
[endsect]
[section:mutable_buffer mutable_buffer]
Holds a buffer that can be modified.
class mutable_buffer
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffer.mutable_buffer [*mutable_buffer]]]
[Construct an empty buffer. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffer.buffer_cast_helper [*buffer_cast_helper]]]
[]
]
[
[[link boost_asio.reference.mutable_buffer.buffer_size_helper [*buffer_size_helper]]]
[]
]
]
The mutable_buffer class provides a safe representation of a buffer that can be modified. It does not own the underlying data, and so is cheap to copy or assign.
[section:buffer_cast_helper mutable_buffer::buffer_cast_helper]
friend void * buffer_cast_helper(
const mutable_buffer & b);
[endsect]
[section:buffer_size_helper mutable_buffer::buffer_size_helper]
friend std::size_t buffer_size_helper(
const mutable_buffer & b);
[endsect]
[section:mutable_buffer mutable_buffer::mutable_buffer]
Construct an empty buffer.
``[link boost_asio.reference.mutable_buffer.mutable_buffer.overload1 mutable_buffer]``();
``[link boost_asio.reference.mutable_buffer.mutable_buffer.overload2 mutable_buffer]``(
void * data,
std::size_t size);
[section:overload1 mutable_buffer::mutable_buffer (1 of 2 overloads)]
Construct an empty buffer.
mutable_buffer();
[endsect]
[section:overload2 mutable_buffer::mutable_buffer (2 of 2 overloads)]
Construct a buffer to represent a given memory range.
mutable_buffer(
void * data,
std::size_t size);
[endsect]
[endsect]
[endsect]
[section:mutable_buffers_1 mutable_buffers_1]
Adapts a single modifiable buffer so that it meets the requirements of the MutableBufferSequence concept.
class mutable_buffers_1 :
public mutable_buffer
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffers_1.const_iterator [*const_iterator]]]
[A random-access iterator type that may be used to read elements. ]
]
[
[[link boost_asio.reference.mutable_buffers_1.value_type [*value_type]]]
[The type for each element in the list of buffers. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffers_1.begin [*begin]]]
[Get a random-access iterator to the first element. ]
]
[
[[link boost_asio.reference.mutable_buffers_1.end [*end]]]
[Get a random-access iterator for one past the last element. ]
]
[
[[link boost_asio.reference.mutable_buffers_1.mutable_buffers_1 [*mutable_buffers_1]]]
[Construct to represent a single modifiable buffer. ]
]
]
[section:begin mutable_buffers_1::begin]
Get a random-access iterator to the first element.
const_iterator begin() const;
[endsect]
[section:const_iterator mutable_buffers_1::const_iterator]
A random-access iterator type that may be used to read elements.
typedef const mutable_buffer * const_iterator;
[endsect]
[section:end mutable_buffers_1::end]
Get a random-access iterator for one past the last element.
const_iterator end() const;
[endsect]
[section:mutable_buffers_1 mutable_buffers_1::mutable_buffers_1]
Construct to represent a single modifiable buffer.
mutable_buffers_1(
const mutable_buffer & b);
[endsect]
[section:value_type mutable_buffers_1::value_type]
The type for each element in the list of buffers.
typedef mutable_buffer value_type;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffer.mutable_buffer [*mutable_buffer]]]
[Construct an empty buffer. ]
]
]
[heading Friends]
[table
[[Name][Description]]
[
[[link boost_asio.reference.mutable_buffer.buffer_cast_helper [*buffer_cast_helper]]]
[]
]
[
[[link boost_asio.reference.mutable_buffer.buffer_size_helper [*buffer_size_helper]]]
[]
]
]
The mutable_buffer class provides a safe representation of a buffer that can be modified. It does not own the underlying data, and so is cheap to copy or assign.
[endsect]
[endsect]
[section:placeholders__bytes_transferred placeholders::bytes_transferred]
An argument placeholder, for use with boost::bind(), that corresponds to the bytes_transferred argument of a handler for asynchronous functions such as boost::asio::basic_stream_socket::async_write_some or boost::asio::async_write.
unspecified bytes_transferred;
[endsect]
[section:placeholders__error placeholders::error]
An argument placeholder, for use with boost::bind(), that corresponds to the error argument of a handler for any of the asynchronous functions.
unspecified error;
[endsect]
[section:placeholders__iterator placeholders::iterator]
An argument placeholder, for use with boost::bind(), that corresponds to the iterator argument of a handler for asynchronous functions such as boost::asio::basic_resolver::resolve.
unspecified iterator;
[endsect]
[section:read read]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.read.overload1 read]``(
SyncReadStream & s,
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.read.overload2 read]``(
SyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.read.overload3 read]``(
SyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition,
boost::system::error_code & ec);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read.overload4 read]``(
SyncReadStream & s,
basic_streambuf< Allocator > & b);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.read.overload5 read]``(
SyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.read.overload6 read]``(
SyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
boost::system::error_code & ec);
[section:overload1 read (1 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read(
SyncReadStream & s,
const MutableBufferSequence & buffers);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::read(s, boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[heading Remarks]
This overload is equivalent to calling:
boost::asio::read(
s, buffers,
boost::asio::transfer_all());
[endsect]
[section:overload2 read (2 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition>
std::size_t read(
SyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's read\_some function are required.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To read into a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::read(s, boost::asio::buffer(data, size),
boost::asio::transfer_at_least(32));
See the
[link boost_asio.reference.buffer buffer] documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 read (3 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename CompletionCondition>
std::size_t read(
SyncReadStream & s,
const MutableBufferSequence & buffers,
CompletionCondition completion_condition,
boost::system::error_code & ec);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* The supplied buffers are full. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[buffers][One or more buffers into which the data will be read. The sum of the buffer sizes indicates the maximum number of bytes to read from the stream.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's read\_some function are required.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes read. If an error occurs, returns the total number of bytes successfully transferred prior to the error.
[endsect]
[section:overload4 read (4 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read(
SyncReadStream & s,
basic_streambuf< Allocator > & b);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][The basic\_streambuf object into which the data will be read.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
This overload is equivalent to calling:
boost::asio::read(
s, b,
boost::asio::transfer_all());
[endsect]
[section:overload5 read (5 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t read(
SyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][The basic\_streambuf object into which the data will be read.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's read\_some function are required.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload6 read (6 of 6 overloads)]
Attempt to read a certain amount of data from a stream before returning.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t read(
SyncReadStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
boost::system::error_code & ec);
This function is used to read a certain number of bytes of data from a stream. The call will block until one of the following conditions is true:
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's read\_some function.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][The basic\_streambuf object into which the data will be read.]]
[[completion_condition][The function object to be called to determine whether the read operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest read_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the read operation is complete. False indicates that further calls to the stream's read\_some function are required.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes read. If an error occurs, returns the total number of bytes successfully transferred prior to the error.
[endsect]
[endsect]
[section:read_until read_until]
Read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload1 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload2 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim,
boost::system::error_code & ec);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload3 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload4 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim,
boost::system::error_code & ec);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload5 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr);
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.read_until.overload6 read_until]``(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr,
boost::system::error_code & ec);
[section:overload1 read_until (1 of 6 overloads)]
Read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim);
This function is used to read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The call will block until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains the delimiter, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[delim][The delimiter character.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the delimiter.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To read data into a streambuf until a newline is encountered:
boost::asio::streambuf b;
boost::asio::read_until(s, b, '\n');
std::istream is(&b);
std::string line;
std::getline(is, line);
[endsect]
[section:overload2 read_until (2 of 6 overloads)]
Read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
char delim,
boost::system::error_code & ec);
This function is used to read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The call will block until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains the delimiter, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[delim][The delimiter character.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the delimiter. Returns 0 if an error occurred.
[endsect]
[section:overload3 read_until (3 of 6 overloads)]
Read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim);
This function is used to read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The call will block until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains the delimiter, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[delim][The delimiter string.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the delimiter.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To read data into a streambuf until a newline is encountered:
boost::asio::streambuf b;
boost::asio::read_until(s, b, "\r\n");
std::istream is(&b);
std::string line;
std::getline(is, line);
[endsect]
[section:overload4 read_until (4 of 6 overloads)]
Read data into a streambuf until a delimiter is encountered.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const std::string & delim,
boost::system::error_code & ec);
This function is used to read data into the specified streambuf until the streambuf's get area contains the specified delimiter. The call will block until one of the following conditions is true:
* The get area of the streambuf contains the specified delimiter.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains the delimiter, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[delim][The delimiter string.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the delimiter. Returns 0 if an error occurred.
[endsect]
[section:overload5 read_until (5 of 6 overloads)]
Read data into a streambuf until a regular expression is located.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr);
This function is used to read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The call will block until one of the following conditions is true:
* A substring of the streambuf's get area matches the regular expression.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[expr][The regular expression.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the substring that matches the regular expression.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To read data into a streambuf until a CR-LF sequence is encountered:
boost::asio::streambuf b;
boost::asio::read_until(s, b, boost::regex("\r\n"));
std::istream is(&b);
std::string line;
std::getline(is, line);
[endsect]
[section:overload6 read_until (6 of 6 overloads)]
Read data into a streambuf until a regular expression is located.
template<
typename ``[link boost_asio.reference.SyncReadStream SyncReadStream]``,
typename Allocator>
std::size_t read_until(
SyncReadStream & s,
boost::asio::basic_streambuf< Allocator > & b,
const boost::regex & expr,
boost::system::error_code & ec);
This function is used to read data into the specified streambuf until the streambuf's get area contains some data that matches a regular expression. The call will block until one of the following conditions is true:
* A substring of the streambuf's get area matches the regular expression.
* An error occurred.
This operation is implemented in terms of zero or more calls to the stream's read\_some function. If the streambuf's get area already contains data that matches the regular expression, the function returns immediately.
[heading Parameters]
[variablelist
[[s][The stream from which the data is to be read. The type must support the SyncReadStream concept.]]
[[b][A streambuf object into which the data will be read.]]
[[expr][The regular expression.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes in the streambuf's get area up to and including the substring that matches the regular expression. Returns 0 if an error occurred.
[endsect]
[endsect]
[section:service_already_exists service_already_exists]
Exception thrown when trying to add a duplicate service to an io_service.
class service_already_exists
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.service_already_exists.service_already_exists [*service_already_exists]]]
[]
]
]
[section:service_already_exists service_already_exists::service_already_exists]
service_already_exists();
[endsect]
[endsect]
[section:socket_acceptor_service socket_acceptor_service]
Default service implementation for a socket acceptor.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``>
class socket_acceptor_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.socket_acceptor_service.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.implementation_type [*implementation_type]]]
[The native type of the socket acceptor. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.native_type [*native_type]]]
[The native acceptor type. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.protocol_type [*protocol_type]]]
[The protocol type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.socket_acceptor_service.accept [*accept]]]
[Accept a new connection. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.assign [*assign]]]
[Assign an existing native acceptor to a socket acceptor. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.async_accept [*async_accept]]]
[Start an asynchronous accept. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.bind [*bind]]]
[Bind the socket acceptor to the specified local endpoint. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the acceptor. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.close [*close]]]
[Close a socket acceptor implementation. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.construct [*construct]]]
[Construct a new socket acceptor implementation. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.destroy [*destroy]]]
[Destroy a socket acceptor implementation. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.get_option [*get_option]]]
[Get a socket option. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.is_open [*is_open]]]
[Determine whether the acceptor is open. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.listen [*listen]]]
[Place the socket acceptor into the state where it will listen for new connections. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.local_endpoint [*local_endpoint]]]
[Get the local endpoint. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.native [*native]]]
[Get the native acceptor implementation. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.open [*open]]]
[Open a new socket acceptor implementation. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.set_option [*set_option]]]
[Set a socket option. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
[
[[link boost_asio.reference.socket_acceptor_service.socket_acceptor_service [*socket_acceptor_service]]]
[Construct a new socket acceptor service for the specified io_service. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.socket_acceptor_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:accept socket_acceptor_service::accept]
Accept a new connection.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``>
boost::system::error_code accept(
implementation_type & impl,
basic_socket< protocol_type, SocketService > & peer,
endpoint_type * peer_endpoint,
boost::system::error_code & ec);
[endsect]
[section:assign socket_acceptor_service::assign]
Assign an existing native acceptor to a socket acceptor.
boost::system::error_code assign(
implementation_type & impl,
const protocol_type & protocol,
const native_type & native_acceptor,
boost::system::error_code & ec);
[endsect]
[section:async_accept socket_acceptor_service::async_accept]
Start an asynchronous accept.
template<
typename ``[link boost_asio.reference.SocketService SocketService]``,
typename ``[link boost_asio.reference.AcceptHandler AcceptHandler]``>
void async_accept(
implementation_type & impl,
basic_socket< protocol_type, SocketService > & peer,
endpoint_type * peer_endpoint,
AcceptHandler handler);
[endsect]
[section:bind socket_acceptor_service::bind]
Bind the socket acceptor to the specified local endpoint.
boost::system::error_code bind(
implementation_type & impl,
const endpoint_type & endpoint,
boost::system::error_code & ec);
[endsect]
[section:cancel socket_acceptor_service::cancel]
Cancel all asynchronous operations associated with the acceptor.
boost::system::error_code cancel(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:close socket_acceptor_service::close]
Close a socket acceptor implementation.
boost::system::error_code close(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:construct socket_acceptor_service::construct]
Construct a new socket acceptor implementation.
void construct(
implementation_type & impl);
[endsect]
[section:destroy socket_acceptor_service::destroy]
Destroy a socket acceptor implementation.
void destroy(
implementation_type & impl);
[endsect]
[section:endpoint_type socket_acceptor_service::endpoint_type]
The endpoint type.
typedef protocol_type::endpoint endpoint_type;
[endsect]
[section:get_io_service socket_acceptor_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:get_option socket_acceptor_service::get_option]
Get a socket option.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code get_option(
const implementation_type & impl,
GettableSocketOption & option,
boost::system::error_code & ec) const;
[endsect]
[section:id socket_acceptor_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:implementation_type socket_acceptor_service::implementation_type]
The native type of the socket acceptor.
typedef implementation_defined implementation_type;
[endsect]
[section:io_control socket_acceptor_service::io_control]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
boost::system::error_code io_control(
implementation_type & impl,
IoControlCommand & command,
boost::system::error_code & ec);
[endsect]
[section:io_service socket_acceptor_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:is_open socket_acceptor_service::is_open]
Determine whether the acceptor is open.
bool is_open(
const implementation_type & impl) const;
[endsect]
[section:listen socket_acceptor_service::listen]
Place the socket acceptor into the state where it will listen for new connections.
boost::system::error_code listen(
implementation_type & impl,
int backlog,
boost::system::error_code & ec);
[endsect]
[section:local_endpoint socket_acceptor_service::local_endpoint]
Get the local endpoint.
endpoint_type local_endpoint(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:native socket_acceptor_service::native]
Get the native acceptor implementation.
native_type native(
implementation_type & impl);
[endsect]
[section:native_type socket_acceptor_service::native_type]
The native acceptor type.
typedef implementation_defined native_type;
[endsect]
[section:open socket_acceptor_service::open]
Open a new socket acceptor implementation.
boost::system::error_code open(
implementation_type & impl,
const protocol_type & protocol,
boost::system::error_code & ec);
[endsect]
[section:protocol_type socket_acceptor_service::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:set_option socket_acceptor_service::set_option]
Set a socket option.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code set_option(
implementation_type & impl,
const SettableSocketOption & option,
boost::system::error_code & ec);
[endsect]
[section:shutdown_service socket_acceptor_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[section:socket_acceptor_service socket_acceptor_service::socket_acceptor_service]
Construct a new socket acceptor service for the specified io_service.
socket_acceptor_service(
boost::asio::io_service & io_service);
[endsect]
[endsect]
[section:socket_base socket_base]
The socket_base class is used as a base for the basic_stream_socket and basic_datagram_socket class templates so that we have a common place to define the shutdown_type and enum.
class socket_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.socket_base.broadcast [*broadcast]]]
[Socket option to permit sending of broadcast messages. ]
]
[
[[link boost_asio.reference.socket_base.bytes_readable [*bytes_readable]]]
[IO control command to get the amount of data that can be read without blocking. ]
]
[
[[link boost_asio.reference.socket_base.debug [*debug]]]
[Socket option to enable socket-level debugging. ]
]
[
[[link boost_asio.reference.socket_base.do_not_route [*do_not_route]]]
[Socket option to prevent routing, use local interfaces only. ]
]
[
[[link boost_asio.reference.socket_base.enable_connection_aborted [*enable_connection_aborted]]]
[Socket option to report aborted connections on accept. ]
]
[
[[link boost_asio.reference.socket_base.keep_alive [*keep_alive]]]
[Socket option to send keep-alives. ]
]
[
[[link boost_asio.reference.socket_base.linger [*linger]]]
[Socket option to specify whether the socket lingers on close if unsent data is present. ]
]
[
[[link boost_asio.reference.socket_base.message_flags [*message_flags]]]
[Bitmask type for flags that can be passed to send and receive operations. ]
]
[
[[link boost_asio.reference.socket_base.non_blocking_io [*non_blocking_io]]]
[IO control command to set the blocking mode of the socket. ]
]
[
[[link boost_asio.reference.socket_base.receive_buffer_size [*receive_buffer_size]]]
[Socket option for the receive buffer size of a socket. ]
]
[
[[link boost_asio.reference.socket_base.receive_low_watermark [*receive_low_watermark]]]
[Socket option for the receive low watermark. ]
]
[
[[link boost_asio.reference.socket_base.reuse_address [*reuse_address]]]
[Socket option to allow the socket to be bound to an address that is already in use. ]
]
[
[[link boost_asio.reference.socket_base.send_buffer_size [*send_buffer_size]]]
[Socket option for the send buffer size of a socket. ]
]
[
[[link boost_asio.reference.socket_base.send_low_watermark [*send_low_watermark]]]
[Socket option for the send low watermark. ]
]
[
[[link boost_asio.reference.socket_base.shutdown_type [*shutdown_type]]]
[Different ways a socket may be shutdown. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.socket_base.max_connections [*max_connections]]]
[The maximum length of the queue of pending incoming connections. ]
]
[
[[link boost_asio.reference.socket_base.message_do_not_route [*message_do_not_route]]]
[Specify that the data should not be subject to routing. ]
]
[
[[link boost_asio.reference.socket_base.message_out_of_band [*message_out_of_band]]]
[Process out-of-band data. ]
]
[
[[link boost_asio.reference.socket_base.message_peek [*message_peek]]]
[Peek at incoming data without removing it from the input queue. ]
]
]
[section:broadcast socket_base::broadcast]
Socket option to permit sending of broadcast messages.
typedef implementation_defined broadcast;
Implements the SOL\_SOCKET/SO\_BROADCAST socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::broadcast option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:bytes_readable socket_base::bytes_readable]
IO control command to get the amount of data that can be read without blocking.
typedef implementation_defined bytes_readable;
Implements the FIONREAD IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::bytes_readable command(true);
socket.io_control(command);
std::size_t bytes_readable = command.get();
[endsect]
[section:debug socket_base::debug]
Socket option to enable socket-level debugging.
typedef implementation_defined debug;
Implements the SOL\_SOCKET/SO\_DEBUG socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::debug option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:do_not_route socket_base::do_not_route]
Socket option to prevent routing, use local interfaces only.
typedef implementation_defined do_not_route;
Implements the SOL\_SOCKET/SO\_DONTROUTE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::udp::socket socket(io_service);
...
boost::asio::socket_base::do_not_route option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:enable_connection_aborted socket_base::enable_connection_aborted]
Socket option to report aborted connections on accept.
typedef implementation_defined enable_connection_aborted;
Implements a custom socket option that determines whether or not an accept operation is permitted to fail with boost::asio::error::connection\_aborted. By default the option is false.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::enable_connection_aborted option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:keep_alive socket_base::keep_alive]
Socket option to send keep-alives.
typedef implementation_defined keep_alive;
Implements the SOL\_SOCKET/SO\_KEEPALIVE socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option(true);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::keep_alive option;
socket.get_option(option);
bool is_set = option.value();
[endsect]
[section:linger socket_base::linger]
Socket option to specify whether the socket lingers on close if unsent data is present.
typedef implementation_defined linger;
Implements the SOL\_SOCKET/SO\_LINGER socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option(true, 30);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::linger option;
socket.get_option(option);
bool is_set = option.enabled();
unsigned short timeout = option.timeout();
[endsect]
[section:max_connections socket_base::max_connections]
The maximum length of the queue of pending incoming connections.
static const int max_connections = implementation_defined;
[endsect]
[section:message_do_not_route socket_base::message_do_not_route]
Specify that the data should not be subject to routing.
static const int message_do_not_route = implementation_defined;
[endsect]
[section:message_flags socket_base::message_flags]
Bitmask type for flags that can be passed to send and receive operations.
typedef int message_flags;
[endsect]
[section:message_out_of_band socket_base::message_out_of_band]
Process out-of-band data.
static const int message_out_of_band = implementation_defined;
[endsect]
[section:message_peek socket_base::message_peek]
Peek at incoming data without removing it from the input queue.
static const int message_peek = implementation_defined;
[endsect]
[section:non_blocking_io socket_base::non_blocking_io]
IO control command to set the blocking mode of the socket.
typedef implementation_defined non_blocking_io;
Implements the FIONBIO IO control command.
[heading Example]
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::non_blocking_io command(true);
socket.io_control(command);
[endsect]
[section:receive_buffer_size socket_base::receive_buffer_size]
Socket option for the receive buffer size of a socket.
typedef implementation_defined receive_buffer_size;
Implements the SOL\_SOCKET/SO\_RCVBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:receive_low_watermark socket_base::receive_low_watermark]
Socket option for the receive low watermark.
typedef implementation_defined receive_low_watermark;
Implements the SOL\_SOCKET/SO\_RCVLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::receive_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:reuse_address socket_base::reuse_address]
Socket option to allow the socket to be bound to an address that is already in use.
typedef implementation_defined reuse_address;
Implements the SOL\_SOCKET/SO\_REUSEADDR socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option(true);
acceptor.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::acceptor acceptor(io_service);
...
boost::asio::socket_base::reuse_address option;
acceptor.get_option(option);
bool is_set = option.value();
[endsect]
[section:send_buffer_size socket_base::send_buffer_size]
Socket option for the send buffer size of a socket.
typedef implementation_defined send_buffer_size;
Implements the SOL\_SOCKET/SO\_SNDBUF socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option(8192);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_buffer_size option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:send_low_watermark socket_base::send_low_watermark]
Socket option for the send low watermark.
typedef implementation_defined send_low_watermark;
Implements the SOL\_SOCKET/SO\_SNDLOWAT socket option.
[heading Examples]
Setting the option:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option(1024);
socket.set_option(option);
Getting the current option value:
boost::asio::ip::tcp::socket socket(io_service);
...
boost::asio::socket_base::send_low_watermark option;
socket.get_option(option);
int size = option.value();
[endsect]
[section:shutdown_type socket_base::shutdown_type]
Different ways a socket may be shutdown.
enum shutdown_type
[heading Values]
[variablelist
[
[shutdown_receive]
[Shutdown the receive side of the socket. ]
]
[
[shutdown_send]
[Shutdown the send side of the socket. ]
]
[
[shutdown_both]
[Shutdown both send and receive on the socket. ]
]
]
[endsect]
[endsect]
[section:ssl__basic_context ssl::basic_context]
SSL context.
template<
typename ``[link boost_asio.reference.Service Service]``>
class basic_context :
public ssl::context_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.file_format [*file_format]]]
[File format types. ]
]
[
[[link boost_asio.reference.ssl__basic_context.impl_type [*impl_type]]]
[The native implementation type of the locking dispatcher. ]
]
[
[[link boost_asio.reference.ssl__basic_context.method [*method]]]
[Different methods supported by a context. ]
]
[
[[link boost_asio.reference.ssl__basic_context.options [*options]]]
[Bitmask type for SSL options. ]
]
[
[[link boost_asio.reference.ssl__basic_context.password_purpose [*password_purpose]]]
[Purpose of PEM password. ]
]
[
[[link boost_asio.reference.ssl__basic_context.service_type [*service_type]]]
[The type of the service that will be used to provide context operations. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_mode [*verify_mode]]]
[Bitmask type for peer verification. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.add_verify_path [*add_verify_path]]]
[Add a directory containing certificate authority files to be used for performing verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.basic_context [*basic_context]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ssl__basic_context.impl [*impl]]]
[Get the underlying implementation in the native type. ]
]
[
[[link boost_asio.reference.ssl__basic_context.load_verify_file [*load_verify_file]]]
[Load a certification authority file for performing verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_options [*set_options]]]
[Set options on the context. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_password_callback [*set_password_callback]]]
[Set the password callback. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_verify_mode [*set_verify_mode]]]
[Set the peer verification mode. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_certificate_chain_file [*use_certificate_chain_file]]]
[Use a certificate chain from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_certificate_file [*use_certificate_file]]]
[Use a certificate from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_private_key_file [*use_private_key_file]]]
[Use a private key from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_rsa_private_key_file [*use_rsa_private_key_file]]]
[Use an RSA private key from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_tmp_dh_file [*use_tmp_dh_file]]]
[Use the specified file to obtain the temporary Diffie-Hellman parameters. ]
]
[
[[link boost_asio.reference.ssl__basic_context._basic_context [*~basic_context]]]
[Destructor. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.default_workarounds [*default_workarounds]]]
[Implement various bug workarounds. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_sslv2 [*no_sslv2]]]
[Disable SSL v2. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_sslv3 [*no_sslv3]]]
[Disable SSL v3. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_tlsv1 [*no_tlsv1]]]
[Disable TLS v1. ]
]
[
[[link boost_asio.reference.ssl__basic_context.single_dh_use [*single_dh_use]]]
[Always create a new key when using tmp_dh parameters. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_client_once [*verify_client_once]]]
[Do not request client certificate on renegotiation. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_fail_if_no_peer_cert [*verify_fail_if_no_peer_cert]]]
[Fail verification if the peer has no certificate. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_none [*verify_none]]]
[No verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_peer [*verify_peer]]]
[Verify the peer. ]
]
]
[section:add_verify_path ssl::basic_context::add_verify_path]
Add a directory containing certificate authority files to be used for performing verification.
void ``[link boost_asio.reference.ssl__basic_context.add_verify_path.overload1 add_verify_path]``(
const std::string & path);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.add_verify_path.overload2 add_verify_path]``(
const std::string & path,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::add_verify_path (1 of 2 overloads)]
Add a directory containing certificate authority files to be used for performing verification.
void add_verify_path(
const std::string & path);
This function is used to specify the name of a directory containing certification authority certificates. Each file in the directory must contain a single certificate. The files must be named using the subject name's hash and an extension of ".0".
[heading Parameters]
[variablelist
[[path][The name of a directory containing the certificates.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::add_verify_path (2 of 2 overloads)]
Add a directory containing certificate authority files to be used for performing verification.
boost::system::error_code add_verify_path(
const std::string & path,
boost::system::error_code & ec);
This function is used to specify the name of a directory containing certification authority certificates. Each file in the directory must contain a single certificate. The files must be named using the subject name's hash and an extension of ".0".
[heading Parameters]
[variablelist
[[path][The name of a directory containing the certificates.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:basic_context ssl::basic_context::basic_context]
Constructor.
basic_context(
boost::asio::io_service & io_service,
method m);
[endsect]
[section:default_workarounds ssl::basic_context::default_workarounds]
['Inherited from ssl::context_base.]
Implement various bug workarounds.
static const int default_workarounds = implementation_defined;
[endsect]
[section:file_format ssl::basic_context::file_format]
['Inherited from ssl::context_base.]
File format types.
enum file_format
[heading Values]
[variablelist
[
[asn1]
[ASN.1 file. ]
]
[
[pem]
[PEM file. ]
]
]
[endsect]
[section:impl ssl::basic_context::impl]
Get the underlying implementation in the native type.
impl_type impl();
This function may be used to obtain the underlying implementation of the context. This is intended to allow access to context functionality that is not otherwise provided.
[endsect]
[section:impl_type ssl::basic_context::impl_type]
The native implementation type of the locking dispatcher.
typedef service_type::impl_type impl_type;
[endsect]
[section:load_verify_file ssl::basic_context::load_verify_file]
Load a certification authority file for performing verification.
void ``[link boost_asio.reference.ssl__basic_context.load_verify_file.overload1 load_verify_file]``(
const std::string & filename);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.load_verify_file.overload2 load_verify_file]``(
const std::string & filename,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::load_verify_file (1 of 2 overloads)]
Load a certification authority file for performing verification.
void load_verify_file(
const std::string & filename);
This function is used to load one or more trusted certification authorities from a file.
[heading Parameters]
[variablelist
[[filename][The name of a file containing certification authority certificates in PEM format.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::load_verify_file (2 of 2 overloads)]
Load a certification authority file for performing verification.
boost::system::error_code load_verify_file(
const std::string & filename,
boost::system::error_code & ec);
This function is used to load the certificates for one or more trusted certification authorities from a file.
[heading Parameters]
[variablelist
[[filename][The name of a file containing certification authority certificates in PEM format.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:method ssl::basic_context::method]
['Inherited from ssl::context_base.]
Different methods supported by a context.
enum method
[heading Values]
[variablelist
[
[sslv2]
[Generic SSL version 2. ]
]
[
[sslv2_client]
[SSL version 2 client. ]
]
[
[sslv2_server]
[SSL version 2 server. ]
]
[
[sslv3]
[Generic SSL version 3. ]
]
[
[sslv3_client]
[SSL version 3 client. ]
]
[
[sslv3_server]
[SSL version 3 server. ]
]
[
[tlsv1]
[Generic TLS version 1. ]
]
[
[tlsv1_client]
[TLS version 1 client. ]
]
[
[tlsv1_server]
[TLS version 1 server. ]
]
[
[sslv23]
[Generic SSL/TLS. ]
]
[
[sslv23_client]
[SSL/TLS client. ]
]
[
[sslv23_server]
[SSL/TLS server. ]
]
]
[endsect]
[section:no_sslv2 ssl::basic_context::no_sslv2]
['Inherited from ssl::context_base.]
Disable SSL v2.
static const int no_sslv2 = implementation_defined;
[endsect]
[section:no_sslv3 ssl::basic_context::no_sslv3]
['Inherited from ssl::context_base.]
Disable SSL v3.
static const int no_sslv3 = implementation_defined;
[endsect]
[section:no_tlsv1 ssl::basic_context::no_tlsv1]
['Inherited from ssl::context_base.]
Disable TLS v1.
static const int no_tlsv1 = implementation_defined;
[endsect]
[section:options ssl::basic_context::options]
['Inherited from ssl::context_base.]
Bitmask type for SSL options.
typedef int options;
[endsect]
[section:password_purpose ssl::basic_context::password_purpose]
['Inherited from ssl::context_base.]
Purpose of PEM password.
enum password_purpose
[heading Values]
[variablelist
[
[for_reading]
[The password is needed for reading/decryption. ]
]
[
[for_writing]
[The password is needed for writing/encryption. ]
]
]
[endsect]
[section:service_type ssl::basic_context::service_type]
The type of the service that will be used to provide context operations.
typedef Service service_type;
[endsect]
[section:set_options ssl::basic_context::set_options]
Set options on the context.
void ``[link boost_asio.reference.ssl__basic_context.set_options.overload1 set_options]``(
options o);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.set_options.overload2 set_options]``(
options o,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::set_options (1 of 2 overloads)]
Set options on the context.
void set_options(
options o);
This function may be used to configure the SSL options used by the context.
[heading Parameters]
[variablelist
[[o][A bitmask of options. The available option values are defined in the context\_base class. The options are bitwise-ored with any existing value for the options.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::set_options (2 of 2 overloads)]
Set options on the context.
boost::system::error_code set_options(
options o,
boost::system::error_code & ec);
This function may be used to configure the SSL options used by the context.
[heading Parameters]
[variablelist
[[o][A bitmask of options. The available option values are defined in the context\_base class. The options are bitwise-ored with any existing value for the options.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:set_password_callback ssl::basic_context::set_password_callback]
Set the password callback.
template<
typename PasswordCallback>
void ``[link boost_asio.reference.ssl__basic_context.set_password_callback.overload1 set_password_callback]``(
PasswordCallback callback);
template<
typename PasswordCallback>
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.set_password_callback.overload2 set_password_callback]``(
PasswordCallback callback,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::set_password_callback (1 of 2 overloads)]
Set the password callback.
template<
typename PasswordCallback>
void set_password_callback(
PasswordCallback callback);
This function is used to specify a callback function to obtain password information about an encrypted key in PEM format.
[heading Parameters]
[variablelist
[[callback][The function object to be used for obtaining the password. The function signature of the handler must be:
``
std::string password_callback(
std::size_t max_length, // The maximum size for a password.
password_purpose purpose // Whether password is for reading or writing.
);
``
The return value of the callback is a string containing the password.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::set_password_callback (2 of 2 overloads)]
Set the password callback.
template<
typename PasswordCallback>
boost::system::error_code set_password_callback(
PasswordCallback callback,
boost::system::error_code & ec);
This function is used to specify a callback function to obtain password information about an encrypted key in PEM format.
[heading Parameters]
[variablelist
[[callback][The function object to be used for obtaining the password. The function signature of the handler must be:
``
std::string password_callback(
std::size_t max_length, // The maximum size for a password.
password_purpose purpose // Whether password is for reading or writing.
);
``
The return value of the callback is a string containing the password.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:set_verify_mode ssl::basic_context::set_verify_mode]
Set the peer verification mode.
void ``[link boost_asio.reference.ssl__basic_context.set_verify_mode.overload1 set_verify_mode]``(
verify_mode v);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.set_verify_mode.overload2 set_verify_mode]``(
verify_mode v,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::set_verify_mode (1 of 2 overloads)]
Set the peer verification mode.
void set_verify_mode(
verify_mode v);
This function may be used to configure the peer verification mode used by the context.
[heading Parameters]
[variablelist
[[v][A bitmask of peer verification modes. The available verify\_mode values are defined in the context\_base class.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::set_verify_mode (2 of 2 overloads)]
Set the peer verification mode.
boost::system::error_code set_verify_mode(
verify_mode v,
boost::system::error_code & ec);
This function may be used to configure the peer verification mode used by the context.
[heading Parameters]
[variablelist
[[v][A bitmask of peer verification modes. The available verify\_mode values are defined in the context\_base class.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:single_dh_use ssl::basic_context::single_dh_use]
['Inherited from ssl::context_base.]
Always create a new key when using tmp_dh parameters.
static const int single_dh_use = implementation_defined;
[endsect]
[section:use_certificate_chain_file ssl::basic_context::use_certificate_chain_file]
Use a certificate chain from a file.
void ``[link boost_asio.reference.ssl__basic_context.use_certificate_chain_file.overload1 use_certificate_chain_file]``(
const std::string & filename);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.use_certificate_chain_file.overload2 use_certificate_chain_file]``(
const std::string & filename,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::use_certificate_chain_file (1 of 2 overloads)]
Use a certificate chain from a file.
void use_certificate_chain_file(
const std::string & filename);
This function is used to load a certificate chain into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the certificate. The file must use the PEM format.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::use_certificate_chain_file (2 of 2 overloads)]
Use a certificate chain from a file.
boost::system::error_code use_certificate_chain_file(
const std::string & filename,
boost::system::error_code & ec);
This function is used to load a certificate chain into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the certificate. The file must use the PEM format.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:use_certificate_file ssl::basic_context::use_certificate_file]
Use a certificate from a file.
void ``[link boost_asio.reference.ssl__basic_context.use_certificate_file.overload1 use_certificate_file]``(
const std::string & filename,
file_format format);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.use_certificate_file.overload2 use_certificate_file]``(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::use_certificate_file (1 of 2 overloads)]
Use a certificate from a file.
void use_certificate_file(
const std::string & filename,
file_format format);
This function is used to load a certificate into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the certificate.]]
[[format][The file format (ASN.1 or PEM).]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::use_certificate_file (2 of 2 overloads)]
Use a certificate from a file.
boost::system::error_code use_certificate_file(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
This function is used to load a certificate into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the certificate.]]
[[format][The file format (ASN.1 or PEM).]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:use_private_key_file ssl::basic_context::use_private_key_file]
Use a private key from a file.
void ``[link boost_asio.reference.ssl__basic_context.use_private_key_file.overload1 use_private_key_file]``(
const std::string & filename,
file_format format);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.use_private_key_file.overload2 use_private_key_file]``(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::use_private_key_file (1 of 2 overloads)]
Use a private key from a file.
void use_private_key_file(
const std::string & filename,
file_format format);
This function is used to load a private key into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the private key.]]
[[format][The file format (ASN.1 or PEM).]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::use_private_key_file (2 of 2 overloads)]
Use a private key from a file.
boost::system::error_code use_private_key_file(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
This function is used to load a private key into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the private key.]]
[[format][The file format (ASN.1 or PEM).]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:use_rsa_private_key_file ssl::basic_context::use_rsa_private_key_file]
Use an RSA private key from a file.
void ``[link boost_asio.reference.ssl__basic_context.use_rsa_private_key_file.overload1 use_rsa_private_key_file]``(
const std::string & filename,
file_format format);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.use_rsa_private_key_file.overload2 use_rsa_private_key_file]``(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::use_rsa_private_key_file (1 of 2 overloads)]
Use an RSA private key from a file.
void use_rsa_private_key_file(
const std::string & filename,
file_format format);
This function is used to load an RSA private key into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the RSA private key.]]
[[format][The file format (ASN.1 or PEM).]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::use_rsa_private_key_file (2 of 2 overloads)]
Use an RSA private key from a file.
boost::system::error_code use_rsa_private_key_file(
const std::string & filename,
file_format format,
boost::system::error_code & ec);
This function is used to load an RSA private key into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the RSA private key.]]
[[format][The file format (ASN.1 or PEM).]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:use_tmp_dh_file ssl::basic_context::use_tmp_dh_file]
Use the specified file to obtain the temporary Diffie-Hellman parameters.
void ``[link boost_asio.reference.ssl__basic_context.use_tmp_dh_file.overload1 use_tmp_dh_file]``(
const std::string & filename);
boost::system::error_code ``[link boost_asio.reference.ssl__basic_context.use_tmp_dh_file.overload2 use_tmp_dh_file]``(
const std::string & filename,
boost::system::error_code & ec);
[section:overload1 ssl::basic_context::use_tmp_dh_file (1 of 2 overloads)]
Use the specified file to obtain the temporary Diffie-Hellman parameters.
void use_tmp_dh_file(
const std::string & filename);
This function is used to load Diffie-Hellman parameters into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the Diffie-Hellman parameters. The file must use the PEM format.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::basic_context::use_tmp_dh_file (2 of 2 overloads)]
Use the specified file to obtain the temporary Diffie-Hellman parameters.
boost::system::error_code use_tmp_dh_file(
const std::string & filename,
boost::system::error_code & ec);
This function is used to load Diffie-Hellman parameters into the context from a file.
[heading Parameters]
[variablelist
[[filename][The name of the file containing the Diffie-Hellman parameters. The file must use the PEM format.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:verify_client_once ssl::basic_context::verify_client_once]
['Inherited from ssl::context_base.]
Do not request client certificate on renegotiation. Ignored unless verify_peer is set.
static const int verify_client_once = implementation_defined;
[endsect]
[section:verify_fail_if_no_peer_cert ssl::basic_context::verify_fail_if_no_peer_cert]
['Inherited from ssl::context_base.]
Fail verification if the peer has no certificate. Ignored unless verify_peer is set.
static const int verify_fail_if_no_peer_cert = implementation_defined;
[endsect]
[section:verify_mode ssl::basic_context::verify_mode]
['Inherited from ssl::context_base.]
Bitmask type for peer verification.
typedef int verify_mode;
[endsect]
[section:verify_none ssl::basic_context::verify_none]
['Inherited from ssl::context_base.]
No verification.
static const int verify_none = implementation_defined;
[endsect]
[section:verify_peer ssl::basic_context::verify_peer]
['Inherited from ssl::context_base.]
Verify the peer.
static const int verify_peer = implementation_defined;
[endsect]
[section:_basic_context ssl::basic_context::~basic_context]
Destructor.
~basic_context();
[endsect]
[endsect]
[section:ssl__context ssl::context]
Typedef for the typical usage of context.
typedef basic_context< context_service > context;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.file_format [*file_format]]]
[File format types. ]
]
[
[[link boost_asio.reference.ssl__basic_context.impl_type [*impl_type]]]
[The native implementation type of the locking dispatcher. ]
]
[
[[link boost_asio.reference.ssl__basic_context.method [*method]]]
[Different methods supported by a context. ]
]
[
[[link boost_asio.reference.ssl__basic_context.options [*options]]]
[Bitmask type for SSL options. ]
]
[
[[link boost_asio.reference.ssl__basic_context.password_purpose [*password_purpose]]]
[Purpose of PEM password. ]
]
[
[[link boost_asio.reference.ssl__basic_context.service_type [*service_type]]]
[The type of the service that will be used to provide context operations. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_mode [*verify_mode]]]
[Bitmask type for peer verification. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.add_verify_path [*add_verify_path]]]
[Add a directory containing certificate authority files to be used for performing verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.basic_context [*basic_context]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ssl__basic_context.impl [*impl]]]
[Get the underlying implementation in the native type. ]
]
[
[[link boost_asio.reference.ssl__basic_context.load_verify_file [*load_verify_file]]]
[Load a certification authority file for performing verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_options [*set_options]]]
[Set options on the context. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_password_callback [*set_password_callback]]]
[Set the password callback. ]
]
[
[[link boost_asio.reference.ssl__basic_context.set_verify_mode [*set_verify_mode]]]
[Set the peer verification mode. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_certificate_chain_file [*use_certificate_chain_file]]]
[Use a certificate chain from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_certificate_file [*use_certificate_file]]]
[Use a certificate from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_private_key_file [*use_private_key_file]]]
[Use a private key from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_rsa_private_key_file [*use_rsa_private_key_file]]]
[Use an RSA private key from a file. ]
]
[
[[link boost_asio.reference.ssl__basic_context.use_tmp_dh_file [*use_tmp_dh_file]]]
[Use the specified file to obtain the temporary Diffie-Hellman parameters. ]
]
[
[[link boost_asio.reference.ssl__basic_context._basic_context [*~basic_context]]]
[Destructor. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__basic_context.default_workarounds [*default_workarounds]]]
[Implement various bug workarounds. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_sslv2 [*no_sslv2]]]
[Disable SSL v2. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_sslv3 [*no_sslv3]]]
[Disable SSL v3. ]
]
[
[[link boost_asio.reference.ssl__basic_context.no_tlsv1 [*no_tlsv1]]]
[Disable TLS v1. ]
]
[
[[link boost_asio.reference.ssl__basic_context.single_dh_use [*single_dh_use]]]
[Always create a new key when using tmp_dh parameters. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_client_once [*verify_client_once]]]
[Do not request client certificate on renegotiation. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_fail_if_no_peer_cert [*verify_fail_if_no_peer_cert]]]
[Fail verification if the peer has no certificate. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_none [*verify_none]]]
[No verification. ]
]
[
[[link boost_asio.reference.ssl__basic_context.verify_peer [*verify_peer]]]
[Verify the peer. ]
]
]
[endsect]
[section:ssl__context_base ssl::context_base]
The context_base class is used as a base for the basic_context class template so that we have a common place to define various enums.
class context_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__context_base.file_format [*file_format]]]
[File format types. ]
]
[
[[link boost_asio.reference.ssl__context_base.method [*method]]]
[Different methods supported by a context. ]
]
[
[[link boost_asio.reference.ssl__context_base.options [*options]]]
[Bitmask type for SSL options. ]
]
[
[[link boost_asio.reference.ssl__context_base.password_purpose [*password_purpose]]]
[Purpose of PEM password. ]
]
[
[[link boost_asio.reference.ssl__context_base.verify_mode [*verify_mode]]]
[Bitmask type for peer verification. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__context_base.default_workarounds [*default_workarounds]]]
[Implement various bug workarounds. ]
]
[
[[link boost_asio.reference.ssl__context_base.no_sslv2 [*no_sslv2]]]
[Disable SSL v2. ]
]
[
[[link boost_asio.reference.ssl__context_base.no_sslv3 [*no_sslv3]]]
[Disable SSL v3. ]
]
[
[[link boost_asio.reference.ssl__context_base.no_tlsv1 [*no_tlsv1]]]
[Disable TLS v1. ]
]
[
[[link boost_asio.reference.ssl__context_base.single_dh_use [*single_dh_use]]]
[Always create a new key when using tmp_dh parameters. ]
]
[
[[link boost_asio.reference.ssl__context_base.verify_client_once [*verify_client_once]]]
[Do not request client certificate on renegotiation. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__context_base.verify_fail_if_no_peer_cert [*verify_fail_if_no_peer_cert]]]
[Fail verification if the peer has no certificate. Ignored unless verify_peer is set. ]
]
[
[[link boost_asio.reference.ssl__context_base.verify_none [*verify_none]]]
[No verification. ]
]
[
[[link boost_asio.reference.ssl__context_base.verify_peer [*verify_peer]]]
[Verify the peer. ]
]
]
[section:default_workarounds ssl::context_base::default_workarounds]
Implement various bug workarounds.
static const int default_workarounds = implementation_defined;
[endsect]
[section:file_format ssl::context_base::file_format]
File format types.
enum file_format
[heading Values]
[variablelist
[
[asn1]
[ASN.1 file. ]
]
[
[pem]
[PEM file. ]
]
]
[endsect]
[section:method ssl::context_base::method]
Different methods supported by a context.
enum method
[heading Values]
[variablelist
[
[sslv2]
[Generic SSL version 2. ]
]
[
[sslv2_client]
[SSL version 2 client. ]
]
[
[sslv2_server]
[SSL version 2 server. ]
]
[
[sslv3]
[Generic SSL version 3. ]
]
[
[sslv3_client]
[SSL version 3 client. ]
]
[
[sslv3_server]
[SSL version 3 server. ]
]
[
[tlsv1]
[Generic TLS version 1. ]
]
[
[tlsv1_client]
[TLS version 1 client. ]
]
[
[tlsv1_server]
[TLS version 1 server. ]
]
[
[sslv23]
[Generic SSL/TLS. ]
]
[
[sslv23_client]
[SSL/TLS client. ]
]
[
[sslv23_server]
[SSL/TLS server. ]
]
]
[endsect]
[section:no_sslv2 ssl::context_base::no_sslv2]
Disable SSL v2.
static const int no_sslv2 = implementation_defined;
[endsect]
[section:no_sslv3 ssl::context_base::no_sslv3]
Disable SSL v3.
static const int no_sslv3 = implementation_defined;
[endsect]
[section:no_tlsv1 ssl::context_base::no_tlsv1]
Disable TLS v1.
static const int no_tlsv1 = implementation_defined;
[endsect]
[section:options ssl::context_base::options]
Bitmask type for SSL options.
typedef int options;
[endsect]
[section:password_purpose ssl::context_base::password_purpose]
Purpose of PEM password.
enum password_purpose
[heading Values]
[variablelist
[
[for_reading]
[The password is needed for reading/decryption. ]
]
[
[for_writing]
[The password is needed for writing/encryption. ]
]
]
[endsect]
[section:single_dh_use ssl::context_base::single_dh_use]
Always create a new key when using tmp_dh parameters.
static const int single_dh_use = implementation_defined;
[endsect]
[section:verify_client_once ssl::context_base::verify_client_once]
Do not request client certificate on renegotiation. Ignored unless verify_peer is set.
static const int verify_client_once = implementation_defined;
[endsect]
[section:verify_fail_if_no_peer_cert ssl::context_base::verify_fail_if_no_peer_cert]
Fail verification if the peer has no certificate. Ignored unless verify_peer is set.
static const int verify_fail_if_no_peer_cert = implementation_defined;
[endsect]
[section:verify_mode ssl::context_base::verify_mode]
Bitmask type for peer verification.
typedef int verify_mode;
[endsect]
[section:verify_none ssl::context_base::verify_none]
No verification.
static const int verify_none = implementation_defined;
[endsect]
[section:verify_peer ssl::context_base::verify_peer]
Verify the peer.
static const int verify_peer = implementation_defined;
[endsect]
[endsect]
[section:ssl__context_service ssl::context_service]
Default service implementation for a context.
class context_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__context_service.impl_type [*impl_type]]]
[The type of the context. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__context_service.add_verify_path [*add_verify_path]]]
[Add a directory containing certification authority files to be used for performing verification. ]
]
[
[[link boost_asio.reference.ssl__context_service.context_service [*context_service]]]
[Constructor. ]
]
[
[[link boost_asio.reference.ssl__context_service.create [*create]]]
[Create a new context implementation. ]
]
[
[[link boost_asio.reference.ssl__context_service.destroy [*destroy]]]
[Destroy a context implementation. ]
]
[
[[link boost_asio.reference.ssl__context_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ssl__context_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ssl__context_service.load_verify_file [*load_verify_file]]]
[Load a certification authority file for performing verification. ]
]
[
[[link boost_asio.reference.ssl__context_service.null [*null]]]
[Return a null context implementation. ]
]
[
[[link boost_asio.reference.ssl__context_service.set_options [*set_options]]]
[Set options on the context. ]
]
[
[[link boost_asio.reference.ssl__context_service.set_password_callback [*set_password_callback]]]
[Set the password callback. ]
]
[
[[link boost_asio.reference.ssl__context_service.set_verify_mode [*set_verify_mode]]]
[Set peer verification mode. ]
]
[
[[link boost_asio.reference.ssl__context_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
[
[[link boost_asio.reference.ssl__context_service.use_certificate_chain_file [*use_certificate_chain_file]]]
[Use a certificate chain from a file. ]
]
[
[[link boost_asio.reference.ssl__context_service.use_certificate_file [*use_certificate_file]]]
[Use a certificate from a file. ]
]
[
[[link boost_asio.reference.ssl__context_service.use_private_key_file [*use_private_key_file]]]
[Use a private key from a file. ]
]
[
[[link boost_asio.reference.ssl__context_service.use_rsa_private_key_file [*use_rsa_private_key_file]]]
[Use an RSA private key from a file. ]
]
[
[[link boost_asio.reference.ssl__context_service.use_tmp_dh_file [*use_tmp_dh_file]]]
[Use the specified file to obtain the temporary Diffie-Hellman parameters. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__context_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:add_verify_path ssl::context_service::add_verify_path]
Add a directory containing certification authority files to be used for performing verification.
boost::system::error_code add_verify_path(
impl_type & impl,
const std::string & path,
boost::system::error_code & ec);
[endsect]
[section:context_service ssl::context_service::context_service]
Constructor.
context_service(
boost::asio::io_service & io_service);
[endsect]
[section:create ssl::context_service::create]
Create a new context implementation.
void create(
impl_type & impl,
context_base::method m);
[endsect]
[section:destroy ssl::context_service::destroy]
Destroy a context implementation.
void destroy(
impl_type & impl);
[endsect]
[section:get_io_service ssl::context_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:id ssl::context_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:impl_type ssl::context_service::impl_type]
The type of the context.
typedef implementation_defined impl_type;
[endsect]
[section:io_service ssl::context_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:load_verify_file ssl::context_service::load_verify_file]
Load a certification authority file for performing verification.
boost::system::error_code load_verify_file(
impl_type & impl,
const std::string & filename,
boost::system::error_code & ec);
[endsect]
[section:null ssl::context_service::null]
Return a null context implementation.
impl_type null() const;
[endsect]
[section:set_options ssl::context_service::set_options]
Set options on the context.
boost::system::error_code set_options(
impl_type & impl,
context_base::options o,
boost::system::error_code & ec);
[endsect]
[section:set_password_callback ssl::context_service::set_password_callback]
Set the password callback.
template<
typename PasswordCallback>
boost::system::error_code set_password_callback(
impl_type & impl,
PasswordCallback callback,
boost::system::error_code & ec);
[endsect]
[section:set_verify_mode ssl::context_service::set_verify_mode]
Set peer verification mode.
boost::system::error_code set_verify_mode(
impl_type & impl,
context_base::verify_mode v,
boost::system::error_code & ec);
[endsect]
[section:shutdown_service ssl::context_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[section:use_certificate_chain_file ssl::context_service::use_certificate_chain_file]
Use a certificate chain from a file.
boost::system::error_code use_certificate_chain_file(
impl_type & impl,
const std::string & filename,
boost::system::error_code & ec);
[endsect]
[section:use_certificate_file ssl::context_service::use_certificate_file]
Use a certificate from a file.
boost::system::error_code use_certificate_file(
impl_type & impl,
const std::string & filename,
context_base::file_format format,
boost::system::error_code & ec);
[endsect]
[section:use_private_key_file ssl::context_service::use_private_key_file]
Use a private key from a file.
boost::system::error_code use_private_key_file(
impl_type & impl,
const std::string & filename,
context_base::file_format format,
boost::system::error_code & ec);
[endsect]
[section:use_rsa_private_key_file ssl::context_service::use_rsa_private_key_file]
Use an RSA private key from a file.
boost::system::error_code use_rsa_private_key_file(
impl_type & impl,
const std::string & filename,
context_base::file_format format,
boost::system::error_code & ec);
[endsect]
[section:use_tmp_dh_file ssl::context_service::use_tmp_dh_file]
Use the specified file to obtain the temporary Diffie-Hellman parameters.
boost::system::error_code use_tmp_dh_file(
impl_type & impl,
const std::string & filename,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:ssl__stream ssl::stream]
Provides stream-oriented functionality using SSL.
template<
typename Stream,
typename ``[link boost_asio.reference.Service Service]`` = stream_service>
class stream :
public ssl::stream_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream.handshake_type [*handshake_type]]]
[Different handshake types. ]
]
[
[[link boost_asio.reference.ssl__stream.impl_type [*impl_type]]]
[The native implementation type of the stream. ]
]
[
[[link boost_asio.reference.ssl__stream.lowest_layer_type [*lowest_layer_type]]]
[The type of the lowest layer. ]
]
[
[[link boost_asio.reference.ssl__stream.next_layer_type [*next_layer_type]]]
[The type of the next layer. ]
]
[
[[link boost_asio.reference.ssl__stream.service_type [*service_type]]]
[The type of the service that will be used to provide stream operations. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream.async_handshake [*async_handshake]]]
[Start an asynchronous SSL handshake. ]
]
[
[[link boost_asio.reference.ssl__stream.async_read_some [*async_read_some]]]
[Start an asynchronous read. ]
]
[
[[link boost_asio.reference.ssl__stream.async_shutdown [*async_shutdown]]]
[Asynchronously shut down SSL on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream.async_write_some [*async_write_some]]]
[Start an asynchronous write. ]
]
[
[[link boost_asio.reference.ssl__stream.get_io_service [*get_io_service]]]
[Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ssl__stream.handshake [*handshake]]]
[Perform SSL handshaking. ]
]
[
[[link boost_asio.reference.ssl__stream.impl [*impl]]]
[Get the underlying implementation in the native type. ]
]
[
[[link boost_asio.reference.ssl__stream.in_avail [*in_avail]]]
[Determine the amount of data that may be read without blocking. ]
]
[
[[link boost_asio.reference.ssl__stream.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the object. ]
]
[
[[link boost_asio.reference.ssl__stream.lowest_layer [*lowest_layer]]]
[Get a reference to the lowest layer. ]
]
[
[[link boost_asio.reference.ssl__stream.next_layer [*next_layer]]]
[Get a reference to the next layer. ]
]
[
[[link boost_asio.reference.ssl__stream.peek [*peek]]]
[Peek at the incoming data on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream.read_some [*read_some]]]
[Read some data from the stream. ]
]
[
[[link boost_asio.reference.ssl__stream.shutdown [*shutdown]]]
[Shut down SSL on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream.stream [*stream]]]
[Construct a stream. ]
]
[
[[link boost_asio.reference.ssl__stream.write_some [*write_some]]]
[Write some data to the stream. ]
]
[
[[link boost_asio.reference.ssl__stream._stream [*~stream]]]
[Destructor. ]
]
]
The stream class template provides asynchronous and blocking stream-oriented functionality using SSL.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Unsafe.
[heading Example]
To use the SSL stream template with an ip::tcp::socket, you would write:
boost::asio::io_service io_service;
boost::asio::ssl::context context(io_service, boost::asio::ssl::context::sslv23);
boost::asio::ssl::stream<boost::asio::ip::tcp::socket> sock(io_service, context);
[section:async_handshake ssl::stream::async_handshake]
Start an asynchronous SSL handshake.
template<
typename HandshakeHandler>
void async_handshake(
handshake_type type,
HandshakeHandler handler);
This function is used to asynchronously perform an SSL handshake on the stream. This function call always returns immediately.
[heading Parameters]
[variablelist
[[type][The type of handshaking to be performed, i.e. as a client or as a server.]]
[[handler][The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation.
);
``
]]
]
[endsect]
[section:async_read_some ssl::stream::async_read_some]
Start an asynchronous read.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
const MutableBufferSequence & buffers,
ReadHandler handler);
This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes read.
);
``
]]
]
[heading Remarks]
The async\_read\_some operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.async_read async_read] function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.
[endsect]
[section:async_shutdown ssl::stream::async_shutdown]
Asynchronously shut down SSL on the stream.
template<
typename ShutdownHandler>
void async_shutdown(
ShutdownHandler handler);
This function is used to asynchronously shut down SSL on the stream. This function call always returns immediately.
[heading Parameters]
[variablelist
[[handler][The handler to be called when the handshake operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
``
void handler(
const boost::system::error_code& error // Result of operation.
);
``
]]
]
[endsect]
[section:async_write_some ssl::stream::async_write_some]
Start an asynchronous write.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
const ConstBufferSequence & buffers,
WriteHandler handler);
This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately.
[heading Parameters]
[variablelist
[[buffers][The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.]]
[[handler][The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
``
void handler(
const boost::system::error_code& error, // Result of operation.
std::size_t bytes_transferred // Number of bytes written.
);
``
]]
]
[heading Remarks]
The async\_write\_some operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.async_write async_write] function if you need to ensure that all data is written before the blocking operation completes.
[endsect]
[section:get_io_service ssl::stream::get_io_service]
Get the io_service associated with the object.
boost::asio::io_service & get_io_service();
This function may be used to obtain the io_service object that the stream uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that stream will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:handshake ssl::stream::handshake]
Perform SSL handshaking.
void ``[link boost_asio.reference.ssl__stream.handshake.overload1 handshake]``(
handshake_type type);
boost::system::error_code ``[link boost_asio.reference.ssl__stream.handshake.overload2 handshake]``(
handshake_type type,
boost::system::error_code & ec);
[section:overload1 ssl::stream::handshake (1 of 2 overloads)]
Perform SSL handshaking.
void handshake(
handshake_type type);
This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.
[heading Parameters]
[variablelist
[[type][The type of handshaking to be performed, i.e. as a client or as a server.]]
]
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::stream::handshake (2 of 2 overloads)]
Perform SSL handshaking.
boost::system::error_code handshake(
handshake_type type,
boost::system::error_code & ec);
This function is used to perform SSL handshaking on the stream. The function call will block until handshaking is complete or an error occurs.
[heading Parameters]
[variablelist
[[type][The type of handshaking to be performed, i.e. as a client or as a server.]]
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:handshake_type ssl::stream::handshake_type]
Different handshake types.
enum handshake_type
[heading Values]
[variablelist
[
[client]
[Perform handshaking as a client. ]
]
[
[server]
[Perform handshaking as a server. ]
]
]
[endsect]
[section:impl ssl::stream::impl]
Get the underlying implementation in the native type.
impl_type impl();
This function may be used to obtain the underlying implementation of the context. This is intended to allow access to stream functionality that is not otherwise provided.
[endsect]
[section:impl_type ssl::stream::impl_type]
The native implementation type of the stream.
typedef service_type::impl_type impl_type;
[endsect]
[section:in_avail ssl::stream::in_avail]
Determine the amount of data that may be read without blocking.
std::size_t ``[link boost_asio.reference.ssl__stream.in_avail.overload1 in_avail]``();
std::size_t ``[link boost_asio.reference.ssl__stream.in_avail.overload2 in_avail]``(
boost::system::error_code & ec);
[section:overload1 ssl::stream::in_avail (1 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail();
This function is used to determine the amount of data, in bytes, that may be read from the stream without blocking.
[heading Return Value]
The number of bytes of data that can be read without blocking.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::stream::in_avail (2 of 2 overloads)]
Determine the amount of data that may be read without blocking.
std::size_t in_avail(
boost::system::error_code & ec);
This function is used to determine the amount of data, in bytes, that may be read from the stream without blocking.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes of data that can be read without blocking.
[endsect]
[endsect]
[section:io_service ssl::stream::io_service]
(Deprecated: use get_io_service().) Get the io_service associated with the object.
boost::asio::io_service & io_service();
This function may be used to obtain the io_service object that the stream uses to dispatch handlers for asynchronous operations.
[heading Return Value]
A reference to the io_service object that stream will use to dispatch handlers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer ssl::stream::lowest_layer]
Get a reference to the lowest layer.
lowest_layer_type & lowest_layer();
This function returns a reference to the lowest layer in a stack of stream layers.
[heading Return Value]
A reference to the lowest layer in the stack of stream layers. Ownership is not transferred to the caller.
[endsect]
[section:lowest_layer_type ssl::stream::lowest_layer_type]
The type of the lowest layer.
typedef next_layer_type::lowest_layer_type lowest_layer_type;
[endsect]
[section:next_layer ssl::stream::next_layer]
Get a reference to the next layer.
next_layer_type & next_layer();
This function returns a reference to the next layer in a stack of stream layers.
[heading Return Value]
A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.
[endsect]
[section:next_layer_type ssl::stream::next_layer_type]
The type of the next layer.
typedef boost::remove_reference< Stream >::type next_layer_type;
[endsect]
[section:peek ssl::stream::peek]
Peek at the incoming data on the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.peek.overload1 peek]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.peek.overload2 peek]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 ssl::stream::peek (1 of 2 overloads)]
Peek at the incoming data on the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers);
This function is used to peek at the incoming data on the stream, without removing it from the input queue. The function call will block until data has been read successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][The buffers into which the data will be read.]]
]
[heading Return Value]
The number of bytes read.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::stream::peek (2 of 2 overloads)]
Peek at the incoming data on the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
This function is used to peek at the incoming data on the stream, withoutxi removing it from the input queue. The function call will block until data has been read successfully or an error occurs.
[heading Parameters]
[variablelist
[[buffers][The buffers into which the data will be read.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes read. Returns 0 if an error occurred.
[endsect]
[endsect]
[section:read_some ssl::stream::read_some]
Read some data from the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.read_some.overload1 read_some]``(
const MutableBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.read_some.overload2 read_some]``(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 ssl::stream::read_some (1 of 2 overloads)]
Read some data from the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers);
This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][The buffers into which the data will be read.]]
]
[heading Return Value]
The number of bytes read.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The read\_some operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[endsect]
[section:overload2 ssl::stream::read_some (2 of 2 overloads)]
Read some data from the stream.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][The buffers into which the data will be read.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes read. Returns 0 if an error occurred.
[heading Remarks]
The read\_some operation may not read all of the requested number of bytes. Consider using the
[link boost_asio.reference.read read] function if you need to ensure that the requested amount of data is read before the blocking operation completes.
[endsect]
[endsect]
[section:service_type ssl::stream::service_type]
The type of the service that will be used to provide stream operations.
typedef Service service_type;
[endsect]
[section:shutdown ssl::stream::shutdown]
Shut down SSL on the stream.
void ``[link boost_asio.reference.ssl__stream.shutdown.overload1 shutdown]``();
boost::system::error_code ``[link boost_asio.reference.ssl__stream.shutdown.overload2 shutdown]``(
boost::system::error_code & ec);
[section:overload1 ssl::stream::shutdown (1 of 2 overloads)]
Shut down SSL on the stream.
void shutdown();
This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload2 ssl::stream::shutdown (2 of 2 overloads)]
Shut down SSL on the stream.
boost::system::error_code shutdown(
boost::system::error_code & ec);
This function is used to shut down SSL on the stream. The function call will block until SSL has been shut down or an error occurs.
[heading Parameters]
[variablelist
[[ec][Set to indicate what error occurred, if any. ]]
]
[endsect]
[endsect]
[section:stream ssl::stream::stream]
Construct a stream.
template<
typename Arg,
typename Context_Service>
stream(
Arg & arg,
basic_context< Context_Service > & context);
This constructor creates a stream and initialises the underlying stream object.
[heading Parameters]
[variablelist
[[arg][The argument to be passed to initialise the underlying stream.]]
[[context][The SSL context to be used for the stream. ]]
]
[endsect]
[section:write_some ssl::stream::write_some]
Write some data to the stream.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.write_some.overload1 write_some]``(
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.ssl__stream.write_some.overload2 write_some]``(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[section:overload1 ssl::stream::write_some (1 of 2 overloads)]
Write some data to the stream.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers);
This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][The data to be written.]]
]
[heading Return Value]
The number of bytes written.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
The write\_some operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[endsect]
[section:overload2 ssl::stream::write_some (2 of 2 overloads)]
Write some data to the stream.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.
[heading Parameters]
[variablelist
[[buffers][The data to be written to the stream.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes written. Returns 0 if an error occurred.
[heading Remarks]
The write\_some operation may not transmit all of the data to the peer. Consider using the
[link boost_asio.reference.write write] function if you need to ensure that all data is written before the blocking operation completes.
[endsect]
[endsect]
[section:_stream ssl::stream::~stream]
Destructor.
~stream();
[endsect]
[endsect]
[section:ssl__stream_base ssl::stream_base]
The stream_base class is used as a base for the boost::asio::ssl::stream class template so that we have a common place to define various enums.
class stream_base
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream_base.handshake_type [*handshake_type]]]
[Different handshake types. ]
]
]
[section:handshake_type ssl::stream_base::handshake_type]
Different handshake types.
enum handshake_type
[heading Values]
[variablelist
[
[client]
[Perform handshaking as a client. ]
]
[
[server]
[Perform handshaking as a server. ]
]
]
[endsect]
[endsect]
[section:ssl__stream_service ssl::stream_service]
Default service implementation for an SSL stream.
class stream_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream_service.impl_type [*impl_type]]]
[The type of a stream implementation. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream_service.async_handshake [*async_handshake]]]
[Start an asynchronous SSL handshake. ]
]
[
[[link boost_asio.reference.ssl__stream_service.async_read_some [*async_read_some]]]
[Start an asynchronous read. ]
]
[
[[link boost_asio.reference.ssl__stream_service.async_shutdown [*async_shutdown]]]
[Asynchronously shut down SSL on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream_service.async_write_some [*async_write_some]]]
[Start an asynchronous write. ]
]
[
[[link boost_asio.reference.ssl__stream_service.create [*create]]]
[Create a new stream implementation. ]
]
[
[[link boost_asio.reference.ssl__stream_service.destroy [*destroy]]]
[Destroy a stream implementation. ]
]
[
[[link boost_asio.reference.ssl__stream_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ssl__stream_service.handshake [*handshake]]]
[Perform SSL handshaking. ]
]
[
[[link boost_asio.reference.ssl__stream_service.in_avail [*in_avail]]]
[Determine the amount of data that may be read without blocking. ]
]
[
[[link boost_asio.reference.ssl__stream_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.ssl__stream_service.null [*null]]]
[Return a null stream implementation. ]
]
[
[[link boost_asio.reference.ssl__stream_service.peek [*peek]]]
[Peek at the incoming data on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream_service.read_some [*read_some]]]
[Read some data from the stream. ]
]
[
[[link boost_asio.reference.ssl__stream_service.shutdown [*shutdown]]]
[Shut down SSL on the stream. ]
]
[
[[link boost_asio.reference.ssl__stream_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
[
[[link boost_asio.reference.ssl__stream_service.stream_service [*stream_service]]]
[Construct a new stream service for the specified io_service. ]
]
[
[[link boost_asio.reference.ssl__stream_service.write_some [*write_some]]]
[Write some data to the stream. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.ssl__stream_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:async_handshake ssl::stream_service::async_handshake]
Start an asynchronous SSL handshake.
template<
typename Stream,
typename HandshakeHandler>
void async_handshake(
impl_type & impl,
Stream & next_layer,
stream_base::handshake_type type,
HandshakeHandler handler);
[endsect]
[section:async_read_some ssl::stream_service::async_read_some]
Start an asynchronous read.
template<
typename Stream,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_read_some(
impl_type & impl,
Stream & next_layer,
const MutableBufferSequence & buffers,
ReadHandler handler);
[endsect]
[section:async_shutdown ssl::stream_service::async_shutdown]
Asynchronously shut down SSL on the stream.
template<
typename Stream,
typename ShutdownHandler>
void async_shutdown(
impl_type & impl,
Stream & next_layer,
ShutdownHandler handler);
[endsect]
[section:async_write_some ssl::stream_service::async_write_some]
Start an asynchronous write.
template<
typename Stream,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_write_some(
impl_type & impl,
Stream & next_layer,
const ConstBufferSequence & buffers,
WriteHandler handler);
[endsect]
[section:create ssl::stream_service::create]
Create a new stream implementation.
template<
typename Stream,
typename Context_Service>
void create(
impl_type & impl,
Stream & next_layer,
basic_context< Context_Service > & context);
[endsect]
[section:destroy ssl::stream_service::destroy]
Destroy a stream implementation.
template<
typename Stream>
void destroy(
impl_type & impl,
Stream & next_layer);
[endsect]
[section:get_io_service ssl::stream_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:handshake ssl::stream_service::handshake]
Perform SSL handshaking.
template<
typename Stream>
boost::system::error_code handshake(
impl_type & impl,
Stream & next_layer,
stream_base::handshake_type type,
boost::system::error_code & ec);
[endsect]
[section:id ssl::stream_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:impl_type ssl::stream_service::impl_type]
The type of a stream implementation.
typedef implementation_defined impl_type;
[endsect]
[section:in_avail ssl::stream_service::in_avail]
Determine the amount of data that may be read without blocking.
template<
typename Stream>
std::size_t in_avail(
impl_type & impl,
Stream & next_layer,
boost::system::error_code & ec);
[endsect]
[section:io_service ssl::stream_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:null ssl::stream_service::null]
Return a null stream implementation.
impl_type null() const;
[endsect]
[section:peek ssl::stream_service::peek]
Peek at the incoming data on the stream.
template<
typename Stream,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t peek(
impl_type & impl,
Stream & next_layer,
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[section:read_some ssl::stream_service::read_some]
Read some data from the stream.
template<
typename Stream,
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t read_some(
impl_type & impl,
Stream & next_layer,
const MutableBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[section:shutdown ssl::stream_service::shutdown]
Shut down SSL on the stream.
template<
typename Stream>
boost::system::error_code shutdown(
impl_type & impl,
Stream & next_layer,
boost::system::error_code & ec);
[endsect]
[section:shutdown_service ssl::stream_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[section:stream_service ssl::stream_service::stream_service]
Construct a new stream service for the specified io_service.
stream_service(
boost::asio::io_service & io_service);
[endsect]
[section:write_some ssl::stream_service::write_some]
Write some data to the stream.
template<
typename Stream,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write_some(
impl_type & impl,
Stream & next_layer,
const ConstBufferSequence & buffers,
boost::system::error_code & ec);
[endsect]
[endsect]
[section:strand strand]
Typedef for backwards compatibility.
typedef boost::asio::io_service::strand strand;
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.io_service__strand.dispatch [*dispatch]]]
[Request the strand to invoke the given handler. ]
]
[
[[link boost_asio.reference.io_service__strand.get_io_service [*get_io_service]]]
[Get the io_service associated with the strand. ]
]
[
[[link boost_asio.reference.io_service__strand.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service associated with the strand. ]
]
[
[[link boost_asio.reference.io_service__strand.post [*post]]]
[Request the strand to invoke the given handler and return immediately. ]
]
[
[[link boost_asio.reference.io_service__strand.strand [*strand]]]
[Constructor. ]
]
[
[[link boost_asio.reference.io_service__strand.wrap [*wrap]]]
[Create a new handler that automatically dispatches the wrapped handler on the strand. ]
]
[
[[link boost_asio.reference.io_service__strand._strand [*~strand]]]
[Destructor. ]
]
]
The io_service::strand class provides the ability to post and dispatch handlers with the guarantee that none of those handlers will execute concurrently.
[heading Thread Safety]
[*Distinct] [*objects:] Safe.
[*Shared] [*objects:] Safe.
[endsect]
[section:stream_socket_service stream_socket_service]
Default service implementation for a stream socket.
template<
typename ``[link boost_asio.reference.Protocol Protocol]``>
class stream_socket_service :
public io_service::service
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.stream_socket_service.endpoint_type [*endpoint_type]]]
[The endpoint type. ]
]
[
[[link boost_asio.reference.stream_socket_service.implementation_type [*implementation_type]]]
[The type of a stream socket implementation. ]
]
[
[[link boost_asio.reference.stream_socket_service.native_type [*native_type]]]
[The native socket type. ]
]
[
[[link boost_asio.reference.stream_socket_service.protocol_type [*protocol_type]]]
[The protocol type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.stream_socket_service.assign [*assign]]]
[Assign an existing native socket to a stream socket. ]
]
[
[[link boost_asio.reference.stream_socket_service.async_connect [*async_connect]]]
[Start an asynchronous connect. ]
]
[
[[link boost_asio.reference.stream_socket_service.async_receive [*async_receive]]]
[Start an asynchronous receive. ]
]
[
[[link boost_asio.reference.stream_socket_service.async_send [*async_send]]]
[Start an asynchronous send. ]
]
[
[[link boost_asio.reference.stream_socket_service.at_mark [*at_mark]]]
[Determine whether the socket is at the out-of-band data mark. ]
]
[
[[link boost_asio.reference.stream_socket_service.available [*available]]]
[Determine the number of bytes available for reading. ]
]
[
[[link boost_asio.reference.stream_socket_service.bind [*bind]]]
[Bind the stream socket to the specified local endpoint. ]
]
[
[[link boost_asio.reference.stream_socket_service.cancel [*cancel]]]
[Cancel all asynchronous operations associated with the socket. ]
]
[
[[link boost_asio.reference.stream_socket_service.close [*close]]]
[Close a stream socket implementation. ]
]
[
[[link boost_asio.reference.stream_socket_service.connect [*connect]]]
[Connect the stream socket to the specified endpoint. ]
]
[
[[link boost_asio.reference.stream_socket_service.construct [*construct]]]
[Construct a new stream socket implementation. ]
]
[
[[link boost_asio.reference.stream_socket_service.destroy [*destroy]]]
[Destroy a stream socket implementation. ]
]
[
[[link boost_asio.reference.stream_socket_service.get_io_service [*get_io_service]]]
[Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.stream_socket_service.get_option [*get_option]]]
[Get a socket option. ]
]
[
[[link boost_asio.reference.stream_socket_service.io_control [*io_control]]]
[Perform an IO control command on the socket. ]
]
[
[[link boost_asio.reference.stream_socket_service.io_service [*io_service]]]
[(Deprecated: use get_io_service().) Get the io_service object that owns the service. ]
]
[
[[link boost_asio.reference.stream_socket_service.is_open [*is_open]]]
[Determine whether the socket is open. ]
]
[
[[link boost_asio.reference.stream_socket_service.local_endpoint [*local_endpoint]]]
[Get the local endpoint. ]
]
[
[[link boost_asio.reference.stream_socket_service.native [*native]]]
[Get the native socket implementation. ]
]
[
[[link boost_asio.reference.stream_socket_service.open [*open]]]
[Open a stream socket. ]
]
[
[[link boost_asio.reference.stream_socket_service.receive [*receive]]]
[Receive some data from the peer. ]
]
[
[[link boost_asio.reference.stream_socket_service.remote_endpoint [*remote_endpoint]]]
[Get the remote endpoint. ]
]
[
[[link boost_asio.reference.stream_socket_service.send [*send]]]
[Send the given data to the peer. ]
]
[
[[link boost_asio.reference.stream_socket_service.set_option [*set_option]]]
[Set a socket option. ]
]
[
[[link boost_asio.reference.stream_socket_service.shutdown [*shutdown]]]
[Disable sends or receives on the socket. ]
]
[
[[link boost_asio.reference.stream_socket_service.shutdown_service [*shutdown_service]]]
[Destroy all user-defined handler objects owned by the service. ]
]
[
[[link boost_asio.reference.stream_socket_service.stream_socket_service [*stream_socket_service]]]
[Construct a new stream socket service for the specified io_service. ]
]
]
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.stream_socket_service.id [*id]]]
[The unique service identifier. ]
]
]
[section:assign stream_socket_service::assign]
Assign an existing native socket to a stream socket.
boost::system::error_code assign(
implementation_type & impl,
const protocol_type & protocol,
const native_type & native_socket,
boost::system::error_code & ec);
[endsect]
[section:async_connect stream_socket_service::async_connect]
Start an asynchronous connect.
template<
typename ``[link boost_asio.reference.ConnectHandler ConnectHandler]``>
void async_connect(
implementation_type & impl,
const endpoint_type & peer_endpoint,
ConnectHandler handler);
[endsect]
[section:async_receive stream_socket_service::async_receive]
Start an asynchronous receive.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``,
typename ``[link boost_asio.reference.ReadHandler ReadHandler]``>
void async_receive(
implementation_type & impl,
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
ReadHandler handler);
[endsect]
[section:async_send stream_socket_service::async_send]
Start an asynchronous send.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename ``[link boost_asio.reference.WriteHandler WriteHandler]``>
void async_send(
implementation_type & impl,
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
WriteHandler handler);
[endsect]
[section:at_mark stream_socket_service::at_mark]
Determine whether the socket is at the out-of-band data mark.
bool at_mark(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:available stream_socket_service::available]
Determine the number of bytes available for reading.
std::size_t available(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:bind stream_socket_service::bind]
Bind the stream socket to the specified local endpoint.
boost::system::error_code bind(
implementation_type & impl,
const endpoint_type & endpoint,
boost::system::error_code & ec);
[endsect]
[section:cancel stream_socket_service::cancel]
Cancel all asynchronous operations associated with the socket.
boost::system::error_code cancel(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:close stream_socket_service::close]
Close a stream socket implementation.
boost::system::error_code close(
implementation_type & impl,
boost::system::error_code & ec);
[endsect]
[section:connect stream_socket_service::connect]
Connect the stream socket to the specified endpoint.
boost::system::error_code connect(
implementation_type & impl,
const endpoint_type & peer_endpoint,
boost::system::error_code & ec);
[endsect]
[section:construct stream_socket_service::construct]
Construct a new stream socket implementation.
void construct(
implementation_type & impl);
[endsect]
[section:destroy stream_socket_service::destroy]
Destroy a stream socket implementation.
void destroy(
implementation_type & impl);
[endsect]
[section:endpoint_type stream_socket_service::endpoint_type]
The endpoint type.
typedef Protocol::endpoint endpoint_type;
[endsect]
[section:get_io_service stream_socket_service::get_io_service]
['Inherited from io_service.]
Get the io_service object that owns the service.
boost::asio::io_service & get_io_service();
[endsect]
[section:get_option stream_socket_service::get_option]
Get a socket option.
template<
typename ``[link boost_asio.reference.GettableSocketOption GettableSocketOption]``>
boost::system::error_code get_option(
const implementation_type & impl,
GettableSocketOption & option,
boost::system::error_code & ec) const;
[endsect]
[section:id stream_socket_service::id]
The unique service identifier.
static boost::asio::io_service::id id;
[endsect]
[section:implementation_type stream_socket_service::implementation_type]
The type of a stream socket implementation.
typedef implementation_defined implementation_type;
[endsect]
[section:io_control stream_socket_service::io_control]
Perform an IO control command on the socket.
template<
typename ``[link boost_asio.reference.IoControlCommand IoControlCommand]``>
boost::system::error_code io_control(
implementation_type & impl,
IoControlCommand & command,
boost::system::error_code & ec);
[endsect]
[section:io_service stream_socket_service::io_service]
['Inherited from io_service.]
(Deprecated: use get_io_service().) Get the io_service object that owns the service.
boost::asio::io_service & io_service();
[endsect]
[section:is_open stream_socket_service::is_open]
Determine whether the socket is open.
bool is_open(
const implementation_type & impl) const;
[endsect]
[section:local_endpoint stream_socket_service::local_endpoint]
Get the local endpoint.
endpoint_type local_endpoint(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:native stream_socket_service::native]
Get the native socket implementation.
native_type native(
implementation_type & impl);
[endsect]
[section:native_type stream_socket_service::native_type]
The native socket type.
typedef implementation_defined native_type;
[endsect]
[section:open stream_socket_service::open]
Open a stream socket.
boost::system::error_code open(
implementation_type & impl,
const protocol_type & protocol,
boost::system::error_code & ec);
[endsect]
[section:protocol_type stream_socket_service::protocol_type]
The protocol type.
typedef Protocol protocol_type;
[endsect]
[section:receive stream_socket_service::receive]
Receive some data from the peer.
template<
typename ``[link boost_asio.reference.MutableBufferSequence MutableBufferSequence]``>
std::size_t receive(
implementation_type & impl,
const MutableBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:remote_endpoint stream_socket_service::remote_endpoint]
Get the remote endpoint.
endpoint_type remote_endpoint(
const implementation_type & impl,
boost::system::error_code & ec) const;
[endsect]
[section:send stream_socket_service::send]
Send the given data to the peer.
template<
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t send(
implementation_type & impl,
const ConstBufferSequence & buffers,
socket_base::message_flags flags,
boost::system::error_code & ec);
[endsect]
[section:set_option stream_socket_service::set_option]
Set a socket option.
template<
typename ``[link boost_asio.reference.SettableSocketOption SettableSocketOption]``>
boost::system::error_code set_option(
implementation_type & impl,
const SettableSocketOption & option,
boost::system::error_code & ec);
[endsect]
[section:shutdown stream_socket_service::shutdown]
Disable sends or receives on the socket.
boost::system::error_code shutdown(
implementation_type & impl,
socket_base::shutdown_type what,
boost::system::error_code & ec);
[endsect]
[section:shutdown_service stream_socket_service::shutdown_service]
Destroy all user-defined handler objects owned by the service.
void shutdown_service();
[endsect]
[section:stream_socket_service stream_socket_service::stream_socket_service]
Construct a new stream socket service for the specified io_service.
stream_socket_service(
boost::asio::io_service & io_service);
[endsect]
[endsect]
[section:streambuf streambuf]
Typedef for the typical usage of basic_streambuf.
typedef basic_streambuf streambuf;
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_streambuf.const_buffers_type [*const_buffers_type]]]
[The type used to represent the get area as a list of buffers. ]
]
[
[[link boost_asio.reference.basic_streambuf.mutable_buffers_type [*mutable_buffers_type]]]
[The type used to represent the put area as a list of buffers. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.basic_streambuf.basic_streambuf [*basic_streambuf]]]
[Construct a buffer with a specified maximum size. ]
]
[
[[link boost_asio.reference.basic_streambuf.commit [*commit]]]
[Move the start of the put area by the specified number of characters. ]
]
[
[[link boost_asio.reference.basic_streambuf.consume [*consume]]]
[Move the start of the get area by the specified number of characters. ]
]
[
[[link boost_asio.reference.basic_streambuf.data [*data]]]
[Get a list of buffers that represents the get area. ]
]
[
[[link boost_asio.reference.basic_streambuf.max_size [*max_size]]]
[Return the maximum size of the buffer. ]
]
[
[[link boost_asio.reference.basic_streambuf.prepare [*prepare]]]
[Get a list of buffers that represents the put area, with the given size. ]
]
[
[[link boost_asio.reference.basic_streambuf.size [*size]]]
[Return the size of the get area in characters. ]
]
]
[endsect]
[section:time_traits_lt__ptime__gt_ time_traits< boost::posix_time::ptime >]
Time traits specialised for posix_time.
template<>
struct time_traits< boost::posix_time::ptime >
[heading Types]
[table
[[Name][Description]]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.duration_type [*duration_type]]]
[The duration type. ]
]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.time_type [*time_type]]]
[The time type. ]
]
]
[heading Member Functions]
[table
[[Name][Description]]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.add [*add]]]
[Add a duration to a time. ]
]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.less_than [*less_than]]]
[Test whether one time is less than another. ]
]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.now [*now]]]
[Get the current time. ]
]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.subtract [*subtract]]]
[Subtract one time from another. ]
]
[
[[link boost_asio.reference.time_traits_lt__ptime__gt_.to_posix_duration [*to_posix_duration]]]
[Convert to POSIX duration type. ]
]
]
[section:add time_traits< boost::posix_time::ptime >::add]
Add a duration to a time.
static time_type add(
const time_type & t,
const duration_type & d);
[endsect]
[section:duration_type time_traits< boost::posix_time::ptime >::duration_type]
The duration type.
typedef boost::posix_time::time_duration duration_type;
[endsect]
[section:less_than time_traits< boost::posix_time::ptime >::less_than]
Test whether one time is less than another.
static bool less_than(
const time_type & t1,
const time_type & t2);
[endsect]
[section:now time_traits< boost::posix_time::ptime >::now]
Get the current time.
static time_type now();
[endsect]
[section:subtract time_traits< boost::posix_time::ptime >::subtract]
Subtract one time from another.
static duration_type subtract(
const time_type & t1,
const time_type & t2);
[endsect]
[section:time_type time_traits< boost::posix_time::ptime >::time_type]
The time type.
typedef boost::posix_time::ptime time_type;
[endsect]
[section:to_posix_duration time_traits< boost::posix_time::ptime >::to_posix_duration]
Convert to POSIX duration type.
static boost::posix_time::time_duration to_posix_duration(
const duration_type & d);
[endsect]
[endsect]
[section:transfer_all transfer_all]
Return a completion condition function object that indicates that a read or write operation should continue until all of the data has been transferred, or until an error occurs.
unspecified transfer_all();
This function is used to create an object, of unspecified type, that meets CompletionCondition requirements.
[heading Example]
Reading until a buffer is full:
boost::array<char, 128> buf;
boost::system::error_code ec;
std::size_t n = boost::asio::read(
sock, boost::asio::buffer(buf),
boost::asio::transfer_all(), ec);
if (ec)
{
// An error occurred.
}
else
{
// n == 128
}
[endsect]
[section:transfer_at_least transfer_at_least]
Return a completion condition function object that indicates that a read or write operation should continue until a minimum number of bytes has been transferred, or until an error occurs.
unspecified transfer_at_least(
std::size_t minimum);
This function is used to create an object, of unspecified type, that meets CompletionCondition requirements.
[heading Example]
Reading until a buffer is full or contains at least 64 bytes:
boost::array<char, 128> buf;
boost::system::error_code ec;
std::size_t n = boost::asio::read(
sock, boost::asio::buffer(buf),
boost::asio::transfer_at_least(64), ec);
if (ec)
{
// An error occurred.
}
else
{
// n >= 64 && n <= 128
}
[endsect]
[section:use_service use_service]
template<
typename ``[link boost_asio.reference.Service Service]``>
Service & use_service(
io_service & ios);
This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, then the io_service will create a new instance of the service.
[heading Parameters]
[variablelist
[[ios][The io\_service object that owns the service.]]
]
[heading Return Value]
The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.
[endsect]
[section:write write]
Write all of the supplied data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t ``[link boost_asio.reference.write.overload1 write]``(
SyncWriteStream & s,
const ConstBufferSequence & buffers);
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.write.overload2 write]``(
SyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition);
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.write.overload3 write]``(
SyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition,
boost::system::error_code & ec);
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator>
std::size_t ``[link boost_asio.reference.write.overload4 write]``(
SyncWriteStream & s,
basic_streambuf< Allocator > & b);
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.write.overload5 write]``(
SyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition);
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t ``[link boost_asio.reference.write.overload6 write]``(
SyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
boost::system::error_code & ec);
[section:overload1 write (1 of 6 overloads)]
Write all of the supplied data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``>
std::size_t write(
SyncWriteStream & s,
const ConstBufferSequence & buffers);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[buffers][One or more buffers containing the data to be written. The sum of the buffer sizes indicates the maximum number of bytes to write to the stream.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::write(s, boost::asio::buffer(data, size));
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[heading Remarks]
This overload is equivalent to calling:
boost::asio::write(
s, buffers,
boost::asio::transfer_all());
[endsect]
[section:overload2 write (2 of 6 overloads)]
Write a certain amount of data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition>
std::size_t write(
SyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[buffers][One or more buffers containing the data to be written. The sum of the buffer sizes indicates the maximum number of bytes to write to the stream.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's write\_some function are required.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Example]
To write a single data buffer use the
[link boost_asio.reference.buffer buffer] function as follows:
boost::asio::write(s, boost::asio::buffer(data, size),
boost::asio::transfer_at_least(32));
See the
[link boost_asio.reference.buffer buffer] documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.
[endsect]
[section:overload3 write (3 of 6 overloads)]
Write a certain amount of data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename ``[link boost_asio.reference.ConstBufferSequence ConstBufferSequence]``,
typename CompletionCondition>
std::size_t write(
SyncWriteStream & s,
const ConstBufferSequence & buffers,
CompletionCondition completion_condition,
boost::system::error_code & ec);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied buffers has been written. That is, the bytes transferred is equal to the sum of the buffer sizes.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[buffers][One or more buffers containing the data to be written. The sum of the buffer sizes indicates the maximum number of bytes to write to the stream.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's write\_some function are required.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes written. If an error occurs, returns the total number of bytes successfully transferred prior to the error.
[endsect]
[section:overload4 write (4 of 6 overloads)]
Write a certain amount of data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator>
std::size_t write(
SyncWriteStream & s,
basic_streambuf< Allocator > & b);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied basic_streambuf has been written.
* An error occurred.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[b][The basic\_streambuf object from which data will be written.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure.]]
]
[heading Remarks]
This overload is equivalent to calling:
boost::asio::write(
s, b,
boost::asio::transfer_all());
[endsect]
[section:overload5 write (5 of 6 overloads)]
Write a certain amount of data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t write(
SyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied basic_streambuf has been written.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[b][The basic\_streambuf object from which data will be written.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's write\_some function are required.]]
]
[heading Return Value]
The number of bytes transferred.
[heading Exceptions]
[variablelist
[[boost::system::system_error][Thrown on failure. ]]
]
[endsect]
[section:overload6 write (6 of 6 overloads)]
Write a certain amount of data to a stream before returning.
template<
typename ``[link boost_asio.reference.SyncWriteStream SyncWriteStream]``,
typename Allocator,
typename CompletionCondition>
std::size_t write(
SyncWriteStream & s,
basic_streambuf< Allocator > & b,
CompletionCondition completion_condition,
boost::system::error_code & ec);
This function is used to write a certain number of bytes of data to a stream. The call will block until one of the following conditions is true:
* All of the data in the supplied basic_streambuf has been written.
* The completion_condition function object returns true.
This operation is implemented in terms of one or more calls to the stream's write\_some function.
[heading Parameters]
[variablelist
[[s][The stream to which the data is to be written. The type must support the SyncWriteStream concept.]]
[[b][The basic\_streambuf object from which data will be written.]]
[[completion_condition][The function object to be called to determine whether the write operation is complete. The signature of the function object must be:
``
bool completion_condition(
const boost::system::error_code& error, // Result of latest write_some
// operation.
std::size_t bytes_transferred // Number of bytes transferred
// so far.
);
``
A return value of true indicates that the write operation is complete. False indicates that further calls to the stream's write\_some function are required.]]
[[ec][Set to indicate what error occurred, if any.]]
]
[heading Return Value]
The number of bytes written. If an error occurs, returns the total number of bytes successfully transferred prior to the error.
[endsect]
[endsect]
[section:is_error_code_enum_lt__addrinfo_errors__gt_ boost::system::is_error_code_enum< boost::asio::error::addrinfo_errors >]
template<>
struct boost::system::is_error_code_enum< boost::asio::error::addrinfo_errors >
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_error_code_enum_lt__addrinfo_errors__gt_.value [*value]]]
[]
]
]
[section:value boost::system::is_error_code_enum< boost::asio::error::addrinfo_errors >::value]
static const bool value = true;
[endsect]
[endsect]
[section:is_error_code_enum_lt__basic_errors__gt_ boost::system::is_error_code_enum< boost::asio::error::basic_errors >]
template<>
struct boost::system::is_error_code_enum< boost::asio::error::basic_errors >
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_error_code_enum_lt__basic_errors__gt_.value [*value]]]
[]
]
]
[section:value boost::system::is_error_code_enum< boost::asio::error::basic_errors >::value]
static const bool value = true;
[endsect]
[endsect]
[section:is_error_code_enum_lt__misc_errors__gt_ boost::system::is_error_code_enum< boost::asio::error::misc_errors >]
template<>
struct boost::system::is_error_code_enum< boost::asio::error::misc_errors >
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_error_code_enum_lt__misc_errors__gt_.value [*value]]]
[]
]
]
[section:value boost::system::is_error_code_enum< boost::asio::error::misc_errors >::value]
static const bool value = true;
[endsect]
[endsect]
[section:is_error_code_enum_lt__netdb_errors__gt_ boost::system::is_error_code_enum< boost::asio::error::netdb_errors >]
template<>
struct boost::system::is_error_code_enum< boost::asio::error::netdb_errors >
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_error_code_enum_lt__netdb_errors__gt_.value [*value]]]
[]
]
]
[section:value boost::system::is_error_code_enum< boost::asio::error::netdb_errors >::value]
static const bool value = true;
[endsect]
[endsect]
[section:is_error_code_enum_lt__ssl_errors__gt_ boost::system::is_error_code_enum< boost::asio::error::ssl_errors >]
template<>
struct boost::system::is_error_code_enum< boost::asio::error::ssl_errors >
[heading Data Members]
[table
[[Name][Description]]
[
[[link boost_asio.reference.is_error_code_enum_lt__ssl_errors__gt_.value [*value]]]
[]
]
]
[section:value boost::system::is_error_code_enum< boost::asio::error::ssl_errors >::value]
static const bool value = true;
[endsect]
[endsect]
[endsect]
Reference in New Issue View Git Blame Copy Permalink