Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 7b149d1613.
PrevUpHomeNext
websocket::stream::async_handshake (2 of 2 overloads)

Perform the WebSocket handshake asynchronously in the client role.

Synopsis
template<
    class HandshakeHandler = net::default_completion_token_t<executor_type>>
DEDUCED
async_handshake(
    response_type& res,
    string_view host,
    string_view target,
    HandshakeHandler&& handler = net::default_completion_token_t< executor_type >{});
Description

This initiating function is used to asynchronously begin performing the WebSocket handshake, required before messages can be sent and received. During the handshake, the client sends the Websocket Upgrade HTTP request, and the server replies with an HTTP response indicating the result of the handshake. This call always returns immediately. The asynchronous operation will continue until one of the following conditions is true:

The algorithm, known as a composed asynchronous operation, is implemented in terms of calls to the next layer's async_read_some and async_write_some functions. No other operation may be performed on the stream until this operation completes. The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a status-code of beast::http::status::switching_protocols.

Parameters

Name

Description

res

The HTTP Upgrade response returned by the remote endpoint. The caller may use the response to access any additional information sent by the server. This object will be assigned before the completion handler is invoked.

host

The name of the remote host. This is required by the HTTP protocol to set the "Host" header field. The implementation will not access the string data after the initiating function returns.

target

The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port. The implementation will not access the string data after the initiating function returns.

handler

The completion handler to invoke when the operation completes. The implementation takes ownership of the handler by performing a decay-copy. The equivalent function signature of the handler must be:

void handler(
    error_code const& ec    // Result of operation
);

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using net::post.

Example
response_type res;
ws.async_handshake(res, "localhost", "/",
    [&res](error_code ec)
    {
        if(ec)
            std::cerr << "Error: " << ec.message() << "\n";
        else
            std::cout << res;

    });
See Also

PrevUpHomeNext