xHarbour Reference Documentation > Class Reference (textmode)

TIpClientPop()

Creates a new TIpClientPop object.

Syntax

TIpClientPop():new( <cUrl>, [<lTrace>] ) --> oTIpClientPop

Arguments

<cUrl>

This is a character string holding the URL of the mail server to retrieve eMails from. It must be coded in this form:

   pop3://<mailAccount>:<password>@<mail.server.com>

Alternatively, a TUrl() object can be passed that is initialized with the mail server URL.

<lTrace>

This parameter defaults to .F. (false). When .T. (true) is passed, the communication with a mail server is logged into the file Pop3<nn>.log, where <nn> is the number of the log file storing information of the internet communictaion with this object.

Return

The function returns a new TIpClientPop object and method :new() initializes the object.

Description

Objects of the TIpClientPop() class inherit from the generic internet client class TIpClient(). TIpClientPop objects are used to communicate with a POP3 mail server. They use the Post Office Protocol (POP) for downloading, or reading, eMails. The address of the mail server must be provided with a URL string with method :new(). The URL is maintained by a TUrl() object, which is stored in the :oUrl instance variable.

The internet connection to the mail server must be established with the :open() method, after which a list of pending eMails can be queried from the mail server with the :list() method.

Individual eMails can then be retrieved with :retrieve(). This method returns the entire contents of a single eMail as a character string which can be decoded using a TIpMail() object and its :fromString() method.

Once an eMail is retrieved and stored locally, it can be deleted from the mail server using the :delete() method. If a mail is retrieved but not deleted, it remains on the mail server and can be retrieved again.

When all eMails are read, the internet connection must be closed with the :close() method.

Instance variables

:nConnTimeout

Numeric timeout value in milliseconds.

:nDefaultPort

Numeric port number.

Methods

:delete( <nMail> ) --> lSuccess

Deletes an eMail on the mail server.

:list() --> cMailIDs

Lists eMails pending on the mail server.

:noOp() --> lSuccess

Can be called repeatedly to keep-alive the connection.

:retrieve( <nMail>, [<nBytes>] ) --> cMail

Retrieves an eMail from the mail server

:stat() --> cStatusMsg

Retrieves a status message from the mail server.

:top( <nMail> ) --> cMailHeaders

Retrieves the headers of an eMail (no body).

:uidl( <nMail> ) --> cMailID

Returns unique ID of an eMail.

Info

See also:	TIpClient(), TIpMail(), TUrl()
Category:	Internet functions , Object functions , xHarbour extensions
Source:	tip\popcln.prg
LIB:	lib\xhb.lib
DLL:	dll\xhb.dll

Example

// The example outlines the steps required for retrieving all
// eMails from a POP mail server and how to decompose
// incoming mail messages.

   PROCEDURE Main
      LOCAL oPop, oPart, aParts, oTIpMail, aEmails, i

      oPop := TIpClientPop():new( "pop://mailaccount:password@pop.server.com" )

      IF .NOT. oPop:open()
         ? "Connection error:", oPop:lastErrorMessage()
         QUIT
      ELSE
         aEMails := oPop:retrieveAll()
         oPop:close()
      ENDIF

      FOR i:=1 TO Len( aEMails )
         oTIpMail := aEmails[i]
         ? oTIpMail:getFieldPart( "From" )
         ? oTIpMail:getFieldPart( "Subject" )

         IF oTIpMail:isMultiPart()
            // Retrieve all parts of a multipart message
            aParts := oTIpMail:getMultiParts()

            FOR EACH oPart IN aParts
               IF .NOT. Empty( oPart:getFileName() )
                  // This is a file attachment. Store it in the TMP folder.
                  IF oPart:detachFile( "C:\tmp\" )
                     ? "File written: C:\tmp\" + oPart:getFileName()
                  ENDIF
               ELSE
                  ? oPart:getBody()
               ENDIF
            NEXT
         ELSE
            // simple mail message
            ? oTIpMail:getBody()
         ENDIF
      NEXT

   RETURN