xHarbour Reference Documentation > Class Reference (textmode)

TIpMail()

Creates a new TIpMail object.

Syntax

TIpMail():new( [<cMailBody>], [<cEncode>] ) --> oTIpMail

Arguments

<cMailBody>

This is an optional character string holding the mail body of an eMail. The mail body is the text transmitted with the eMail.

<cEncode>

This is an optional character string holding the name of the encoding method to use for the body of the eMail. The following encoding methods are supported:

Encoding methods for eMail bodies

Name	Description
as-is *)	Not encoded (unchanged)
base64	Base64 encoded
quoted-printable	Encoded as quoted printable.
url	Url encoded
urlencoded	Url encoded
7bit	7bit encoded
8bit	8bit encoded
*)default

Return

Function TIpMail() returns a new TIpMail object and method :new() initializes the object.

Description

Objects of class TIpMail are used to manage a complete eMail. The minimum data an eMail must contain are the sender address (From), the recipient address (To), a subject line (Subject) and the text of the eMail (Body). These data can be assigned to a TIpMail object with its :setBody() and :setHeader() methods.

Note:  methods of the TIptMail class are divided into "High level" and "Low level" methods. "High level" methods are designed to compose an email easily, while "Low level" methods manipulate individual entries of an eMail header. You should be familiar with eMail headers when using "Low level" methods.

Instance variables

:hHeaders

Hash holding the mail header entries.

High level methods

:attachFile( <cFileName> ) --> lSuccess

Attaches a file to an eMail.

:detachFile( [<cPath>] ) --> lSuccess

Stores an attached a file to disk.

:getBody() --> cEmailBody

Returns the mail body.

:getFileName() --> cFileName

Retrieves the name of an attached file.

:getMultiParts() --> aParts

Retrieves all parts of a multipart mail message.

:isMultipart() --> lIsMultiPartMail

Determines if an eMail is a miltipart mail message.

:setBody( <cMailBody> ) --> lSuccess

Assigns the contents of the mail body

:setHeader( ... ) --> lSuccess

Low level methods

:attach( <oTIpMail> ) --> lSuccess

Composes a multipart mail message.

:countAttachments() --> nCount

Returns the number of parts in a multipart mail message.

:fromString( <cEMail> ) --> lSuccess

Decomposes a downloaded mail message.

:getAttachment() --> oTIpMail

Returns the current part of a multipart mail message.

:getCharEncoding() --> cEncoding

Returns character encoding information.

:getContentType() --> cContentType

Returns the content type of a mail message.

:getFieldOption( <cField>, <cOption> ) --> cValue

Returns an optional value of a mail header field.

:getFieldPart( <cField> ) --> cValue

Returns the value of a mail header field.

:nextAttachment() --> oTIpMail

Returns the next part of a multipart mail message.

:resetAttachment() --> NIL

Resets the internal part counter to 1.

:setFieldOption( <cField>, <cOption>, <cValue> ) --> lSuccess

Assigns an optional value to a mail header field.

:setFieldPart( <cField>, <cValue> ) --> lSuccess

Assigns a value to a mail header field.

:toString() --> cEmail

Collects all information of a mail message in a character string.

Info

See also:	TIpClientPop(), TIpClientSmtp(), TUrl()
Category:	Internet functions , Object functions , xHarbour extensions
Source:	tip\mail.prg
LIB:	lib\xhb.lib
DLL:	dll\xhb.dll

Examples

Incoming eMails

// 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

Outgoing eMails

// The example outlines the steps required for composing an eMail
// and sending it to an SMTP mail server.

   PROCEDURE Main
      LOCAL oSmtp, oEMail
      LOCAL cSmtpUrl
      LOCAL cSubject, cFrom, cTo, cBody, cFile

      // preparing data for eMail
      cSmtpUrl := "smtp://mailaccount:password@smtp.server.com"
      cSubject := "Testing eMail"
      cFrom    := "MyName@Mail.server.com"
      cTo      := "YourName@another.server.com"
      cFile    := "File_Attachment.zip"
      cBody    := "This is a test mail sent at: " + DtoC(Date()) + " " + Time()

      // preparing eMail object
      oEMail   := TIpMail():new()
      oEMail:setHeader( cSubject, cFrom, cTo )
      oEMail:setBody( cBody )
      oEMail:attachFile( cFile )

      // preparing SMTP object
      oSmtp := TIpClientSmtp():new( cSmtpUrl )

      // sending data via internet connection
      IF oSmtp:open()
         oSmtp:sendMail( oEMail )
         oSmtp:close()
         ? "Mail sent"
      ELSE
         ? "Error:", oSmtp:lastErrorMessage()
      ENDIF
   RETURN