Go to the first, previous, next, last section, table of contents.

Mbox

/* Prefix mbox_ is reserved */
#include <mailutils/mbox.h>

The most common mailbox format on UNIX platform is mbox. Mbox file is messages separated by the special format string.

   From SP envelope-sender SP date [SP moreinfo]

"From "

is sometimes call the From_.

envelope-sender

is a word with no space.

date

has the same format as asctime ()

moreinfo

are optional values that are seldom used.

A mbox_t is created, initialized and destroyed by mbox_create () and mbox_destroy (). When opening, mbox_open () will do a quick check to see if the format is a valid format or an empty file. The scanning of the mailbox is done by mbox_scan (). The function, mbox_scan (), takes callback functions called during the scanning to provide information. The scanning will cache some of the headers fields for speed. Closing the mailbox, mbox_close () will free any resources like, headers cache, locks etc ... All the messages with attributes marked deleted will only be removed on mbox_expunge (). If only the attributes need to be save but the messages not removed, this can be done by mbox_save_attributes (). New messages are added with mbox_append (). Attributes are saved in the Status: header field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.

Initialization

Function: int mbox_create (mbox_t *mbox)

Allocate and initialize a mbox handle.

MU_ERROR_NO_MEMORY

MU_ERROR_INVALID_PARAMETER

Function: void mbox_destroy (mbox_t mbox)

When a POP3 session is finished, the structure must be free ()'ed to reclaim memory.

Carrier

Function: int mbox_set_carrier (mbox_t, stream_t carrier);

Another type of stream can be provided to work on, the carrier is set in the mbox_t handle. Any previous carrier stream in the handle, will be close and release. Since the parsing code maintain only the offsets off the message the carrier stream must be seekable.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_carrier (mbox_t, stream_t *carrier);

Return the mbox_t carrier. If none was set, a new file stream will be created.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_open (mbox_t, const char *filename, int flags)

Open carrier stream with filename and flags. The stream will be quickly examine to see if it is a mbox format.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

MU_ERROR_NO_ENTRY

MU_ERROR_NO_ACCESS

MU_ERROR_NOT_SUPPORTED

Function: int mbox_close (mbox_t)

Close the carrier stream and resources particular to the mailbox.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_uidnext (mbox_t, unsigned long *uidnext)

Return the uidnext, if the mbox_t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER

same as mbox_scan ()

Function: int mbox_uidvalidity (mbox_t, unsigned long *uidvalidity)

Return the uidvalidity, if the mbox_t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER

same as mbox_scan ()

Function: int mbox_get_attribute (mbox_t, unsigned int msgno, attribute_t *attribute)

Return an attribute to indicate the status of message number msgno.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_get_separator (mbox_t, unsigned int msgno, char **sep)

Return an allocated string in sep containing the value "From " separating each message in Unix mbox format. The string should be free ()ed by the caller.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_set_separator (mbox_t, unsigned int msgno, const char *sep)

The variable sep should contain a valid "From " separator that will be use when the expunging.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_get_hstream (mbox_t, unsigned int msgno, stream_t *stream)

Return a stream to read the header of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_set_hstream (mbox_t, unsigned int msgno, stream_t stream)

Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_hsize (mbox_t, unsigned int msgno, unsigned int *size)

Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_hlines (mbox_t, unsigned int msgno, unsigned int *size)

Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_bstream (mbox_t, unsigned int msgno, stream_t *stream)

Return a stream to read the body of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_NO_MEMORY

Function: int mbox_set_bstream (mbox_t, unsigned int msgno, stream_t stream)

Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_bsize (mbox_t, unsigned int msgno, unsigned int *size)

Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_blines (mbox_t, unsigned int msgno, unsigned int *size)

Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_size (mbox_t, unsigned int *size)

Return the size of mailbox.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_save (mbox_t)

Save the changes to the messages back to the mailbox, but do not remove messages mark for deletion in the process.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_mak_deleted (mbox_t, unsigned int msgno)

Mark msgno for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_unmak_deleted (mbox_t, unsigned int msgno)

Unmark msgno if it was marked for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_expunge (mbox_t)

Save the changes to the mailbox and in the process remove all messages marked for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_append (mbox_t, const char *sep, stream_t stream)

Append to the mailbox an rfc822 message represented by stream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_append_hb (mbox_t, const char *sep, stream_t hstream, stream_t bstream)

Append to the mailbox an rfc822 message represented by a header, hstream, and a body, bstream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_scan (mbox_t, unsigned int start, unsigned int *count)

Start scanning the mailbox for new messages. The variable start can be a message number starting point. The result of the scanning will be in count. The scanning will trigger the mbox_newmsg_cb() callback for each new message and mbox_progress_cb () at different interval to notify progression. The return values of the those callback should be 0 is different then 0 the scanning will be stop an the function returns MU_ERROR_INTERRUPTED.

MU_ERROR_INVALID_PARAMETER

MU_ERROR_INTERRUPTED

MU_ERROR_NO_MEMORY

Function: int mbox_set_progress_cb (mbox_t, int (*callback) (int, void *)), void *arg)

Set the callback function for progress. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_newmsg_cb (mbox_t, int (*callback) (int, void *)), void *arg)

Set the callback function for new messages. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

Go to the first, previous, next, last section, table of contents.