WebSocketHandler::WebSocketHandler Class Reference

the main web socket handler class More...

#include <WebSocketHandler.qm.dox.h>

Inheritance diagram for WebSocketHandler::WebSocketHandler:

Public Member Methods
	constructor (*HttpServer::AbstractAuthenticator auth, *hash< auto > opts)
	create the object optionally with the given AbstractAuthenticator More...
	deregisterConnectionImpl (WebSocketConnection wsc)
	called when the connection terminates; the default implementation does nothing
WebSocketConnection	doNewConnection (hash< auto > cx, hash< auto > hdr, string cid)
	called when a connection is established; registers the new connection internally
bool	flushIo (WebSocketConnection wsc, Socket sock)
	Flushes I/O in the connection queue. More...
*list< string >	getConnectionIds ()
	get list of socket connection ids
WebSocketConnection	getConnectionImpl (hash< auto > cx, hash< auto > hdr, string cid)
	called when a connection is established; the default implementation creates a WebSocketConnection object
int	getHeartbeat ()
	returns the connection heartbeat interval as a number of seconds More...
string	getHeartbeatMessage ()
	returns the heartbeat message as a string More...
hash< auto >	handleRequest (hash< auto > cx, hash< auto > hdr, *data b)
	called by the HTTP server to handle incoming HTTP requests More...
	logDebug (string fmt)
	default implementation is empty
	logError (string fmt)
	default implementation is empty
	logInfo (string fmt)
	default implementation is empty
	sendAll (data d)
	sends a message to all connected clients More...
	sendOne (softstring id, data d)
	sends a message to the given connection ID More...
	setHeartbeat (softint seconds)
	sets the heartbeat interval as a number of seconds More...
	setHeartbeatMessage (string msg)
	sets the heartbeat message More...
	startImpl (softstring lid, hash< auto > cx, hash< auto > hdr, Qore::Socket sock)
	called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...
	stopOne (softstring id)
	stop given connection ID

Public Attributes
const	DefaultHeartbeatInterval = 20s
	default heartbeat interval
const	DefaultHeartbeatMsg = "heartbeat"
	default heartbeat message
const	DefaultSocketSendTimeout = 30s
	default socket send timeout
const	Options = ...
	known constructor options

Private Member Methods
RWLock	rwl ()
	connection read-write lock

Private Attributes
hash< string, WebSocketConnection >	ch
	connection hash
softint	heartbeat = DefaultHeartbeatInterval
	heartbeat interval in seconds
string	heartbeat_msg = DefaultHeartbeatMsg
	heartbeat message

Private:Internal Attributes
string	tlk = get_random_string(50)
	Thread-local key for I/O check.

Detailed Description

the main web socket handler class

connections are represented by object descended from WebSocketConnection. WebSocketHandler::WebSocketHandler::getConnectionImpl() returns a suitable object for each connection, this method can be overridden in subclasses to return a custom object for each connection if required.

Receiving WebSocket Messages from Clients

When the WebSocketHandler class receives a message from the client, the WebSocketHandler class calls the WebSocketConnection::gotMessage() on the object that represents that connection.

Sending WebSocket Message to Clients

To send a message to a websocket client, call one of the following methods:

• WebSocketHandler::sendOne(): send a message to single connection given its connection ID
• WebSocketHandler::sendAll(): send a message to all connected clients

Websocket connections are identified by their HTTP connection ID as passed in WebSocketHandler::handleRequest() in the "cx.id" argument when the connection is first established.

Member Function Documentation

constructor()

WebSocketHandler::WebSocketHandler::constructor	(	*HttpServer::AbstractAuthenticator	auth,
		*hash< auto >	opts
	)

create the object optionally with the given AbstractAuthenticator

Parameters

auth	the authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
opts	options for the object with the following optional keys: heartbeat: a positive integer value giving seconds for the heartbeat interval for the server connection (default: 20 seconds) heartbeat_msg: a string giving the payload to send in heartbeat messages (default: "heartbeat"); may be an empty string meaning no message

Exceptions

WEBSOCKETHANDLER-OPTION-ERROR

unknown or invalid option

flushIo()

bool WebSocketHandler::WebSocketHandler::flushIo	(	WebSocketConnection	wsc,
		Socket	sock
	)

Flushes I/O in the connection queue.

Returns

True if any data was flushed, False if not

getHeartbeat()

int WebSocketHandler::WebSocketHandler::getHeartbeat

(

)

returns the connection heartbeat interval as a number of seconds

Returns

the connection heartbeat interval as a number of seconds

Since

WebSocketHandler 1.4.2

getHeartbeatMessage()

string WebSocketHandler::WebSocketHandler::getHeartbeatMessage

(

)

returns the heartbeat message as a string

Returns

the heartbeat message as a string; an empty string means no message

Since

WebSocketHandler 1.4.2

handleRequest()

hash< auto > WebSocketHandler::WebSocketHandler::handleRequest	(	hash< auto >	cx,
		hash< auto >	hdr,
		*data	b
	)

called by the HTTP server to handle incoming HTTP requests

To accept a dedicated connection; make sure the return value hash's "code" key is 101 (i.e. "Switching Protocols") and the "close" key is not False

Parameters

cx	call context hash; this hash will have the following keys: socket: the bind address used to bind the listener ("socket-info" provides more detailed information) socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) url: a hash of broken-down URL information (as returned from parseURL()) id: the unique HTTP connection ID; this ID is also used to identify the websocket client connection in WebSocketHandler::sendOne() listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo() ) user: the current RBAC username (if any)
hdr	incoming header hash; all keys will be converted to lower-case, additionally the following keys will be present: method: the HTTP method received (ie "GET", "POST", etc) path: the HTTP path given in the request, after processing by decode_url() (Qore function) http_version: the HTTP version number in the request (either "1.0" or "1.1")
b	message body, if any

Returns

a hash representing the response to the client as follows; to accept a dedicated connection; make sure the "code" is 101 (ie "Switching Protocols") and the "close" key is not False:

• "code": the HTTP return code (see HttpServer::HttpCodes) (101 "Switching Protocols" to accept the dedicated connection, in which case the start() method will be called)
• "body": the message body to return in the response
• "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
• "hdr": (optional) set this key to a hash of extra header information to be returned with the response

Websocket connections are identified by their HTTP connection ID as passed in "cx.id"

sendAll()

WebSocketHandler::WebSocketHandler::sendAll

(

data

d

)

sends a message to all connected clients

Messages are automatically encoded with WebSocketUtil::ws_encode_message() before sending.

sendOne()

WebSocketHandler::WebSocketHandler::sendOne	(	softstring	id,
		data	d
	)

sends a message to the given connection ID

Websocket connections are identified by their HTTP connection ID as passed in WebSocketHandler::handleRequest() in the "cx.id" argument when the connection is first established.

Messages are automatically encoded with WebSocketUtil::ws_encode_message() before sending.

setHeartbeat()

WebSocketHandler::WebSocketHandler::setHeartbeat

(

softint

seconds

)

sets the heartbeat interval as a number of seconds

Parameters

seconds

the heartbeat interval as a number of seconds

Since

WebSocketHandler 1.4.2

setHeartbeatMessage()

WebSocketHandler::WebSocketHandler::setHeartbeatMessage

(

string

msg

)

sets the heartbeat message

Parameters

msg	the string payload to send with heartbeat messages; an empty string means no message

Since

WebSocketHandler 1.4.2

startImpl()

WebSocketHandler::WebSocketHandler::startImpl	(	softstring	lid,
		hash< auto >	cx,
		hash< auto >	hdr,
		Qore::Socket	sock
	)

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() method is called

Parameters

lid	the unique HTTP listener ID
cx	call context hash; this hash will have the following keys: socket: the bind address used to bind the listener ("socket-info" provides more detailed information) socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) url: a hash of broken-down URL information (as returned from parseURL()) id: the unique HTTP connection ID listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo()) user: the current RBAC username (if any)
hdr	a hash of headers in the request
sock	the Socket object for the dedicated connection to the client