8-Bit MIME in C++

This blog post discusses the C++ pitfalls present when handling 8bit MIME files. Suppose you have a .eml file containing this MIME:

MIME-Version: 1.0
Subject: Test
Content-Type: text/plain; charset=UTF-8
To: support@chilkatsoft.com
Content-Transfer-Encoding: 8bit
From: admin@chilkatsoft.com
Date: Sun, 16 Mar 2008 01:28:21 +0100
	
Guten Tag,
	
äß

(It is assumed for this discussion that the .eml file was properly saved using the utf-8 character encoding.)

How do you load this text into a CkString object?

    CkString mimeText;
    bool success = mimeText.loadFile("8bit_utf8.eml","utf-8");

The CkString::loadFile method must be told the character encoding it is expecting. This allows it to correctly interpret the bytes as the correct characters. How do you know the character encoding without first reading the MIME header? It’s not possible and this is a problem. The CkString class is not a MIME parser, and it does not have the intelligence to auto-sense the charset. However, the CkMime class provides a LoadMimeFile method that is capable of doing it. Internally, CkMime is loading the .eml as bytes with no attempt to interpret according to any character encoding. It parses the header, and if an 8bit encoding w/ charset specified is found, it knows how to interpret the remainder of the MIME. (If 8bit characters are used within the header itself, the CkMime class is smart enough to first examine the Content-Type header before parsing the remainder of the header fields. )

With CkMime, we can do this without worrying about 8bit MIME or charsets:

    CkMime mimeObj;
    bool success = mimeObj.LoadMimeFile("8bit_utf8.eml");

The same can be said for the CkEmail object:

    CkEmail emailObj;
    bool success = emailObj.LoadEml("8bit_utf8.eml");

OK, let’s say you want access to the MIME string directly in C++. (IMPORTANT) Remember, a "const char *" is a pointer to a null-terminated multi-byte string. It is up to your application to know the charset of the bytes pointed to by "const char *". My habit is to always give these variables names that include the charset as a constant reminder about the character encoding. For example:

    CkString mimeText;
    bool success = mimeText.loadFile("8bit_utf8.eml","utf-8");
	
    // Both are null-terminated strings.  One contains ANSI, the other utf-8.
    const char *ansiMimeStr = mimeText.getAnsi();
    const char *utf8MimeStr = mimeText.getUtf8();
	
    CkMime mimeObj;
    success = mimeObj.LoadMimeFile("8bit_utf8.eml");
	
    // The "Utf8" property determine whether "const char *" arguments and
    // return values are ANSI or utf-8.  
	
    mimeObj.put_Utf8(false);	// Return ANSI
    const char *ansiMimeStr2 = mimeObj.getMime();
	
    mimeObj.put_Utf8(true);	// Return utf-8
    const char *utf8MimeStr2 = mimeObj.getMime();

The CkMailMan::SendMime method provides a way to send an email specifying the exact MIME source of the email to be sent. The email addresses passed to the SMTP server via the FROM and "RCPT TO" commands (as part of the SMTP protocol) are provided in the fromAddr and recipients arguments of the SendMime method. If your application calls SendMime, and the MIME uses an 8bit encoding, then you must pass a "const char *" pointing to MIME text encoded using that same character encoding. In this case, our email uses 8bit utf-8. This is how one would call SendMime:

    CkMailMan mailman;
    const char *from = "admin@chilkatsoft.com";
    const char *recipients = "support@chilkatsoft.com, matt@chilkatsoft.com";
	
    // The MIME specifies 8bit utf-8 in the header, therefore you must pass
    // a utf-8 encoded string.  Furthermore, you must tell the mailman that
    // the string arguments are utf-8:
    mailman.put_Utf8(true);
    success = mailman.SendMime(from,recipients,utf8MimeStr);