Using Caché Internet Utilities
Creating, Writing, and Reading MIME Messages
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Caché provides a class that you can use to create multipart MIME messages (%Net.MIMEPart). You use this class when you create attachments to add to SOAP messages; see Creating Web Services and Web Clients in Caché. Because MIME is a common standard, there are many other possible applications, such as email processing and HTTP multipart POST.

This chapter discusses the following topics:
An Overview of MIME Messages
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.MIMEPart 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.MIMEPart.
  2. Do one of the following:
  3. Optionally set headers as described in Setting and Getting MIME Part Headers.”
Setting and Getting MIME Part Headers
You can set values for and get values of the HTTP headers. The following properties of %Net.MIMEPart affect the MIME headers:
The %Net.MIMEPart class provides general methods that you can use to manage the MIME headers:
For complete method signatures and other details, see the class documentation for %Net.MIMEPart.
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.MIMEWriter as follows:
  1. Create an instance of the %Net.MIMEWriter 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:
    For single-part messages, WriteMIMEBody() and WriteMIMEMessage() produce the same output.
For complete method signatures and other details, see the class documentation for %Net.MIMEPart.
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.MIMEReader, as follows:
  1. Create an instance of the %Net.MIMEReader 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.MIMEPart 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.MIMEPart.