Struct imap::extensions::idle::Handle

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

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.

Each of the wait functions 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 ssl_conn = TlsConnector::builder().build().unwrap();
let client = imap::connect(("example.com", 993), "example.com", &ssl_conn)
    .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");

let idle = imap.idle().expect("Could not IDLE");

// Exit on any mailbox change
let result = idle.wait_keepalive_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. Handle::wait_keepalive_while does this. This still allows a client to receive immediate mailbox updates even though it need only “poll” at half hour intervals.

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

Implementations

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

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

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

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

pub fn set_keepalive(&mut self, interval: Duration)

Set the keep-alive interval to use when wait_keepalive_while is called.

The interval defaults to 29 minutes as dictated by RFC 2177.

pub fn wait_keepalive_while<F>(self, callback: F) -> Result<()> where
    F: FnMut(UnsolicitedResponse) -> bool, 

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

This method differs from Handle::wait_while in that it will periodically refresh the IDLE connection, to prevent the server from timing out our connection. The keepalive interval is set to 29 minutes by default, as dictated by RFC 2177, but can be changed using Handle::set_keepalive.

This is the recommended method to use for waiting.

pub fn wait_with_timeout_while<F>(
    self,
    timeout: Duration,
    callback: F
) -> Result<WaitOutcome> where
    F: FnMut(UnsolicitedResponse) -> bool, 

Block until the given given amount of time has elapsed, 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.