Class MIMEMessage() Professional
Class function of the MIMEMessage class
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().
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.
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.
// 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
// 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
// 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.