diff options
Diffstat (limited to 'mimelib/Tutorial')
| -rw-r--r-- | mimelib/Tutorial | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/mimelib/Tutorial b/mimelib/Tutorial new file mode 100644 index 000000000..358fab7e5 --- /dev/null +++ b/mimelib/Tutorial @@ -0,0 +1,437 @@ + + + T U T O R I A L F O R M I M E + + + +1. Introduction + +Welcome to MIME++, a C++ class library for creating, parsing, and modifying +messages in MIME format. MIME++ has been designed specifically with the +following objectives in mind: + + * Create classes that directly correspond to the elements described in + RFC-822, RFC-2045, and other MIME-related documents. + + * Create a library that is easy to use. + + * Create a library that is extensible. + +MIME++ classes directly model the elements of the BNF grammar specified in +RFC-822, RFC-2045, and RFC-2046. For this reason, I recommend that you +understand these RFCs and keep a copy of them handy as you learn MIME++. +If you know C++ well, and if you are familiar with the RFCs, you should find +MIME++ easy to learn and use. If you are new to C++ and object-oriented +programming, you will find in MIME++ some very good object-oriented +techinques, and hopefully you will learn a lot. + +Before looking at the MIME++ classes, it is important to understand how +MIME++ represents a message. There are two representations of a message. +The first is a string representation, in which a message is considered +simply a sequence of characters. The second is a 'broken-down' -- that is, +parsed -- representation, in which the message is represented as a tree of +components. + +The tree will be explained later, but for now, let's consider the +relationship between the string representation and the broken-down +representation. When you create a new message, the string representation +is initially empty. After you set the contents of the broken-down +representation, such as the header fields and the message body, you then +assemble the message from its broken-down representation into its string +representation. The assembling is done through a call to the Assemble() +member function of the DwMessage class. Conversely, when you receive a +message, it is received in its string representation, and you parse the +message to create its broken-down representation. The parsing is done +through a call to the Parse() member function of the DwMessage class. +From the broken-down representation, you can access the header fields, the +body, and so on. If you want to modify a received message, you can change +the contents of the broken-down representation, then assemble the message +to create the modified string representation. Because of the way MIME++ +implements the broken-down representation, only those specific components +that were modified in the broken-down representation will be modified in +the new string representation. + +The broken-down representation takes the form of a tree. The idea for the +tree comes from the idea that a message can be broken down into various +components, and that the components form a hierarchy. At the highest +level, we have the complete message. We can break the message down into a +header and a body to arrive at the second-highest level. We can break the +header down into a collection of header fields. We can break each header +field down into a field-name and a field-body. If the header field is a +structured field, we can further break down its field-body into components +specific to that field-body, such as a local-part and domain for a +mailbox. Now, we can think of each component of the message as a node in +the tree. The top, or root, node is the message itself. Below that, the +message node contains child nodes for the header and body; the header node +contains a child node for each header field; and so on. Each node +contains a substring of the entire message, and a node's string is the +concatenation of all of its child nodes' strings. + +In the MIME++ implementation, the abstract base class DwMessageComponent +encapsulates all the common attributes and behavior of the tree's nodes. +The most important member functions of DwMessageComponent are Parse() and +Assemble(), which are declared as pure virtual functions. Normally, you +would use these member functions only as operations on objects of the +class DwMessage, a subclass of DwMessageComponent. Parse() builds the +entire tree of components with the DwMessage object at the root. +Assemble() builds the string representation of the DwMessage object by +traversing the tree and concatenating the strings of the leaf nodes. +While every node in the tree is a DwMessageComponent, and therefore has a +Parse() and Assemble() member function, you do not have to call these +member functions for every node in the tree. The reason is that both of +these functions traverse the subtree rooted at the current node. Parse() +acts first on the current node, then calls the Parse() member function of +its child nodes. Assemble() first calls the Assemble() member functions +of a node's child nodes, then concatenates the string representations of +its child nodes. Therefore, when you call Parse() or Assemble() for an +object of the class DwMessage, Parse() or Assemble() will be called +automatically for every component (that is, child node) in the message. + +DwMessageComponent also has one important attribute that you should be aware +of. That attribute is an is-modified flag (aka dirty flag), which is +cleared whenever Parse() or Assemble() is called, and is set whenever the +broken-down representation is modified. To understand how this works, +suppose you have just called Parse() on a DwMessage object to create its +broken-down representation. If you add a new DwField object (representing a +new header field) to the DwHeaders object (representing the header), the +is-modified flag will be set for the DwHeaders object, indicating that the +string representation of the DwHeaders object will have to be re-assembled +from the header fields that it contains. When a node's is-modified flag is +set, it also notifies its parent node to set its is-modified flag. Thus, +when the DwHeaders object's is-modified flag is set, the DwMessage object +that is its parent will also have its is-modified flag set. That way, when +Assemble() is called for the DwMessage object, it will call the Assemble() +member function for the DwHeaders object, as required. Notice that the value +of having an is-modified flag is that it can purge the tree traversal when +the string representation of a message is being assembled. + +One of the first classes you should become familiar with is the DwString +class, which handles character strings in MIME++. DwString has been +designed to handle very large character strings, so it may be different +from string classes in other libraries. Most of the standard C library +string functions have DwString counterparts in MIME++. These functions +all start with "Dw", and include DwStrcpy(), DwStrcmp(), DwStrcasecmp(), +and so on. In addition, the equality operators and assignment operators +work as expected. If you have used string classes from other libraries, +you will find DwString fairly intuitive. + +The following sections describe how to create, parse, and modify a +message. You should also look at the example programs included with the +distribution. These example programs are well-commented and use wrapper +classes. The wrapper classes BasicMessage, MultipartMessage, and +MessageWithAttachments, are designed with three purposes in mind. First, +if your requirements are very modest -- say you just want to send a few +files as attachments -- then you may find these classes to be adequate for +your needs, and you will not have to learn the MIME++ library classes. +Second, wrapper classes are the recommended way to use MIME++. You should +consider starting with these classes and customizing them for your own +application. Using wrapper classes will simplify the use of the MIME++ +library, but will also help to shield your application from future changes +in the MIME++ library. Third, these classes provide excellent examples for +how to use the MIME++ library classes. + +The rest of this tutorial focuses on the library classes themselves. + + +2. Creating a Message + +Creating a message with MIME++ involves instantiating a DwMessage object, +setting values for its parts, and assembling the message into its final +string representation. The following simple example shows how to +accomplish this. + + + void SendMessage( + const char* aTo, + const char* aFrom, + const char* aSubject, + const char* aBody) + { + // Create an empty message + + DwMessage msg; + + // Set the header fields. + // [ Note that a temporary DwString object is created for + // the argument for FromString() using the + // DwString::DwString(const char*) constructor. ] + + DwHeaders& headers = msg.Headers(); + headers.MessageId().CreateDefault(); + headers.Date().FromCalendarTime(time(NULL)); //current date, time + headers.To().FromString(aTo); + headers.From().FromString(aFrom); + headers.Subject().FromString(aSubject); + + // Set the message body + + msg.Body().FromString(aBody); + + // Assemble the message from its parts + + msg.Assemble(); + + // Finally, send it. In this example, just print it to the + // cout stream. + + cout << msg.AsString(); + } + + +In this example, we set the fields 'Message-Id', 'Date', 'To', 'From', and +'Subject', which are all documented in RFC-822. The MIME++ class DwHeaders +directly supports all header fields documented in RFC-822, RFC-2045, and +RFC-1036. To access the field-body for any one these fields, use the +member function from DwHeaders that has a name corresponding to the +field-name for that field. The correspondence between a field-name and +the name of the member function in DwHeaders is consistent: hyphens are +dropped and the first character after the hyphen is capitalized. Thus, +field-name Content-type in RFC-1521 corresponds to the member function +name ContentType. These field-body access functions create an empty field +in the headers if that field does not already exist. To check if a +particular field exists already, DwHeaders provides member functions +HasXxxxx(); for example, HasSender(), HasMimeVersion(), or HasXref() +will indicate whether the DwHeaders object has a 'Sender' field, a +'MIME-Version' field, or an 'Xref' field, respectively. + +In the example, we used the FromString() member function of +DwMessageComponent to set the string representation of the field-bodies. +This is the simplest way to set the contents of a DwFieldBody object. +Many of the field-bodies also have a broken-down represenation, and it is +possible to set the parts of the broken-down representation. Consider, for +example, the DwDateTime class, which represents the date-time element of the +BNF grammar specified in RFC-822. In the example above, we did not set the +string representation -- that would be more difficult and error prone. +Instead we set the contents from the time_t value returned from a call to +the ANSI C function time(). The DwDateTime class also contains member +functions for setting individual attributes. For example, we could have +used the following code: + + DwDateTime& date = msg.Headers().Date(); + time_t t = time(NULL); + struct tm stm = *localtime(&t); + date.SetYear(stm.tm_year); + date.SetMonth(stm.tm_mon); + date.SetDay(stm.tm_mday); + date.SetHour(stm.tm_hour); + date.SetMinute(stm.tm_min); + + +3. Parsing a Message + +Parsing a received message with MIME++ involves instantiating a DwMessage +object, setting its string representation to contain the message, and then +calling the Parse() member function of the DwMessage object. The +following simple example shows how to accomplish this. + + void ParseMessage(DwString& aMessageStr) + { + // Create a message object + // We can set the message's string representation directly from the + // constructor, as in the uncommented version. Or, we can use the + // default constructor and set its string representation using + // the member function DwMessage::FromString(), as in the + // commented version. + + DwMessage msg(aMessageStr); + + // Alternate technique: + // DwMessage msg; // Default constructor + // msg.FromString(aMessageStr); // Set its string representation + + // Execute the parse method, which will create the broken-down + // representation (the tree representation, if you recall) + + msg.Parse(); + + // Print some of the header fields, just to show how it's done + + // Date field. First check if the field exists, since + // DwHeaders::Date() will create it if is not found. + + if (msg.Headers().HasDate()) { + cout << "Date of message is " + << msg.Headers().Date().AsString() + << '\n'; + } + + // From field. Here we access the broken-down field body, too, + // to get the full name (which may be empty), the local part, + // and the domain of the first mailbox. (The 'From' field can + // have a list of mailboxes). + + if (msg.Headers().HasFrom()) { + DwMailboxList& from = msg.Headers().From(); + cout << "Message is from "; + + // Get first mailbox, then iterate through the list + + int isFirst = 1; + DwMailbox* mb = from.FirstMailbox(); + while (mb) { + if (isFirst) { + isFirst = 0; + } + else { + cout << ", "; + } + DwString& fullName = mb->FullName(); + if (fullName != "") { + cout << fullName << '\n'; + } + else { + // Apparently, there is no full name, so use the email + // address + cout << mb->LocalPart() << '@' << mb->Domain() << '\n'; + } + mb = mb->Next(); + } + + } + + // Finally, print the message body, just to show how the body is + // retrieved. + + cout << msg.Body().AsString() << '\n'; + } + +Once you have parsed the message, you can access any of its parts. The +field-bodies of well-known header fields can be accessed by calling member +functions of DwHeaders. Some examples follow. + + DwMediaType& contType = msg.Headers().ContentType(); + DwMechanism& cte = msg.Headers().ContentTransferEncoding(); + DwDateTime& date = msg.Headers().Date(); + +The various subclasses of DwFieldBody, including DwMediaType, DwMechanism, +and DwDateTime above, have member functions that allow you to access the parts +of the field-body. For example, DwMediaType has member functions to allow +you to access its type, subtype, and parameters. If the message is a +multipart message, you may access the body parts by calling member +functions of the class DwBody. See the example code in multipar.cpp for +an example of how to do this. + + +4. Modifying a Message + +Modifying a message combines the procedures of parsing a message and +creating a message. First, parse the message, as explained above. Then +set the values of the components -- field-bodies, new fields, new body +parts, or what have you -- that you wish to modify. Finally, call the +Assemble() member function of the DwMessage object to reassemble the +message. You can then access the modified message by calling +DwMessage::AsString(). These final steps are the same as those involved +in creating a new message. + + +5. Customizing MIME++ Classes + +MIME++ has been designed to be easily customizable. Typically, you +customize C++ library classes through inheritance. MIME++ allows you to +create subclasses of most of its library classes in order to change their +behavior. MIME++ also includes certain 'hooks', which make it far easier +to customize certain parts of the library. + +The most common customization is that of changing the way header fields +are dealt with. This could include adding the ability to handle certain +non-standard header fields, or to change the way the field-bodies of +certain standard header fields are interpreted or parsed. As an example of +the former customization, you may want to add the 'X-status' field or +'X-sender' field to your messages. As an example of the latter, you may +want to change DwMediaType so that it will handle other MIME subtypes. + +Let's begin with the latter situation -- that of subclassing DwMediaType. +Obviously, you will have to become familiar with DwMediaType and its +superclasses before you change its behavior. Then, at a minimum, you will +want to provide your own implementation of the virtual member functions +Parse() and Assemble(). Once you feel comfortable with the behavior of +the behavior of your new class -- call it MyMediaType -- you will have to +take the right steps to ensure that the MIME++ library internal routines +will create objects of type MyMediaType, and not DwMediaType. There are +three such steps. + +First, define a function NewMyMediaType(), matching the prototype + + DwMediaType* NewMyMediaType( + const DwString& aStr, + DwMessage* aParent) + +that creates a new instance of MyMediaType and returns it. Set the static +data member DwMediaType::sNewMediaType to point to this function. +DwMediaType::sNewMediaType is normally NULL, meaning that no user-defined +function is available. When you set this static data member, however, +MIME++'s internal routines will call your own function, and will therefore +be able to create instances of your subclass. + +Second, make sure you have reimplemented the virtual function +DwMediaType::Clone() to return a clone of your own subclassed object. +Clone() serves as a 'virtual constructor'. (See the discussion of virtual +constructors in Stroustrup's _The C++ Programming Language_, 2nd Ed). + +Third, you should define a function CreateFieldBody(), matching the +prototype + + DwFieldBody* CreateFieldBody( + const DwString& aFieldName, + const DwString& aFieldBody, + DwMessageComponent* aParent) + +that returns an object of a subclass of DwFieldBody. (DwFieldBody is a +superclass of MyMediaType). CreateFieldBody() is similar to the +NewMyMediaType() function already described, except that its first +argument supplies the field-name for the particular field currently being +handled by MIME++. CreateFieldBody() should examine the field-name, +create an object of the appropriate subclass of DwFieldBody, and return a +pointer to the object. In this particular case, you need to make sure +that when the field-name is 'Content-Type' you return an object of the +class MyMediaType. Set the hook for CreateFieldBody() setting the static +data member DwField::sCreateFieldBody to point to your CreateFieldBody() +function. DwField::sCreateFieldBody is normally NULL when no user +function is provided. + +These three steps are sufficient to ensure that your subclass of +DwMediaType is integrated with the other MIME++ classes. + +The other customization task mentioned above is that of adding support for +a non-standard header field. There is a simple way to do this, and a way +that involves creating a subclass of DwHeaders. You can access any header +field by calling DwHeaders's member functions. In fact, you can iterate +over all the header fields if you would like. Therefore, the really +simple way is just to not change anything and just use existing member +functions. The relevant functions include DwHeaders::HasField(), which will +return a boolean value indicating if the header has the specified field, +and DwHeaders::FieldBody(), which will return the DwFieldBody object +associated with a specified field. [ Note that DwHeaders::FieldBody() will +create a field if it is not found. ] The default DwFieldBody subclass, +which applies to all header fields not recognized by MIME++, is DwText, +which is suitable for the unstructured field-bodies described in RFC-822 +such as 'Subject', 'Comments', and so on. If a DwText object is suitable +for your non-standard header field, then you don't have to do anything at all. +Suppose, however, that you want an object of your own subclass of +DwFieldBody, say StatusFieldBody, to be attached to the 'X-status' field. +In this case, you will need to set the hook DwField::sCreateFieldBody as +discussed above. Your CreateFieldBody() function should return an +instance of StatusFieldBody whenever the field-name is 'X-status'. + +Finally, while you can access any header field using DwHeaders's member +functions, you may want to create your own subclass of DwHeaders for some +reason or other -- maybe to add a convenience function to access the +'X-status' header field. To ensure that your new class is integrated with +the library routines, you basically follow steps 1 and 2 above for +subclassing DwFieldBody. First, define a function NewMyHeaders() and set the +static data member DwHeaders::sNewHeaders to point to your function. Second, +make sure you have reimplemented the virtual function DwHeaders::Clone() to +return an instance of your subclass. Step 3 for subclassing DwFieldBody +does not apply when subclassing DwHeaders. + + +6. Getting Help + +I will try to help anyone who needs help specific to MIME++. I won't try +to answer general questions about C++ that could be answered by any C++ +expert. Bug reports will receive the highest priority. Other questions +about how to do something I will try to answer in time, but I ask for your +patience. If you have any comments -- perhaps maybe you know of a better +way to do something -- please send them. My preferred email is +dwsauder@fwb.gulf.net, but dwsauder@tasc.com is also acceptable. + +Good luck! + |