TPop3Cli.Uidl
Main page -> ICS component reference -> TPop3Cli -> Uidl
Definition
<syntaxhighlight lang="delphi"> procedure Uidl; virtual; </syntaxhighlight>
Description
Sends UIDL command to a POP3 server. The command can be issued in 2 modes - list mode and single mode. This command is valid in POP3 TRANSACTION state so you must issue it after you've successfully authenticated. To issue it in list mode set MsgNum property to 0 before calling this method. To issue it in single mode set MsgNum property to index of the message you want to get UIDL for. UIDL returns unique ID string from POP3 server that identifies a particular message. This command belongs to optional POP3 commands and may not be supported by all servers so you must prepare your code to handle eventual -ERR error response from server indicating that the command has failed or is not supported. Note though, that most servers will support this command.
<syntaxhighlight lang="delphi"> // This will issue Uidl in list mode (triggers OnUidl events) Pop3Cli.MsgNum := 0; Pop3Cli.Uidl; </syntaxhighlight>
<syntaxhighlight lang="delphi"> // This will issue Uidl in single mode for the message 1 (does not trigger OnUidl events) Pop3Cli.MsgNum := 1; Pop3Cli.Uidl; </syntaxhighlight>
If the command is issued in single mode it returns the result from POP3 server in the next LastResponse property. Also, MsgUidl will hold the unique ID string. If it is issued in list mode, LastResponse will be empty but it will trigger OnUidlBegin, OnUidlLine and OnUidlEnd events instead which you can use to appropriately handle the output from the UIDL. When the events occur, MsgNum and MsgUidl contain the appropriate values of the currently listed message that the event is generated for.
Delphi Example
For this example to work, drop a Memo, Pop3Cli and Button components on the form. Then, add OnClick event to the button and OnUidlBegin, OnUidlLine, OnUidlEnd and OnRequestDone events to the Pop3Cli component and use the following code.
<syntaxhighlight lang="delphi"> //--------------------------------------------------------------------------- procedure TForm1.Button1Click(Sender: TObject) begin
// Clear the memo for clean output Memo1.Lines.Clear;
// Fill the following with your actual server details Pop3Cli1.Host := 'pop3.yourserver.com'; Pop3Cli1.UserName := 'username'; Pop3Cli1.PassWord := 'password'; Pop3Cli1.Connect;
end;
//--------------------------------------------------------------------------- procedure TForm1.Pop3Cli1RequestDone(Sender: TObject; RqType: TPop3Request; Error: WORD) var
UidlAll: Boolean;
begin
// Toggle this to change the behaviour of UIDL command from single to list and back UidlAll := true;
// Everything OK, no errors on last request
if Error = 0 then begin
if Pop3Cli1.LastResponse <> then
Memo1.Lines.Add(Pop3Cli1.LastResponse);
case (RqType) of
pop3Connect: Pop3Cli1.User;
pop3User: Pop3Cli1.Pass;
pop3Pass: Pop3Cli1.Stat;
pop3Quit: ; // Nothing
pop3Stat:
begin
if UidlAll then begin
Pop3Cli1.MsgNum := 0;
Pop3Cli1.Uidl;
end
else begin
Pop3Cli1.MsgNum := 1;
Pop3Cli1.Uidl;
end;
end;
pop3List: // Do not list if it's in "list" mode
begin
if not UidlAll
Memo1.Lines.Add('Message='+ IntToStr(Pop3Cli1.MsgNum) +
', Size=' + Pop3Cli1.MsgUidl);
Pop3Cli1.Quit;
end;
end;
end;
// UIDL is optional command and needs special handling on error else if RqType = pop3Uidl then begin
if Pop3Cli1.LastResponse <> Memo1.Lines.Add(Pop3Cli1.LastResponse);
Memo1.Lines.Add('UIDL is not supported by this server');
Pop3Cli1.Quit;
end;
else
begin
Memo1.Lines.Add('Some other error occurred.');
// Remove other events to make sure they don't occur after Abort() call
Pop3Cli1.OnRequestDone = nil;
Pop3Cli1.OnUidlBegin = nil;
Pop3Cli1.OnUidlLine = nil;
Pop3Cli1.OnUidlEnd = nil;
// Close connection and terminate as fast as possible
Pop3Cli1.Abort;
end;
end;
//--------------------------------------------------------------------------- procedure TForm1.Pop3Cli1UidlBegin(Sender: TObject) begin
Memo1.Lines.Add('Uidl Begin');
end;
//--------------------------------------------------------------------------- procedure TForm1.Pop3Cli1UidlLine(Sender: TObject) begin
Memo1.Lines.Add('Uidl line='+ Pop3Cli1.LastResponse);
Memo1.Lines.Add('Message='+ IntToStr(Pop3Cli1.MsgNum) +
', Size=' + Pop3Cli1.MsgUidl);
end;
//--------------------------------------------------------------------------- procedure TForm1.Pop3Cli1UidlEnd(Sender: TObject) begin
Memo1.Lines.Add('Uidl End');
end; //--------------------------------------------------------------------------- </syntaxhighlight>
C++ Example
For this example to work, drop a Memo, Pop3Cli and Button components on the form. Then, add OnClick event to the button and OnUidlBegin, OnUidlLine, OnUidlEnd and OnRequestDone events to the Pop3Cli component and use the following code.
<syntaxhighlight lang="cpp"> //--------------------------------------------------------------------------- void __fastcall TForm1::Button1Click(TObject *Sender) { // Clear the memo for clean output Memo1->Lines->Clear();
// Fill the following with your actual server details Pop3Cli1->Host = "pop3.yourserver.com"; Pop3Cli1->UserName = "username"; Pop3Cli1->PassWord = "password"; Pop3Cli1->Connect(); } //--------------------------------------------------------------------------- void __fastcall TForm1::Pop3Cli1RequestDone(TObject *Sender, TPop3Request RqType, WORD Error) { // Toggle this to change the behaviour of UIDL command from single to list and back bool UidlAll = true;
// Everything OK, no errors on last request if (Error == 0) {
if (Pop3Cli1->LastResponse != "") Memo1->Lines->Add(Pop3Cli1->LastResponse);
switch (RqType) {
case pop3Connect: Pop3Cli1->User(); break;
case pop3User: Pop3Cli1->Pass(); break;
case pop3Pass: Pop3Cli1->Stat(); break;
case pop3Quit: break;
case pop3Stat: if (UidlAll) {
Pop3Cli1->MsgNum = 0;
Pop3Cli1->Uidl();
}
else {
Pop3Cli1->MsgNum = 1;
Pop3Cli1->Uidl();
}
break;
case pop3Uidl: // Do not list if it's in "list" mode
if (!UidlAll) {
Memo1->Lines->Add("Message="+IntToStr(Pop3Cli1->MsgNum) + ", UID="+Pop3Cli1->MsgUidl);
}
Pop3Cli1->Quit();
break;
default: break;
}
}
// UIDL is optional command and needs special handling on error else if (RqType == pop3Uidl) {
if (Pop3Cli1->LastResponse != "") Memo1->Lines->Add(Pop3Cli1->LastResponse);
Memo1->Lines->Add("UIDL is not supported by this server");
Pop3Cli1->Quit();
}
else
{
Memo1->Lines->Add("Some other error occurred.");
Pop3Cli1->OnRequestDone = NULL; Pop3Cli1->OnUidlBegin = NULL; Pop3Cli1->OnUidlLine = NULL; Pop3Cli1->OnUidlEnd = NULL;
// Close connection and terminate as fast as possible Pop3Cli1->Abort(); }
} //--------------------------------------------------------------------------- void __fastcall TForm1::Pop3Cli1UidlBegin(TObject *Sender) { Memo1->Lines->Add("Uidl Begin"); } //--------------------------------------------------------------------------- void __fastcall TForm1::Pop3Cli1UidlLine(TObject *Sender) { Memo1->Lines->Add("Uidl line="+Pop3Cli1->LastResponse); Memo1->Lines->Add("Message="+IntToStr(Pop3Cli1->MsgNum) + ", UID="+Pop3Cli1->MsgUidl); } //--------------------------------------------------------------------------- void __fastcall TForm1::Pop3Cli1UidlEnd(TObject *Sender) { Memo1->Lines->Add("Uidl End"); } //--------------------------------------------------------------------------- </syntaxhighlight>
