sander/rust-imap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation around unhandled responses.

Browse source 
UnsolicitedResponse is not exhaustive, and open an issue if you find one
that isn't handled.
This commit is contained in:
Todd Mortimer 2021-04-06 21:54:52 -04:00
parent ff39ebf58d
commit 9126d3c15b
2 changed files with 13 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
src/extensions/idle.rs
View file

@ -193,8 +193,8 @@ impl<'a, T: Read + Write + 'a> Handle<'a, T> {
} }
} }
/// Block until the given callback returns `Stop`, or until an unhandled /// Block until the given callback returns `Stop`, or until a response
/// response arrives on the IDLE channel. /// arrives that is not explicitly handled by [`UnsolicitedResponse`].
pub fn wait<F>(mut self, callback: F) -> Result<()> pub fn wait<F>(mut self, callback: F) -> Result<()>
where where
F: FnMut(UnsolicitedResponse) -> CallbackAction, F: FnMut(UnsolicitedResponse) -> CallbackAction,
@ -211,8 +211,8 @@ impl<'a, T: SetReadTimeout + Read + Write + 'a> Handle<'a, T> {
self.keepalive = interval; self.keepalive = interval;
} }
/// Block until the given callback returns `Stop`, or until an unhandled /// Block until the given callback returns `Stop`, or until a response
/// response arrives on the IDLE channel. /// arrives that is not explicitly handled by [`UnsolicitedResponse`].
/// ///
/// This method differs from [`Handle::wait`] in that it will periodically refresh the IDLE /// This method differs from [`Handle::wait`] in that it will periodically refresh the IDLE
/// connection, to prevent the server from timing out our connection. The keepalive interval is /// connection, to prevent the server from timing out our connection. The keepalive interval is
@ -235,8 +235,9 @@ impl<'a, T: SetReadTimeout + Read + Write + 'a> Handle<'a, T> {
self.timed_wait(keepalive, true, callback).map(|_| ()) self.timed_wait(keepalive, true, callback).map(|_| ())
} }
/// Block until the given amount of time has elapsed, or the given callback /// Block until the given given amount of time has elapsed, the given callback
/// returns `Stop`, or until an unhandled response arrives on the IDLE channel. /// returns `Stop`, or until a response arrives that is not explicitly handled
/// by [`UnsolicitedResponse`].
pub fn wait_with_timeout<F>(self, timeout: Duration, callback: F) -> Result<WaitOutcome> pub fn wait_with_timeout<F>(self, timeout: Duration, callback: F) -> Result<WaitOutcome>
where where
F: FnMut(UnsolicitedResponse) -> CallbackAction, F: FnMut(UnsolicitedResponse) -> CallbackAction,

7
src/types/unsolicited_response.rs
View file

@ -12,7 +12,12 @@ use imap_proto::{
/// Responses that the server sends that are not related to the current command. /// Responses that the server sends that are not related to the current command.
/// [RFC 3501](https://tools.ietf.org/html/rfc3501#section-7) states that clients need to be able /// [RFC 3501](https://tools.ietf.org/html/rfc3501#section-7) states that clients need to be able
/// to accept any response at any time. These are the ones we've encountered in the wild. /// to accept any response at any time.
///
/// Not all possible responses are explicitly enumerated here because in practice only
/// some types of responses are delivered as unsolicited responses. If you encounter an
/// unsolicited response in the wild that is not handled here, please
/// [open an issue](https://github.com/jonhoo/rust-imap/issues) and let us know!
/// ///
/// Note that `Recent`, `Exists` and `Expunge` responses refer to the currently `SELECT`ed folder, /// Note that `Recent`, `Exists` and `Expunge` responses refer to the currently `SELECT`ed folder,
/// so the user must take care when interpreting these. /// so the user must take care when interpreting these.