ceph/src/boost/libs/asio/doc/overview/other_protocols.qbk

   1 [/
   2  / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:other_protocols Support for Other Protocols]
   9
  10 Support for other socket protocols (such as Bluetooth or IRCOMM sockets) can be
  11 added by implementing the [link boost_asio.reference.Protocol protocol type
  12 requirements]. However, in many cases these protocols may also be used with
  13 Boost.Asio's generic protocol support. For this, Boost.Asio provides the following four
  14 classes:
  15
  16 * [link boost_asio.reference.generic__datagram_protocol `generic::datagram_protocol`]
  17 * [link boost_asio.reference.generic__raw_protocol `generic::raw_protocol`]
  18 * [link boost_asio.reference.generic__seq_packet_protocol `generic::seq_packet_protocol`]
  19 * [link boost_asio.reference.generic__stream_protocol `generic::stream_protocol`]
  20
  21 These classes implement the [link boost_asio.reference.Protocol protocol type
  22 requirements], but allow the user to specify the address family (e.g. `AF_INET`)
  23 and protocol type (e.g. `IPPROTO_TCP`) at runtime. For example:
  24
  25   boost::asio::generic::stream_protocol::socket my_socket(my_io_service);
  26   my_socket.open(boost::asio::generic::stream_protocol(AF_INET, IPPROTO_TCP));
  27   ...
  28
  29 An endpoint class template, [link boost_asio.reference.generic__basic_endpoint
  30 `boost::asio::generic::basic_endpoint`], is included to support these protocol
  31 classes. This endpoint can hold any other endpoint type, provided its native
  32 representation fits into a `sockaddr_storage` object. This class will also
  33 convert from other types that implement the [link boost_asio.reference.Endpoint
  34 endpoint] type requirements:
  35
  36   boost::asio::ip::tcp::endpoint my_endpoint1 = ...;
  37   boost::asio::generic::stream_protocol::endpoint my_endpoint2(my_endpoint1);
  38
  39 The conversion is implicit, so as to support the following use cases:
  40
  41   boost::asio::generic::stream_protocol::socket my_socket(my_io_service);
  42   boost::asio::ip::tcp::endpoint my_endpoint = ...;
  43   my_socket.connect(my_endpoint);
  44
  45 [heading C++11 Move Construction]
  46
  47 When using C++11, it is possible to perform move construction from a socket (or
  48 acceptor) object to convert to the more generic protocol's socket (or acceptor)
  49 type. If the protocol conversion is valid:
  50
  51   Protocol1 p1 = ...;
  52   Protocol2 p2(p1);
  53
  54 then the corresponding socket conversion is allowed:
  55
  56   Protocol1::socket my_socket1(my_io_service);
  57   ...
  58   Protocol2::socket my_socket2(std::move(my_socket1));
  59
  60 For example, one possible conversion is from a TCP socket to a generic
  61 stream-oriented socket:
  62
  63   boost::asio::ip::tcp::socket my_socket1(my_io_service);
  64   ...
  65   boost::asio::generic::stream_protocol::socket my_socket2(std::move(my_socket1));
  66
  67 These conversions are also available for move-assignment.
  68
  69 These conversions are not limited to the above generic protocol classes.
  70 User-defined protocols may take advantage of this feature by similarly ensuring
  71 the conversion from `Protocol1` to `Protocol2` is valid, as above.
  72
  73 [heading Accepting Generic Sockets]
  74
  75 As a convenience, a socket acceptor's `accept()` and `async_accept()` functions
  76 can directly accept into a different protocol's socket type, provided the
  77 corresponding protocol conversion is valid. For example, the following is
  78 supported because the protocol `boost::asio::ip::tcp` is convertible to
  79 `boost::asio::generic::stream_protocol`:
  80
  81   boost::asio::ip::tcp::acceptor my_acceptor(my_io_service);
  82   ...
  83   boost::asio::generic::stream_protocol::socket my_socket(my_io_service);
  84   my_acceptor.accept(my_socket);
  85
  86 [heading See Also]
  87
  88 [link boost_asio.reference.generic__datagram_protocol `generic::datagram_protocol`],
  89 [link boost_asio.reference.generic__raw_protocol `generic::raw_protocol`],
  90 [link boost_asio.reference.generic__seq_packet_protocol `generic::seq_packet_protocol`],
  91 [link boost_asio.reference.generic__stream_protocol `generic::stream_protocol`],
  92 [link boost_asio.reference.Protocol protocol type requirements].
  93
  94 [endsect]