WebSocketHandler::WebSocketHandler Class Reference

the main web socket handler class More...

Inheritance diagram for WebSocketHandler::WebSocketHandler:

Public Member Functions
	constructor (*HttpServer::AbstractAuthenticator auth, *hash< auto > opts)
	create the object optionally with the given AbstractAuthenticator
	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.
*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
string	getHeartbeatMessage ()
	returns the heartbeat message as a string
date	getSendTimeout ()
	Returns the send timeout value as a relative date/time value.
hash< auto >	handleRequest (hash< auto > cx, hash< auto > hdr, *data b)
	called by the HTTP server to handle incoming HTTP requests
	logDebug (string fmt,...)
	Log to the logger.
	logError (string fmt,...)
	Log to the logger.
	logInfo (string fmt,...)
	Log to the logger.
	logWarn (string fmt,...)
	Log to the logger.
	sendAll (data d)
	sends a message to all connected clients
	sendOne (softstring id, data d)
	sends a message to the given connection ID
	setHeartbeat (softint seconds)
	sets the heartbeat interval as a number of seconds
	setHeartbeatMessage (string msg)
	sets the heartbeat message
	setSendTimeout (date to)
	Set the send timeout with a non-negative relative date/time value.
	setSendTimeout (int ms)
	Set the send timeout with a non-negative value in milliseconds.
bool	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
	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

Protected Member Functions
RWLock	rwl ()
	connection read-write lock

Protected Attributes
hash< string, WebSocketConnection >	ch
	connection hash
softint	heartbeat = DefaultHeartbeatInterval
	heartbeat interval in seconds
string	heartbeat_msg = DefaultHeartbeatMsg
	heartbeat message
date	send_timeout = DefaultSocketSendTimeout
	Send timeout.

Private 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 logger: a Logger object to use for logging (default: no logging) send_timeout: a relative date/time value giving the timeout to use for sending data on the socket (default: 30s); if an integer is sent here, it is assumed to represent a value in milliseconds

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

getSendTimeout()

date WebSocketHandler::WebSocketHandler::getSendTimeout

(

)

Returns the send timeout value as a relative date/time value.

Returns

the send timeout value as a relative date/time value

Since

WebSocketHandler 2.1

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

Parameters

d	the data to send

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

setSendTimeout() [1/2]

WebSocketHandler::WebSocketHandler::setSendTimeout

(

date

to

)

Set the send timeout with a non-negative relative date/time value.

Parameters

the	send timeout value as a relative date/time value

Since

WebSocketHandler 2.1

setSendTimeout() [2/2]

WebSocketHandler::WebSocketHandler::setSendTimeout

(

int

ms

)

Set the send timeout with a non-negative value in milliseconds.

Parameters

the	send timeout as a non-negative value in milliseconds

Since

WebSocketHandler 2.1

startImpl()

bool 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