Struct Client

pub struct Client { /* private fields */ }

Implementations

impl Client

Client constructors.

This section defines 3 public constructors for Client: insecure, tls and starttls.

pub async fn insecure( host: impl ToString, port: u16, ) -> Result<Self, ClientError>

Creates an insecure client, using TCP.

This constructor creates a client based on an raw TcpStream, receives greeting then saves server capabilities.

pub async fn tls(host: impl ToString, port: u16) -> Result<Self, ClientError>

Creates a secure client, using SSL/TLS.

This constructor creates an client based on a secure TcpStream wrapped into a TlsStream, receives greeting then saves server capabilities.

pub async fn starttls( host: impl ToString, port: u16, ) -> Result<Self, ClientError>

Creates a secure client, using STARTTLS.

This constructor creates an insecure client based on a raw TcpStream, receives greeting, wraps the TcpStream into a secured TlsStream then saves server capabilities.

impl Client

Client getters and setters.

This section defines helpers to easily manipulate the client’s parameters and data.

pub fn get_idle_timeout(&self) -> &Duration

pub fn set_idle_timeout(&mut self, timeout: Duration)

pub fn set_some_idle_timeout(&mut self, timeout: Option<Duration>)

pub fn with_idle_timeout(self, timeout: Duration) -> Self

pub fn with_some_idle_timeout(self, timeout: Option<Duration>) -> Self

pub fn capabilities(&self) -> &Vec1<Capability<'static>>

Returns the server capabilities.

This function does not fetch capabilities from server, it just returns capabilities saved during the creation of this client (using Client::insecure, Client::tls or Client::starttls).

pub fn capabilities_iter( &self, ) -> impl Iterator<Item = &Capability<'static>> + '_

Returns the server capabilities, as an iterator.

Same as Client::capabilities, but just returns an iterator instead.

pub fn supported_auth_mechanisms( &self, ) -> impl Iterator<Item = &AuthMechanism<'static>> + '_

Returns supported authentication mechanisms, as an iterator.

pub fn supports_auth_mechanism(&self, mechanism: AuthMechanism<'static>) -> bool

Returns true if the given authentication mechanism is supported by the server.

pub fn login_supported(&self) -> bool

Returns true if LOGIN is supported by the server.

pub fn ext_enable_supported(&self) -> bool

Returns true if the ENABLE extension is supported by the server.

pub fn ext_sasl_ir_supported(&self) -> bool

Returns true if the SASL-IR extension is supported by the server.

pub fn ext_id_supported(&self) -> bool

Returns true if the ID extension is supported by the server.

pub fn ext_uidplus_supported(&self) -> bool

Returns true if the UIDPLUS extension is supported by the server.

pub fn ext_sort_supported(&self) -> bool

Returns true if the SORT extension is supported by the server.

pub fn ext_thread_supported(&self) -> bool

Returns true if the THREAD extension is supported by the server.

pub fn ext_idle_supported(&self) -> bool

Returns true if the IDLE extension is supported by the server.

pub fn ext_binary_supported(&self) -> bool

Returns true if the BINARY extension is supported by the server.

pub fn ext_move_supported(&self) -> bool

Returns true if the MOVE extension is supported by the server.

impl Client

Client low-level API.

This section defines the low-level API of the client, by exposing convenient wrappers around Tasks. They do not contain any logic.

pub async fn resolve<T: Task>( &mut self, task: T, ) -> Result<T::Output, ClientError>

Resolves the given Task.

pub async fn enable( &mut self, capabilities: impl IntoIterator<Item = CapabilityEnable<'_>>, ) -> Result<Option<Vec<CapabilityEnable<'_>>>, ClientError>

Enables the given capabilities.

pub async fn create( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

Creates a new mailbox.

pub async fn list( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, mailbox_wildcard: impl TryInto<ListMailbox<'_>, Error = ValidationError>, ) -> Result<Vec<(Mailbox<'static>, Option<QuotedChar>, Vec<FlagNameAttribute<'static>>)>, ClientError>

Lists mailboxes.

pub async fn select( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<SelectDataUnvalidated, ClientError>

Selects the given mailbox.

pub async fn examine( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<SelectDataUnvalidated, ClientError>

Selects the given mailbox in read-only mode.

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

Expunges the selected mailbox.

A mailbox needs to be selected before, otherwise this function will fail.

pub async fn delete( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

Deletes the given mailbox.

pub async fn search( &mut self, criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<NonZeroU32>, ClientError>

Searches messages matching the given criteria.

This function returns sequence numbers, if you need UID see Client::uid_search.

pub async fn uid_search( &mut self, criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<NonZeroU32>, ClientError>

Searches messages matching the given criteria.

This function returns UIDs, if you need sequence numbers see Client::search.

pub async fn sort( &mut self, sort_criteria: impl IntoIterator<Item = SortCriterion>, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<NonZeroU32>, ClientError>

Searches messages matching the given search criteria, sorted by the given sort criteria.

This function returns sequence numbers, if you need UID see Client::uid_sort.

pub async fn uid_sort( &mut self, sort_criteria: impl IntoIterator<Item = SortCriterion>, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<NonZeroU32>, ClientError>

Searches messages matching the given search criteria, sorted by the given sort criteria.

This function returns UIDs, if you need sequence numbers see Client::sort.

pub async fn thread( &mut self, algorithm: ThreadingAlgorithm<'_>, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<Thread>, ClientError>

pub async fn uid_thread( &mut self, algorithm: ThreadingAlgorithm<'_>, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, ) -> Result<Vec<Thread>, ClientError>

pub async fn store( &mut self, sequence_set: SequenceSet, kind: StoreType, flags: impl IntoIterator<Item = Flag<'_>>, ) -> Result<HashMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn uid_store( &mut self, sequence_set: SequenceSet, kind: StoreType, flags: impl IntoIterator<Item = Flag<'_>>, ) -> Result<HashMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn silent_store( &mut self, sequence_set: SequenceSet, kind: StoreType, flags: impl IntoIterator<Item = Flag<'_>>, ) -> Result<(), ClientError>

pub async fn uid_silent_store( &mut self, sequence_set: SequenceSet, kind: StoreType, flags: impl IntoIterator<Item = Flag<'_>>, ) -> Result<(), ClientError>

pub async fn post_append_noop(&mut self) -> Result<Option<u32>, ClientError>

pub async fn post_append_check(&mut self) -> Result<Option<u32>, ClientError>

pub async fn fetch_first( &mut self, id: NonZeroU32, items: MacroOrMessageDataItemNames<'_>, ) -> Result<Vec1<MessageDataItem<'static>>, ClientError>

pub async fn uid_fetch_first( &mut self, id: NonZeroU32, items: MacroOrMessageDataItemNames<'_>, ) -> Result<Vec1<MessageDataItem<'static>>, ClientError>

pub async fn copy( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

pub async fn uid_copy( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

pub async fn move( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

pub async fn uid_move( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

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

Executes the CHECK command.

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

Executes the NOOP command.

impl Client

Client medium-level API.

This section defines the medium-level API of the client (based on the low-level one), by exposing helpers that update client state and use a small amount of logic (mostly conditional code depending on available server capabilities).

pub async fn refresh_capabilities(&mut self) -> Result<(), ClientError>

Fetches server capabilities, then saves them.

pub async fn login( &mut self, username: impl TryInto<AString<'_>, Error = ValidationError>, password: impl TryInto<AString<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

Identifies the user using the given username and password.

pub async fn authenticate_plain( &mut self, login: impl AsRef<str>, password: impl AsRef<str>, ) -> Result<(), ClientError>

Authenticates the user using the PLAIN mechanism.

pub async fn authenticate_xoauth2( &mut self, login: impl AsRef<str>, token: impl AsRef<str>, ) -> Result<(), ClientError>

Authenticates the user using the XOAUTH2 mechanism.

pub async fn authenticate_oauthbearer( &mut self, user: impl AsRef<str>, host: impl AsRef<str>, port: u16, token: impl AsRef<str>, ) -> Result<(), ClientError>

Authenticates the user using the OAUTHBEARER mechanism.

pub async fn id( &mut self, params: Option<Vec<(IString<'static>, NString<'static>)>>, ) -> Result<Option<Vec<(IString<'static>, NString<'static>)>>, ClientError>

Exchanges client/server ids.

If the server does not support the ID extension, this function has no effect.

pub async fn append( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, flags: impl IntoIterator<Item = Flag<'_>>, message: impl AsRef<[u8]>, ) -> Result<Option<u32>, ClientError>

pub async fn appenduid( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, flags: impl IntoIterator<Item = Flag<'_>>, message: impl AsRef<[u8]>, ) -> Result<Option<(NonZeroU32, NonZeroU32)>, ClientError>

impl Client

Client high-level API.

This section defines the high-level API of the client (based on the low and medium ones), by exposing opinionated helpers. They contain more logic, and make use of fallbacks depending on available server capabilities.

pub async fn fetch( &mut self, sequence_set: SequenceSet, items: MacroOrMessageDataItemNames<'_>, ) -> Result<HashMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn uid_fetch( &mut self, sequence_set: SequenceSet, items: MacroOrMessageDataItemNames<'_>, ) -> Result<HashMap<NonZeroU32, Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn sort_or_fallback( &mut self, sort_criteria: impl IntoIterator<Item = SortCriterion> + Clone, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, fetch_items: MacroOrMessageDataItemNames<'_>, ) -> Result<Vec<Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn uid_sort_or_fallback( &mut self, sort_criteria: impl IntoIterator<Item = SortCriterion> + Clone, search_criteria: impl IntoIterator<Item = SearchKey<'_>>, fetch_items: MacroOrMessageDataItemNames<'_>, ) -> Result<Vec<Vec1<MessageDataItem<'static>>>, ClientError>

pub async fn appenduid_or_fallback( &mut self, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError> + Clone, flags: impl IntoIterator<Item = Flag<'_>>, message: impl AsRef<[u8]>, ) -> Result<Option<NonZeroU32>, ClientError>

pub async fn move_or_fallback( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

pub async fn uid_move_or_fallback( &mut self, sequence_set: SequenceSet, mailbox: impl TryInto<Mailbox<'_>, Error = ValidationError>, ) -> Result<(), ClientError>

pub fn enqueue_idle(&mut self) -> Tag<'static>

pub async fn idle( &mut self, tag: Tag<'static>, ) -> Result<(), StreamError<NextError>>

pub async fn idle_done( &mut self, tag: Tag<'static>, ) -> Result<(), StreamError<NextError>>