Before creating the endpoint, the client application must obtain the raw IP address and the protocol port number designating the server it will communicate with. The server application on the other hand, as it usually listens for incoming messages on all IP addresses, only needs to obtain a port number on which to listen.

Here, we don't consider how the application obtains a raw IP address or a port number. In the following recipes, we assume that the IP address and the port number have already been obtained by the application and are available at the beginning of the corresponding algorithm.

The following algorithms and corresponding code samples demonstrate two common scenarios of creating an endpoint. The first one demonstrates how the client application can create an endpoint to specify the server it wants to communicate with. The second one demonstrates how the server application creates an endpoint to specify on which IP addresses and port it wants to listen for incoming messages from clients.

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Assume that the client application has already 
  // obtained the IP-address and the protocol port number.
  std::string raw_ip_address = "127.0.0.1";
  unsigned short port_num = 3333;

  // Used to store information about error that happens
  // while parsing the raw IP-address.
  boost::system::error_code ec;
  // Step 2. Using IP protocol version independent address
  // representation.
  asio::ip::address ip_address =
    asio::ip::address::from_string(raw_ip_address, ec);

  if (ec.value() != 0) {
    // Provided IP address is invalid. Breaking execution.
    std::cout 
      << "Failed to parse the IP address. Error code = "
      << ec.value() << ". Message: " << ec.message();
      return ec.value();
  }

  // Step 3.
  asio::ip::tcp::endpoint ep(ip_address, port_num);

  // Step 4. The endpoint is ready and can be used to specify a 
  // particular server in the network the client wants to 
  // communicate with.
  
  return 0;
}

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Here we assume that the server application has
  //already obtained the protocol port number.
  unsigned short port_num = 3333;

  // Step 2. Create special object of asio::ip::address class
  // that specifies all IP-addresses available on the host. Note
  // that here we assume that server works over IPv6 protocol.
  asio::ip::address ip_address = asio::ip::address_v6::any();

  // Step 3.
  asio::ip::tcp::endpoint ep(ip_address, port_num);

  // Step 4. The endpoint is created and can be used to 
  // specify the IP addresses and a port number on which 
  // the server application wants to listen for incoming 
  // connections.

  return 0;
}

Let's consider the first code sample. The algorithm it implements is applicable in an application playing a role of a client that is an application that actively initiates the communication session with a server. The client application needs to be provided an IP address and a protocol port number of the server. Here we assume that those values have already been obtained and are available at the beginning of the algorithm, which makes step 1 details a given.

Having obtained the raw IP address, the client application must represent it in terms of the Boost.Asio type system. Boost.Asio provides three classes used to represent an IP address:

In our sample, we use the asio::ip::address class, which makes the client application IP-protocol-version-agnostic. This means that it can transparently work with both IPv4 and IPv6 servers.

In step 2, we use the asio::ip::address class's static method, from_string(). This method accepts a raw IP address represented as a string, parses and validates the string, instantiates an object of the asio::ip::address class, and returns it to the caller. This method has four overloads. In our sample we use this one:

static asio::ip::address from_string(
    const std::string & str,
    boost::system::error_code & ec);

This method is very useful as it checks whether the string passed to it as an argument contains a valid IPv4 or IPv6 address and if it does, instantiates a corresponding object. If the address is invalid, the method will designate an error through the second argument. It means that this function can be used to validate the raw user input.

In step 3, we instantiate an object of the boost::asio::ip::tcp::endpoint class, passing the IP address and a protocol port number to its constructor. Now, the ep object can be used to designate a server application in the Boost.Asio communication related functions.

The second sample has a similar idea, although it somewhat differs from the first one. The server application is usually provided only with the protocol port number on which it should listen for incoming messages. The IP address is not provided because the server application usually wants to listen for the incoming messages on all IP addresses available on the host, not only on a specific one.

To represent the concept of all IP addresses available on the host, the classes asio::ip::address_v4 and asio::ip::address_v6 provide a static method any(), which instantiates a special object of corresponding class representing the concept. In step 2, we use the any() method of the asio::ip::address_v6 class to instantiate such a special object.

Note that the IP-protocol-version-agnostic class asio::ip::address does not provide the any() method. The server application must explicitly specify whether it wants to receive requests either on IPv4 or on IPv6 addresses by using the object returned by the any() method of either the asio::ip::address_v4 or asio::ip::address_v6 class correspondingly. In step 2 of our second sample, we assume that our server communicates over IPv6 protocol and therefore called the any() method of the asio::ip::address_v6 class.

In step 3, we create an endpoint object which represents all IP addresses available on the host and a particular protocol port number.

In both our previous samples we used the endpoint class declared in the scope of the asio::ip::tcp class. If we look at the declaration of the asio::ip::tcp class, we'll see something like this:

class tcp
{
public:
  /// The type of a TCP endpoint.
  typedef basic_endpoint<tcp> endpoint;

  //...
}

It means that this endpoint class is a specialization of the basic_endpoint<> template class that is intended for use in clients and servers communicating over the TCP protocol.

However, creating endpoints that can be used in clients and servers that communicate over the UDP protocol is just as easy. To represent such an endpoint, we need to use the endpoint class declared in the scope of the asio::ip::udp class. The following code snippet demonstrates how this endpoint class is declared:

class udp
{
public:
  /// The type of a UDP endpoint.
  typedef basic_endpoint<udp> endpoint;

  //...
}

For example, if we want to create an endpoint in our client application to designate a server with which we want to communicate over the UDP protocol, we would only slightly change the implementation of step 3 in our sample. This is how that step would look like with changes highlighted:

// Step 3.
asio::ip::udp::endpoint ep(ip_address, port_num);

All other code would not need to be changed as it is transport protocol independent.

The same trivial change in the implementation of step 3 in our second sample is required to switch from a server communicating over TCP to one communicating over UDP.

The following algorithm describes the steps required to perform in a client application to create and open an active socket:

The following code sample demonstrates possible implementation of the algorithm. It is assumed that the socket is intended to be used to communicate over the TCP protocol and IPv4 as the underlying protocol:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. An instance of 'io_service' class is required by
  // socket constructor. 
  asio::io_service ios;

  // Step 2. Creating an object of 'tcp' class representing
  // a TCP protocol with IPv4 as underlying protocol.
  asio::ip::tcp protocol = asio::ip::tcp::v4();

  // Step 3. Instantiating an active TCP socket object.
  asio::ip::tcp::socket sock(ios);

  // Used to store information about error that happens
  // while opening the socket.
  boost::system::error_code ec;

  // Step 4. Opening the socket.
  sock.open(protocol, ec);

  if (ec.value() != 0) {
    // Failed to open the socket.
    std::cout
      << "Failed to open the socket! Error code = "
      << ec.value() << ". Message: " << ec.message();
      return ec.value();
  }

  return 0;
}

In step 1, we instantiate an object of the asio::io_service class. This class is a central component in the Boost.Asio I/O infrastructure. It provides access to the network I/O services of the underlying operating system. Boost.Asio sockets get access to those services through the object of this class. Therefore, all socket class constructors require an object of asio::io_service as an argument. We'll consider the asio::io_service class in more detail in the following chapters.

In the next step, we create an instance of the asio::ip::tcp class. This class represents a TCP protocol. It provides no functionality, but rather acts like a data structure that contains a set of values that describe the protocol.

The asio::ip::tcp class doesn't have a public constructor. Instead, it provides two static methods, asio::ip::tcp::v4() and asio::ip::tcp::v6(), that return an object of the asio::ip::tcp class representing the TCP protocol with the underlying IPv4 or IPv6 protocol correspondingly.

Besides, the asio::ip::tcp class contains declarations of some basic types intended to be used with the TCP protocol. Among them are asio::tcp::endpoint, asio::tcp::socket, asio::tcp::acceptor, and others. Let's have a look at those declarations found in the boost/asio/ip/tcp.hpp file:

namespace boost {
namespace asio {
namespace ip {

  // ...
  class tcp
  {
  public:
    /// The type of a TCP endpoint.
    typedef basic_endpoint<tcp> endpoint;
    
    // ...
  
    /// The TCP socket type.
    typedef basic_stream_socket<tcp> socket;

    /// The TCP acceptor type.
    typedef basic_socket_acceptor<tcp> acceptor;
    
    // ...

In step 3, we create an instance of the asio::ip::tcp::socket class, passing the object of the asio::io_service class to its constructor as an argument. Note that this constructor does not allocate the underlying operating system's socket object. The real operating system's socket is allocated in step 4 when we call the open() method and pass an object specifying protocol to it as an argument.

In Boost.Asio, opening a socket means associating it with full set of parameters describing a specific protocol over which the socket is intended to be communicating. When the Boost.Asio socket object is provided with these parameters, it has enough information to allocate a real socket object of the underlying operating system.

The asio::ip::tcp::socket class provides another constructor that accepts a protocol object as an argument. This constructor constructs a socket object and opens it. Note that this constructor throws an exception of the type boost::system::system_error if it fails. Here is a sample demonstrating how we could combine steps 3 and 4 from the previous sample:

try {
  // Step 3 + 4 in single call. May throw.
  asio::ip::tcp::socket sock(ios, protocol);
} catch (boost::system::system_error & e) {
  std::cout << "Error occured! Error code = " << e.code()
    << ". Message: "<< e.what();
}

The previous sample demonstrates how to create an active socket intended to communicate over the TCP protocol. The process of creating a socket intended for communication over the UDP protocol is almost identical.

The following sample demonstrates how to create an active UDP socket. It is assumed that the socket is going to be used to communicate over the UDP protocol with IPv6 as the underlying protocol. No explanation is provided with the sample because it is very similar to the previous one and therefore should not be difficult to understand:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. An instance of 'io_service' class is required by
  // socket constructor. 
  asio::io_service ios;

  // Step 2. Creating an object of 'udp' class representing
  // a UDP protocol with IPv6 as underlying protocol.
  asio::ip::udp protocol = asio::ip::udp::v6();

  // Step 3. Instantiating an active UDP socket object.
  asio::ip::udp::socket sock(ios);

  // Used to store information about error that happens
  // while opening the socket.
  boost::system::error_code ec;

  // Step 4. Opening the socket.
  sock.open(protocol, ec);

  if (ec.value() != 0) {
    // Failed to open the socket.
    std::cout
      << "Failed to open the socket! Error code = "
      << ec.value() << ". Message: " << ec.message();
    return ec.value();
  }

  return 0;
}

In Boost.Asio a passive socket is represented by the asio::ip::tcp::acceptor class. The name of the class suggests the key function of the objects of the class—to listen for and accept or handle incoming connection requests.

The following algorithm describes the steps required to perform to create an acceptor socket:

The following code sample demonstrates the possible implementation of the algorithm. It is assumed that the acceptor socket is intended to be used over the TCP protocol and IPv6 as the underlying protocol:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. An instance of 'io_service' class is required by
  // socket constructor. 
  asio::io_service ios;

  // Step 2. Creating an object of 'tcp' class representing
  // a TCP protocol with IPv6 as underlying protocol.
  asio::ip::tcp protocol = asio::ip::tcp::v6();

  // Step 3. Instantiating an acceptor socket object.
  asio::ip::tcp::acceptor acceptor(ios);

  // Used to store information about error that happens
  // while opening the acceptor socket.
  boost::system::error_code ec;

  // Step 4. Opening the acceptor socket.
  acceptor.open(protocol, ec);

  if (ec.value() != 0) {
    // Failed to open the socket.
    std::cout
      << "Failed to open the acceptor socket!"
      << "Error code = "
      << ec.value() << ". Message: " << ec.message();
    return ec.value();
  }

  return 0;
}

Because an acceptor socket is very similar to an active socket, the procedure of creating them is almost identical. Therefore, here we only shortly go through the sample code. For more details about each step and each object involved in the procedure, please refer to the Creating an active socket recipe.

In step 1, we create an instance of the asio::io_service class. This class is needed by all Boost.Asio components that need access to the services of the underlying operating system.

In step 2, we create an object representing a TCP protocol with IPv6 as its underlying protocol.

Then in step 3, we create an instance of the asio::ip::tcp::acceptor class, passing an object of the asio::io_service class as an argument to its constructor. Just as in the case of an active socket, this constructor instantiates an object of Boost.Asio the asio::ip::tcp::acceptor class, but does not allocate the actual socket object of the underlying operating system.

The operating system socket object is allocated in step 4, where we open the acceptor socket object, calling its open() method and passing the protocol object to it as an argument. If the call succeeds, the acceptor socket object is opened and can be used to start listening for incoming connection requests. Otherwise, the ec object of the boost::system::error_code class will contain error information.

The following algorithm describes steps required to perform in a client application in order to resolve a DNS name to obtain IP addresses (zero or more) of hosts (zero or more) running the server application that the client application wants to communicate with:

The following code sample demonstrates the possible implementation of the algorithm. It is assumed that the client application is intended to communicate with the server application over the TCP protocol and IPv6 as the underlying protocol. Besides, it is assumed that the server DNS name and a port number have already been obtained and represented as strings by the client application:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Assume that the client application has already
  // obtained the DNS name and protocol port number and 
  // represented them as strings.
  std::string host = "samplehost.com";
  std::string port_num = "3333";

  // Step 2.
  asio::io_service ios;

  // Step 3. Creating a query.
  asio::ip::tcp::resolver::query resolver_query(host,
    port_num, asio::ip::tcp::resolver::query::numeric_service);

  // Step 4. Creating a resolver.
  asio::ip::tcp::resolver resolver(ios);

  // Used to store information about error that happens
  // during the resolution process.
  boost::system::error_code ec;

  // Step 5.
  asio::ip::tcp::resolver::iterator it =
    resolver.resolve(resolver_query, ec);

  // Handling errors if any.
  if (ec != 0) {
    // Failed to resolve the DNS name. Breaking execution.
    std::cout << "Failed to resolve a DNS name."
      << "Error code = " << ec.value() 
      << ". Message = " << ec.message();

    return ec.value();
  }

  return 0;
}

In step 1, we begin by obtaining a DNS name and a protocol port number and representing them as strings. Usually, these parameters are supplied by a user through the client application's UI or as command-line arguments. The process of obtaining and validating these parameters is behind the scope of this recipe; therefore, here we assume that they are available at the beginning of the sample.

Then, in step 2, we create an instance of the asio::io_service class that is used by the resolver to access underlying OS's services during a DNS name resolution process.

In step 3 we create an object of the asio::ip::tcp::resolver::query class. This object represents a query to the DNS. It contains a DNS name to resolve, a port number that will be used to construct an endpoint object after the DNS name resolution and a set of flags controlling some specific aspects of resolution process, represented as a bitmap. All these values are passed to the query class's constructor. Because the service is specified as a protocol port number (in our case, 3333) and not as a service name (for example, HTTP, FTP, and so on), we passed the asio::ip::tcp::resolver::query::numeric_service flag to explicitly inform the query object about that, so that it properly parses the port number value.

In step 4, we create an instance of the asio::ip::tcp::resolver class. This class provides the DNS name resolution functionality. To perform the resolution, it requires services of the underlying operating system and it gets access to them through the object of the asio::io_services class being passed to its constructor as an argument.

The DNS name resolution is performed in step 5 in the resolver object's resolve() method. The method overload we use in our sample accepts objects of the asio::ip::tcp::resolver::query and system::error_code classes. The latter object will contain information describing the error if the method fails.

If successful, the method returns an object of the asio::ip::tcp::resolver::iterator class, which is an iterator pointing to the first element of a collection representing resolution results. The collection contains objects of the asio::ip::basic_resolver_entry<tcp> class. There are as many objects in the collection as the total number of IP addresses that resolution yielded. Each collection element contains an object of the asio::ip::tcp::endpoint class instantiated from one IP address resulting from the resolution process and a port number provided with the corresponding query object. The endpoint object can be accessed through the asio::ip::basic_resolver_entry<tcp>::endopoint() getter method.

The default-constructed object of the asio::ip::tcp::resolver::iterator class represents an end iterator. Consider the following sample demonstrating how we can iterate through the elements of the collection representing the DNS name resolution process results and how to access the resulting endpoint objects:

asio::ip::tcp::resolver::iterator it = 
    resolver.resolve(resolver_query, ec);

asio::ip::tcp::resolver::iterator it_end;

for (; it != it_end; ++it) {
  // Here we can access the endpoint like this.
  asio::ip::tcp::endpoint ep = it->endpoint();
}

Usually, when a DNS name of the host running the server application is resolved to more than one IP address and correspondingly to more than one endpoint, the client application doesn't know which one of the multiple endpoints to prefer. The common approach in this case is to try to communicate with each endpoint one by one, until the desired response is received.

Note that when the DNS name is mapped to more than one IP address and some of them are IPv4 and others are IPv6 addresses, the DNS name may be resolved either to the IPv4 address or to the IPv6 address or to both. Therefore, the resulting collection may contain endpoints representing both IPv4 and IPv6 addresses.

To resolve a DNS name and obtain a collection of endpoints that can be used in the client that is intended to communicate over the UDP protocol, the code is very similar. The sample is given here with differences highlighted and without explanation:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Assume that the client application has already
// obtained the DNS name and protocol port number and 
// represented them as strings.
std::string host = "samplehost.book";
  std::string port_num = "3333";

  // Step 2.
  asio::io_service ios;

  // Step 3. Creating a query.
  asio::ip::udp::resolver::query resolver_query(host,
port_num, asio::ip::udp::resolver::query::numeric_service);

  // Step 4. Creating a resolver.
  asio::ip::udp::resolver resolver(ios);

  // Used to store information about error that happens
  // during the resolution process.
  boost::system::error_code ec;

  // Step 5.
  asio::ip::udp::resolver::iterator it =
    resolver.resolve(resolver_query, ec);

  // Handling errors if any.
  if (ec != 0) {
    // Failed to resolve the DNS name. Breaking execution.
    std::cout << "Failed to resolve a DNS name."
<< "Error code = " << ec.value() 
<< ". Message = " << ec.message();

    return ec.value();
  }

asio::ip::udp::resolver::iterator it_end;

for (; it != it_end; ++it) {
    // Here we can access the endpoint like this.
    asio::ip::udp::endpoint ep = it->endpoint();
}

  return 0;
}

The following algorithm describes steps required to create an acceptor socket and to bind it to an endpoint designating all IP addresses available on the host and a particular protocol port number in the IPv4 TCP server application:

The following code sample demonstrates possible implementation of the algorithm. It is assumed that the protocol port number has already been obtained by the application:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Here we assume that the server application has
  // already obtained the protocol port number.
  unsigned short port_num = 3333;

  // Step 2. Creating an endpoint.
  asio::ip::tcp::endpoint ep(asio::ip::address_v4::any(),
    port_num);

  // Used by 'acceptor' class constructor.
  asio::io_service ios;

  // Step 3. Creating and opening an acceptor socket.
  asio::ip::tcp::acceptor acceptor(ios, ep.protocol());

  boost::system::error_code ec;

  // Step 4. Binding the acceptor socket.
  acceptor.bind(ep, ec);

  // Handling errors if any.
  if (ec != 0) {
    // Failed to bind the acceptor socket. Breaking
    // execution.
    std::cout << "Failed to bind the acceptor socket."
      << "Error code = " << ec.value() << ". Message: "
      << ec.message();

    return ec.value();
  }

  return 0;
}

We begin by obtaining a protocol port number in step 1. The process of obtaining this parameter is beyond the scope of this recipe; therefore, here we assume that the port number has already been obtained and is available at the beginning of the sample.

In step 2 we create an endpoint representing all IP addresses available on the host and the specified port number.

In step 3 we instantiate and open the acceptor socket. The endpoint we created in step 2 contains information about the transport protocol and the version of the underlying IP protocol (IPv4). Therefore, we don't need to create another object representing the protocol to pass it to the acceptor socket's constructor. Instead, we use the endpoint's protocol() method, which returns an object of the asio::ip::tcp class representing the corresponding protocols.

The binding is performed in step 4. This is quite a simple operation. We call the acceptor socket's bind() method, passing an object representing an endpoint to which the acceptor socket should be bound as an argument of the method. If the call succeeds, the acceptor socket is bound to the corresponding endpoint and is ready to start listening for incoming connection requests on that endpoint.

UDP servers don't establish connections and use active sockets to wait for incoming requests. The process of binding an active socket is very similar to binding an acceptor socket. Here, we present a sample code demonstrating how to bind a UDP active socket to an endpoint designating all IP addresses available on the host and a particular protocol port number. The code is provided without explanation:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Here we assume that the server application has
  // already obtained the protocol port number.
  unsigned short port_num = 3333;

  // Step 2. Creating an endpoint.
  asio::ip::udp::endpoint ep(asio::ip::address_v4::any(),
    port_num);

  // Used by 'socket' class constructor.
  asio::io_service ios;

  // Step 3. Creating and opening a socket.
  asio::ip::udp::socket sock(ios, ep.protocol());

  boost::system::error_code ec;

  // Step 4. Binding the socket to an endpoint.
  sock.bind(ep, ec);

  // Handling errors if any.
  if (ec != 0) {
    // Failed to bind the socket. Breaking execution.
    std::cout << "Failed to bind the socket."
      << "Error code = " << ec.value() << ". Message: "
      << ec.message();

    return ec.value();
  }

  return 0;
}

The following algorithm descries steps required to perform in the TCP client application to connect an active socket to the server application:

The following code sample demonstrates a possible implementation of the algorithm:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step 1. Assume that the client application has already
  // obtained the IP address and protocol port number of the
  // target server.
  std::string raw_ip_address = "127.0.0.1";
  unsigned short port_num = 3333;

  try {
    // Step 2. Creating an endpoint designating 
    // a target server application.
    asio::ip::tcp::endpoint
      ep(asio::ip::address::from_string(raw_ip_address),
      port_num);

    asio::io_service ios;

    // Step 3. Creating and opening a socket.
    asio::ip::tcp::socket sock(ios, ep.protocol());

    // Step 4. Connecting a socket.
    sock.connect(ep);

    // At this point socket 'sock' is connected to 
    // the server application and can be used
    // to send data to or receive data from it.
  }
  // Overloads of asio::ip::address::from_string() and 
  // asio::ip::tcp::socket::connect() used here throw
  // exceptions in case of error condition.
  catch (system::system_error &e) {
    std::cout << "Error occured! Error code = " << e.code()
      << ". Message: " << e.what();
    
    return e.code().value();
  }

  return 0;
}

In step 1, we begin with obtaining the target server's IP address and a protocol port number. The process of obtaining these parameters is beyond the scope of this recipe; therefore, here we assume that they have already been obtained and are available at the beginning of our sample.

In step 2, we create an object of the asio::ip::tcp::endpoint class designating the target server application to which we are going to connect.

Then, in step 3 an active socket is instantiated and opened.

In step 4, we call the socket's connect() method, passing an endpoint object designating the target server to it as an argument. This function connects the socket to the server. The connection is performed synchronously, which means that the method blocks the caller thread until either the connection operation is established or an error occurs.

Note that we didn't bind the socket to any local endpoint before connecting it. This doesn't mean that the socket stays unbound. Before performing the connection establishment procedure, the socket's connect() method will bind the socket to the endpoint consisting of an IP address and a protocol port number chosen by the operating system.

Another thing to note in this sample is that we use an overload of the connect() method that throws an exception of the boost::system::system_error type if the operation fails, and so does overload of the asio::ip::address::from_string() static method we use in step 2. Therefore, both calls are enclosed in a try block. Both methods have overloads that don't throw exceptions and accept an object of the boost::system::error_code class, which is used to conduct error information to the caller in case the operation fails. However, in this case, using exceptions to handle errors makes code better structured.

The previous code sample showed how to connect a socket to a specific server application designated by an endpoint when an IP address and a protocol port number are provided to the client application explicitly. However, sometimes the client application is provided with a DNS name that may be mapped to one or more IP addresses. In this case, we first need to resolve the DNS name using the resolve() method provided by the asio::ip::tcp::resolver class. This method resolves a DNS name, creates an object of the asio::ip::tcp::endpoint class from each IP address resulted from resolution, puts all endpoint objects in a collection, and returns an object of the asio::ip::tcp::resolver::iterator class, which is an iterator pointing to the first element in the collection.

When a DNS name resolves to multiple IP addresses, the client application—when deciding to which one to connect—usually has no reasons to prefer one IP address to any other. The common approach in this situation is to iterate through endpoints in the collection and try to connect to each of them one by one until the connection succeeds. Boost.Asio provides auxiliary functionality that implements this approach.

The free function asio::connect() accepts an active socket object and an object of the asio::ip::tcp::resolver::iterator class as input arguments, iterates over a collection of endpoints, and tries to connect the socket to each endpoint. The function stops iteration, and returns when it either successfully connects a socket to one of the endpoints or when it has tried all the endpoints and failed to connect the socket to all of them.

The following algorithm demonstrates steps required to connect a socket to a server application represented by a DNS name and a protocol port number:

The following code sample demonstrates possible implementation of the algorithm:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // Step1. Assume that the client application has already
  // obtained the DNS name and protocol port number and
  // represented them as strings.
  std::string host = "samplehost.book";
  std::string port_num = "3333";

  // Used by a 'resolver' and a 'socket'.
  asio::io_service ios;

  // Creating a resolver's query.
  asio::ip::tcp::resolver::query resolver_query(host, port_num,
    asio::ip::tcp::resolver::query::numeric_service);

  // Creating a resolver.
  asio::ip::tcp::resolver resolver(ios);

  try {
    // Step 2. Resolving a DNS name.
    asio::ip::tcp::resolver::iterator it =
      resolver.resolve(resolver_query);

    // Step 3. Creating a socket.
    asio::ip::tcp::socket sock(ios);

    // Step 4. asio::connect() method iterates over
    // each endpoint until successfully connects to one
    // of them. It will throw an exception if it fails
    // to connect to all the endpoints or if other
    // error occurs.
    asio::connect(sock, it);
    
    // At this point socket 'sock' is connected to 
    // the server application and can be used
    // to send data to or receive data from it.
  }
  // Overloads of asio::ip::tcp::resolver::resolve and 
  // asio::connect() used here throw
  // exceptions in case of error condition.
  catch (system::system_error &e) {
    std::cout << "Error occured! Error code = " << e.code()
      << ". Message: " << e.what();

    return e.code().value();
  }

  return 0;
}

Note that in step 3, we don't open the socket when we create it. This is because we don't know the version of IP addresses to which the provided DNS name will resolve. The asio::connect() function opens the socket before connecting it to each endpoint specifying proper protocol object and closes it if the connection fails.

All other steps in the code sample should not be difficult to understand, therefore no explanation is provided.

The following algorithm describes how to set up an acceptor socket so that it starts listening for incoming connections and then how to use it to synchronously process the pending connection request. The algorithm assumes that only one incoming connection will be processed in synchronous mode:

The following code sample demonstrates possible implementation of the server application that follows the algorithm. Here, we assume that the server is intended to communicate over the TCP protocol with IPv4 as the underlying protocol:

#include <boost/asio.hpp>
#include <iostream>

using namespace boost;

int main()
{
  // The size of the queue containing the pending connection
  // requests.
  const int BACKLOG_SIZE = 30;

  // Step 1. Here we assume that the server application has
  // already obtained the protocol port number.
  unsigned short port_num = 3333;

  // Step 2. Creating a server endpoint.
  asio::ip::tcp::endpoint ep(asio::ip::address_v4::any(),
    port_num);

  asio::io_service ios;

  try {
    // Step 3. Instantiating and opening an acceptor socket.
    asio::ip::tcp::acceptor acceptor(ios, ep.protocol());

    // Step 4. Binding the acceptor socket to the 
    // server endpint.
    acceptor.bind(ep);

    // Step 5. Starting to listen for incoming connection
    // requests.
    acceptor.listen(BACKLOG_SIZE);

    // Step 6. Creating an active socket.
    asio::ip::tcp::socket sock(ios);

    // Step 7. Processing the next connection request and 
    // connecting the active socket to the client.
    acceptor.accept(sock);

    // At this point 'sock' socket is connected to 
    //the client application and can be used to send data to
    // or receive data from it.
  }
  catch (system::system_error &e) {
    std::cout << "Error occured! Error code = " << e.code()
      << ". Message: " << e.what();

    return e.code().value();
  }

  return 0;
}

In step 1, we obtain the protocol port number to which the server application binds its acceptor socket. Here, we assume that the port number has already been obtained and is available at the beginning of the sample.

In step 2, we create a server endpoint that designates all IP addresses available on the host running the server application and a specific protocol port number.

Then in step 3, we instantiate and open an acceptor socket and bind it to the server endpoint in step 4.

In step 5, we call the acceptor's listen() method passing the BACKLOG_SIZE constant value as an argument. This call switches the acceptor socket into the state in which it listens for incoming connection requests. Unless we call the listen() method on the acceptor object, all connection requests arriving at corresponding endpoint will be rejected by the operating system network software. The application must explicitly notify the operating system that it wants to start listening for incoming connection requests on specific endpoint by this call.

The argument that the listen() method accepts as an argument specifies the size of the queue maintained by the operating system to which it puts connection requests arriving from the clients. The requests stay in the queue and are waiting for the server application to de-queue and process them. When the queue becomes full, the new connection requests are rejected by the operating system.

In step 6, we create an active socket object without opening it. We'll need it in step 7.

In step 7, we call the acceptor socket's accept() method. This method accepts an active socket as an argument and performs several operations. First, it checks the queue associated with the acceptor socket containing pending connection requests. If the queue is empty, the method blocks execution until a new connection request arrives to an endpoint to which the acceptor socket is bound and the operating system puts it in the queue.

If at least one connection request is available in the queue, the one on the top of the queue is extracted from it and processed. The active socket that was passed to the accept() method as an argument is connected to the corresponding client application which issued the connection request.

If the connection establishment process succeeds, the accept() method returns and the active socket is opened and connected to the client application and can be used to send data to and receive data from it.

Note that UDP servers don't use acceptor sockets because the UDP protocol doesn't imply connection establishment. Instead, an active socket is used that is bound to an endpoint and listens for incoming I/O messages, and this same active socket is used for communication.