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.");

   // Remove other events to make sure they don't occur after Abort() call
   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>