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 semi-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").

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.

Whitespace is stripped out for each filter specification.

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 {
    my($fields_hash_ref, $body_data_ref, $is_decoded, $filter_args) = @_;

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

Parameter Descriptions

  $fields_hash_ref->{'content-type'}[0]

Return Value

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

Any other list 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 $mhonarc::OUTDIR to determine the location of the mail archive.

  NOTE	Do not include $mhonarc::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.

• Test your filter before production use.

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 conventions described in Writing Filters.

Default Setting

<MIMEFilters>
application/octet-stream;  m2h_external::filter;	mhexternal.pl
application/*;		   m2h_external::filter;	mhexternal.pl
application/x-patch;	   m2h_text_plain::filter;	mhtxtplain.pl
audio/*;		   m2h_external::filter;	mhexternal.pl
chemical/*;		   m2h_external::filter;	mhexternal.pl
model/*;		   m2h_external::filter;	mhexternal.pl
image/*;		   m2h_external::filter;	mhexternal.pl
message/delivery-status;   m2h_text_plain::filter;	mhtxtplain.pl
message/external-body;     m2h_msg_extbody::filter;	mhmsgextbody.pl
message/partial;	   m2h_text_plain::filter;	mhtxtplain.pl
text/*;			   m2h_text_plain::filter;	mhtxtplain.pl
text/enriched;		   m2h_text_enriched::filter;	mhtxtenrich.pl
text/html;		   m2h_text_html::filter;	mhtxthtml.pl
text/plain;		   m2h_text_plain::filter;	mhtxtplain.pl
text/richtext;		   m2h_text_enriched::filter;	mhtxtenrich.pl
text/setext;		   m2h_text_setext::filter;	mhtxtsetext.pl
text/tab-separated-values; m2h_text_tsv::filter;	mhtxttsv.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
x-sun-attachment;	   m2h_text_plain::filter;	mhtxtplain.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. The following is an example how the link is formatted:

Attachment: blueball.gif
Description: Blue ball GIF icon

The description text is retrieved from the Content-Disposition message header field, if defined. If not defined, a generic description will be provided based on the specified content-type of the data.

If the useicon filter argument has been specified for the filter, the following format will be used:

blueball.gif
Description: Blue ball GIF icon

The actual icon used is based upon the ICONS resource.

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:

All arguments should be separated by at least one space.

The following table shows the default list of content-types with the filename extension used and a short description that m2h_external::filter recognizes:

m2h_msg_extbody::filter

This filter is designed to process message/external-body data. The filter attempts to translate the external-body paramaters into a linked URL with some descriptive information, if provided. The following access-types are supported: ANON-FTP, FTP, TFTP, LOCAL-FILE, and URL. Note, LOCAL-FILE is only supported if the local-file option is specified.

m2h_msg_extbody::filter can take the following arguments:

m2h_text_enriched::filter

This filter is designed to process text/enriched, or text/richtext, data. The following table summarizes the translation of text/enriched commands to HTML tags:

If the text/enriched contains non-ASCII character, the filter will convert the characters to the appropriate entity references.

m2h_text_html::filter

This filter is designed to process text/html, or text/x-html, data. The filter modifies HTML documents so they can be included into the message pages without causing invalid markup to occur. The following modification are done to HTML documents when processed by MHonArc:

• The HEAD element is removed. Since some elements within the HEAD element may be relevant to the rest of the document, the following is done when removing the HEAD element:

  • The title will be extracted and prepended to the body data.
  • Any BASE URL will be propogated to any relative URLs in the document.

• Any markup related to scripting is removed for security reasons. The following tags are removed: <applet>, <base>, <embed>, <form>, <ilayer>, <input>, <layer>, <link>, <meta>, <object>, <option>, <param>, <script>, <select>, <style>, <textarea>. The following attributes are removed: onload, onunload, onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup. The allowscript option can be be used to override this behavior (see below).

• cid: URLs are resolved, if possible. Therefore, if image data related to the HTML document is included with the message, the URLs will be modified to the filenames of the images that were decoded.

m2h_text_html::filter can take the following arguments:

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:

All arguments should be separated by at least one space.

m2h_text_setext::filter

This filter converts text/setext and text/x-setext messages to HTML.

m2h_text_tsv::filter

This filter converts text/tab-separated-values to HTML. The tabular data will be converted into an HTML table.

m2h_null::filter

This filter can be used to exclude message content from archives. You can register this filter to any content-type you do not want to store in your archives. For example, the following resource setting excludes all images:

<MIMEFilters>
image/*; m2h_null::filter; mhnull.pl
</MIMEFilters>

The markup returned by this filter displays the a one line description of what was excluded. Examples:

<<attachment: HelloWorld.jpg>>
<<application/postscript>>
<<inline: image/jpg>>

If the disposition is available, it will be shown. If a filename was specified, it will be shown. If there was no filename, the content-type is shown.

Resource Variables

N/A

Examples

The following code is an example filter for converting text/tab-separated-values into an HTML table:

package m2h_text_tsv;

sub filter {
    my($fields, $data, $isdecode, $args) = @_;
    my($field, $line, $ret);
    local($_);

    $$data =~ s/^\s+//;
    $ret  = "<table border=1>\n";
    foreach $line (split(/\r?\n/, $$data)) {
	$ret .= "<tr>";
	foreach $field (split(/\t/, $line)) {
	    $ret .= "<td>$field</td>";
	}
	$ret .= "</tr>\n";
    }
    $ret .= "</table>\n";
    ($ret);
}

1;

Version

1.0

See Also

CHARSETCONVERTERS, MIMEARGS, MIMEDECODERS, MIMEEXCS, PERLINC

$Date: 2002/10/21 16:55:19 $
MHonArc
Copyright © 1997-2001 Earl Hood, mhonarc@mhonarc.org