TIdIMAP4.GetInternalResponse Method

Reads mutiple untagged responses or a single tagged response from the server.

Pascal

function GetInternalResponse(
    const ATag: String; 
    AExpectedResponses: array of String; 
    ASingleLineMode: Boolean; 
    ASingleLineMayBeSplit: Boolean = False
): string; overload; reintroduce;

Parameters

Parameters	Description
ATag	Command tag expecetd in the IMAP4 response.
AExpectedResponses	Success values for the current response.
ASingleLineMode	Caller wants only the first line of the server response.
ASingleLineMayBeSplit	The first line may contain values split among one or more lines. Default value is False.

Returns

String - Text from the server response.

Description

GetInternalResponse is a procedure that implements reading of tagged and untagged IMAP4 responses from the remote IMAP4 server. GetInternalResponse is called from the implementation of the GetResponse method.

GetInternalResponse creates and maintains a TStringList that is used to capture the response line(s) from the IMAP4 server using ReadLnWait. GetInternalLineResponse will read multiple untagged responses until the tagged response in ATag is encountered, or a single tagged response line having the value in ATag.

ASingleLineMode indicates if the caller wants only the first line in the IMAP4 response. For instance, the caller may be looking only for "* FETCH (blah blah)", because he needs to parse that line to figure out how the rest will follow. This arises with a number of the FETCH commands where the caller needs to get the byte-count from the first line before he can retrieve the rest of the response.

Note "FETCH" would have to be in AExpectedResponses.

When ASingleLineMode contains False, the caller wants everything up to and including the reply terminator (e.g. "C45 OK Completed").

In ASingleLineMode, we ignore any lines that dont have one of AExpectedResponses at the start, otherwise we add all lines to .Text and later strip out any lines that dont have one of AExpectedResponses at the start.

ASingleLineMayBeSplit (which should only be used with ASingleLineMode = True) deals with the (unusual) case where the server cannot or does not fit a single-line response onto one line. This arises when FETCHing the BODYSTRUCTURE, which can be very long. The server (Courier, anyway) signals it by adding a byte-count to the end of the first line, that would not normally be present.

For example, for normal short responses, the server would send:

FETCH (BODYSTRUCTURE (Part1 Part2))

but if it splits it, it sends:

FETCH (BODYSTRUCTURE (Part1 {16} Part2))

The number in the chain brackets {16} seems to be random.

WARNING: If you use ASingleLineMayBeSplit on a line that is EXPECTED to end with a byte-count, the code will break, so don't use it unless absolutely necessary.

GetInternalResponse handles server response lines that include the "BYE" command that indicates pending disconnection from the server. If the value "BYE" is not included in AExpectedResponses, the disconnection is not expected and causes the value in ConnectionState to be set to csUnexpectedlyDisconnected. An EIdDisconnectedProbablyIdledOut is raised in this circumstance.

GetInternalResponse calls LastCmdResult.ParseResponse using the command tag in ATag and the TStringList containing response lines to prepare the response for use in the IMAP4 client. GetInternalResponse frees the TStringList prior to exiting from the method.