1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section:using_websocket WebSocket] 11 12[/-----------------------------------------------------------------------------] 13 14The WebSocket Protocol enables two-way communication between a client running 15untrusted code in a controlled environment to a remote host that has opted-in 16to communications from that code. The protocol consists of an opening handshake 17followed by basic message framing, layered over TCP. The goal of this 18technology is to provide a mechanism for browser-based applications needing 19two-way communication with servers without relying on opening multiple HTTP 20connections. 21 22Beast provides developers with a robust WebSocket implementation 23built on Boost.Asio with a consistent asynchronous model using a modern C++ 24approach. 25 26[note 27 This documentation assumes familiarity with __Asio__ and 28 the protocol specification described in __rfc6455__. 29 Sample code and identifiers appearing in this section is written 30 as if these declarations are in effect: 31 32 [code_websocket_1a] 33 '''<?linebreak?>''' 34 [code_websocket_1b] 35] 36 37[/-----------------------------------------------------------------------------] 38 39[heading Construction] 40 41A WebSocket connection requires a stateful object, represented in Beast by a 42single class template 43[link beast.ref.boost__beast__websocket__stream `websocket::stream`]. 44The interface uses the layered stream model. A websocket stream object contains 45another stream object, called the "next layer", which it uses to perform I/O. 46Descriptions of each template parameter follow: 47 48[code_websocket_1h] 49 50[table WebSocket Stream Template Parameters 51[[Name][Description]] 52[ 53 [`NextLayer`] 54 [ 55 The type of the next layer. An object of this type will be constructed 56 and maintained for the lifetime of the stream. All reads and writes 57 will go through the next layer. This type must meet the requirements 58 of either __SyncStream__, __AsyncStream__, or both, depending on the 59 style of I/O that is to be performed. 60 ] 61][ 62 [`deflateSupported`] 63 [ 64 When this value is `true`, the stream will support (but not require) 65 the [@https://tools.ietf.org/html/rfc7692 permessage-deflate extension]. 66 Whether or not the stream actually requests or accepts the extension 67 during a handshake depends on a separate configurable option. 68 69 When the value is `false` the extension is disabled. Streams will 70 never request the extension in the client role or accept a request 71 for the extension in the server role. An additional benefit of 72 disabling the extension is that compilation will be faster, and 73 the resulting program executable will contain less code. 74 ] 75]] 76 77When a stream is constructed, any arguments provided to the constructor are 78forwarded to the next layer object's constructor. This declares a stream 79over a plain TCP/IP socket using an I/O context: 80 81[code_websocket_1f] 82 83[tip 84 Websocket streams use their own protocol-specific timeout feature. When 85 using a websocket stream with the 86 [link beast.ref.boost__beast__tcp_stream `tcp_stream`] or 87 [link beast.ref.boost__beast__basic_stream `basic_stream`] 88 class template, timeouts should be disabled on the TCP or basic stream 89 after the connection is established, otherwise the behavior of the 90 stream is undefined. 91] 92 93As with most I/O objects, a websocket stream is [*not thread-safe]. Undefined 94behavior results if two different threads access the object concurrently. 95For multi-threaded programs, the `tcp_stream` can be constructed from an 96executor, in this case a strand. The stream declared below will use a 97strand to invoke all completion handlers: 98 99[code_websocket_2f] 100 101If the next layer supports move-construction, then the websocket stream can be 102constructed from a moved-from object. 103 104[code_websocket_3f] 105 106The next layer may be accessed by calling 107[link beast.ref.boost__beast__websocket__stream.next_layer.overload1 `stream::next_layer`]. 108 109[code_websocket_4f] 110 111[/-----------------------------------------------------------------------------] 112 113[heading Using SSL] 114 115To use WebSockets over SSL, use an instance of the __ssl_stream__ 116class template as the template type for the stream. The required 117__io_context__ and __ssl_context__ arguments are forwarded to the 118wrapped stream's constructor: 119 120[code_websocket_5f] 121 122[important 123 Code which declares websocket stream objects using Asio SSL types 124 must include the file [include_file boost/beast/websocket/ssl.hpp]. 125] 126 127As before, the underlying SSL stream may be accessed by calling `next_layer`. 128 129[code_websocket_6f] 130 131With multi-layered streams such as the one declared above, accessing an 132individual layer can be cumbersome when using chained calls to `next_layer`. 133The function 134[link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`] 135returns the last stream in a stack of layers in a layered stream. Here we 136access the lowest layer to cancel all outstanding I/O. 137 138[code_websocket_7f] 139 140[/-----------------------------------------------------------------------------] 141 142[heading Non-Blocking Mode] 143 144Please note that websocket streams do not support non-blocking modes. 145 146[/-----------------------------------------------------------------------------] 147 148[include 01_connecting.qbk] 149[include 02_handshaking.qbk] 150[include 03_decorator.qbk] 151[include 04_messages.qbk] 152[include 05_control_frames.qbk] 153[include 06_timeouts.qbk] 154[include 07_teardown.qbk] 155[include 08_notes.qbk] 156 157[endsect] 158