MIME++ Frequently Asked Questions

1. The documentation refers to some member functions as advanced functions. What is an advanced function?

An advanced function is a function that is intended to be used by the library itself, and possibly by some code that extends the library. Advanced functions should not be used by user code. The obvious question then arises: Why not make them protected or private functions? There are two reasons. First, it would mean that the library author would give up some of the benefits of encapsulation -- that is, he would have to make extensive use of friend classes, which violate encapsulation. Second, it would be harder to extend the library without modifying the source code (that is, by declaring additional friend classes in order to violate the encapsulation). For more information on this approach, see Designing and Coding Reusable C++, by Carroll and Ellis.

2. Evidently, you created the HTML documentation from the .h files using some kind of tool. What tool did you use?

I used h2html. What, you never heard of it? That's probably because it's a Perl program that I wrote myself. I tried Doc++ at first, but I wanted more control over what the output format would be. h2html is not perfect, or polished. In fact, I have to do some manual fixing in most cases. But it works. Send me an email if you'd like to try it out for yourself. If enough people ask for it, I may just put it on my web page. But beware, it's truly a hack!

3. What's the best way to handle end of line characters in Windows NT?

The MIME++ library allows you to specify that CR LF will be used, however, I don't recommend this. The reason is, that C and C++ libraries all assume that newline (LF) is the sole end of line character. You can try using binary I/O all the time, and CR LF as the end of line characters, but I have a feeling that sooner or later you might run into trouble. That trouble could happen when you try to integrate with other C++ libraries that use text I/O streams.

I really recommend that you use just LF (newline). When you receive a message from the network, first convert the CR LF to LF, then work with it. Before you send a message to the network, convert the LF to CR LF. In other words, always do the conversion at the interface to the network. (One exception is that you may sometimes need to convert text to its canonical form, which has CR LF. You would do this before base64 encoding, for example.)

You can use the utility functions DwToLfEol() and DwToCRLfEol() to do the conversions.

4. I am writing a multithreaded application? What do I need to know about using MIME++?

As of version 1.3, MIME++ should be thread safe on Windows, Linux 2.0 (glibc 2), Solaris, AIX 4.3, Compaq TruUnix64 4.0, and HP/UX 11.0, and possibly other platforms. It uses Posix threads on Unix-like platforms for mutexes.

The following are some things you should be aware of when using MIME++ in a multithreaded application.

• First and foremost, understand how to do multithreaded programming on your development platform. Many development systems offer different versions of the C library for single threaded and multi-threaded applications. On Windows, be sure to use _beginthreadex() to start a thread, or use CWinThread in MFC. On most Unix systems, you must define the _REENTRANT macro, although this is usually defined by a compiler command line switch. These are just some of the things to be concerned with.
• There is a macro, DW_MULTITHREADED, in config.h that must be defined before you build the thread-safe library.
• If you need to share instances of MIME++ classes between two or more threads, then you must ensure that access to these objects is serialized (for example, protected by a CRITICAL_SECTION on Windows, or by a mutex on Unix). MIME++ does not provide any protection, such as the protection Java provides with synchronized methods.
• MIME++ doesn't use any non-thread-safe C library function calls, if at all possible. The one problem function call is gethostbyname(). Some platforms offer thread-safe versions of this function. Others, notably Linux (glibc) and Solaris offer versions of gethostbyname_r(). If you want to be certain that this function is handled correctly, then check the documentation of your C library and the implementation in system.cpp. If you are programming on Windows, Linux 2.0 (glibc), Solaris 7, AIX 4.3, Tru64 Unix 4.0, or HP-UX 11.0, then you should be fine.

5. Is there a way to tell if a DwMessageComponent object is parsed?

Currently, there is no way, and I am not sure of the need to add an IsParsed() member function. The reason is because the Parse() function is supposed to be part of a two-phase constructor. In other words, you should almost always call the Parse() member function immediately after the constructor. (The copy constructor would be an exception to this rule, since the copy constructor performs a deep copy.) This brings up another question: Why a two-phase constructor? The answer is, that this is an elegant way to deal with the fact the you cannot call a virtual function from a constructor (and get the behavior you want from a virtual function). Parse() is a virtual function, so it can't be called from the constructor.

6. What does a valid email address look like?

I'll answer that question in a minute. But first, let's make sure you understand that many of the headers that take an email address -- the "To" header, for example -- actually take a list of addresses, separated by commas. That's why the function DwHeaders::To() returns a reference to a DwAddressList.

An address, according to the official standard RFC 822, can be either a mailbox or a group. A group contains a group name and a list of addresses. Since groups are not commonly used, I'll just mention that it is supported by the DwGroup class and refer you to the RFC. If you are curious, here is an example of a "To" header field that contains a group:

To: mimepp-users: Santa Clause <santa@santa.np>,
  Winnie the Pooh <winstonp@disney.com>,
  <beehoven@bonn.de>;

A mailbox usually has one of these forms:

(1) jspratt@xyz.org
(2) jspratt@xyz.org (Jack A. Spratt)
(3) <jspratt@xyz.org>
(4) Jack Spratt <jspratt@xyz.org>
(5) "Jack A. Spratt" <jspratt@xyz.org>
(6) "Spratt, Jack" <jspratt@xyz.org>

The (1) form is the simplest of all. (2) is popular in news messages (see RFC-1036, which describes the format of USENET message). The parentheses set off a comment, which in this case is the full name of the individual. (3) is a minimal form, similar to (1), except for the angle brackets. Angle brackets are optional if a full name is not given. (4) and (5) are probably the most common forms. In both cases, the angle brackets are required to set apart the actual "address" from the full name. (5) without the quotation marks would be invalid because of the period, which is one of the special characters. The quotation marks are even more important in the form (6), because a comma is used to delimit mailboxes in a list of mailboxes. Because the special characters have to be quoted, many implementations, such as MIME++, always use quotes to set off the full name. One common error is to use single quotes for the full name.

If you create a list of mailboxes, such as in the "To" headers, you delimit them using a comma, like this:

To: "Jack Spratt" <jspratt@xyz.org>, "Ms. Muffet" <muffet@abc.edu>,
  "Humpty Dumpty" <hdumpty@abc.edu>

7. I want to get a commercial license. What does it cost?

Commercial licenses are negotiated on an individual basis. Please contact Charlotte Sauder <cbsauder@hunnysoft.com> for more information.

8. I think I found a bug. What should I do?

Send me an email to tell me about it. My email is Doug Sauder <dwsauder@hunnysoft.com>.