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

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

@deftp {Data Type} mu_mailbox_t
The @code{mu_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
                             mu_mailbox_t               mu_url_t
  -/var/mail-    +---//--->/------------------\   +-->/-----------\
 (  alain   )    |         |  mu_url_t      *-|---+   |  port     |
  ----------     |         |------------------+       |  hostname |
 (  jakob *-)----+         |  mu_observer_t *-|       |  file     |
  ----------               |------------------+       |  ...      |
 (  jeff    )              |  mu_stream_t     |       \-----------/
  ----------               |------------------|
 (  sean    )              |  mu_locker_t     |
  ----------               |------------------|
                           |  mu_message_t(1) |
                           |------------------|
                           |  mu_message_t(2) |
                           |  ......          |
                           |  mu_message_t(n) |
                           \------------------/
@end group
@end smallexample

@c
@c Constructor/destructor and possible types.
@c

@deftypefun  int mu_mailbox_create (mu_mailbox_t *@var{mbox}, const char *@var{name})
The function @code{mu_mailbox_create} allocates and initializes @var{mbox}.
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{mbox} supplied is @code{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 mu_mailbox_create_default (mu_mailbox_t *@var{mbox}, const char *@var{name})
Create a mailbox with @code{mu_mailbox_create()} based on the environment
variable @env{MAIL} or the string formed by
@emph{_PATH_MAILDIR}/@var{user}" or @env{LOGNAME} if @var{user} is null,
@end deftypefun

@deftypefun  void mu_mailbox_destroy (mu_mailbox_t *@var{mbox})
Destroys and releases resources held by @var{mbox}.
@end deftypefun

@deftypefun  int mu_mailbox_open (mu_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 @code{NULL} or flag is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_close (mu_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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_flush (mu_mailbox_t @var{mbox}, int @var{expunge})
@end deftypefun

@deftypefun  int mu_mailbox_get_folder (mu_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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_folder (mu_mailbox_t @var{mbox}, mu_folder_t @var{folder})
@end deftypefun

@deftypefun  int mu_mailbox_uidvalidity (mu_mailbox_t @var{mbox}, unsigned long *@var{number});
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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_uidnext (mu_mailbox_t @var{mbox}, size_t *@var{number});
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 @code{NULL}.
@end table
@end deftypefun

@c
@c Messages.
@c

@deftypefun  int mu_mailbox_get_message (mu_mailbox_t @var{mbox}, size_t @var{msgno}, mu_message_t *@var{message})
Retrieve message number @var{msgno}, @var{message} 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 @code{NULL} or @var{msgno} is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_append_message (mu_mailbox_t @var{mbox}, mu_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 @code{NULL} or @var{message} is invalid.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_messages_count (mu_mailbox_t @var{mbox}, size_t *@var{number});
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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_messages_recent (mu_mailbox_t @var{mbox}, size_t *@var{number});
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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_message_unseen (mu_mailbox_t @var{mbox}, size_t *@var{number});
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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_expunge (mu_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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_save_attributes (mu_mailbox_t @var{mbox})
@end deftypefun

@c
@c Update and Scanning.
@c

@deftypefun  int mu_mailbox_get_size (mu_mailbox_t @var{mbox}, mu_off_t *@var{size})
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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_is_updated (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_scan (mu_mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{count});
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 @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@c
@c Mailbox Stream.
@c

@deftypefun  int mu_mailbox_get_stream (mu_mailbox_t @var{mbox}, mu_stream_t *@var{stream})
The mailbox stream is put in @var{stream}.

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{stream} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_stream (mu_mailbox_t @var{mbox}, mu_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 @code{NULL}.
@end table
@end deftypefun

@c
@c Lock Settings.
@c

@deftypefun  int mu_mailbox_get_locker (mu_mailbox_t @var{mbox}, mu_locker_t *@var{locker})
Get the @var{mu_locker_t} 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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_locker (mu_mailbox_t @var{mbox}, mu_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 @code{NULL}.
@end table
@end deftypefun

@c
@c Property.
@c

@deftypefun  int mu_mailbox_get_property (mu_mailbox_t @var{mbox}, mu_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 @code{NULL}.
@item ENOMEM
@end table
@end deftypefun

@c
@c URL.
@c

@deftypefun  int mu_mailbox_get_url (mu_mailbox_t @var{mbox}, mu_url_t *@var{url})
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 @code{NULL}.
@end table
@end deftypefun

@c
@c Debug.
@c

@deftypefun  int mu_mailbox_has_debug (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_get_debug (mu_mailbox_t @var{mbox}, mu_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 @code{NULL}.
@item ENOMEM
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_debug (mu_mailbox_t @var{mbox}, mu_debug_t @var{debug})
@end deftypefun

@c
@c Events.
@c

@deftypefun  int mu_mailbox_get_observable (mu_mailbox_t mbox @var{mbox}, mu_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 @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@c
@c Locking
@c

@deftypefun  int mu_mailbox_lock (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_unlock (mu_mailbox_t @var{mbox})
@end deftypefun