[Previous][Next][Contents][FAQ][Bugs][Home]

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 are occasionally 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:

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.

By default, MHonArc ignores any filename specification (the "name" attribute as defined in the Content-Type header field) given in the message when writing the data to disk. MHonArc generates a unique filename with an extenstion based upon sub-type.

If you want MHonArc to use the filename, then you can use the MIMEARGS resource and specify an argument string of "usename".

Example:

<MIMEARGS>
application/postscript:usename
</MIMEARGS>

If you want MHonArc to use specified filename for all application types, then use the following:

<MIMEARGS>
application/*:usename
</MIMEARGS>

CAUTION

The use of "usename" is discouraged since it can lead to filename conflicts and security problems.

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. The name of the file created follows the same guidelines mentioned under application/*.

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. The name of the file created follows the same guidelines mentioned under application/*. In addition to the filename specification mentioned under application/*, an "inline" argument may be declared to instruct MHonArc to inline the image in the generated HTML.

Example:

<MIMEARGS>
image/gif:inline
</MIMEARGS>

The following examples says to inline XBM images and use the name attribute as the filename if defined:

<MIMEARGS>
image/x-xbm:inline usename
</MIMEARGS>

The following represents the default argument settings used by MHonArc:

<MIMEARGS>
image/gif:inline
image/x-xbitmap:inline
image/x-xbm:inline
</MIMEARGS>

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.

multipart/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. The name of the file created follows the same guidelines mentioned under application/*.

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, $decoded, $argstring) = @_;

    # 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.

$decoded

This flag is set to 1 if MHonArc decoded the message and $data represents the orginal data before encoded by the sender. If set to 0, $data has not been decoded. The failure to decode occurs if MHonArc does not recognizeed the encoding specified in the Content-Transfer-Encoding field.

MHonArc has decoded the data for you if it was encoded in 7-Bit, 8-Bit, Binary, Quoted-Printable, Base64, or X-Uuencode.

$argstring

This is an optional argument string that may be used to modify the behavior of the filter. The format of this string is determined by the filter itself.

The value of the string is set by the MIMEARGS resource.

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. The two resources for specifying and controlling MIME filters are MIMEFILTERS and MIMEARGS.

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.

<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-patch:m2h_text_plain'filter:mhtxtplain.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-bmp:m2h_external'filter:mhexternal.pl
image/x-cmu-raster:m2h_external'filter:mhexternal.pl
image/x-pbm:m2h_external'filter:mhexternal.pl
image/x-pcx: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> 

MIMEARGS

The MIMEARGS resource may be used to pass optional arguments to filters to control their behavior. Arguments may be defined on a per content-type basis, or for a specific filter itself. The syntax for each line of the the MIMEARGS element is as follows:

<content-type>:<argument-string>

Or,

<filter-name>:<argument-string>

The format of argument strings is dependent on the filter that processes <content-type> or by the specified filter, <filter-name>.

If an argument string is defined for a filter explicitly and for a content-type that the filter processes, the content-type string will override the filter string.

Examples

The following example represents the default settings used by MHonArc:

<MIMEARGS>
image/gif:inline
image/x-xbitmap:inline
image/x-xbm:inline
</MIMEARGS>

The following example tells the filter that deals handles content-types that cannot be converted directly into HTML to use the "name" attribute as defined in the Content-Type header field as the name of the file generated:

<MIMARGS>
m2h_external'filter:usename
</MIMEARGS>

The following examples says to inline XBM images and use the name attribute as the filename if defined:

<MIMEARGS>
image/x-xbm:inline usename
</MIMEARGS>


[Previous][Next][Contents][FAQ][Bugs][Home]