TPop3

Source: source/classes/tpop3.prg

TPop3 is FiveWin's email retrieval class, implementing the POP3 protocol to receive messages from a mail server. It handles the full POP3 session lifecycle: connect, authenticate, list messages, retrieve content, optionally delete messages from the server, and quit. Like TSmtp, it is built on top of TSocket.

Protocol Flow

sequenceDiagram participant App as FiveWin App participant POP3 as TPop3 participant Server as POP3 Server App->>POP3: GetMail() POP3->>Server: USER username Server-->>POP3: +OK POP3->>Server: PASS password Server-->>POP3: +OK POP3->>Server: STAT Server-->>POP3: +OK count size loop For each message POP3->>Server: RETR n Server-->>POP3: [message content] POP3->>Server: DELE n (if lDelMsgs=.T.) Server-->>POP3: +OK end POP3->>Server: QUIT Server-->>POP3: +OK

Key DATA Members

DATA	Type	Default	Description
`cIPServer`	Character		POP3 server hostname or IP address
`nPort`	Numeric	`110`	POP3 server port
`User`	Character		Username for authentication
`Pass`	Character		Password for authentication
`aMsgs`	Array		Array of retrieved email messages (raw POP3 format)
`nAtMsg`	Numeric		Index of the message currently being retrieved
`lDelMsgs`	Logical	`.T.`	Delete messages from server after retrieval
`lHeaderOnly`	Logical	`.F.`	Retrieve only email headers (using TOP command)
`AllOk`	Logical	`.F.`	Set to .T. when all operations complete successfully
`bConnecting`	Block		Callback while connecting
`bConnected`	Block		Callback when connected and authenticated
`bDone`	Block		Callback when all messages have been retrieved

Methods

Method	Description
`New( cIPServer, nPort, User, Pass )`	Create a new POP3 session. nPort defaults to 110.
`GetMail()`	Connect to the server and begin the mail retrieval sequence. Messages are stored in aMsgs[].

Example: Check Inbox

#include "FiveWin.ch"

function Main()

   local oPop3, n

   oPop3 := TPop3():New( "mail.example.com", 110, ;
                         "user@example.com", "password" )

   oPop3:bConnected := { || MsgInfo( "Connected! Messages: " + ;
                                     LTrim( Str( Len( oPop3:aMsgs ) ) ) ) }

   oPop3:bDone := { ||
      MsgInfo( "Retrieved " + LTrim( Str( Len( oPop3:aMsgs ) ) ) + ;
               " messages." )
   }

   oPop3:GetMail()

   // Wait for async operation to complete
   while ! oPop3:AllOk
      SysRefresh()
   end

   // Display messages
   for n := 1 to Len( oPop3:aMsgs )
      ? "Message", n, ":", SubStr( oPop3:aMsgs[ n ], 1, 200 )
   next

return nil

Example: Retrieve Headers Only

#include "FiveWin.ch"

function Main()

   local oPop3, n

   oPop3 := TPop3():New( "mail.example.com", 110, ;
                         "user@example.com", "password" )

   // Only retrieve headers (faster, less bandwidth)
   oPop3:lHeaderOnly := .T.

   // Keep messages on the server
   oPop3:lDelMsgs := .F.

   oPop3:GetMail()

   while ! oPop3:AllOk
      SysRefresh()
   end

   // Display headers
   for n := 1 to Len( oPop3:aMsgs )
      ? "--- Message", n, "---"
      ? SubStr( oPop3:aMsgs[ n ], 1, 500 )
   next

return nil

Notes

TPop3 uses the asynchronous socket model. After calling GetMail(), the retrieval happens via the FiveWin message loop. Call SysRefresh() in a loop if using a console-style application without a window.
By default, messages are deleted from the server after retrieval (lDelMsgs := .T.). Set to .F. to leave messages on the server.
Set lHeaderOnly := .T. to retrieve only email headers using the POP3 TOP command. This is useful for quickly scanning inbox contents without downloading full messages.
Messages in aMsgs[] are stored in raw POP3 format including all headers. Parsing them for subject, from, date, etc. requires string extraction from the raw content.
Error details are logged to MailErr.log in the application directory when a POP3 error occurs.