boost_beast/doc/qbk/06_websocket/3_client.qbk

[/
    Copyright (c) 2016-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)

    Official repository: https://github.com/boostorg/beast
]

[section Handshaking (Clients)]

A WebSocket session begins when a client sends the HTTP/1
[@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade]
request for
[@https://tools.ietf.org/html/rfc6455#section-1.3 websocket],
and the server sends an appropriate response indicating that
the request was accepted and that the connection has been upgraded.
The Upgrade request must include the
[@https://tools.ietf.org/html/rfc7230#section-5.4 Host]
field, and the
[@https://tools.ietf.org/html/rfc7230#section-5.3 target]
of the resource to request. The stream member functions
[link beast.ref.boost__beast__websocket__stream.handshake.overload1 `handshake`] and
[link beast.ref.boost__beast__websocket__stream.async_handshake.overload1 `async_handshake`]
are used to send the request with the required host and target strings.

[ws_snippet_8]

The implementation will create and send a request that typically
looks like this:

[table WebSocket Upgrade HTTP Request
[[Serialized Octets][Description]]
[[
```
    GET / HTTP/1.1
    Host: localhost
    Upgrade: websocket
    Connection: upgrade
    Sec-WebSocket-Key: 2pGeTR0DsE4dfZs2pH+8MA==
    Sec-WebSocket-Version: 13
    User-Agent: Beast
```
][
    The host and target parameters become part of the Host field
    and request-target in the resulting HTTP request. The key is
    generated by the implementation. Callers may add fields or
    modify fields by providing a ['decorator], described below.
]]]

[heading Decorators]

If the caller wishes to add or modify fields, the member functions
[link beast.ref.boost__beast__websocket__stream.handshake_ex `handshake_ex`] and
[link beast.ref.boost__beast__websocket__stream.async_handshake_ex `async_handshake_ex`]
are provided which allow an additional function object, called a
['decorator], to be passed. The decorator is invoked to modify
the HTTP Upgrade request as needed. This example sets a subprotocol
on the request:

[ws_snippet_9]

The HTTP Upgrade request produced by the previous call will look thusly:

[table Decorated WebSocket Upgrade HTTP Request
[[Serialized Octets][Description]]
[[
    ```
    GET / HTTP/1.1
    Host: localhost
    Upgrade: websocket
    Connection: upgrade
    Sec-WebSocket-Key: 2pGeTR0DsE4dfZs2pH+8MA==
    Sec-WebSocket-Version: 13
    Sec-WebSocket-Protocol: xmpp;ws-chat
    User-Agent: Beast
    ```
][
    Undefined behavior results if the decorator modifies the fields
    specific to perform the WebSocket Upgrade , such as the Upgrade
    and Connection fields.
]]]

[heading Filtering]

When a client receives an HTTP Upgrade response from the server indicating
a successful upgrade, the caller may wish to perform additional validation
on the received HTTP response message. For example, to check that the
response to a basic authentication challenge is valid. To achieve this,
overloads of the handshake member function allow the caller to store the
received HTTP message in an output reference argument of type
[link beast.ref.boost__beast__websocket__response_type `response_type`]
as follows:

[ws_snippet_10]

[endsect]