Struct imap::extensions::idle::Handle

pub struct Handle<'a, T: Read + Write> { /* private fields */ }

Handle allows a client to block waiting for changes to the remote mailbox.

The handle blocks using the IDLE command specificed in RFC 2177 until the underlying server state changes in some way.

The wait_while function takes a callback function which receives any responses that arrive on the channel while IDLE. The callback function implements whatever logic is needed to handle the IDLE response, and then returns a boolean to continue idling (true) or stop (false).

For users that want the IDLE to exit on any change (the behavior proior to version 3.0), a convenience callback function stop_on_any is provided.

use imap::extensions::idle;
let client = imap::ClientBuilder::new("example.com", 993).native_tls()
    .expect("Could not connect to imap server");
let mut imap = client.login("user@example.com", "password")
    .expect("Could not authenticate");
imap.select("INBOX")
    .expect("Could not select mailbox");

// Exit on any mailbox change. By default, connections will be periodically
// refreshed in the background.
let result = imap.idle().wait_while(idle::stop_on_any);

Note that the server MAY consider a client inactive if it has an IDLE command running, and if such a server has an inactivity timeout it MAY log the client off implicitly at the end of its timeout period. Because of that, clients using IDLE are advised to terminate the IDLE and re-issue it at least every 29 minutes to avoid being logged off. This is done by default, but can be disabled by calling Handle::keepalive

As long as a Handle is active, the mailbox cannot be otherwise accessed.

Implementations

impl<'a, T: SetReadTimeout + Read + Write + 'a> Handle<'a, T>

pub fn timeout(&mut self, interval: Duration) -> &mut Self

Set the timeout duration on the connection. This will also set the frequency at which the connection is refreshed.

The interval defaults to 29 minutes as given in RFC 2177.

pub fn keepalive(&mut self, keepalive: bool) -> &mut Self

Do not continuously refresh the IDLE connection in the background.

By default, connections will periodically be refreshed in the background using the timeout duration set by Handle::timeout. If you do not want this behaviour, call this function and the connection will simply IDLE until wait_while returns or the timeout expires.

pub fn wait_while<F>(&mut self, callback: F) -> Result<WaitOutcome> where
    F: FnMut(UnsolicitedResponse) -> bool, 

Block until the given callback returns false, or until a response arrives that is not explicitly handled by UnsolicitedResponse.

Trait Implementations

impl<'a, T: Debug + Read + Write> Debug for Handle<'a, T>

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

Formats the value using the given formatter.

impl<'a, T: Read + Write + 'a> Drop for Handle<'a, T>

fn drop(&mut self)

Executes the destructor for this type.