[][src]Struct imap::Client

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

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 Client<TcpStream>[src]

pub fn secure<S: AsRef<str>>(
    self,
    domain: S,
    ssl_connector: &TlsConnector
) -> Result<Client<TlsStream<TcpStream>>>
[src]

This will upgrade an IMAP client from using a regular TCP connection to use TLS.

The domain parameter is required to perform hostname verification.

impl<T: Read + Write> Client<T>[src]

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

Creates a new client over the given stream.

For an example of how to use this method to provide a pure-Rust TLS integration, see the rustls.rs in the examples/ directory.

This method primarily exists for writing tests that mock the underlying transport, but can also be used to support IMAP over custom tunnels.

Note: In case you do need to use Client::new over imap::connect, 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 login<U: AsRef<str>, P: AsRef<str>>(
    self,
    username: U,
    password: P
) -> Result<Session<T>, (Error, Client<T>)>
[src]

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::connect(
    ("imap.example.org", 993),
    "imap.example.org",
    &tls_connector).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, S: AsRef<str>>(
    self,
    auth_type: S,
    authenticator: &A
) -> Result<Session<T>, (Error, Client<T>)>
[src]

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

extern crate imap;
extern crate native_tls;
use native_tls::TlsConnector;

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 domain = "imap.example.com";
    let tls = TlsConnector::builder().build().unwrap();
    let client = imap::connect((domain, 993), domain, &tls).unwrap();
    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>[src]

impl<T: Read + Write> Deref for Client<T>[src]

type Target = Connection<T>

The resulting type after dereferencing.

impl<T: Read + Write> DerefMut for Client<T>[src]

Auto Trait Implementations

impl<T> RefUnwindSafe for Client<T> where
    T: RefUnwindSafe

impl<T> Send for Client<T> where
    T: Send

impl<T> Sync for Client<T> where
    T: Sync

impl<T> Unpin for Client<T> where
    T: Unpin

impl<T> UnwindSafe for Client<T> where
    T: UnwindSafe

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.