One WebSocket frame/message (RFC 6455): parsing, generation and control frames. More...

#include <NetworkProtocols.h>

Public Types
enum	DataType { NONE = 0 , TEXT = 1 , BINARY = 2 , CLOSE = 8 , PING = 9 , PONG = 10 }
	Frame content type, mapping to the RFC 6455 opcode. More...
enum	WSSTATUS { IDLE = 0 , INCOMPLETE = 1 , COMPLETE = 2 }
	Parsing status of this frame: not started, awaiting more bytes, or fully received. More...

Public Member Functions
	WebsocketData (uint64 source=0, uint64 startRecTime=0)
	Construct an empty frame.
	WebsocketData (WebsocketData *req)
	Deep-copy constructor.
virtual	~WebsocketData ()
bool	isTerminationRequest ()
bool	isTerminationConfirmation ()
bool	isComplete ()
bool	isPing ()
bool	isPong ()
bool	setData (DataType dataType, bool maskData, const char *data=NULL, uint64 size=0)
	Set the payload and build the serialised frame for sending.
const char *	getRawData (uint64 &size)
	Get the serialised on-the-wire frame bytes (header + masked payload).
bool	processHeader (const char *buffer, uint64 size, bool &isInvalid)
	Parse the frame header from raw bytes (handles 16/64-bit extended lengths).
bool	processContent (const char *buffer, uint64 size)
	Append (and unmask) payload bytes after the header has been parsed.
const char *	getContent (uint64 &size)
	Get the decoded (unmasked) payload.
uint64	getContentSize ()
uint64	getPayloadSize ()

Static Public Member Functions
static WebsocketData *	CreateTerminationConfirmation ()
static WebsocketData *	CreatePong ()
static WebsocketData *	CreatePing ()

Public Attributes
enum cmlabs::WebsocketData::DataType	dataType
enum cmlabs::WebsocketData::WSSTATUS	status
bool	isFinal
	FIN bit: true when this is the last fragment of a message.
uint64	time
	Timestamp when reception/creation started (ms epoch).
uint64	endReceiveTime
	Timestamp when the frame was fully received (ms epoch).
uint64	source
	Packed uint64 endpoint of the sender (0 if local).
uint32	headerLength
	Parsed frame header length in bytes (2..14).
uint64	contentSize
	Payload bytes accumulated so far.
uint64	payloadSize
	Declared payload length from the header.
uint8	opcode
	RFC 6455 opcode (see DataType).
uint32	maskingKey
	32-bit masking key (0 when unmasked, i.e.
uint32	packages
	Number of fragments accumulated into this message.
char *	data
	Owned decoded payload bytes.
char *	rawData
	Owned serialised frame bytes (for sending).

Static Public Attributes
static uint8 const	BHB0_OPCODE = 0x0F
	Byte 0: 4-bit opcode (see DataType).
static uint8 const	BHB0_RSV3 = 0x10
	Byte 0: reserved bit 3 (extensions; must be 0).
static uint8 const	BHB0_RSV2 = 0x20
	Byte 0: reserved bit 2 (extensions; must be 0).
static uint8 const	BHB0_RSV1 = 0x40
	Byte 0: reserved bit 1 (extensions; must be 0).
static uint8 const	BHB0_FIN = 0x80
	Byte 0: FIN — set on the final fragment of a message.
static uint8 const	BHB1_PAYLOAD = 0x7F
	Byte 1: 7-bit basic payload length / extension code.
static uint8 const	BHB1_MASK = 0x80
	Byte 1: MASK — payload is XOR-masked (required client-to-server).
static uint8 const	payload_size_code_16bit = 0x7E
	Basic length 126: a 16-bit big-endian length follows.
static uint8 const	payload_size_code_64bit = 0x7F
	Basic length 127: a 64-bit big-endian length follows.
static uint8 const	basic_header_length = 2
static uint8 const	max_header_length = 14
	Maximum length of a WebSocket header.
static uint8 const	max_extended_header_length = 12
	Maximum length of the variable portion of the WebSocket header.
static uint8 const	payload_size_basic = 125
	Maximum size of a basic WebSocket payload.
static uint16 const	payload_size_extended = 0xFFFF
	Maximum size of an extended WebSocket payload (basic payload = 126).
static uint64 const	payload_size_jumbo = 0x7FFFFFFFFFFFFFFFLL
	Maximum size of a jumbo WebSocket payload (basic payload = 127).

Detailed Description

One WebSocket frame/message (RFC 6455): parsing, generation and control frames.

Represents a single WebSocket data unit, either parsed from socket bytes (processHeader() + processContent(), possibly across multiple fragments — see ::isFinal and ::packages) or generated for sending via setData() / the CreatePing()/CreatePong()/CreateTerminationConfirmation() factories. The BHB0_* and BHB1_* constants are the RFC 6455 basic-header bit masks (FIN/RSV/opcode in byte 0, mask flag and 7-bit payload length in byte 1); extended payload lengths (16-bit and 64-bit) are read in network byte order. Client-to-server frames are masked with ::maskingKey per the RFC.

Header layout parsed/produced (see also the file-level framing overview):

 byte 0            byte 1              optional extension
+-+-+-+-+-------+ +-+-------------+  +----------------+--------------+
|F|R|R|R|opcode | |M| payload len |  | ext. len 2/8 B | mask key 4 B |
|I|S|S|S|(4 bit)| |A|   (7 bit)   |  | if len=126/127 | if MASK set  |
|N|V|V|V|       | |S|             |  | (big-endian)   |              |
+-+-+-+-+-------+ +-+-------------+  +----------------+--------------+

A header is thus 2..14 bytes (::basic_header_length .. ::max_header_length). Fragmented messages (FIN clear on all but the last frame) are reassembled by HTTPProtocol::ReceiveWebsocketData(), counting fragments in ::packages.

Note: Not thread-safe; owned by one connection thread.

Definition at line 443 of file NetworkProtocols.h.

Member Enumeration Documentation

◆ DataType

enum cmlabs::WebsocketData::DataType

Frame content type, mapping to the RFC 6455 opcode.

Enumerator
NONE
TEXT
BINARY
CLOSE
PING
PONG

Definition at line 446 of file NetworkProtocols.h.

◆ WSSTATUS

enum cmlabs::WebsocketData::WSSTATUS

Parsing status of this frame: not started, awaiting more bytes, or fully received.

Enumerator
IDLE
INCOMPLETE
COMPLETE

Definition at line 448 of file NetworkProtocols.h.

Constructor & Destructor Documentation

◆ WebsocketData() [1/2]

cmlabs::WebsocketData::WebsocketData	(	uint64	source = 0,
		uint64	startRecTime = 0 )

Construct an empty frame.

Parameters

source	Packed uint64 endpoint of the sender (0 if local).
startRecTime	Receive start timestamp; defaults to now when 0.

Definition at line 942 of file NetworkProtocols.cpp.

References contentSize, data, dataType, headerLength, IDLE, isFinal, maskingKey, NONE, opcode, packages, payloadSize, rawData, source, and status.

Referenced by CreatePing(), CreatePong(), CreateTerminationConfirmation(), and WebsocketData().

◆ WebsocketData() [2/2]

cmlabs::WebsocketData::WebsocketData ( WebsocketData * req )

Deep-copy constructor.

Parameters

req	Frame to copy (not modified).

Definition at line 956 of file NetworkProtocols.cpp.

References contentSize, data, dataType, headerLength, isFinal, maskingKey, opcode, packages, payloadSize, rawData, status, and WebsocketData().

◆ ~WebsocketData()

cmlabs::WebsocketData::~WebsocketData ( )

virtual

Definition at line 978 of file NetworkProtocols.cpp.

References data, IDLE, rawData, and status.

Member Function Documentation

◆ CreatePing()

WebsocketData * cmlabs::WebsocketData::CreatePing ( )

static

Returns: A new PING control frame (caller owns it).

Definition at line 994 of file NetworkProtocols.cpp.

References PING, setData(), and WebsocketData().

◆ CreatePong()

WebsocketData * cmlabs::WebsocketData::CreatePong ( )

static

Returns: A new PONG control frame (caller owns it).

Definition at line 1000 of file NetworkProtocols.cpp.

References PONG, setData(), and WebsocketData().

◆ CreateTerminationConfirmation()

WebsocketData * cmlabs::WebsocketData::CreateTerminationConfirmation ( )

static

Returns: A new CLOSE frame acknowledging a termination request (caller owns it).

Definition at line 988 of file NetworkProtocols.cpp.

References CLOSE, setData(), and WebsocketData().

Referenced by cmlabs::NetworkChannel::HTTPServerRun().

◆ getContent()

const char * cmlabs::WebsocketData::getContent ( uint64 & size )

Get the decoded (unmasked) payload.

Parameters

size	Out: payload size.

Returns: Payload bytes owned by this object, or NULL.

Definition at line 1301 of file NetworkProtocols.cpp.

References COMPLETE, contentSize, data, payloadSize, and status.

Referenced by cmlabs::WebsocketTestServer::receiveWebsocketData(), and cmlabs::TestWebsocketRoundTrip().

◆ getContentSize()

uint64 cmlabs::WebsocketData::getContentSize ( )

Returns: Number of payload bytes received so far (this frame).

Definition at line 1128 of file NetworkProtocols.cpp.

References contentSize.

◆ getPayloadSize()

uint64 cmlabs::WebsocketData::getPayloadSize ( )

Returns: The declared payload size from the frame header.

Definition at line 1132 of file NetworkProtocols.cpp.

References payloadSize.

Referenced by cmlabs::TestWebSocketRequestClient::run(), and cmlabs::TestWebsocketRoundTrip().

◆ getRawData()

const char * cmlabs::WebsocketData::getRawData ( uint64 & size )

Get the serialised on-the-wire frame bytes (header + masked payload).

Parameters

size	Out: total frame size.

Returns: Frame bytes owned by this object, or NULL.

Definition at line 1118 of file NetworkProtocols.cpp.

References COMPLETE, headerLength, payloadSize, rawData, and status.

Referenced by cmlabs::HTTPProtocol::SendWebsocketData(), and cmlabs::TestWebsocketRoundTrip().

◆ isComplete()

bool cmlabs::WebsocketData::isComplete ( )

Returns: true once the full payload has been received (status == COMPLETE).

Definition at line 1137 of file NetworkProtocols.cpp.

References COMPLETE, and status.

Referenced by cmlabs::HTTPProtocol::ReceiveWebsocketData(), and cmlabs::TestWebsocketRoundTrip().

◆ isPing()

bool cmlabs::WebsocketData::isPing ( )

Returns: true if this is a PING control frame.

Definition at line 1014 of file NetworkProtocols.cpp.

References dataType, and PING.

◆ isPong()

bool cmlabs::WebsocketData::isPong ( )

Returns: true if this is a PONG control frame.

Definition at line 1018 of file NetworkProtocols.cpp.

References dataType, and PONG.

◆ isTerminationConfirmation()

bool cmlabs::WebsocketData::isTerminationConfirmation ( )

Returns: true if this is a CLOSE frame confirming termination.

Definition at line 1010 of file NetworkProtocols.cpp.

References CLOSE, and dataType.

◆ isTerminationRequest()

bool cmlabs::WebsocketData::isTerminationRequest ( )

Returns: true if this is a CLOSE frame initiating termination.

Definition at line 1006 of file NetworkProtocols.cpp.

References CLOSE, and dataType.

Referenced by cmlabs::NetworkChannel::HTTPClientRun(), and cmlabs::NetworkChannel::HTTPServerRun().

◆ processContent()

bool cmlabs::WebsocketData::processContent	(	const char *	buffer,
		uint64	size )

Append (and unmask) payload bytes after the header has been parsed.

Parameters

buffer	Payload bytes.
size	Byte count.

Returns: true when the payload is complete.

Definition at line 1232 of file NetworkProtocols.cpp.

References COMPLETE, contentSize, data, endReceiveTime, cmlabs::GetTimeNow(), IDLE, INCOMPLETE, isFinal, LOG_NETWORK, LogPrint, maskingKey, packages, payloadSize, and status.

Referenced by cmlabs::HTTPProtocol::ReceiveWebsocketData(), and cmlabs::TestWebsocketRoundTrip().

◆ processHeader()

bool cmlabs::WebsocketData::processHeader	(	const char *	buffer,
		uint64	size,
		bool &	isInvalid )

Parse the frame header from raw bytes (handles 16/64-bit extended lengths).

Parameters

buffer	Raw bytes.
size	Byte count.
isInvalid	Out: set true when the bytes cannot be a WebSocket frame.

Returns: true when the header was parsed; false if more bytes are needed or invalid.

Definition at line 1141 of file NetworkProtocols.cpp.

References basic_header_length, BHB0_FIN, BHB0_OPCODE, BHB1_MASK, BHB1_PAYLOAD, BINARY, CLOSE, COMPLETE, dataType, cmlabs::GetTimeNow(), headerLength, IDLE, isFinal, maskingKey, cmlabs::utils::ntoh64(), opcode, payload_size_basic, payload_size_code_16bit, payloadSize, PING, PONG, status, TEXT, and time.

Referenced by cmlabs::HTTPProtocol::ReceiveWebsocketData(), and cmlabs::TestWebsocketRoundTrip().

◆ setData()

bool cmlabs::WebsocketData::setData	(	DataType	dataType,
		bool	maskData,
		const char *	data = NULL,
		uint64	size = 0 )

Set the payload and build the serialised frame for sending.

Parameters

dataType	TEXT, BINARY or a control type.
maskData	Apply client-side masking (required for client-to-server frames).
data	Payload bytes (copied; may be NULL for empty control frames).
size	Payload size in bytes.

Returns: true when the frame was assembled.

Warning: The current sender writes at most a 16-bit extended length: a single frame larger than 65535 bytes would be framed incorrectly (the 64-bit "jumbo" branch is unreachable — see the implementation note in NetworkProtocols.cpp). Keep individual frames ≤ 64 KB; the receive path handles all RFC sizes.

Definition at line 1022 of file NetworkProtocols.cpp.

References basic_header_length, BHB0_FIN, BHB0_OPCODE, BHB1_MASK, COMPLETE, contentSize, data, dataType, headerLength, maskingKey, MAXVALUINT32, NONE, cmlabs::utils::ntoh64(), opcode, payload_size_basic, payload_size_code_16bit, payload_size_code_64bit, payload_size_extended, payloadSize, cmlabs::utils::RandomInt(), rawData, and status.

Referenced by CreatePing(), CreatePong(), CreateTerminationConfirmation(), cmlabs::WebsocketTestServer::receiveWebsocketData(), cmlabs::RequestGateway::replyToClient(), cmlabs::TestWebSocketRequestClient::run(), and cmlabs::TestWebsocketRoundTrip().

Member Data Documentation

◆ basic_header_length

uint8 const cmlabs::WebsocketData::basic_header_length = 2

static

Definition at line 461 of file NetworkProtocols.h.

Referenced by processHeader(), and setData().

◆ BHB0_FIN

uint8 const cmlabs::WebsocketData::BHB0_FIN = 0x80

static

Byte 0: FIN — set on the final fragment of a message.

Definition at line 455 of file NetworkProtocols.h.

Referenced by processHeader(), setData(), and cmlabs::TestWebsocketRoundTrip().

◆ BHB0_OPCODE

uint8 const cmlabs::WebsocketData::BHB0_OPCODE = 0x0F

static

Byte 0: 4-bit opcode (see DataType).

Definition at line 451 of file NetworkProtocols.h.

Referenced by processHeader(), setData(), and cmlabs::TestWebsocketRoundTrip().

◆ BHB0_RSV1

uint8 const cmlabs::WebsocketData::BHB0_RSV1 = 0x40

static

Byte 0: reserved bit 1 (extensions; must be 0).

Definition at line 454 of file NetworkProtocols.h.

◆ BHB0_RSV2

uint8 const cmlabs::WebsocketData::BHB0_RSV2 = 0x20

static

Byte 0: reserved bit 2 (extensions; must be 0).

Definition at line 453 of file NetworkProtocols.h.

◆ BHB0_RSV3

uint8 const cmlabs::WebsocketData::BHB0_RSV3 = 0x10

static

Byte 0: reserved bit 3 (extensions; must be 0).

Definition at line 452 of file NetworkProtocols.h.

◆ BHB1_MASK

uint8 const cmlabs::WebsocketData::BHB1_MASK = 0x80

static

Byte 1: MASK — payload is XOR-masked (required client-to-server).

Definition at line 457 of file NetworkProtocols.h.

Referenced by processHeader(), and setData().

◆ BHB1_PAYLOAD

uint8 const cmlabs::WebsocketData::BHB1_PAYLOAD = 0x7F

static

Byte 1: 7-bit basic payload length / extension code.

Definition at line 456 of file NetworkProtocols.h.

Referenced by processHeader().

◆ contentSize

uint64 cmlabs::WebsocketData::contentSize

Payload bytes accumulated so far.

Definition at line 563 of file NetworkProtocols.h.

Referenced by getContent(), getContentSize(), processContent(), cmlabs::RequestGateway::receiveWebsocketData(), setData(), WebsocketData(), and WebsocketData().

◆ data

char* cmlabs::WebsocketData::data

Owned decoded payload bytes.

Definition at line 569 of file NetworkProtocols.h.

Referenced by getContent(), processContent(), cmlabs::RequestGateway::receiveWebsocketData(), cmlabs::TestWebSocketRequestClient::run(), setData(), WebsocketData(), WebsocketData(), and ~WebsocketData().

◆ dataType

enum cmlabs::WebsocketData::DataType cmlabs::WebsocketData::dataType

Referenced by isPing(), isPong(), isTerminationConfirmation(), isTerminationRequest(), processHeader(), cmlabs::WebsocketTestServer::receiveWebsocketData(), setData(), cmlabs::TestWebsocketRoundTrip(), WebsocketData(), and WebsocketData().

◆ endReceiveTime

uint64 cmlabs::WebsocketData::endReceiveTime

Timestamp when the frame was fully received (ms epoch).

Definition at line 558 of file NetworkProtocols.h.

Referenced by processContent().

◆ headerLength

uint32 cmlabs::WebsocketData::headerLength

Parsed frame header length in bytes (2..14).

Definition at line 562 of file NetworkProtocols.h.

Referenced by getRawData(), processHeader(), cmlabs::HTTPProtocol::ReceiveWebsocketData(), setData(), cmlabs::TestWebsocketRoundTrip(), WebsocketData(), and WebsocketData().

◆ isFinal

bool cmlabs::WebsocketData::isFinal

FIN bit: true when this is the last fragment of a message.

Definition at line 556 of file NetworkProtocols.h.

Referenced by processContent(), processHeader(), WebsocketData(), and WebsocketData().

◆ maskingKey

uint32 cmlabs::WebsocketData::maskingKey

32-bit masking key (0 when unmasked, i.e.

server-to-client).

Definition at line 566 of file NetworkProtocols.h.

Referenced by processContent(), processHeader(), setData(), WebsocketData(), and WebsocketData().

◆ max_extended_header_length

uint8 const cmlabs::WebsocketData::max_extended_header_length = 12

static

Maximum length of the variable portion of the WebSocket header.

Definition at line 465 of file NetworkProtocols.h.

◆ max_header_length

uint8 const cmlabs::WebsocketData::max_header_length = 14

static

Maximum length of a WebSocket header.

Definition at line 463 of file NetworkProtocols.h.

◆ opcode

uint8 cmlabs::WebsocketData::opcode

RFC 6455 opcode (see DataType).

Definition at line 565 of file NetworkProtocols.h.

Referenced by processHeader(), setData(), WebsocketData(), and WebsocketData().

◆ packages

uint32 cmlabs::WebsocketData::packages

Number of fragments accumulated into this message.

Definition at line 567 of file NetworkProtocols.h.

Referenced by processContent(), WebsocketData(), and WebsocketData().

◆ payload_size_basic

uint8 const cmlabs::WebsocketData::payload_size_basic = 125

static

Maximum size of a basic WebSocket payload.

Definition at line 467 of file NetworkProtocols.h.

Referenced by processHeader(), and setData().

◆ payload_size_code_16bit

uint8 const cmlabs::WebsocketData::payload_size_code_16bit = 0x7E

static

Basic length 126: a 16-bit big-endian length follows.

Definition at line 458 of file NetworkProtocols.h.

Referenced by processHeader(), and setData().

◆ payload_size_code_64bit

uint8 const cmlabs::WebsocketData::payload_size_code_64bit = 0x7F

static

Basic length 127: a 64-bit big-endian length follows.

Definition at line 459 of file NetworkProtocols.h.

Referenced by setData().

◆ payload_size_extended

uint16 const cmlabs::WebsocketData::payload_size_extended = 0xFFFF

static

Maximum size of an extended WebSocket payload (basic payload = 126).

Definition at line 469 of file NetworkProtocols.h.

Referenced by setData().

◆ payload_size_jumbo

uint64 const cmlabs::WebsocketData::payload_size_jumbo = 0x7FFFFFFFFFFFFFFFLL

static

Maximum size of a jumbo WebSocket payload (basic payload = 127).

Definition at line 471 of file NetworkProtocols.h.

◆ payloadSize

uint64 cmlabs::WebsocketData::payloadSize

Declared payload length from the header.

Definition at line 564 of file NetworkProtocols.h.

Referenced by getContent(), getPayloadSize(), getRawData(), processContent(), processHeader(), cmlabs::HTTPProtocol::ReceiveWebsocketData(), setData(), WebsocketData(), and WebsocketData().

◆ rawData

char* cmlabs::WebsocketData::rawData

Owned serialised frame bytes (for sending).

Definition at line 570 of file NetworkProtocols.h.

Referenced by getRawData(), setData(), WebsocketData(), WebsocketData(), and ~WebsocketData().

◆ source

uint64 cmlabs::WebsocketData::source

Packed uint64 endpoint of the sender (0 if local).

Definition at line 559 of file NetworkProtocols.h.

Referenced by cmlabs::RequestGateway::receiveWebsocketData(), and WebsocketData().

◆ status

enum cmlabs::WebsocketData::WSSTATUS cmlabs::WebsocketData::status

Referenced by getContent(), getRawData(), isComplete(), processContent(), processHeader(), setData(), WebsocketData(), WebsocketData(), and ~WebsocketData().

◆ time

uint64 cmlabs::WebsocketData::time

Timestamp when reception/creation started (ms epoch).

Definition at line 557 of file NetworkProtocols.h.

Referenced by processHeader().

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

/home/ubuntu/c/partner/psyclone2/CMSDK/include/NetworkProtocols.h
/home/ubuntu/c/partner/psyclone2/CMSDK/src/NetworkProtocols.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ DataType

◆ WSSTATUS

Constructor & Destructor Documentation

◆ WebsocketData() [1/2]

◆ WebsocketData() [2/2]

◆ ~WebsocketData()

Member Function Documentation

◆ CreatePing()

◆ CreatePong()

◆ CreateTerminationConfirmation()

◆ getContent()

◆ getContentSize()

◆ getPayloadSize()

◆ getRawData()

◆ isComplete()

◆ isPing()

◆ isPong()

◆ isTerminationConfirmation()

◆ isTerminationRequest()

◆ processContent()

◆ processHeader()

◆ setData()

Member Data Documentation

◆ basic_header_length

◆ BHB0_FIN

◆ BHB0_OPCODE

◆ BHB0_RSV1

◆ BHB0_RSV2

◆ BHB0_RSV3

◆ BHB1_MASK

◆ BHB1_PAYLOAD

◆ contentSize

◆ data

◆ dataType

◆ endReceiveTime

◆ headerLength

◆ isFinal

◆ maskingKey

◆ max_extended_header_length

◆ max_header_length

◆ opcode

◆ packages

◆ payload_size_basic

◆ payload_size_code_16bit

◆ payload_size_code_64bit

◆ payload_size_extended

◆ payload_size_jumbo

◆ payloadSize

◆ rawData

◆ source

◆ status

◆ time