Skip to content
Meshline
SDK 1.6.0 · TypeView source on GitHub

Developer guide · API index

Members on this page

Meshline.Sdk

Meshline

MeshlineClient Class

Coordinates account, device, profile, messaging, channel, and group components for one local account and device.

public sealed class MeshlineClient : Meshline.Components.ClientComponent

Inheritance System.Object → ClientComponent → MeshlineClient

Remarks

Migrate the database before InitializeAsync(CancellationToken), establish authorization when needed,
then call StartAsync(CancellationToken) separately. Startup awaits required network authentication;
local history is available after initialization. The client owns its components; the application owns the supplied pool,
signer and secret protector. Events may be raised from background threads.

Verified local-device removal or rejected local authentication suspends background work. An own-state query
denied after device-session renewal also suspends it, preserving the last verified state without declaring revocation.
Background reads never request account signatures. Observe BackgroundError for the cause and StateChanged for completed shutdown.

Use one active client per database, including across processes, and await DisposeAsync()
before transferring ownership. The SDK does not enforce exclusivity. Concurrent calls follow each method's calling contract;
EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken) must not overlap direct device mutations.

Constructors

MeshlineClient(ClientOptions, DatabaseOptions, RelayClientPool, ISecretProtector, IAccountSigner) Constructor

Initializes a new instance of MeshlineClient.

public MeshlineClient(Meshline.Models.Client.ClientOptions options, Meshline.Storage.DatabaseOptions databaseOptions, Meshline.Transport.RelayClientPool relayClients, Meshline.Interactions.ISecretProtector secretProtector, Meshline.Interactions.IAccountSigner? accountSigner=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.

secretProtector ISecretProtector

The application-owned protector used to store and restore local secrets.

accountSigner IAccountSigner

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

Exceptions

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

System.ArgumentException
The configured account identifier is invalid.

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

Properties

MeshlineClient.AccountManager Property

The client-owned component for account routing.

public Meshline.Components.AccountManager AccountManager { get; }

Property Value

AccountManager

MeshlineClient.ChannelManager Property

The client-owned component for public channels.

public Meshline.Components.ChannelManager ChannelManager { get; }

Property Value

ChannelManager

MeshlineClient.Device Property

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

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

Property Value

DeviceCertificate

MeshlineClient.DeviceManager Property

The client-owned component for local device keys and authorization.

public Meshline.Components.DeviceManager DeviceManager { get; }

Property Value

DeviceManager

MeshlineClient.DeviceState Property

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

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

Property Value

AccountDeviceState

MeshlineClient.GroupManager Property

The client-owned component for encrypted groups.

public Meshline.Components.GroupManager GroupManager { get; }

Property Value

GroupManager

MeshlineClient.MessageManager Property

The client-owned component for contacts and direct messaging.

public Meshline.Components.MessageManager MessageManager { get; }

Property Value

MessageManager

MeshlineClient.Profile Property

The current account's profile, or null when it is unavailable.

public Meshline.Models.Protocol.AccountProfile? Profile { get; }

Property Value

AccountProfile

MeshlineClient.ProfileManager Property

The client-owned component for account profiles.

public Meshline.Components.ProfileManager ProfileManager { get; }

Property Value

ProfileManager

MeshlineClient.Route Property

The current account's last known route, or null when no route is known.

public Meshline.Models.Protocol.AccountRoute? Route { get; }

Property Value

AccountRoute

Methods

MeshlineClient.ChangeHomeRelayAsync(string, CancellationToken) Method

Migrates the current account's device state, route, and profile to another eligible home relay.

public System.Threading.Tasks.Task ChangeHomeRelayAsync(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
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. A verified active relay, account signer, complete device state, or local-device authorization required by the operation is unavailable. The route changed concurrently, a pending migration targets another relay, the device is not yet valid, or staging leaves too little time to publish the route.

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 relay, previous device state, or publication input is invalid or belongs to another account.

System.ArgumentOutOfRangeException
A certificate or route validity duration, or a selected publication revision, is outside its supported range.

Remarks

Requires a known route, complete device state, and a local device. Progress is persisted for retry or startup resumption at the same target relay. This transfers authorization and profile state; it does not copy relay message history.

MeshlineClient.EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken) Method

Idempotently establishes or renews local-device authorization while preserving the account's other devices and original relay.

public System.Threading.Tasks.Task EstablishAccountAsync(Meshline.Models.Client.AccountEstablishmentOptions? options=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

options AccountEstablishmentOptions

Optional initial settings and explicit device replacement. An unfinished operation retains its saved lifetimes, initial push gateway and profile.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task
A task that completes after confirming effective route/device authorization and initializing the profile as needed.

Exceptions

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

System.InvalidOperationException
Initialization is incomplete, synchronization is running when authorization needs changing, no active relay is configured, or the pool is bound to an unrelated device.

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

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.ArgumentException
The target relay, previous device state, or publication input is invalid or belongs to another account.

System.ArgumentOutOfRangeException
A certificate or route validity duration, or a selected publication revision, is outside its supported range.

AccountEstablishmentException
Setup requires caller action, verified state is unavailable, or publication is not confirmed.
Inspect Reason and the optional device, key-access or contact details. InnerException preserves signing, transport and validation failures.

Remarks

Requires initialization. Valid authorization is reused; account signing is requested only for authorization changes
or account-authenticated state access. Repeat this method with the same database to resume interrupted setup.
Start background synchronization separately through StartAsync(CancellationToken).

Retain the database, device keys and protection material together, or begin with all local data absent.
Partial permanent loss is unsupported. Key-access failures preserve records and never regenerate keys.
Device reauthorization does not restore lost chat history.

Stop synchronization before changing authorization. Do not overlap this method with
CreateDeviceAsync, RenewDeviceAsync, RemoveDeviceAsync or PublishDeviceStateAsync on this client's DeviceManager,
including from signing or event callbacks. Await completion, failure or cancellation before starting the other operation.

MeshlineClient.GetConversationAsync(string, CancellationToken) Method

Reads one locally available conversation by its peer, group, or channel identifier.

public System.Threading.Tasks.Task<Meshline.Models.Client.Conversation?> GetConversationAsync(string conversationId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

conversationId System.String

The peer account identifier for a direct conversation, or the group or channel identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Conversation>
The local conversation summary, or null when absent.

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.

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.ArgumentException
The conversation identifier is not a valid peer account, group, or channel identifier.

System.NotSupportedException
A direct-conversation identifier uses an unsupported account namespace.

MeshlineClient.GetConversationsAsync(ConversationQuery, CancellationToken) Method

Opens a snapshot reader for locally available conversations matching the supplied filters.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.Conversation>> GetConversationsAsync(Meshline.Models.Client.ConversationQuery? query=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

query ConversationQuery

Optional conversation filters; null includes all conversation kinds.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Conversation>>
A snapshot reader for the matching local results. The caller must dispose the reader after use.

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.

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.ArgumentException
The query contains unsupported conversation-kind flags.

Remarks

This query reads local storage without fetching missing relay history. Its snapshot is fixed when opened; dispose the reader promptly and open a new reader to observe later changes.

MeshlineClient.MarkReadAsync(string, long, CancellationToken) Method

Advances a conversation's local read position through the supplied message position, inclusively.

public System.Threading.Tasks.Task MarkReadAsync(string conversationId, long localSequence, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

conversationId System.String

The peer account identifier for a direct conversation, or the group or channel identifier.

localSequence System.Int64

The positive LocalSequence of a message the application has read in this conversation.

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 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 conversation kind cannot be handled by the local read-position update.

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.ArgumentException
The conversation identifier is not a valid peer account, group, or channel identifier.

System.ArgumentOutOfRangeException
The position is not positive, or advancing to it would not identify a locally known message in this conversation.

System.NotSupportedException
A direct-conversation identifier uses an unsupported account namespace.

Remarks

The position only advances; repeated or older positions are no-ops. New messages beyond this fixed boundary remain unread.
Advancing requires a locally stored direct message, decrypted group message, or known original channel publication at this position.
A channel publication remains a valid boundary after deletion while its original metadata is retained.
This is a cumulative read position, so filtered or incomplete history must not be treated as proof that every earlier message was read.

MeshlineClient.MarkReadAsync(string, CancellationToken) Method

Advances a conversation's local read position to its latest currently stored readable message.

public System.Threading.Tasks.Task MarkReadAsync(string conversationId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

conversationId System.String

The peer account identifier for a direct conversation, or the group or channel 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 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 conversation kind cannot be handled by the local read-position update.

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.ArgumentException
The conversation identifier is not a valid peer account, group, or channel identifier.

System.NotSupportedException
A direct-conversation identifier uses an unsupported account namespace.

Remarks

This overload marks all currently stored readable messages as read, including arrivals since an earlier query.
To acknowledge only messages already viewed, use the overload that accepts their LocalSequence.
An empty conversation is a no-op, and the read position never moves backward.

MeshlineClient.RecoverAccountAsync(AccountRecoveryOptions, CancellationToken) Method

Explicitly restores account access by publishing device state and a new account route.

public System.Threading.Tasks.Task RecoverAccountAsync(Meshline.Models.Client.AccountRecoveryOptions? options=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

options AccountRecoveryOptions

Optional relay selection, validity, prior device state, and recovery revision settings.

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. A verified active relay, account signer, complete device state, or local-device authorization required by the operation 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 relay, previous device state, or publication input is invalid or belongs to another account.

System.ArgumentOutOfRangeException
A certificate or route validity duration, or a selected publication revision, is outside its supported range.

Remarks

Requires initialization and an account signer. Recovery can publish new authoritative device and route revisions and clears pending establishment and migration records after success. Use this explicitly when restoring access, not as a routine startup fallback.

Events

MeshlineClient.ConversationChanged Event

Occurs when a locally computed conversation summary is created, updated, or removed.

public event EventHandler<ConversationChangedEventArgs>? ConversationChanged;

Event Type

System.EventHandler<ConversationChangedEventArgs>