
                                libnewmail 0.3

   Copyright 2003 Lennart Poettering <mzarjznvy (at) 0pointer (dot) de>
     * [1]License
     * [2]News
     * [3]Overview
     * [4]Status
     * [5]Documentation
     * [6]Requirements
     * [7]Installation
     * [8]Acknowledgements
     * [9]Download

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:

   [10]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:

   [11]Version 0.2 released; changes include: added missing headers

   Wed June 4 2003:

   [12]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:
     * Unix mail spool (libunix.so)
     * qmail Maildir (libmaildir.so)
     * POP3 with SSL and APOP (libpop3.so)
     * IMAP4rev1 with SSL (libimap.so)

   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 [13]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:
     * %h - home directory of user
     * %H - host name
     * %u - user name

  libunix.so

   This plugin for accessing unix mail spools knows the following
   directives:
     * Path: path to the mail spool; subject to specials expansions,
       defaults to /var/mail/%u

  libmaildir.so

   This plugin for accessing qmail Maildirs knows the following
   directives:
     * Path: path to the maildir; subject to specials expansions,
       defaults to %h/Maildir

  libpop3.so

   This plugin for accessing POP3 mail spools knows the following
   directives:
     * Hostname: Host name of the POP3 server, defaults to localhost
     * Username: User name on the POP3 server, defaults to local user
       name
     * Password: Password on the POP3 server
     * UseSSL: Enable SSL? (Yes or No, defaults to No)
     * Port: Which port? (Defaults to 110 whith UseSSL off and 995
       otherwise
     * Debug: Request that every POP3 command is written to STDOUT on
       query? (Yes or No, defaults No)

  libimap.so

   This plugin for accessing IMAP4rev1 mail spools knows the following
   directives:
     * Hostname: Host name of the IMAP server, defaults to localhost
     * Username: User name on the IMAP server, defaults to local user
       name
     * Password: Password on the IMAP server
     * UseSSL: Enable SSL? (Yes or No, defaults to No)
     * Port: Which port? (Defaults to 143 whith UseSSL off and 993
       otherwise
     * Debug: Request that every IMAP command is written to STDOUT on
       query? (Yes or No, defaults No)
     * Folder: Which folder shall be queried? Defaults to "INBOX".

   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 [14]liboop for main loop abstraction for asynchronous
   queries and may thus be integrated with GTK+ and other toolkits
   supported by liboop.

   libnewmail uses [15]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
   [16]http://0pointer.de/lennart/projects/libnewmail/

   The current release is [17]0.3

   Get libnewmail's development sources from the [18]Subversion
   [19]repository.
     _________________________________________________________________


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

   $Id: README.html.in 33 2003-10-22 23:14:15Z lennart $

References

   1. README#license
   2. README#news
   3. README#overview
   4. README#status
   5. README#documentation
   6. README#requirements
   7. README#installation
   8. README#acks
   9. README#download
  10. http://0pointer.de/lennart/projects/libnewmail/libnewmail-0.3.tar.gz
  11. http://0pointer.de/lennart/projects/libnewmail/libnewmail-0.2.tar.gz
  12. http://0pointer.de/lennart/projects/libnewmail/libnewmail-0.1.tar.gz
  13. reference/html/index.html
  14. http://www.liboop.org/
  15. http://www.gnu.org/software/gnutls/gnutls.html
  16. http://0pointer.de/lennart/projects/libnewmail/
  17. http://0pointer.de/lennart/projects/libnewmail/libnewmail-0.3.tar.gz
  18. http://subversion.tigris.org/
  19. https://seth.intheinter.net:8081/svn/libnewmail/
