Mail boxes come in different formats and may be on a remote hosts,
only accessible through Mail Delivery Agent(MDA).  Regardeless
of the format and the protocol use, some common actions are needed like
reading, saving, deleting, scanning ... Those actions are provided via a
unify API mailbox_t.

All functions of the mailbox_t API return 0 if succesfull or non-zero
for failure, unless specify otherwise.

@section Init/Destroy
Initializing and destroying a mailbox_t object.

@deftypefun int mailbox_init (mailbox_t *@var{mbx}, const char * @var{url}, int @var{id})
Based on the type of the @var{url}, @var{mbx} is initialize to a known type,
if @var{id} is not zero, it represents the id of the mailbox. The @var{id}
will be use instead of doing heuristic search on the @var{url}.
@example
#include <mailutils.h>
@dots{}
mailbox_t foo, popmbx, bar;
/* same as @url{file:///var/mail/foo} */
mailbox_init (&mbox, "/var/mail/foo", 0);
mailbox_init (&mbox, "pop://popserver.bar.com/foo", 0);
mailbox_init (&mbox, "file:///home/bar/.hiddenmail/bar", 0);
@end example
@end deftypefun

@deftypefun int mailbox_init_default (mailbox_t *@var{mbx}, const char * @var{user})
Initialize the default mailbox of the system as set by the mail adminstrator.
It could be hardcoded or override by a configuration
@file{$sysconfig/mailutils.conf}.
@example
#include <mailutils.h>
@dots{}
/* If the default mailbox on this system is @file{/var/mail} */

mailbox_t mbx;

/* sets the mailbox name to @url{file:///var/mail/foo} */
mailbox_init_default (&mbx, "foo");

/*
 If the user is log as @emph{bar}, sets the mailbox name
 to @url{file:///var/mail/bar}
*/
mailbox_init_default (&mbx, NULL);
@end example
@end deftypefun

@deftypefun int mailbox_destroy (mailbox_t *@var{mbx})
All ressources allocated are release.  If the stream is not open,
@code{mailbox_close} is call.
@end deftypefun

@section Open/Close
Opening and closing mailbox can be done any number of times. But be warned
on some cases like POP3, when opening, the lock can be persistent until
the stream is closed as required by the RFC.

@deftypefun int mailbox_open (mailbox_t @var{mbx}, int @var{flag})
Open the mailbox box stream. This funtion will call @code{mailbox_scan}.

@defmac MU_MB_RDONLY
Stream is open read-only.
@end defmac
@defmac MU_MB_WRONLY
Stream is open write-only.
@end defmac
@defmac MU_MB_RDWR
Stream is open read-write.
@end defmac
@defmac MU_MB_CREAT
If Folder does not exist it is created. May be a noop on remote hosts mailbox.
@end defmac
@defmac MU_MB_APPEND
The stream is opened in append mode.
@end defmac
@defmac MU_MB_ONONBLOCK
For sockets, open() nonblocking.  Not supported.
@end defmac
@end deftypefun

@deftypefun int mailbox_close (mailbox_t @var{mbx})
Close the streams and release the locks.
@end deftypefun

@deftypefun int mailbox_is_open (mailbox_t @var{mbx})
Return a non-zero value if  the stream is open, zero otherwise.
@end deftypefun

This is a very simple implementation of Unix @command{biff}.

@example
#include <mailutils.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

#define NAP 120

int
main ()
@{
    mailbox_t mbx;
    size_t size = 0, size2 = 0;

    if (mailbox_init_default (&mbx, NULL) != 0)
      @{
          fprintf ("Can't initiliaze system mailbox\n");
          exit (EXIT_FAILURE);
      @}
    /* the open may fail if no mailbox was created,
       will check this later */
    mailbox_open (mbx, MU_MB_RDONLY);
    mailbox_size (mbx, &size);
    for (;;)
      @{
         if (! mailbox_is_open (mbx))
           @{
              if (mailbox_open (mbx, MU_MB_RDONLY) != 0);
                @{
                   //fprintf (stderr, "Not exist ?\n");
                @}
           @}
         else
           @{
              if (mailbox_size (mbx, &size2) == 0)
                @{
                   if (size2 > size)
                     @{
                        printf ("You got mail\a\n");
                     @}
                   size = size2;
                @}
           @}

          /* rest a while */
          sleep (NAP);

          /* It is a good habit to close the resources.
             A mailbox could be a remote host and the locking
             may interfere with normal delivery, for example with
             POP, the lock is hold during the entire session.
           */
          mailbox_close (mbx);
       @}

     return 0;
@}
@end example

@section Deletion
Messages can be marked for deletion but the action of removing them is only
taken when @code{mailbox_expunge} is called.

@deftypefun int mailbox_delete (mailbox_t @var{mbx}, size_t @var{msgno})
Mark message @var{msgno} for deletion.
@end deftypefun

@deftypefun int mailbox_undelete (mailbox_t @var{mbx}, size_t @var{msgno})
UnMark message @var{msgno} for deletion.
@end deftypefun

@deftypefun int mailbox_is_deleted (mailbox_t @var{mbx}, size_t @var{msgno})
Return 1 if message @var{msgno} is mark deleted.
@end deftypefun

@deftypefun int mailbox_expunge (mailbox_t @var{mbx})
All messages marked for deletion will be removed and the mailbox updated.
@end deftypefun

@deftypefun int mailbox_num_deleted (mailbox_t @var{mbx})
Return the number of Mailbox marked to be delete.
@end deftypefun

@section New Message
Certain mailboxes allow new messages to be appended the existing folder.
The stream must be @code{mailbox_open}  with the proper permission.

@deftypefun int mailbox_new_message (mailbox_t @var{mbx}, size_t *@var{msgno})
Create an envelope, @var{msgno} will contain a uniq number for this envelope.
@end deftypefun

@deftypefun int mailbox_set_header (mailbox_t @var{mbx}, size_t @var{msgno}, const char *@var{header}, size_t @var{len}, int @var{replace})
Fill the header of new envelope @var{msgno}.  If @var{replace} is zero the
buffer @var{header} will be append, otherwise it will overwrite any
existing one.
@end deftypefun

@deftypefun int mailbox_set_body (mailbox_t @var{mbx}, size_t @var{msgno}, const char *@var{body}, size_t @var{len}, int @var{replace})
Fill the body of new envelope @var{msgno}.  If @var{replace} is zero the buffer
@var{body} will be append, otherwise it will overwrite any existing one.
@end deftypefun

@deftypefun int mailbox_append_message (mailbox_t @var{mbx}, size_t @var{msgno}, int @var{destroy})
@var{msgno} given from @code{mailbox_envelope} will be append to
the mailbox. When appending the header may be modified.  In the case of
Unix Mbox, the header "From " is prepend.  If @var{destroy} is set non-zero
@code{mailbox_destroy_envelope} will be call after delivery.
@end deftypefun

@deftypefun int mailbox_destroy_envelope (mailbox_t @var{mbx}, size_t @var{msgno})
Ressources allocated to envelope @var{msgno} will be release.  This function
should be call after @code{mailbox_append}.
@end deftypefun

@section Reading
Reading the message body and header.

@deftypefun int mailbox_get_content (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
Read the body of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned in
@var{nread}.
@end deftypefun

@deftypefun int mailbox_get_mcontent (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
A buffer is allocated with @code{malloc(3)} return memory containing the body
of message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
@end deftypefun

@deftypefun int mailbox_get_header (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
Read the header of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned
in @var{nread}.
@end deftypefun

@deftypefun int mailbox_get_mheader (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
A buffer allocate with @code{malloc(3)} is return containing the header of
message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
@end deftypefun

@section Locking
Most mailboxes provide locking before changing the content.  Functions
will grab the lock before doing any destructive action.  The Locking functions
are provided for accesssing the folder outside the API, in that case the
lock should be grabed and released.  There is also another level of internal
locking to provide synchronisation to the mailbox_t object.

@deftypefun int mailbox_lock (mailbox_t @var{mbx}, int @var{flag})
Grab the lock.  In some cases, i.e Unix mbox this may involve creating
a .lock file in the spool directory.
@comment Say something about permission the program be gid on some OS.

@defmac MU_MB_RDLOCK
Read lock.
@end defmac
@defmac MU_MB_WRLOCK
Write lock.
@end defmac
@defmac MU_MB_RWLOCK
Read/Write lock.
@end defmac

@end deftypefun

Note on many mailbox, RDLOCK is a noop.

@deftypefun int mailbox_unlock (mailbox_t @var{mbx})
Release the lock.
@end deftypefun

@section Owner/Group
Most mailboxes provide locking before changing their content, Ownership
and group. When creating certain mailbox, you can set the owner/group.

@deftypefun int mailbox_set_owner (mailbox_t @var{mbx}, uid_t @var{uid})
Set the owner to @var{uid}.  If the Mailbox was not @code{mailbox_open}
the action is delayed until the stream is opened.
@end deftypefun
@deftypefun int mailbox_set_group (mailbox_t @var{mbx}, gid_t @var{gid})
Set the group to @var{gid}.  If the Mailbox was not @code{mailbox_open}
the action is delayed until the stream is opened.
@end deftypefun

@section Scanning

Scan is done explicitely on @code{mailbox_open}.

@deftypefun int mailbox_scan (mailbox_t @var{mbx}, size_t *@var{msgs})
The mailbox is parse and @var{msgs} if not NULL contain the message count.
@end deftypefun

@deftypefun int mailbox_scan_progress (mailbox_t @var{mbx}, int (*@var{progress}) (mailbox_t @var{mbx}, int @var{count}, void *@var{arg}), void *@var{arg})
When doing @var{mailbox_scan}, function @var{progress}(@var{mbx}, @var{count},
@var{arg}) is called for each new message.
@end deftypefun

@deftypefun int mailbox_is_updated  (mailbox_t @var{mbx})
Return 1 if @var{mbx} is up to date 0 otherwise.
@end deftypefun

@deftypefun int mailbox_size (mailbox_t @var{mbx}, offt_t *@var{size})
@var{size} is assign the mailbox total size.
@end deftypefun

@deftypefun int mailbox_get_size (mailbox_t @var{mbx}, size_t @var{msgno}, size_t *@var{header}, size_t *@var{body})
For message @var{msgno} set @var{header} size and @var{body} size.
@end deftypefun

@deftypefun int mailbox_count (mailbox_t @var{mbx})
Return the number of messages in @var{mbx}.
@end deftypefun

@section Timeout/Notification
Setting timeout and notifications.  @code{mailbox_scan} can be called
periodically to see if new messages have arrived, if the number of
total messages has changed the notification function is called.  By default
they are disabled.

@deftypefun int mailbox_set_timeout (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@deftypefun int mailbox_get_timeout (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@deftypefun int mailbox_set_refresh (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@deftypefun int mailbox_get_refresh (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@deftypefun int mailbox_set_notification (mailbox_t @var{mbx}, int (*@var{notification}) (mailbox_t @var{mbx}, void *@var{arg}), void *@var{arg})
Not Implemented.
@end deftypefun

@section Registration and Type

Mailbox_t comes with a certain number of builtin types, you can query them
or add you own to the list.

@deftp {Data type} struct mailbox_type
@example
@{
  char *name;
  int  id;
  struct url_type *utype;
  int  (*_init) __P ((mailbox_t *, const char *name));
  void (*_destroy) __P ((mailbox_t *));
@};
@end example
@end deftp

@deftypefun int mailbox_list_type (struct mailbox_type *@var{mtype}, size_t @var{len}, size_t *@var{n})
The @var{mtype} array will be initialize with the list of builtin up to
@var{len}.  The number of struct maiblox_type is put in @var{n}.
@end deftypefun

@deftypefun int mailbox_list_mtype  (struct mailbox_type **@var{mtype}, size_t *@var{n})
An array of size @var{n} is @code{malloc(3)} to hold the builtin list.
@end deftypefun

@deftypefun int mailbox_add_type (struct mailbox_type *@var{mtype})
Add a mailbox @var{mtype} to the list of builtin.
@end deftypefun

@deftypefun int mailbox_remove_type (struct mailbox_type *@var{mtype})
Remove a mailbox @var{mtype} to the list of builtin.
@end deftypefun

@deftypefun int mailbox_get_type (struct mailbox_type **@var{mtype}, int @var{urlid})
Base on the URL @var{urlid} return the mailbox_type.
@end deftypefun

@deftypefun int mailbox_get_name (mailbox_t @var{mbx}, int *@var{mbxid}, char *@var{name}, size_t @var{len}, size_t *@var{n})
Return the name of mailbox identify by @var{mbxid}, in buffer @var{name} of
size @var{len}.  The number of byte is put in @var{n}.
@end deftypefun

@deftypefun int mailbox_get_mname (mailbox_t @var{mbx}, int *@var{mbxid}, char **@var{name}, size_t *@var{n})
Return the name of mailbox identify by @var{mbxid}, in a @code{malloc(3)}
buffer @var{name} of size @var{n}.
@end deftypefun

All mailbox implementations provide this minimum set of the API.

@section Unix Mbox
@cindex Unix Mbox

TODO: describe particularities :
locking policy, appending envelope, describe the flags use in _open(..), etc...

@section POP3 Mbox
@cindex POP3 Mbox

TODO: describe timeout policies, describe the flags use in _open(..),
describe different authorisation supported.

@section IMAP Mbox
@cindex IMAP Mbox

Not implemented.

@section QMail Mbox
@cindex QMail Mbox

Not implemented.

@section MMDF Mbox
@cindex MMDF Mbox

Not implemented.