Creating, Writing, and Reading MIME Messages

Overview

A document in MIME format is referred to as a MIME part. Each MIME part has headers and either contains a message body (either text or binary) or contains additional MIME parts. A MIME part that has a MIME-Version header can be used as a top-level document and is called a MIME message. The following figure shows an example:

In this example, E and F have additional subparts that are not shown.

To represent a MIME part, you use the %Net.MIMEPartOpens in a new tab class, which provides properties that you use to set the headers and contents of the part.

Creating MIME Parts

To create a MIME part, do the following:

1. Create an instance of %Net.MIMEPartOpens in a new tab.

2. Do one of the following:

   • Add a text or binary body. To do so, create an instance of a stream (either text or binary) and set the Body property of your MIME part equal to this stream. Use the standard stream interface to write data into this stream. Do not specify a value for the Parts property.

   • Add a list of MIME parts. To do so, create the MIME parts as described here and set the Parts property equal to a list of these parts. Do not specify a value for the Body property.

3. Optionally set headers as described in Setting and Getting MIME Part Headers.

Writing MIME Messages

To write MIME messages, use %Net.MIMEWriterOpens in a new tab as follows:

1. Create an instance of the %Net.MIMEWriterOpens in a new tab class.

2. Optionally specify an output destination. To do so, use one of the following methods of your writer instance: OutputToDevice() (the default), OutputToFile(), or OutputToStream().

3. Call methods of your writer to write output as needed:

   • Given a header name and value, WriteHeader() writes that header.

   • Given an instance of %Net.MIMEPartOpens in a new tab, WriteMIMEBody() writes the message body, which can have multiple parts.

     If the message is multipart, this method does not write any headers; it is your responsibility to write them. If the message is not multipart, however, the method does write the headers.

   • Given an instance of %Net.MIMEPartOpens in a new tab, WriteMIMEMessage() writes the MIME message, including all headers.

   For single-part messages, WriteMIMEBody() and WriteMIMEMessage() produce the same output.

For complete method signatures and other details, see the class documentation for %Net.MIMEPartOpens in a new tab.

Example: WriteMIMEMessage()

The following example demonstrates the use of WriteMIMEMessage():

ClassMethod WriteMIMEMessage(text As %String,header as %String) as %Status
{
 Set msg=##class(%Net.MIMEPart).%New()
 Set msg.Body=##class(%GlobalCharacterStream).%New()
 Do msg.Body.Write(text)
 
 //specify some headers
 Set msg.ContentType="text/html"
 Set msg.ContentCharset="us-ascii"
 Do msg.SetHeader("Custom-header",header)
 
 //create MIME writer; write MIME message
 Set writer=##class(%Net.MIMEWriter).%New()
 Set status=writer.WriteMIMEMessage(msg)
 
 If $$$ISERR(status) do $system.Status.DisplayError(status)
 Quit $$$OK
}

The following Terminal session shows this method in use:

GNET> Set text = "message text"
 
GNET> Set header="my header value"
 
GNET> Do ##class(GNET.MIME).WriteMIMEMessage(text,header)
CONTENT-TYPE: text/html
Custom-header: my header value
 
message text
 
GNET>

Reading MIME Messages

To read MIME messages, use %Net.MIMEReaderOpens in a new tab, as follows:

1. Create an instance of the %Net.MIMEReaderOpens in a new tab class.

2. Specify the source of input. To do so, use one of the following methods of your reader instance: OpenFile() or OpenStream().

3. Call the ReadMIMEMessage() method of your reader instance. This method returns an instance of %Net.MIMEPartOpens in a new tab by reference as the first argument. It returns a status, which you should check.

For complete method signatures and other details, see the class documentation for %Net.MIMEPartOpens in a new tab.