| Home | Libraries | People | FAQ | More

###### websocket::stream::handshake_ex (1 of 4 overloads)

Send an HTTP WebSocket Upgrade request and receive the response.

Synopsis

    template<
        class RequestDecorator>
    void
    handshake_ex(
        string_view host,
        string_view target,
        RequestDecorator const& decorator);

Description

This function is used to synchronously send the WebSocket upgrade HTTP request. The call blocks until one of the following conditions is true:

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

This function is implemented in terms of one or more calls to the next layer's `read_some` and `write_some` functions.

The operation is successful if the received HTTP response indicates a successful HTTP Upgrade (represented by a Status-Code of 101, "switching protocols").

Parameters

Name | Description
--- | ---
`host` | The name of the remote host, required by the HTTP protocol.
`target` | The Request Target, which may not be empty, required by the HTTP protocol.
`decorator` | A function object which will be called to modify the HTTP request object generated by the implementation. This could be used to set the User-Agent field, subprotocols, or other application or HTTP specific fields. The object will be called with this equivalent signature:
     void decorator(
        request_type& req
    );

Exceptions

Type | Thrown On
--- | ---
`system_error` | Thrown on failure.

Example

    websocket::stream<ip::tcp::socket> ws{io_context};
    ...
    try
    {
        ws.handshake("localhost", "/",
            [](request_type& req)
            {
                req.set(field::user_agent, "Beast");
            });
    }
    catch(...)
    {
        // An error occurred.
    }