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.
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.
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>
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:
zip (zip)
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:
x-wav (wav)
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:
x-xwd (xwd)
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 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 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 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 signifies multiple content-types with the same (or similiar) information. MHonArc processes only the latest part that has a content-type filter.
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 signifies data with multiple content-types. MHonArc extracts each part and calls the appropriate content-type filter for each part, if defined.
multipart/parallel is processed in the same manner as multipart/mixed.
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 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:
http://
...
ftp://
...
afs://
...
wais://
...
telnet://
...
gopher://
...
news:
...
nntp:
...
mid:
...
cid:
...
mailto:
...
prospero:
...
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/>.
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:
Messages that do not contain a MIME Content-Type
header field are processed
as text/plain messages.
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.
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. }
$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.
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.
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.
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.
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.
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:
The MIME content-type the filter processes.
The actual routine name of the filter. The name should be fully qualified
by the package it is definedi (e.g. "mypackage'filter
").
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.
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>
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.
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>