MIME

MHonArc has some 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:

application/*
audio/*
image/*
message/news (cannot override)
message/partial
message/rfc822 (cannot override)
multipart/alternative (cannot override)
mulltipart/digest (cannot override)
multipart/mixed (cannot override)
multipart/parallel (cannot override)
text/html
text/plain
text/setext
video/mpeg
video/quicktime

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:

octet-stream (bin)
oda (oda)
pdf (pdf)
postscript (ps)
rtf (rtf)
x-bcpio (bcpio)
x-cpio (cpio)
x-csh (csh)
x-dvi (dvi)
x-gtar (gtar)
x-hdf (hdf)
x-latex (latex)
x-mif (mif)
x-netcdf (cdf)
x-sh (sh)
x-shar (shar)
x-sv4cpio (sv4cpio)
x-sv4crc (sv4crc)
x-tar (tar)
x-tcl (tcl)
x-tex (tex)
x-texinfo (texinfo)
x-troff (roff)
x-troff-man (man)
x-troff-me (me)
x-troff-ms (ms)
x-ustar (ustar)
x-wais-source (src)
zip (zip)

audio/*

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

basic (snd)
x-aiff (aif)
x-wav (wav)

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:

gif (gif)
ief (ief)
jpeg (jpg)
tiff (tif)
x-cmu-raster (ras)
x-pict (pict)
x-portable-anymap (pnm)
x-pnm (pnm)
x-portable-bitmap (pbm)
x-pbm (pbm)
x-portable-graymap (pgm)
x-pgm (pgm)
x-portable-pixmap (ppm)
x-ppm (ppm)
x-rgb (rgb)
x-xbitmap (xbm)
x-xbm (xbm)
x-xpixmap (xpm)
x-xpm (xpm)
x-xwindowdump (xwd)
x-xwd (xwd)

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:

http://...
ftp://...
afs://...
wais://...
telnet://...
gopher://...
news:...
nntp:...
mid:...
cid:...
mailto:...
prospero:...

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/*

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

mpeg (mpg)
quicktime (mov)
x-msvideo (avi)
x-sgi-movie (movie)

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 and treats the return value as the HTML markup to include in the message. The prototype of the interface routine is as follows:

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

    # Filter code here

    # The last statement should be the HTML return value, unless an
    # explicit return is done.
}

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.

Return Value

The return value should be 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.

Filter Writing Tips

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

Qualify your filter in its own package. This eliminates possible variable/routine conflicts with MHonArc.
If the filter creates derived files (like the image filters), you may use the variable $'OUTDIR to determine the location of the mail archive.
Look at the default filters contained in the distribution of MHonArc. You can use these as templates for writing your own.
Make sure your Perl source file ends with a true statement (like "1;"). MHonArc just performs a require on the file, and if the file does not return true, Perl will abort execution.

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/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:Adding New Messages to an Archive]
[Next:Index Page Customization]
[ToC]

MHonArc 1.0.0 -- MIME