the main web socket handler class
More...
|
| | 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
|
| |
| 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
|
| |
| 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
|
| |
|
|
const | DefaultHeartbeatInterval = 20s |
| | default heartbeat interval
|
| |
|
const | DefaultHeartbeatMsg = "heartbeat" |
| | default heartbeat message
|
| |
|
const | DefaultSocketSendTimeout = 30s |
| | default socket send timeout
|
| |
|
const | Options = ... |
| | known constructor options
|
| |
|
|
RWLock | rwl () |
| | connection read-write lock
|
| |
|
|
string | tlk = get_random_string(50) |
| | Thread-local key for I/O check.
|
| |
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:
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.
◆ 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()
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
- Parameters
-
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()
| 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 |