Struct ImapClientStd 

pub struct ImapClientStd {
    pub inner: ImapClientStd,
    pub auto_select: bool,
    pub capabilities: Vec<Capability<'static>>,
}

Available on crate features client and imap only.

Light IMAP client built on top of the io-imap type-erased inner.

auto_select is the per-message policy flag the IMAP coroutines read at construction time; flip it off when the caller already pre-selects the target mailbox. capabilities is the live list discovered at login; watch_mailbox needs QRESYNC to be present.

The RFC 2971 auto_id knob lives on the inner io-imap client (inner.auto_id) because the auth coroutines themselves chain the ID round-trip; set it before any auth_*/login call (or pass it through Self::connect).

Fields

inner: ImapClientStd

auto_select: bool

capabilities: Vec<Capability<'static>>

Implementations

impl ImapClientStd

pub fn new<S: Read + Write + Send + 'static>(stream: S) -> Self

Wraps an already-connected stream with a fresh inner client, the default auto_select = true policy, and an empty capability list. Callers that intend to use watch_mailbox should populate capabilities after login.

pub fn run<C, T, E>(&mut self, coroutine: C) -> Result<T, ImapClientError>

where C: ImapCoroutine<Yield = ImapYield, Return = Result<T, E>>, ImapClientError: From<E>,

Pumps any standard-shape IMAP coroutine (Yield = ImapYield, Return = Result<T, E>) against the inner client’s stream and fragmentizer until it terminates.

Reaches into Self::inner for raw field access rather than delegating to InnerImapClientStd::run so error variants route through ImapClientError directly.

pub fn ping(&mut self) -> Result<(), ImapClientError>

Sends a NOOP to keep the connection alive (RFC 3501 §6.1.2). Sole purpose is to reset the server’s inactivity timer on long-idle TUI sessions; the response is discarded.

pub fn list_mailboxes( &mut self, with_counts: bool, ) -> Result<Vec<Mailbox>, ImapClientError>

Lists every mailbox visible to the session. When with_counts is set, follows up with one STATUS per row to populate Mailbox::total / Mailbox::unread.

pub fn list_envelopes( &mut self, mailbox: &str, page: Option<u32>, page_size: Option<u32>, with_attachment: bool, ) -> Result<Vec<Envelope>, ImapClientError>

Lists envelopes from mailbox. page = None and page_size = None fetch the whole mailbox. Page 1 is the most recent window.

pub fn search_envelopes( &mut self, mailbox: &str, query: Option<&SearchEmailsQuery>, page: Option<u32>, page_size: Option<u32>, with_attachment: bool, ) -> Result<Vec<Envelope>, ImapClientError>

Available on crate feature search only.

Searches envelopes in mailbox against the shared query. Pagination is applied to the SORT-ordered UID list before FETCH.

pub fn store_flags( &mut self, mailbox: &str, ids: &[&str], flags: &[Flag], op: FlagOp, ) -> Result<(), ImapClientError>

Adds, sets, or removes flags on a UID set. When Self::auto_select is on, the target mailbox is SELECTed first; sync engines flip it off and pre-select once per batch.

pub fn get_message( &mut self, mailbox: &str, id: &str, ) -> Result<Vec<u8>, ImapClientError>

Fetches one message’s raw RFC 5322 bytes without flipping the \Seen flag. Honours Self::auto_select.

pub fn add_message( &mut self, mailbox: &str, flags: &[Flag], raw: Vec<u8>, ) -> Result<String, ImapClientError>

Appends raw to mailbox with the given flags. Returns the appended UID, resolved via UIDPLUS when available or via UID SEARCH HEADER Message-ID as a fallback.

pub fn create_mailbox(&mut self, name: &str) -> Result<(), ImapClientError>

Creates name as a new mailbox (RFC 3501 §6.3.3).

pub fn delete_mailbox(&mut self, name: &str) -> Result<(), ImapClientError>

Deletes name (RFC 3501 §6.3.4).

pub fn delete_message( &mut self, mailbox: &str, id: &str, ) -> Result<(), ImapClientError>

Marks id as \Deleted then EXPUNGEs. Honours Self::auto_select.

pub fn copy_messages( &mut self, from: &str, to: &str, ids: &[&str], ) -> Result<(), ImapClientError>

Copies a UID set from from to to (RFC 3501 §6.4.7). Honours Self::auto_select.

pub fn move_messages( &mut self, from: &str, to: &str, ids: &[&str], ) -> Result<(), ImapClientError>

Moves a UID set from from to to (RFC 6851). Honours Self::auto_select.

pub fn watch_mailbox( &mut self, mailbox: &str, shutdown: Arc<AtomicBool>, tx: Sender<WatchEvent>, ) -> Result<(), ImapClientError>

Watches mailbox for envelope-level deltas, forwarding every event through the caller-supplied Sender.

Blocks the current thread: drives the IDLE + QRESYNC coroutine in a loop, fans socket reads / writes against Self::inner’s stream, and pushes each yielded WatchEvent into tx. Returns Ok(()) when shutdown flips (cooperative: the inner watcher winds IDLE down at the next loop tick) or when the receiver behind tx is dropped; returns Err when the protocol layer errors out.

The caller must set a read timeout on the inner stream before invoking this method so the shutdown flag is polled at every timeout tick instead of only on server traffic. WouldBlock and TimedOut errors are treated as “no new bytes” and let the coroutine re-yield WantsRead.

Self::capabilities must advertise QRESYNC (RFC 7162); populate it via login or an explicit CAPABILITY round-trip before reaching here.

pub fn diff_envelopes( &mut self, mailbox: &str, state: Option<&[u8]>, ) -> Result<EnvelopeDiff, ImapClientError>

Returns the QRESYNC-driven envelope delta for mailbox.

Decodes state into a checkpoint, opens SELECT (QRESYNC …) with (uid_validity, highest_mod_seq), then fetches new UIDs above the cached high-water mark. Surfaces EnvelopeDiff::FullListRequired when QRESYNC is missing from Self::capabilities, when UIDVALIDITY bumped, or when no usable checkpoint was supplied; otherwise returns EnvelopeDiff::Incremental with the new state, the flag updates, the new envelopes and the vanished UIDs.

impl ImapClientStd

pub fn connect( url: &Url, tls: &Tls, starttls: bool, sasl: Option<impl Into<Sasl>>, auto_id: Option<Vec<(IString<'static>, NString<'static>)>>, ) -> Result<Self, ImapClientError>

Available on crate features native-tls or rustls-aws or rustls-ring only.

Opens a TCP / TLS connection to url, runs the optional STARTTLS upgrade and the SASL authentication, then wraps the authenticated stream with the io-email knobs.

Delegates the protocol dance to InnerImapClientStd::connect, which also sets a 5 s read timeout on the underlying socket so Self::watch_mailbox can poll its shutdown flag at every timeout tick. auto_id is forwarded to the inner connect and triggers an RFC 2971 ID round-trip after authentication (see InnerImapClientStd::auto_id).