@example
@code{/* Prefix @emph{mbox_} is reserved */}
@code{#include <mailutils/mbox.h>}

@end example

The most common mailbox format on UNIX platform is @emph{mbox}.  Mbox file
is messages separated by the special format string.
@example
   From SP envelope-sender SP date [SP moreinfo]
@end example

@table @code
@item "From "
 is sometimes call the @emph{From_}.
@item  evelope-sender
 is a word with no space.
@item date
 has the same format as @code{asctime ()}
@item moreinfo
 are optional values that are seldom used.
@end table

A @var{mbox_t} is created, initialised and destroyed by @code{mbox_create ()}
and @code{mbox_destroy ()}. When opening, @code{mbox_open ()} will do a quick
check to see if the format is a valid format or an empty file. The scanning
of the mailbox is done by @code{mbox_scan ()}.
The function, @code{mbox_scan ()}, takes callback functions called during the
scanning to provide information. The scanning will cache some of the headers
fields for speed.  Closing the mailbox, @code{mbox_close ()} will free
any ressources like, headers cache, locks etc ... All the messages with
attributes marked deleted will only be removed on @code{mbox_expunge ()}.
If only the attributes need to be save but the messages not removed, this
can be done by @code{mbox_save_attributes ()}.  New messages are added with
@code{mbox_append ()}.  Attributes are saved in the @emph{Status:} header
field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.

@subsubsection Initialisation
@cindex Mbox Initialisation

@deftypefun int mbox_create (mbox_t *@var{mbox})

Allocate and initialize a @var{mbox} handle.

@table @code
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun void mbox_destroy (mbox_t @var{mbox})

When a POP3 session is finished, the structure must be @code{free ()}'ed to
reclaim memory.
@end deftypefun

@subsubsection Carrier
@cindex Mbox channel

@deftypefun int mbox_set_carrier (mbox_t, stream_t @var{carrier});

Another type of stream can be provided to work on, the @var{carrier}
is set in the @var{mbox_t} handle.  Any  previous @var{carrier} stream in
the handle, will be close and release.  Since the parsing code
maintain only the offsets off the message the @var{carrier} stream must be
seekable.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_get_carrier (mbox_t, stream_t *@var{carrier});

Return the @var{mbox_t} carrier.  If none was set, a new file stream will be
created.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_open (mbox_t, const char *@var{filename}, int @var{flags})

Open carrier stream with @var{filename} and @var{flags}.  The stream will be
quickly examine to see if it is a mbox format.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_NO_ENTRY
@item MU_ERROR_NO_ACCESS
@item MU_ERROR_NOT_SUPPORTED
@end table
@end deftypefun

@deftypefun int mbox_close (mbox_t)

Close the carrier stream and ressources particular to the mailbox.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_uidnext (mbox_t, unsigned long *@var{uidnext})

Return the uidnext, if the @var{mbox_t} was not scan @code{mbox_scan ()}
is called first.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item same as @code{mbox_scan ()}
@end table
@end deftypefun

@deftypefun int mbox_uidvalidity (mbox_t, unsigned long *@var{uidvalidity})

Return the uidvalidity, if the @var{mbox_t} was not scan @code{mbox_scan ()}
is called first.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item same as @code{mbox_scan ()}
@end table
@end deftypefun

@deftypefun int mbox_get_attribute (mbox_t, unsigned int @var{msgno}, attribute_t *@var{attribute})

Return an @var{attribute} to indicate the status of message number @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_get_separator (mbox_t, unsigned int @var{msgno}, char **@var{sep})

Return an allocated string in @var{sep} containing the value "From " separating
each message in Unix mbox format. The string should be @code{free ()}ed by
the caller.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_set_separator (mbox_t, unsigned int @var{msgno}, const char *@var{sep})

The variable @var{sep} should contain a valid "From " separtor that will be use
when the expunging.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_get_hstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})

Return a @var{stream} to read the header of message @var{msgno}. The
@var{stream} should be destroy after usage.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_set_hstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})

Use @var{stream} when expunging for message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_set_hsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the @var{size} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_set_hlines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the number of @var{lines} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_get_bstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})

Return a @var{stream} to read the body of message @var{msgno}. The
@var{stream} should be destroy after usage.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_set_bstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})

Use @var{stream} when expunging for message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_set_bsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the @var{size} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_set_blines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the number of @var{lines} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_get_size (mbox_t, unsigned int *@var{size})

Return the @var{size} of mailbox.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_save (mbox_t)

Save the changes to the messages back to the mailbox, but do not
remove messages mark for deletion in the process.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_mak_deleted (mbox_t, unsigned int @var{msgno})

Mark @var{msgno} for deletion.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_unmak_deleted (mbox_t, unsigned int @var{msgno})

Unmark @var{msgno} if it was marked for deletion.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_expunge (mbox_t)

Save the changes to the mailbox and in the process remove all messages
marked for deletion.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_append (mbox_t, const char *@var{sep}, stream_t @var{stream})

Append to the mailbox an rfc822 message represented by @var{stream}.
The variable @var{sep} should contain a valid "From " separator or
NULL to get the default.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_append_hb (mbox_t, const char *@var{sep}, stream_t @var{hstream}, stream_t @var{bstream})

Append to the mailbox an rfc822 message represented by a header, @var{hstream},
and a body, @var{bstream}.  The variable @var{sep} should contain a valid
"From " separator or NULL to get the default.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_scan (mbox_t, unsigned int start, unsigned int *@var{count})

Start scanning the mailbox for new messages.  The variable @var{start} can be
a message number starting point.  The result of the scanning will be in
@var{count}.  The scanning will trigger the @code{mbox_newmsg_cb()} callback
for each new message and @code{mbox_progress_cb ()} at different interval
to notify progression.  The return values of the those callback should be
0 is different then 0 the scanning will be stop an the function returns
MU_ERROR_INTERRUPTED.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_INTERRUPTED
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mbox_set_progress_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})

Set the callback function for progress.  The variable @var{arg} will be pass
back in the callback as the second argument.
@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mbox_set_newmsg_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})

Set the callback function for new messages.  The variable @var{arg} will be
pass back in the callback as the second argument.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun