Members on this page
ErrorOccurredFaultedNotificationReceivedSocketConnectedStateChangedGetDescriptorAsync(CancellationToken)GetInfoAsync(CancellationToken)SendHttpAsync(HttpMethod, string, ProtocolModel, bool, CancellationToken)SendHttpAsync<T>(HttpMethod, string, ProtocolModel, bool, CancellationToken)SendWebSocketAsync(string, ProtocolModel, CancellationToken)SendWebSocketAsync<T>(string, ProtocolModel, CancellationToken)AuthenticationStateConnectionStateLastErrorRelayIdSessionMode
Meshline.Sdk
Meshline.Transport
RelayClient Class
Sends HTTP and WebSocket protocol requests to one relay through an application-owned relay pool.
public sealed class RelayClient
Inheritance System.Object → RelayClient
Remarks
Obtain instances from RelayClientPool. The pool owns their lifetime. Events run on the raising thread. Reconnection restores transport availability but does not replay business requests; use protocol-specific recovery or synchronization to resolve interrupted work.
Properties
RelayClient.AuthenticationState Property
The current authentication state, including expiry evaluated when this property is read.
public Meshline.Transport.RelayAuthenticationState AuthenticationState { get; }
Property Value
RelayClient.ConnectionState Property
The observed communication state; HTTP state does not imply a continuously monitored connection.
public Meshline.Transport.RelayConnectionState ConnectionState { get; }
Property Value
RelayClient.LastError Property
The most recently recorded relay communication error, or null when none is recorded.
public System.Exception? LastError { get; }
Property Value
RelayClient.RelayId Property
The relay's lowercase Neo script hash, including the 0x prefix.
public string RelayId { get; }
Property Value
RelayClient.SessionMode Property
The mode bound after successful authentication, or null before authentication; the binding survives expiry.
public System.Nullable<Meshline.Models.Protocol.SessionMode> SessionMode { get; }
Property Value
Methods
RelayClient.GetDescriptorAsync(CancellationToken) Method
Retrieves and verifies the relay's descriptor, using the cached descriptor until refresh is needed.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.RelayDescriptor> GetDescriptorAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<RelayDescriptor>
The relay's verified, unexpired descriptor.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.InvalidOperationException
The registry does not identify an active relay with the requested identity.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.Security.Cryptography.CryptographicException
The relay public-key signature cannot be verified by the cryptographic provider.
RelayClient.GetInfoAsync(CancellationToken) Method
Retrieves the relay's public information and advertised limits.
public System.Threading.Tasks.Task<Meshline.Models.Protocol.RelayInfo> GetInfoAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<RelayInfo>
The relay's validated public information, including limits required by its capabilities.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.InvalidOperationException
The registry does not identify an active relay with the requested identity.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.Security.Cryptography.CryptographicException
The relay public-key signature cannot be verified by the cryptographic provider.
RelayClient.SendHttpAsync(HttpMethod, string, ProtocolModel, bool, CancellationToken) Method
Sends an HTTP protocol request to the relay and checks the response for relay and protocol errors.
public System.Threading.Tasks.Task SendHttpAsync(System.Net.Http.HttpMethod method, string name, Meshline.Models.Protocol.ProtocolModel? parameters=null, bool authenticated=true, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
method System.Net.Http.HttpMethod
The HTTP method required by the protocol operation.
name System.String
The protocol operation name, such as account.route.resolve.
parameters ProtocolModel
Optional named protocol parameters, serialized according to the transport operation.
authenticated System.Boolean
Whether to use the bound authenticated session; pass false for a public request.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.InvalidOperationException
The relay is not registered as active, or the authentication identity required by the request is unavailable or has changed.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.NotSupportedException
A requested response model or protocol value has no supported serializer.
System.ArgumentException
An HTTP GET parameter is null or is not a scalar JSON value.
System.Security.Cryptography.CryptographicException
The cryptographic provider or configured signer fails while verifying relay evidence or authenticating the request.
Remarks
The successful response must be HTTP 204 with no content.
RelayClient.SendHttpAsync<T>(HttpMethod, string, ProtocolModel, bool, CancellationToken) Method
Sends an HTTP protocol request to the relay and checks the response for relay and protocol errors.
public System.Threading.Tasks.Task<T> SendHttpAsync<T>(System.Net.Http.HttpMethod method, string name, Meshline.Models.Protocol.ProtocolModel? parameters=null, bool authenticated=true, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken))
where T : Meshline.Models.Protocol.ProtocolModel;
Type parameters
T
The protocol model type expected in the response.
Parameters
method System.Net.Http.HttpMethod
The HTTP method required by the protocol operation.
name System.String
The protocol operation name, such as account.route.resolve.
parameters ProtocolModel
Optional named protocol parameters, serialized according to the transport operation.
authenticated System.Boolean
Whether to use the bound authenticated session; pass false for a public request.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<T>
A task whose result is the deserialized response model after its protocol validation succeeds.
Exceptions
System.InvalidOperationException
The relay is not registered as active, or the authentication identity required by the request is unavailable or has changed.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.NotSupportedException
A requested response model or protocol value has no supported serializer.
System.ArgumentException
An HTTP GET parameter is null or is not a scalar JSON value.
System.Security.Cryptography.CryptographicException
The cryptographic provider or configured signer fails while verifying relay evidence or authenticating the request.
RelayClient.SendWebSocketAsync(string, ProtocolModel, CancellationToken) Method
Sends a JSON-RPC request through an authenticated WebSocket session and awaits its response.
public System.Threading.Tasks.Task SendWebSocketAsync(string method, Meshline.Models.Protocol.ProtocolModel? parameters=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
method System.String
The JSON-RPC method name to invoke.
parameters ProtocolModel
Optional named protocol parameters, serialized according to the transport operation.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.InvalidOperationException
The relay is not registered as active, or the authentication identity required by the request is unavailable or has changed.
System.NotSupportedException
The relay has no WebSocket endpoint, or a protocol value has no supported serializer.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.Net.WebSockets.WebSocketException
The WebSocket handshake, send, or receive operation fails.
System.IO.IOException
The WebSocket stream closes before the pending response is received.
System.ArgumentException
The serialized WebSocket request exceeds 1 MiB.
System.Security.Cryptography.CryptographicException
The cryptographic provider or configured signer fails while verifying relay evidence or authenticating the request.
Remarks
The successful JSON-RPC result must be null. Device sessions also start notification dispatch; reconnection does not replay the request. Waiting for connection readiness shares the request's 60-second timeout.
RelayClient.SendWebSocketAsync<T>(string, ProtocolModel, CancellationToken) Method
Sends a JSON-RPC request through an authenticated WebSocket session and awaits its response.
public System.Threading.Tasks.Task<T> SendWebSocketAsync<T>(string method, Meshline.Models.Protocol.ProtocolModel? parameters=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken))
where T : Meshline.Models.Protocol.ProtocolModel;
Type parameters
T
The protocol model type expected in the response.
Parameters
method System.String
The JSON-RPC method name to invoke.
parameters ProtocolModel
Optional named protocol parameters, serialized according to the transport operation.
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task<T>
A task whose result is the deserialized response model after its protocol validation succeeds.
Exceptions
System.InvalidOperationException
The relay is not registered as active, or the authentication identity required by the request is unavailable or has changed.
System.NotSupportedException
The relay has no WebSocket endpoint, or a protocol value has no supported serializer.
RelayException
The relay rejects the operation with a structured HTTP or JSON-RPC protocol error.
System.IO.InvalidDataException
The response is missing, violates transport or model rules, or contains inconsistent relay evidence.
System.Text.Json.JsonException
The request or response cannot be represented as protocol JSON.
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
This relay client, its pool, or its supplied HTTP client has been disposed.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
System.Net.WebSockets.WebSocketException
The WebSocket handshake, send, or receive operation fails.
System.IO.IOException
The WebSocket stream closes before the pending response is received.
System.ArgumentException
The serialized WebSocket request exceeds 1 MiB.
System.Security.Cryptography.CryptographicException
The cryptographic provider or configured signer fails while verifying relay evidence or authenticating the request.
Remarks
Account and device sessions can send requests. Device sessions also start notification dispatch; reconnection does not replay the request. Waiting for connection readiness shares the request's 60-second timeout.
Events
RelayClient.ErrorOccurred Event
Occurs when the notification dispatcher reports an error or connection invalidation.
public event EventHandler<Exception>? ErrorOccurred;
Event Type
System.EventHandler<System.Exception>
RelayClient.Faulted Event
Occurs when the notification dispatcher encounters a terminal failure that retires this client from its pool.
public event EventHandler? Faulted;
Event Type
RelayClient.NotificationReceived Event
Occurs when a JSON-RPC notification is dispatched from the relay WebSocket stream.
public event EventHandler<RpcRequest>? NotificationReceived;
Event Type
System.EventHandler<RpcRequest>
RelayClient.SocketConnected Event
Occurs after a WebSocket notification stream connects or reconnects and authenticates.
public event EventHandler? SocketConnected;
Event Type
RelayClient.StateChanged Event
Occurs when the relay connection, authentication, session, or last-error state changes.
public event EventHandler? StateChanged;