Struct pop3_client::Client

pub struct Client { /* fields omitted */ }

The key structure for the crate, delineating capabilities of the POP3 client as per the protocol RFC

Errors and problems

All the methods this Client has are susceptible to errors. The common reasons for those are:

• Not possible to establish connection
• The server does not support the protocol
• Connection aborted
• Some data got lost or modified, and now it's not possible to decode the obtained message
• The server does not recognize the command. This might happen even if by RFC, the command is mandatory, as most of the servers do not follow the protocol letter by letter
• The command was sent on the wrong stage. In other words, you tried to do something before you authorized.
• The server returned an error response. We'll look at those within each separate method

To find out more, read the output of the error you've got -- it's always a string!

Methods

impl Client

pub fn connect(host: &str, port: u16) -> Result<Self>

Connect to given host and port.

This is the simplest way to initiate connection, so it's preferable to use it in a straightforward manner unless you have specific ClientConfig reservations.

Example

let client = Client::connect("my.host.com", 110)?;

pub fn login(&mut self, username: &str, password: &str) -> Result<()>

Authorization through plaintext login and password

Example

client.login("sweet_username", "very_secret_password")?;

Errors

The server may return an error response if:

• the username was not found
• the password does not match the username
• the connection to this mailbox has been locked by another device -- so you won't be able to connect until the lock is released.

pub fn quit(self) -> Result<()>

End the session, consuming the client

Example

client.quit()?;
client.noop()?; // Shouldn't compile, as the client has been consumed upon quitting

pub fn stat(&mut self) -> Result<(u32, u32)>

Display the statistics for the mailbox (that's what the STAT command does).

In the resulting u32 tuple, the first number is the number of messages, and the second one is number of octets in those messages.

Example

let (messages, octets) = client.stat()?;
assert_eq!(messages, 2);
assert_eq!(octets, 340);

pub fn list(&mut self, msg: Option<u32>) -> Result<String>

Show the statistical information on a chosen letter, or all letters. The information in question always required to start with the letter size, but use of additional stats is not regimented in any way.

Example

let single_stats = client.list(Some(1))?; // show info on the letter number 1
let all_stats = client.list(None)?; // show info on all letters

Errors

The server may return an error response if:

• The letter under the given index does not exist in the mailbox
• The letter under the given index has been marked deleted

pub fn retr(&mut self, msg: u32) -> Result<String>

Show the full content of the chosen message

Example

let letter_content = client.retr(5)?;

Errors

The server may return an error response if:

• The letter under the given index does not exist in the mailbox
• The letter under the given index has been marked deleted

pub fn dele(&mut self, msg: u32) -> Result<String>

Mark the chosen message as deleted

Example

client.dele(3)?; // now, the THIRD message is marked as deleted, and no new manipulations on it are possible

Errors

The server may return an error response if:

• The letter under the given index does not exist in the mailbox
• The letter under the given index has been marked deleted

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

Do nothing and return a positive response

Example

assert!(client.noop().is_ok());

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

Reset the session state, unmarking the items marked as deleted

Example

client.dele(3)?;
client.dele(4)?;
client.rset()?; // undo all the previous deletions

pub fn top(&mut self, msg: u32, n: u32) -> Result<String>

Show top n lines of a chosen message

Example

let top = client.top(1, 2)?; // Get TWO first lines of the FIRST message

Errors

The server may return an error response if:

• The letter under the given index does not exist in the mailbox
• The letter under the given index has been marked deleted

pub fn uidl(&mut self, msg: Option<u32>) -> Result<String>

Show the unique ID listing for the chosen message or for all the messages. Unlike message numbering, this ID does not change between sessions.

Example

let uidl_all = client.uidl(None)?;
let uidl_one = client.uidl(Some(1));

Errors

The server may return an error response if:

• The letter under the given index does not exist in the mailbox
• The letter under the given index has been marked deleted

pub fn apop(&mut self, name: &str, digest: &str) -> Result<String>

Authorise using the APOP method

Refer to the POP3 RFC for details.

Example

client.apop("another_sweet_username", "c4c9334bac560ecc979e58001b3e22fb")?;

Errors

The server will return error if permission was denied.