Sending MIME Messages | Observing the User Experience: A Practitioners Guide to User Research

CSMTPConnection provides a number of different methods for sending messages. Each method varies in the level of control you have over the message being sent.

The following method is the simplest way to send an e-mail message. The parameters of this method correspond to familiar e-mail message properties; none of these parameters can be NULL . You can specify multiple recipients in lpszRecipients using a string delimited by a comma, semicolon, or space. If you need to set your own delimiter characters , then you should override the method AtlSmtpIsRecipientDelimiter in atlsmptutil.h that determines the valid delimiter characters.

 inline BOOL SendSimple(LPCTSTR lpszRecipients,                                           LPCTSTR lpszSender,                                           LPCTSTR lpszSubject,                                           LPCTSTR lpszBody,                                           int  nTextLen = -1) throw()

The following method allows you to use a CMimeMessage object to represent the message you want to send. You can optionally override the recipients and sender specified in that object with the lpszRecipients and lpszSender parameters, respectively. The CMimeMessage class provides you with a convenient way of working with MIME messages. The next section of this chapter covers CMimeMessage , so we don t look at this class in depth right now.

 inline BOOL SendMessage(CMimeMessage& msg,                                                LPCTSTR  lpszRecipients = NULL,                                                LPCTSTR  lpszSender = NULL) throw()

The following method gives you the most control over how you send messages with CSMTPConnection . None of the string parameters can be NULL . lpszRawData is expected to contain all of the text of your message. The format of this text must conform to RFC 822 (http://www.rfc.net/rfc822.html). You should use this method if you want to specify exactly what your message will look like as it s transferred over the network.

 inline BOOL SendRaw(LPCTSTR lpszRawData,                                       DWORD   dwLen,                                       LPCTSTR lpszRecipients,                                       LPCTSTR lpszSender) throw()

Now that you have an understanding of how to send messages using CSMTPConnection , you ll take a closer look at how you can build more sophisticated messages using the CMimeMessage class.

CMimeMessage

CMimeMessage gives you access to the various parts of a MIME message. You can use this class to construct a MIME message with multiple attachments and text segments. Let s begin by looking at how to construct instances of this class.

Constructing MIME Messages

The CMimeMessage constructor allows you to optionally specify an object that implements the IMultiLanguage interface:

 CMimeMessage(IMultiLanguage *pMultiLanguage = NULL) throw()

IMultiLanguage is part of the MLang services. As mentioned earlier, MLang is an API that makes writing internationalized Internet applications easier. Because of the nature of MLang, creating objects that implement IMultiLanguage can be computationally expensive. You can use CoCreateInstance to create an instance of IMultiLanguage and reuse it across multiple CMimeMessage objects.

By using MLang, CMimeMessage allows you to easily add text from various character sets to your MIME message. This is one major advantage of using a MIME message over sending regular ANSI text.

The following method allows you to create a copy of a CMimeMessage instance. A new instance of CMimeMessage is created and populated from the current instance. Because a memory allocation is required, there s a possibility of an exception being thrown from this method. You ll notice this pattern in ATL Server in general; all methods that require memory allocation will be marked as being ones that could throw exceptions.

 virtual ATL_NOINLINE CMimeBodyPart* Copy() throw( ... )

The following method lets you easily specify a display name for your message. A display name isn t required.

 inline BOOL SetDisplayName(LPCTSTR szDisplayName) throw()

Once you ve constructed an instance of CMimeMessage , you have many options available for sending text and adding attachments. We describe these methods later in the chapter.

Addressing Your Messages

CMimeMessage derives from the CMimeHeader base class. This base class implements methods to construct the elements of a MIME message as defined in RFC 822 (http://www.rfc.net/rfc822.html). You can use this base class if you want to create your own MIME message classes. CMimeMessage inherits and exposes the following methods. Most of these methods relate to familiar elements of e-mail messages, so we don t spend too much time explaining them.

 inline BOOL SetPriority(ATL_MIME_PRIORITY nPriority) throw()  inline ATL_MIME_PRIORITY GetPriority() throw()

These methods set and get the priority of your message. The priority levels are as follows :

ATL_MIME_HIGH_PRIORITY
ATL_MIME_NORMAL_PRIORITY
ATL_MIME_LOW_PRIORITY
ATL_MIME_PRIORITY_ERROR

The value chosen sets the X-Priority header in your MIME message.

The following methods set and get the friendly sender name of your message. The friendly names are not required, but they are used by most e-mail clients .

 inline BOOL SetSenderName(LPCTSTR szName, UINT uiCodePage = 0) throw()  inline LPCSTR GetSenderName() throw()

The following method appends a user -defined header to your message. You should use the X- prefix convention in your header. Like other MIME headers, the user-defined header that you specify must not contain any line break (CR/LF) characters. You also have the option of specifying any code page that your system supports.

 inline BOOL AppendUserDefinedHeader(LPCTSTR szHeaderName, LPCTSTR szHeader,                                                        UINT uiCodePage = 0) throw()

The following methods allow you to work with the direct recipients of your message. GetRecipients returns a comma-delimited list of recipients.

 inline BOOL AddRecipient(LPCTSTR szAddress,                                            LPCTSTR szName = NULL,                                            UINT uiCodePage = 0) throw()  inline LPCSTR GetRecipients() throw()  inline BOOL   ClearRecipients() throw()

The following methods allow you to work with the Cc recipients of your message. GetCc returns a comma-delimited list of recipients.

 inline BOOL AddCc(LPCTSTR szAddress, LPCTSTR szName = NULL, UINT  inline LPCSTR GetCc() throw()  inline BOOL ClearCc() throw()

The following methods allow you to work with the Bcc recipients of your message. GetBcc returns a comma-delimited list of recipients.

 inline BOOL AddBcc(LPCTSTR szAddress) throw()  inline LPCSTR GetBcc() throw()  inline BOOL ClearBcc() throw()

These methods allow you to work with required recipients of your message:

 inline DWORD GetRequiredRecipientsStringLength() throw()  ATL_NOINLINE BOOL GetRecipientsString(LPSTR szRecip, LPDWORD pdwLen) throw()

These methods allow you to work with the sender of your message:

 inline LPCSTR GetSender() throw()  inline BOOL SetSender(LPCTSTR szSender) throw()

These methods allow you to work with the subject of your message:

 inline BOOL SetSubject(LPCTSTR szSubject, UINT uiCodePage = 0) throw()  inline LPCSTR GetSubject() throw()

Sending Text

The AddText method adds a text segment to your MIME message and optionally specifies a code page for that text. The text specified by szText can t be NULL . You can specify any code page in uiCodePage that your system supports. By default, you use the default ANSI code page on your system, which ATL Server determines by calling the GetACP() Win32 API function.

 inline BOOL AddText(LPCTSTR szText,                      int     nTextLen   = -1,                      int     nPos       = 1,                      UINT    uiCodePage = 0) throw()

Besides sending text, MIME allows you to add attachments to your message, which we cover in the following section. This ability gives you many more options for sending information back to your user.

Adding Attachments

The following method allows you to add different types of attachments to your MIME message:

 inline BOOL AttachFile(LPCTSTR szFileName,                                      LPCTSTR szDisplayName   = NULL,                                      LPCTSTR szContentType   = NULL,                                      Int  nEncodingScheme = ATLSMTP_BASE64_ENCODE,                                      UINT  uiCodepage = 0)

AttachFile allows you to specify a file to attach to your MIME message. You can optionally specify a display name, content type, encoding scheme, and code page.

szDisplayName specifies the display name that is used by e-mail clients such as Outlook to display information about a given attachment. If no display name is specified, you ll use the name rawdata as a default.

szContentType describes the content of the attachment. If one isn t specified, try to determine the content type by looking up the file extension under the HKEY_CLASSES_ROOT registry key and reading its content type value. If the extension isn t registered or there isn t a content type value, default the content type to application/octet-stream .

nEncodingScheme specifies how the file will be encoded. You can specify one of the following:

ATLSMTP_BASE64_ENCODE : Encodes using base64, as described in RFC 2045 (http://www.ietf.org/rfc/rfc2045.txt)
ATLSMTP_UUENCODE : Encodes using the scheme specified in the POSIX P1003.2b/D11 specification
ATLSMTP_QP_ENCODE : Encodes using the Q encoding scheme specified in RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)

All of these encoding schemes, as well as other schemes, are implemented in functions defined in atlenc.h and can be used independently anywhere in your application.

Listing 24-2 is a very simple example showing how you can use Base64Encode to encode a piece of data. If the encoding was successful, the resulting encoded data is output to the console.

Listing 24.2: Using Base64Encode to Encode a Piece of Data

 #include <atlenc.h>  int _tmain()  {      char *data   = _T( "Hello World!" );      int   dataLen = strlen( data );      //      // First determine how much memory to allocate to      // hold the encoded data.      //      int encodedDataLen  = Base64EncodeGetRequiredLength( dataLen );      char* encodedData = new char[ encodedDataLen + 1 ];      if( TRUE == Base64Encode( ( const BYTE*)data,                                dataLen,                                encodedData,                                &encodedDataLen ) )      {          encodedData[ encodedDataLen ] = 0;          printf( "Successfully encoded!\n%s", encodedData );      }      else      {          printf( "Error encoding!" );      }      return 0;  }

The following method allows you to attach one CMimeMessage to another. A copy of pMsg is made and attached so that the caller remains responsible for the memory management of pMsg . A minor bug in this method is that it should be declared as throw() rather than throw( ... ) . In other words, the declaration of this method says that it might throw an exception, when in fact it never will.

 inline BOOL AttachMessage(CMimeMessage* pMsg) throw( ... )

As with CSMTPConnection , CMimeMessage gives you a way of sending a raw attachment, as shown in the following code snippet. This gives you complete control of how you obtain the data that s to be attached. A great use of this method is to read the contents of a file that you ll attach to all messages that your application sends at start-up. This saves the overhead of reading the file each time you want to attach it (you can just use a memory buffer or something else more efficient than a file).

 inline BOOL AttachRaw(void*   pRawData,                        DWORD   dwDataLength,                        int     nEncodingScheme = ATLSMTP_BASE64_ENCODE,                        BOOL    bCopyData = TRUE,                        LPCTSTR szDisplayName = NULL,                        LPCTSTR szContentType = _T("application/octet-stream"),                        UINT    uiCodepage = 0)

Now that you ve had a chance to look at the classes that make up ATL Server s support for sending SMTP messages, you ll take a look at a complete example. In the next section, you ll learn how you can extend ATL Server s SMTP functionality to send HTML messages instead of regular text.