MIMEFILTERS

• Syntax
• Description
  • Default Filters
  • Writing Filters
• Available Filters
  • m2h_external::filter
  • m2h_msg_extbody::filter
  • m2h_text_enriched::filter
  • m2h_text_html::filter
  • m2h_text_plain::filter
  • m2h_text_tsv::filter
  • m2h_null::filter
• Default Setting
• Resource Variables
• Examples
• Version
• See Also

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.

Default Filters

MHonArc provides an existing set of filters which should be sufficient for most of your needs. For information about the filters, see the Available Filters section below.

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.

Special Variables and Header Fields

The following global variables are made available to filters:

The $fields_hash_ref parameter will have special MHonArc-specific keys defined. Unlike regular header field values, the values are not arrays (unless noted). The following special keys are defined:

x-mha-charset

my $charset = $fields_hash_ref->{'x-mha-charset'}

Only defined for text entities, the value represents the character set encoding of the text entity.

If your filter will take character encoding into account, you should use this value vs what is specified in regular entity header fields because TEXTENCODE may be affect, so the effective character encoding of the data may be different from the original encoding specified in the message.

x-mha-content-type

my $content_type = $fields_hash_ref->{'x-mha-content-type'}

The media type of the entity extracted from content-type entity header.

x-mha-part-number

my $part_no      = $fields_hash_ref->{'x-mha-part-number'}
my $full_part_no = readmail::gen_full_part_number($fields_hash_ref);

The child number of the entity within a multipart entity. Numbering starts with 1, and if data is not part of a multipart entity, this key may not be defined.

x-mha-parent-header

my $parent_header = $fields_hash_ref->{'x-mha-parent-header'}

The header field hash for the parent entity, if applicable.

Accessing Other Parts

For some media-types, a filter may need to access other entity parts to properly process a given part. For example, m2h_text_html::filter must access other entity parts when processing MHTML messages.

When MHonArc parses a multipart message, it fills the %readmail::Cid hash for each entity that defines either a Content-Id or Content-Location. The %readmail::Cid hash is mainly for use by media types, like multipart/related where message parts may reference other message parts.

The keys of the %readmail::Cid hash will be the Content-Ids and Content-Locations and each value will be a reference to an entity hash structure. Code example:

my $entity = $readmail::Cid{$content_id};

The hash structure defines the following fields:

body

my $entity_body_ref = $readmail::Cid{$content_id}->{'body'}

Scalar reference to the body of the entity.

fields

my $entity_header_ref = $readmail::Cid{$content_id}->{'fields'}

Entity header fields hash reference. The format is the same as described for $fields_hash_ref.

filtered

my $is_filtered = $readmail::Cid{$content_id}->{'filtered'}

Boolean if part has already been filtered. This field should be set to a true value by filters that explicitly filters other entity parts. This tells MHonArc to not invoke a filter for the entity.

uri

my $entity_uri = $readmail::Cid{$content_id}->{'uri'}

The URI to the filtered version of the entity. This field should be set by filters that explicitly filters other entity parts.

For a detailed example on how %readmail::Cid can be used, see the MHonArc library mhtxthtml.pl.

Utility Routines

See Utilities Routines in the appendix for various helper routines that can be used by your filter.

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.

Available Filters

The following is the list of filters available in the standard MHonArc distribution:

<MIMEArgs>
m2h_text_plain::filter; attachcheck fancyquote maxwidth=80
</MIMEArgs>

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 extension based upon sub-type is generated.

m2h_external::filter can take the following MIMEARGS 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, HTTP, 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 MIMEARGS 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:

Character data will be translated as specified by the CHARSETCONVERTERS resources.

m2h_text_html::filter

This filter is designed to process text/html, or text/x-html, data. The following modifications are done to HTML documents when processed by MHonArc:

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

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

• Any markup related to scripting is removed for security reasons. Javascript URLs are munged to make them ineffective. At a minimum, the following tags are stripped: <applet>, <base>, <embed>, <form>, <ilayer>, <input>, <layer>, <link>, <meta>, <object>, <option>, <param>, <script>, <select>, <style>, <textarea>. At a minimum, 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 in the HTML will be modified to reference the decoded image data.

m2h_text_html::filter can take the following MIMEARGS 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 to wrap the data in the HTML PRE element and escape special characters. It also converts text that looks like a URL into a hyperlink. Character data will be translated as specified by the CHARSETCONVERTERS resources.

This filter supports text data donoted with flowed sematics as defined by RFC 2646. Quoted text will be wrapped in HTML BLOCKQUOTE tags with inline CSS styles to highlight quoted text with a vertical bar in the left margin:

This is some quoted text. This is some quoted text. This is some quoted text. This is some quoted text. This is some quoted text.

CSS style customization can be done by using the quoteclass argument described below.

m2h_text_plain::filter can take the following MIMEARGS arguments:

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

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/tab-separated-values; m2h_text_tsv::filter;	mhtxttsv.pl
text/x-html;		   m2h_text_html::filter;	mhtxthtml.pl
video/*;		   m2h_external::filter;	mhexternal.pl
x-sun-attachment;	   m2h_text_plain::filter;	mhtxtplain.pl
</MIMEFilters>

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>' . mhonarc::htmlize($field) . '</td>';
	}
	$ret .= "</tr>\n";
    }
    $ret .= "</table>\n";
    ($ret);
}

1;

Version

1.0

See Also

CHARSETCONVERTERS, MIMEALTPREFS, MIMEARGS, MIMEDECODERS, MIMEEXCS, PERLINC

$Date: 2005/06/02 05:50:25 $
MHonArc
Copyright © 1997-2005 Earl Hood, mhonarc@mhonarc.org