MIMEFILTERS

Syntax

Envariable
: N/A
Element
: <MIMEFILTERS> filter-specification
...
</MIMEFILTERS>
Command-line Option
: N/A

Description

The resource MIMEFILTERS is used to hook in user specifed filters into MHonArc. The MIMEFILTERS resource can only be set via the MIMEFILTERS element. 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. An explicit content-type (base/subtype) or a base content-type (base/*) can be specified.

routine-name

The actual routine name of the filter. The name should be fully qualified by the package it is defined in (e.g. "mypackage'filter").

NOTE: Package qualification must use Perl 4 syntax. The '::' qualification is not supported, yet.

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.

Any whitespace is stripped out before processing.

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.

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 multipart message).
*`fields`**	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 `$readmail'FieldSep` 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, Uuencode (x-uuencode, uuencode, x-uue, uue).
`$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:

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.

NOTE

Do not include $'OUTDIR as part as the filename that is returned to MHonArc. If the filter does create files, just return the base name.
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.

Default Setting

<MIMEFilters>
application/*:m2h_external'filter:mhexternal.pl
application/x-patch:m2h_text_plain'filter:mhtxtplain.pl
audio/*:m2h_external'filter:mhexternal.pl
image/*:m2h_external'filter:mhexternal.pl
message/partial:m2h_text_plain'filter:mhtxtplain.pl
text/*: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/*:m2h_external'filter:mhexternal.pl
</MIMEFilters>

The following describes the behavior of each filter.

m2h_external'filter

The filter extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message.

By default, the filter ignores any filename specification given in the message when writing the data to disk. A unique filename with an extenstion based upon sub-type is generated.

m2h_external'filter can take the following arguments:

`inline`	Inline image data by default if content-disposition not defined.
`usename`	Use (file)name attribute for determining name of derived file. Use this option with caution since it can lead to filename conflicts and security problems.
`ext=ext`	Use `ext` as the filename extension. The filter already has a large list of extensions for various content-types. Only use this argument if you process a content-type not recognized by the filter.
`type="description"`	Use "`description`" as type description of the data. The double quotes are required. The filter already has a large list of descriptions for various content-types. Only use this argument if you process a content-type not recognized by the filter.

All arguments should be separated by at least one space.

m2h_text_html'filter

This filter is designed to process text/html or text/x-html messages. The filter must modify the HTML for merging into the final filtered HTML messages. Modification is needed so the resulting filtered message is valid HTML.

m2h_text_plain'filter

This filter is designed to process text/plain messages and messages with no MIME information. The filter is also used to process text messages of an unknown subtype.

The default behavior of the filter is wrap the data in the HTML PRE element and escape special characters. It will also convert text that looks like a URL into a hyperlink. If the data contains non-ASCII character, the filter will convert the characters to the appropriate entity reference.

m2h_text_plain'filter can take the following arguments:

`nourl`	Do not hyperlink URLs.
`quote`	Italicize quoted message text.
`asis=set1:...`	Colon separated lists of charsets to leave as-is. Only HTML special characters will be converted into entities.