WPILibC++  2019.3.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
wpi::WebSocket Class Reference

RFC 6455 compliant WebSocket client and server implementation. More...

#include <WebSocket.h>

Inheritance diagram for wpi::WebSocket:

Classes

struct  ClientOptions
 Client connection options. More...
 

Public Types

enum  State {
  CONNECTING = 0, OPEN, CLOSING, FAILED,
  CLOSED
}
 Connection states. More...
 

Public Member Functions

 WebSocket (uv::Stream &stream, bool server, const private_init &)
 
 WebSocket (const WebSocket &)=delete
 
 WebSocket (WebSocket &&)=delete
 
WebSocketoperator= (const WebSocket &)=delete
 
WebSocketoperator= (WebSocket &&)=delete
 
State GetState () const
 Get connection state.
 
bool IsOpen () const
 Return if the connection is open. More...
 
uv::StreamGetStream () const
 Get the underlying stream.
 
StringRef GetProtocol () const
 Get the selected sub-protocol. More...
 
void SetMaxMessageSize (size_t size)
 Set the maximum message size. More...
 
void SetCombineFragments (bool combine)
 Set whether or not fragmented frames should be combined. More...
 
void Close (uint16_t code=1005, const Twine &reason=Twine{})
 Initiate a closing handshake. More...
 
void SendText (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a text message. More...
 
void SendBinary (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a binary message. More...
 
void SendTextFragment (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a text message fragment. More...
 
void SendBinaryFragment (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a text message fragment. More...
 
void SendFragment (ArrayRef< uv::Buffer > data, bool fin, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a continuation frame. More...
 
void SendPing (std::function< void(uv::Error)> callback=nullptr)
 Send a ping frame with no data. More...
 
void SendPing (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a ping frame. More...
 
void SendPong (std::function< void(uv::Error)> callback=nullptr)
 Send a pong frame with no data. More...
 
void SendPong (ArrayRef< uv::Buffer > data, std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)> callback)
 Send a pong frame. More...
 
void Fail (uint16_t code=1002, const Twine &reason="protocol error")
 Fail the connection.
 
void Terminate (uint16_t code=1006, const Twine &reason="terminated")
 Forcibly close the connection.
 
template<typename T = void>
std::shared_ptr< T > GetData () const
 Gets user-defined data. More...
 
void SetData (std::shared_ptr< void > data)
 Sets user-defined data. More...
 

Static Public Member Functions

static std::shared_ptr< WebSocketCreateClient (uv::Stream &stream, const Twine &uri, const Twine &host, ArrayRef< StringRef > protocols=ArrayRef< StringRef >{}, const ClientOptions &options=ClientOptions{})
 Starts a client connection by performing the initial client handshake. More...
 
static std::shared_ptr< WebSocketCreateServer (uv::Stream &stream, StringRef key, StringRef version, StringRef protocol=StringRef{})
 Starts a server connection by performing the initial server side handshake. More...
 

Public Attributes

sig::Signal< StringRefopen
 Open event. More...
 
sig::Signal< uint16_t, StringRefclosed
 Close event. More...
 
sig::Signal< StringRef, bool > text
 Text message event. More...
 
sig::Signal< ArrayRef< uint8_t >
, bool > 
binary
 Binary message event. More...
 
sig::Signal< ArrayRef< uint8_t > > ping
 Ping event. More...
 
sig::Signal< ArrayRef< uint8_t > > pong
 Pong event. More...
 

Detailed Description

RFC 6455 compliant WebSocket client and server implementation.

Member Enumeration Documentation

Connection states.

Enumerator
CONNECTING 

The connection is not yet open.

OPEN 

The connection is open and ready to communicate.

CLOSING 

The connection is in the process of closing.

FAILED 

The connection failed.

CLOSED 

The connection is closed.

Member Function Documentation

void wpi::WebSocket::Close ( uint16_t  code = 1005,
const Twine reason = Twine{} 
)

Initiate a closing handshake.

Parameters
codeA numeric status code (defaults to 1005, no status code)
reasonA human-readable string explaining why the connection is closing (optional).
static std::shared_ptr<WebSocket> wpi::WebSocket::CreateClient ( uv::Stream stream,
const Twine uri,
const Twine host,
ArrayRef< StringRef protocols = ArrayRefStringRef >{},
const ClientOptions options = ClientOptions{} 
)
static

Starts a client connection by performing the initial client handshake.

An open event is emitted when the handshake completes. This sets the stream user data to the websocket.

Parameters
streamConnection stream
uriThe Request-URI to send
hostThe host or host:port to send
protocolsThe list of subprotocols
optionsHandshake options
static std::shared_ptr<WebSocket> wpi::WebSocket::CreateServer ( uv::Stream stream,
StringRef  key,
StringRef  version,
StringRef  protocol = StringRef{} 
)
static

Starts a server connection by performing the initial server side handshake.

This should be called after the HTTP headers have been received. An open event is emitted when the handshake completes. This sets the stream user data to the websocket.

Parameters
streamConnection stream
keyThe value of the Sec-WebSocket-Key header field in the client request
versionThe value of the Sec-WebSocket-Version header field in the client request
protocolThe subprotocol to send to the client (in the Sec-WebSocket-Protocol header field).
template<typename T = void>
std::shared_ptr<T> wpi::WebSocket::GetData ( ) const
inline

Gets user-defined data.

Returns
User-defined data if any, nullptr otherwise.
StringRef wpi::WebSocket::GetProtocol ( ) const
inline

Get the selected sub-protocol.

Only valid in or after the open() event.

bool wpi::WebSocket::IsOpen ( ) const
inline

Return if the connection is open.

Messages can only be sent on open connections.

void wpi::WebSocket::SendBinary ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a binary message.

Parameters
dataData to send
callbackCallback which is invoked when the write completes.
void wpi::WebSocket::SendBinaryFragment ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters
dataData to send
callbackCallback which is invoked when the write completes.
void wpi::WebSocket::SendFragment ( ArrayRef< uv::Buffer data,
bool  fin,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a continuation frame.

This is used to send additional parts of a message started with SendTextFragment() or SendBinaryFragment().

Parameters
dataData to send
finSet to true if this is the final fragment of the message
callbackCallback which is invoked when the write completes.
void wpi::WebSocket::SendPing ( std::function< void(uv::Error)>  callback = nullptr)
inline

Send a ping frame with no data.

Parameters
callbackOptional callback which is invoked when the ping frame write completes.
void wpi::WebSocket::SendPing ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a ping frame.

Parameters
dataData to send in the ping frame
callbackCallback which is invoked when the ping frame write completes.
void wpi::WebSocket::SendPong ( std::function< void(uv::Error)>  callback = nullptr)
inline

Send a pong frame with no data.

Parameters
callbackOptional callback which is invoked when the pong frame write completes.
void wpi::WebSocket::SendPong ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a pong frame.

Parameters
dataData to send in the pong frame
callbackCallback which is invoked when the pong frame write completes.
void wpi::WebSocket::SendText ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a text message.

Parameters
dataUTF-8 encoded data to send
callbackCallback which is invoked when the write completes.
void wpi::WebSocket::SendTextFragment ( ArrayRef< uv::Buffer data,
std::function< void(MutableArrayRef< uv::Buffer >, uv::Error)>  callback 
)
inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters
dataUTF-8 encoded data to send
callbackCallback which is invoked when the write completes.
void wpi::WebSocket::SetCombineFragments ( bool  combine)
inline

Set whether or not fragmented frames should be combined.

Default is to combine. If fragmented frames are combined, the text and binary callbacks will always have the second parameter (fin) set to true.

Parameters
combineTrue if fragmented frames should be combined.
void wpi::WebSocket::SetData ( std::shared_ptr< void >  data)
inline

Sets user-defined data.

Parameters
dataUser-defined arbitrary data.
void wpi::WebSocket::SetMaxMessageSize ( size_t  size)
inline

Set the maximum message size.

Default is 128 KB. If configured to combine fragments this maximum applies to the entire message (all combined fragments).

Parameters
sizeMaximum message size in bytes

Member Data Documentation

sig::Signal<ArrayRef<uint8_t>, bool> wpi::WebSocket::binary

Binary message event.

Emitted when a binary message is received. The first parameter is the data, the second parameter is true if the data is the last fragment of the message.

sig::Signal<uint16_t, StringRef> wpi::WebSocket::closed

Close event.

Emitted when the connection is closed. The first parameter is a numeric value indicating the status code explaining why the connection has been closed. The second parameter is a human-readable string explaining the reason why the connection has been closed.

sig::Signal<StringRef> wpi::WebSocket::open

Open event.

Emitted when the connection is open and ready to communicate. The parameter is the selected subprotocol.

sig::Signal<ArrayRef<uint8_t> > wpi::WebSocket::ping

Ping event.

Emitted when a ping message is received.

sig::Signal<ArrayRef<uint8_t> > wpi::WebSocket::pong

Pong event.

Emitted when a pong message is received.

sig::Signal<StringRef, bool> wpi::WebSocket::text

Text message event.

Emitted when a text message is received. The first parameter is the data, the second parameter is true if the data is the last fragment of the message.


The documentation for this class was generated from the following file: