Expand description
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
sourceimpl<T: Read + Write> Client<T>
impl<T: Read + Write> Client<T>
sourcepub fn new(stream: T) -> 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();
sourcepub fn login<U: AsRef<str>, P: AsRef<str>>(
self,
username: U,
password: P
) -> Result<Session<T>, (Error, Client<T>)>
pub fn login<U: AsRef<str>, P: AsRef<str>>(
self,
username: U,
password: P
) -> 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)
.native_tls().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;
}
}
sourcepub fn authenticate<A: Authenticator, S: AsRef<str>>(
self,
auth_type: S,
authenticator: &A
) -> Result<Session<T>, (Error, Client<T>)>
pub fn authenticate<A: Authenticator, S: AsRef<str>>(
self,
auth_type: S,
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).native_tls()
.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
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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more