Indy 9
TIdIMAP4
Hierarchy, Properties, Methods, Events, See Also, Unit: IdIMAP4
Implements an Internet Message Access Protocol version 4.1 client.
TIdIMAP4 = class(TIdMessageClient)
Unit
IdIMAP4
Description
TIdIMAP4 is a TIdMessageClient descendant that implements a client for the IMAP4 (Internet Message Access Protocol version 4.1) protocol, as described in the Internet standards document:

  • RFC 2060 - Internet Message Access Protocol version 4.1 (http://www.rfc-editor.org/rfc/rfc2060.txt)

The Internet Message Access Protocol, Version 4.1 (IMAP4rev1) allows a client to access and manipulate electronic mail messages on an IMAP4 server. IMAP4 permits manipulation of remote message folders, called "mailboxes", in a way that is functionally equivalent to local mailboxes.

IMAP4rev1 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; permanently removing messages; setting and clearing flags; RFC 822 and MIME message parsing; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev1 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers.

IMAP4rev1 does not specify a means of posting mail; message posting is handled by a mail transfer protocol such as TIdSMTP.

The IMAP4 protocol allows the client to issue multiple commands before expecting a server response. In addition, server responses may not necessarily be received in the order in which the IMAP commands are issued on the client. Finally, IMAP4 responses differ from TCP-related response codes in both format and content. To accomodate these protocol differences, methods inherited from TIdTCPConnection are reimplemented to support the specifics or the IMAP protocol for sending commands and receiving responses.


TIdIMAP4.ConnectionState
TIdIMAP4, See Also
Indicates the IMAP4 connection state.
property ConnectionState: TIdIMAP4ConnectionState;
Description
ConnectionState is a read-only TIdIMAP4ConnectionState property that indicates the state of the IMAP4 connection. AN IMAP4 connection can exist in one of the following states: Non-Authenticated, Authenticated, Selected, and Logout. ConnectionState is used to determine which IMAP commands are valid for the indicated state.

ConnectionState can contain one the follwing TIdIMAP4ConnectionState values:

  • csAny - Commands allowed in any connection state.

  • csNonAuthenticated - Commands allowed prior to establishing authentication and entering an authenticated state.

  • csAuthenticated - Commands allowed after authentication but prior to mailbox selection.

  • csSelected - Commands allowed after selecting a mailbox.

csAny permits the commands cmdCAPABILITY, cmdNOOP, and cmdLOGOUT.

csNonAuthenticated permits commands from the csAny connection state, as well as the commands cmdAUTHENTICATE and cmdLOGOUT.

csAuthenticated permits commands from the csNonAuthenticated connection state, as well as the commands cmdSELECT, cmdEXAMINE, cmdCREATE, cmdDELETE, cmdRENAME, cmdSUBSCRIBE, cmdUNSUBSCRIBE, cmdLIST, cmdLSUB, cmdSTATUS, and cmdAPPEND.

csSelected permits commands from the csAuthenticated connection state, as well as the commands cmdCHECK, cmdCLOSE, cmdEXPUNGE, cmdSEARCH, cmdFETCH, cmdSTORE, cmdCOPY, cmdUID, and the experimental/expansion commmands represented by cmdXCmd.


TIdIMAP4.MailBox
TIdIMAP4, See Also
Represents the IMAP4 mailbox.
property MailBox: TIdMailBox;
Description
MailBox is a TIdMailBox property that represents the IMAP4 mailbox including Attributes, Flags, and Messages stored on the IMAP4 server. MailBox is assigned in either the SelectMailBox or ExamineMailBox methods, and can be updated by methods that select, retrieve or update messages on the IMAP4 server.

TIdIMAP4.MailBoxSeparator
TIdIMAP4
Identifies the character used to separate mailbox in the hierarchical mailbox namespace.
property MailBoxSeparator: Char;
Description
MailBoxSeparator is a Char property that represents the character used to separate levels of hierarchy in a hierarchical mailbox namespace. In Indy, the default value for MailBoxSeparator is '/'.

The namespace consists of an optional namespace character '#' and namespace identifier that specified the type of mailbox store, followed by one or more mailboxes. The interpretation of mailbox names is implementation-dependent. However, the case-insensitive mailbox name INBOX is a special name reserved to mean "the primary mailbox for this user on this server".

For instance, the following examples represent the default mailbox for an IMAP4 account for the user 'dsiders', and the shared NNTP mailbox for the borland.public.delphi.internet.winsock newsgroup on the server Forums.Borland.Com:

  • dsiders/InBox

  • #news/Forums/Borland/Com/Borland/Public/Delphi/Internet/Winsock

By changing the MailboxSeparator character to '.', the previous examples would contain the following:

  • dsiders.InBox

  • #news.Forums.Borland.Com.Borland.Public.Delphi.Internet.Winsock

TIdIMAP4.Password
TIdIMAP4, See Also
Identifies the password for IMAP4 server authentication.
property Password;
Description
Password is a String property that identifies the user (or account) to be used for connection and authentication to the IMAP4 server. Username and Password are used in the Connect method to perform a clear-text login to the IMAP4 server.

TIdIMAP4.Port
TIdIMAP4, See Also
Identifies the port number used for IMAP4 server connections.
property Port: integer;
Description
Port is an Integer property that identifies the port number used for IMAP4 server connections. Port is assigned the default value IdPORT_IMAP4 in the Create constructor.

TIdIMAP4.RetrieveOnSelect
TIdIMAP4, See Also
Indicates data to be automatically retrieved from the mailbox when a mailbox is selected.
property RetrieveOnSelect: TIdRetrieveOnSelect;
Description
RetrieveOnSelect is a TIdRetrieveOnSelect property that indicates data to be automatically retrieved from the mailbox when an IMAP4 mailbox is selected. The default value for RetrieveOnSelect is rsDisabled as assigned in the Create constructor.

RetrieveOnSelect is used in SelectMailBox to determine how much data should be loaded in the TIdMailbox that represents the currently selected mailbox.

rsHeaders indicates that only message headers are loaded for messages in the mailbox.

rsMessages indicates that complete messages are loaded from the mailbox.


TIdIMAP4.Username
TIdIMAP4, See Also
Identifies the user name for IMAP4 server authentication.
property Username;
Description
Username is a String property that identifies the user (or account) to be used for connection and authentication to the IMAP4 server. Username and Password are used in the Connect method to perform a clear-text login to the IMAP4 server.

TIdIMAP4.AppendMsg
TIdIMAP4, See Also
Adds a message to the specified mailbox.
function AppendMsg(const AMBName: String; AMsg: TIdMessage; const AFlags: TIdMessageFlagsSet = []): Boolean;
Parameters
const AMBName: String
Mailbox name used to store the new message.
AMsg: TIdMessage
Message to be added to the mailbox.
const AFlags: TIdMessageFlagsSet = []
Message flags to apply to the message in the mailbox. Default value is [].
Return Value
Boolean - True on success.
Description
AppendMsg is a Boolean function that appends the message in AMsg to the mailbox specified in AMBName. AFlags indicates the set of message flags which should be applied to the message in the mailbox. AppendMsg implements the IMAP4 APPEND command, and requires that the ConnectionState for client contain the value csAuthenticated or csSelected. AppendMsg can raise an EIdConnectionStateError exception when the ConnectionState does not contain one of the expected values. Note: the APPEND command is not used for message delivery, because it does not provide a mechanism to transfer SMTP envelope information.

AppendMsg constructs the flags for the message using MessageFlagSetToStr prior to calling SendCmd using the IMAP4 APPEND command. AppendMsg inspects the numeric response code in LastCmdResult, and when the value is wsOk sends the message headers and body in AMsg to the IMAP4 server.

AppendMsg returns False if an exception occurs, or the response code from the IMAP4 server is not wsOk.


TIdIMAP4.Capability
TIdIMAP4
Retrieves a list of capabilities supported on the IMAP4 server.
function Capability(ASlCapability: TStrings): Boolean;
Parameters
ASlCapability: TStrings
TStrings used to store results for the command.
Return Value
Boolean - True on success.
Description
Capability is a Boolean function that provides a list of the capabilities supported on the IMAP4 server. Capability implements the IMAP4 CAPABILTIY command, and returns the untagged response from the server as a series of lines in ASlCapability. Capability calls SendCmd to perform the IMAP4 CAPBILITY command, and parses values in a successful response into ASlCapability. There will be one capability per line in ASlCapability.

Use of the Capability method is not dependent on a particular value in ConnectionState, and can be used at any time during the session. It is not necessary to issue a Capability call more than once for a client connection.

Any line in ASlCapability which begins with "AUTH=" indicates that the server supports that particular authentication mechanism. Other lines in ASlCapability may refer to extensions, revisions, or amendments to the IMAP4 specification, and are not enabled for an IMAP4 session without explicit client action to invoke the capability.


TIdIMAP4.CheckMailBox
TIdIMAP4, See Also
Requests a checkpoint of the currently selected mailbox.
function CheckMailBox: Boolean;
Return Value
Boolean - True on success.
Description
CheckMailBox is a Boolean function that requests a checkpoint of the currently selected mailbox. A checkpoint refers to the IMAP4 server-specific housekeeping associated with a mailbox that is not normally executed as part of each IMAP4 command.

CheckMailBox requires that ConnectionState contain the value csSelected or an EIdConnectionStateError exception wil be raised.

CheckMailBox executes the IMAP4 CHECK command, and sets the return value to indicate if the server response in ResultNo is wsOk.


TIdIMAP4.CheckMsgSeen
TIdIMAP4, See Also
Indicates if the specified message has been read.
function CheckMsgSeen(const AMsgNum: Integer): Boolean;
Parameters
const AMsgNum: Integer
Message number to be checked.
Return Value
Boolean - True when the message has been read.
Description
CheckMsgSeen is a Boolean function that indicates if the message specified by AMsgNum in the current mailbox has been read. CheckMsgSeen requires that the ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

CheckMsgSeen calls SendCmd, after incrementing the IMAP command counter, using the IMAP FETCH command with the FLAGS attribute. CheckMsgSeen returns True when the server response indicates that the flags for the message contains the TIdMessageFlag value mfSeen.


TIdIMAP4.CloseMailBox
TIdIMAP4, See Also
Closes the currently selected mailbox.
function CloseMailBox: Boolean;
Return Value
Boolean - True on success.
Description
CloseMailBox is a Boolean function that closes the currently selected mailbox. CloseMailBox requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised. CloseMailBox calls SendCmd using the IMAP CLOSE command, and sets ConnectionState to csAuthenticated on successful completion.

TIdIMAP4.Connect
TIdIMAP4, See Also
Opens a connection and attempts to login to the IMAP server.
procedure Connect(const ATimeout: Integer = IdTimeoutDefault); override;
Parameters
const ATimeout: Integer = IdTimeoutDefault
Number of milliseconds before a connection timeout occurs. Default value is IdTimeoutDefault.
Description
Connect is an overridden procedure in TIdIMAP4 that opens a connection to the IMAP server and attempts to login using the Username and Password for the account.

Connect calls the inherited Connect method, and on successful connection, sets ConnectionState to the value csNonAuthenticated. Connect calls SendCmd using the IMAP LOGIN command and the Username and Password values specified for the account. If the login is accepted by the IMAP server, Connect sets ConnectionState to the value csAuthenticated.

If an exception occurs in Connect, Connect calls Disconnect and re-raises the exception.


TIdIMAP4.CopyMsgs
TIdIMAP4, See Also
Copies messages to the specified mailbox.
function CopyMsgs(const AMsgNumList: array of Integer; const AMBName: String): Boolean;
Parameters
const AMsgNumList: array of Integer
Message numbers to copy to the destination mailbox.
const AMBName: String
Mailbox name to receive a copy of the selected messages.
Return Value
Boolean - True on success.
Description
CopyMsgs is an overloaded Boolean function in TIdIMAP4 that copies messages specified by AMsgNumList from the currently selected mailbox to the mailbox specified in AMBName.

If AMsgNumList is an empty array (length of zero), CopyMsg sets the return value to False and exits the method. CopyMsg requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

CopyMsg calls the SendCmd method using the IMAP COPY command, and sets the return value to True when the response in ResultNo contains wsOk.


TIdIMAP4.Create
TIdIMAP4
Constructor for the object instance.
constructor Create(AOwner: TComponent); override;
Parameters
AOwner: TComponent
Owner of the object instance.
Description
Create is the Constructor for the object instance, and relies on the inhertited Create method. Create also initializes properties to their default values, including:


TIdIMAP4.CreateMailBox
TIdIMAP4, See Also
Creates a new mailbox on the IMAP4 server.
function CreateMailBox(const AMBName: String): Boolean;
Parameters
const AMBName: String
Mailbox name to be created on the server.
Return Value
Boolean - True on success.
Description
CreateMailBox is a Boolean function that creates the new mailbox specified in AMBName on the IMAP4 server. When AMBName ends with the hierarchy seperator character (returned by ListMailBoxes), additional mailboxes may be created under the current mailbox in the hierarchy. When AMBName contains the hierarchy seperator character anywhere else in the mailbox name, additional mailbox folders should be created prior to the final mailbox name in the specification.

CreateMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

CreateMailBox calls the SendCmd method using the IMAP CREATE command and the attributes specified in AMBName. CreateMsg sets the return value to True when ResultNo contains wsOk.


TIdIMAP4.DeleteMailBox
TIdIMAP4, See Also
Removes the specified mailbox on the IMAP4 server.
function DeleteMailBox(const AMBName: String): Boolean;
Parameters
const AMBName: String
Mailbox to be removed.
Return Value
Boolean - True on success.
Description
DeleteMailBox is a Boolean function that permanently removes the mailbox specified in AMBName from the IMAP4 server. Attempting to remove the "INBOX" mailbox, or a mailbox name that does not exist, will result in an error response from the server.

DeleteMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

DeleteMailBox calls SendCmd using the IMAP DELETE Command, and sets the return value to True when ResultNo contains wsOk.


TIdIMAP4.DeleteMsgs
TIdIMAP4, See Also
Marks the specified messages for subsequent deletion when a mailbox is purged.
function DeleteMsgs(const AMsgNumList: array of Integer): Boolean;
Parameters
const AMsgNumList: array of Integer
Array of messge numbers to mark for deletion.
Return Value
Boolean - True on success.
Description
DeleteMsgs is a Boolean function that marks the specified messages in AMsgNumList for subsequent deletion when the mailbox is purged. DeleteMsgs calls StoreFlags to add the message flag value mfDeleted to the flags stored in the message on the IMAP4 server.

TIdIMAP4.Destroy
TIdIMAP4, See Also
Frees the object instance.
destructor Destroy; override;
Description
Destroy is the destructor for the object instance. Destroy frees and releases object properties that were initialized in the Create constructor, including MailBox and CmdResultDetails, prior to calling the inherited destructor.

TIdIMAP4.Disconnect
TIdIMAP4, See Also
Closes an IMAP4 session and connection.
procedure Disconnect; override;
Description
Disconnect is an overriden procedure in TIdIMAP4 that closes an IMAP4 session and connection. If Connected is False, an EIdNotConnected exception will be raised.

Disconnect calls the SendCmd method using the IMAP LOGOUT command prior to calling the inherited Disconnect method and setting ConnectionState to the value csNonAuthenticated.


TIdIMAP4.DoAlert
TIdIMAP4, See Also
Implements signalling of an alert message.
procedure DoAlert(const AMsg: String);
Parameters
const AMsg: String
Text for the alert message.
Description
DoAlert is a procedure that implements event notification for alert messages in an IMAP4 response. Alert messages can occur in results from an IMAP4 command that selects the current mailbox, or appends a new message to a mailbox. TIdAlertEvent event are generated when the alert is parsed from the results from the command.

DoAlert signals the OnAlert event handler for the current IMAP4 client instance using the value in AMsg for the alert message. Applications must assign a procedure to the OnAlert event handler to allow responding to the event notification.


TIdIMAP4.ExamineMailBox
TIdIMAP4, See Also
Select a mailbox for read-only access.
function ExamineMailBox(const AMBName: String; AMB: TIdMailBox): Boolean;
Parameters
const AMBName: String
Mailbox name to use accessed on the IMAP4 server.
AMB: TIdMailBox
Mailbox to be filled with the retrieved message values.
Return Value
Boolean - True on success.
Description
ExamineMailBox is a Boolean function in TIdIMAP4 used to select the mailbox specified in AMBName for read-only access. Messages and Flags are retrieved from the mailbox and stored in the TIdMailBox instance specified in AMB. ExamineMailBox returns the same output as SelectMailBox, except for the read-only attribute applied to the mailbox, flags, and messages.

ExamineMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

ExamineMailBox calls SendCmd using the IMAP EXAMINE command. When the numeric code in LastCmdResult contains wsOk, the text values in LastCmdResult are parsed to populate the TIdMailBox instance specified AMB.

ExamineMailBox returns True on successful completion of the method, or false when the response code is not wsOk or an exception occurs.


TIdIMAP4.ExpungeMailBox
TIdIMAP4, See Also
Removes messages marked for deletion in the currently selected mailbox.
function ExpungeMailBox: Boolean;
Return Value
Boolean - True on success.
Description
ExpungeMailBox is a Boolean function that permanently removes messages marked for deletion in the currently selected mailbox. Messages marked for deletion contain the Deleted flag. ExpungeMailBox requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

ExpungeMailBox calls the SendCmd method using the IMAP EXPUNGE command, and on successful completion calls the ParseExpungeResultDetails method for the selected mailbox.

ExpungeMailBox sets the return value to True when protocol response contains the value wsOk.


TIdIMAP4.GetInternalLineResponse
TIdIMAP4, See Also
Reads multiple tagged and untagged IMAP4 responses from a server.
procedure GetInternalLineResponse(const ATag: String);
Parameters
const ATag: String
Tagged response expected as the terminal response for the message.
Description
GetInternalLineResponse is a procedure that implements reading of multiple tagged and untagged IMAP4 responses from a server. GetInternalLineResponse is called in the implementation of the GetLineResponse method. GetInternalLineResponse creates and populates a TStringList that is used to capture the response lines from the IMAP4 server using ReadLnWait. GetInternalLineResponse will read untagged responses until the tagged response in ATag is encountered.

GetInternalLineResponse calls FLastCmdResult.ParseLineResponse using the values in ATag and the TStringList to prepare the response for use by the IMAP4 client. GetInternalLineResponse frees the TStringList used to capture response lines prior to exiting from the method.


TIdIMAP4.GetInternalResponse
TIdIMAP4, See Also
Reads mutiple untagged response or a single tagged response from the server.
procedure GetInternalResponse(const ATag: String); overload;
Parameters
const ATag: String
Command tag expecetd in the IMAP4 response.
Description
GetInternalResponse is an overloaded procedure that implements reading of tagged and untagged IMAP4 responses from a server. GetInternalResponse is called from the implementation of the GetResponse method. GetInternalResponse creates and populates 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.

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 free the TStringList prior to exiting from the method.


TIdIMAP4.GetInternalResponse
TIdIMAP4, See Also
Reads mutiple untagged response or a single tagged response from the server.
procedure GetInternalResponse; overload;
Parameters
ATag
Command tag expecetd in the IMAP4 response.
Description
GetInternalResponse is an overloaded procedure that implements reading of tagged and untagged IMAP4 responses from a server. GetInternalResponse is called from the implementation of the GetResponse method. GetInternalResponse creates and populates 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.

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 free the TStringList prior to exiting from the method.


TIdIMAP4.GetLineResponse
TIdIMAP4, See Also
Retrieves and Checks an IMAP4 server response line.
function GetLineResponse(const ATag: String; const AAllowedResponses: array of SmallInt): SmallInt;
Parameters
const ATag: String
Command tag name expected in the response.
const AAllowedResponses: array of SmallInt
Response codes allowed.
Return Value
SmallInt - Response code from the server.
Description
GetLineResponse is a SmallInt function in TIdIMAP4 that retrieves an IMAP4 server response line, and determines the response code based on the tagged or untagged response content. Untagged response codes, indicated by "*" in the initial position of the response, always set the return value to True. Otherwise, the command tag name in ATag is expected in the server response, and the return value is based on the presence of "OK", "NO", "BAD", "PREAUTH" or "BYE" in the response line.

GetLineResponse calls GetInternalLineResponse using the value specified in ATag, and sets the numeric response code in LastCmdResult to one of the integer constants wsOk, wsNo, wsBad, wsPreAuth, or wsBye. GetLineResponse can raise an EIdException exception using the message specified in RSUnrecognizedIMAP4ResponseHeader when the numeric response code is not in one of the integer constants. GetLineResponse calls CheckResponse to insure that the numeric response code is one of the allowable values specified in AAllowedResponses.

GetLineResponse calls the inherited CheckResponse method, and sets the return value to the ResultNo from CheckResponse.


TIdIMAP4.GetResponse
TIdIMAP4, See Also
Retrieves and Checks a multiple line IMAP4 server response.
function GetResponse(const ATag: String; const AAllowedResponses: array of SmallInt): SmallInt; overload; reintroduce;
function GetResponse(const AAllowedResponses: array of SmallInt): SmallInt; overload; reintroduce;
Parameters
const ATag: String
Command tag name expected in the server response.
const AAllowedResponses: array of SmallInt
Array of allowed server response codes.
Return Value
SmallInt - Response code from the server.
Description
GetResponse is an overloaded SmallInt function in TIdIMAP4 that implements retrieval and processing of IMAP4 server responses. GetResponse is overloaded to allow used with commands that expect a tagged response having the value in ATag, or an untagged response. GetResponse calls GetInternalResponse, using the optional commag tag in ATag to read one or more response lines from the IMAP4 server.

GetResponse sets the numeric code in LastCmdResult to one of the IMAP4 integer constants weOk, wsBad, wsBye, wsPreAuth, wsNo. GetResponse can raise an EIdException with the message RSUnrecognizedIMAP4ResponseHeader if a response code other than the preceeding is encountered in the IMAP4 response.

GetResponse checks the the numeric response code against the allowable numeric response code(s) specified in AAllowedResponses.


TIdIMAP4.GetResponse
TIdIMAP4, See Also
Retrieves and Checks a multiple line IMAP4 server response.
function GetResponse(const ATag: String; const AAllowedResponses: array of SmallInt): SmallInt; overload; reintroduce;
function GetResponse(const AAllowedResponses: array of SmallInt): SmallInt; overload; reintroduce;
Parameters
const ATag: String
Command tag name expected in the server response.
const AAllowedResponses: array of SmallInt
Array of allowed server response codes.
Return Value
SmallInt - Response code from the server.
Description
GetResponse is an overloaded SmallInt function in TIdIMAP4 that implements retrieval and processing of IMAP4 server responses. GetResponse is overloaded to allow used with commands that expect a tagged response having the value in ATag, or an untagged response. GetResponse calls GetInternalResponse, using the optional commag tag in ATag to read one or more response lines from the IMAP4 server.

GetResponse sets the numeric code in LastCmdResult to one of the IMAP4 integer constants weOk, wsBad, wsBye, wsPreAuth, wsNo. GetResponse can raise an EIdException with the message RSUnrecognizedIMAP4ResponseHeader if a response code other than the preceeding is encountered in the IMAP4 response.

GetResponse checks the the numeric response code against the allowable numeric response code(s) specified in AAllowedResponses.


TIdIMAP4.KeepAlive
TIdIMAP4, See Also
Prevents loss of a IMAP server connection due to a timeout.
procedure KeepAlive;
Description
KeepAlive is a Procedure used to prevents loss of the IMAP server connection due to a timeout condition by sending the IMAP NOOP command.

TIdIMAP4.ListInferiorMailBoxes
TIdIMAP4, See Also
Retrieves a list of mailboxes contained in the specified mailbox folder hierarchy.
function ListInferiorMailBoxes(AMailBoxList: TStringList; AInferiorMailBoxList: TStringList): Boolean;
Parameters
AMailBoxList: TStringList
Optional mailbox or folder to be searched.
AInferiorMailBoxList: TStringList
Receives mailbox names retreived in the search.
Return Value
Boolean - True on success.
Description
ListInferiorMailBoxes is a Boolean function that retrieves a list of mailboxes contained in the specified mailbox folder hierarchy.

ListInferiorMailBoxes can be used when the container folder might include many child mailboxes, and the search might be time consuming. ListInferiorMailBoxes requires that the value of ConnectionState be csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

When AMailBoxList in unassigned (Nil), ListInferiorMailBoxes will search for child mailboxes in the currently selected mailbox using the IMAP LIST command. ListInferiorMailBoxes calls ParseListResultDetails to populate the AInferiorMailBoxList variable with the contents of CmdResultDetails including the default "INBOX".

When AMailBoxList contains valid TStrings values, ListInferiorMailBoxes retrieves the child mailbox list for each line in AMailBoxList and accumulates the parsed results in AInferiorMailBoxList.

ListInferiorMailBoxes sets the return value to True when the numeric protocol response contains wsOk.


TIdIMAP4.ListMailBoxes
TIdIMAP4, See Also
Retrieves a list of mailboxes for the IMAP4 account.
function ListMailBoxes(AMailBoxList: TStringList): Boolean;
Parameters
AMailBoxList: TStringList
Receives the list of mailboxes for the account.
Return Value
Boolean - True on success.
Description
ListMailBoxes is a Boolean function that retrieves a list of mailboxes for the IMAP4 account. ListMailBoxes requires that the value of ConnectionState be csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

ListMailBoxes calls SendCmd using the IMAP LIST command for all mailboxes in the currently selected folder. ListMailBoxes calls parses the results and stores the mailboxes information in CmdResultDetails to the AMailBoxList variable.

ListMailBoxes sets the return value to True when the protocol numeric response code contains the value wsOk.


TIdIMAP4.ListSubscribedMailBoxes
TIdIMAP4, See Also
Retrieves the list of subscribed mailboxes on the IMAP4 server.
function ListSubscribedMailBoxes(AMailBoxList: TStringList): Boolean;
Parameters
AMailBoxList: TStringList
Destination for the list of subscribed mailboxes.
Return Value
Boolean - True on success, False on protocol error or exception.
Description
ListSubscribedMailBoxes is a Boolean function used to retrieve the list of subscribed mailbox from the IMAP4 server, and store the results in AMailBoxList. ListSubscribedMailBoxes implements the IMAP4 LSUB command using arguments required to retrieve all mailboxes having the appropriate IMAP4 flags.

ListSubscribedMailBoxes requires that the ConnectionState property for the client contain either the value csAuthenticated or csSelected. When ConnectionState is not valid for the operation, an EIdConnectionStateError exception wil be raised and the return value for the method will be False. The return value will be True when the LSUB command has compeleted with the wsOk protocol response code and the list of mailboxes has been parsed in the AMailBoxList parameter.

Use SelectMailBox to activate a particular mailbox in the subscribed mailbox list.

Use UnsubscribeMailBox to remove a mailbox from the subscribed list on the IMAP4 server.


TIdIMAP4.RenameMailBox
TIdIMAP4, See Also
Renames a specified mailbox on the IMAP4 server.
function RenameMailBox(const AOldMBName: String; const ANewMBName: String): Boolean;
Parameters
const AOldMBName: String
Mailbox name to be changed .
const ANewMBName: String
New name for the mailbox.
Return Value
Boolean - True on success.
Description
RenameMailBox is a Boolean function that renames the mailbox specified in AOldMBName to the value specified in ANewMBName on the IMAP4 server. RenameMailBox will receive a protocol error if AOldMBName does not exist, of when ANewMBName already exists.

Renaming the "INBOX" mailbox is permitted, and has special behavior. It moves all messages in INBOX to a new mailbox with the given name, leaving INBOX empty. If the server implementation supports inferior hierarchical names of INBOX, these are unaffected by a rename of INBOX.

RenameMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

RenameMailBox calls SendCmd using the IMAP4 RENAME command to alter the mailbox name. RenameMailBox sets the return value to True when ResultNo contains the value wsOk.


TIdIMAP4.Retrieve
TIdIMAP4, See Also
Retrieves a message from a mailbox and marks it as read on the server.
function Retrieve(const AMsgNum: Integer; AMsg: TIdMessage): Boolean;
Parameters
const AMsgNum: Integer
Message number to retreive from the mailbox.
AMsg: TIdMessage
Stores the retrieved message headers, body, and attachments.
Return Value
Boolean - True on success.
Description
Retrieve is a Boolean function that retrieves a message from a mailbox and marks it as read on the server. Retrieve requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

Retrieve send the IMAP4 FETCH command for the specified message number. On successful retrieval of the RFC 822 envelope data, Retrieve calls ReceiveHeader and ReceiveBody to load the message contents into the TIdMessage instance specified by AMsg.

Retrieve sets the return value to True when ResultNo contains the value wsOk.


TIdIMAP4.RetrieveAllEnvelopes
TIdIMAP4, See Also
Retrieves RFC-822 envelope data for messages in a mailbox.
function RetrieveAllEnvelopes(AMsgList: TIdMessageCollection): Boolean;
Parameters
AMsgList: TIdMessageCollection
Collection of message instances created while retrieving message envelope data.
Return Value
Boolean - True on success, False on exception or protocol error.
Description
RetrieveAllEnvelopes is a Boolean function used to retrieve IMAP4 envelope data for all messages in the currently selected IMAP4 mailbox by their message number.

IMAP4 envelope information consists of data items that describes the envelope structure of a message and is computed by parsing RFC-822 message headers from individual messages in the IMAP4 mailbox. Fields in the envelope structure are in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id.

Any member in an envelope structure that is not applicable is presented as an empty value. Note that the IMAP4 server MUST default the reply-to and sender fields from the from field; a client is not expected to know how to do this.

RetrieveAllEnvelopes constructs instances of TIdMessage which are assigned to collection items added to the AMsgList message collection. RetrieveAllEnvelopes requires that the ConnectionState property for the IMAP4 client contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value will be set to False.

RetrieveAllEnvelopes implements the IMAP4 FETCH command using arguments that will result in all envelope data items for the messages in the selected mailbox. The multi-line response from the IMAP4 server is captured and parsed into newly created TIdMessages instances in AMsgList collections items.

The return value for RetrieveAllEnvelopes will be True when the protocol response code from the IMAP4 server is wsOk, and the multi-line response is successfully parsed into the AMsgList collection.

Use UIDLRetrieveAllEnvelopes to retrieve envelope data for messages using their unique Identifier.


TIdIMAP4.RetrieveAllHeaders
TIdIMAP4, See Also
Retrieves headers for all messages in a mailbox and populates the specified message collection.
function RetrieveAllHeaders(AMsgList: TIdMessageCollection): Boolean;
Parameters
AMessageList
Message collection to be populated.
Return Value
Boolean - True on success.
Description
RetrieveAllHeaders is a Boolean function that retrieves headers for all messages in the currently selected mailbox, and populates the message collection specified in AMessageList with message instances to store the headers.

RetrieveAllHeaders is used in SelectMailBox to automatically retrieve data from the selected mailbox when RetrieveOnSelect contains the value rsHeaders.

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

When AMessageList is unassigned (Nil), RetrieveAllHeaders will set the return value to False and exit from the method. Otherwise, RetrieveAllHeaders will create a new message in the collection and call RetrieveHeader for each individual message number. If the headers for a given message cannot be loaded from the IMAP mailbox, the return value is set to False and additional messages are ignored.

RetrieveAllHeaders will return True when all message headers have been retrieved from the mailbox.

Use RetrieveAllMsgs to fetch both message headers and contents in a message collection.


TIdIMAP4.RetrieveAllMsgs
TIdIMAP4, See Also
Retrieves all messages in a mailbox and populates the specified message collection.
function RetrieveAllMsgs(AMsgList: TIdMessageCollection): Boolean;
Parameters
AMessageList
Message collection to be populated.
Return Value
Boolean - True on success.
Description
RetrieveAllMsgs is a Boolean function that retrieves all messages in the currently selected mailbox, and populates the message collection specified in AMessageList with message instances.

RetrieveAllMsgs is used in SelectMailBox to automatically retrieve data from the selected mailbox when RetrieveOnSelect contains the value rsMessages.

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

When AMessageList is unassigned (Nil), RetrieveAllHeaders will set the return value to False and exit from the method. Otherwise, RetrieveAllMsgs will create a new message in the collection and call Retrieve for each individual message number. If the headers for given message cannot be loaded from the IMAP mailbox, the return value is set to False and additional messages are ignored.

RetrieveAllMsgs will return True when all messages have been retrieved from the mailbox.

Use RetrieveAllHeaders to fetch only message headers for the message collection.


TIdIMAP4.RetrieveEnvelope
TIdIMAP4, See Also
Retrieves SMTP evnvelope information for a message in the mailbox.
function RetrieveEnvelope(const AMsgNum: Integer; AMsg: TIdMessage): Boolean;
Parameters
const AMsgNum: Integer
Message number to retrieve from the mailbox.
AMsg: TIdMessage
Message instance to store the return values.
Return Value
Bolean - True on success.
Description
RetrieveEnvelope is a Boolean function used to retrieve the SMTP envelope information for the message number specified in AMsgNum, and to store the information in the message identified by AMsg. RetrieveEnvelope requires that ConnectionState contain the value csSelected, indicating a mailbox has been successfully selected and authenticated. RetrieveEnvelope can raise an EIdConnectionStateError exception if a mailbox has not been selected and/or authenticated for the current user.

RetrieveEnvelope calls SendCmd using the IMAP4 FETCH command and arguments constructed from the value in AMsgNum and the IMAP4 fetch data flags required for the operation. RetrieveEnvelope reads the multi-line response form the IMAP4 server, and verifies that the initial response matches the command issued using SendCmd. When they are the same, RetrieveEnvelope extracts the SMTP headers from the response and parses the header values in the message specified in AMsg.


TIdIMAP4.RetrieveFlags
TIdIMAP4, See Also
Retrieves message flags stored in a message on the IMAP4 server.
function RetrieveFlags(const AMsgNum: Integer; AFlags: TIdMessageFlagsSet): Boolean;
Parameters
const AMsgNum: Integer
Message number containing flags to be retrieved.
AFlags: TIdMessageFlagsSet
Pointer the array where messge flags are stored.
Return Value
Boolean - True on success.
Description
RetrieveFlags is a Boolean function that is used to retrieves message flags for a the message number specified in stored in AMsgNum from an IMAP4 server.

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

RetrieveFlags calls the IMAP4 FETCH command to get flags for the specified message number. If a protocol error occurs while retrieving the flag value, RetrieveFlags sets the return value to False and exits from the method. On successful completion, RetrieveFlags processes the untagged responses in CmdResultDetails using ParseFlagString and sets the return value to True.


TIdIMAP4.RetrieveHeader
TIdIMAP4, See Also
Retrieves headers for a specified message number and populates the message instance.
function RetrieveHeader(const AMsgNum: Integer; AMsg: TIdMessage): Boolean;
Parameters
const AMsgNum: Integer
Message number to be retrieved from the mailbox.
AMsg: TIdMessage
Message instance used to store retrieved header values.
Return Value
Boolean - True on success.
Description
RetrieveHeader is a Boolean function that retrieves headers for the message number specified in AMsgNum, and populates the message instance AMsg with the header values.

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

RetrieveHeader send the IMAP4 FETCH command for the specified message number to access the stored header values. RetrieveHeader insures that the untagged server response contains an RFC 822 header before calling ReceiveHeader to populate the header values in the message instance.

RetrieveHeader sets the return value to True when the numeric protocol response in LastCmdResult contains the value wsOk.


TIdIMAP4.RetrieveMailBoxSize
TIdIMAP4, See Also
Indicates the size of all messages in the currently selected mailbox.
function RetrieveMailBoxSize: Integer;
Return Value
Integer - Bytes required to store all messages in the mailbox or -1 when an error occurs.
Description
RetrieveMailBoxSize is an Integer function that calculates the size of all messages in the currently selected mailbox.

RetrieveMailBoxSize requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised. The return value for RetrieveMailBoxSize is -1 if an error occurs in the method. RetrieveMailBoxSize calls SendCMd using the IMAP4 FETCH command to get the message size for each message in the IMAP mailbox, and accumulates the total size as the return value for the method.


TIdIMAP4.RetrieveMsgSize
TIdIMAP4, See Also
Indicates the size of a specified message in the currently selected mailbox.
function RetrieveMsgSize(const AMsgNum: Integer): Integer;
Parameters
const AMsgNum: Integer
Message number to access in the mailbox.
Return Value
Integer - Bytes required to store the message in the mailbox or -1 when an error occurs.
Description
RetrieveMsgSize is an Integer function that calculates the size of the message specified by AMsgNum in the currently selected mailbox.

RetrieveMsgSize requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised. The return value for RetrieveMsgSize is -1 if an error occurs in the method. RetrieveMsgSize calls SendCMd using the IMAP4 FETCH command to get the message size for the specified message number in the IMAP mailbox, and sets the return value for the method.


TIdIMAP4.RetrievePeek
TIdIMAP4, See Also
Retrieves a specified message number from a mailbox preserving its Seen flag.
function RetrievePeek(const AMsgNum: Integer; AMsg: TIdMessage): Boolean;
Parameters
const AMsgNum: Integer
Message number to be retrieved from the mailbox.
AMsg: TIdMessage
Message instance to store the retrieved message.
Return Value
Boolean - True on success.
Description
RetrievePeek is a Boolean function that retrieves the message specified in AMsgNum and stores the result in the mesage instance specified by AMsg. Unlike Retrieve, RetrievePeek preserves the state of the Seen flag for the message in the mailbox.

RetrievePeek requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception wil be raised. RetrievePeek sends the IMAP4 FETCH command to retrieve data for the specified message number. RetrievePeek insures that the server response contains untagged resposnes for the desired message prior to calling ReceiveHeader and ReceiveBody to populate the message instance.

RetrievePeek sets the return value to True when the protocol reponse code contains the value wsOk.


TIdIMAP4.SearchMailBox
TIdIMAP4
function SearchMailBox(const ASearchInfo: array of TIdIMAP4SearchRec): Boolean;
Parameters
const ASearchInfo: array of TIdIMAP4SearchRec
Array

TIdIMAP4.SelectMailBox
TIdIMAP4, See Also
Selects a mailbox on the IMAP4 server as the current mailbox for message access.
function SelectMailBox(const AMBName: String): Boolean;
Parameters
const AMBName: String
Mailbox name to be activated.
Return Value
Boolean - True on success.
Description
SelectMailBox is a Boolean function that selects the mailbox specified in AMBName as the current mailbox for message access on the IMAP4 server. Only one mailbox can be selected at a time in a IMAP4 connection. Simultaneous access to multiple mailboxes requires multiple connections. SelectMailBox automatically deselects any currently selected mailbox before attempting the new selection. Consequently, if a mailbox is selected and a SELECT command that fails is attempted, no mailbox is selected.

SelectMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

SelectMailBox calls SendCmd using the IMAP4 SELECT command for the specified mailbox name. On successful completion of the command, SelectMailBox parses the multi-line response in LastCmdResult and loads the values into the MailBox specified in AMBName. SelectMailBox sets ConnectionState to the value csSelected. If the response code from SendCmd contains a value other than wsOk, the value in ConnectionState is set csAuthenticated.

SelectMailBox also calls either RetrieveAllHeaders or RetrieveAllMsgs, based on the value of RetrieveOnSelect, to populate the message list in MailBox.

SelectMailBox sets the return value for the method to True when bumeric response code in LastCmdResult contains the value wsOk.


TIdIMAP4.SendCmd
TIdIMAP4, See Also
Sends a tagged IMAP4 command to the server and checks for valid response codes.
function SendCmd(const ATag: string; const AOut: string; const AResponse: SmallInt = -1): SmallInt; overload;
function SendCmd(const ATag: string; const AOut: string; const AResponse: array of SmallInt): SmallInt; overload;
Parameters
const ATag: string
Tag to identify the server response to this command.
const AOut: string
Command to be executed on the IMAP4 server.
const AResponse: SmallInt = -1
Anticipated server reponse(s). -1 when omitted.
Return Value
SmallInt - Response code received from the IMAP4 server.
Description
SendCmd is an overloaded SmallInt function in TIdIMAP4 that allows the client to send the tagged command specified in ATag and AOut to the IMAP4 server, and anticipates a response or responses as specified in AResponse.

AResponse can be an array of SmallInt values that indicate the valie responses for the command, or a single SmallInt value.

SendCmd calls WriteLn to send the values in Atag and AOut to the IMAOP4 server, and calls GetResponse to determine the server response.


TIdIMAP4.SendCmd
TIdIMAP4, See Also
Sends a tagged IMAP4 command to the server and checks for valid response codes.
function SendCmd(const ATag: string; const AOut: string; const AResponse: SmallInt = -1): SmallInt; overload;
function SendCmd(const ATag: string; const AOut: string; const AResponse: array of SmallInt): SmallInt; overload;
Parameters
const ATag: string
Tag to identify the server response to this command.
const AOut: string
Command to be executed on the IMAP4 server.
const AResponse: SmallInt = -1
Anticipated server reponse(s). -1 when omitted.
Return Value
SmallInt - Response code received from the IMAP4 server.
Description
SendCmd is an overloaded SmallInt function in TIdIMAP4 that allows the client to send the tagged command specified in ATag and AOut to the IMAP4 server, and anticipates a response or responses as specified in AResponse.

AResponse can be an array of SmallInt values that indicate the valie responses for the command, or a single SmallInt value.

SendCmd calls WriteLn to send the values in Atag and AOut to the IMAOP4 server, and calls GetResponse to determine the server response.


TIdIMAP4.StatusMailBox
TIdIMAP4, See Also
Retrieves status data items for the specified mailbox.
function StatusMailBox(const AMBName: String; AMB: TIdMailBox; const AStatusDataItems: array of TIdIMAP4StatusDataItem): Boolean;
Parameters
const AMBName: String
Mailbox name tio be accessed and loaded.
AMB: TIdMailBox
Represents the contents read from the mailbox.
const AStatusDataItems: array of TIdIMAP4StatusDataItem
Status data items to be retrieved.
Return Value
Boolean - True on success.
Description
StatusMailBox is a Boolean function that retrieves the status data items specified in AStatusDataItems for the mailbox specified in AMBName.

StatusMailBox requires that the value of ConnectionState contain either csAuthenticated or csSelected, or an EIdConnectionStateError exception will be raised.

StatusMailBox calls SendCmd using the IMAP4 STATUS command for the specified mailbox name and data items. On succesful completion, StatusMailBox calls ParseStatusResultDetails to load the values in CmdResultDetails into the Mailbox sopecified in AMB.

StatusMailBox sets the return value for the method to True when ResultNo contains the value wsOk.


TIdIMAP4.StoreFlags
TIdIMAP4, See Also
Updates the specified message flags for a list of message numbers.
function StoreFlags(const AMsgNumList: array of Integer; const AStoreMethod: TIdIMAP4StoreDataItem; const AFlags: TIdMessageFlagsSet): Boolean;
Parameters
const AMsgNumList: array of Integer
Message numbers to be updated by the method.
const AStoreMethod: TIdIMAP4StoreDataItem
Method to use for storing flag values.
const AFlags: TIdMessageFlagsSet
Message flags to be updated for the specified messages.
Return Value
Boolean - True on success.
Description
StoreFlags is a Boolean function that Updates the message flags specified in AFlags for the list of message numbers specified in AMsgNumList. AStoreMethod indicates if the message flags are added, replaced or removed.

When AMsgNumList has a length of zero, the return value for the method is set to False and the method is exited. StoreFlags requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception will be raised.

StoreFlags calls SendCmd using the IMAP4 STORE command for the specified messages and flags. StoreFlags sets the return value for the method to True when ResultNo contains the value wsOk.


TIdIMAP4.SubscribeMailBox
TIdIMAP4, See Also
Adds a mailbox to the list of "active" or "subscribed" mailboxes.
function SubscribeMailBox(const AMBName: String): Boolean;
Parameters
const AMBName: String
Mailbox name to add to the active mailbox list.
Return Value
Boolean - True on success.
Description
SubscribeMailBox is a Boolean function used to add the mailbox name specified in AMBName to the list of "active" or "subscribed" mailboxes on the IMAP4 server. SubscribeMailBox updates the values that are returned by the IMAP4 LSUB command. SubscribeMailBox returns True when the response code from the IMAP4 server is wsOk.

SubscribeMailBox requires that the ConnectionState for the client contain the value csAuthenticated or csSelected to perform the IMAP4 function. SubscribeMailBox can raise an EIdConnectionStateError exception with the message RSIMAP4ConnectionStateError if ConnectionState contains a value other than csAuthenticated or csSelected.

SubscribeMailBox calls SendCmd using the IMAP4 SUBSCRIBE command and the value specified in AMBName as an argument. The IMAP4 server may validate the mailbox argument in AMBName to verify that it exists. The return value for SubscribeMailBox will be True when the numeric response code from SendCmd is wsOk and an exception does not occur.

Use UnsubscribeMailBox to remove a specified mailbox from the "active" or "subscibed" list.


TIdIMAP4.UIDCheckMsgSeen
TIdIMAP4, See Also
Indicates if the mailbox message has been read.
function UIDCheckMsgSeen(const AMsgUID: String): Boolean;
Parameters
const AMsgUID: String
Unique Identifier for the message to examine.
Return Value
Boolean - True when read, False when unread or on protocol error.
Description
UIDCheckMsgSeen is a Boolean function that indicates if the message Unique Identifier specified in AMsgUID references a message that has been read in the IMAP4 mailbox. UIDCheckMsgSeen requires that ConnectionState contain the value csSelected, indicating a mailbox has been selected, or an EIdConnectionStateError exception will be raised.

When a mailbox has been selected, UIDCheckMsgSeen performs the IMAP4 UID command with arguments needed to retrieve mailbox message flags for the message specified in AMsgUID.

The return value for UIDCheckMsgSeen is True when the IMAP4 Seen flag is present in mailbox message flags for the message, or False when the flag is not present or the protocol request returns a value other than wsOK.


TIdIMAP4.UIDDeleteMsg
TIdIMAP4, See Also
Marks a messasge for deletion in the IMAP4 mailbox.
function UIDDeleteMsg(const AMsgUID: String): Boolean;
Parameters
const AMsgUID: String
Unique Identifier for the message to delete.
Return Value
Boolean - True on success.
Description
UIDDeleteMsg is a Boolean function that allows the IMAP4 client to mark the message specified in AMsgUID for deletion in the IMAP4 mailbox. AMsgUID is the Unique Identifier for the message to mark for deletion. UIDDeleteMsg does not physically remove the message from the mailbox. UIDDeleteMsg calls the UIDStoreFlags to add the IMAP4 Deleted flag to the message flags in the IMAP4 mailbox. Use ExpungeMailBox to physically remove all messages marked for deletion.

TIdIMAP4.UIDRetrieve
TIdIMAP4, See Also
Retrieves the contents of a message by UID from an IMAP4 server.
function UIDRetrieve(const AMsgUID: String; AMsg: TIdMessage): Boolean;
Parameters
const AMsgUID: String
Unique Identifier for the message to retrieve.
AMsg: TIdMessage
Storage for the retrieve message values.
Return Value
Boolean - True on success.
Description
UIDRetrieve is a Boolean function used to retrieve the entire contents of a message from an IMAP4 server by Unique Identifier for the message. UIDRetrieve requires that ConnectionState contain the value csSelected, indicating a mailbox has been selected, or an EIdConnectionStateError exception will be raised. The return value for the method will be True when the protocol response is wsOk.

UIDRetrieve executes the IMAP4 UID FETCH command with the arguments needed to retrieve the message identified by the valuein AMsgUID. UIDRetrieve will retrieve the RFC message headers, body, and attachments, and mailbox message flags for storage in the message instance specified by AMsg.

Use UIDRetrievePeek to retrieve a mailbox message while avoiding use of the IMAP4 Seen message flag in the iMAP4 mailbox.


TIdIMAP4.UIDRetrieveAllEnvelopes
TIdIMAP4, See Also
Retrieves RFC-822 envelope data for messages in a mailbox.
function UIDRetrieveAllEnvelopes(AMsgList: TIdMessageCollection): Boolean;
Parameters
AMsgList: TIdMessageCollection
Message collection for envelope data from the mailbox.
Return Value
Boolean - True on success.
Description
UIDRetrieveAllEnvelopes is a Boolean function used to retrieve envelope data for all messages in the IMAP4 mailbox, and store the results in the message collection specified by AMsgList.

IMAP4 envelope information consists of data items that describes the envelope structure of a message and is computed by parsing RFC-822 message headers from individual messages in the IMAP4 mailbox. Fields in the envelope structure are in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id.

Any member in an envelope structure that is not applicable is presented as an empty value. Note that the IMAP4 server MUST default the reply-to and sender fields from the from field; a client is not expected to know how to do this.

UIDRetrieveAllEnvelopes constructs instances of TIdMessage which are assigned to collection items added to the AMsgList message collection. RetrieveAllEnvelopes requires that the ConnectionState property for the IMAP4 client contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value will be set to False.

UIDRetrieveAllEnvelopes requires that ConnectionState contain the value csSelected, indicating that a mailbox has been selected, or an EIdConnectionStateError exception will be raised.

UIDRetrieveAllEnvelopes executes the IMAP4 UID FETCH command using arguments to select all envelope data items from the IMAP4 mailbox by their uniqueness identifier. UIDRetrieveAllEnvelopes will retrieve the protocol results, storing parsed values in message collection items.

The return value for UIDRetrieveAllEnvelopes will be True when the protocol response code from the IMAP4 server is wsOk, and the multi-line response is successfully parsed into the AMsgList collection.

Use RetrieveAllEnvelopes to retrieve envelope data for messages using their messge number in the IMAP4 mailbox.


TIdIMAP4.UIDRetrieveAllHeaders
TIdIMAP4
Retrieves headers for mail messages by their uniqueness identifier.
function UIDRetrieveAllHeaders(AMsgList: TIdMessageCollection): Boolean;
Description
UIDRetrieveAllHeaders is a Boolean function used to retrieve message headers for all mail messages in the selected IMAP4 mailbox. AMsgList is the TIdMessageCollection where retrieved headers are stored using newly created TIdMessageItem instances.

Note: UIDRetrieveAllHeaders is not implmented at this time, and always returns the value False.


TIdIMAP4.UIDRetrieveEnvelope
TIdIMAP4, See Also
Retrieves envelope data for a specific message.
function UIDRetrieveEnvelope(const AMsgUID: String; AMsg: TIdMessage): Boolean;
Parameters
const AMsgUID: String
Uniqueness Identifier for the desired message.
AMsg: TIdMessage
Message used to store retrieved envelope data.
Return Value
Boolean - True on success.
Description
UIDRetrieveEnvelope is a Boolean function used to retrieve the IMAP envelope headers for the message identified by the uniqueness identifier in AMsgID. Values returned by the IMAP4 server are stored in the AMsg class instance.

UIDRetrieveEnvelope implements the IMAP4 UID FETCH command using AMsgId and other arguments needed to retrieve the envelope headers for the specified message.

IMAP4 envelope information consists of data items that describe the envelope structure of a message and is computed by parsing RFC-822 message headers from individual messages in the IMAP4 mailbox. Fields in the envelope structure are in the following order: date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id. Any member in an envelope structure that is not applicable is presented as an empty value.

UIDRetrieveEnvelope requires that the ConnectionState property contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value is set to False. The return value will be True when the protocol response code is wsOk, and the multi-line response containing the envelope data fields is successfully parsed into the AMsg message instance.


TIdIMAP4.UIDRetrieveFlags
TIdIMAP4, See Also
Retrieves message flags associated with the specified message.
function UIDRetrieveFlags(const AMsgUID: String; AFlags: TIdMessageFlagsSet): Boolean;
Parameters
const AMsgUID: String
Uniqueness identifier for the desired message.
AFlags: TIdMessageFlagsSet
set of IMAP4 flags for the indicated message.
Return Value
Boolean - True on success.
Description
UIDRetrieveFlags is a Boolean function used to retrieve a set of IMAP4 message flags associated with the message identified by the uniqueness identifier specified in AMsgUID. AFlags is used to store the optional TIdMessageFlags values for the message.

UIDRetrieveFlags requires that the ConnectionState property contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value will be set to False.

UIDRetrieveFlags executes the IMAP4 UID FETCH command using arguments to retrieve the flags for the message specified in AMsgID. When the protocol response code from the IMAP4 server is wsOk, the multi-line response is parsed to store flag valuein AFlags. If the server response code is not wsOk, the return value for the method is set to False.

Use UIDStoreFlags to add or remove flags for a message identified bu it's uniqueness identifier in the IMAP4 mailbox.


TIdIMAP4.UIDRetrieveHeader
TIdIMAP4, See Also
Retrieves the RFC 822 headers for a specific message.
function UIDRetrieveHeader(const AMsgUID: String; AMsg: TIdMessage): Boolean;
Parameters
const AMsgUID: String
Uniqueness identifier for the desired message.
AMsg: TIdMessage
Message instance to store retrieved headers.
Return Value
Boolean - True on success.
Description
UIDRetrieveHeader is a Boolean function used to retrieve message headers for the uniqueness identifier specified in AMsgId. UIDRetrieveHeader retrieves all IMAP4 headers associated with the message in the IMAP4 mailbox. UIDRetrieveHeader implements the IMAP4 UID FETCH using AMsgId and other arguments needed to retrieve the RFC 822 Headers for the message.

UIDRetrieveHeader requires that the ConnectionState property contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value will be set to False.

UIDRetrieveHeader reads the multi-line IMAP4 protocol response, and calls ReceiveHeader toload the RFC 822 headers into the AMsg message instance. The return value for the method will be True when the protocol response code from the IMAP4 server is wsOk.


TIdIMAP4.UIDRetrieveMailBoxSize
TIdIMAP4, See Also
Calculates the size of all messages in a mailbox.
function UIDRetrieveMailBoxSize: Integer;
Return Value
Integer - Size of the mailbox in bytes.
Description
UIDRetrieveMailBoxSize is an Integer function used to retrieve the size in bytes of the currently selected IMAP4 mailbox. UIDRetrieveMailBoxSize requires the ConnectionState property to contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value will be set to -1. The return value will be 0 when the selected TIdMailBox does not contain any messages.

UIDRetrieveMailBoxSize implements the IMAP4 UID FETCH command using arguments to select the RFC message size for all messages in the mailbox. The multi-line protocol response from the IMAP4 server is parsed to determine the size of each message, and the total is assigned as the return value for the method.

Use RetrieveMailBoxSize to calculate the size of all messages in the mailbox regardless of uniqueness identifiers for messages. RetrieveMailBoxSize will include messages marked for deletion, and draft messages.


TIdIMAP4.UIDRetrieveMsgSize
TIdIMAP4, See Also
Retrieves the size of a message in the IMAP4 mailbox.
function UIDRetrieveMsgSize(const AMsgUID: String): Integer;
Parameters
const AMsgUID: String
Uniqueness identifier for the desired message.
Return Value
Integer - Size of the message in the IMAP4 mailbox.
Description
UIDRetrieveMsgSize is an Integer function used to retrieve the size of a message in the IMAP4 mailbox by the uniqueness identifier specified in AMsgID. UIDRetrieveMsgSize requires the ConnectionState property to contain the value csSelected, or an EIdConnectionStateError exception will be raised and the return value is set to -1.

UIDRetrieveMsgSize implements the IMAP4 UID FETCH using AMsgID and flags need to retrieve the RFC 822 message size from the currently selected IMAP4 mailbox. When the protocol response code is wsOk, the values are parsed to determine the number of bytes required for the message in the mailbox. The return value for the method is -1 when a response code other than wsOk is received from the IMAP4 server.

Use RetrieveMsgSize to retrieve the size for a message that can be marked for deletion or saved as a draft.


TIdIMAP4.UIDRetrievePeek
TIdIMAP4, See Also
Retrieves a specified message from a mailbox preserving its Seen flag.
function UIDRetrievePeek(const AMsgUID: String; AMsg: TIdMessage): Boolean;
Parameters
const AMsgUID: String
Uniqueness identifier for the desired message.
AMsg: TIdMessage
Stores the message retrieve from mailbox.
Return Value
Boolean - True on success.
Description
UIDRetrievePeek is a Boolean function used to retrieve a message identified by the Uniqueness identifier specified in AMsgID, and to store the message contents in AMsg. Unlike UIDRetrieve, UIDRetrievePeek preserves the state of the "Seen" flag for the message in the mailbox.

UIDRetrievePeek requires that ConnectionState contain the value csSelected, or an EIdConnectionStateError exception wil be raised. RetrievePeek sends the IMAP4 UID FETCH command to retrieve data for the specified message in AMsgID. UIDRetrievePeek insures that the server response contains untagged responses for the desired message prior to calling ReceiveHeader and receiving the body to populate the message instance.

UIDRetrievePeek sets the return value to True when the protocol response code contains the value wsOk.

Use RetrievePeek to retrieve a message by it's relative message number in the IMAP4 mailbox.

Use UIDRetrieve to retrieve a message by it's uniquesness identifier, and mark the message as read in the IMAP4 mailbox.


TIdIMAP4.UIDStoreFlags
TIdIMAP4, See Also
Applies flag values using the desired storage method for a specified message.
function UIDStoreFlags(const AMsgUID: String; const AStoreMethod: TIdIMAP4StoreDataItem; const AFlags: TIdMessageFlagsSet): Boolean;
Parameters
const AMsgUID: String
Uniqueness identifier for the affected message.
const AStoreMethod: TIdIMAP4StoreDataItem
Storage method for flag values.
const AFlags: TIdMessageFlagsSet
Flag values to apply to the affected message.
Return Value
Boolean - True on success.
Description
UIDStoreFlags is a Boolean function used to apply the set of TIdMessageFlags values in AFlags to the message specified by the uniqueness identifier specified in AMsgID. AStoreMethod indicates the storage method to be used for the message flag values.

AMsgID is the uniqueness identifier for the affected message. When AMsgID is omitted, the return value for the method is set to False and exits to the calling procedure or function.

UIDStoreFlags requires the ConnectionState property to contain the value csSelected, or an EIdConnectionStateError exception is raised and the return value for the method is set to False.

UIDStoreFlags implements the IMAP4 UID STORE command using AMsgID and the directives needed to apply the flags storage methods and values specified in AStoreMethod and AFlags. The return value for the method will be True when the IMAP4 protocol reopens code is wsOk.


TIdIMAP4.UnsubscribeMailBox
TIdIMAP4, See Also
Removes a mailbox from the list of "active" or "subscribed" mailboxes.
function UnsubscribeMailBox(const AMBName: String): Boolean;
Parameters
const AMBName: String
Mailbox name to removed from the active or subscribed list.
Return Value
Boolean - True on success.
Description
UnsubscribeMailBox is a Boolean function used to remove the mailbox name specified in AMBName to the list of "active" or "subscribed" mailboxes on the IMAP4 server. UnsubscribeMailBox updates the values that are returned by the IMAP4 LSUB command.

UnsubscribeMailBox requires that the ConnectionState for the client contain the value csAuthenticated or csSelected to perform the IMAP4 function. SubscribeMailBox can raise an EIdConnectionStateError exception with the message RSIMAP4ConnectionStateError if ConnectionState contains a value other than csAuthenticated or csSelected.

UnsubscribeMailBox calls SendCmd using the IMAP4 UNSUBSCRIBE command and the value specified in AMBName as an argument. UnsubscribeMailBox returns True when the response code from the IMAP4 server is wsOk.

Use SubscribeMailBox to add a specified mailbox from the "active" or "subscibed" list.


TIdIMAP4.OnAlert
TIdIMAP4, See Also
Event handler for alert messages in IMAP4 responses.
property OnAlert: TIdAlertEvent;
Description
OnAlert is a TIdAlertEvent property that represents the event handler signalled to allow an IMAP4 client to receive alert messages. Alert messages can occur in results from an IMAP4 command that selects the current mailbox, or appends a new message to a mailbox. OnAlert is signalled when the alert message is parsed from the lines in an IMAP4 response.

Applications must assign a procedure to the OnAlert event handler to allow responding to alert messages.


Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.