UIDLManager.Item Method


Gets specified UIDLItem instance by index.

[Visual Basic 6.0]
Public Function Item( Index As Long _
) As UIDLItem
[Visual C++]
public: Item(LONG Index, 
UIDLItem **pVal);

Return Value

A UIDLItem instance.

Remarks

Sometimes the developers want to leave a copy of email on the POP3/IMAP4/Exchange server for backup, so they don't delete the email after the email was received. The common issue is how to detect if the email has been retrieved by the application already, otherwise, all the emails on the server will be retrieved again and again. In this case, we should use the Unique Identifier (UIDL) to avoid to receive the same email more than once.

Using Unique Identifier (UIDL)

The mail server assigns an unique identifier for every email in the same account. You can get the UIDL for every email by MailInfo.UIDL property. To avoid to receive the same email twice, the best way is storing the UIDL of email retrieved to a text file or database. Next time before you retrieve the email, compare your local uidl list with remote uidl. If this uidl exists in your local uidl list, then you don't receive it, otherwise you should receive it.

Difference with UIDL in POP3/IMAP4/Exchange Web Service/WebDAV

UIDL is always unique in IMAP4 and it is always increasing integer. UIDL in POP3 can be any valid asc-ii characters, and the UIDL may be reused by POP3 server if the email with the UIDL has been deleted from the server, so we suggest that you should remove the uidl from your local uidl list if the uidl is no longer existed on the POP3 server. UIDL is also unique in Exchange Web Service/WebDAV, but the UIDL is string but not integer. Every email has a unique identifier (UIDL) on IMAP4 server. It is a 32bit integer and it is always unique in your email account life time. So we can use the integer as file name to identify if the email has been downloaded. There is a little bit different in POP3 server. The UIDL is only unique in the email life time. That means if the email was deleted from the server, other email can use the old unique identifier. Another problem is: UIDL in POP3 server can be any number or characters, so we cannot use UIDL as the file name, because UIDL may contain invalid characters for file name. For Exchange Web Service/WebDAV, although the UIDL is always unique in your email account, but UIDL may also contain invalid characters for file name.

Total Solution

UIDLManager provides an easy way to maintain UIDL between your server and your local client. How does it work? It stores UIDL collection to a local disk file and you can use this object to add, remove and search UIDL with this local file.

UIDL File Format

With UIDLManager, you can use any file name as the UIDL local file, but we suggest that you use different UIDL file for different email account. In the UIDL file, each line presents a UIDL information.

"mailserver#user#protocol","UIDL","Local File Name","Download Date Time","Flags"
"mailserver#user#protocol","UIDL1","Local File Name1","Download Date Time","Flags"
        

You can use UIDLManager to record the UIDL of the email that you have downloaded; you can also associate the local file name and flags to UIDLItem object. Then you can use UIDLManager to detect if the email has been downloaded, when it has been downloaded. If it has been downloaded, what local file it has saved to.

Example

[Visual Basic 6.0] The following example demonstrates how to enumerate UIDL with EAGetMail POP3 & IMAP ActiveX Object, but it doesn't demonstrates the events and mail parsing usage. To get the full samples of EAGetMail, please refer to Samples section.

[Visual Basic 6.0]
Sub EnumerateUIDLItem()
    Dim oUIDLManager As New EAGetMailObjLib.UIDLManager
    ' Load UIDL from local uidl file
    oUIDLManager.Load ("d:\mailfolder\uidl.txt")

    Dim i, Count As Integer
    Count = oUIDLManager.Count
    For i = 0 To Count - 1
        ' Get UIDLItem instance by index
        Dim oUIDL As EAGetMailObjLib.UIDLItem
        Set oUIDL = oUIDLManager.Item(i)
        MsgBox "ServerUser: " & oUIDL.ServerUser
        MsgBox "UIDL: " & oUIDL.UIDL
        MsgBox "FileName: " & oUIDL.fileName
        MsgBox "Download Time: " & oUIDL.DownloadTime
        MsgBox "Flags: " & oUIDL.Flags
    Next
End Sub

See Also

MailInfo.UIDL Property

Online Tutorials

Using UIDL Function to Mark the Email has been downloaded/read in C# - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read in VB.NET - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read C++/CLI - Tutorial