libnewmail 0.3

Copyright 2003 Lennart Poettering <mzarjznvy (at) 0pointer (dot) de>

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.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

News

Thu Oct 23 2003:

Version 0.3 released; changes include: add new tool nm-spoolhack for emulating unix mail spools, build fixes, added some consts to the headers, library is not completely API- but ABI-compatible (!) to previous versions.

Fri June 5 2003:

Version 0.2 released; changes include: added missing headers

Wed June 4 2003:

Version 0.1 released

Overview

libnewmail is a generic mail checking library for Unix/Linux and other operating systems. It supports a simple API, an extensible plugin architecture and asynchronous queries among other features. It is intented to be a replacement for all that crappy and incomplete code of all those mail checking utilities available. Applications linking to libnewmail may enumerate configured mailboxes, query mail box information and status and request a mail spool auto-detection for users without any libnewmail specific configuration. The library offers a clean API to implement your own mail checking plugins. Programs using libnewmail may query for both the boolean availability and the number of available mails. (The former is usually much faster than the latter) The library is able to distuingish between new (unread) and old (read, current) mails. It includes four CLI tools easy, nmail, nmail-async and nm-spoolhackusing the libnewmail API for mail checking. They are intended to be an example how to use the API with either the synchronous or the asynchronous interface. The utility nm-spoolhack serves a special purpose: mail checking applets using the stat() trick to check the status of Unix mail spools may be tought new tricks by pointing them to the emulated mail spool generated by this tool according to another (remote) mail spool. The emulated spool is at most a single byte in size but carries the right stat() attributes to fool the applets. This way you may use the Gnome mail check applet to query IMAPS mail spools, as an example. It's a hack, but it works quite well.

Status

Currently libnewmail includes plugins for the following mailbox protocols:

There is an API for a graphical configuration interface. However, this is currently a NOOP. This feature will be added eventually.

Documentation

An extensive API reference is available, for both the public and the plugin interface.

libnewmail searches for mailbox configuration in /etc/newmail/ and ~/.newmail/. For each configured mail spool a distinct file exists in one of these directories. The filename consists of a descriptive text and a plugin specification seperated by a dot. e.g. my_funny_mailserver.pop3 is a configuration file for a mail server accessed via the POP3 plugin. Depending on the used plugin, the configuration file may contain different configuration directives. Each directive must be on a seperate line, leading white spaces are ignored, as are lines beginning with # or empty lines. Unknown directives are silently ignored. Some configuration values (especially paths) are subject to a "specials" expansion. The following specials are known:

libunix.so

This plugin for accessing unix mail spools knows the following directives:

libmaildir.so

This plugin for accessing qmail Maildirs knows the following directives:

libpop3.so

This plugin for accessing POP3 mail spools knows the following directives:

libimap.so

This plugin for accessing IMAP4rev1 mail spools knows the following directives:

The default mail spool my be defined by creating a symbolic link named .default in ~/.newmail, which points to the select configuration file.

See the examples directory in the distribution for some examples of configuration files.

Requirements

libnewmail was developed and tested on Debian GNU/Linux "testing" from May 2003, it should work on most other Linux distributions and Unix versions since it uses GNU Autoconf and GNU libtool for source code configuration and shared library management.

The library uses liboop for main loop abstraction for asynchronous queries and may thus be integrated with GTK+ and other toolkits supported by liboop.

libnewmail uses GnuTLS for SSL encryption of POP3 and IMAP4 remote mailbox access.

Installation

As this package is made with the GNU autotools you should run ./configure inside the distribution directory for configuring the source tree. After that you should run make for compilation and make install (as root) for installation of libnewmail.

Acknowledgements

This software includes an implementation of the MD5 algorithm by L. Peter Deutsch. Thanks to him for this.

Download

The newest release is always available from http://0pointer.de/lennart/projects/libnewmail/

The current release is 0.3

Get libnewmail's development sources from the Subversion repository.


Lennart Poettering <mzarjznvy (at) 0pointer (dot) de>, October 2003
$Id: README.html.in 33 2003-10-22 23:14:15Z lennart $