Skip to content
Meshline
SDK 1.6.0 · TypeView source on GitHub

Developer guide · API index

Members on this page

Meshline.Sdk

Meshline.Components

MessageManager Class

Manages contacts, encrypted direct messages, the persistent outbox, and account timeline synchronization.

public sealed class MessageManager : Meshline.Components.ClientComponent

Inheritance System.Object → ClientComponent → MessageManager

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.

Constructors

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

Manages contacts, encrypted direct messages, the persistent outbox, and account timeline synchronization.

public MessageManager(Meshline.Models.Client.ClientOptions options, Meshline.Storage.DatabaseOptions databaseOptions, Meshline.Transport.RelayClientPool relayClients, Meshline.Components.AccountManager accountManager, Meshline.Components.DeviceManager deviceManager, 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.

deviceManager DeviceManager

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

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.

Methods

MessageManager.AcceptContactRequestAsync(string, CancellationToken) Method

Verifies an incoming request, activates the contact, and queues reciprocal consent and account-device synchronization.
The acceptance message requests offline push.

public System.Threading.Tasks.Task<Meshline.Models.Client.ContactInfo> AcceptContactRequestAsync(string accountId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactInfo>
The newly active contact with its updated grant states.

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. Required account routes, current device states, local keys, or the secret protector are unavailable. There is no incoming request, its device state is unavailable, or the request changed while being accepted.

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 stored contact grant or resulting consent or synchronization message violates protocol constraints.

System.NotSupportedException
An account identifier uses an unsupported namespace.

System.UnauthorizedAccessException
The local device lacks current authorization or a direct message lacks the recipient's required contact grant.

MessageManager.AddContactAsync(ContactInvite, string, CancellationToken) Method

Creates an outgoing contact request and queues signed consent for delivery to the account.
The contact request message requests offline push.

public System.Threading.Tasks.Task<Meshline.Models.Client.ContactRequestInfo> AddContactAsync(Meshline.Models.Protocol.ContactInvite invite, string? note=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

invite ContactInvite

The signed invitation authorizing the operation.

note System.String

An optional note accompanying the contact request.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactRequestInfo>
The locally stored outgoing contact request and its associated outbox information.

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. Required account routes, current device states, local keys, or the secret protector are unavailable. The account is already a contact or the prospective contact has no currently authorized devices.

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 is invalid or is the current account, or the invitation or note violates protocol constraints.

System.NotSupportedException
An account identifier uses an unsupported namespace.

System.UnauthorizedAccessException
The local device lacks current authorization or a direct message lacks the recipient's required contact grant.

MessageManager.AddContactAsync(string, string, CancellationToken) Method

Creates an outgoing contact request and queues signed consent for delivery to the account.
The contact request message requests offline push.

public System.Threading.Tasks.Task<Meshline.Models.Client.ContactRequestInfo> AddContactAsync(string accountId, string? note=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 identifier.

note System.String

An optional note accompanying the contact request.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactRequestInfo>
The locally stored outgoing contact request and its associated outbox information.

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. Required account routes, current device states, local keys, or the secret protector are unavailable. The account is already a contact or the prospective contact has no currently authorized devices.

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 is invalid or is the current account, or the invitation or note violates protocol constraints.

System.NotSupportedException
An account identifier uses an unsupported namespace.

System.UnauthorizedAccessException
The local device lacks current authorization or a direct message lacks the recipient's required contact grant.

MessageManager.CancelMessageAsync(string, CancellationToken) Method

Cancels an outgoing message only while its local outbox state is queued.

public System.Threading.Tasks.Task<bool> CancelMessageAsync(string messageId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

messageId System.String

The canonical message identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<System.Boolean>
true if this call changes a queued message to canceled; otherwise, false.

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.

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

Remarks

Missing messages and messages in any state other than queued are left unchanged. This does not retract a submitted or accepted message.

MessageManager.CreateInviteAsync(DateTimeOffset, CancellationToken) Method

Creates an expiring, device-signed invitation to contact the current account.

public System.Threading.Tasks.Task<Meshline.Models.Protocol.ContactInvite> CreateInviteAsync(System.DateTimeOffset expiresAt, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

expiresAt System.DateTimeOffset

The future expiration time of the invitation.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactInvite>
The signed contact invitation.

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. No local device has been created, or its signing key cannot be loaded without a secret protector.

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.

System.ArgumentOutOfRangeException
The invitation does not expire in the future.

MessageManager.DismissContactRequestAsync(string, CancellationToken) Method

Removes an incoming contact request from local storage if it exists.

public System.Threading.Tasks.Task DismissContactRequestAsync(string accountId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 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.

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.

MessageManager.GetContactAsync(string, CancellationToken) Method

Reads an active contact from local storage by account identifier.

public System.Threading.Tasks.Task<Meshline.Models.Client.ContactInfo?> GetContactAsync(string accountId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactInfo>
The active contact, or null when no active contact exists for the account.

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.

MessageManager.GetContactRequestsAsync(string, ContactRequestDirection, CancellationToken) Method

Opens a snapshot reader for locally stored contact requests matching the supplied filters.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.ContactRequestInfo>> GetContactRequestsAsync(string? accountId=null, Meshline.Models.Client.ContactRequestDirection direction=Meshline.Models.Client.ContactRequestDirection.All, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

An optional account identifier filter; null includes all values.

direction ContactRequestDirection

The incoming or outgoing request directions to include; defaults to both.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<ContactRequestInfo>>
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 direction filter contains unsupported 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.

MessageManager.GetContactsAsync(string, CancellationToken) Method

Opens a snapshot reader for active local contacts, optionally matching an account identifier or alias.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.ContactInfo>> GetContactsAsync(string? search=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

search System.String

An optional substring of the account identifier or alias. Null or empty text disables this filter.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<ContactInfo>>
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.

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.

MessageManager.GetMessageAsync(MessageRef, CancellationToken) Method

Reads a direct message from local storage by sender and message identifier.

public System.Threading.Tasks.Task<Meshline.Models.Client.MessageInfo?> GetMessageAsync(Meshline.Models.Client.MessageRef key, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

key MessageRef

The sender and identifier of the direct message.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<MessageInfo>
The stored direct message, 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.

MessageManager.GetMessageHistoryAsync(string, HistoryRange, CancellationToken) Method

Opens a snapshot reader for locally stored direct messages, optionally restricted to one peer.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.MessageInfo>> GetMessageHistoryAsync(string? peerAccountId=null, Meshline.Models.Client.HistoryRange? range=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

peerAccountId System.String

An optional peer account filter; null includes all direct messages.

range HistoryRange

The optional exclusive local sequence bounds, copied when this method is called. Null means unbounded.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<MessageInfo>>
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 history bounds or resource scope are invalid.

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.
Each batch is returned in ascending sequence order. With before, successive batches move toward older messages; otherwise they move toward newer messages.
When reopening, use the first item of a backward batch as before, or the last item of a forward batch as after.
Sequence bounds must be nonnegative safe integers; when both are supplied, after must be less than before and before determines the direction.

MessageManager.GetMessageHistoryAsync(string, CancellationToken) Method

Opens a snapshot reader for locally stored direct messages, optionally restricted to one peer.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.MessageInfo>> GetMessageHistoryAsync(string? peerAccountId, System.Threading.CancellationToken cancellationToken);

Parameters

peerAccountId System.String

An optional peer account filter; null includes all direct messages.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<MessageInfo>>
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.

Remarks

This overload retains the original parameter list for binary compatibility. Optional arguments are provided by the HistoryRange overload.
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.

MessageManager.GetOutboxAsync(string, MessageSendState, CancellationToken) Method

Opens a snapshot reader for direct-message outbox entries matching the recipient and state filters.

public System.Threading.Tasks.Task<Meshline.Storage.QueryReader<Meshline.Models.Client.MessageSendStatus>> GetOutboxAsync(string? recipient=null, Meshline.Models.Client.MessageSendState state=Meshline.Models.Client.MessageSendState.All, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

recipient System.String

An optional recipient account filter; null includes all recipients.

state MessageSendState

The outbox states to include; flags may be combined and the default includes all states.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<Meshline.Storage.QueryReader<MessageSendStatus>>
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 send-state filter contains unsupported 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.
Results include retained terminal records. The SDK retains the newest 1000 terminal records by creation time and then ordinal message identifier across the account's entire outbox, including internal protocol messages.

MessageManager.GetSendStatusAsync(string, CancellationToken) Method

Reads the locally tracked outbox status of a message.

public System.Threading.Tasks.Task<Meshline.Models.Client.MessageSendStatus?> GetSendStatusAsync(string messageId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

messageId System.String

The canonical message identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<MessageSendStatus>
The pending or retained terminal outbox status, or null when no local record remains, including after history eviction.

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.

Remarks

Terminal states remain queryable across restarts within the SDK's retained history of 1000 terminal outbox records.
A missing record does not prove success, failure, or that the message was never sent.

MessageManager.GetSyncStatusAsync(string, CancellationToken) Method

Returns the current local synchronization snapshot for the account timeline on this relay, without network access.

public System.Threading.Tasks.Task<Meshline.Models.Client.ResourceSyncStatus> GetSyncStatusAsync(string relayId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

relayId System.String

The canonical resource identifier.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ResourceSyncStatus>
An immutable runtime snapshot, initially Idle with no successful completion time.

Exceptions

System.ArgumentException
The resource identifier is invalid.

System.InvalidOperationException
This component has not been initialized.

System.ObjectDisposedException
This component has been disposed.

System.OperationCanceledException
The operation was canceled.

MessageManager.RemoveContactAsync(string, CancellationToken) Method

Marks a contact deleted, clears local grants and requests, and queues account-device synchronization.

public System.Threading.Tasks.Task RemoveContactAsync(string accountId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 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 home route, local device, or device state needed for contact synchronization 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.

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.UnauthorizedAccessException
The local device is not authorized to enqueue contact synchronization.

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

System.ArgumentException
The account identifier is invalid or identifies the current account.

System.NotSupportedException
The account identifier uses an unsupported namespace.

System.IO.InvalidDataException
The device certificates used for the account synchronization message contain duplicate devices or another account.

Remarks

This updates local contact state and synchronizes the account's other devices. It does not erase existing message history or retract already delivered grants or messages.

MessageManager.SendMessageAsync(string, DirectMessageDraft, CancellationToken) Method

Validates and persists an encrypted direct-message outbox operation for background delivery.
The message requests offline push.

public System.Threading.Tasks.Task<Meshline.Models.Client.MessageSendStatus> SendMessageAsync(string recipient, Meshline.Models.Client.DirectMessageDraft draft, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

recipient System.String

The recipient account's CAIP-10 identifier.

draft DirectMessageDraft

The plaintext message body, attachment references, and optional reply information to send.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<MessageSendStatus>
The locally persisted outbox status; delivery proceeds in background processing.

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. Required account routes, current device states, local keys, or the secret protector are 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 recipient account identifier or message payload violates protocol constraints.

System.NotSupportedException
An account identifier uses an unsupported namespace.

System.UnauthorizedAccessException
The local device lacks current authorization or a direct message lacks the recipient's required contact grant.

Remarks

The result describes a persisted outbox entry, not confirmed delivery. Start the component to process queued work and observe SendStatusChanged or query its status. Sending to another account requires the appropriate contact authorization.

MessageManager.SetAliasAsync(string, string, CancellationToken) Method

Updates an active contact's private alias and queues synchronization to the account's other devices.

public System.Threading.Tasks.Task<Meshline.Models.Client.ContactInfo> SetAliasAsync(string accountId, string? alias, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

accountId System.String

The account's CAIP-10 identifier.

alias System.String

The private contact alias to store, or null to clear it.

cancellationToken System.Threading.CancellationToken

A token that can cancel the operation.

Returns

System.Threading.Tasks.Task<ContactInfo>
The contact snapshot containing the updated alias.

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 account is not an active contact or a required account-device synchronization message cannot be enqueued.

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.ArgumentException
A nonempty alias contains only whitespace or exceeds 256 UTF-8 bytes.

System.UnauthorizedAccessException
The local device is not authorized to enqueue contact synchronization.

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

System.IO.InvalidDataException
The device certificates used for the account synchronization message contain duplicate devices or another account.

MessageManager.SynchronizeAsync(string, CancellationToken) Method

Performs and awaits one incremental synchronization pass for the account timeline on the specified relay.

public System.Threading.Tasks.Task<Meshline.Models.Client.ResourceSyncStatus> SynchronizeAsync(string relayId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

relayId System.String

The resource to synchronize.

cancellationToken System.Threading.CancellationToken

Cancels this call, including queued work; already committed data is retained.

Returns

System.Threading.Tasks.Task<ResourceSyncStatus>
This pass's completion snapshot, including any processing block such as missing group keys.

Exceptions

System.ArgumentException
The resource identifier is invalid.

System.InvalidOperationException
This component or a required component is not initialized, or authorization is unavailable.

System.ObjectDisposedException
The component has been disposed.

System.OperationCanceledException
The call, component lifetime, or relay request was canceled.

System.Net.Http.HttpRequestException
Relay discovery or a network request fails.

RelayException
The relay rejects synchronization.

System.IO.InvalidDataException
Remote or stored data fails validation.

Microsoft.Data.Sqlite.SqliteException
Local storage cannot be accessed.

Microsoft.EntityFrameworkCore.DbUpdateException
Persisting synchronized data fails.

Remarks

Requires initialization and usable authorization, but not StartAsync. Every call performs a fresh pass,
serialized with background synchronization. Reads forward from local progress until the relay reports no more pages;
this does not freeze a remote sequence at call time or guarantee complete historical data.
Transport and storage failures update synchronization status and propagate to the caller.

MessageManager.WaitForSendStatusAsync(string, MessageSendState, CancellationToken) Method

Waits for a locally tracked send to reach an acceptance milestone or finish unsuccessfully.

public System.Threading.Tasks.Task<Meshline.Models.Client.MessageSendStatus?> WaitForSendStatusAsync(string messageId, Meshline.Models.Client.MessageSendState targetState=Meshline.Models.Client.MessageSendState.TargetAccepted, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

messageId System.String

The message identifier returned by SendMessageAsync(string, DirectMessageDraft, CancellationToken).

targetState MessageSendState

The milestone to await: queued, relay accepted, or target accepted. Defaults to target accepted.

cancellationToken System.Threading.CancellationToken

A token that cancels only this wait, without canceling the outgoing message.

Returns

System.Threading.Tasks.Task<MessageSendStatus>
The actual status at or beyond the requested milestone, a failed or canceled status, or null if no local record or concurrent completion is available.

Exceptions

System.ArgumentOutOfRangeException
The target is not queued, relay accepted, or target accepted, including combined filter flags.

System.OperationCanceledException
The caller cancels the wait or the component is disposed while waiting.

System.InvalidOperationException
The component has not completed initialization.

System.ObjectDisposedException
The component has been disposed.

Microsoft.Data.Sqlite.SqliteException
Reading the local send status fails.

Remarks

Checks retained local status and observes subsequent commits by this manager without polling or issuing network requests.
Later acceptance satisfies an earlier milestone; failed and canceled always end the wait. Inspect the returned state.
Unknown or evicted records return null immediately. Target acceptance is not a recipient read receipt.
Initialize the component before waiting. Waiting does not start the sender; it survives stop/start, but component disposal cancels it.
There is no built-in timeout; use a cancellation token to bound the wait. Changes made by another manager or process are not observed.

Events

MessageManager.ContactChanged Event

Occurs when a local contact's relationship, alias, or authorization changes.

public event EventHandler<ContactChangedEventArgs>? ContactChanged;

Event Type

System.EventHandler<ContactChangedEventArgs>

MessageManager.ContactRequestChanged Event

Occurs when a local incoming or outgoing contact request changes.

public event EventHandler<ContactRequestChangedEventArgs>? ContactRequestChanged;

Event Type

System.EventHandler<ContactRequestChangedEventArgs>

MessageManager.MessageReceived Event

Occurs after verified direct messages are committed to local storage.

public event EventHandler<MessageReceivedEventArgs>? MessageReceived;

Event Type

System.EventHandler<MessageReceivedEventArgs>

MessageManager.SendStatusChanged Event

Occurs when a locally tracked outgoing-message status changes.

public event EventHandler<MessageSendStatusChangedEventArgs>? SendStatusChanged;

Event Type

System.EventHandler<MessageSendStatusChangedEventArgs>

MessageManager.SyncStatusChanged Event

Occurs after the local synchronization snapshot changes. Handlers must not synchronously wait for component operations.

public event EventHandler<ResourceSyncStatus>? SyncStatusChanged;

Event Type

System.EventHandler<ResourceSyncStatus>

MessageManager.TimelineChanged Event

Occurs after account messages and their synchronization cursor are committed locally.

public event EventHandler? TimelineChanged;

Event Type

System.EventHandler