Abstract

Tcl MIME generates and parses MIME body parts.

Table of Contents

1.  SYNOPSIS
1.1  Requirements
1.2  Copyrights
2.  SYNTAX
3.  SEMANTICS
3.1  mime::initialize
3.2  mime::finalize
3.3  mime::getproperty
3.4  mime::getheader
3.5  mime::setheader
3.6  mime::getbody
3.7  mime::copymessage
3.8  smtp::sendmessage
3.9  mime::parseaddress
3.10  mime::parsedatetime
4.  EXAMPLES
§  References
§  Author's Address
A.  TODO List
B.  Acknowledgements

1. SYNOPSIS

Tcl MIME is an implementation of a Tcl package that generates and parses MIME[1] body parts.

Each MIME part consists of a header (zero or more key/value pairs), an empty line, and a structured body. A MIME part is either a "leaf" or has (zero or more) subordinates.

MIME defines four keys that may appear in the headers:

Content-Type:

describes the data contained in the body ("the content");

Content-Transfer-Encoding:

describes how the content is encoded for transmission in an ASCII stream;

Content-Description:

a textual description of the content; and,

Content-ID:

a globally-unique identifier for the content.

Consult [2] for a list of standard content types. Further, consult [3] for a list of several other header keys (e.g., "To", "cc", etc.)

A simple example might be:

In addition to an implementation of the mime package, Tcl MIME includes an implementation of the smtp package.

1.1 Requirements

This package requires:

• Tcl/Tk version 8.0
• Trf version 1.8

1.2 Copyrights

(c) 1999 Marshall T. Rose

Hold harmless the author, and any lawful use is allowed.

2. SYNTAX

mime::initialize returns a token. Parameters:

mime::finalize returns an empty string. Parameters:

mime::getproperty returns a string or a list of strings. Parameters:

mime::getheader returns a list of strings. Parameters:

mime::setheader returns a list of strings. Parameters:

mime::getbody returns a string. Parameters:

mime::copymessage returns an empty string. Parameters:

smtp::sendmessage returns a list. Parameters:

mime::parseaddress returns a list of serialized arrays. Parameters:

mime::parsedatetime returns a string. Parameters:

3. SEMANTICS

3.1 mime::initialize

mime::initialize creates a MIME part:

• If the -canonical option is present, then the body is in canonical (raw) form and is found by consulting either the -file, -string, or -part option.
  
  In addition, both the -param and -header options may occur zero or more times to specify "Content-Type" parameters (e.g., "charset") and header keyword/values (e.g., "Content-Disposition"), respectively.
  
  Also, -encoding, if present, specifies the "Content-Transfer-Encoding" when copying the body.
• If the -canonical option is not present, then the MIME part contained in either the -file or the -string option is parsed, dynamically generating subordinates as appropriate.

3.2 mime::finalize

mime::finalize destroys a MIME part.

If the -subordinates option is present, it specifies which subordinates should be also be destroyed. The default value is "dynamic".

3.3 mime::getproperty

mime::getproperty returns the properties of a MIME part.

The properties are:

The "parts" property is present only if the MIME part has subordinates.

If mime::getproperty is invoked with the name of a specific property, then the corresponding value is returned; instead, if -names is specified, a list of all properties is returned; otherwise, a serialized array of properties and values is returned.

3.4 mime::getheader

mime::getheader returns the header of a MIME part.

A header consists of zero or more key/value pairs. Each value is a list containing one or more strings.

If mime::getheader is invoked with the name of a specific key, then a list containing the corresponding value(s) is returned; instead, if -names is specified, a list of all keys is returned; otherwise, a serialized array of keys and values is returned. Note that when a key is specified (e.g., "Subject"), the list returned usually contains exactly one string; however, some keys (e.g., "Received") often occur more than once in the header, accordingly the list returned usually contains more than one string.

3.5 mime::setheader

mime::setheader writes, appends to, or deletes the value associated with a key in the header.

The value for -mode is one of:

write:

the key/value is either created or overwritten (the default);

append:

a new value is appended for the key (creating it as necessary); or,

delete:

all values associated with the key are removed (the "value" parameter is ignored).

Regardless, mime::setheader returns the previous value associated with the key.

3.6 mime::getbody

mime::getbody returns the body of a leaf MIME part in canonical form.

If the -command option is present, then it is repeatedly invoked with a fragment of the body as this:

(The -blocksize option, if present, specifies the maximum size of each fragment passed to the callback.)

When the end of the body is reached, the callback is invoked as:

Alternatively, if an error occurs, the callback is invoked as:

Regardless, the return value of the final invocation of the callback is propagated upwards by mime::getbody.

If the -command option is absent, then the return value of mime::getbody is a string containing the MIME part's entire body.

3.7 mime::copymessage

mime::copymessage copies the MIME part to the specified channel.

mime::copymessage operates synchronously, and uses fileevent to allow asynchronous operations to proceed independently.

3.8 smtp::sendmessage

smtp::sendmessage sends a MIME part to an SMTP server. (Note that this procedure is in the "smtp" package, not the "mime" package.)

The options are:

-servers:

a list of SMTP servers (the default is "localhost");

-queue:

indicates that the SMTP server should be asked to queue the message for later processing;

-atleastone:

indicates that the SMTP server must find at least one recipient acceptable for the message to be sent;

-originator:

a string containing an 822-style address specification (if present the header isn't examined for an originator address);

-recipients:

a string containing one or more 822-style address specifications (if present the header isn't examined for recipient addresses); and,

-header:

a keyword/value pairing (may occur zero or more times).

If the -originator option is not present, the originator address is taken from "From" (or "Resent-From"); similarly, if the -recipients option is not present, recipient addresses are taken from "To", "cc", and "Bcc" (or "Resent-To", and so on). Note that the header key/values supplied by the "-header" option (not those present in the MIME part) are consulted. Regardless, header key/values are added to the outgoing message as necessary to ensure that a valid 822-style message is sent.

smtp::sendmessage returns a list indicating which recipients were unacceptable to the SMTP server. Each element of the list is another list, containing the address, an SMTP error code, and a textual diagnostic. Depending on the -atleastone option and the intended recipients,, a non-empty list may still indicate that the message was accepted by the server.

3.9 mime::parseaddress

mime::parseaddr takes a string containing one or more 822-style address specifications and returns a list of serialized arrays, one element for each address specified in the argument.

Each serialized array contains these properties:

Note that one or more of these properties may be empty.

3.10 mime::parsedatetime

mime::parsedatetime takes a string containing an 822-style date-time specification and returns the specified property.

The list of properties and their ranges are:

4. EXAMPLES

References

Author's Address

Appendix A. TODO List

mime::initialize

• well-defined errorCode values
• catch nested errors when processing a multipart

Appendix B. Acknowledgements

This package is influenced by the safe-tcl package (Borenstein and Rose, circa 1993), and also by Darren New's unpublished package of 1999.

This package makes use of Andreas Kupries's excellent Trf package.