Members on this page
ConversationChangedMeshlineClient(ClientOptions, DatabaseOptions, RelayClientPool, ISecretProtector, IAccountSigner)ChangeHomeRelayAsync(string, CancellationToken)EstablishAccountAsync(AccountEstablishmentOptions, CancellationToken)GetConversationAsync(string, CancellationToken)GetConversationsAsync(ConversationQuery, 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 explicitly before calling InitializeAsync(CancellationToken). Establish or recover account authorization before starting a new device. The client owns its components; the application owns the supplied pool, signer, and secret protector. Events may be raised from background threads.
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 operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
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
Creates and authorizes a local device and establishes the account's initial home-relay route.
public System.Threading.Tasks.Task EstablishAccountAsync(Meshline.Models.Client.AccountEstablishmentOptions? options=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
options AccountEstablishmentOptions
Optional relay selection and validity settings; omitted settings use their defaults.
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 is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
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. A route is already known without valid local-device authorization, or an interrupted establishment targets another relay.
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, an account signer, and protected local key storage. Interrupted establishment resumes using the same database and selected relay. An existing route without valid local-device authorization requires explicit account recovery.
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, 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.
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 operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
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;