[/
    Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail 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:connect Establishing Connections]

Connections are established by invoking functions directly on the next layer
object. For example, to make an outgoing connection using a standard TCP/IP
socket:
```
    std::string const host = "mywebapp.com";
    boost::asio::io_service ios;
    boost::asio::ip::tcp::resolver r{ios};
    beast::websocket::stream<boost::asio::ip::tcp::socket> ws{ios};
    boost::asio::connect(ws.next_layer(),
        r.resolve(boost::asio::ip::tcp::resolver::query{host, "ws"}));
```

Similarly, to accept an incoming connection using a standard TCP/IP
socket, pass the next layer object to the acceptor:
```
void do_accept(boost::asio::ip::tcp::acceptor& acceptor)
{
    beast::websocket::stream<boost::asio::ip::tcp::socket> ws{acceptor.get_io_service()};
    acceptor.accept(ws.next_layer());
}
```

When using SSL, which itself wraps a next layer object that is usually a
TCP/IP socket, multiple calls to retrieve the next layer may be required.
In this example, the websocket stream wraps the SSL stream which wraps
the TCP/IP socket:
```
    beast::websocket::stream<boost::asio::ssl::stream<
        boost::asio::ip::tcp::socket>> ws{ios, ctx};

    // connect the underlying TCP/IP socket
    ws.next_layer().next_layer().connect(ep);

    // perform SSL handshake
    ws.next_layer().handshake(boost::asio::ssl::stream_base::client);

    // perform WebSocket handshake
    ws.handshake("localhost", "/");
```

[note
    Examples use synchronous interfaces for clarity of exposition.
]

[endsect]