Indy 9 | Content | Index | Reference

TIdPOP3
Hierarchy, Properties, Methods, Events, See Also, Unit: IdPOP3
Implements a POP3 client.

    TIdPOP3 = class(TIdMessageClient)

Unit
IdPOP3
Description
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.

TIdPOP3.APOP
TIdPOP3, See Also
Indicates that alternate authentication using a 128-bit MD5 hash value is desired.

    property APOP: Boolean;

Description
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.

TIdPOP3.Password
TIdPOP3, See Also
Password for the POP3 account.

    property Password;

Description
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.

TIdPOP3.Port
TIdPOP3
Port number for the client connection to the POP3 server.

    property Port: integer;

Description
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.

TIdPOP3.Username
TIdPOP3, See Also
User identitity for the POP3 account.

    property Username;

Description
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.

TIdPOP3.CheckMessages
TIdPOP3, See Also
Gets the number of messages in a mailbox on the POP3 server.

    function CheckMessages: longint;

Return Value
LongInt - Number of messages in a mailbox on the POP3 server.
Description
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.

TIdPOP3.Connect
TIdPOP3
Opens a POP3 client connection.

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

Parameters
const ATimeout: Integer = IdTimeoutDefault
Number of milliseconds to wait for a valid connection. Default value is IdTimeoutDefault.
Description
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.

TIdPOP3.Create
TIdPOP3
Constructor for the object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the object instance.
Description
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).

TIdPOP3.Delete
TIdPOP3, See Also
Marks a message for deletion on the POP3 server.

    function Delete(const MsgNum: Integer): Boolean;

Parameters
const MsgNum: Integer
Message number to be removed.
Return Value
Boolean - True when the result is wsOK.
Description
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.

TIdPOP3.Disconnect
TIdPOP3
Closes the socket connection to the POP3 server.

    procedure Disconnect; override;

Description
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.

TIdPOP3.GetResponse
TIdPOP3, See Also
Provides numeric response codes for POP3 protocol requests.

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

Parameters
const AAllowedResponses: array of SmallInt
Response code or codes expected or allowed in the protocol response.
Return Value
SmallInt - Numeric response code for the response.
Description
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.

TIdPOP3.KeepAlive
TIdPOP3
Prevents a connection timeout.

    procedure KeepAlive;

Description
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.

TIdPOP3.Reset
TIdPOP3, See Also
Reset messages marked for deletion.

    function Reset: Boolean;

Return Value
Boolean - True on success, False on error.
Description
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.

TIdPOP3.Retrieve
TIdPOP3, See Also
Retrieves a message by number.

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

Parameters
const MsgNum: Integer
Message number to retrieve from the server.
AMsg: TIdMessage
Message instance where the values will be stored.
Return Value
Boolean - True on success.
Description
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.

TIdPOP3.RetrieveHeader
TIdPOP3
Retrieves headers for a message.

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

Parameters
const MsgNum: Integer
Message number to be retrieved.
AMsg: TIdMessage
Message instance where headers will be stored.
Return Value
Boolean - True on success.
Description
RetrieveHeader is a Boolean function that retrieves the headers of the message number specified in MsgNum and stores the values in the AMsg instance.

TIdPOP3.RetrieveMailBoxSize
TIdPOP3
Gets the mailbox size on the POP3 server.

    function RetrieveMailBoxSize: integer;

Return Value
Integer - Mailbox size in bytes, or -1 on error.
Description
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.

TIdPOP3.RetrieveMsgSize
TIdPOP3, See Also
Gets the size of a message.

    function RetrieveMsgSize(const MsgNum: Integer): Integer;

Parameters
const MsgNum: Integer
Message number to examine.
Return Value
Integer - Number of bytes in the message.
Description
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.

TIdPOP3.RetrieveRaw
TIdPOP3, See Also
Retrieves message headers and body without performing MIME decoding.

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

Parameters
const MsgNum: Integer
Message number to be retrieved.
const Dest: TStrings
Destination used to store the message in raw format.
Return Value
Boolean - True when message retrieval is successful.
Description
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.

TIdPOP3.UIDL
TIdPOP3, See Also
Retieves the unique-id listing for one or all messages in the mailbox.

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

Parameters
const ADest: TStrings
Container for UID values in the listing.
const AMsgNum: Integer = -1
The message number desired, or all messages when the value is -1. Default value is -1.
Return Value
Boolean - True on success.
Description
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.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.