1[/
2 / Copyright (c) 2003-2021 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
10Boost.Asio provides off-the-shelf support for the internet protocols TCP, UDP and
11ICMP.
12
13[heading TCP Clients]
14
15Hostname resolution is performed using a resolver, where host and service names
16are looked up and converted into one or more endpoints:
17
18  ip::tcp::resolver resolver(my_io_context);
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
28The list of endpoints obtained above could contain both IPv4 and IPv6 endpoints,
29so a program should try each of them until it finds one that works. This keeps the
30client program independent of a specific IP version.
31
32To simplify the development of protocol-independent programs, TCP clients may
33establish connections using the free functions [link boost_asio.reference.connect
34connect()] and [link boost_asio.reference.async_connect async_connect()]. These
35operations try each endpoint in a list until the socket is successfully
36connected. For example, a single call:
37
38  ip::tcp::socket socket(my_io_context);
39  boost::asio::connect(socket, resolver.resolve(query));
40
41will synchronously try all endpoints until one is successfully connected.
42Similarly, 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
62When a specific endpoint is available, a socket can be created and connected:
63
64  ip::tcp::socket socket(my_io_context);
65  socket.connect(endpoint);
66
67Data may be read from or written to a connected TCP socket using the [link
68boost_asio.reference.basic_stream_socket.receive receive()], [link
69boost_asio.reference.basic_stream_socket.async_receive async_receive()], [link
70boost_asio.reference.basic_stream_socket.send send()] or [link
71boost_asio.reference.basic_stream_socket.async_send async_send()] member functions.
72However, as these could result in [link boost_asio.overview.core.streams short writes
73or reads], an application will typically use the following operations instead:
74[link boost_asio.reference.read read()], [link boost_asio.reference.async_read
75async_read()], [link boost_asio.reference.write write()] and [link
76boost_asio.reference.async_write async_write()].
77
78[heading TCP Servers]
79
80A program uses an acceptor to accept incoming TCP connections:
81
82  ip::tcp::acceptor acceptor(my_io_context, my_endpoint);
83  ...
84  ip::tcp::socket socket(my_io_context);
85  acceptor.accept(socket);
86
87After a socket has been successfully accepted, it may be read from or written
88to as illustrated for TCP clients above.
89
90[heading UDP]
91
92UDP hostname resolution is also performed using a resolver:
93
94  ip::udp::resolver resolver(my_io_context);
95  ip::udp::resolver::query query("localhost", "daytime");
96  ip::udp::resolver::iterator iter = resolver.resolve(query);
97  ...
98
99A UDP socket is typically bound to a local endpoint. The following code will
100create 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_context, endpoint);
105
106Data may be read from or written to an unconnected UDP socket using the [link
107boost_asio.reference.basic_datagram_socket.receive_from receive_from()], [link
108boost_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
110boost_asio.reference.basic_datagram_socket.async_send_to async_send_to()] member
111functions. For a connected UDP socket, use the [link
112boost_asio.reference.basic_datagram_socket.receive receive()], [link
113boost_asio.reference.basic_datagram_socket.async_receive async_receive()], [link
114boost_asio.reference.basic_datagram_socket.send send()] or [link
115boost_asio.reference.basic_datagram_socket.async_send async_send()] member functions.
116
117[heading ICMP]
118
119As with TCP and UDP, ICMP hostname resolution is performed using a resolver:
120
121  ip::icmp::resolver resolver(my_io_context);
122  ip::icmp::resolver::query query("localhost", "");
123  ip::icmp::resolver::iterator iter = resolver.resolve(query);
124  ...
125
126An ICMP socket may be bound to a local endpoint. The following code will create
127an 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_context, endpoint);
131
132The port number is not used for ICMP.
133
134Data may be read from or written to an unconnected ICMP socket using the [link
135boost_asio.reference.basic_raw_socket.receive_from receive_from()], [link
136boost_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
138boost_asio.reference.basic_raw_socket.async_send_to async_send_to()] member
139functions.
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]
150