POP3 - Post Office Protocol

Topics
	POP3 Return Codes

Functions
int	POPGetResultCode (int fd, uint32_t timeout)
	Returns the result code of the previous POP3 operation.
int	POP3_InitializeSession (IPADDR server_address, uint16_t port, PCSTR UserName, PCSTR Password, uint32_t timeout)
	Create a connection to the POP3 server and log in.
int	POP3_CloseSession (int session)
	Close a POP3 session.
int	POP3_StatCmd (int session, uint32_t *num_messages, uint32_t *total_bytes, uint32_t timeout)
	Returns the status of the mailstore on the POP3 server.
int	POP3_ListCmd (int session, uint32_t message_number, uint32_t *total_bytes, uint32_t timeout)
	Get the size of a message on the server.
int	POP3_DeleteCmd (int session, uint32_t message_number, uint32_t timeout)
	Delete a pending message on the server.
int	POP3_RetrieveMessage (int session, uint32_t message_number, char *buffer, char **subject_ptr, char **body_ptr, int max_bufferlen, uint32_t timeout)
	Retrieve a message from the server.
PCSTR	GetPOPErrorString (int err)
	Returns the error text for an error code.
int	SSL_POP3_InitializeSession (IPADDR server_address, uint16_t port, PCSTR UserName, PCSTR PassWord, uint32_t time_out)
	Initialize Post Office Protocol Version 3 (POP3) on a SSL socket.

Detailed Description

#include< pop3.h>

Function Documentation

GetPOPErrorString()

PCSTR GetPOPErrorString

(

int

err

)

#include <pop3.h>

Returns the error text for an error code.

Parameters

err	Error number to decode

Returns

Pointer to a string containing the error code text

POP3_CloseSession()

int POP3_CloseSession

(

int

session

)

#include <pop3.h>

Close a POP3 session.

Parameters

session

The session number returned by POP3_InitializeSession()

Returns

POP3 Return Codes

POP3_DeleteCmd()

int POP3_DeleteCmd	(	int	session,
		uint32_t	message_number,
		uint32_t	timeout )

#include <pop3.h>

Delete a pending message on the server.

Note: the server will not actually delete the message until the session is closed.

Parameters

session	The session number returned by POP3_InitializeSession().
message_number	The message number to delete. The message number can be obtained by POP3_StatCmd().
timeout	Timeout in system Time Ticks.

Returns

Return code POP3 Return Codes

POP3_InitializeSession()

int POP3_InitializeSession	(	IPADDR	server_address,
		uint16_t	port,
		PCSTR	UserName,
		PCSTR	Password,
		uint32_t	timeout )

#include <pop3.h>

Create a connection to the POP3 server and log in.

Parameters

server_address	Server IP address
port	Server port number
UserName	Account username
Password	Account password
timeout	Timeout in system Time Ticks

Returns

The POP3 session number if greater than 0, otherwise error code POP3 Return Codes

See also

SSL_POP3_InitializeSession

POP3_ListCmd()

int POP3_ListCmd	(	int	session,
		uint32_t	message_number,
		uint32_t *	total_bytes,
		uint32_t	timeout )

#include <pop3.h>

Get the size of a message on the server.

Parameters

session	The session number returned by POP3_InitializeSession().
message_number	The message number to query. The message number can be obtained by POP3_StatCmd().
total_bytes	Pointer to the variable in which to store the total number of bytes of the pending message.
timeout	Timeout in system Time Ticks.

Returns

Return code POP3 Return Codes

POP3_RetrieveMessage()

int POP3_RetrieveMessage	(	int	session,
		uint32_t	message_number,
		char *	buffer,
		char **	subject_ptr,
		char **	body_ptr,
		int	max_bufferlen,
		uint32_t	timeout )

#include <pop3.h>

Retrieve a message from the server.

The message is retrieved as a block of bytes including the header, subject, etc. The headers will appear first. Note that the message is left on the server and will not be deleted until the POP3_DeleteCmd() function is called for the message number.

Parameters

session	The session number returned by POP3_InitializeSession().
message_number	The message number to retrieve. The message number can be obtained by POP3_StatCmd().
buffer	Pointer to the buffer to store the entire message, including headers
subject_ptr	If not NULL, a pointer to the start of the subject in the message buffer
body_ptr	If not NULL, a pointer to the start of the body in the message buffer
max_bufferlen	Maximum length of the buffer
timeout	Timeout in system Time Ticks.

Returns

Return code POP3 Return Codes

POP3_StatCmd()

int POP3_StatCmd	(	int	session,
		uint32_t *	num_messages,
		uint32_t *	total_bytes,
		uint32_t	timeout )

#include <pop3.h>

Returns the status of the mailstore on the POP3 server.

Parameters

session	The session number returned by POP3_InitializeSession()
num_messages	Pointer to the variable in which to store the number of pending messages
total_bytes	Pointer to the variable in which to store the total number of bytes of the pending messages
timeout	Timeout in system Time Ticks

Returns

Return code POP3 Return Codes

POPGetResultCode()

int POPGetResultCode	(	int	fd,
		uint32_t	timeout )

#include <pop3.h>

Returns the result code of the previous POP3 operation.

Parameters

fd	TCP socket file descriptor for the active session
timeout	Timeout in system Time Ticks

Returns

POP3 Return Codes

SSL_POP3_InitializeSession()

int SSL_POP3_InitializeSession	(	IPADDR	server_address,
		uint16_t	port,
		PCSTR	UserName,
		PCSTR	PassWord,
		uint32_t	time_out )

#include <ssl_pop3.h>

Initialize Post Office Protocol Version 3 (POP3) on a SSL socket.

Note: Routine makes the connection to the POP server and logs in with the provided UserName and PassWord. Session is release with POP3_CloseSession in pop3.h.

Post Office Protocol, Version 3 (POP3) is defined in RFC1939.

Parameters

server_address	IP address of the server.
port	Port to connect to the server.
UserName	Account user name string.
PassWord	Account password string.
time_out	Number of ticks to wait.

Return values

>=0	The session handle
<0	Error code from POP3 Return Codes

See also

POP3_InitializeSession