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

@smallexample
@code{/* Prefix @emph{mailbox_} is reserved */}
@code{#include <mailutils/mailbox.h>}
@end smallexample

@deftp {Data Type} mailbox_t
The @code{mailbox_t} object is used to hold information and it is an opaque
data structure to the user. Functions are provided to retrieve information
from the data structure.
@end deftp

@smallexample
@group
                             mailbox_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain   )    |          |  url_t        *-|----+   |  port     |
  -----------    |          |-----------------+        |  hostname |
 (  jakob *-)----+          |  observer_t   *-|        |  file     |
  -----------               |-----------------+        |  ...      |
 (  jeff    )               |  stream_t       |        \-----------/
  -----------               |-----------------|
 (  sean    )               |  locker_t       |
  ----------                |-----------------|
                            |  message_t(1)   |
                            |-----------------|
                            |  message_t(2)   |
                            |  ......         |
                            |  message_t(n)   |
                            \-----------------/
@end group
@end smallexample

@deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
The @var{message} is appended 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_PARAMETER
@var{mbox} is null or @var{message} is invalid.
@end table
@end deftypefun

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

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

@deftypefun int mailbox_create (mailbox_t *@var{pmbox}, const char *@var{name})
The function @code{mailbox_create} allocates and initializes @var{pmbox}.
The concrete mailbox type instantiate is based on the scheme of the url @var{name}.

The return value is @code{0} on success and a code number on error conditions:
@table @code

@item MU_ERR_OUT_PTR_NULL
The pointer @var{pmbox} supplied is NULL.
@item MU_ERR_NO_HANDLER
The url @var{name} supplied is invalid or not supported.
@item EINVAL
@item ENOMEM
Not enough memory to allocate resources.
@end table
@end deftypefun

@deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{name})
Create a mailbox with @code{mailbox_create ()} based on the environment
variable @emph{$MAIL} or the string formed by
@emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null,
@end deftypefun

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

@deftypefun  int mailbox_expunge (mailbox_t @var{mbox})
All messages marked for deletion are removed.

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

@deftypefun  int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
Get the @var{folder}.

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

@deftypefun  int mailbox_get_debug (mailbox_t @var{mbox}, debug_t *@var{debug})
Get a debug object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@item ENOMEM
@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_PARAMETER
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{pmessage})
Retrieve message number @var{msgno}, @var{pmessage} is allocated and
initialized.

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

@deftypefun  int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t*@var{observable})
Get the observable object.

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

@deftypefun  int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property})
Get the property object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@item ENOMEM
@end table
@end deftypefun

@deftypefun  int mailbox_get_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_PARAMETER
@var{mbox} is null.
@end table
@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_PARAMETER
@var{mbox} is invalid or @var{pstream} is NULL.
@end table
@end deftypefun

@deftypefun  int mailbox_get_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
The return value is @code{0} on success and a code number on error conditions:

@table @code
@item MU_ERROR_INVALID_PARAMETER
@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_PARAMETER
@var{mbox} is null.
@end table
@end deftypefun

@deftypefun  int mailbox_is_modified (mailbox_t @var{mbox})
Check if the mailbox been modified by an external source.

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

@deftypefun  int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of first unseen message in @var{mbox}.

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

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

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

@deftypefun  int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of recent messages in @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is 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 created based on the @var{mbox} type.  The @var{flag} can be OR'ed.
See @code{stream_create} for @var{flag}'s description.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EAGAIN
@itemx EINPROGRESS
Operation in progress.
@item EBUSY
Resource busy.
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null or flag is invalid.
@item ENOMEM
Not enough memory.
@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_PARAMETER
@var{mbox} is null.
@item ENOMEM
Not enough memory.
@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_PARAMETER
@var{mbox} 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_PARAMETER
@var{mbox} or @var{stream} is NULL.
@end table
@end deftypefun

@deftypefun  int mailbox_set_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
The @var{ticket} will be set on the @code{auth_t} object on creation.

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

@deftypefun  int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the next predicted uid for @var{mbox}.

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

@deftypefun  int mailbox_uidvalidity (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the uid validity of @var{mbox}.

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