@code{#include <mailutils/mailbox.h>}
@deftp {Data Type} mailbox_t
The @code{mailbox_t} object is use to hold information and it is an opaque
data structure to the user. Functions are provided to retrieve the information.
@end deftp
@example
@group
                             mailbox_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain   )    |          |  url_t        *-|----+   |  port     |
  -----------    |          |-----------------+        |  hostname |
 (  jakob *-)----+          |  auth_t       *-|----+   |  file     |
  -----------               |-----------------+    |   |  ...      |
 (  jeff    )               |  stream_t       |    |   \-----------/
  -----------               |-----------------|    |
 (  sean    )               |  locker_t       |    |    auth_t
  ----------                |-----------------|    +-->/----------\
                            |  url_t          |        |  user    |
                            |-----------------|        |  passwd  |
                            |  message[0]     |        \----------/
                            |  ......         |
                            |  message[n]     |
                            \-----------------/
@end group
@end example

@deftypefun int mailbox_create (mailbox_t *@var{pmbox}, const char *@var{name}, int @var{id})
The funcion @code{mailbox_create} allocates and initializes @var{pmbox}.
The validation is base on the scheme of the url @var{name} or @var{id}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_NAME
The url @var{name} supply is invalid or not supported.
@item MU_ERROR_INVALID_ID
The @var{id} is not pointing to a valid reference.
@item MU_ERROR_INVALID_ARG
@var{pmbox} is NULL.
@item MU_ERROR_OUT_OF_MEMORY
Not enough memory to allocate resources.
@end table
@end deftypefun

@deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{user})
The environment variable @emph{$MAIL} or the string form by
@emph{$MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null,
for a default mailbox and calls @code{mailbox_create}.
@end deftypefun

@deftypefun  int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{pstream})
The mailbox stream is put in @var{pstream}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is invalid or @var{pstream} is NULL.
@end table
@end deftypefun

@deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream})
Set the @var{stream} connection to use for the mailbox.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} or @var{stream} are NULL.
@end table
@end deftypefun

@deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag})
A connection is open, if no stream was provided, a stream
is create base on the @var{mbox} type.  The @var{flag} can be OR'ed.
See @code{stream_create} for @var{flag} description.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_EAGAIN
@itemx MU_ERROR_EINPROGRESS
Operation in progress.
@item MU_ERROR_BUSY
Resource busy.
@item MU_ERROR_INVALID_ARG
@var{mbox} is null or flag is invalid.
@item MU_ERROR_OUT_OF_MEMORY
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mailbox_close (mailbox_t @var{mbox})
The stream attach to @var{mbox} is close.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  void mailbox_destroy (mailbox_t *@var{pmbox})
Destroy and releases resources hold by @var{pmbox}.
@end deftypefun

@deftypefun  int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{pmessage})
Retreive message number @var{msgno}, @var{pmessage} is allocate and
initialize.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null or @var{msgno} is invalid.
@item MU_ERROR_OUT_OF_MEMORY
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
The @var{message} is append to the mailbox @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null or @var{message} is invalid.
@end table
@end deftypefun

@deftypefun  int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of message is @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_expunge (mailbox_t @var{mbox})
All the messages set deleted are removed.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{plocker})
Return the @var{locker} object.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_set_locker (mailbox_t @var{mbox}, locker_t @var{locker})
Set the type of locking done by the @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_get_auth (mailbox_t @var{mbox}, auth_t *@var{pauth})
Retriever the @var{*pauth} of the @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_set_auth (mailbox_t @var{mbox}, auth_t @var{auth})
Set the type of authaurity for the mailbox.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_is_updated (mailbox_t @var{mbox})
Check if the mailbox is uptodate.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{pcount});
Scan the mailbox for new messages starting at message @var{msgno}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@item MU_ERROR_OUT_OF_MEMORY
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mailbox_size (mailbox_t @var{mbox}, off_t *@var{psize})
Gives the @var{mbox} size.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{purl})
Gives the constructed @var{url}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun


@deftypefun  int mailbox_register (mailbox_t mbox @var{mbox}, size_t @var{type}, int (*@var{action}) (size_t @var{type}, void *@var{arg}), void *@var{arg})

Register a notification for a event @var{type}:
@table @code
@item MU_EVT_MBX_DESTROY
Mailbox destruction.
@item MU_EVT_MBX_CORRUPTED
When doing expunge an error condition occured.
@item MU_EVT_MBX_MSG_ADD
On every new message when scanning.
@item MU_EVT_MBX_PROGRESS
When scanning notification is send.
@end table
@var{action} will be call when the event occured.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@item MU_ERROR_OUT_OF_MEMORY
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mailbox_deregister (mailbox_t @var{mbox}, void *@var{action})
Delete a register @var{action} for an event.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_set_debug_level (mailbox_t @var{mbox}, size_t @var{level})
Set a trace @var{level}:
@table @code
@item MU_MAILBOX_DEBUG_TRACE
Trace the functions.
@item MU_MAILBOX_DEBUG_PROT
Trace the protocol.
@end table

The return value is @code{0} on success and a code number on error conditions:
@table @code
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end table
@end deftypefun

@deftypefun  int mailbox_get_debug_level (mailbox_t @var{mbox}, size_t *@var{plevel})

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_set_debug_print (mailbox_t @var{mbox}, int (*@var{debug_print}) (void *@var{arg}, const char *@var{buffer}, size_t @var{buffler_length}), void *@var{arg})
Set the function @var{debug_print} being call for the trace.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_ARG
@var{mbox} is null.
@end table
@end deftypefun