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 connect( url: &Url, tls: &Tls, sasl: Option<impl Into<Sasl>>, opts: ImapSessionOpenOptions, ) -> Result<(Self, Vec<Capability<'static>>), ImapClientError>

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), unix:// is a local socket. opts.starttls = true is only valid on a cleartext transport. Pass None as sasl to skip auth.

SCRAM credentials carrying an empty nonce are given one drawn here, an empty nonce being no nonce at all as far as RFC 5802 is concerned; a caller wanting its own passes it in the credentials.

Every protocol decision belongs to ImapSessionOpen; this method only answers its transport requests with Stream. A caller on another runtime pumps the same coroutine with its own sockets.

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 watch_mailbox( self, mailbox: Mailbox<'static>, capability: &[Capability<'static>], opts: ImapMailboxWatchStreamOptions, ) -> Result<ImapMailboxWatchStream, ImapClientError>

Consumes the client into a background watcher.

Drop the returned stream (or call its close) to wind down. capability selects the QRESYNC path or the whole-mailbox fallback, and opts.shutdown_poll how long winding down may take.

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

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<(), ImapClientError>

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 append_stream( &mut self, mailbox: Mailbox<'static>, source: impl Read, len: usize, opts: ImapMessageAppendOptions, ) -> Result<ImapMessageAppendOutput, ImapClientError>

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.

Trait Implementations

impl Debug for ImapClientStd

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

Formats the value using the given formatter.

impl ImapClient for ImapClientStd

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

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

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

fn greeting(&mut self) -> Result<ImapGreetingOk, ImapClientError>

Consumes the greeting and reports the advertised capabilities along with whether the session opened already authenticated.

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

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

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

SASL AUTHENTICATE ANONYMOUS.

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

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

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

SASL AUTHENTICATE PLAIN.

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

SASL AUTHENTICATE OAUTHBEARER. Channel must be TLS-protected.

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

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

fn auth_scram_sha256( &mut self, creds: SaslScramCreds, opts: ImapAuthScramSha256Options, ) -> Result<Vec<Capability<'static>>, ImapClientError>

Available on crate feature scram only.

SASL AUTHENTICATE SCRAM-SHA-256.

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

LOGOUT; ends the session.

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

CAPABILITY; returns the advertised capabilities.

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

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

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

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

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

ENABLE; returns the capabilities the server confirmed enabling.

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

LIST; returns the mailboxes matching reference and pattern.

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

LSUB; returns the subscribed mailboxes matching reference and pattern.

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

STATUS; returns the requested status items for mailbox.

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

CREATE; creates mailbox.

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

DELETE; deletes mailbox.

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

RENAME; renames mailbox from to to.

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

SUBSCRIBE; subscribes to mailbox.

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

UNSUBSCRIBE; unsubscribes from mailbox.

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

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

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

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

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

CLOSE; expunges deleted messages and unselects the mailbox.

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

UNSELECT; unselects the mailbox without expunging.

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

CHECK; requests a mailbox checkpoint.

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

EXPUNGE; returns the expunged sequence numbers.

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

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

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

FETCH; returns the requested items keyed by message id.

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

SEARCH; returns the ids matching criteria.

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

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

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

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

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

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

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

APPEND; returns the optional EXISTS count and APPENDUID pair.

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

SORT with a client-side fallback.

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

THREAD; returns the message threads matching search_criteria.

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

LOGIN. Channel must be TLS-protected.

fn raw(&mut self, command: &[u8]) -> Result<String, ImapClientError>

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

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

SELECT <mailbox> (QRESYNC ...).