MIME

MHonArc has support for e-mail messages with Multipurpose Internet Mail Extensions (MIME) as defined in RFC 1521. MHonArc handles the filtering of the various content-types used in MIME in a modular fashion. Since new content-types occasionally are defined for MIME, this modularity allows users to add new filters to accomodate new content-types. Also, filters can be hooked in to override MHonArc's default filters, or provide MHonArc with the ability to process existing content-types that it cannot handle currently.


Default Filters

The default filters provided by MHonArc supports the following MIME content-types, which may be overriden by user-defined filters, except where noted:

For more information on how to write your filters, or replace existing filters, see Writing Filters.

The next sections describes how MHonArc processes the content-types listed above.

       

application/*

MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. If the "name" attribute is defined in the Content-Type header field, then the separate file will use the attribute as the filename. Otherwise, MHonArc generates a unique filename with an extenstion based upon sub-type.

Here is the current list of application sub-types (with their filename extensions) supported by MHonArc:

audio/*

MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. If the "name" attribute is defined in the Content-Type header field, then the separate file will use the attribute as the filename. Otherwise, MHonArc generates a unique filename with an extenstion based upon sub-type.

Here is the current list of audio sub-types (with their filename extensions) supported by MHonArc:

image/*

MHonArc will extract the data into a separate file and puts a hyperlink to the file into the HTMLized message. If the "name" attribute is defined in the Content-Type header field, then the separate file will use the attribute as the filename. Otherwise, MHonArc will generate a unique filename with an extenstion based upon sub-type.

Here is the current list of image sub-types (with their filename extensions) supported by MHonArc:

If the image is a GIF or XBM (X bitmap), the HTML IMG element will be used to in-line the image into the HTMLized message.

message/news

message/news signifies an included (MIME) USENET news message. The data associated with a message/news part is processed by MHonArc in the same manner as a regular mail message.

message/partial

message/partial signifies that the content is a single part of a message split into multiple mail messages. message/partial is treated in the same manner as text/plain.

message/rfc822

message/rfc822 signifies an included (MIME) mail message. The data associated with a message/rfc822 part is processed by MHonArc in the same manner as a regular mail message.

multipart/alternative

multipart/alternative signifies multiple content-types with the same (or similiar) information. MHonArc processes only the latest part that has a content-type filter.

mulltipart/digest

mulltipart/digest signifies a series of included mail messages. Each part is processed in the same manner as message/rfc822 unless an explicit content-type is specifed for each part.

multipart/mixed

multipart/mixed signifies data with multiple content-types. MHonArc extracts each part and calls the appropriate content-type filter for each part, if defined.

multipart/parallel

multipart/parallel is processed in the same manner as multipart/mixed.

text/html

text/html signifies that the data is HTML markup. The data as left "as is" with the exception of some processing to legally include the HTML into the HTMLized mail message. I.e. MHonArc removes the HEAD an BODY tags, the TITLE element will be replaced with an ADDRESS element surrounded by HR's, and the BASE element URL will be propogated to relative URLs.

text/plain

text/plain signifies ASCII character data. In the HTMLized message, the data is wrapped in a PRE element with special characters (< > &) converted to entity references. MHonArc will also make any URLs into hyperlinks. The following URL types are recognized:

text/setext

text/setext signifies "structure enhanced text". The data is converted into HTML containing hyperlinks as defined by the setext data. For more information on setext, see <URL:http://www.bsdi.com/setext/>.

video/*

MHonArc extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. If the "name" attribute is defined in the Content-Type header field, then the separate file will use the attribute as the filename. Otherwise, MHonArc generates a unique filename with an extenstion based upon sub-type.

Here is the current list of video sub-types (with their filename extensions) supported by MHonArc:


Non-MIME Messages

Messages that do not contain a MIME Content-Type header field are processed as text/plain messages.


Writing Filters

If you want to write your own filter for use in MHonArc, you need to know the Perl programming language. The following information assumes you know Perl. To learn how to hook in your filters into MHonArc, see Specifying Filters.

Function Interface of Filter

MHonArc interfaces with MIME filters by calling a routine with a specific set of arguments. The prototype of the interface routine is as follows:

sub filter {
    local($head, *fields, $data) = @_;

    # Filter code here

    # The last statement should be the return value, unless an
    # explicit return is done. See the following for the format of the
    # return value.
}

Argument Descriptions

$head
This is the header text of the message (or body part if called in a mulitpart message).
*fields
This is a pointer to an associative array that has broken down $head into field label/field value components. The keys are the lower-case representations of the field values. Example: If you would like to retrieve the value of the Content-Type field, then use the following: $fields{`content-type'}. If a field occurs more than once in a header, MHonArc separates the field values in the associative array by a `\034' character. To make your filter less likely to break due to changes in MHonArc, you may use the $'X variable instead of `\034'.

$data
This is a copy of the message (or body part if called in a mulitpart message) body. MHonArc has decoded the data for you if it was encoded in Quoted-Printable or Base64. You might want to check the Content-Transfer-Encoding field to determine if the data has been decoded. If the value does not equal Quoted-Printable or Base64, then data is still encoded by the method specified in Content-Transfer-Encoding field.

Return Value

The return value is treated as an array. The first item in the array is a string representing the HTML markup to insert in the HTMLized message. An empty string may be returned to tell MHonArc that the routine was unable to filter data.

Any other array items are treated as names of any files that were generated by the filter. MHonArc needs to keep track if any extra files that a filter may generate in order for MHonArc to delete those files if the message gets removed from the archive.

Filter Writing Tips

The following recommendations/tips are given to help you write filters:

Using C

If a MIME filter requires the utilization of a C program, or other non-Perl executable, a Perl wrapper must be written for the program in-order to interface with MHonArc. The wrapper must follow the rules as specified in Function Interface of Filter.


Specifying Filters

Adding new filters, or overriding existing ones, are done via the Resource File.

MIMEFILTERS

The resource element MIMEFILTERS in the Resource File is used to hook in user specifed filters into MHonArc. The syntax for each line of the the MIMEFILTERS element is as follows:

<content-type>:<routine-name>:<file-of-routine>

The definition of each colon-separated value is as follows:

<content-type>
The MIME content-type the filter processes. The mulitpart types and the message/rfc822 content-types cannot not be overridden.
<routine-name>
The actual routine name of the filter. The name should be fully qualified by the package it is definedi (e.g. "mypackage'filter").
<file-of-routine>
The name of the file that defines <routine-name>. If the file is not a full pathname, MHonArc finds the file by looking in the standard include paths of Perl, and the paths specified by the PERLINC resource element.
Any whitespace is stripped out before processing.

Example

The following represents the default value of MIMEFILTERS:

<MIMEFILTERS>
application/mac-binhex40:m2h_external'filter:mhexternal.pl
application/octet-stream:m2h_external'filter:mhexternal.pl
application/oda:m2h_external'filter:mhexternal.pl
application/pdf:m2h_external'filter:mhexternal.pl
application/postscript:m2h_external'filter:mhexternal.pl
application/rtf:m2h_external'filter:mhexternal.pl
application/x-bcpio:m2h_external'filter:mhexternal.pl
application/x-cpio:m2h_external'filter:mhexternal.pl
application/x-csh:m2h_external'filter:mhexternal.pl
application/x-dvi:m2h_external'filter:mhexternal.pl
application/x-gtar:m2h_external'filter:mhexternal.pl
application/x-hdf:m2h_external'filter:mhexternal.pl
application/x-latex:m2h_external'filter:mhexternal.pl
application/x-mif:m2h_external'filter:mhexternal.pl
application/x-netcdf:m2h_external'filter:mhexternal.pl
application/x-sh:m2h_external'filter:mhexternal.pl
application/x-shar:m2h_external'filter:mhexternal.pl
application/x-sv4cpio:m2h_external'filter:mhexternal.pl
application/x-sv4crc:m2h_external'filter:mhexternal.pl
application/x-tar:m2h_external'filter:mhexternal.pl
application/x-tcl:m2h_external'filter:mhexternal.pl
application/x-tex:m2h_external'filter:mhexternal.pl
application/x-texinfo:m2h_external'filter:mhexternal.pl
application/x-troff-man:m2h_external'filter:mhexternal.pl
application/x-troff-me:m2h_external'filter:mhexternal.pl
application/x-troff-ms:m2h_external'filter:mhexternal.pl
application/x-troff:m2h_external'filter:mhexternal.pl
application/x-ustar:m2h_external'filter:mhexternal.pl
application/x-wais-source:m2h_external'filter:mhexternal.pl
application/zip:m2h_external'filter:mhexternal.pl
audio/basic:m2h_external'filter:mhexternal.pl
audio/x-aiff:m2h_external'filter:mhexternal.pl
audio/x-wav:m2h_external'filter:mhexternal.pl
image/gif:m2h_external'filter:mhexternal.pl
image/ief:m2h_external'filter:mhexternal.pl
image/jpeg:m2h_external'filter:mhexternal.pl
image/tiff:m2h_external'filter:mhexternal.pl
image/x-cmu-raster:m2h_external'filter:mhexternal.pl
image/x-pbm:m2h_external'filter:mhexternal.pl
image/x-pgm:m2h_external'filter:mhexternal.pl
image/x-pict:m2h_external'filter:mhexternal.pl
image/x-pnm:m2h_external'filter:mhexternal.pl
image/x-portable-anymap:m2h_external'filter:mhexternal.pl
image/x-portable-bitmap:m2h_external'filter:mhexternal.pl
image/x-portable-graymap:m2h_external'filter:mhexternal.pl
image/x-portable-pixmap:m2h_external'filter:mhexternal.pl
image/x-ppm:m2h_external'filter:mhexternal.pl
image/x-rgb:m2h_external'filter:mhexternal.pl
image/x-xbitmap:m2h_external'filter:mhexternal.pl
image/x-xbm:m2h_external'filter:mhexternal.pl
image/x-xpixmap:m2h_external'filter:mhexternal.pl
image/x-xpm:m2h_external'filter:mhexternal.pl
image/x-xwd:m2h_external'filter:mhexternal.pl
image/x-xwindowdump:m2h_external'filter:mhexternal.pl
message/partial:m2h_text_plain'filter:mhtxtplain.pl
text/html:m2h_text_html'filter:mhtxthtml.pl
text/plain:m2h_text_plain'filter:mhtxtplain.pl
text/richtext:m2h_text_plain'filter:mhtxtplain.pl
text/setext:m2h_text_setext'filter:mhtxtsetext.pl
text/tab-separated-values:m2h_text_plain'filter:mhtxtplain.pl
text/x-html:m2h_text_html'filter:mhtxthtml.pl
text/x-setext:m2h_text_setext'filter:mhtxtsetext.pl
video/mpeg:m2h_external'filter:mhexternal.pl
video/quicktime:m2h_external'filter:mhexternal.pl
video/x-msvideo:m2h_external'filter:mhexternal.pl
video/x-sgi-movie:m2h_external'filter:mhexternal.pl
</MIMEFILTERS> 

[Prev:Message Customization]
[Next:Gory Details]
[ToC]


MHonArc 1.1.0 -- MIME