==== Description ====

gmime-filter-lzo is an add-on filter for GMime. This filter can be
used as a drop-in replacement for the gzip filter that achieves a
better compression ratio, but is much slower. LZO has the advantage of
having fast compression, with a decent compression ratio, or slower
compression with a better compression ratio. Decompression is always
very fast, regardless of the compression level. See the LZO homepage
for benchmarks and additionnal information.

The latest version of this library can be found at http://x2a.org/git

==== License ====

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

See the 'COPYING' file for details.

==== Requirements ====

- A fairly recent version of GCC.
- CMake verion 2.4 or higher.
- GLib version 2 or higher, 2.12.4 or higher recommended.
- GMime version 2.2 or higher, 2.2.3 or higher recommended.
- LZO, version 2 or higher, 2.02 or higher recommended.

==== Installation ====

For UNIX-like systems:

(untar source in current directory)
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ../<path of gmime-filter-lzo>
$ make
# make install
# ldconfig

==== Usage ====

gmime-filter-lzo is used like any other GMime filter, be sure to link
your program against this library. Your program must either call
g_mime_filter_lzo_lib_init() or lzo_init() (if your program uses
liblzo itself) once, be sure to check for an error.

To initialize a new lzo filter, you call g_mime_filter_lzo_new:

GMimeFilter *g_mime_filter_lzo_new(GMimeFilterLZOMode mode, gboolean slow_comp);

mode can either be GMIME_FILTER_LZO_MODE_COMPRESS or
GMIME_FILTER_LZO_MODE_DECOMPRESS, to compress or decompress,
respectively.

slow_comp is a boolean value to indicate if you want to use the slow
compressor, which achieves a better compression ratio at the cost of
some speed and more memory usage during compression.


Example:

#include <gmime-filter-lzo.h>
...

int main(int argc, char *argv[]) {
	...

	if(g_mime_filter_lzo_lib_init() == FALSE)
		<handle error and do not call the gmime-filter-lzo library>
	...

}

void some_function() {
	GMimeFilter *lzo;
	...

	lzo = g_mime_filter_lzo_new([GMIME_FILTER_LZO_MODE_COMPRESS | GMIME_FILTER_LZO_MODE_DECOMPRESS], [TRUE | FALSE]);
	g_mime_stream_filter_add(<stream_filter>, lzo);
	...

}

A sample program, 'lzo-test' is also included in this distribution. By
default, it reads from standard input and outputs a compressed data
stream to standard output. If given the '-d' argument, it decompresses
standard input to standard output.

==== Feedback ====

If you have found a bug or have a suggestion or comment, feel free to
contact the author either by email or by the http://x2a.org/contact
page.

==== Bugs ====

I don't write those :-).

- The gmime-filter API does not seem to provide a way to report errors
  to higher-level functions, when an error is detected, the library
  simply outputs nothing.

- This library is not yet widely tested, there might be bugs which
  compromise security, especially in the decoder.

==== References ====

GMime, A MIME encoding and parsing library: http://spruce.sourceforge.net/gmime/
GLib, A general utility library: http://developer.gnome.org/doc/API/2.0/glib/index.html
LZO, The LZO real-time data compression library: http://www.oberhumer.com/opensource/lzo/