Removes UIDL that is not existent on server from local UIDL file.
This method is obsoleted by SyncUIDLEX
[Visual Basic 6.0] Public Sub SyncUIDL( oServer As MailServer, _ infos() As MailInfo _ )
[Visual C++] public: SyncUIDL( MailServer* oServer, VARIANT infos );
Parameters
This method removes UIDL that is not existent on server from local UIDL file.
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, VBScript, Visual C++] The following example demonstrates how To retrieve email with EAGetMail POP3 & IMAP Component, 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]
Public Sub ReceiveMail( _
ByVal sServer As String, _
ByVal sUserName As String, _
ByVal sPassword As String, _
ByVal bSSLConnection As Boolean, _
ByVal bLeaveCopy)
Const MailServerPop3 = 0
Const MailServerImap4 = 1
Const MailServerEWS = 2
Const MailServerDAV = 3
Const MailServerMsGraph = 4
Dim oClient As New EAGetMailObjLib.MailClient
oClient.LicenseCode = "TryIt"
'bLeaveCopy = True will leave a copy of message on the server
'bLeaveCopy = False will delete the email after the download is finished.
'To receive email from imap4 server, please change
'MailServerPop3 to MailServerImap4 to MailServer.Protocol
'To receive email with Exchange Web Service, please change
'MailServerPop3 to MailServerEWS to MailServer.Protocol
'To receive email with Exchange WebDAV, please change
'MailServerPop3 to MailServerDAV to MailServer.Protocol
'Exchange Server supports POP3/IMAP4 protocol as well, but in Exchange 2007
'or later version, POP3/IMAP4 service is disabled by default. If you don't want to use POP3/IMAP4
'to download email from Exchange Server, you can use Exchange Web Service(Exchange 2007/2010 or
'later version) or WebDAV(Exchange 2000/2003) protocol.
'For Exchange Web Service/WebDAV, please ignore
'Port property. But for Exchange Web Service, please set SSLConnection to True
Dim oServer As New EAGetMailObjLib.MailServer
oServer.Server = sServer
oServer.User = sUserName
oServer.Password = sPassword
oServer.SSLConnection = bSSLConnection
oServer.Protocol = MailServerPop3
'By default, the pop3 port is 110, imap4 port is 143,
'the pop3 ssl port is 995, imap4 ssl port is 993
'you can also change the port like this
'oServer.Port = 110
If oServer.Protocol = MailServerImap4 Then
If oServer.SSLConnection Then
oServer.Port = 993 'SSL IMAP4
Else
oServer.Port = 143 'IMAP4 normal
End If
Else
If oServer.SSLConnection Then
oServer.Port = 995 'SSL POP3
Else
oServer.Port = 110 'POP3 normal
End If
End If
' UIDL is the identifier of every email on POP3/IMAP4/Exchange server, to avoid retrieve
' the same email from server more than once, we record the email UIDL retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' UIDLManager wraps the function to write/read uidl record from a text file.
Dim oUIDLManager As New EAGetMailObjLib.UIDLManager
' Create a folder to store uidl file and email files
Dim localfolder As String
localfolder = "d:\mailfolder"
Dim uidlfile As String
uidlfile = "d:\mailfolder\uidl.txt"
Dim oTools As New EAGetMailObjLib.Tools
If Not oTools.ExistFile(localfolder) Then
oTools.CreateFolder localfolder
End If
On Error GoTo ErrorHandle
' Load existed uidl records to UIDLManager
oUIDLManager.Load uidlfile
oClient.Connect oServer
Dim infos
infos = oClient.GetMailInfos()
' Remove the local uidl which is not existed on the server.
oUIDLManager.SyncUIDL oServer, infos
oUIDLManager.Update
Dim i, Count
Count = UBound(infos)
For i = LBound(infos) To Count
Dim info As EAGetMailObjLib.MailInfo
Set info = infos(i)
Debug.Print "UIDL: " & info.UIDL
'This email has not been downloaded
If oUIDLManager.FindUIDL(oServer, info.UIDL) Is Nothing Then
Dim fileName As String
'generate a random file name by current local datetime,
'you can use your method to generate the filename if you do not like it
Dim shortName As String
shortName = oTools.GenFileName(i) & ".eml"
fileName = localfolder & "\" & shortName
Dim oMail As EAGetMailObjLib.Mail
Set oMail = oClient.GetMail(info)
'Save mail to local disk
oMail.SaveAs fileName, True
If bLeaveCopy Then
'add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager.AddUIDL oServer, info.UIDL, shortName
End If
End If
Next
If Not bLeaveCopy Then
For i = LBound(infos) To Count
oClient.Delete infos(i)
' Remove UIDL from local uidl file.
oUIDLManager.RemoveUIDL oServer, infos(i).UIDL
Next
End If
' Delete method just mark the email as deleted,
' Quit method expunge the emails from server permanently.
oClient.Quit
oUIDLManager.Update
Exit Sub
ErrorHandle:
'Error handle
MsgBox Err.Description
oUIDLManager.Update
oClient.Close
End Sub
[VBScript]
Public Sub ReceiveMail( _
ByVal sServer As String, _
ByVal sUserName As String, _
ByVal sPassword As String, _
ByVal bSSLConnection As Boolean, _
ByVal bLeaveCopy)
Const MailServerPop3 = 0
Const MailServerImap4 = 1
Const MailServerEWS = 2
Const MailServerDAV = 3
Const MailServerMsGraph = 4
Dim oClient
Set oClient = CreateObject("EAGetMailObj.MailClient")
oClient.LicenseCode = "TryIt"
'bLeaveCopy = True will leave a copy of message on the server
'bLeaveCopy = False will delete the email after the download is finished.
'To receive email from imap4 server, please change
'MailServerPop3 to MailServerImap4 to MailServer.Protocol
'To receive email with Exchange Web Service, please change
'MailServerPop3 to MailServerEWS to MailServer.Protocol
'To receive email with Exchange WebDAV, please change
'MailServerPop3 to MailServerDAV to MailServer.Protocol
'Exchange Server supports POP3/IMAP4 protocol as well, but in Exchange 2007
'or later version, POP3/IMAP4 service is disabled by default. If you don't want to use POP3/IMAP4
'to download email from Exchange Server, you can use Exchange Web Service(Exchange 2007/2010 or
'later version) or WebDAV(Exchange 2000/2003) protocol.
'For Exchange Web Service/WebDAV, please ignore
'Port property. But for Exchange Web Service, please set SSLConnection to True
Dim oServer
Set oServer = CreateObject("EAGetMailObj.MailServer")
oServer.Server = sServer
oServer.User = sUserName
oServer.Password = sPassword
oServer.SSLConnection = bSSLConnection
oServer.Protocol = MailServerPop3
'By default, the pop3 port is 110, imap4 port is 143,
'the pop3 ssl port is 995, imap4 ssl port is 993
'you can also change the port like this
'oServer.Port = 110
If oServer.Protocol = MailServerImap4 Then
If oServer.SSLConnection Then
oServer.Port = 993 'SSL IMAP4
Else
oServer.Port = 143 'IMAP4 normal
End If
Else
If oServer.SSLConnection Then
oServer.Port = 995 'SSL POP3
Else
oServer.Port = 110 'POP3 normal
End If
End If
' UIDL is the identifier of every email on POP3/IMAP4/Exchange server, to avoid retrieve
' the same email from server more than once, we record the email UIDL retrieved every time
' if you delete the email from server every time and not to leave a copy of email on
' the server, then please remove all the function about uidl.
' UIDLManager wraps the function to write/read uidl record from a text file.
Dim oUIDLManager
Set oUIDLManager = CreateObject("EAGetMailObj.UIDLManager")
' Create a folder to store uidl file and email files
Dim localfolder
localfolder = "d:\mailfolder"
Dim uidlfile
uidlfile = "d:\mailfolder\uidl.txt"
Dim oTools
Set oTools = CreateObject("EAGetMailObj.Tools")
If Not oTools.ExistFile(localfolder) Then
oTools.CreateFolder localfolder
End If
' Load existed uidl records to UIDLManager
oUIDLManager.Load uidlfile
oClient.Connect oServer
Dim infos
infos = oClient.GetMailInfos()
' Remove the local uidl which is not existed on the server.
oUIDLManager.SyncUIDL oServer, infos
oUIDLManager.Update
Dim i, Count
Count = UBound(infos)
For i = LBound(infos) To Count
Dim info
Set info = infos(i)
WScript.Echo "UIDL: " & info.UIDL
'This email has not been downloaded
If oUIDLManager.FindUIDL(oServer, info.UIDL) Is Nothing Then
Dim fileName
'generate a random file name by current local datetime,
'you can use your method to generate the filename if you do not like it
Dim shortName
shortName = oTools.GenFileName(i) & ".eml"
fileName = localfolder & "\" & shortName
Dim oMail
Set oMail = oClient.GetMail(info)
'Save mail to local disk
oMail.SaveAs fileName, True
If bLeaveCopy Then
'add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager.AddUIDL oServer, info.UIDL, shortName
End If
End If
Next
If Not bLeaveCopy Then
For i = LBound(infos) To Count
oClient.Delete infos(i)
' Remove UIDL from local uidl file.
oUIDLManager.RemoveUIDL oServer, infos(i).UIDL
Next
End If
' Delete method just mark the email as deleted,
' Quit method expunge the emails from server permanently.
oClient.Quit
oUIDLManager.Update
End Sub
[Visual C++]
#include "stdafx.h"
#include <windows.h>
#include "eagetmailobj.tlh"
using namespace EAGetMailObjLib;
void ReceiveMail(
LPCTSTR sServer,
LPCTSTR sUserName,
LPCTSTR sPassword,
bool bSSLConnection,
bool bLeaveCopy)
{
::CoInitialize(NULL);
const int MailServerPop3 = 0;
const int MailServerImap4 = 1;
const int MailServerEWS = 2;
const int MailServerDAV = 3;
const int MailServerMsGraph = 4;
try
{
IMailClientPtr oClient;
oClient.CreateInstance(__uuidof(EAGetMailObjLib::MailClient));
IMailServerPtr oServer;
oServer.CreateInstance(__uuidof(EAGetMailObjLib::MailServer));
oClient->LicenseCode = _T("TryIt");
oServer->Server = sServer;
oServer->User = sUserName;
oServer->Password = sPassword;
INT nProtocol = MailServerPop3;
//bLeaveCopy = true will leave a copy of message on the server
//bLeaveCopy = false will delete the email after the download is finished.
//To receive email from imap4 server, please change
//MailServerPop3 to MailServerImap4 in MailServer constructor
//To receive email with Exchange Web Service, please change
//MailServerPop3 to MailServerEWS to MailServer.Protocol
//To receive email with Exchange WebDAV, please change
//MailServerPop3 to MailServerDAV to MailServer.Protocol
//Exchange Server supports POP3/IMAP4 protocol as well, but in Exchange 2007
//or later version, POP3/IMAP4 service is disabled by default. If you don't want to use POP3/IMAP4
//to download email from Exchange Server, you can use Exchange Web Service(Exchange 2007/2010 or
//later version) or WebDAV(Exchange 2000/2003) protocol.
//For Exchange Web Service/WebDAV, please ignore
//Port property. But for Exchange Web Service, please set SSLConnection to True
oServer->Protocol = nProtocol;
if(nProtocol == MailServerPop3)
{
if(bSSLConnection)
{
oServer->Port = 995;
oServer->SSLConnection = VARIANT_TRUE;
}
else
{
oServer->Port = 110;
}
}
else
{
if(bSSLConnection)
{
oServer->Port = 993;
oServer->SSLConnection = VARIANT_TRUE;
}
else
{
oServer->Port = 143;
}
}
// UIDL is the identifier of every email on POP3/IMAP4/Exchange server, to avoid retrieve
// the same email from server more than once, we record the email UIDL retrieved every time
// if you delete the email from server every time and not to leave a copy of email on
// the server, then please remove all the function about uidl.
// UIDLManager wraps the function to write/read uidl record from a text file.
IUIDLManagerPtr oUIDLManager;
oUIDLManager.CreateInstance(__uuidof(EAGetMailObjLib::UIDLManager));
IToolsPtr oTools;
oTools.CreateInstance(__uuidof(EAGetMailObjLib::Tools));
// Create a folder to store uidl file and email files
LPCTSTR pszFolder = _T("d:\\mailfolder");
LPCTSTR pszUIDLFile = _T("d:\\mailfolder\\uidl.txt");
if( oTools->ExistFile(pszFolder) == VARIANT_FALSE)
{
oTools->CreateFolder(pszFolder);
}
// Load existed UIDL records to UIDLManager
oUIDLManager->Load(pszUIDLFile);
oClient->Connect(oServer);
_variant_t arInfo = oClient->GetMailInfos();
// Remove the local uidl which is not existed on the server.
oUIDLManager->SyncUIDL(oServer, arInfo);
oUIDLManager->Update();
SAFEARRAY *psa = arInfo.parray;
long LBound = 0, UBound = 0;
SafeArrayGetLBound(psa, 1, &LBound);
SafeArrayGetUBound(psa, 1, &UBound);
INT count = UBound-LBound+1;
for(long i = LBound; i <= UBound; i++)
{
_variant_t vtInfo;
SafeArrayGetElement(psa, &i, &vtInfo);
IMailInfoPtr pInfo;
vtInfo.pdispVal->QueryInterface(__uuidof(IMailInfo), (void**)&pInfo);
_tprintf(_T("UIDL: %s\r\n"), (TCHAR*)pInfo->UIDL);
IUIDLItemPtr oUIDLItem = oUIDLManager->FindUIDL(oServer, pInfo->UIDL);
if(oUIDLItem != NULL)
{
// this email has been downloaded before.
continue;
}
// this email has not been downloaded before.
IMailPtr oMail = oClient->GetMail(pInfo);
TCHAR fileName[MAX_PATH+1];
memset( fileName, 0, sizeof(fileName));
SYSTEMTIME curtm;
::GetLocalTime(&curtm);
// generate a random file name by current local datetime,
// you can use your method to generate the filename if you do not like it
::wsprintf( fileName, _T("%04d%02d%02d%02d%02d%02d%03d%d.eml"),
curtm.wYear,
curtm.wMonth,
curtm.wDay,
curtm.wHour,
curtm.wMinute,
curtm.wSecond,
curtm.wMilliseconds,
i);
TCHAR fullPath[MAX_PATH+1];
memset( fullPath, 0, sizeof(fullPath));
::wsprintf(fullPath, _T("%s\\%s"), pszFolder, fileName);
oMail->SaveAs(fullPath, VARIANT_TRUE);
oMail.Release();
if(bLeaveCopy)
{
// Add the email uidl to uidl file to avoid we retrieve it next time.
oUIDLManager->AddUIDL( oServer, pInfo->UIDL, (const TCHAR*)fileName);
}
}
if(!bLeaveCopy)
{
for(long i = LBound; i <= UBound; i++)
{
_variant_t vtInfo;
SafeArrayGetElement(psa, &i, &vtInfo);
IMailInfoPtr pInfo;
vtInfo.pdispVal->QueryInterface(__uuidof(IMailInfo), (void**)&pInfo);
oClient->Delete(pInfo);
// Remove UIDL from local uidl file.
oUIDLManager->RemoveUIDL(oServer, pInfo->UIDL);
}
}
// Delete method just mark the email as deleted,
// Quit method expunge the emails from server permanently.
arInfo.Clear();
oUIDLManager->Update();
oClient->Quit();
}
catch(_com_error &ep)
{
_tprintf(_T("ERROR: %s\r\n"), (TCHAR*)ep.Description());
}
::CoUninitialize();
}
See Also
Online Tutorials
Using UIDL Function to Mark the Email has been downloaded/read in VB6 - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read in Delphi - Tutorial
Using UIDL Function to Mark the Email has been downloaded/read VC++ - Tutorial