@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2010
@c Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

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

@end smallexample

The most common mailbox format on UNIX platform is @emph{mbox}. Mbox is a
text file that contains messages separated by a special format string.

@smallexample
From SP envelope-sender SP date [SP moreinfo]
@end smallexample

@table @code
@item "From "
 is sometimes call the @emph{From_}.
@item  envelope-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{mu_mbox_t} is created, initialized and destroyed by @code{mu_mbox_create ()}
and @code{mu_mbox_destroy ()}. When opening, @code{mu_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{mu_mbox_scan ()}, the function, takes callback
functions called during the scanning to provide information on progress and
new messages found. The scanning will cache some of the headers fields for
speed, new fields could be add with @code{mu_mbox_add_hcache ()}. On Closing
the @var{mu_mbox_t}, @code{mu_mbox_close ()} will free any resources like, headers
cache, locks etc ... The messages with attributes marked deleted will only
be removed on @code{mu_mbox_expunge ()}, if there is a need to save the
modification without purging @code{mu_mbox_save ()} is more appropriate.
New messages are added to the mbox with @code{mu_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 Initialization
@cindex Mbox Initialization

@deftypefun int mu_mbox_create (mu_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 mu_mbox_destroy (mu_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 mu_mbox_set_carrier (mu_mbox_t, stream_t @var{carrier});

Another type of stream can be provided, the @var{carrier}
is set in the @var{mu_mbox_t} handle. Any  previous @var{carrier} stream in
the handle, will be close and destroy. 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 mu_mbox_get_carrier (mu_mbox_t, stream_t *@var{carrier});

Return the @var{mu_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 mu_mbox_open (mu_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 mu_mbox_close (mu_mbox_t)

Close the carrier stream and resources particular to the mailbox.

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

@deftypefun int mu_mbox_uidnext (mu_mbox_t, unsigned long *@var{uidnext})

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

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

@deftypefun int mu_mbox_uidvalidity (mu_mbox_t, unsigned long *@var{uidvalidity})

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

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

@deftypefun int mu_mbox_get_uid (mu_mbox_t, unsigned int @var{msgno}, unsigned long *@var{uid})

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

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

@deftypefun int mu_mbox_get_attribute (mu_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 mu_mbox_get_separator (mu_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 mu_mbox_set_separator (mu_mbox_t, unsigned int @var{msgno}, const char *@var{sep})

The variable @var{sep} should contain a valid "From " separator 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 mu_mbox_get_hstream (mu_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 mu_mbox_set_hstream (mu_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 mu_mbox_set_hsize (mu_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 mu_mbox_set_hlines (mu_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 mu_mbox_get_bstream (mu_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 mu_mbox_set_bstream (mu_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 mu_mbox_set_bsize (mu_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 mu_mbox_set_blines (mu_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 mu_mbox_get_size (mu_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 mu_mbox_set_hcache (mu_mbox_t, const char **@var{array}, size_t @var{len})

Set the @var{array} of fields as the header to cache when doing the scanning.
If @var{array} is NULL the header cache is emptied.

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

@deftypefun int mu_mbox_add_hcache (mu_mbox_t, const char **@var{array}, size_t @var{len})

Add to the current cache for the scan, the fields in @var{array}.

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

@deftypefun int mu_mbox_value_hcache (mu_mbox_t, unsigned int @var{msgno}, const char *@var{field}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})

Get the value of @var{field} in the header cache for @var{msgno}. The
result is copied in a @var{buffer} of @var{buflen} and @var{writen} is set
to the number of byte put in @var{buffer}.

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

@deftypefun int mu_mbox_save (mu_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 mu_mbox_expunge (mu_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 mu_mbox_append (mu_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 mu_mbox_append_hb (mu_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 mu_mbox_scan (mu_mbox_t, unsigned int @var{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{mu_mbox_newmsg_cb()} callback
for each new message and @code{mu_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 mu_mbox_count (mu_mbox_t, unsigned int *@var{count})

Same as @code{mu_mbox_scan ()} but does not call the callbacks.

@end deftypefun
@deftypefun int mu_mbox_set_progress_cb (mu_mbox_t, int (*@var{callback}) (int @var{percentage}, 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. The first argument of the
callback represents a @var{percentage} of the scanning progress.

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

@deftypefun int mu_mbox_set_newmsg_cb (mu_mbox_t, int (*@var{callback}) (int @var{count}, 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. The  first argument
is the total of messages found.

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

@deftypefun int mu_mbox_set_error_cb (mu_mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})

Set the callback function for errors. 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  mu_mbox_has_newmail (mu_mbox_t)

Return nonzero if there is new mail append to the mu_mbox_t.
@end deftypefun