TIdIMAP4.RetrievePartToFilePeek Method (Integer, string, Integer, string, string)

Retrieves and stores a message part for a message in the specified local file without updating message flags stored on the remote IMAP4 server.

Pascal

function RetrievePartToFilePeek(
    const AMsgNum: Integer; 
    const APartNum: string; 
    ALength: Integer; 
    ADestFileNameAndPath: string; 
    AContentTransferEncoding: string
): Boolean; overload;

Parameters

Parameters	Description
AMsgNum	relative message number for the message.
APartNum	relative part number for the message part.
ALength	size of message part as indicated in the IMAP4 server response.
ADestFileNameAndPath	name of the file (including the optional path) used to store the contents of the message part.
AContentTransferEncoding	content transfer encoding expected for the specified message part.

Returns

Boolean - True on success.

Description

RetrievePartToFilePeek is a Boolean function used to retrieve a specific message part for the specified message, and to store the message parts contents in the specified local file name. RetrievePartToFilePeek is similar to RetrievePartToFile, but does not update the message flags stored on the remote IMAP4 server. Specifically, it does not affect the 'Seen' flag when accessing the message and/or message parts.

AMsgNum is the relative message number for the message as stored in the currently selected mailbox on the remote IMAP4 server.

APartNum is the relative part number for the message part in the structure for the message.

ALength is the size of message part as indicated in the IMAP4 server response.

ADestFileNameAndPath is the name of the file (including the optional path) used to store the contents of the message part.

AContentTransferEncoding is the content transfer encoding expected for the specified message part.

Use RetrieveStructure 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 RetrievePartToFilePeek.

RetrievePartToFilePeek validates the message number in AMsgNum to ensure that it contains a positive non-zero value, and raises an EIdNumberInvalid exception if the requirement is not met.

RetrievePartToFilePeek validates the message part number in APartNum to ensure that it contains a valid value, and raises an EIdNumberInvalid exception if the requirement is not met.

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

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

The return value for the method is True if the message part is successfully retrieved for the specified message. The return value for the method is False if a protocol error response is received (any value other than IMAP_OK) or the value in ADestFileNameAndPath is an empty string ('').

Please note that the destination file specified in ADestFileNameAndPath will contain the decoded content for the message part after reversing the encoding algorithm specified in AContentTransferEncoding.

Use RetrievePartToFile or UIDRetrievePartToFile to retrieve a message part to a file and to update the stored message flags for the message.

Use RetrievePart or UIDRetrievePart to retrieve a message part and to update the stored message flags for the message.