MHonArc Resources: MIMEFILTERS

[Prev: MIMEEXCS] | [Resources][TOC] | [Next: MODIFYBODYADDRESSES]

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

NOTE | As of v2.5 of MHonArc, the API for filters is different from v2.4.x, and earlier. The following describes the v2.5 API for filters.

#### 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` | A reference to hash of message/part header fields. Keys are field names in lowercase and values are array references containing the field values. For example, to obtain the content-type, if defined, you would do:
      $fields_hash_ref->{'content-type'}[0]
Values for a fields are stored in arrays since duplication of fields are possible. For example, the `Received:` header field is typically repeated multiple times. For fields that only occur once, the array for the field will only contain one item. See Special Variables and Header Fields for more information about this parameter.
`$body_data_ref` | Reference to body data. The filter can safely modify referenced data.
`$is_decoded` | Boolean flag if body data has been decoded. This is normally true unless some non-standard content-transfer-encoding is used. See MIMEDECODERS on how to register decoders for various content-transfer-encodings.
`$filter_args` | 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 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.

NOTE | If you want MHonArc to treat the data as filtered, but not have anything displayed on the page, just return a string with a single space character.

NOTE | If the filter creates a subdirectory with files, the filter only needs to return the subdirectory in the return list. If the message gets removed, MHonArc will delete the entire directory.

#### Special Variables and Header Fields

The following global variables are made available to filters:

`$mhonarc::MHAindex` | Index key of message. Various MHonArc data structures and utility routines require the index key of the message.
`$mhonarc::MHAmsgid` | Message ID of message.
`$mhonarc::MHAmsgnum` | Message number. The format of the number will at least be five digits wide, with leading zero padding. For example, if the number for a message is `15`, `$mhonarc::$MHAmsgnum` will be equal to `00015`.
`$mhonarc::OUTDIR` | Pathname to archive directory. This variable is useful for filters that create derived files.

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-Id`s and `Content-Location`s 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 itself to not invoke a filter for the data.

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

#### 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:

NOTE | The filters use a MIMEARGS argument style similiar to HTML attribute values. For example:
    <MIMEArgs>
    m2h_text_plain::filter; attachcheck fancyquote maxwidth=80
    </MIMEArgs>
If writing your own filters, you are encouraged to use the same style for consistency.

### 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:

`excludeexts=`ext1`,`... | A comma separated list of message specified filename extensions to exclude. I.e. If the filename extension matches an extension in excludeexts, the content will not be written. The return markup will contain the name of the attachment, but no link to the data. This option is best used with application/octet-stream to exclude unwanted data that is not tagged with the proper content-type.
`ext=ext` | Use ext as the filename extension. The filter already has a large list of extensions for various content-types. Use this argument if you process a content-type not recognized by the filter.
`forceattach` | Force images to never be displayed inline, overriding any Content-Disposition setting.
`forceinline` | Force images to be displayed inline, overriding any Content-Disposition setting.
`frame` | Draw a border around the attachment link.
`iconurl="url"` | Use "url" as the url for the icon to use if the `useicon` option is set. This option will override any setting defined by the ICONS resource. The double quotes are required.
`inline` | Inline image data by default if content-disposition not defined.
`inlineexts=`ext1`,`... | A comma separated list of message specified filename extensions to treat as possible inline data. Applicable when content-type is not `image/`* and `usename` or `usenameext` is in effect.
`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. Use this argument if you process a content-type not recognized by the filter.
`subdir` | Place derived file in a subdirectory of the archive. The subdirectory will be called "`msgMSGNUM`". This option may be useful if `usename` is specified to minimize security and name conflict problems.
`target=`name | Set the TARGET attribute of anchor link to file Default value is undefined (ie. no TARGET attribute will be written).
`useicon` | Include a content-type icon with the hyperlink to the derived file. The icon used is the value of the `iconurl` option or the icon defined by the ICONS resource.
`usename` | Use (file)name attribute for determining name of derived file.
CAUTION | Use this option with caution since it can lead to filename conflicts and security problems.
`usenameext` | Use (file)name attribute for determining the extension of derived file.
CAUTION | Use this option with caution since it can lead to security problems.

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:

Content-type | Extension | Description
--- | --- | ---
application/astound | `asd` | Astound presentation
application/envoy | `evy` | Envoy file
application/fastman | `lcc` | fastman file
application/fractals | `fif` | Fractal Image Format
application/iges | `iges` | IGES file
application/mac-binhex40 | `hqx` | Mac BinHex archive
application/mathematica | `ma` | Mathematica Notebook document
application/mbedlet | `mbd` | mbedlet file
application/ms-excel | `xls` | MS-Excel spreadsheet
application/ms-powerpoint | `ppt` | MS-Powerpoint presentation
application/ms-project | `mpp` | MS-Project file
application/msword | `doc` | MS-Word document
application/octet-stream | `bin` | Binary data
application/oda | `oda` | ODA file
application/pdf | `pdf` | Adobe PDF document
application/pgp | `pgp` | PGP message
application/pgp-signature | `pgp` | PGP signature
application/pkcs7-mime | `p7m` | S/MIME encrypted message
application/pkcs7-signature | `p7s` | S/MIME cryptographic signature
application/postscript | `ps` | PostScript document
application/rtf | `rtf` | RTF file
application/sgml | `sgml` | SGML document
application/studiom | `smp` | Studio M file
application/timbuktu | `tbt` | timbuktu file
application/vis5d | `v5d` | Vis5D dataset
application/vnd.framemaker | `fm` | FrameMaker document
application/vnd.hp-hpgl | `hpg` | HPGL file
application/vnd.lotus-1-2-3 | `123` | Lotus 1-2-3
application/vnd.lotus-approach | `apr` | Lotus Approach
application/vnd.lotus-freelance | `prz` | Lotus Freelance
application/vnd.lotus-organizer | `org` | Lotus Organizer
application/vnd.lotus-screencam | `scm` | Lotus Screencam
application/vnd.lotus-wordpro | `lwp` | Lotus WordPro
application/vnd.mif | `mif` | Frame MIF document
application/vnd.ms-excel | `xls` | MS-Excel spreadsheet
application/vnd.ms-powerpoint | `ppt` | MS-Powerpoint presentation
application/vnd.ms-project | `mpp` | MS-Project file
application/vnd.stardivision.calc | `sdc` | StarCalc spreadsheet
application/vnd.stardivision.chart | `sds` | StarChart document
application/vnd.stardivision.draw | `sda` | StarDraw document
application/vnd.stardivision.impress | `sdd` | StarImpress presentation
application/vnd.stardivision.impress-packed | `sdp` | StarImpress packed file
application/vnd.stardivision.mail | `smd` | StarMail mail file
application/vnd.stardivision.math | `smf` | StarMath document
application/vnd.stardivision.writer | `sdw` | StarWriter document
application/vnd.stardivision.writer-global | `sgl` | StarWriter global document
application/vnd.sun.xml.calc | `sxc` | OpenOffice Calc spreadsheet
application/vnd.sun.xml.calc.template | `stc` | OpenOffice Calc template
application/vnd.sun.xml.draw | `sxd` | OpenOffice Draw document
application/vnd.sun.xml.draw.template | `std` | OpenOffice Draw Template
application/vnd.sun.xml.impress | `sxi` | OpenOffice Impress presentation
application/vnd.sun.xml.impress.template | `sti` | OpenOffice Impress template
application/vnd.sun.xml.math | `sxm` | OpenOffice Math documents
application/vnd.sun.xml.writer | `sxw` | OpenOffice Writer document
application/vnd.sun.xml.writer.global | `sxg` | OpenOffice Writer global document
application/vnd.sun.xml.writer.template | `stw` | OpenOffice Write template
application/winhlp | `hlp` | WinHelp document
application/wordperfect5.1 | `wp` | WordPerfect 5.1 document
application/x-asap | `asp` | asap file
application/x-bcpio | `bcpio` | BCPIO file
application/x-bzip2 | `bz2` | BZip2 compressed data
application/x-compress | `Z` | Unix compressed data
application/x-cpio | `cpio` | CPIO file
application/x-csh | `csh` | C-Shell script
application/x-dot | `dot` | dot file
application/x-dvi | `dvi` | TeX dvi file
application/x-earthtime | `etc` | Earthtime file
application/x-envoy | `evy` | Envoy file
application/x-excel | `xls` | MS-Excel spreadsheet
application/x-gtar | `gtar` | GNU Unix tar archive
application/x-gzip | `gz` | GNU Zip compressed data
application/x-hdf | `hdf` | HDF file
application/x-javascript | `js` | JavaScript source
application/x-ksh | `ksh` | Korn Shell script
application/x-latex | `latex` | LaTeX document
application/x-maker | `fm` | FrameMaker document
application/x-mif | `mif` | Frame MIF document
application/x-mocha | `moc` | mocha file
application/x-msaccess | `mdb` | MS-Access database
application/x-mscardfile | `crd` | MS-CardFile
application/x-msclip | `clp` | MS-Clip file
application/x-msmediaview | `m14` | MS-Media View file
application/x-msmetafile | `wmf` | MS-Metafile
application/x-msmoney | `mny` | MS-Money file
application/x-mspublisher | `pub` | MS-Publisher document
application/x-msschedule | `scd` | MS-Schedule file
application/x-msterminal | `trm` | MS-Terminal
application/x-mswrite | `wri` | MS-Write document
application/x-net-install | `ins` | Net Install file
application/x-netcdf | `cdf` | Cdf file
application/x-ns-proxy-autoconfig | `proxy` | Netscape Proxy Auto Config
application/x-patch | `patch` | Source code patch
application/x-perl | `pl` | Perl program
application/x-pointplus | `css` | pointplus file
application/x-salsa | `slc` | salsa file
application/x-script | `script` | A script file
application/x-sh | `sh` | Bourne shell script
application/x-shar | `shar` | Unix shell archive
application/x-sprite | `spr` | sprite file
application/x-stuffit | `sit` | Macintosh archive
application/x-sv4cpio | `sv4cpio` | SV4Cpio file
application/x-sv4crc | `sv4crc` | SV4Crc file
application/x-tar | `tar` | Unix tar archive
application/x-tcl | `tcl` | Tcl script
application/x-tex | `tex` | TeX document
application/x-texinfo | `texinfo` | TeXInfo document
application/x-timbuktu | `tbp` | timbuktu file
application/x-tkined | `tki` | tkined file
application/x-troff | `roff` | Troff document
application/x-troff-man | `man` | Unix manual page
application/x-troff-me | `me` | Troff ME-macros document
application/x-troff-ms | `ms` | Troff MS-macros document
application/x-ustar | `ustar` | UStar file
application/x-wais-source | `src` | WAIS Source
application/x-zip-compressed | `zip` | Zip compressed data
application/zip | `zip` | Zip archive
audio/basic | `snd` | Basic audio
audio/echospeech | `es` | Echospeech audio
audio/microsoft-wav | `wav` | Wave audio
audio/midi | `midi` | MIDI audio
audio/wav | `wav` | Wave audio
audio/x-aiff | `aif` | AIF audio
audio/x-epac | `pae` | epac audio
audio/x-midi | `midi` | MIDI audio
audio/x-mpeg | `mp2` | MPEG audio
audio/x-pac | `pac` | pac audio
audio/x-pn-realaudio | `ra` | PN Realaudio
audio/x-wav | `wav` | Wave audio
chemical/chem3d | `c3d` | Chem3d chemical test
chemical/chemdraw | `chm` | Chemdraw chemical test
chemical/cif | `cif` | CIF chemical test
chemical/cml | `cml` | CML chemical test
chemical/cmsl | `cml` | Chemical Structure Markup
chemical/cxf | `cxf` | Chemical Exhange Format file
chemical/daylight-smiles | `smi` | SMILES format file
chemical/embl-dl-nucleotide | `emb` | EMBL nucleotide format file
chemical/gaussian | `gau` | Gaussian data
chemical/gaussian-input | `gau` | Gaussian input data
chemical/gaussian-log | `gal` | Gaussian log
chemical/gcg8-sequence | `gcg` | GCG format file
chemical/genbank | `gen` | GENbank data
chemical/jcamp-dx | `jdx` | Jcamp chemical spectra test
chemical/kinemage | `kin` | Kinemage
chemical/macromodel-input | `mmd` | Macromodel chemical test
chemical/mdl-molfile | `mol` | MOL mdl chemical test
chemical/mdl-rdf | `rdf` | RDF chemical test
chemical/mdl-rxn | `rxn` | RXN chemical test
chemical/mdl-sdf | `sdf` | SDF chemical test
chemical/mdl-tgf | `tgf` | TGF chemical test
chemical/mif | `mif` | MIF chemical test
chemical/mmd | `mmd` | Macromodel data
chemical/mopac-input | `mop` | MOPAC data
chemical/ncbi-asn1 | `asn` | NCBI data
chemical/ncbi-asn1-binary | `val` | NCBI data
chemical/pdb | `pdb` | Protein Databank data
chemical/rosdal | `ros` | Rosdal data
chemical/xyz | `xyz` | Xmol XYZ data
image/bmp | `bmp` | Windows bitmap
image/cgm | `cgm` | Computer Graphics Metafile
image/fif | `fif` | Fractal Image Format image
image/g3fax | `g3f` | Group III FAX image
image/gif | `gif` | GIF image
image/ief | `ief` | IEF image
image/ifs | `ifs` | IFS image
image/jpeg | `jpg` | JPEG image
image/pbm | `pbm` | Portable bitmap
image/pgm | `pgm` | Portable graymap
image/png | `png` | PNG image
image/tiff | `tif` | TIFF image
image/vnd | `dwg` | VND image
image/wavelet | `wi` | Wavelet image
image/x-cmu-raster | `ras` | CMU raster
image/x-pbm | `pbm` | Portable bitmap
image/x-pcx | `pcx` | PCX image
image/x-pgm | `pgm` | Portable graymap
image/x-pict | `pict` | Mac PICT image
image/x-pnm | `pnm` | Portable anymap
image/x-portable-anymap | `pnm` | Portable anymap
image/x-portable-bitmap | `pbm` | Portable bitmap
image/x-portable-graymap | `pgm` | Portable graymap
image/x-portable-pixmap | `ppm` | Portable pixmap
image/x-ppm | `ppm` | Portable pixmap
image/x-rgb | `rgb` | RGB image
image/x-xbitmap | `xbm` | X bitmap
image/x-xbm | `xbm` | X bitmap
image/x-xpixmap | `xpm` | X pixmap
image/x-xpm | `xpm` | X pixmap
image/xwd | `xwd` | X window dump
image/xwindowdump | `xwd` | X window dump
message/news | `822` | News post
message/rfc822 | `822` | Mail message
model/iges | `iges` | IGES model
model/mesh | `mesh` | Mesh model
model/vrml | `wrl` | VRML model
text/enriched | `rtx` | Text-enriched document
text/html | `html` | HTML document
text/plain | `txt` | Text document
text/richtext | `rtx` | Richtext document
text/setext | `stx` | Setext document
text/sgml | `sgml` | SGML document
text/tab-separated-values | `tsv` | Tab separated values
text/x-speech | `talk` | Speech document
text/x-vcard | `vcf` | Vcard
video/isivideo | `fvi` | isi video
video/mpeg | `mpg` | MPEG movie
video/msvideo | `avi` | MS Video
video/quicktime | `mov` | QuickTime movie
video/vivo | `viv` | vivo video
video/wavelet | `wv` | Wavelet video
video/x-sgi-movie | `movie` | SGI movie

### 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:

`local-file` | Support LOCAL-FILE access-type. This option is best used for internal local mail archives where it is known that readers will have direct access to the file.

### 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:

Text/Enriched Command | HTML Translation
--- | ---
<Bold> | <b>
<Italic> | <i>
<Underline> | <u>
<Fixed> | <tt>
<Smaller> | <small>
<Bigger> | <big>
<FontFamily><Param>family</Param> | <font face="family">
<Color><Param>color</Param> | <font color="color">
<Center> | <p align="center">
<FlushLeft> | <p align="left">
<FlushRight> | <p align="right">
<FlushBoth> | <p align="justify">
<ParaIndent> | <blockquote>
<Excerpt> | <blockquote>
<Lang><Param>lang</Param> | <div lang="lang">

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

### m2h_text_html::filter

CAUTION | If you are worried about security, it is recommended that you disable support of HTML messages in your mail archives. There is no guarantee that this filter is robust enough to eliminate all possible exploits that can occur with HTML data. See the MIMEALTPREFS and MIMEEXCS resource and the m2h_null::filter on ways to exclude HTML data.

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. 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 will be modified to the filenames of the images that were decoded.

`m2h_text_html::filter` can take the following MIMEARGS arguments:

`allowcomments` | Preserve any comment declarations. Comment declarations are sometimes used to contain executable commands, like for server-side includes. Normally, comment declarations are munged to protect against potential exploits, but this option will disable that behavior.
CAUTION | Using this option can open up security vulnerabilies, including the potential accessing of server resources.
`allownoncidurls` | Preserve URL-based attributes that are not cid: URLs. Normally, any URL-based attribute -- `href`, `src`, `background`, `classid`, `data`, `longdesc` -- will be stripped if it is not a cid: URL. This is to prevent malicious URLs that verify mail addresses for spam purposes, secretly set cookies, or gather some statistical data automatically with the use of elements that cause browsers to automatically fetch data: `IMG`, `BODY`, `IFRAME`, `FRAME`, `OBJECT`, `SCRIPT`, `INPUT`.
NOTE | `Href` attributes for anchor, `<A>`, elements are preserved, even if `allownoncidurls` is not specified. This is so regular hyperlinks will function. Javascript URLs will still be munged (unless the `allowscript` option is specified).
`allowscript` | Preserve any markup associated with scripting. This includes elements and attributes related to scripting.
CAUTION | Use of this option can open up your archives to cross-site scripting (XSS) attacks. It is highly recommended to not use this option, especially for publicly accessible archives.
`attachcheck` | Honor attachment disposition. By default, all text/html data is displayed inline on the message page. If `attachcheck` is specified and Content-Disposition specifies the data as an attachment, the data is saved to a file with a link to it from the message page.
CAUTION | If `attachcheck` is specified, the HTML data is saved "as-is". For example, no stripping of scripting-based markup is performed and no resolution of cid URLs are performed, allowing your archive to be used for cross-site scripting (XSS) exploits. This option SHOULD NOT BE USED for archives unless all mail from all senders can be trusted.
`disablerelated` | Disable processing of related parts processing. I.e. Things like cid URLs will not be resolved.
`nofont` | Remove font tags and styles, including CSS styles.
`notitle` | Do not print extracted title at the beginning of converted output. Since this filter strips out HEAD markup so the document can be included into the message page, this filter will extract the title and print the title of the document before the document body. The `notitle` argument disables this behavior.
`subdir` | Place attachment files in a subdirectory of the archive. This option is used for MHTML messages that include inline images are other referenced data.

### 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. 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 as follows:

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

`asis=`set1`:`... | Colon separated lists of charsets to leave as-is. Only HTML special characters will be converted into entities.
NOTE | The `asis` option is deprecated. It is recommended to use the CHARSETCONVERTERS resource to control how character data is converted.
`attachcheck` | Honor attachment disposition. By default, all text/plain data is displayed inline on the message page. If `attachcheck` is specified and Content-Disposition specifies the data as an attachment, the data is saved to a file with a link to it from the message page.
`disableflowed` | Flowed sematics will be ignored for text denoted with flowed formatting.
NOTE | The effects of `fancyquote` and `quote` will still occur if either option is specified.
`fancyquote` | Highlight quoted message text. Quoted text will be wrapped in HTML `BLOCKQUOTE` elements. By default, inline CSS style settings are generated to render a vertical bar in the left margin. The inline styles are suppressed if the `quoteclass` option is set. This option generates similiar rendering of quoted text as is done for flowed text data, but without the flowed text wrapping sematics.
NOTE | If message text is denoted as flowed text by message headers, the text will always be rendered with flowed sematics unless the `disableflowed` option is specified.
`htmlcheck` | Check if message is actually an HTML message (to get around abhorrent MUAs). The message is treated as HTML if the first non-whitespace data looks like the start of an HTML document. If the data looks like HTML, the HTML filter will be invoked on it.
`inlineexts=`ext1`,`... | A comma separated list of message specified filename extensions to treat as inline data. Applicable only when `uudecode` and `usename` are specified.
`keepspace` | Preserve all spaces if the `nonfixed` option is specified. All spaces and tabs will be translated to the equivalent number of &nbsp; entity references.
`maxwidth=`# | Force the maximum width of lines to be # characters in length. Any lines longer than # characters will be wrapped.
NOTE | A line that contains no whitespace and is longer than `maxwidth`, will NOT be wrapped.
`nonfixed` | Do not wrap message text in the HTML `PRE` element. This will cause text to be rendered in the default font (which is normally proportionally spaced). Each line of the message will have a `<br>` appended in order to preserve the line representation of the message.
`nourl` | Do not hyperlink URLs.
`quote` | Italicize quoted message text. Any quoted lines in the message will be wrapped in the HTML `I` element. Compare this with the `fancyquote` option.
`quoteclass=`classname | CSS classname to use for quoted text. This option applies only for flowed text data or if `fancyquote` is specified. The classname will be the value of the `CLASS` attbribute for the `BLOCKQUOTE` elements, and this option suppresses the generation of inline styles. This option is useful for where a master stylesheet controls the appearance of archives. By using this option, the master stylesheet has complete control on how quoted text in messages should be rendered.
`subdir` | Place attachment files in a subdirectory of the archive. This option is only applicable if `uudecode` is specified.
`target=`name | Set the TARGET attribute of anchors generated from hyperlinking URLs.
`usename` | When decoding uuencoded data, use the full filename specified when write the data to disk instead of just the filename extension.
CAUTION | Use this option with caution since it can lead to filename conflicts and security problems. If you plan on using `usename`, consider using the `subdir` option with it.
`uudecode` | Decode any embedded uuencoded data. Including uuencoded data within messages was a way to trasmit binary data via email before MIME was developed. The inclusion of uuencoded data is deprecated within email, but is still common in the USENET (binary) newsgroups. Note, specifying `uudecode` adds extra overhead in the processing of text messages, including messages without any uuencoded data. Uuencoded data is treated as `application/octet-stream` data for purposes of checking if the data should be excluded when checked against the MIMEEXCS resource. Therefore, if `application/octet-stream` data is listed in MIMEEXCS, uuencoded data will be excluded.

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

NOTE | The sematics of using the MIMEEXCS resource vs this filter are different. When using this filter, MHonArc considers the data successfully converted. But with MIMEEXCS, MHonArc does not consider the data converted. This is relevant when MHonArc determines which alternative part to use for an `multipart/alternative` entity. The `m2h_null::filter` existed before MIMEEXCS was added to MHonArc, hence it mainly exists for compatibility reasons.

## Default Setting

NOTE | It is important to have an explicit entry for `application/octet-stream` for handling unknown media-types.

    <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, MIMEARGS, MIMEDECODERS, MIMEEXCS, PERLINC

[Prev: MIMEEXCS] | [Resources][TOC] | [Next: MODIFYBODYADDRESSES]