Class WebSocketClient

Inheritance

object

WebSocketClient

Namespace: Xrpl.Client

Assembly: Xrpl.dll

Syntax

public class WebSocketClient

Constructors

WebSocketClient(string, IReadOnlyDictionary<string, string>?)

Declaration

protected WebSocketClient(string uri, IReadOnlyDictionary<string, string>? handshakeHeaders = null)

Parameters

Type	Name	Description
string	uri
IReadOnlyDictionary<string, string>	handshakeHeaders

Fields

IsDisposed

Declaration

public bool IsDisposed

Field Value

Type	Description
bool

Properties

FailureReason

Declaration

public SocketFailureReason FailureReason { get; }

Property Value

Type	Description
SocketFailureReason

State

Get the current state of the WebSocket client.

Declaration

public WebSocketState State { get; }

Property Value

Type	Description
WebSocketState

Methods

Cancel()

Cancel work without setting intentional disconnect flag. Use CancelIntentionally() for user-initiated cancellations.

Declaration

public void Cancel()

CancelIntentionally()

Cancel work as an intentional disconnect. Sets the intentional disconnect flag before cancelling. Use this for user-initiated disconnects.

Declaration

public void CancelIntentionally()

Connect()

Connects to the WebSocket server.

Declaration

public Task<WebSocketClient> Connect()

Returns

Type	Description
Task<WebSocketClient>	Self

Create(string, IReadOnlyDictionary<string, string>?)

Creates a new instance.

Declaration

public static WebSocketClient Create(string uri, IReadOnlyDictionary<string, string>? handshakeHeaders = null)

Parameters

Type	Name	Description
string	uri	The URI of the WebSocket server.
IReadOnlyDictionary<string, string>	handshakeHeaders	Optional HTTP headers to put on the upgrade handshake (e.g. Authorization). Ignored under WebAssembly — the browser WebSocket API cannot set request headers.

Returns

Type	Description
WebSocketClient	Instance of the created WebSocketWrapper

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

ResetIntentionalDisconnect()

Resets the intentional disconnect flag to false. Called after successful connection to enable error detection.

Declaration

public void ResetIntentionalDisconnect()

SendMessage(string)

Sends a UTF-8 string to the WebSocket server, fire-and-forget.

Declaration

public void SendMessage(string message)

Parameters

Type	Name	Description
string	message	The message to send

Remarks

A failure is reported through the error callback and nowhere else - this is the keepalive's entry point, and a consumer's, and neither has a request to reject. A caller that does have one uses SendMessageAsync(byte[]) and observes the task. Neither entry point ever reconnects: a send on a socket that is not open fails, it does not call Connect(). It used to - ConnectAsync on an already used System.Net.WebSockets.ClientWebSocket throws, the catch disposed the socket and raised OnConnectionError, and the send went ahead regardless.

SendMessageAsync(byte[])

Sends a byte array to the WebSocket server. The returned task faults if the message could not be written, so the owner of a request can reject it instead of leaving it to its timeout.

Declaration

public Task SendMessageAsync(byte[] message)

Parameters

Type	Name	Description
byte[]	message	The data to send

Returns

Type	Description
Task

Remarks

The write is issued synchronously when the send lock is free: everything up to the first incomplete await of System.Net.WebSockets.ClientWebSocket.SendAsync(System.ArraySegment<byte>, System.Net.WebSockets.WebSocketMessageType, bool, System.Threading.CancellationToken) runs on the caller's thread. Connection relies on that - it starts the send under the lock its retirement paths take, so a retirement either finds the request not yet sent, or already handed to the socket.

A send that queued behind another one re-checks the socket once it holds the lock: the retirement marks the socket before it lets go of it, and that mark is what refuses a message that would otherwise reach a server the client has left. Between that check and the write there is no lock - a few instructions - and that is the residue this method does not close.

Exceptions

Type	Condition
InvalidOperationException	The socket is not open.

SetIntentionalDisconnect()

Sets the intentional disconnect flag to true without cancelling. Use this before Cancel() if you need to set the flag earlier.

Declaration

public void SetIntentionalDisconnect()