     /* Prefix mailbox_ is reserved */
     #include <mailutils/mailbox.h>

 -- Data Type: mailbox_t
     The 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.

                                  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)   |
                                 \-----------------/

 -- Function: int mailbox_append_message (mailbox_t MBOX, message_t MESSAGE)
     The MESSAGE is appended to the mailbox MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null or MESSAGE is invalid.

 -- Function: int mailbox_close (mailbox_t MBOX)
     The stream attach to MBOX is closed.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_create (mailbox_t *PMBOX, const char *NAME)
     The function mailbox_create allocates and initializes PMBOX. The concrete mailbox type instantiate is based on the scheme of the url NAME.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          The url NAME supplied is invalid or not supported. PMBOX is NULL.

     ENOMEM
          Not enough memory to allocate resources.

 -- Function: int mailbox_create_default (mailbox_t *PMBOX, const char *NAME)
     Create a mailbox with mailbox_create () based on the environment variable $MAIL or the string formed by _PATH_MAILDIR/USER" or $LOGNAME if USER is null,

 -- Function: void mailbox_destroy (mailbox_t *PMBOX)
     Destroys and releases resources held by PMBOX.

 -- Function: int mailbox_expunge (mailbox_t MBOX)
     All messages marked for deletion are removed.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_get_folder (mailbox_t MBOX, folder_t *FOLDER)
     Get the FOLDER.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_get_debug (mailbox_t MBOX, debug_t *DEBUG)
     Get a debug object. The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

     ENOMEM

 -- Function: int mailbox_get_locker (mailbox_t MBOX, locker_t *PLOCKER)
     Return the LOCKER object.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_get_message (mailbox_t MBOX, size_t MSGNO, message_t *PMESSAGE)
     Retrieve message number MSGNO, PMESSAGE is allocated and initialized.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null or MSGNO is invalid.

     ENOMEM
          Not enough memory.

 -- Function: int mailbox_get_observable (mailbox_t mbox MBOX, observable_t*OBSERVABLE)
     Get the observable object.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

     ENOMEM
          Not enough memory.

 -- Function: int mailbox_get_property (mailbox_t MBOX, property_t *PROPERTY)
     Get the property object. The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

     ENOMEM

 -- Function: int mailbox_get_size (mailbox_t MBOX, off_t *PSIZE)
     Gives the MBOX size.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_get_stream (mailbox_t MBOX, stream_t *PSTREAM)
     The mailbox stream is put in PSTREAM.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is invalid or PSTREAM is NULL.

 -- Function: int mailbox_get_ticket (mailbox_t MBOX, ticket_t TICKET)
     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_get_url (mailbox_t MBOX, url_t *PURL)
     Gives the constructed URL.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_is_modified (mailbox_t MBOX)
     Check if the mailbox been modified by an external source.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_message_unseen (mailbox_t MBOX, size_t *PNUMBER);
     Give the number of first unseen message in MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_messages_count (mailbox_t MBOX, size_t *PNUMBER);
     Give the number of messages in MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_messages_recent (mailbox_t MBOX, size_t *PNUMBER);
     Give the number of recent messages in MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_open (mailbox_t MBOX, int FLAG)
     A connection is open, if no stream was provided, a stream is created based on the MBOX type.  The FLAG can be OR'ed. See stream_create for FLAG's description.

     The return value is 0 on success and a code number on error conditions:

     EAGAIN
     EINPROGRESS
          Operation in progress.

     EBUSY
          Resource busy.

     MU_ERROR_INVALID_PARAMETER
          MBOX is null or flag is invalid.

     ENOMEM
          Not enough memory.

 -- Function: int mailbox_scan (mailbox_t MBOX, size_t MSGNO, size_t *PCOUNT);
     Scan the mailbox for new messages starting at message MSGNO.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

     ENOMEM
          Not enough memory.

 -- Function: int mailbox_set_locker (mailbox_t MBOX, locker_t LOCKER)
     Set the type of locking done by the MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_set_stream (mailbox_t MBOX, stream_t STREAM)
     Set the STREAM connection to use for the mailbox.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX or STREAM is NULL.

 -- Function: int mailbox_set_ticket (mailbox_t MBOX, ticket_t TICKET)
     The TICKET will be set on the auth_t object on creation.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_uidnext (mailbox_t MBOX, size_t *PNUMBER);
     Give the next predicted uid for MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.

 -- Function: int mailbox_uidvalidity (mailbox_t MBOX, size_t *PNUMBER);
     Give the uid validity of MBOX.

     The return value is 0 on success and a code number on error conditions:

     MU_ERROR_INVALID_PARAMETER
          MBOX is null.