the main websocket client class
More...
|
|
int | cid = -1 |
| | unique websocket connection ID; -1 when not connected
|
| |
|
string | url |
| | URL string.
|
| |
|
*code | yield |
| | callable object to yield the current thread's execution
|
| |
the main websocket client class
To use this class, create a WebSocketClient object and the call WebSocketClient::connect().
The WebSocketClient::connect() method starts a background thread to receive messages, which are then posted to the callback provided in the WebSocketClient::constructor().
To stop listening for web socket events, call WebSocketClient::disconnect().
The WebSocketClient class includes support for running in sandboxed Program objects with the following parse options set:
◆ clearStats()
| WebSocketClient::WebSocketClient::clearStats |
( |
| ) |
|
Clears performance statistics.
- Example:
- Since
- WebSocketClient 1.1
- See also
- WebSocketClient::getUsageInfo()
◆ clearWarningQueue()
| nothing WebSocketClient::WebSocketClient::clearWarningQueue |
( |
| ) |
|
Removes any warning Queue object from the Socket.
- Example:
- See also
- WebSocketClient::setWarningQueue()
- Since
- WebSocketClient 1.1
◆ connect()
| hash WebSocketClient::WebSocketClient::connect |
( |
*hash |
opts, |
|
|
*reference< hash > |
info |
|
) |
| |
connects to the websocket server
- Example:
sub event(*data msg) {
if (!msg)
printf(
"connection closed\n");
else
printf(
"%s msg: %y\n",
now_us().format(
"YYYY-MM-DD HH:mm:SS.xx"), msg);
}
WebSocketClient ws(("url": "ws://example.com:8080/path", "callback": \event()));
ws.connect();
This method starts a background thread to receive messages, which are then posted to the callback closure or call reference given as an argument. If the server disconnects the web socket connection, the callback will be called with no argument (ie NOTHING). In this case the event thread also terminates and the WebSocketClient object will be in a disconnected state.
To stop listening for web socket events, call WebSocketClient::disconnect().
If this method is called while a connection is already in progress, then the existing connection is first implicitly disconnected with close code WSCC_GoingAway.
- Parameters
-
| opts | a hash with the following keys:
hdr: (optional) a hash giving header values for the connection request to the web socket server
|
| info | a reference to a hash which will be set to information about the call setup |
- Returns
- a hash with information about the HTTP response from the webn socket server corresponding to the return value of Qore::Socket::readHTTPHeader()
- Exceptions
-
| WEBSOCKET-ERROR | the option hash is missing either the 'url' or 'callback' keys or type error in the option hash |
◆ constructor()
| WebSocketClient::WebSocketClient::constructor |
( |
code |
cb, |
|
|
hash |
opts |
|
) |
| |
creates the object and optionally sets logging targets
- Example:
sub event(*data msg) {
if (!msg)
printf(
"connection closed\n");
else
printf(
"%s msg: %y\n",
now_us().format(
"YYYY-MM-DD HH:mm:SS.xx"), msg);
}
WebSocketClient ws(\event(), ("url": "ws://example.com:8080/path"));
- Parameters
-
- Exceptions
-
| WEBSOCKET-ERROR | unknown scheme, missing 'url' key in option hash; invalid option value |
- Since
- WebSocketClient 1.6 added the
yield option
◆ getUsageInfo()
| hash WebSocketClient::WebSocketClient::getUsageInfo |
( |
| ) |
|
Returns performance statistics for the socket.
- Example:
hash h = ws.getUsageInfo();
- Returns
- a hash with the following keys:
"bytes_sent": an integer giving the total amount of bytes sent"bytes_recv": an integer giving the total amount of bytes received"us_sent": an integer giving the total number of microseconds spent sending data"us_recv": an integer giving the total number of microseconds spent receiving data"arg": (only if warning values have been set with WebSocketClient::setWarningQueue()) the optional argument for warning hashes"timeout": (only if warning values have been set with WebSocketClient::setWarningQueue()) the warning timeout in microseconds"min_throughput": (only if warning values have been set with WebSocketClient::setWarningQueue()) the minimum warning throughput in bytes/sec
- Since
- WebSocketClient 1.1
- See also
- WebSocketClient::clearStats()
◆ pong()
| WebSocketClient::WebSocketClient::pong |
( |
| ) |
|
Sends a PONG message to the server as a unidirectional keep-alive message.
- Since
- WebSocketClient 1.6.1
◆ send() [1/2]
| WebSocketClient::WebSocketClient::send |
( |
string |
str | ) |
|
Sends string data over the web socket with timeout specified in options; if any errors occur, an exception is thrown.
- Parameters
-
| str | Sends the string data over the socket |
- See also
- Socket::send()
◆ send() [2/2]
| WebSocketClient::WebSocketClient::send |
( |
binary |
bin | ) |
|
Sends binary data over the web socket with timeout specified in options; if any errors occur, an exception is thrown.
- Parameters
-
| bin | Sends the binary data over the socket |
- See also
- Socket::send()
◆ setWarningQueue()
| nothing WebSocketClient::WebSocketClient::setWarningQueue |
( |
int |
warning_ms, |
|
|
int |
warning_bs, |
|
|
Queue |
queue, |
|
|
auto |
arg, |
|
|
timeout |
min_ms = 1s |
|
) |
| |
Sets a Queue object to receive socket warnings.
- Example:
ws.setWarningQueue(5000, 5000, queue, "socket-1");
- Parameters
-
| warning_ms | the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
"type": a string with the constant value "SOCKET-OPERATION-WARNING" "operation": a string giving the operation that caused the warning (ex: "connect")"us": an integer giving the number of microseconds for the operation"timeout": an integer giving the warning threshold in microseconds"arg": if any "arg" argument is passed to the WebSocketClient::setWarningQueue() method, it will be included in the warning hash here
|
| warning_bs | value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
"type": a string with the constant value "SOCKET-THROUGHPUT-WARNING" "dir": either "send" or "recv" depending on the direction of the data flow"bytes": the amount of bytes sent"us": an integer giving the number of microseconds for the operation"bytes_sec": a float giving the transfer speed in bytes per second"threshold": an integer giving the warning threshold in bytes per second"arg": if any "arg" argument is passed to the WebSocketClient::setWarningQueue() method, it will be included in the warning hash here
|
| queue | the Queue object to receive warning events |
| arg | an optional argument to be placed in the "arg" key in each warning hash (could be used to identify the socket for example) |
| min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning |
- Exceptions
-
| QUEUE-ERROR | the Queue passed has a maximum size set |
| SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0 |
- See also
- WebSocketClient::clearWarningQueue()
- Since
- WebSocketClient 1.1
