All Classes Namespaces Functions Variables Groups Pages
DebugHandler::WebSocketDebugHandler Class Reference

the main web socket debug handler class More...

Inheritance diagram for DebugHandler::WebSocketDebugHandler:
[legend]

## Public Member Functions

| constructor (*HttpServer::AbstractAuthenticator auth, WebSocketDebugProgramControl dpc, *list args)
| create the object optionally with the given AbstractAuthenticator More...
WebSocketHandler::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...

## Detailed Description

the main web socket debug handler class

connections are represented by an 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

DebugHandler::WebSocketDebugHandler::constructor | ( | *HttpServer::AbstractAuthenticator | auth,
|  | WebSocketDebugProgramControl | dpc,
|  | *list | args
| ) |  |

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
  dpc | the debug program controller object
  args | an optional list of arguments for the setLogger() method

hash DebugHandler::WebSocketDebugHandler::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::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; this class returns the Qore websocket debug protocol version in the header `"QoreDebugWsProtocol"`

Websocket connections are identified by their HTTP connection ID as passed in `"cx.id"`

Reimplemented from WebSocketHandler::WebSocketHandler.