Struct imap::Client

pub struct Client<T: Read + Write> { /* private fields */ }

An (unauthenticated) handle to talk to an IMAP server. This is what you get when first connecting. A succesfull call to Client::login or Client::authenticate will return a Session instance that provides the usual IMAP methods.

Implementations

impl<T: Read + Write> Client<T>

pub fn new(stream: T) -> Client<T>

Creates a new client over the given stream.

This method primarily exists for writing tests that mock the underlying transport, but can also be used to support IMAP over custom tunnels. If you do not need to do that, then it is simpler to use the ClientBuilder to get a new client.

For an example, see examples/timeout.rs which uses a custom timeout on the tcp stream.

Note: In case you do need to use Client::new instead of the ClientBuilder you will need to listen for the IMAP protocol server greeting before authenticating:

let mut client = Client::new(tls);
client.read_greeting().unwrap();
let session = client.login(username, password).unwrap();

pub fn into_inner(self) -> Result<T>

Yield the underlying connection for this Client.

This consumes self since the Client is not much use without an underlying transport.

pub fn capabilities(&mut self) -> Result<Capabilities>

The CAPABILITY command requests a listing of capabilities that the server supports. The server will include “IMAP4rev1” as one of the listed capabilities. See Capabilities for further details.

This allows reading capabilities before authentication.

pub fn login( self, username: impl AsRef<str>, password: impl AsRef<str> ) -> Result<Session<T>, (Error, Client<T>)>

Log in to the IMAP server. Upon success a Session instance is returned; on error the original Client instance is returned in addition to the error. This is because login takes ownership of self, so in order to try again (e.g. after prompting the user for credetials), ownership of the original Client needs to be transferred back to the caller.

let client = imap::ClientBuilder::new("imap.example.org", 993)
    .connect().unwrap();

match client.login("user", "pass") {
    Ok(s) => {
        // you are successfully authenticated!
    },
    Err((e, orig_client)) => {
        eprintln!("error logging in: {}", e);
        // prompt user and try again with orig_client here
        return;
    }
}

pub fn authenticate<A: Authenticator>( self, auth_type: impl AsRef<str>, authenticator: &A ) -> Result<Session<T>, (Error, Client<T>)>

Authenticate with the server using the given custom authenticator to handle the server’s challenge.

struct OAuth2 {
    user: String,
    access_token: String,
}

impl imap::Authenticator for OAuth2 {
    type Response = String;
    fn process(&self, _: &[u8]) -> Self::Response {
        format!(
            "user={}\x01auth=Bearer {}\x01\x01",
            self.user, self.access_token
        )
    }
}

fn main() {
    let auth = OAuth2 {
        user: String::from("me@example.com"),
        access_token: String::from("<access_token>"),
    };
    let client = imap::ClientBuilder::new("imap.example.com", 993).connect()
        .expect("Could not connect to server");

    match client.authenticate("XOAUTH2", &auth) {
        Ok(session) => {
            // you are successfully authenticated!
        },
        Err((e, orig_client)) => {
            eprintln!("error authenticating: {}", e);
            // prompt user and try again with orig_client here
            return;
        }
    };
}

Trait Implementations

impl<T: Debug + Read + Write> Debug for Client<T>

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

Formats the value using the given formatter.

impl<T: Read + Write> DerefMut for Client<T>

fn deref_mut(&mut self) -> &mut Connection<T>

Mutably dereferences the value.

impl<T: Read + Write> Deref for Client<T>

type Target = Connection<T>

The resulting type after dereferencing.

fn deref(&self) -> &Connection<T>

Dereferences the value.