/* 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_create (mailbox_t *mbox, const char *name)

The function mailbox_create allocates and initializes mbox. 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_ERR_OUT_PTR_NULL

The pointer mbox supplied is NULL.

MU_ERR_NO_HANDLER

The url name supplied is invalid or not supported.

EINVAL

ENOMEM

Not enough memory to allocate resources.

— Function: int mailbox_create_default (mailbox_t *mbox, 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 *mbox)

Destroys and releases resources held by mbox.

— 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_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_flush (mailbox_t mbox, int expunge)

— 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_set_folder (mailbox_t mbox, folder_t folder)

— Function: int mailbox_uidvalidity (mailbox_t mbox, unsigned long *number);

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.

— Function: int mailbox_uidnext (mailbox_t mbox, size_t *number);

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_get_message (mailbox_t mbox, size_t msgno, message_t *message)

Retrieve message number msgno, message 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_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_messages_count (mailbox_t mbox, size_t *number);

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 *number);

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_message_unseen (mailbox_t mbox, size_t *number);

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_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_save_attributes (mailbox_t mbox)

— Function: int mailbox_get_size (mailbox_t mbox, off_t *size)

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_is_updated (mailbox_t mbox)

— Function: int mailbox_scan (mailbox_t mbox, size_t msgno, size_t *count);

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_get_stream (mailbox_t mbox, stream_t *stream)

The mailbox stream is put in stream.

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

MU_ERROR_INVALID_PARAMETER

mbox is invalid or stream 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_get_locker (mailbox_t mbox, locker_t *locker)

Get the locker_t 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_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_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_url (mailbox_t mbox, url_t *url)

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_has_debug (mailbox_t mbox)

— Function: int mailbox_get_debug (mailbox_t mbox, mu_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_set_debug (mailbox_t mbox, mu_debug_t debug)

— 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_lock (mailbox_t mbox)

— Function: int mailbox_unlock (mailbox_t mbox)