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 |