Xbase++ - Class MIMEMessage()

Class function of the MIMEMessage class

MIMEContent()

Instances of the MIMEMessage class encapsulate the complexities of the Multipurpose Internet Mail Extensions, a specification for formatting non-ASCII messages so that they can be sent over the Internet. MIMEMessage objects are used to retrieve e-mail messages in conjunction with a POP3Client() object, or to send e-mails with a SMTPClient() object. This means that MIMEMessage objects are of no use on their own, but help a programmer to create and/or examine MIME e-mail messages in a comfortable way.

A MIMEMessage object takes care of all elements of an e-mail, that is, sender, recipients, headers, content and file attachments. Therefore, a MIMEMessage object plays a central role for sending/receiving e-mails with Xbase++ applications.

The MIMEMessage class does not feature specific interfaces for accessing every header field which may be used in an e-mail message. However, the methods :getHeader() and :addHeader() provide a generalized way for reading and writing arbitrary header values, and can be used in cases where no specific interface exists.

The following code snippet illustrates accessing the recipient of a message, the recipient of a carbon copy ("Cc"), and the recipient of a blind copy ("Bcc") of the same message:

oMimeMessage := MimeMessage():new() 

oMimeMessage:addRecipient( MailAddress():new( "user1@mail.com" ) ) 
oMimeMessage:addHeader( "Cc", "user2@mail.com" ) 
oMimeMessage:addHeader( "Bcc", "user3@mail.com" ) 

? oMimeMessage:getHeader( "To" ) 
? oMimeMessage:getHeader( "Cc" ) 
? oMimeMessage:getHeader( "Bcc" )

The maintenance of different (mime) parts of an e-mail is the task of the subclass MIMEContent().

The class MailAddress() is used for stting the recipient with the method :addRecipient() and for determining the sender with the method :getFrom().

Creates an instance of the MIMEMessage class.

Creates an instance of the MIMEMessage class from a string.

Methods in this group are mainly used to examine the contents of an e-mail that is retrieved via oPOP3Client:getMessage(). This method returns a MIMEMessage object containing the different parts of an e-mail.

Retrieves the contents of all header fields.

Extracts the contents.

Retrieves the content transfer encoding.

Retrieves the content type.

Retrieves the creation date.

Retrieves the "From:" header.

Retrieves the contents of a header field.

Retrieves the "Subject:" line.

Methods in this group are usually called when an e-mail message is assembled in an Xbase++ application. The mail is then sent to a mail server via a SMTPClient object and its :send() method.

Adds a header field.

Adds a "To:" header.

Attaches a file.

Deletes a header field.

Deletes a recipient.

Sets the contents of all header fields.

Defines the content transfer encoding.

Defines the content type.

Configures the sending of Delivery Service Notification e-mails

Defines the "From:" header.

Assigns the text body.

Defines the "Subject:" header.

Using a MIMEMessage object for sending an e-mail

// The example demonstrates how to assemble an e-mail 
// and send it via an SMTPCLient object to the recipient 

#include "asinet.ch" 

#define CRLF  Chr(13)+Chr(10) 

// 
// Usage: <cEmailAdr>   Email address for both, the sender and recepient 
//        <cMailServer> Your mailserver ( "example.domain.de" ) 
//        <cUsername>   In case your mailserver requires authentification 
//                      the username can be passed 
//        <cPasswor>    Password for authentification 
// 
PROCEDURE main( cEmailAdr, cMailServer, cUsername, cPassword ) 
   LOCAL oSmtp, oMail, oSender, cText, oRecipient 

   // This will be the message text 
   cText      := "Happy Birthday to Jane" + CRLF + CRLF 
   cText      += "Cheers" + CRLF 
   cText      += "  John" + CRLF 

   // create the MIMEMessage, the sender and the 
   // recipient object 
   oMail      := MIMEMessage():new() 
   oSender    := MailAddress():new( cEmailAdr ) 
   oRecipient := MailAddress():new( cEmailAdr ) 

   // 
   // Assemble the e-mail 
   // 
   // Set contact information 
   oMail:setFrom     ( oSender     ) 
   oMail:addRecipient( oRecipient  ) 
   oMail:addHeader   ( "Reply-To", cEmailAdr ) 

   // Set message contents 
   oMail:setSubject  ( "Greetings" ) 
   oMail:setMessage  ( cText       ) 

   // 
   // Connect to smtp server and send the mail 
   // 
   oSmtp := SMTPClient():new( cMailServer ) 
   IF oSmtp:connect( cUsername, cPassword ) 

      oSmtp:send( oMail ) 
      oSmtp:disconnect() 
      ? "Message sent" 
   ELSE 
      ? "Unable to connect to mail server" 
   ENDIF 

RETURN

Using a MIMEMessage object for sending an html e-mail

// The example demonstrates how to generate an e-mail from an html page. 
// Hereby the MimeMessage object is created by using class methods 
// from its baseclass MimeContent. Additionally a bitmap is added 
// to the mail as related content. 

#include "asinet.ch" 

// 
// This sample demonstrates the creation of an html mail. 
// 
// Usage: <cEmailAdr>   Email address for both, the sender and recepient 
//        <cMailServer> Your mailserver ( "example.domain.de" ) 
//        <cUsername>   In case your mailserver requires authentification 
//                      the username can be passed 
//        <cPasswor>    Password for authentification 
// 
PROCEDURE main( cEmailAdr, cMailServer, cUsername, cPassword ) 
    LOCAL oMe, oMail, oServer, oBitmapCont 
    LOCAL cID 

    // 
    // For connecting to related content we need the same string 
    // in the html content as link and as header info in the 
    // related content 
    // 
    cID := MimeContent():new():uniqueString 

    // 
    // Parameter checking 
    // 
    IF PCount() < 2 
       ? "Usage:" 
       ? AppName(), "cEmailAdr cMailServer [cUsername] [cPassword]" 
       WAIT 
       QUIT 
    ENDIF 

    // 
    // One MAILAddress object for sender and recepient 
    // 
    oMe := MAILAddress():new( cEmailAdr ) 

    // 
    // Prepare MIMEMessage object. 
    // 
    // Create the MIMEMessage object QuotedPrintable encoded. 
    // EncodeQuotedPrintable is a class method of MIMEContent. 
    // The background image will be connected to the html page 
    // by parameter cID 
    // 
    oMail := MIMEMessage():encodeQuotedPrintable( getHtml(cEmailAdr, cID), ; 
                                                  "text/html" ) 

    oMail:setFrom( oMe ) 
    oMail:addRecipient( oMe ) 
    oMail:setSubject( "Asinet Html mail docu sample" ) 

    // Create the MIMEContent object containing the bitmap 
    oBitmapCont := getBitmapCont() 

    // 
    // Attach the Content that contains the bitmap 
    // Note that the same ID is required as in the html string. 
    // (see function getBitmapCont() below) 
    // 
    IF ! Empty( oBitmapCont ) 
       oMail:attachRelated( oBitmapCont, cID ) 
    ENDIF 

    // 
    // Create SMTPClient. Then connect to Server and send message. 
    // 
    oServer := SMTPClient():new( cMailServer ) 
    IF ! oServer:connect( cUsername, cPassword ) 
       ? "Unable to connect to mail server" 
       WAIT 
       QUIT 
    ENDIF 

    oServer:send( oMail ) 
    oServer:disconnect() 

    ? "Message sent!" 
    ? "Check account", cEmailAdr, "for new mail" 
    wait 

RETURN 

// 
// Helper method for creating a MimeContent object 
// from a bitmap 
// 
FUNCTION getBitmapCont() 
   LOCAL cXppResource, oContent, nPos 

   // 
   // Extract bitmap resource path from environment 
   // variable 
   // 
   cXppResource := Lower( GetEnv( "XppResource" ) ) 
   IF 0 == ( nPos := At( "resource", cXppResource ) ) 
      ? "XppResource Environment variable not set:" 
      ? "  Background image can not be loaded" 
      RETURN NIL 
   ENDIF 
   // len( "resource" ) + 1 == 7 
   cXppResource := SubStr( cXppResource, 1, nPos + 7 ) 
   cXppResource += "\bitmap\keybd1.bmp" 

   // 
   // Create content from file 
   // 
   oContent := MimeContent():createFromFile( cXppResource ) 

RETURN oContent 

// 
// Helper for returning a Html page 
// 
FUNCTION getHtml( cMail, cID ) 
   LOCAL cStr := "" 
   cStr += '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">' 
   // 
   // Here we use a link to the embedded picture 
   // 
   cStr += '<html>' 
   cStr += '  <head></head>' 
   cStr += '  <body background="cid:' + cID + '"' 
   cStr += '    <h1>' 
   cStr += '       Hallo from <br>'+cMail+'!' 
   cStr += '    <h1>' 
   cStr += '  </body>' 
   cStr += '</html>' 
RETURN cStr

Using a MIMEMessage object for retrieving an e-mail

// The example outlines the steps required for retrieving 
// an e-mail and examining its contents. The first mail 
// stored in a mailbox is retrieved, header fields are displayed 
// and file attachments are written to local files. 

#include "asinet.ch" 

PROCEDURE Main() 
   LOCAL nHandle, i, cText, aContent 
   LOCAL oPop3, oMail, oSender, oContent 

   LOCAL cFile     := NIL 
   LOCAL cServer   := "mail" 
   LOCAL cUserName := "JohnDoe" 
   LOCAL cPassword := "Lancelot" 

   oPop3 := POP3Client():new( cServer  , NIL      , ; 
                              cUserName, cPassWord  ) 

   IF .NOT. oPOP3:connect() 
      ? "Unable to establish connection to:", cServer 
      WAIT 
      QUIT 
   ENDIF 

   // receive the first message from the Pop server and 
   // extract the sender and an array with all MIMEContent 
   // objects 
   oMail    := oPOP3:getMessage(1) 
   oSender  := oMail:getFrom() 
   aContent := oMail:getContent() 

   ? "   From:", oSender:getString() 
   ? "Subject:", oMail:getSubject() 

   FOR i:=1 TO Len( aContent ) 
      oContent := aContent[i] 

      IF oContent:isMultiPart() 
         ? "Multi-part contents must be extracted recursively" 
         LOOP 
      ENDIF 

      cText := oContent:getMessage() 

      DO CASE 
      CASE "text/" $ Lower( oContent:getContentType() ) 

         // This is printable content 
         ? "Content:", cText 

      CASE .NOT. Empty( cFile := oContent:getFileName() ) 

         // This is a file attachment 
         nHandle := FCreate( cFile ) 
         FWrite( nHandle, cText, Len( cText ) ) 
         FClose( nHandle ) 
         ? "Attachment written to:", cFile 

      ENDCASE 
   NEXT 

   // Remove the first message from the Pop server 
   oPop3:deleteMessage(1) 
   oPop3:disconnect() 

   WAIT 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class MIMEMessage() Professional