summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/protocols.qbk
blob: eed070c75115dddfbebb1b848b5f8462f7cc2333 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
[/
 / 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:protocols TCP, UDP and ICMP]

Asio provides off-the-shelf support for the internet protocols TCP, UDP and
ICMP.

[heading TCP Clients]

Hostname resolution is performed using a resolver, where host and service names
are looked up and converted into one or more endpoints:

  ip::tcp::resolver resolver(my_io_context);
  ip::tcp::resolver::query query("www.boost.org", "http");
  ip::tcp::resolver::iterator iter = resolver.resolve(query);
  ip::tcp::resolver::iterator end; // End marker.
  while (iter != end)
  {
    ip::tcp::endpoint endpoint = *iter++;
    std::cout << endpoint << std::endl;
  }

The list of endpoints obtained above could contain both IPv4 and IPv6 endpoints,
so a program should try each of them until it finds one that works. This keeps the
client program independent of a specific IP version.

To simplify the development of protocol-independent programs, TCP clients may
establish connections using the free functions [link asio.reference.connect
connect()] and [link asio.reference.async_connect async_connect()]. These
operations try each endpoint in a list until the socket is successfully
connected. For example, a single call:

  ip::tcp::socket socket(my_io_context);
  asio::connect(socket, resolver.resolve(query));

will synchronously try all endpoints until one is successfully connected.
Similarly, an asynchronous connect may be performed by writing:

  asio::async_connect(socket_, iter,
      boost::bind(&client::handle_connect, this,
        asio::placeholders::error));

  // ...

  void handle_connect(const error_code& error)
  {
    if (!error)
    {
      // Start read or write operations.
    }
    else
    {
      // Handle error.
    }
  }

When a specific endpoint is available, a socket can be created and connected:

  ip::tcp::socket socket(my_io_context);
  socket.connect(endpoint);

Data may be read from or written to a connected TCP socket using the [link
asio.reference.basic_stream_socket.receive receive()], [link
asio.reference.basic_stream_socket.async_receive async_receive()], [link
asio.reference.basic_stream_socket.send send()] or [link
asio.reference.basic_stream_socket.async_send async_send()] member functions.
However, as these could result in [link asio.overview.core.streams short writes
or reads], an application will typically use the following operations instead:
[link asio.reference.read read()], [link asio.reference.async_read
async_read()], [link asio.reference.write write()] and [link
asio.reference.async_write async_write()].

[heading TCP Servers]

A program uses an acceptor to accept incoming TCP connections:

  ip::tcp::acceptor acceptor(my_io_context, my_endpoint);
  ...
  ip::tcp::socket socket(my_io_context);
  acceptor.accept(socket);

After a socket has been successfully accepted, it may be read from or written
to as illustrated for TCP clients above.

[heading UDP]

UDP hostname resolution is also performed using a resolver:

  ip::udp::resolver resolver(my_io_context);
  ip::udp::resolver::query query("localhost", "daytime");
  ip::udp::resolver::iterator iter = resolver.resolve(query);
  ...

A UDP socket is typically bound to a local endpoint. The following code will
create an IP version 4 UDP socket and bind it to the "any" address on port
`12345`:

  ip::udp::endpoint endpoint(ip::udp::v4(), 12345);
  ip::udp::socket socket(my_io_context, endpoint);

Data may be read from or written to an unconnected UDP socket using the [link
asio.reference.basic_datagram_socket.receive_from receive_from()], [link
asio.reference.basic_datagram_socket.async_receive_from async_receive_from()],
[link asio.reference.basic_datagram_socket.send_to send_to()] or [link
asio.reference.basic_datagram_socket.async_send_to async_send_to()] member
functions. For a connected UDP socket, use the [link
asio.reference.basic_datagram_socket.receive receive()], [link
asio.reference.basic_datagram_socket.async_receive async_receive()], [link
asio.reference.basic_datagram_socket.send send()] or [link
asio.reference.basic_datagram_socket.async_send async_send()] member functions.

[heading ICMP]

As with TCP and UDP, ICMP hostname resolution is performed using a resolver:

  ip::icmp::resolver resolver(my_io_context);
  ip::icmp::resolver::query query("localhost", "");
  ip::icmp::resolver::iterator iter = resolver.resolve(query);
  ...

An ICMP socket may be bound to a local endpoint. The following code will create
an IP version 6 ICMP socket and bind it to the "any" address:

  ip::icmp::endpoint endpoint(ip::icmp::v6(), 0);
  ip::icmp::socket socket(my_io_context, endpoint);

The port number is not used for ICMP.

Data may be read from or written to an unconnected ICMP socket using the [link
asio.reference.basic_raw_socket.receive_from receive_from()], [link
asio.reference.basic_raw_socket.async_receive_from async_receive_from()],
[link asio.reference.basic_raw_socket.send_to send_to()] or [link
asio.reference.basic_raw_socket.async_send_to async_send_to()] member
functions.

[heading See Also]

[link asio.reference.ip__tcp ip::tcp],
[link asio.reference.ip__udp ip::udp],
[link asio.reference.ip__icmp ip::icmp],
[link asio.tutorial.tutdaytime1 daytime protocol tutorials],
[link asio.examples.cpp03_examples.icmp ICMP ping example].

[endsect]