CMSDK 2.0.1
Cross-platform C++ base library and SDK for the Psyclone AIOS platform
Loading...
Searching...
No Matches
NetworkProtocols.h File Reference
Networking

Wire-protocol layer: HTTP request/reply, WebSocket frames, Telnet lines, binary DataMessages, and protocol auto-detection. More...

#include "DataMessage.h"
#include "NetworkConnections.h"
#include "jsmn.h"
#include "hash/sha1.h"
Include dependency graph for NetworkProtocols.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  cmlabs::HTTPPostEntry
 One named entry of an HTTP POST body (form field or uploaded file part). More...
class  cmlabs::HTTPRequest
 A parsed or generated HTTP request (also used for WebSocket upgrade handshakes). More...
struct  cmlabs::JSONMEntry
 Metadata for one binary attachment chunk inside a JSONM container. More...
class  cmlabs::JSONM
 JSONM: a JSON document with attached binary chunks in one contiguous buffer. More...
class  cmlabs::WebsocketData
 One WebSocket frame/message (RFC 6455): parsing, generation and control frames. More...
class  cmlabs::TelnetLine
 One line of Telnet-style text traffic. More...
class  cmlabs::HTTPReply
 A parsed or generated HTTP response. More...
class  cmlabs::NetworkProtocol
 Base class for the protocol auto-detection framework. More...
class  cmlabs::HTTPProtocol
 Server-side HTTP/WebSocket protocol handler (static send/receive helpers). More...
class  cmlabs::HTTPClientProtocol
 Client-side HTTP protocol handler (mirror of HTTPProtocol for outgoing requests). More...
class  cmlabs::MessageProtocol
 Binary DataMessage protocol handler: size-prefixed serialised messages. More...
class  cmlabs::TelnetProtocol
 Telnet line protocol handler for interactive text connections. More...

Namespaces

namespace  cmlabs

Macros

Protocol and encryption flags

Bit flags identifying wire protocols (combinable for auto-detect listeners) and encryption schemes.

#define PROTOCOL_HTTP_SERVER   1
 Serve HTTP: parse requests, send replies (server role).
#define PROTOCOL_HTTP_CLIENT   2
 Speak HTTP as a client: send requests, parse replies.
#define PROTOCOL_MESSAGE   4
 CMSDK binary DataMessage protocol (size-prefixed frames).
#define PROTOCOL_TELNET   8
 Line-based Telnet-style text protocol.
#define PROTOCOL_3GCAM   16
 Legacy 3G camera streaming protocol.
#define ENCRYPTION_SSL   1
 SSL/TLS transport encryption flag.
#define ENCRYPTION_AES   2
 AES transport encryption flag (reserved).
HTTP methods

Numeric HTTP method ids used in HTTPRequest::type; index into ::HTTP_Type for the method name string.

#define HTTP_GET   1
 GET.
#define HTTP_PUT   2
 PUT.
#define HTTP_POST   3
 POST.
#define HTTP_HEAD   4
 HEAD.
#define HTTP_DELETE   5
 DELETE.
#define HTTP_OPTIONS   6
 OPTIONS.
Telnet line-ending styles
#define TELNET_WINDOWS   1
 CRLF (\r\n) line endings.
#define TELNET_UNIX   2
 LF (\n) line endings.
HTTP reply status codes

CMSDK-internal status ids used with HTTPReply::createErrorPage() etc.; index into ::HTTP_Status for the full status line text.

#define HTTP_OK   0
 200 OK
#define HTTP_MOVED_PERMANENTLY   1
 301 Moved Permanently
#define HTTP_USE_LOCAL_COPY   2
 304 Not Modified (use cached copy)
#define HTTP_MALFORMED_URL   3
 400 Bad Request
#define HTTP_UNAUTHORIZED   4
 401 Unauthorized (triggers Basic auth)
#define HTTP_ACCESS_DENIED   5
 403 Forbidden
#define HTTP_FILE_NOT_FOUND   6
 404 Not Found
#define HTTP_INTERNAL_ERROR   7
 500 Internal Server Error (page generation)
#define HTTP_NOT_IMPLEMENTED   8
 501 Not Implemented
#define HTTP_SERVICE_NOT_AVAILABLE   9
 503 Service Unavailable
#define HTTP_GATEWAY_TIMEOUT   10
 504 Gateway Timeout
#define HTTP_SERVER_UNAVAILABLE   11
 500 (backend server unavailable)
#define HTTP_SERVER_NOREPLY   12
 500 (no reply from backend server)
#define HTTP_SERVER_MALFORMED_REPLY   13
 500 (malformed backend reply)
#define HTTP_SWITCH_PROTOCOL   14
 101 Switching Protocols (WebSocket upgrade)

Functions

bool cmlabs::NetworkProtocols_UnitTest ()

Variables

static char cmlabs::HTTP_Type [][8]
 HTTP method name strings, indexed by the HTTP_* method ids (index 0 unused).
static char cmlabs::HTTP_Status [][128]
 Full HTTP status lines (with inline error bodies for error cases), indexed by the HTTP_* status ids above.

Detailed Description

Wire-protocol layer: HTTP request/reply, WebSocket frames, Telnet lines, binary DataMessages, and protocol auto-detection.

This header sits between the raw transports (NetworkConnections.h) and the connection manager (NetworkManager.h). It defines:

  • Message containers: HTTPRequest, HTTPReply, WebsocketData, TelnetLine and JSONM (JSON-with-binary-attachments multipart container). Each knows how to parse itself from raw socket bytes (processHeader()/processContent()) and how to serialise itself for sending.
  • Protocol handlers: static-method classes (HTTPProtocol, HTTPClientProtocol, MessageProtocol, TelnetProtocol) that read/write the containers over a NetworkConnection with timeouts.
  • Auto-detection: each protocol implements CheckBufferForCompatibility(), letting a listener sniff the first bytes of an incoming connection and route it to the right handler (see NetworkChannel::autoDetectConnection()).

PROTOCOL_* constants are bit flags, so a listener can accept several protocols on one port (e.g. HTTP + binary messages + Telnet).

Byte order
WebSocket framing (extended payload lengths, masking keys) is converted with htons()/ntohs()/ntoh64() and follows RFC 6455 network (big-endian) byte order — see the BHB0_* and BHB1_* masks in WebsocketData. The binary DataMessage protocol, by contrast, sends the message's serialised memory image as-is: its leading uint32 size field is read on the receiving side without any byte-order conversion (see MessageProtocol::ReceiveMessage()), so both endpoints are assumed to share the same (in practice little-endian) endianness — fine for x86/ARM deployments, but a real portability caveat for big-endian hosts.
Wire framing at a glance
The two binary formats framed by this layer:
DataMessage frame (PROTOCOL_MESSAGE), host byte order:
[uint32 totalSize][uint32 DATAMESSAGEID][ ...serialised message... ]
ReceiveMessage() peeks the first 8 bytes, validates the id, then reads
exactly totalSize bytes and hands them to DataMessage (zero-copy adopt).
WebSocket frame header (RFC 6455), network byte order:
byte 0: FIN(0x80) RSV1-3(0x40/0x20/0x10) OPCODE(0x0F)
byte 1: MASK(0x80) PAYLOAD-LEN(0x7F)
len <= 125 : that value is the payload size (no extension)
len == 126 : next 2 bytes = uint16 payload size (ntohs)
len == 127 : next 8 bytes = uint64 payload size (ntoh64)
then, if MASK set: 4-byte masking key; payload bytes are XORed with
key[i % 4] (clients MUST mask; servers send unmasked).
PROTOCOL_MESSAGE
#define PROTOCOL_MESSAGE
CMSDK binary DataMessage protocol (size-prefixed frames).
Definition NetworkProtocols.h:76
DATAMESSAGEID
#define DATAMESSAGEID
Definition ObjectIDs.h:75
Platform notes
This header itself is platform-neutral: all Winsock-vs-BSD socket differences (#ifdef WIN32 / _WIN64 vs POSIX, WSAStartup, SOCKET vs int descriptors) live one layer down in NetworkConnections.h, and the byte-order helpers (htons()/ntohs() from the platform headers, utils::ntoh64() for 64-bit values) behave identically on both families. Protocol code here therefore compiles unchanged on Windows, Linux and macOS.

Definition in file NetworkProtocols.h.

Macro Definition Documentation

◆ ENCRYPTION_AES

#define ENCRYPTION_AES   2

AES transport encryption flag (reserved).

Definition at line 80 of file NetworkProtocols.h.

◆ ENCRYPTION_SSL

#define ENCRYPTION_SSL   1

SSL/TLS transport encryption flag.

Definition at line 79 of file NetworkProtocols.h.

◆ HTTP_ACCESS_DENIED

#define HTTP_ACCESS_DENIED   5

403 Forbidden

Definition at line 638 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkChannel::HTTPServerRun(), cmlabs::HTTPReply::processHeader(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_DELETE

#define HTTP_DELETE   5

DELETE.

Definition at line 96 of file NetworkProtocols.h.

Referenced by cmlabs::RESTHTTPCall::init(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::HTTPRequest::processHeader(), and cmlabs::RequestGateway::receiveWebsocketData().

◆ HTTP_FILE_NOT_FOUND

#define HTTP_FILE_NOT_FOUND   6

404 Not Found

Definition at line 639 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPReply::createFromFile(), cmlabs::HTTPReply::processHeader(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_GATEWAY_TIMEOUT

#define HTTP_GATEWAY_TIMEOUT   10

504 Gateway Timeout

Definition at line 643 of file NetworkProtocols.h.

Referenced by cmlabs::TestWebRequestClient::run().

◆ HTTP_GET

#define HTTP_GET   1

GET.

Definition at line 92 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPServerTest(), cmlabs::RESTHTTPCall::init(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::HTTPRequest::processHeader(), cmlabs::RequestGateway::receiveWebsocketData(), cmlabs::RESTParser::UnitTest(), and cmlabs::NetworkManager::UnitTestHTTP().

◆ HTTP_HEAD

#define HTTP_HEAD   4

HEAD.

Definition at line 95 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPRequest::processHeader().

◆ HTTP_INTERNAL_ERROR

#define HTTP_INTERNAL_ERROR   7

500 Internal Server Error (page generation)

Definition at line 640 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPReply::processHeader(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_MALFORMED_URL

#define HTTP_MALFORMED_URL   3

400 Bad Request

Definition at line 636 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_MOVED_PERMANENTLY

#define HTTP_MOVED_PERMANENTLY   1

301 Moved Permanently

Definition at line 634 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPReply::processHeader(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_NOT_IMPLEMENTED

#define HTTP_NOT_IMPLEMENTED   8

501 Not Implemented

Definition at line 641 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkManager::makeHTTPRequest(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_OK

#define HTTP_OK   0

200 OK

Definition at line 633 of file NetworkProtocols.h.

Referenced by cmlabs::RequestGateway::callInternalAPI(), cmlabs::HTTPReply::createFromFile(), cmlabs::HTTPReply::processHeader(), cmlabs::HTTPTestServer::receiveHTTPRequest(), cmlabs::RequestGateway::replyToClient(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_OPTIONS

#define HTTP_OPTIONS   6

OPTIONS.

Definition at line 97 of file NetworkProtocols.h.

Referenced by cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), and cmlabs::HTTPRequest::processHeader().

◆ HTTP_POST

#define HTTP_POST   3

POST.

Definition at line 94 of file NetworkProtocols.h.

Referenced by cmlabs::RESTHTTPCall::init(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkProtocols_UnitTest(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::HTTPRequest::processHeader(), cmlabs::RequestGateway::receiveWebsocketData(), cmlabs::TestWebRequestClient::run(), and cmlabs::RequestClient::TestServerLogin().

◆ HTTP_PUT

#define HTTP_PUT   2

PUT.

Definition at line 93 of file NetworkProtocols.h.

Referenced by cmlabs::RESTHTTPCall::init(), cmlabs::RESTParser::parseRequest(), cmlabs::RESTParser::parseRequest(), cmlabs::HTTPRequest::processHeader(), and cmlabs::RequestGateway::receiveWebsocketData().

◆ HTTP_SERVER_MALFORMED_REPLY

#define HTTP_SERVER_MALFORMED_REPLY   13

500 (malformed backend reply)

Definition at line 646 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPServerTest(), cmlabs::HTTPProtocol::ReceiveHTTPReply(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_SERVER_NOREPLY

#define HTTP_SERVER_NOREPLY   12

500 (no reply from backend server)

Definition at line 645 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPServerTest(), cmlabs::HTTPProtocol::ReceiveHTTPReply(), cmlabs::RequestGateway::replyToClient(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_SERVER_UNAVAILABLE

#define HTTP_SERVER_UNAVAILABLE   11

500 (backend server unavailable)

Definition at line 644 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPServerTest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::TestWebRequestClient::run(), and cmlabs::NetworkChannel::sendReceiveHTTPRequest().

◆ HTTP_SERVICE_NOT_AVAILABLE

#define HTTP_SERVICE_NOT_AVAILABLE   9

503 Service Unavailable

Definition at line 642 of file NetworkProtocols.h.

Referenced by cmlabs::RequestGateway::callInternalAPI(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_SWITCH_PROTOCOL

#define HTTP_SWITCH_PROTOCOL   14

101 Switching Protocols (WebSocket upgrade)

Definition at line 647 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkChannel::createWebsocketConnection(), cmlabs::HTTPReply::createWebsocketHTTPReply(), cmlabs::HTTPReply::isWebsocketUpgrade(), and cmlabs::HTTPReply::processHeader().

◆ HTTP_UNAUTHORIZED

#define HTTP_UNAUTHORIZED   4

401 Unauthorized (triggers Basic auth)

Definition at line 637 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPReply::createAuthorizationReply(), and cmlabs::TestWebRequestClient::run().

◆ HTTP_USE_LOCAL_COPY

#define HTTP_USE_LOCAL_COPY   2

304 Not Modified (use cached copy)

Definition at line 635 of file NetworkProtocols.h.

Referenced by cmlabs::HTTPReply::createFromFile(), cmlabs::HTTPReply::processHeader(), and cmlabs::TestWebRequestClient::run().

◆ PROTOCOL_3GCAM

#define PROTOCOL_3GCAM   16

Legacy 3G camera streaming protocol.

Definition at line 78 of file NetworkProtocols.h.

◆ PROTOCOL_HTTP_CLIENT

#define PROTOCOL_HTTP_CLIENT   2

Speak HTTP as a client: send requests, parse replies.

Definition at line 75 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkChannel::ConnectionAutodetectRun(), cmlabs::NetworkChannel::createWebsocketConnection(), cmlabs::HTTPClientProtocol::HTTPClientProtocol(), cmlabs::HTTPServerTest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkManager::makeHTTPRequest(), cmlabs::NetworkChannel::startConnection(), cmlabs::NetworkManager::TestHTTP(), cmlabs::NetworkManager::UnitTestHTTP(), and cmlabs::NetworkManager::WebsocketTest().

◆ PROTOCOL_HTTP_SERVER

#define PROTOCOL_HTTP_SERVER   1

Serve HTTP: parse requests, send replies (server role).

Definition at line 74 of file NetworkProtocols.h.

Referenced by cmlabs::RequestGateway::addPort(), cmlabs::NetworkChannel::ConnectionAutodetectRun(), cmlabs::HTTPProtocol::HTTPProtocol(), cmlabs::NetworkChannel::startConnection(), cmlabs::NetworkManager::UnitTestHTTP(), and cmlabs::NetworkManager::WebsocketTest().

◆ PROTOCOL_MESSAGE

#define PROTOCOL_MESSAGE   4

CMSDK binary DataMessage protocol (size-prefixed frames).

Definition at line 76 of file NetworkProtocols.h.

Referenced by cmlabs::RequestClient::addGateway(), cmlabs::RequestExecutor::addGateway(), cmlabs::RequestGateway::addPort(), cmlabs::NetworkChannel::ConnectionAutodetectRun(), cmlabs::MessageProtocol::MessageProtocol(), cmlabs::NetworkChannel::startConnection(), cmlabs::Test_RequestClient(), cmlabs::NetworkManager::UnitTest(), and cmlabs::NetworkManager::UnitTestDelayedConnect().

◆ PROTOCOL_TELNET

#define PROTOCOL_TELNET   8

Line-based Telnet-style text protocol.

Definition at line 77 of file NetworkProtocols.h.

Referenced by cmlabs::NetworkChannel::ConnectionAutodetectRun(), cmlabs::NetworkChannel::startConnection(), and cmlabs::TelnetProtocol::TelnetProtocol().

◆ TELNET_UNIX

#define TELNET_UNIX   2

LF (\n) line endings.

Definition at line 582 of file NetworkProtocols.h.

Referenced by cmlabs::TelnetProtocol::ReceiveTelnetLine(), and cmlabs::TelnetLine::setCR().

◆ TELNET_WINDOWS

#define TELNET_WINDOWS   1

CRLF (\r\n) line endings.

Definition at line 581 of file NetworkProtocols.h.

Referenced by cmlabs::TelnetProtocol::ReceiveTelnetLine(), and cmlabs::TelnetLine::setCR().