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

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

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

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

Resource Variables

N/A

Examples

The following code is an example filter for HTML message data (note, this example has a subset of the functionality of the HTML filter used by MHonArc):

##---------------------------------------------------------------------------##
##    Copyright (C) 1995-1998	Earl Hood, earlhood@usa.net
##---------------------------------------------------------------------------##

package m2h_text_html;

$Url	= '(\w+://|\w+:)';	# Beginning of URL match expression

##---------------------------------------------------------------------------
##	The filter must modify HTML content parts for merging into the
##	final filtered HTML messages.  Modification is needed so the
##	resulting filtered message is valid HTML.
##
sub filter {
    local($header, *fields, *data, $isdecode, $args) = @_;
    local($base, $title, $tmp);
    $base 	= '';
    $title	= '';
    $tmp	= '';

    ## Get/remove title
    if ($data =~ s%<title\s*>([^<]*)</title\s*>%%i) {
        $title = "<ADDRESS>Title: <STRONG>$1</STRONG></ADDRESS>\n";
    }
    ## Get/remove BASE url
    if ($data =~ s%(<base\s[^>]*>)%%i) {
        $tmp = $1;
        if ($tmp =~ m|href\s*=\s*['"]([^'"]+)['"]|i) {
	    $base = $1;
	} elsif ($tmp =~ m|href\s*=\s*([^\s>]+)|i) {
	    $base = $1;
	}
    } elsif ((defined($tmp = $fields{'content-base'}) ||
	      defined($tmp = $fields{'content-location'})) &&
	     ($tmp =~ m%/%)) {
	($base = $tmp) =~ s/['"\s]//g;
    }
    $base =~ s%(.*/).*%$1%;

    ## Strip out certain elements/tags
    $data =~ s%<!doctype\s[^>]*>%%i;
    $data =~ s%</?html[^>]*>%%ig;
    $data =~ s%</?body[^>]*>%%ig;
    $data =~ s%<head\s*>[\s\S]*</head\s*>%%i;

    ## Modify relative urls to absolute using BASE
    if ($base =~ /\S/) {
        $data =~ s%(href\s*=\s*['"])([^'"]+)(['"])%
		   &addbase($base,$1,$2,$3)%gei;
        $data =~ s%(src\s*=\s*['"])([^'"]+)(['"])%
                   &addbase($base,$1,$2,$3)%gei;
    }

    ($title . $data);
}
##---------------------------------------------------------------------------
sub addbase {
    local($b, $pre, $u, $suf) = @_;
    local($ret);
    $u =~ s/^\s+//;
    if ($u =~ m%^$Url%o) {	# Non-relative URL, do nothing
        $ret = $pre . $u . $suf;
    } else {			# Relative URL
	if ($u =~ m%^/%) {		# Check for "/..."
	    $b =~ s%^(${Url}[^/]*)/.*%$1%o;	# Get hostname:port number
	}
        $ret = $pre . $b . $u . $suf;
    }
    $ret;
}
##---------------------------------------------------------------------------

1;

Version

1.0

See Also

CHARSETCONVERTERS, MIMEARGS, PERLINC

98/10/24 16:57:31
MHonArc
Copyright © 1997-1998 Earl Hood, earlhood@usa.net