Struct ImapClientStd 

pub struct ImapClientStd {
    pub stream: Box<dyn ImapStream>,
    pub fragmentizer: Fragmentizer,
    pub auto_id: Option<Vec<(IString<'static>, NString<'static>)>>,
    pub pre_authenticated: bool,
}

Available on crate feature client only.

Blocking IMAP client: a stream, the connection-wide Fragmentizer and one method per coroutine.

Fields

stream: Box<dyn ImapStream>

The stream carrying the connection to the IMAP server.

fragmentizer: Fragmentizer

The connection-wide parser buffer shared by every coroutine run on this connection.

auto_id: Option<Vec<(IString<'static>, NString<'static>)>>

ID parameters consumed by every auth_*/login call; required by a few providers (mail.qq.com, fastmail).

None skips, Some(empty) sends ID NIL, Some(params) sends ID (k v ...).

pre_authenticated: bool

Whether the server greeting was PREAUTH: the session opened already authenticated (a socket proxy such as sirup), so connect skipped the SASL step. Stays false on a freshly-opened connection.

Implementations

impl ImapClientStd

pub fn new<S: ImapStream + 'static>(stream: S) -> Self

Caller is responsible for opening the connection (TCP, TLS, STARTTLS).

pub fn set_stream<S: ImapStream + 'static>(&mut self, stream: S)

Useful after a STARTTLS upgrade or on reconnection.

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

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

Runs a standard-shape coroutine to completion, fulfilling its read and write requests.

Richer yields (IDLE events, watch deltas, streamed bodies) need their own per-method loops.

pub fn greeting( &mut self, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

Consumes the greeting and returns the advertised capabilities (forcing a CAPABILITY round-trip if the greeting carried none).

pub fn login( &mut self, user: impl AsRef<str>, password: impl AsRef<str>, opts: ImapLoginOptions, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

LOGIN. Channel must be TLS-protected. Consumes auto_id.

pub fn starttls(&mut self) -> Result<Vec<u8>, ImapClientStdError>

STARTTLS. Caller still has to upgrade the socket and refresh capabilities.

Returns any bytes pre-read past the tagged response; a non-empty return is a STARTTLS-injection signal, refuse the upgrade.

pub fn auth_anonymous( &mut self, message: Option<impl AsRef<str>>, opts: ImapAuthAnonymousOptions, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

SASL AUTHENTICATE ANONYMOUS. Consumes auto_id.

pub fn auth_login( &mut self, user: impl AsRef<str>, password: impl AsRef<str>, opts: ImapAuthLoginOptions, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

SASL AUTHENTICATE LOGIN (legacy). Prefer auth_plain or auth_scram_sha256 when supported. Consumes auto_id.

pub fn auth_plain( &mut self, authzid: Option<impl AsRef<str>>, authcid: impl AsRef<str>, password: impl AsRef<str>, opts: ImapAuthPlainOptions, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

SASL AUTHENTICATE PLAIN. Consumes auto_id.

pub fn auth_oauthbearer( &mut self, user: impl AsRef<str>, host: impl AsRef<str>, port: u16, token: impl AsRef<str>, opts: ImapAuthOauthbearerOptions, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

SASL AUTHENTICATE OAUTHBEARER. Channel must be TLS-protected. Consumes auto_id.

pub fn auth_xoauth2( &mut self, user: impl AsRef<str>, token: impl AsRef<str>, opts: ImapAuthXoauth2Options, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

SASL AUTHENTICATE XOAUTH2 (Google’s pre-standard mechanism). Prefer auth_oauthbearer when supported. Consumes auto_id.

pub fn auth_scram_sha256( &mut self, user: impl AsRef<str>, password: impl AsRef<str>, opts: ImapAuthScramSha256Options, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

Available on crate feature scram only.

SASL AUTHENTICATE SCRAM-SHA-256. Consumes auto_id.

pub fn logout(&mut self) -> Result<(), ImapClientStdError>

LOGOUT; ends the session.

pub fn capability( &mut self, ) -> Result<Vec<Capability<'static>>, ImapClientStdError>

CAPABILITY; returns the advertised capabilities.

pub fn noop(&mut self) -> Result<(), ImapClientStdError>

NOOP; round-trips to keep the connection alive or poll for updates.

pub fn raw( &mut self, command: impl AsRef<[u8]>, ) -> Result<String, ImapClientStdError>

Sends one or more caller-tagged command lines byte-for-byte and returns the verbatim server response.

The bytes are written to the server exactly as given (no tag is injected, no CRLF is trimmed or appended), so callers must tag every command and separate them with CRLF. The response spans up to and including the tagged completion of every command, which may arrive out of order.

pub fn id( &mut self, opts: ImapServerIdOptions, ) -> Result<Option<Vec<(IString<'static>, NString<'static>)>>, ImapClientStdError>

ID. An opts.parameters of None sends ID NIL.

pub fn enable( &mut self, capabilities: Vec1<CapabilityEnable<'static>>, ) -> Result<Option<Vec<CapabilityEnable<'static>>>, ImapClientStdError>

ENABLE; returns the capabilities the server confirmed enabling.

pub fn list( &mut self, reference: Mailbox<'static>, pattern: ListMailbox<'static>, ) -> Result<ImapMailboxListing, ImapClientStdError>

LIST; returns the mailboxes matching reference and pattern.

pub fn lsub( &mut self, reference: Mailbox<'static>, pattern: ListMailbox<'static>, ) -> Result<ImapMailboxListing, ImapClientStdError>

LSUB; returns the subscribed mailboxes matching reference and pattern.

pub fn status( &mut self, mailbox: Mailbox<'static>, item_names: impl Into<Cow<'static, [StatusDataItemName]>>, ) -> Result<Vec<StatusDataItem>, ImapClientStdError>

STATUS; returns the requested status items for mailbox.

pub fn create( &mut self, mailbox: Mailbox<'static>, ) -> Result<(), ImapClientStdError>

CREATE; creates mailbox.

pub fn delete( &mut self, mailbox: Mailbox<'static>, ) -> Result<(), ImapClientStdError>

DELETE; deletes mailbox.

pub fn rename( &mut self, from: Mailbox<'static>, to: Mailbox<'static>, ) -> Result<(), ImapClientStdError>

RENAME; renames mailbox from to to.

pub fn subscribe( &mut self, mailbox: Mailbox<'static>, ) -> Result<(), ImapClientStdError>

SUBSCRIBE; subscribes to mailbox.

pub fn unsubscribe( &mut self, mailbox: Mailbox<'static>, ) -> Result<(), ImapClientStdError>

UNSUBSCRIBE; unsubscribes from mailbox.

pub fn select( &mut self, mailbox: Mailbox<'static>, opts: ImapMailboxSelectOptions, ) -> Result<ImapMailboxSelectData, ImapClientStdError>

SELECT; opens mailbox for read-write and returns its state.

pub fn examine( &mut self, mailbox: Mailbox<'static>, opts: ImapMailboxExamineOptions, ) -> Result<ImapMailboxSelectData, ImapClientStdError>

EXAMINE; opens mailbox read-only and returns its state.

pub fn select_qresync( &mut self, mailbox: Mailbox<'static>, uid_validity: NonZeroU32, highest_mod_seq: u64, capability: &[Capability<'static>], ) -> Result<ImapMailboxSelectData, ImapClientStdError>

SELECT <mailbox> (QRESYNC ...).

Errors with QresyncNotSupported when capability lacks QRESYNC, with InvalidModSeq when highest_mod_seq is 0.

pub fn close(&mut self) -> Result<(), ImapClientStdError>

CLOSE; expunges deleted messages and unselects the mailbox.

pub fn unselect(&mut self) -> Result<(), ImapClientStdError>

UNSELECT; unselects the mailbox without expunging.

pub fn check(&mut self) -> Result<(), ImapClientStdError>

CHECK; requests a mailbox checkpoint.

pub fn expunge(&mut self) -> Result<Vec<NonZeroU32>, ImapClientStdError>

EXPUNGE; returns the expunged sequence numbers.

pub fn uid_expunge( &mut self, sequence_set: SequenceSet, ) -> Result<Vec<NonZeroU32>, ImapClientStdError>

UID EXPUNGE <sequence_set> (RFC 4315); permanently removes only the \Deleted messages whose UID is in sequence_set, leaving any other \Deleted message untouched.

Requires the server to advertise UIDPLUS (see [Self::supports_uidplus]); returns the expunged sequence numbers.

pub fn watch_mailbox( self, mailbox: Mailbox<'static>, capability: &[Capability<'static>], ) -> Result<ImapMailboxWatchStream, ImapClientStdError>

Consumes the client into a background watcher.

Drop the returned stream (or call its close) to wind down. Errors when capability lacks QRESYNC.

pub fn fetch( &mut self, sequence_set: SequenceSet, items: MacroOrMessageDataItemNames<'static>, opts: ImapMessageFetchOptions, ) -> Result<BTreeMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ImapClientStdError>

FETCH; returns the requested items keyed by message id.

pub fn fetch_body_stream( &mut self, id: NonZeroU32, uid: bool, sink: impl Write, ) -> Result<(), ImapClientStdError>

FETCH <id> (BODY.PEEK[]) streaming the message body straight into sink; the body never lands in memory whole.

Peek leaves \Seen untouched. Returns once the tagged response is parsed; a missing id completes with an empty sink.

pub fn fetch_bodies_stream<S: Write>( &mut self, sequence_set: SequenceSet, uid: bool, open: impl FnMut(u32) -> Result<S>, done: impl FnMut(u32, S) -> Result<()>, ) -> Result<(), ImapClientStdError>

UID FETCH <set> (UID BODY.PEEK[]) streaming every message body in one command — N bodies for one round trip. Each message is routed to its own sink: open(uid) returns a fresh sink when a message begins, its body is streamed into it, and done(uid, sink) commits it when the message ends. No body is held in memory whole. A requested UID absent on the server simply never calls open/done.

pub fn search( &mut self, criteria: Vec1<SearchKey<'static>>, opts: ImapMessageSearchOptions, ) -> Result<Vec<NonZeroU32>, ImapClientStdError>

SEARCH; returns the ids matching criteria.

pub fn store( &mut self, sequence_set: SequenceSet, kind: StoreType, flags: Vec<Flag<'static>>, opts: ImapMessageStoreOptions, ) -> Result<BTreeMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ImapClientStdError>

STORE (echo variant); returns the server-reported FETCH echoes.

pub fn copy( &mut self, sequence_set: SequenceSet, mailbox: Mailbox<'static>, opts: ImapMessageCopyOptions, ) -> Result<ImapCopyUid, ImapClientStdError>

COPY; copies messages to mailbox and returns the optional COPYUID pair.

pub fn move( &mut self, sequence_set: SequenceSet, mailbox: Mailbox<'static>, opts: ImapMessageMoveOptions, ) -> Result<ImapCopyUid, ImapClientStdError>

MOVE; moves messages to mailbox and returns the optional COPYUID pair.

pub fn append( &mut self, mailbox: Mailbox<'static>, message: &[u8], opts: ImapMessageAppendOptions, ) -> Result<ImapMessageAppendOutput, ImapClientStdError>

APPEND; returns the optional EXISTS count and APPENDUID pair.

Buffered: the whole message is held in memory. For large messages prefer Self::append_stream.

pub fn append_stream( &mut self, mailbox: Mailbox<'static>, source: impl Read, len: usize, opts: ImapMessageAppendOptions, ) -> Result<ImapMessageAppendOutput, ImapClientStdError>

APPEND streaming len octets from source straight to the socket; the body never lands in memory whole.

len must match the source exactly: IMAP declares the octet count up front, so a shorter source poisons the connection. Synchronising by default so the server can reject before the body is sent; set opts.non_sync to skip the wait.

pub fn sort( &mut self, sort_criteria: Vec1<SortCriterion>, search_criteria: Vec1<SearchKey<'static>>, opts: ImapMessageSortOptions, ) -> Result<Vec<NonZeroU32>, ImapClientStdError>

SORT with a client-side fallback.

With opts.fallback == false this is a plain server SORT; with opts.fallback == true it SEARCHes, FETCHes the sort keys, and sorts locally. Feed fallback from a SORT capability check (the server SORT requires the extension).

pub fn thread( &mut self, algorithm: ThreadingAlgorithm<'static>, search_criteria: Vec1<SearchKey<'static>>, opts: ImapMessageThreadOptions, ) -> Result<Vec<Thread>, ImapClientStdError>

THREAD; returns the message threads matching search_criteria.

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, Vec<Capability<'static>>), ImapClientStdError>

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

End-to-end connect: TCP/TLS, optional STARTTLS, greeting, optional SASL.

imap:// is plain TCP (143), imaps:// is implicit TLS (993). starttls = true is only valid on imap://. Pass Sasl::None to skip auth.

Trait Implementations

impl Debug for ImapClientStd

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.