Method ObserveWindowWithoutSettingSeenAsync

Namespace: MailFathom.Application.Synchronization.Sessions

Assembly: MailFathom.Application.dll

ObserveWindowWithoutSettingSeenAsync(IReadOnlyList<ImapUid>, ulong?, CancellationToken)

Reports which of the supplied occurrences the folder still holds, with the flags the server shows for them.

Task<RemoteFolderWindowObservation> ObserveWindowWithoutSettingSeenAsync(IReadOnlyList<ImapUid> uids, ulong? reconciledThroughModSeq, CancellationToken cancellationToken)

Parameters

uids IReadOnlyList<ImapUid>: The UIDs to ask about, which must belong to this session's folder and UIDVALIDITY.
reconciledThroughModSeq ulong?: The modification sequence the whole folder was last reconciled through, or null to ask about every supplied UID without regard to what has changed since.
cancellationToken CancellationToken: Cancels the read and every remaining attempt.

Returns

Task<RemoteFolderWindowObservation>: What the folder still holds out of uids, described or merely confirmed, and the folder's modification sequence where it reports one.

Remarks

A UID the answer accounts for in neither list is one the folder no longer holds. That is the whole detection mechanism for a message deleted on the server, so an implementation must never invent an entry for a UID the server said nothing about, and must never omit one it did answer for.

The supplied sequence is a permission rather than an instruction. An implementation may use it to ask the server only about what changed since — which is the point of accepting it — but only where the server also tells it which of the remaining UIDs still exist, because a sequence-limited answer alone cannot tell an unchanged message from a deleted one. Where the server offers no such mechanism, the implementation asks about the whole window and reports nothing as unchanged; the end state is identical either way, and only the work differs.

An answer that names a UID without its flags is refused rather than dropped, because dropping it would turn a message the server proved exists into the silence a deleted message produces. An implementation reports that as a failure and lets the caller's next run ask again; nothing local may be derived from a partial answer.

The operation reads flags and nothing else. It must not request a message body, a header, or any other item whose retrieval sets the remote \Seen flag, and it must not write a flag back: this is the path that inspects mail somebody has already stored, and a careless fetch here would mark a whole mailbox as read.

Exceptions

MailboxUnavailableException: Thrown when the mail server did not serve the read within its configured resilience budget.
MailboxFolderRecreatedException: Thrown when a recovered connection reselected the folder with a different UIDVALIDITY.
MailboxAnswerIncompleteException: Thrown when the server answered for an email without the flags this operation requested.