Struct ImapClientStd 

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

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 ...).

Implementations

impl ImapClientStd

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

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

pub fn set_stream<S: Read + Write + Send + '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<str>, ) -> Result<String, ImapClientStdError>

Sends an arbitrary raw command line (no tag, no trailing CRLF) and returns the verbatim server response.

The response spans up to and including the tagged completion line. Synchronizing literals are not supported.

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 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 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.