Qore WebSocketHandler Module Reference: WebSocketHandler::WebSocketHandler Class Reference

Qore WebSocketHandler Module Reference 1.0

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | List of all members
WebSocketHandler::WebSocketHandler Class Reference

the main web socket handler class More...

Inheritance diagram for WebSocketHandler::WebSocketHandler:
[legend]

## Public Member Functions
| constructor (*HttpServer::AbstractAuthenticator auth)
| create the object optionally with the given AbstractAuthenticator More...
| deregisterConnectionImpl (WebSocketConnection wsc)
| called when the connection terminates; the default implementation does nothing
WebSocketConnection | getConnectionImpl (hash cx, hash hdr, string cid)
| called when a connection is established; the default implementation creates a WebSocketConnection object
hash | handleRequest (hash cx, hash 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 (string id, data d)
| sends a message to the given connection ID More...
| startImpl (softstring lid, hash cx, hash hdr, Qore::Socket sock)
| called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...

## Private Member Functions
RWLock | rwl ()
| connection read-write lock

## Private Attributes
hash | ch
| connection hash

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

WebSocketHandler::WebSocketHandler::constructor | ( | *HttpServer::AbstractAuthenticator | auth | ) |

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

hash WebSocketHandler::WebSocketHandler::handleRequest | ( | hash | cx,
|  | hash | 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::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.

WebSocketHandler::WebSocketHandler::sendAll | ( | data | d | ) |

sends a message to all connected clients

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

WebSocketHandler::WebSocketHandler::sendOne | ( | string | 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.

WebSocketHandler::WebSocketHandler::startImpl | ( | softstring | lid,
|  | hash | cx,
|  | hash | 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