Chapter 9 Creates, writes, and reads MIME messages

Iris provides a class that can be used to create MultiPart Mime messages (% net.mimepart). Use this class when creating attachments to add to SOAP messages; See Creating Web Services and Web clients. Because MIME is a common standard, there are many other possible applications, such as E-mail processing and HTTP Multipart Post.

MIME Message Overview

A document in MIME format is called a MIME part. Each MIME part has a header that contains the message body (text or binary) or contains additional MIME parts. A MIME part with a MIME version title can be used as a top-level document, called a MIME message. An example is shown below:

In this example, E and F have additional subsections that are not displayed.

To represent the MIME part, use the % net.mimePart class, which provides properties to set the title and content of the part.

Creating MIME parts

To create a MIME part, perform the following steps:

  1. create%Net.MIMEPartThe instance.
  2. Do one of the following:
  • Adds text or binary text. To do this, create an instance of the stream (text or binary) and place the MIME partBodyProperty is set to equal to the stream. Data is written to this stream using the standard stream interface. Don’t bePartsProperty specifies a value.
  • Add a list of MIME parts. To do this, click here to create the MIME part and placePartsProperty set to be equal to the list of these parts. Don’t beBodyProperty specifies a value.
  1. You can optionally set the headers as described in Set and Get MIME Part Headers.

Sets and gets the MIME part header

You can set and get values for HTTP headers. The following properties of % net.mimepart affect the MIME header:

  • ContentType – Content-TypeThe Internet media type (MIME type) of the header. This specifies the Internet media type for the body data. Such as:"text/plain"."text/html"."image/jpeg", "multipart/mixed"And so on.
  • ContentCharset – Content-TypeThe character set portion of the title. If this property is set, it must be set firstContentTypeProperties. For each containing text bodyMIMESection, make sure to set up properlyContentCharsetProperty to indicate the character set used in the text. This property should declare the character set used, because%Net.MIMEPartNo conversions are performed.
  • ContentId– normalizedContent-IDHeader, without Angle brackets (<>) and any leading and trailing Spaces.
  • ContentLocation– standardizedContent-LocationHeader, without any leading or trailing Spaces.
  • ContentTransferEncoding – Content-Transfer-EncodingThe headers. This property can be one of the following:"base64" "quoted-printable" "7bit" "8bit"

Important: Please note that if the content is “Base64” encoded, it cannot contain any Unicode characters. If the content you are sending includes Unicode characters, be sure to convert the content to UTF-8 using $ZCONVERT and then base-64 encoding it. Such as:

set BinaryText=$ZCONVERT(UnicodeText,"O"."UTF8")
set Base64Encoded=$system.Encryption.Base64Encode(BinaryText)
Copy the code

The recipient must use the reverse process to decode the text:

set BinaryText=$system.Encryption.Base64Decode(Base64Encoded)
set UnicodeText=$ZCONVERT(BinaryText,"I"."UTF8")
Copy the code

The % net.mimePart class provides general methods that can be used to manage MIME headers:

  • GetHeader()Returns the value of the header.
  • NextHeader()Gets the next header.
  • SetHeader()Sets the value of the title. In general, you can use it to set non-standard headers.
  • RemoveHeader()Delete the title.

Specifies optional message boundary values

By default, message boundaries are automatically generated. Message boundaries can be specified if desired. To do this, specify the value of the boundary attribute. Be sure to use strings that are highly unlikely to be used in any part of the message.

Writing MIME Mail

To write MIME messages, use % net.mimeWriter, as follows:

  1. create%Net.MIMEWriterClass.
  2. (Optional) Specify the output destination. To do this, use one of the following methods for the writer instance:OutputToDevice()(Default value),OutputToFile()orOutputToStream().
  3. Call the writer’s methods and write the output as needed:
  • After assigning the header name and value,WriteHeader()Will be written to the header.
  • For a given%Net.MIMEPartAn instance of theWriteMIMEBody()Writes the message body, which can have multiple parts.

If the message is multi-part, this method does not write any headers; Writing them is a responsibility. However, if the message is not multipart, the method writes the header.

  • For a given%Net.MIMEPartAn instance of theWriteMIMEMessage()Writes a MIME message, including all headers.

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

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(a)Set msg.Body= # #class(%GlobalCharacterStream%).New(a)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(a)Set status=writer.WriteMIMEMessage(msg)

	If $$$ISERR(status) do $system.Status.DisplayError(status)
	Quit $$$OK
}

Copy the code

The following terminal session shows the use of this method: Java

DHC-APP>w ##class(PHA.TEST.HTTP).WriteMIMEMessage("message text","my header value")                                                                             CONTENT-TYPE: text/html; charset=us-ascii
Custom-header: my header value
 
message text
1
Copy the code

Read MIME Mail

To read MIME messages, use % net.mimereader, as shown below:

  1. create%Net.MIMEReaderClass.
  2. Specify the input source. To do this, use one of the following methods for the reader instance:OpenFile()orOpenStream().
  3. Calling the reader instanceReadMIMEMessage()Methods. This method is returned by reference%Net.MIMEPartAs the first parameter. It returns a status that should be checked.