Boolean - True on success.

GetUID is a Bollean function used to retrieve the UID (unique identifier) for a specified relative message number. GetUID allows the user to switch from relative message numbers to UIDs. 

Please note that TIdIMAP4 stores the UID as a string rather than a number (it is defined as a number in the RFCs) for historical reasons but is simply converted to a number via StrToInt should you wish to do so. Storing it as a string rather than a number is of no practical consequence or disadvantage, and changing it in TIdIMAP4 would only break existing code. 

The IMAP protocol uses two methods for message numbering: "relative" message numbers and UIDs. "Relative" message numbers are sequential numbers starting from 1 for each message in a mailbox - this is just the index number of the message in the TIdMailBox plus 1 (the first index is 0 in TIdMailBox and 1 on the IMAP server). UIDs are unique numbers assigned by the IMAP server, which rarely, if ever, change. While they can theoretically be changed as per the IMAP protocol, they certainly should not change during the period you have a mailbox open. While you may be able to get away with using the relative message number, you will get into difficulties if two sessions are accessing the same mailbox, and one of them deletes a message - the relative message for the other session will then be incorrect. As an example, this can arise where a manager and his/her secretary are accessing the manager's mailbox. Even if you are using UIDs, this also gives the problem that the second session may also try to modify the deleted message, but the solution is to always call the UIDRetrieveFlags function before you try to modify the message - it will return False if the message has been deleted. 

IMAP implements a mechanism for checking if UIDs are valid over long periods. This can be useful in certain circumstances where you may need to keep track of a message between sessions or over long periods, such as weeks. A possible application that would do this is one that monitors a particular mailbox, such as sales leads, to ensure that someone reads them, and if they do not after say a week, emails an administrator to assign someone to read them. In that case, you don't want to create a high load on the IMAP server by continually scanning through the mailbox. While there are different methods of doing this, one way is to periodically call UIDCheckMsgSeen or UIDRetrieveFlags for the given UID. The only potential problem you have is the unlikely/infrequent possibility of some other program re-ordering the mailbox, which will make your UIDs invalid. 

The return value for the method indicates if the UID was successfully retrieved for the specified relative message number. 

GetUID validates the value in AMsgNum to ensure that it contains a positive non-zero value. An EIdNumberInvalid exception is raised when the relative message number contains an invalid value. 

GetUID requires that ConnectionState contain the value csSelected, indicating that a mailbox has been previously selected using SelectMailBox, or an EIdConnectionStateError exception is raised. 

GetUID calls SendCmd to send the IMAP4 FETCH command using the values in AMsgNum and the fetch data item for the UID value. Some servers return NO if the requested message number is not present (e.g. Cyrus), others return OK but no data (CommuniGate). If the server response contains the value IMAP_OK, the values in LastCmdResult are parsed to determine the UID value. 

To check if your UIDs have changed, use StatusMailBox command and check for changes to the UIDValidity field - the IMAP protocol guarantees that the server will change this value if it changes the UIDs of any existing messages.