| Version: | 1.4.4 |
| Title: | 'WebSocket' Client Library |
| Description: | Provides a 'WebSocket' client interface for R. 'WebSocket' is a protocol for low-overhead real-time communication:https://en.wikipedia.org/wiki/WebSocket. |
| License: | GPL-2 |
| Encoding: | UTF-8 |
| ByteCompile: | true |
| Imports: | R6, later (≥ 1.2.0) |
| LinkingTo: | cpp11, AsioHeaders, later |
| BugReports: | https://github.com/rstudio/websocket/issues |
| SystemRequirements: | GNU make, OpenSSL >= 1.0.2 |
| RoxygenNote: | 7.3.2 |
| Suggests: | httpuv, testthat, knitr, rmarkdown |
| VignetteBuilder: | knitr |
| NeedsCompilation: | yes |
| Packaged: | 2025-04-09 10:46:21 UTC; cg334 |
| Author: | Winston Chang [aut, cre], Joe Cheng [aut], Alan Dipert [aut], Barbara Borges [aut], Posit, PBC [cph], Peter Thorson [ctb, cph] (WebSocket++ library), René Nyffenegger [ctb, cph] (Base 64 library), Micael Hildenborg [ctb, cph] (SHA1 library), Aladdin Enterprises [cph] (MD5 library), Bjoern Hoehrmann [ctb, cph] (UTF8 Validation library) |
| Maintainer: | Winston Chang <winston@posit.co> |
| Repository: | CRAN |
| Date/Publication: | 2025-04-10 09:00:02 UTC |
Create a WebSocket client
Description
WebSocket$new(url, protocols = character(0), headers = NULL, autoConnect = TRUE, accessLogChannels = c("none"), errorLogChannels = NULL, maxMessageSize = 32 * 1024 * 1024)Arguments
url | The WebSocket URL. Should begin with |
protocols | Zero or more WebSocket sub-protocol names to offer to the serverduring the opening handshake. |
headers | A named list or character vector representing keys and valuesof headers in the initial HTTP request. |
autoConnect | If set to 'FALSE', then constructing the WebSocket objectwill not automatically cause the connection to be established. This can beused if control will return to R before event handlers can be set on theWebSocket object (i.e. you are constructing a WebSocket object manually atan interactive R console); after you are done attaching event handlers, youmust call 'ws$connect()' to establish the WebSocket connection. |
accessLogChannels | A character vector of access log channels that areenabled. Defaults to A few commonly used access logging values are:
All logging levels are explained in more detail athttps://docs.websocketpp.org/reference_8logging.html. |
errorLogChannels | A character vector of error log channels that aredisplayed. The default value is A few commonly used error logging values are:
All logging levels are explained in more detail athttps://docs.websocketpp.org/reference_8logging.html. |
maxMessageSize | The maximum size of a message in bytes. If a messagelarger than this is sent, the connection will fail with the |
Details
A WebSocket object has four events you can listen for, by calling thecorresponding 'onXXX' method and passing it a callback function. All callbackfunctions must take a single 'event' argument. The 'event' argument is anamed list that always contains a 'target' element that is the WebSocketobject that originated the event, plus any other relevant data as detailedbelow.
onMessageCalled each time a message is received from theserver. The event will have a 'data' element, which is the messagecontent. If the message is text, the 'data' will be a one-elementcharacter vector; if the message is binary, it will be a raw vector.
onOpenCalled when the connection is established.
onCloseCalled when a previously-opened connection is closed.The event will have 'code' (integer) and 'reason' (one-element character)elements that describe the remote's reason for closing.
onErrorCalled when the connection fails to be established.The event will have an 'message' element, a character vector of length 1describing the reason for the error.
Each 'onXXX' method can be called multiple times to register multiplecallbacks. Each time an 'onXXX' is called, its (invisible) return value is afunction that can be invoked to cancel that particular registration.
A WebSocket object also has the following methods:
connect()Initiates the connection to the server. (This doesnot need to be called unless you have passed 'autoConnect=FALSE' to theconstructor.)
send(msg)Sends a message to the server.
close()Closes the connection.
readyState()Returns an integer representing the state of theconnection.
0L: ConnectingThe WebSocket has not yet established aconnection with the server.
1L: OpenThe WebSocket has connected and can send andreceive messages.
2L: ClosingThe WebSocket is in the process of closing.
3L: ClosedThe WebSocket has closed, or failed to open.
- setAccessLogChannels(channels)
Enable the websocket Access channels after thewebsocket's creation. A value of
NULLwill not enable any new Access channels.- setErrorLogChannels(channels)
Enable the websocket Error channels after thewebsocket's creation. A value of
NULLwill not enable any new Error channels.- clearAccessLogChannels(channels)
Disable the websocket Access channels after thewebsocket's creation. A value of
NULLwill not clear any existing Access channels.- clearErrorLogChannels(channels)
Disable the websocket Error channels after thewebsocket's creation. A value of
NULLwill not clear any existing Error channels.
Examples
## Only run this example in interactive R sessionsif (interactive()) {# Create a websocket using the websocket.org test serverws <- WebSocket$new("ws://echo.websocket.org/")ws$onMessage(function(event) { cat("Client got msg:", event$data, "\n")})ws$onClose(function(event) { cat("Client disconnected\n")})ws$onOpen(function(event) { cat("Client connected\n")})# Try sending a message with ws$send("hello").# Close the websocket with ws$close() after you're done with it.}