Members on this page
ConversationChangedMeshlineClient(ClientOptions, DatabaseOptions, RelayClientPool, ISecretProtector, IAccountSigner)ChangeHomeRelayAsync(string, CancellationToken)EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken)GetConversationAsync(string, CancellationToken)GetConversationsAsync(ConversationQuery, CancellationToken)MarkReadAsync(string, long, CancellationToken)MarkReadAsync(string, CancellationToken)RecoverAccountAsync(AccountRecoveryOptions, CancellationToken)AccountManagerChannelManagerDeviceDeviceManagerDeviceStateGroupManagerMessageManagerProfileProfileManagerRoute
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
MeshlineClient.ChannelManager Property
The client-owned component for public channels.
public Meshline.Components.ChannelManager ChannelManager { get; }
Property Value
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
MeshlineClient.DeviceManager Property
The client-owned component for local device keys and authorization.
public Meshline.Components.DeviceManager DeviceManager { get; }
Property Value
MeshlineClient.DeviceState Property
The currently known account device state, or null when it is unavailable.
public Meshline.Models.Protocol.AccountDeviceState? DeviceState { get; }
Property Value
MeshlineClient.GroupManager Property
The client-owned component for encrypted groups.
public Meshline.Components.GroupManager GroupManager { get; }
Property Value
MeshlineClient.MessageManager Property
The client-owned component for contacts and direct messaging.
public Meshline.Components.MessageManager MessageManager { get; }
Property Value
MeshlineClient.Profile Property
The current account's profile, or null when it is unavailable.
public Meshline.Models.Protocol.AccountProfile? Profile { get; }
Property Value
MeshlineClient.ProfileManager Property
The client-owned component for account profiles.
public Meshline.Components.ProfileManager ProfileManager { get; }
Property Value
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
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;