libEtPan! API
Prev | Chapter 5. Storages, folders, messages | Next

# Folder

## Folder driver

    #include <libetpan/libetpan.h>

    typedef struct mailfolder_driver mailfolder_driver;

    struct mailfolder_driver {
      int (* fld_get_session)(struct mailfolder * folder,
        mailsession ** result);

      int (* fld_noop)(struct mailfolder * folder);

      int (* fld_check)(struct mailfolder * folder);

      int (* fld_expunge)(struct mailfolder * folder);

      int (* fld_status)(struct mailfolder * folder,
        uint32_t * result_messages, uint32_t * result_recent,
        uint32_t * result_unseen);

      int (* fld_append_message)(struct mailfolder * folder,
        char * message, size_t size);

      int (* fld_get_messages_list)(struct mailfolder * folder,
        struct mailmessage_list ** result);

      int (* fld_get_envelopes_list)(struct mailfolder * folder,
        struct mailmessage_list * result);

      int (* fld_get_message)(struct mailfolder * folder,
        uint32_t num, mailmessage ** result);

      int (* fld_get_message_by_uid)(struct mailfolder * folder,
        const char * uid, mailmessage ** result);
    }

XXX - this will be implemented in the future.

- fld_get_session() will return the session this folder should use.

- For other method, you should see the Section called Session driver.

## Folder

    #include <libetpan/libetpan.h>

    struct mailfolder {
      char * fld_pathname;
      char * fld_virtual_name;

      struct mailstorage * fld_storage;

      mailsession * fld_session;
      int fld_shared_session;
      clistiter * fld_pos;

      struct mailfolder * fld_parent;
      unsigned int fld_sibling_index;
      carray * fld_children; /* array of (struct mailfolder *) */

      void * fld_user_data;
    };

- fld_pathname is the pathname specific to the driver.

- fld_virtual_name is the identifier of this folder. This can be NULL.

- fld_storage is the storage used for this folder (see the Section called Storage).

- fld_session is the session used for this folder.

- fld_shared_session is set to 1 if the folder use the same session as the storage. This is used internally.

- fld_pos is the position in the list of folders of the storage. This is used internally.

- use of fld_parent, fld_sibling_index and fld_children is deprecated.

- fld_user_data is a field for free use. The user can store any data in that field.

## mailfolder_new and mail_folder_free

    #include <libetpan/libetpan.h>

    struct mailfolder * mailfolder_new(struct mailstorage * fld_storage,
        char * fld_pathname, char * fld_virtual_name);

    void mailfolder_free(struct mailfolder * folder);

mailfolder_new() initializes a folder structure with an identifier (fld_virtual_name) with path name (fld_pathname). The folder will be owned by the given storage (fld_storage).

mailfolder_free() free the memory used by the folder.

## mailfolder_connect and mailfolder_disconnect

    #include <libetpan/libetpan.h>

    int mailfolder_connect(struct mailfolder * folder);

    void mailfolder_disconnect(struct mailfolder * folder);

mailfolder_connect() connects the folder. This function can also be used to confirm that a folder connection is valid when the folder is already connected. When doing operations with several folders, you have to be sure that this function has been called before making calls on folder.

mailfolder_disconnect() disconnects the folder.

## mailfolder_noop

    #include <libetpan/libetpan.h>

    int mailfolder_noop(struct mailfolder * folder);

This function will only send noop to the mail access.

## mailfolder_check

    #include <libetpan/libetpan.h>

    int mailfolder_check(struct mailfolder * folder);

A call to this function will save to disk the internal state of the selected mailbox (such as flags).

## mailfolder_expunge

    #include <libetpan/libetpan.h>

    int mailfolder_expunge(struct mailfolder * folder);

A call to this function will delete all messages marked for deletion.

## mailfolder_status

    int mailfolder_status(struct mailfolder * folder,
        uint32_t * result_messages, uint32_t * result_recent,
        uint32_t * result_unseen);

A call to this function will return some counts of messages in the mailbox.

## mailfolder_append_message

    int mailfolder_append_message(struct mailfolder * folder,
        char * message, size_t size);

This function will store a new message in the given folder. The message is given by a string in memory (message) and a size (size).

## mailfolder_get_messages_list

    int mailfolder_get_messages_list(struct mailfolder * folder,
        struct mailmessage_list ** result);

This function will return the list of messages in the given folder (see the Section called Message list).

## mailfolder_get_envelopes_list

    int mailfolder_get_envelopes_list(struct mailfolder * folder,
        struct mailmessage_list * result);

This function will fill the list of parsed header fields structure in the mailmessage structures of the given list of messages (result).

## mailfolder_get_message

    int mailfolder_get_message(struct mailfolder * folder,
        uint32_t num, mailmessage ** result);

This function will return the message identified by a message index (num) This will return a mailmessage structure in (* result) (see the Section called Message).

## mailfolder_get_message_by_uid

    int mailfolder_get_message_by_uid(struct mailfolder * folder,
        const char * uid, mailmessage ** result);

This function will return the message identified by a unique identifier (uid) This will return a mailmessage structure in (* result) (see the Section called Message).

## Example

Example 5-2. use of folder

    int main(void)
    {
      struct mailstorage * storage;
      int r;

      storage = mailstorage_new(NULL);

      imap_mailstorage_init(storage, "imap.my-servers.org", 0,
        NULL, CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN,
        "my-login", "my-password", 1, "/home/login/.libetpan/cache");

      r = mailstorage_connect(storage);
      if (r == MAIL_NO_ERROR) {
        struct mailfolder * folder;

        folder = mailfolder_new(storage, "INBOX", NULL);

        r = mailfolder_connect(folder);
        if (r == MAIL_NO_ERROR) {
          struct mailmessage_list * msg_list;

          mailfolder_get_messages_list(folder, &msg_list);

          /* do the things */

          mailmessage_list_free(msg_list);

          mailfolder_disconnect(folder);
        }

        mailstorage_disconnect(storage);
      }

      mailstorage_free(storage);
    }

Prev | Home | Next
Storage | Up | Message