Filter Class Overview

GMime comes pre-bundled with a number of stream filters for your convenience and more may be added in the future. For now, lets breeze through a summary of some of the more important ones:

GMimeFilterBasic is used quite a lot internally in GMime for encoding and decoding the content of MIME parts. This class contains a mode for encoding and decoding each of Base64, Quoted-Printable, and Uuencode.

If you are interested in converting between charsets for your users, you will likely want to become familiar with GMimeFilterCharset which provides a convenient way to convert text streams of one charset into another charset.

GMimeFilterCRLF will likely become very useful to you if you are implementing any internet standards or DOS/Unix compatability. This filter is meant for converting line endings from the traditional Unix sequence (LF) to the internet standard (and DOS) sequence, CRLF, and vice versa. Also included in this filter is a way to escape and unescape lines beginning with '.' in the method used by the SMTP and POP protocols.

GMimeFilterFrom is one you will likely need to use if ever you need to write to an mbox-formatted mail spool. At present, it has 2 modes: GMIME_FILTER_FROM_MODE_ESCAPE and GMIME_FILTER_FROM_MODE_ARMOR. If you are writing to an mbox-formatted spool, you will always want to use the ESCAPE mode which will escape lines beginning with "From " by prepending a '>' character, resulting in ">From ". The other mode might come in handy if you are implementing a multipart/signed method where you are quoted-printable encoding a text stream and need to special-case From-lines in order to protect against Unix systems which will alter the message when writing it to an mbox file such as the previously mentioned filter mode. The result is something like "=46rom " which prevents the need to prepend a '>' character when the message arrives at a Unix machine.

Also included are: GMimeFilterBest (which will likely not concern you), GMimeFilterEnriched (which will convert text/enriched and/or text/rtf to text/html), and GMimeFilterHTML which will convert text/plain into text/html with options to wrap strings that appear to be hyperlinks with appropriate <a href=...> tags; GMimeFilterStrip (again, likely this won't concern you), and finally GMimeFilterYenc which will encode or decode the horrific YEncode format that has recently crawled out of the woodwork on Usenet. I emplore you, if you decide to use the YEncode filter in your application, please only use it for compatability with the broken news agents that so evilly pollute our beautiful internet with this rubbish and don't add support to your application to send this nasty format.

For an example on how to use filters, please see the end of the previous chapter where it talks about GMimeStreamFilter and provides a snippet from src/uuencode.c

Note: Since it is non-obvious, filters are applied to a stream in the same order that they are added to the GMimeFilterStream. This means that if you add a base64 encode filter and then add a CRLF filter, the stream will first be base64 encoded and then the end-of-line formatting will be canonicalised to CRLF.