TIdIMAP4.UIDRetrievePartPeek Method (String, Integer, TIdBytes, Integer, string)

Retrieves a specified message part without affecting the flags stored for the message.

Pascal

function UIDRetrievePartPeek(
    const AMsgUID: String; 
    const APartNum: Integer; 
    var ABuffer: TIdBytes; 
    var ABufferLength: Integer; 
    AContentTransferEncoding: string = 'text'
): Boolean; overload;

Parameters

Parameters	Description
AMsgUID	Unique identifier for the message with the desired message part.
APartNum	Relative part number for the message part.
ABuffer	Buffer for storing the retrieve message part.
ABufferLength	SIze of the buffer need to store the message part.
AContentTransferEncoding	Content transfer encoding applied to the stored message part.

Returns

Boolean - True on success.

Description

UIDRetrievePartPeek is an overloaded Boolean function used to retrieve a message part for a specific message without affecting the flags stored on the remote IMAP4 server for the message.

AMsgUID is the unique identifier (UID) for the message stored in the current mailbox on the remote IMAP4 server.

APartNum is the relative part number for the requested message part.

Use RetrieveStructure or UIDRetrieveStructure to find the message parts available for a specific message, and the content transfer encoding used for each of the message parts. Use the message part number (the relative position of the message part) and the content transfer encoding when calling RetrievePart or RetrievePartPeek.

ABuffer is the storage to use for the retrieved message part after decoding the message content using the algorithm specified in AContentTransferEncoding.

On successful retrieval of the message part, the values in ABuffer and ABufferLength are updated to reflect the message part content and length (respectively). Please note that the caller is responsible for freeing the memory allocated in ABuffer by calling FreeMem.

UIDRetrievePartPeek validates the message identifier in AMsgUID to ensure that it contains a valid value, and raises an EIdNumberInvalid exception if the requirement is not met.

UIDRetrievePartPeek requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised. Use SelectMailBox or ExamineMailBox to select a mailbox prior to calling RetrievePartPeek or UIDRetrievePartPeek.

UIDRetrievePartPeek sends the IMAP4 FETCH command to retrieve the specified message part, and retrieves the message part content using a TIdTCPStream instance. UIDRetrievePartPeek assigns the event handlers in OnWorkBeginForPart, OnWorkForPart, and OnWorkEndForPart to the TIdTCPStream instance to respond to work events occurring during message part retrieval.

After retrieval of the message part, ABuffer will contain the decoded message part content and ABufferLength will contain the length of the decoded message part.

Please note that UIDRetrievePartPeek does not affect the message flags stored for the message. Specifically, it allows accessing the message parts without setting the 'Seen' message flag that indicates the message has been read.

Use RetrievePart or UIDRetrievePart to retrieve (and mark as seen) a specific message part.

Use RetrievePartToFilePeek or UIDRetrievePartToFilePeek to capture and store an unseen message part into a file on the local system.

Use RetrievePeek or UIDRetrievePeek to perform similar processing for the entire contents of a specified message.