Creating, Writing, and Reading MIME Messages
InterSystems IRIS® provides a class that you can use to create multipart MIME messages (%Net.MIMEPartOpens in a new tab). You use this class when you create attachments to add to SOAP messages; see Creating Web Services and Web Clients. There are many other possible applications, such as email processing and HTTP multipart POST.
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:
Create an instance of %Net.MIMEPartOpens in a new tab.
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.
Optionally set headers as described in Setting and Getting MIME Part Headers.
Specifying an Optional Message Boundary Value
By default, message boundaries are generated automatically. You can specify the message boundary, if needed. To do so, specify a value for the Boundary property. Be sure to use a string that is extremely unlikely to be used in any of the message parts.
Writing MIME Messages
To write MIME messages, use %Net.MIMEWriterOpens in a new tab as follows:
Create an instance of the %Net.MIMEWriterOpens in a new tab class.
Optionally specify an output destination. To do so, use one of the following methods of your writer instance: OutputToDevice() (the default), OutputToFile(), or OutputToStream().
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.
The following example demonstrates the use of WriteMIMEMessage():
ClassMethod WriteMIMEMessage(text As %String,header as %String) as %Status
//specify some headers
//create MIME writer; write MIME message
If $$$ISERR(status) do $system.Status.DisplayError(status)
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)
Custom-header: my header value