Skip to content
Meshline
SDK 1.6.0 · TypeView source on GitHub

Developer guide · API index

Members on this page

Meshline.Sdk

Meshline.Components

DeviceManager Class

Manages the local device's protected keys, certificates, published authorization, and device signing.

public sealed class DeviceManager : Meshline.Components.ClientComponent, Meshline.Interactions.IDeviceSigner

Inheritance System.Object → ClientComponent → DeviceManager

Implements IDeviceSigner

Exceptions

System.ArgumentNullException
The network context in options is null. The options argument is null.

System.ArgumentException
The configured account identifier is invalid.

System.NotSupportedException
The configured account identifier uses an unsupported account namespace.

Remarks

Callers must not run device creation, renewal, removal, or state publication concurrently with
EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken) on the same client, including from signing or event callbacks.
Await the current operation's completion, failure, or cancellation before starting the other operation.

Constructors

DeviceManager(ClientOptions, DatabaseOptions, RelayClientPool, AccountManager, IAccountSigner, ISecretProtector) Constructor

Manages the local device's protected keys, certificates, published authorization, and device signing.

public DeviceManager(Meshline.Models.Client.ClientOptions options, Meshline.Storage.DatabaseOptions databaseOptions, Meshline.Transport.RelayClientPool relayClients, Meshline.Components.AccountManager accountManager, Meshline.Interactions.IAccountSigner? accountSigner=null, Meshline.Interactions.ISecretProtector? secretProtector=null);

Parameters

options ClientOptions

The network and account configuration for this component.

databaseOptions DatabaseOptions

The SQLite database configuration; create its parent directory and apply migrations before initialization.

relayClients RelayClientPool

The shared relay pool. The application owns it and must dispose it after all dependent components.

accountManager AccountManager

The account component sharing this network, account, database, and relay pool.

accountSigner IAccountSigner

The application-owned account signer required for account-authorized operations, or null when those operations are not needed.

secretProtector ISecretProtector

The application-owned secret protector, required for operations that persist or restore protected key or message material.

Exceptions

System.ArgumentNullException
The network context in options is null. The options argument is null.

System.ArgumentException
The configured account identifier is invalid.

System.NotSupportedException
The configured account identifier uses an unsupported account namespace.

Remarks

Callers must not run device creation, renewal, removal, or state publication concurrently with
EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken) on the same client, including from signing or event callbacks.
Await the current operation's completion, failure, or cancellation before starting the other operation.

Properties

DeviceManager.DeviceState Property

The currently known account device state, or null when it is unavailable.

public Meshline.Models.Protocol.AccountDeviceState? DeviceState { get; }

Property Value

AccountDeviceState

DeviceManager.Local Property

The local device certificate, or null when no local device has been loaded or created.

public Meshline.Models.Protocol.DeviceCertificate? Local { get; }

Property Value

DeviceCertificate

DeviceManager.RelayClients Property

The shared relay pool used by this device manager.

public Meshline.Transport.RelayClientPool RelayClients { get; }

Property Value

RelayClientPool

Methods

DeviceManager.CreateDeviceAsync(DeviceCreationOptions, CancellationToken) Method

Creates and stores a new local device with the supplied certificate lifetime and optional push gateway declaration.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> CreateDeviceAsync(Meshline.Models.Client.DeviceCreationOptions options, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

options DeviceCreationOptions

The certificate lifetime and optional push gateway declaration.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<DeviceCertificate>
The newly stored local device certificate.

Exceptions

System.ArgumentNullException
options is null.

System.ArgumentException
The push gateway is not a valid protocol HTTPS URL.

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable, a local device already exists, or device preparation/publication is unfinished.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.

System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.

Remarks

Requires an account signer, a secret protector, and no local device or unfinished device preparation/publication.
Publish device state before treating the device as authorized by the relay.

DeviceManager.CreateDeviceAsync(TimeSpan, CancellationToken) Method

Creates local Ed25519 and X25519 keys and an account-authorized device certificate, then protects and stores them.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> CreateDeviceAsync(System.TimeSpan validity, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

validity System.TimeSpan

The validity duration, from one second through 720 days.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<DeviceCertificate>
The newly stored local device certificate.

Exceptions

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable, a local device already exists, or device preparation/publication is unfinished.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.

System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.

Remarks

Requires an account signer, a secret protector, and a database without a local device or unfinished device preparation/publication. This overload omits the push gateway declaration. The returned certificate is stored locally; publish device state before treating the device as authorized by the relay.

DeviceManager.DeriveSharedSecretAsync(ReadOnlyMemory<byte>, CancellationToken) Method

Performs X25519 key agreement with the local device's encryption private key.

public System.Threading.Tasks.Task<byte[]> DeriveSharedSecretAsync(System.ReadOnlyMemory<byte> peerPublicKey, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

peerPublicKey System.ReadOnlyMemory<System.Byte>

The peer's 32-byte X25519 public key.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<System.Byte[]>
A new 32-byte buffer containing the raw shared secret.

Exceptions

System.ArgumentException
The peer key is not 32 bytes or produces an all-zero shared secret.

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. The local device or the secret protector required to load its keys is unavailable.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.IO.InvalidDataException
The stored local device certificate is JSON null.

Remarks

The returned bytes are raw key-agreement material. Apply the protocol's required key derivation before using them as a cryptographic key and clear sensitive buffers after use.

DeviceManager.GetAuthorizationState(string) Method

Evaluates registration and certificate validity in the currently known account device state.

public Meshline.Components.DeviceAuthorizationState GetAuthorizationState(string deviceId);

Parameters

deviceId System.String

The canonical device identifier.

Returns

DeviceAuthorizationState
The device's authorization state according to locally known registration and the current time.

Exceptions

System.InvalidOperationException
This component or a required component has not completed initialization.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

System.ArgumentException
The deviceId argument is not a canonical device identifier.

DeviceManager.GetCertificate(string) Method

Finds a device certificate in the currently known account device state.

public Meshline.Models.Protocol.DeviceCertificate? GetCertificate(string deviceId);

Parameters

deviceId System.String

The canonical device identifier.

Returns

DeviceCertificate
The registered certificate, or null when the state or device is unknown.

Exceptions

System.InvalidOperationException
This component or a required component has not completed initialization.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

System.ArgumentException
The deviceId argument is not a canonical device identifier.

DeviceManager.GetDeviceStateAsync(ContactGrant, CancellationToken) Method

Returns verified cached device state, starting a demand-triggered background refresh when due.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(Meshline.Models.Protocol.ContactGrant grant, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

grant ContactGrant

A contact grant authorizing this account to access the grantor's device state.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The grant has no valid signature from a currently authorized device.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

DeviceManager.GetDeviceStateAsync(ContactInvite, CancellationToken) Method

Returns verified cached device state, starting a demand-triggered background refresh when due.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(Meshline.Models.Protocol.ContactInvite invite, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

invite ContactInvite

The signed invitation authorizing the operation.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The invitation signature is invalid, a local signing key fails validation, or the cryptographic provider fails signature verification.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

DeviceManager.GetDeviceStateAsync(string, CancellationToken) Method

Returns verified cached device state, starting a demand-triggered background refresh when due.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetDeviceStateAsync(string? accountId=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The target account identifier, or null for the current account.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

Remarks

Reads trigger refreshes one hour after success or one minute after failure. Missing or unusable state requires a shared fetch;
caller cancellation only ends that caller's wait. State signatures and revisions are verified before caching, and authorization is checked on use.
Use RefreshDeviceStateAsync(string, CancellationToken) to await a refresh.

DeviceManager.GetOwnDeviceStateAsync(string, CancellationToken) Method

Resolves the current account's device state directly from the specified relay.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> GetOwnDeviceStateAsync(string relayId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

relayId System.String

The relay's canonical lowercase Neo script-hash identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The current account's verified device state, or null when unavailable at that relay.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

Remarks

While running, queries use device authentication only. A stopped manager may use account authentication when its local device authorization is unavailable. Device-authenticated reads retry an expired session with the same identity but never escalate a rejection into account signing; use explicit account establishment for reauthorization.

DeviceManager.PublishDeviceStateAsync(string, IReadOnlyList<DeviceCertificate>, DeviceStatePublishOptions, CancellationToken) Method

Signs and publishes a complete device authorization state and reports acceptance or staging.

public System.Threading.Tasks.Task<Meshline.Models.Client.DeviceStatePublishResult> PublishDeviceStateAsync(string relayId, System.Collections.Generic.IReadOnlyList<Meshline.Models.Protocol.DeviceCertificate>? certificates=null, Meshline.Models.Client.DeviceStatePublishOptions? options=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

relayId System.String

The relay's canonical lowercase Neo script-hash identifier.

certificates System.Collections.Generic.IReadOnlyList<DeviceCertificate>

The complete certificate list to publish, or null to preserve known devices and refresh the local certificate.

options DeviceStatePublishOptions

Optional prior-state, recovery, and revision settings.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<DeviceStatePublishResult>
The submitted state and the relay's authoritative-acceptance or temporary-staging result.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The account signer or complete prior device state is unavailable, the local device is unauthorized outside recovery, or a pending publication conflicts with the requested update.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
The relay response or returned device state is inconsistent, including an expired staging interval.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.ArgumentException
The prior state belongs to another account or is invalid, or the complete certificate list fails protocol validation.

System.ArgumentOutOfRangeException
The selected device-state revision is not a newer nonnegative safe integer. A relay-provided staging timestamp is outside the supported DateTimeOffset range.

Remarks

A supplied list is the complete authorized device set, not a delta. With no list, known devices are preserved and the local certificate is refreshed; unavailable prior state or missing local authorization requires explicit recovery. Staged publication is not yet authoritative.
Staged and unknown-outcome submissions remain pending. Retry with the same complete certificate list, relay, and optional revision to reuse the signed request. A call without a certificate list performs a refresh and may advance the revision.

DeviceManager.RefreshDeviceStateAsync(ContactGrant, CancellationToken) Method

Awaits device-state refresh with the supplied grant, bypassing the success interval but retaining the one-minute failure cooldown.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> RefreshDeviceStateAsync(Meshline.Models.Protocol.ContactGrant grant, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

grant ContactGrant

A contact grant authorizing this account to access the grantor's device state.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The grant has no valid signature from a currently authorized device.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

DeviceManager.RefreshDeviceStateAsync(ContactInvite, CancellationToken) Method

Awaits device-state refresh with the supplied invitation, bypassing the success interval but retaining the one-minute failure cooldown.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> RefreshDeviceStateAsync(Meshline.Models.Protocol.ContactInvite invite, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

invite ContactInvite

The signed invitation authorizing the operation.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The invitation signature is invalid, a local signing key fails validation, or the cryptographic provider fails signature verification.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

DeviceManager.RefreshDeviceStateAsync(string, CancellationToken) Method

Awaits device-state refresh, bypassing the success interval but retaining the one-minute failure cooldown.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.AccountDeviceState?> RefreshDeviceStateAsync(string? accountId=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The target account identifier, or null for the current account.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<AccountDeviceState>
The verified device state, or null when unavailable.

Exceptions

System.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. The home route, local device, or account signer needed to authenticate the query is unavailable.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.ArgumentException
The target account or relay identifier is invalid, or supplied contact evidence does not authorize a query for this account.

System.NotSupportedException
An account identifier in the query uses an unsupported namespace.

DeviceManager.RemoveDeviceAsync(string, CancellationToken) Method

Publishes a complete device state with the selected device removed after checking contact-grant continuity.

public System.Threading.Tasks.Task RemoveDeviceAsync(string deviceId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

deviceId System.String

The canonical device identifier.

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.OperationCanceledException
The caller cancels the operation or a component or relay lifetime ends.

System.TimeoutException
An SDK request deadline expires. Data contains operation and timeoutSeconds; InnerException preserves the cancellation cause.

System.InvalidOperationException
This component or a required component has not completed initialization. Published device state or retained contact history is unavailable, removal would invalidate a contact grant without accepted replacement signatures, or the relay only stages the removal.

System.ObjectDisposedException
This component, a required component, or the shared relay pool has been disposed.

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 protocol error that is not handled by this method.

System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.ArgumentException
The deviceId argument is not a canonical device identifier.

System.ArgumentOutOfRangeException
The next device-state revision exceeds the protocol safe-integer limit.

Remarks

Uses the same retained-history and confirmed-grant checks as account setup with an explicit replacement.
This operation checks existing evidence; it does not send contact-grant updates or start background synchronization.

DeviceManager.RenewDeviceAsync(DeviceRenewalOptions, CancellationToken) Method

Renews and stores the local certificate with an optional push gateway change, retaining the device keys and identity.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> RenewDeviceAsync(Meshline.Models.Client.DeviceRenewalOptions options, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

options DeviceRenewalOptions

The certificate lifetime and gateway update. See PushGateway for retain, set and remove semantics.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<DeviceCertificate>
The renewed local device certificate with the same device keys.

Exceptions

System.ArgumentNullException
options is null.

System.ArgumentException
The assigned gateway is null or is not a valid protocol HTTPS URL.

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable, no local device has been created, or device preparation/publication is unfinished.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.

System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.

System.IO.InvalidDataException
The stored local device certificate is JSON null.

Remarks

Requires account signing and no unfinished device preparation or publication. Renewal stores the certificate
and retires device sessions; publish device state to make the new authorization authoritative at the relay.

DeviceManager.RenewDeviceAsync(TimeSpan, CancellationToken) Method

Issues and stores a renewed certificate for the existing local device without replacing its keys.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.DeviceCertificate> RenewDeviceAsync(System.TimeSpan validity, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

validity System.TimeSpan

The validity duration, from one second through 720 days.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<DeviceCertificate>
The renewed local device certificate with the same device keys.

Exceptions

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. An account signer or required secret protector is unavailable, no local device has been created, or device preparation/publication is unfinished.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails. The account signer produces a certificate that fails identity or signature validation.

System.ArgumentOutOfRangeException
The requested certificate validity is outside one second through 720 days.

System.IO.InvalidDataException
The stored local device certificate is JSON null.

Remarks

The renewed certificate retains the device identity and push gateway declaration. Complete any unfinished device preparation or publication before renewing. Publish device state to make the renewed authorization authoritative at the relay.

DeviceManager.SignAsync(ReadOnlyMemory<byte>, CancellationToken) Method

Signs the supplied bytes using the device Ed25519 signing key.

public System.Threading.Tasks.Task<byte[]> SignAsync(System.ReadOnlyMemory<byte> data, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

data System.ReadOnlyMemory<System.Byte>

The exact bytes to sign or verify.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Implements SignAsync(ReadOnlyMemory<byte>, CancellationToken)

Returns

System.Threading.Tasks.Task<System.Byte[]>
The signature over the supplied input bytes.

Exceptions

System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.

System.InvalidOperationException
This component or a required component has not completed initialization. The local device or the secret protector required to load its keys is unavailable.

System.ObjectDisposedException
This component or a component used by the operation has been disposed.

Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.

System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.

System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.

System.IO.InvalidDataException
The stored local device certificate is JSON null.

Events

DeviceManager.DeviceChanged Event

Occurs when a local device certificate is created or renewed.

public event EventHandler<DeviceChangedEventArgs>? DeviceChanged;

Event Type

System.EventHandler<DeviceChangedEventArgs>

DeviceManager.DeviceStateChanged Event

Occurs when the current account's known device authorization state changes.

public event EventHandler? DeviceStateChanged;

Event Type

System.EventHandler