@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

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

@deftypefun  int mailbox_create (mailbox_t *@var{mbox}, const char *@var{name})
The function @code{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 mailbox_create_default (mailbox_t *@var{mbox}, const char *@var{name})
Create a mailbox with @code{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 mailbox_destroy (mailbox_t *@var{mbox})
Destroys and releases resources held by @var{mbox}.
@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 @code{NULL} or flag is invalid.
@item ENOMEM
Not enough memory.
@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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mailbox_flush (mailbox_t @var{mbox}, int @var{expunge})
@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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mailbox_set_folder (mailbox_t @var{mbox}, folder_t @var{folder})
@end deftypefun

@deftypefun  int mailbox_uidvalidity (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 mailbox_uidnext (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 mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, 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 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 @code{NULL} or @var{message} is invalid.
@end table
@end deftypefun

@deftypefun  int mailbox_messages_count (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 mailbox_messages_recent (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 mailbox_message_unseen (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 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 @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mailbox_save_attributes (mailbox_t @var{mbox})
@end deftypefun

@c
@c Update and Scanning.
@c

@deftypefun  int mailbox_get_size (mailbox_t @var{mbox}, 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 mailbox_is_updated (mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mailbox_scan (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 mailbox_get_stream (mailbox_t @var{mbox}, 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 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 @code{NULL}.
@end table
@end deftypefun

@c
@c Lock Settings.
@c

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

@c
@c Property.
@c

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

@c
@c URL.
@c

@deftypefun  int mailbox_get_url (mailbox_t @var{mbox}, 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 mailbox_has_debug (mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mailbox_get_debug (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 mailbox_set_debug (mailbox_t @var{mbox}, mu_debug_t @var{debug})
@end deftypefun

@c
@c Events.
@c

@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 @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@c
@c Locking
@c

@deftypefun  int mailbox_lock (mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mailbox_unlock (mailbox_t @var{mbox})
@end deftypefun