Method WaitForFolderChangeAsync

Namespace: MailFathom.Application.Synchronization.Sessions

Assembly: MailFathom.Application.dll

WaitForFolderChangeAsync(TimeSpan, CancellationToken)

Waits until the folder changes or until the supplied wait elapses, whichever comes first.

Task<MailboxNotificationOutcome> WaitForFolderChangeAsync(TimeSpan maxWait, CancellationToken cancellationToken)

Parameters

maxWait TimeSpan: How long this call may wait before it returns having observed nothing.
cancellationToken CancellationToken: Ends the wait promptly and leaves the session usable, which is how a caller with several sessions stops the rest once one of them reported a change.

Returns

Task<MailboxNotificationOutcome>: Whether the folder changed or the wait ended without one.

Remarks

The bound belongs to the caller because renewal is a scheduling decision rather than a protocol one: a push mechanism has to be re-issued before the server's own idle timeout, and returning WaitElapsed is how the session says it is ready to be renewed. An implementation must therefore treat an elapsed wait as an ordinary return and leave the session usable.

A wait is never repeated on the caller's behalf. Retrying one would re-enter a wait whose result the caller has already been told nothing about, and the retry budgets that cover an ordinary read are measured in seconds while a wait here is measured in minutes.

Cancellation ends the wait as WaitElapsed rather than as an OperationCanceledException, and the session stays open. A caller cancels this to stop waiting, not to abandon the session, and the two are the same thing only at shutdown — where the caller disposes the session next anyway. Reporting a cancelled wait as a failure instead would make one folder's notification cost every other watched folder its connection.

Exceptions

ArgumentOutOfRangeException: Thrown when maxWait is negative or zero.
MailboxUnavailableException: Thrown when the mail server did not hold the session up within its configured resilience budget.
MailboxFolderRecreatedException: Thrown when a re-established connection reselected the folder with a different UIDVALIDITY.