Implements a POP3 client.

TIdPOP3 = class(TIdMessageClient)

TIdPOP3 is a TIdMessageClient descendant that provides a client implementation of the Post Office Protocol version 3 (POP3) as described in the Internet Standards document:

• RFC 1939 - Post Office Protocol Version 3

TIdPOP3 is used to retrieve E-Mail messages on a mail server and return the messages to the user's computer. TIdPOP3 provides methods and properties that allow a client account to connect to a POP3 server, and to retreive various information about the size and contents of a mail box or email message.

TIdPOP3 is not intended to provide extensive manipulation operations of mail on the server; normally, mail is downloaded and then deleted. Use TIdIMAP4 and TIdIMAP4Server when a more advanced (and complex) mail protocol is required.

Indicates that alternate authentication using a 128-bit MD5 hash value is desired.

property APOP: Boolean;

APOP is a Boolean property and indicates if the TIdPOP3 client wants to use the alternate authentication method providing secure password exchange over the network. APOP authentication involves the use of a 128-bit TIdHashMessageDigest5 value calculated from the message-id timestamp and the shared secret that is the password for the client session. APOP authentication can be used when the APOP property contains True and the server implementation supports the capability.

The value in APOP is used in the Connect method, and requires that the server include the APOP message-id timestamp required for the APOP authentication exchange. When APOP is True and the server does not support APOP authentication, an EIdException will be raised with the RSPOP3ServerDoNotSupportAPOP message. When APOP is False, normal Username and Password authentication is used.

Password for the POP3 account.

property Password;

Password is a String property that represents the password used for the POP3 account. Username and Password are used in Connect to provide account authentication on the POP3 server connection.

Port number for the client connection to the POP3 server.

property Port: integer;

Port is an Integer property that represents the port number used for connecting to a POP3 server. Port is published in TIdPOP3 to allow streaming of the default value used by the POP3 protocol (IdPORT_POP3).

Use Host to specifiy the IP address or host name of the POP3 server used in the client connection.

User identitity for the POP3 account.

property Username;

Username is a String property that represents the account identity used for the POP3 account. Username and Password are used in Connect to provide account authentication on the POP3 server connection.

Gets the number of messages in a mailbox on the POP3 server.

function CheckMessages: longint;

LongInt - Number of messages in a mailbox on the POP3 server.

CheckMessages is a LongInt function that returns the total number of messages currently in a mailbox on the POP3 server. CheckMessages performs the POP3 STAT command to retrieve the current message count from the POP3 server.

CheckMessages will return 0 (zero) if an exception is raised during execution of the method. Otherwise, the return vaslue for the method is set to numeric value reurned in the text portion of LastCmdResult.

Opens a POP3 client connection.

procedure Connect(const ATimeout: Integer = IdTimeoutDefault); override;

Number of milliseconds to wait for a valid connection. Default value is IdTimeoutDefault.

Connect is a procedure used to establish a connection to the POP3 server with the address and port number specified in Host and Port. Connect calls the inherited Connect method and waits for a valid connection for ATimeout milliseconds prior to sending account information for the connection. Username and Password must be assigned prior to calling the Connect method.

If an exception occurs during connection or authentication, the socket will Disconnect and the exception will be re-raised.

Use Disconnect to close the POP3 client connection.

Constructor for the object instance.

constructor Create(AOwner: TComponent); override;

Owner of the object instance.

Create is the constructor for the object instance, and relies on the inherited Create method. Create sets the Port property to the default value used for the POP3 protocol (IdPORT_POP3).

Marks a message for deletion on the POP3 server.

function Delete(const MsgNum: Integer): Boolean;

Message number to be removed.

Boolean - True when the result is wsOK.

Delete is a Boolean function that marks a message on the POP3 server for deletion using the message number specified in MsgNum. If a non-existent message number is used, an exception is raised. Delete uses the POP DELE command to mark the indicated message number for deletion. Messages marked for deletion on the POP3 server will be physically removed when Disconnect is called.

Delete returns True when the numeric result for the operation , as indicated by LastCmdResult, contains the value wsOk.

Closes the socket connection to the POP3 server.

procedure Disconnect; override;

Disconnect is a procedure that closes the client socket connection to the POP3 server. All messages marked for deletion on the POP3 server will be physically removed from the server mailbox. Disconnect performs the POP3 QUIT command to close the POP3 protocol session prior to calling the inherited Disconnect method.

Provides numeric response codes for POP3 protocol requests.

function GetResponse(const AAllowedResponses: array of SmallInt): SmallInt; override;

Response code or codes expected or allowed in the protocol response.

SmallInt - Numeric response code for the response.

GetResponse is an overridden SmallInt function in TIdPOP3, and allows the POP3 client implementation to provide numeric response codes in a fashion consistent with other RFC-based protocols.

Note: The POP3 protocol does not provide numeric response codes, but instead uses '+OK' and '-ERR' in protocol response messages. GetResponse is overridden to capture these alphabetic responses, and convert them into the values wsOk and wsErr which are stored in the numeric portion of the LastCmdResult property.

AAllowedResponses is an Array of SmallInt values that represents response codes expected and/or allowed in the protocol request. GetResponse will raise an EIdException with the constant value RSUnrecognizedPOP3ResponseHeader if a response code other than wsOk or wsErr is received for the request.

GetResponse calls the inherited method CheckResponse using the numeric value in LastCmdResult.NumericCode and AAllowedResponses prior to exiting from the method.

Prevents a connection timeout.

procedure KeepAlive;

KeepAlive is a procedure used to insure that the POP3 protocol session remains open and valid. KeepAlive sends the POP3 NOOP command to avoid a session timeout for the POP3 client. TIdPOP3 can use KeepAlive when performing time consuming operations, such as maintaining mail folders and messages on local file system, after the POP3 session has be started in Connect.

Reset messages marked for deletion.

function Reset: Boolean;

Boolean - True on success, False on error.

Reset is a Boolean function that clears the deletion flag for any messages that have been marked for deletion. Reset performs the POP3 RSET command to remove the deletion flag for messages on the POP3 server. Note: Some POP3 servers do not support the POP3 RSET command.

The return value for Reset will be True when the numeric result in LastCmdResult contains wsOk. If an error occurs, the return value will be False.

Retrieves a message by number.

function Retrieve(const MsgNum: Integer; AMsg: TIdMessage): Boolean;

Message number to retrieve from the server.

Message instance where the values will be stored.

Boolean - True on success.

Retrieve is a Boolean function that retrieves the message with the message number idemtified in MsgNo, and stores the result in a TIdMessage component. Retrieve executes the POP3 RETR command, and checks for the wsOK response from the server prior to processing the contents of the message. Retrieve calls ReceiveHeader to load RFC message headers into AMsg, and on success, calls ReceiveBody to load the message body parts into AMsg.

Retrieves headers for a message.

function RetrieveHeader(const MsgNum: Integer; AMsg: TIdMessage): Boolean;

Message number to be retrieved.

Message instance where headers will be stored.

Boolean - True on success.

RetrieveHeader is a Boolean function that retrieves the headers of the message number specified in MsgNum and stores the values in the AMsg instance.

Gets the mailbox size on the POP3 server.

function RetrieveMailBoxSize: integer;

Integer - Mailbox size in bytes, or -1 on error.

RetrieveMailBoxSize is an Integer function that retrieves the total size of the mailbox on the POP server. The value is returned in bytes. RetrieveMailBoxSize will return 0 when the mailbox is empty, or -1 when an exception is raised.

RetrieveMailBoxSize uses the POP3 LIST command to accumulate the total mailbox size from the values returned for individual messages.

Gets the size of a message.

function RetrieveMsgSize(const MsgNum: Integer): Integer;

Message number to examine.

Integer - Number of bytes in the message.

RetrieveMsgSize is an Integer function that retrieves the size of the message specified in MsgNum in the POP3 mailbox. The return value for RetrieveMsgSize is expressed in bytes, and may contain -1 if an error occurs wile trying to access the mailbox or the specified message number on the POP3 server.

RetrieveMsgSize executes the POP3 LIST command with the message number identified in MsgNum. RetrieveMsgSize will extract the numeric message size from the text returned in the LastCmdResult property, or -1 when a server or a protocol error is encountered.

Retrieves message headers and body without performing MIME decoding.

function RetrieveRaw(const MsgNum: Integer; const Dest: TStrings): boolean;

Message number to be retrieved.

Destination used to store the message in raw format.

Boolean - True when message retrieval is successful.

RetrieveRaw is a Boolean function that retrieves POP3 message headers without performing MIME decoding for the header values. RetrieveRaw uses the POP3 RETR command to intitiate message retrieval. Header values are obtained using Capture.

Use RetrieveHeader to get the parsed message headers and store the result in a TIdMessage instance. Use Retrieve to get an entire message and store the result in a TIdMessage instance.

Retieves the unique-id listing for one or all messages in the mailbox.

function UIDL(const ADest: TStrings; const AMsgNum: Integer = -1): Boolean;

Container for UID values in the listing.

The message number desired, or all messages when the value is -1. Default value is -1.

Boolean - True on success.

UIDL is a Boolean function used to retrieve the unique-id listing for one or all messages in the POP3 mailbox. When AMsgNum is specified, UIDL will request the UIDL for the specified message number. Otherwise, all message numbers in the mailbox are requested from the POP3 server.

UIDL calls SendCmd with the POP3 UIDL command and the optional message number. When the response code from SendCmd is wsOk, the response values are stored in Dest. Value from the POP3 UIDL command consist of the message number folowed by a space character and the unique-id for the message. The unique-id of a message is an arbitrary server-determined string, consisting of one to 70 characters in the range 0x21 to 0x7E, and uniquely identifies a message within a POP3 mailbox. Messages marked as deleted are not included in a UIDL listing.