| Home | Libraries | People | FAQ | More

###### websocket::stream::handshake (4 of 4 overloads)

Perform the WebSocket handshake in the client role.

<h7> Synopsis </h7>

    void
    handshake(
        response_type& res,
        string_view host,
        string_view target,
        error_code& ec);

<h7> Description </h7>

This function is used to perform 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. The call blocks until one of the following conditions is true:

- The request is sent and the response is received.
- An error occurs.

The algorithm, known as a composed operation, is implemented in terms of calls to the next layer's `read_some` and `write_some` functions. The handshake is successful if the received HTTP response indicates the upgrade was accepted by the server, represented by a status-code of `http::switching_protocols`.

<h7> Parameters </h7>

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.
`host` | The name of the remote host. This is required by the HTTP protocol to set the "Host" header field.
`target` | The request-target, in origin-form. The server may use the target to distinguish different services on the same listening port.
`ec` | Set to indicate what error occurred, if any.

<h7> Example </h7>

    error_code ec;
    response_type res;
    ws.handshake(res, "localhost", "/", ec);
    if(! ec)
        std::cout << res;

<h7> See Also </h7>

- Websocket Opening Handshake Client Requirements (RFC6455)
- Host field (RFC7230)
- request-target (RFC7230)
- origin-form (RFC7230)