WebSocketHandler::WebSocketHandler Class Reference

the main web socket handler class More...

Inheritance diagram for WebSocketHandler::WebSocketHandler:
[legend]

## Public Member Functions

| 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
*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

## 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

## 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

## 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
| ) |  |

virtual

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 (ie `"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"`

Implements HttpServer::AbstractHttpSocketHandler.

## 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