Struct Client

Help

pub struct Client<S: Write + Read + Unpin + Send> { /* private fields */ }

Implementations§

Source §

pub fn get_state(&self) -> &ClientState

§Current client state

Indicates what state the client is currently in, can be either Authentication, Transaction, Update or None.

Some methods are only available in some specified states and will error if run in an incorrect state.

https://www.rfc-editor.org/rfc/rfc1939#section-3

Source

pub async fn noop(&mut self) -> Result<()>

§NOOP

The POP3 server does nothing, it merely replies with a positive response.

§Arguments: none

§Restrictions:

May only be given in the TRANSACTION state

§Possible Responses:

OK

§Examples:

client.noop()?;

https://www.rfc-editor.org/rfc/rfc1939#page-9

Source

pub async fn uidl(&mut self, msg_number: Option<usize>) -> Result<UidlResponse>

§UIDL

If an argument was given and the POP3 server issues a positive response with a line containing information for that message. This line is called a “unique-id listing” for that message.

If no argument was given and the POP3 server issues a positive response, then the response given is multi-line. After the initial +OK, for each message in the maildrop, the POP3 server responds with a line containing information for that message. This line is called a “unique-id listing” for that message.

§Arguments:

a message-number (optional), which, if present, may NOT refer to a message marked as deleted.

§Restrictions:

May only be given in the TRANSACTION state.

§Possible responses:

+OK unique-id listing follows
-ERR no such message

https://www.rfc-editor.org/rfc/rfc1939#page-12

Source

pub fn last_activity(&self) -> Option<Instant>

When the last communication with the server happened.

Returns None if there is no connection or the connection is not in the right state.

Source

pub async fn top(&mut self, msg_number: usize, lines: usize) -> Result<Bytes>

Source

pub fn is_deleted(&mut self, msg_number: &usize) -> bool

Check whether a given message is marked as deleted by the server.

If this function returns true then the message may still not exist.

§Examples:

let msg_number: u32 = 8;
let is_deleted = client.is_deleted(msg_number);
assert_eq!(is_deleted, false);

Source

pub async fn dele(&mut self, msg_number: usize) -> Result<Text>

§DELE

The POP3 server marks the message as deleted. Any future reference to the message-number associated with the message in a POP3 command generates an error. The POP3 server does not actually delete the message until the POP3 session enters the UPDATE state.

§Arguments:

a message-number (required) which may NOT refer to a message marked as deleted.

§Restrictions:

may only be given in the TRANSACTION state

§Possible Responses:

OK: message deleted
ERR: no such message

§Examples

let msg_number: u32 = 8;
let is_deleted = client.is_deleted(msg_number);

println!("{}", is_deleted);

Source

pub async fn rset(&mut self) -> Result<Text>

§RSET

If any messages have been marked as deleted by the POP3 server, they are unmarked.

§Arguments: none

§Restrictions:

May only be given in the TRANSACTION state

§Possible Responses:

+OK

https://www.rfc-editor.org/rfc/rfc1939#page-9

Source

pub async fn retr(&mut self, msg_number: usize) -> Result<Bytes>

§RETR

Retrieves the full RFC822 compliant message from the server and returns it as a byte vector

§Arguments:

A message-number (required) which may NOT refer to a message marked as deleted

§Restrictions:

May only be given in the TRANSACTION state

§Possible Responses:

OK: message follows
ERR: no such message

§Examples

extern crate mailparse;
use mailparse::parse_mail;

let response = client.retr(1).unwrap();

let parsed = parse_mail(&response);

let subject = parsed.headers.get_first_value("Subject").unwrap();

println!("{}", subject);

https://www.rfc-editor.org/rfc/rfc1939#page-8

Source

pub async fn list(&mut self, msg_number: Option<usize>) -> Result<ListResponse>

§LIST

If an argument was given and the POP3 server issues a positive response with a line containing information for that message. This line is called a “scan listing” for that message.

If no argument was given and the POP3 server issues a positive response, then the response given is multi-line. After the initial +OK, for each message in the maildrop, the POP3 server responds with a line containing information for that message. This line is also called a “scan listing” for that message. If there are no messages in the maildrop, then the POP3 server responds with no scan listings–it issues a positive response followed by a line containing a termination octet and a CRLF pair.

§Arguments:

a message-number (optional), which, if present, may NOT refer to a message marked as deleted

§Restrictions:

may only be given in the TRANSACTION state

§Possible responses:

+OK scan listing follows
-ERR no such message

Source

pub async fn stat(&mut self) -> Result<Stat>

§STAT

The POP3 server issues a positive response with a line containing information for the maildrop. This line is called a “drop listing” for that maildrop.

§Arguments: none

§Restrictions:

may only be given in the TRANSACTION state

§Possible responses:

+OK nn mm

Source

pub async fn apop<N: AsRef<str>, D: AsRef<str>>( &mut self, name: N, digest: D, ) -> Result<Text>

§APOP

Normally, each POP3 session starts with a USER/PASS exchange. This results in a server/user-id specific password being sent in the clear on the network. For intermittent use of POP3, this may not introduce a sizable risk. However, many POP3 client implementations connect to the POP3 server on a regular basis – to check for new mail. Further the interval of session initiation may be on the order of five minutes. Hence, the risk of password capture is greatly enhanced.

An alternate method of authentication is required which provides for both origin authentication and replay protection, but which does not involve sending a password in the clear over the network. The APOP command provides this functionality.

A POP3 server which implements the APOP command will include a timestamp in its banner greeting. The syntax of the timestamp corresponds to the `msg-id’ in [RFC822], and MUST be different each time the POP3 server issues a banner greeting. For example, on a UNIX implementation in which a separate UNIX process is used for each instance of a POP3 server, the syntax of the timestamp might be:

<process-ID.clock@hostname>

where `process-ID’ is the decimal value of the process’s PID, clock is the decimal value of the system clock, and hostname is the fully-qualified domain-name corresponding to the host where the POP3 server is running.

The POP3 client makes note of this timestamp, and then issues the APOP command. The name parameter has identical semantics to the name parameter of the USER command. The digest parameter is calculated by applying the MD5 algorithm [RFC1321] to a string consisting of the timestamp (including angle-brackets) followed by a shared

§Arguments:

a string identifying a mailbox and a MD5 digest string (both required)

§Restrictions:

may only be given in the AUTHORIZATION state after the POP3 greeting or after an unsuccessful USER or PASS command

§Possible responses:

+OK maildrop locked and ready
-ERR permission denied

Source

pub async fn auth<A: Authenticator + Sync>( &mut self, authenticator: A, ) -> Result<Text>

§AUTH

Requires an sasl::Authenticator to work. One could implement this themeselves for any given mechanism, look at the documentation for this trait.

If a common mechanism is needed, it can probably be found in the sasl module.

The AUTH command indicates an authentication mechanism to the server. If the server supports the requested authentication mechanism, it performs an authentication protocol exchange to authenticate and identify the user. Optionally, it also negotiates a protection mechanism for subsequent protocol interactions. If the requested authentication mechanism is not supported, the server should reject the AUTH command by sending a negative response.

The authentication protocol exchange consists of a series of server challenges and client answers that are specific to the authentication mechanism. A server challenge, otherwise known as a ready response, is a line consisting of a “+” character followed by a single space and a BASE64 encoded string. The client answer consists of a line containing a BASE64 encoded string. If the client wishes to cancel an authentication exchange, it should issue a line with a single “*”. If the server receives such an answer, it must reject the AUTH command by sending a negative response.

A protection mechanism provides integrity and privacy protection to the protocol session. If a protection mechanism is negotiated, it is applied to all subsequent data sent over the connection. The protection mechanism takes effect immediately following the CRLF that concludes the authentication exchange for the client, and the CRLF of the positive response for the server. Once the protection mechanism is in effect, the stream of command and response octets is processed into buffers of ciphertext. Each buffer is transferred over the connection as a stream of octets prepended with a four octet field in network byte order that represents the length of the following data. The maximum ciphertext buffer length is defined by the protection mechanism.

The server is not required to support any particular authentication mechanism, nor are authentication mechanisms required to support any protection mechanisms. If an AUTH command fails with a negative response, the session remains in the AUTHORIZATION state and client may try another authentication mechanism by issuing another AUTH command, or may attempt to authenticate by using the USER/PASS or APOP commands. In other words, the client may request authentication types in decreasing order of preference, with the USER/PASS or APOP command as a last resort.

§USER & PASS

To authenticate using the USER and PASS command combination, the client must first issue the USER command. If the POP3 server responds with a positive status indicator (“+OK”), then the client may issue either the PASS command to complete the authentication, or the QUIT command to terminate the POP3 session. If the POP3 server responds with a negative status indicator (“-ERR”) to the USER command, then the client may either issue a new authentication command or may issue the QUIT command.

The server may return a positive response even though no such mailbox exists. The server may return a negative response if mailbox exists, but does not permit plaintext password authentication.

When the client issues the PASS command, the POP3 server uses the argument pair from the USER and PASS commands to determine if the client should be given access to the appropriate maildrop.

Since the PASS command has exactly one argument, a POP3 server may treat spaces in the argument as part of the password, instead of as argument separators.