TIdIMAP4.UIDRetrievePeek Method

Retrieves a message from a mailbox without marking it as read on the server.

Pascal

function UIDRetrievePeek(
    const AMsgUID: String; 
    AMsg: TIdMessage
): Boolean;

Parameters

Parameters	Description
AMsgUID	Unique identifier for the desired message.
AMsg	Stores the retrieved message headers, body, and attachments.

Returns

Boolean - True on success.

Description

UIDRetrievePeek is a Boolean function that retrieves the entire contents for a message from a mailbox without marking it as read on the remote IMAP4 server.

Please note that "Peek" versions of the IMAP4 functions do NOT set the mfSeen message flag. A new message in your inbox should not have set the mfSeen flag until you retrieve the message via a function such as Retrieve. You can, however, retrieve the message via RetrievePeek, which should not set the mfSeen flag. The situation is not so clear, however, if you retrieve the third attachment (only) of an email. All the "Peek" versions of TIdIMAP4 functions do imply that the mfSeen flag NOT be set. Be aware that IMAP4 server support for the "Peek" functionality may vary.

UIDRetrievePeek requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

UIDRetrievePeek calls a protected method that sends the IMAP4 FETCH command for the message number specified in AMsgNum. UIDRetrievePeek performs validation for the unique message identifier to ensure that it contains a valid value. An EIdNumberInvalid exception can be raised if the condition is not met.

On successful retrieval of the RFC 822 envelope data, UIDRetrievePeek 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.

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

UIDRetrievePeek 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, UIDRetrieve, RetrievePeek, or UIDRetrievePeek methods.

Use on of the RetrieveXxx methods to retrieve message(s) using the relative message number for a message in the selected mailbox.