forked from boostorg/beast
ff15cf8688
New buffer sequence classes are provided to allow full
control over the serialization of chunk-encoded message
payloads:
* chunk_header
A ConstBufferSequence representing the chunk header.
It includes a hexadecimal-encoded size, an optional
set of chunk extensions, and the trailing CRLF
required to denote the end of the chunk header.
This allows the caller to manually serialize the chunk
body in one or more calls to a stream output function.
The caller must also output an object of type `chunk_crlf`
to the stream to indicate the end of the chunk body.
* chunk_crlf
A small ConstBufferSequence that simply represents
the two character sequence "\r\n" (CRLF). This is needed
for the case where the caller wants to output a chunk
body as a series of buffers (i.e. "chunking a chunk").
* chunk_body
A ConstBufferSequence representing a complete chunk.
This includes the size, an optional set of chunk extensions,
a caller provided buffer containing the body, and the
required CRLF that follows.
* chunk_final
A ConstBufferSequence representing a final chunk. It
includes an optional set of caller-provided field trailers
* chunk_extensions
A container for building a set of chunk extensions to use
during serialization. The use of the container is optional,
callers may provide their own buffer containing a correctly
formatted set of chunk extensions, or they may use their
own convenience container which meets the requirements.
The basic_fields container is modified to allow construction
outside the context of a message. The container can be used
to provide trailers to `chunk_final`.
Actions Required:
* Remove references to ChunkDecorators. Use the new chunk-encoding
buffer sequences to manually produce a chunked payload body in
the case where control over the chunk-extensions and/or trailers
is required.
65 lines
2.1 KiB
Plaintext
65 lines
2.1 KiB
Plaintext
[/
|
|
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 Creating Streams]
|
|
|
|
The interface to the WebSocket implementation is a single template class
|
|
[link beast.ref.beast__websocket__stream `stream`]
|
|
which wraps an existing network transport object or other type of
|
|
octet oriented stream. The wrapped object is called the "next layer"
|
|
and must meet the requirements of __SyncStream__ if synchronous
|
|
operations are performed, __AsyncStream__ if asynchronous operations
|
|
are performed, or both. Any arguments supplied during construction of
|
|
the stream wrapper are passed to next layer's constructor.
|
|
|
|
Here we declare a websocket stream over a TCP/IP socket with ownership
|
|
of the socket. The `io_service` argument is forwarded to the wrapped
|
|
socket's constructor:
|
|
|
|
[ws_snippet_2]
|
|
|
|
[heading Using SSL]
|
|
|
|
To use WebSockets over SSL, use an instance of the `boost::asio::ssl::stream`
|
|
class template as the template type for the stream. The required `io_service`
|
|
and `ssl::context` arguments are forwarded to the wrapped stream's constructor:
|
|
|
|
[wss_snippet_1]
|
|
[wss_snippet_2]
|
|
|
|
[important
|
|
Code which declares websocket stream objects using Asio SSL types
|
|
must include the file [include_file beast/websocket/ssl.hpp].
|
|
]
|
|
|
|
[heading Non-owning References]
|
|
|
|
If a socket type supports move construction, a websocket stream may be
|
|
constructed around the already existing socket by invoking the move
|
|
constructor signature:
|
|
|
|
[ws_snippet_3]
|
|
|
|
Or, the wrapper can be constructed with a non-owning reference. In
|
|
this case, the caller is responsible for managing the lifetime of the
|
|
underlying socket being wrapped:
|
|
|
|
[ws_snippet_4]
|
|
|
|
Once the WebSocket stream wrapper is created, the wrapped object may be
|
|
accessed by calling
|
|
[link beast.ref.beast__websocket__stream.next_layer.overload1 `stream::next_layer`]:
|
|
|
|
[ws_snippet_5]
|
|
|
|
[warning
|
|
Initiating operations on the next layer while websocket
|
|
operations are being performed may result in undefined behavior.
|
|
]
|
|
|
|
[endsect]
|