forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,95 @@
|
||||
[/
|
||||
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:client 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.websocket__stream.handshake.overload1 `handshake`] and
|
||||
[link beast.ref.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.websocket__stream.handshake_ex `handshake_ex`] and
|
||||
[link beast.ref.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 as
|
||||
[link beast.ref.websocket__response_type `response_type`]
|
||||
as follows:
|
||||
|
||||
[ws_snippet_10]
|
||||
|
||||
[endsect]
|
||||
Reference in new issue
Block a user