4.1.2 Mailbox

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