TIdIMAP4.UIDRetrievePartToFile Method (String, Integer, Integer, string, string)

Retrieves and stores a message part for a message in the specified local file.

Pascal

function UIDRetrievePartToFile(
    const AMsgUID: String; 
    const APartNum: Integer; 
    ALength: Integer; 
    ADestFileNameAndPath: string; 
    AContentTransferEncoding: string
): Boolean; overload;

Parameters

Parameters	Description
AMsgUID	Unique identifier (UID) for the desired 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

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

AMsgUID is the unique identifier (UID) 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 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 RetrievePartToFile.

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

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

UIDRetrievePartToFile 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 RetrievePartToFile.

UIDRetrievePartToFile sends the IMAP4 FETCH command to retrieve the specified message part, and retrieves the message part content using a TIdTCPStream instance. UIDRetrievePartToFile 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 RetrievePartToFilePeek or UIDRetrievePartToFilePeek to retrieve a message part to a file without affecting 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.