TIdIMAP4.Retrieve Method

Retrieves a message from a mailbox and marks it as read on the server.

Pascal

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

Parameters

Parameters	Description
AMsgNum	Message number to retreive from the mailbox.
AMsg	Stores the retrieved message headers, body, and attachments.

Returns

Boolean - True on success.

Description

Retrieve is a Boolean function that retrieves the entire contents for a message from a mailbox and marks it as read on the remote IMAP4 server. Retrieve requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

Retrieve calls a protected method that sends the IMAP4 FETCH command for the message number specified in AMsgNum. Retrieve performs validation for the relative message number to ensure that it contains a positive non-zero value. An EIdNumberInvalid exception can be raised if the relative message number in aMsgNum is invalid.

On successful retrieval of the RFC 822 envelope data, Retrieve calls ReceiveHeader and ReceiveBody to load the message contents into the TIdMessage instance specified by AMsg. All headers, message parts, and the body of the message instance are cleared prior to storing values retrieved from the remote IMAP4 server. The value of the UID and Flags properties for the message in AMsg are updated based on the values found in the IMAP4 server response.

Todo

Update to reflect optional UID and Flags usage.

Retrieve creates an internal TIdTCPStream instance to read message parts in the serve response, and assigns event handlers for the operation using procedure stored in OnWorkBeginForPart, OnWorkForPart, and OnWorkEndForPart.

Retrieve sets the return value to True when the IMAP4 server response contains the value IMAP_OK.

Use SelectMailBox or ExamineMailBox to select a mailbox and retrieve messages or headers in Mailbox prior to calling the Retrieve method.

Use on of the UIDRetrieveXxx methods to retrieve messages using the unique identifier (UID) for a message in the selected mailbox.