libs/asio/doc/overview/protocols.qbk

   1 [/
   2  / Copyright (c) 2003-2014 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:protocols TCP, UDP and ICMP]
   9
  10 Boost.Asio provides off-the-shelf support for the internet protocols TCP, UDP and
  11 ICMP.
  12
  13 [heading TCP Clients]
  14
  15 Hostname resolution is performed using a resolver, where host and service names
  16 are looked up and converted into one or more endpoints:
  17
  18   ip::tcp::resolver resolver(my_io_service);
  19   ip::tcp::resolver::query query("www.boost.org", "http");
  20   ip::tcp::resolver::iterator iter = resolver.resolve(query);
  21   ip::tcp::resolver::iterator end; // End marker.
  22   while (iter != end)
  23   {
  24     ip::tcp::endpoint endpoint = *iter++;
  25     std::cout << endpoint << std::endl;
  26   }
  27
  28 The list of endpoints obtained above could contain both IPv4 and IPv6 endpoints,
  29 so a program should try each of them until it finds one that works. This keeps the
  30 client program independent of a specific IP version.
  31
  32 To simplify the development of protocol-independent programs, TCP clients may
  33 establish connections using the free functions [link boost_asio.reference.connect
  34 connect()] and [link boost_asio.reference.async_connect async_connect()]. These
  35 operations try each endpoint in a list until the socket is successfully
  36 connected. For example, a single call:
  37
  38   ip::tcp::socket socket(my_io_service);
  39   boost::asio::connect(socket, resolver.resolve(query));
  40
  41 will synchronously try all endpoints until one is successfully connected.
  42 Similarly, an asynchronous connect may be performed by writing:
  43
  44   boost::asio::async_connect(socket_, iter,
  45       boost::bind(&client::handle_connect, this,
  46         boost::asio::placeholders::error));
  47
  48   // ...
  49
  50   void handle_connect(const error_code& error)
  51   {
  52     if (!error)
  53     {
  54       // Start read or write operations.
  55     }
  56     else
  57     {
  58       // Handle error.
  59     }
  60   }
  61
  62 When a specific endpoint is available, a socket can be created and connected:
  63
  64   ip::tcp::socket socket(my_io_service);
  65   socket.connect(endpoint);
  66
  67 Data may be read from or written to a connected TCP socket using the [link
  68 boost_asio.reference.basic_stream_socket.receive receive()], [link
  69 boost_asio.reference.basic_stream_socket.async_receive async_receive()], [link
  70 boost_asio.reference.basic_stream_socket.send send()] or [link
  71 boost_asio.reference.basic_stream_socket.async_send async_send()] member functions.
  72 However, as these could result in [link boost_asio.overview.core.streams short writes
  73 or reads], an application will typically use the following operations instead:
  74 [link boost_asio.reference.read read()], [link boost_asio.reference.async_read
  75 async_read()], [link boost_asio.reference.write write()] and [link
  76 boost_asio.reference.async_write async_write()].
  77
  78 [heading TCP Servers]
  79
  80 A program uses an acceptor to accept incoming TCP connections:
  81
  82   ip::tcp::acceptor acceptor(my_io_service, my_endpoint);
  83   ...
  84   ip::tcp::socket socket(my_io_service);
  85   acceptor.accept(socket);
  86
  87 After a socket has been successfully accepted, it may be read from or written
  88 to as illustrated for TCP clients above.
  89
  90 [heading UDP]
  91
  92 UDP hostname resolution is also performed using a resolver:
  93
  94   ip::udp::resolver resolver(my_io_service);
  95   ip::udp::resolver::query query("localhost", "daytime");
  96   ip::udp::resolver::iterator iter = resolver.resolve(query);
  97   ...
  98
  99 A UDP socket is typically bound to a local endpoint. The following code will
 100 create an IP version 4 UDP socket and bind it to the "any" address on port
 101 `12345`:
 102
 103   ip::udp::endpoint endpoint(ip::udp::v4(), 12345);
 104   ip::udp::socket socket(my_io_service, endpoint);
 105
 106 Data may be read from or written to an unconnected UDP socket using the [link
 107 boost_asio.reference.basic_datagram_socket.receive_from receive_from()], [link
 108 boost_asio.reference.basic_datagram_socket.async_receive_from async_receive_from()],
 109 [link boost_asio.reference.basic_datagram_socket.send_to send_to()] or [link
 110 boost_asio.reference.basic_datagram_socket.async_send_to async_send_to()] member
 111 functions. For a connected UDP socket, use the [link
 112 boost_asio.reference.basic_datagram_socket.receive receive()], [link
 113 boost_asio.reference.basic_datagram_socket.async_receive async_receive()], [link
 114 boost_asio.reference.basic_datagram_socket.send send()] or [link
 115 boost_asio.reference.basic_datagram_socket.async_send async_send()] member functions.
 116
 117 [heading ICMP]
 118
 119 As with TCP and UDP, ICMP hostname resolution is performed using a resolver:
 120
 121   ip::icmp::resolver resolver(my_io_service);
 122   ip::icmp::resolver::query query("localhost", "");
 123   ip::icmp::resolver::iterator iter = resolver.resolve(query);
 124   ...
 125
 126 An ICMP socket may be bound to a local endpoint. The following code will create
 127 an IP version 6 ICMP socket and bind it to the "any" address:
 128
 129   ip::icmp::endpoint endpoint(ip::icmp::v6(), 0);
 130   ip::icmp::socket socket(my_io_service, endpoint);
 131
 132 The port number is not used for ICMP.
 133
 134 Data may be read from or written to an unconnected ICMP socket using the [link
 135 boost_asio.reference.basic_raw_socket.receive_from receive_from()], [link
 136 boost_asio.reference.basic_raw_socket.async_receive_from async_receive_from()],
 137 [link boost_asio.reference.basic_raw_socket.send_to send_to()] or [link
 138 boost_asio.reference.basic_raw_socket.async_send_to async_send_to()] member
 139 functions.
 140
 141 [heading See Also]
 142
 143 [link boost_asio.reference.ip__tcp ip::tcp],
 144 [link boost_asio.reference.ip__udp ip::udp],
 145 [link boost_asio.reference.ip__icmp ip::icmp],
 146 [link boost_asio.tutorial.tutdaytime1 daytime protocol tutorials],
 147 [link boost_asio.examples.cpp03_examples.icmp ICMP ping example].
 148
 149 [endsect]