summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/other_protocols.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/other_protocols.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/other_protocols.qbk94
1 files changed, 94 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/other_protocols.qbk b/3rdparty/asio/src/doc/overview/other_protocols.qbk
new file mode 100644
index 00000000000..9a6fe077ea1
--- /dev/null
+++ b/3rdparty/asio/src/doc/overview/other_protocols.qbk
@@ -0,0 +1,94 @@
+[/
+ / Copyright (c) 2003-2016 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:other_protocols Support for Other Protocols]
+
+Support for other socket protocols (such as Bluetooth or IRCOMM sockets) can be
+added by implementing the [link asio.reference.Protocol protocol type
+requirements]. However, in many cases these protocols may also be used with
+Asio's generic protocol support. For this, Asio provides the following four
+classes:
+
+* [link asio.reference.generic__datagram_protocol `generic::datagram_protocol`]
+* [link asio.reference.generic__raw_protocol `generic::raw_protocol`]
+* [link asio.reference.generic__seq_packet_protocol `generic::seq_packet_protocol`]
+* [link asio.reference.generic__stream_protocol `generic::stream_protocol`]
+
+These classes implement the [link asio.reference.Protocol protocol type
+requirements], but allow the user to specify the address family (e.g. `AF_INET`)
+and protocol type (e.g. `IPPROTO_TCP`) at runtime. For example:
+
+ asio::generic::stream_protocol::socket my_socket(my_io_context);
+ my_socket.open(asio::generic::stream_protocol(AF_INET, IPPROTO_TCP));
+ ...
+
+An endpoint class template, [link asio.reference.generic__basic_endpoint
+`asio::generic::basic_endpoint`], is included to support these protocol
+classes. This endpoint can hold any other endpoint type, provided its native
+representation fits into a `sockaddr_storage` object. This class will also
+convert from other types that implement the [link asio.reference.Endpoint
+endpoint] type requirements:
+
+ asio::ip::tcp::endpoint my_endpoint1 = ...;
+ asio::generic::stream_protocol::endpoint my_endpoint2(my_endpoint1);
+
+The conversion is implicit, so as to support the following use cases:
+
+ asio::generic::stream_protocol::socket my_socket(my_io_context);
+ asio::ip::tcp::endpoint my_endpoint = ...;
+ my_socket.connect(my_endpoint);
+
+[heading C++11 Move Construction]
+
+When using C++11, it is possible to perform move construction from a socket (or
+acceptor) object to convert to the more generic protocol's socket (or acceptor)
+type. If the protocol conversion is valid:
+
+ Protocol1 p1 = ...;
+ Protocol2 p2(p1);
+
+then the corresponding socket conversion is allowed:
+
+ Protocol1::socket my_socket1(my_io_context);
+ ...
+ Protocol2::socket my_socket2(std::move(my_socket1));
+
+For example, one possible conversion is from a TCP socket to a generic
+stream-oriented socket:
+
+ asio::ip::tcp::socket my_socket1(my_io_context);
+ ...
+ asio::generic::stream_protocol::socket my_socket2(std::move(my_socket1));
+
+These conversions are also available for move-assignment.
+
+These conversions are not limited to the above generic protocol classes.
+User-defined protocols may take advantage of this feature by similarly ensuring
+the conversion from `Protocol1` to `Protocol2` is valid, as above.
+
+[heading Accepting Generic Sockets]
+
+As a convenience, a socket acceptor's `accept()` and `async_accept()` functions
+can directly accept into a different protocol's socket type, provided the
+corresponding protocol conversion is valid. For example, the following is
+supported because the protocol `asio::ip::tcp` is convertible to
+`asio::generic::stream_protocol`:
+
+ asio::ip::tcp::acceptor my_acceptor(my_io_context);
+ ...
+ asio::generic::stream_protocol::socket my_socket(my_io_context);
+ my_acceptor.accept(my_socket);
+
+[heading See Also]
+
+[link asio.reference.generic__datagram_protocol `generic::datagram_protocol`],
+[link asio.reference.generic__raw_protocol `generic::raw_protocol`],
+[link asio.reference.generic__seq_packet_protocol `generic::seq_packet_protocol`],
+[link asio.reference.generic__stream_protocol `generic::stream_protocol`],
+[link asio.reference.Protocol protocol type requirements].
+
+[endsect]