ws-client/client
ws-connect
(ws-connect [uri : cstr] :)
open a WebSocket connection to uri with verified TLS.
| uri | a ws:// or wss:// URI string (e.g. "ws://localhost:9000/feed"). |
A WsConn handle on success; a null handle on failure (test with ws-conn-null?, then read ws-last-error). wss:// requires the spice to have been built with mbedTLS available.
(let [c (ws-connect "wss://example.com/feed")]
(when (not (ws-conn-null? c)) (ws-send c "hi") (ws-free c)))
Since: WC1 (verified-by-default since TLS-V0)
ws-connect-with-ca
(ws-connect-with-ca [uri : cstr ca-path : cstr] :)
open a wss:// connection verifying against a custom
| uri | a ws:// or wss:// URI string. | |
| ca-path | filesystem path to a CA certificate bundle. |
A WsConn handle on success; a null handle on failure (test with ws-conn-null?, then read ws-last-error -- e.g. the bundle failed to load).
(ws-connect-with-ca "wss://localhost:8443/socket" "/path/to/dev-ca.pem")
Since: TLS-V0
ws-connect-insecure
(ws-connect-insecure [uri : cstr] :)
open a wss:// connection WITHOUT verifying the
| uri | a ws:// or wss:// URI string. |
A WsConn handle on success; a null handle on failure (test with ws-conn-null?, then read ws-last-error).
Since: TLS-V0
ws-connect-with-subprotocols
(ws-connect-with-subprotocols [uri : cstr offered : cstr] :)
open a verified WebSocket connection that
| uri | a ws:// or wss:// URI string. | |
| offered | comma-separated subprotocol list (RFC 6455 1.9 token list). |
A WsConn handle on success; null on failure (read ws-last-error). TLS uses the system CA store, exactly like ws-connect.
(let [c (ws-connect-with-subprotocols "wss://api.example.com/feed"
"json.v1, msgpack.v1")]
(when (not (ws-conn-null? c))
(println (ws-subprotocol c)))) ; e.g. "json.v1"
Since: SUB-V0
ws-subprotocol
(ws-subprotocol [conn : WsConn] :)
the application subprotocol the server selected during the
Since: SUB-V0
ws-conn-null?
(ws-conn-null? [conn : WsConn] :)
true if `conn` is the failure sentinel from ws-connect.
Since: WC1
ws-last-error
(ws-last-error :)
human-readable reason for the most recent failure.
Since: WC1
ws-send
(ws-send [conn : WsConn msg : cstr] :)
send a UTF-8 text frame.
| conn | WsConn handle. | |
| msg | null-terminated UTF-8 string. |
Number of bytes handed to the transport, or negative on error.
Since: WC1
ws-send-bytes
(ws-send-bytes [conn : WsConn ptr ptr<void> len : int] :)
send a binary frame.
| conn | WsConn handle. | |
| ptr | pointer to the payload buffer. | |
| len | byte length of the payload. |
Number of bytes handed to the transport, or negative on error.
Since: WC1
ws-send-fragmented
(ws-send-fragmented [conn : WsConn ptr ptr<void> len : int frame-size : int] :)
send a binary message split across multiple frames
| conn | WsConn handle. | |
| ptr | payload buffer. | |
| len | byte length of the payload. | |
| frame-size | max bytes per outbound frame (a value <= 0 sends one frame). |
Total bytes handed to the transport, or negative on error.
(ws-send-fragmented c big-buf 1048576 16384) ; 1 MiB across 16 KiB frames
Since: FRAG-V0
ws-recv
(ws-recv [conn : WsConn] :)
receive the next WebSocket message.
| conn | WsConn handle. |
A WsFrame handle (a view valid until the next ws-recv / ws-free). Its kind is :text / :binary / :ping / :pong / :close / :timeout / :error.
Since: WC1
ws-close
(ws-close [conn : WsConn] :)
initiate the WebSocket closing handshake.
Since: WC1
ws-free
(ws-free [conn : WsConn] :)
unconditionally release all resources for conn.
Since: WC1
ws-set-timeout
(ws-set-timeout [conn : WsConn ms : int] :)
set the receive timeout in milliseconds.
| conn | WsConn handle. | |
| ms | timeout in milliseconds. |
Since: WC3
Internal definitions
ws-connect-impl-- internal core driving every connect entry point.