diff options
Diffstat (limited to '3rdparty/asio/src/doc/overview/protocols.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/overview/protocols.qbk | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/protocols.qbk b/3rdparty/asio/src/doc/overview/protocols.qbk new file mode 100644 index 00000000000..eed070c7511 --- /dev/null +++ b/3rdparty/asio/src/doc/overview/protocols.qbk @@ -0,0 +1,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] |