<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Folder</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="libEtPan! API"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Storages, folders, messages"
HREF="c2988.htm"><LINK
REL="PREVIOUS"
TITLE="Storage"
HREF="x3015.htm"><LINK
REL="NEXT"
TITLE="Message"
HREF="x3198.htm"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>libEtPan! API</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x3015.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 5. Storages, folders, messages</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x3198.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN3082"
>Folder</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-DRIVER"
>Folder driver</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#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);
}
</PRE
><P
> XXX - this will be implemented in the future.
</P
><P
></P
><UL
><LI
><P
> <B
CLASS="COMMAND"
>fld_get_session()</B
> will return the session
this folder should use.
</P
></LI
><LI
><P
> For other method, you should see <A
HREF="x3472.htm#MAILSESSION-DRIVER"
>the Section called <I
>Session driver</I
></A
>.
</P
></LI
></UL
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN3095"
>Folder</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#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;
};
</PRE
><P
></P
><UL
><LI
><P
> <B
CLASS="COMMAND"
>fld_pathname</B
> is the pathname specific to
the driver.
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_virtual_name</B
> is the identifier of
this folder. This can be <B
CLASS="COMMAND"
>NULL</B
>.
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_storage</B
> is the storage used for this
folder (see <A
HREF="x3015.htm#MAILSTORAGE"
>the Section called <I
>Storage</I
></A
>).
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_session</B
> is the session used for this
folder.
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_shared_session</B
> is set to 1 if the
folder use the same session as the storage. This is used
internally.
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_pos</B
> is the
position in the list of folders of the storage.
This is used internally.
</P
></LI
><LI
><P
> use of <B
CLASS="COMMAND"
>fld_parent</B
>,
<B
CLASS="COMMAND"
>fld_sibling_index</B
> and
<B
CLASS="COMMAND"
>fld_children</B
> is deprecated.
</P
></LI
><LI
><P
> <B
CLASS="COMMAND"
>fld_user_data</B
> is a field for free
use. The user can store any data in that field.
</P
></LI
></UL
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-NEW"
>mailfolder_new and mail_folder_free</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#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);
</PRE
><P
> <B
CLASS="COMMAND"
>mailfolder_new()</B
> initializes a folder
structure with an identifier
(<B
CLASS="COMMAND"
>fld_virtual_name</B
>) with path name
(<B
CLASS="COMMAND"
>fld_pathname</B
>). The folder will be owned
by the given storage (<B
CLASS="COMMAND"
>fld_storage</B
>).
</P
><P
> <B
CLASS="COMMAND"
>mailfolder_free()</B
> free the memory used
by the folder.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-CONNECT"
>mailfolder_connect and mailfolder_disconnect</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#include <libetpan/libetpan.h>
int mailfolder_connect(struct mailfolder * folder);
void mailfolder_disconnect(struct mailfolder * folder);
</PRE
><P
> <B
CLASS="COMMAND"
>mailfolder_connect()</B
> 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.
</P
><P
> <B
CLASS="COMMAND"
>mailfolder_disconnect()</B
> disconnects the
folder.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-NOOP"
>mailfolder_noop</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#include <libetpan/libetpan.h>
int mailfolder_noop(struct mailfolder * folder);
</PRE
><P
> This function will only send noop to the mail access.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-CHECK"
>mailfolder_check</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#include <libetpan/libetpan.h>
int mailfolder_check(struct mailfolder * folder);
</PRE
><P
> A call to this function will save to disk the internal state
of the selected mailbox (such as flags).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-EXPUNGE"
>mailfolder_expunge</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>#include <libetpan/libetpan.h>
int mailfolder_expunge(struct mailfolder * folder);
</PRE
><P
> A call to this function will delete all messages marked for
deletion.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-STATUS"
>mailfolder_status</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_status(struct mailfolder * folder,
uint32_t * result_messages, uint32_t * result_recent,
uint32_t * result_unseen);
</PRE
><P
> A call to this function will return some counts of messages
in the mailbox.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-APPEND-MESSAGE"
>mailfolder_append_message</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_append_message(struct mailfolder * folder,
char * message, size_t size);
</PRE
><P
> This function will store a new message in the given folder.
The message is given by a string in memory
(<B
CLASS="COMMAND"
>message</B
>) and a size
(<B
CLASS="COMMAND"
>size</B
>).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-GET-MESSAGES-LIST"
>mailfolder_get_messages_list</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_get_messages_list(struct mailfolder * folder,
struct mailmessage_list ** result);
</PRE
><P
> This function will return the list of messages in the given
folder (see <A
HREF="x3198.htm#MAILMESSAGE-LIST"
>the Section called <I
>Message list</I
></A
>).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-GET-ENVELOPES-LIST"
>mailfolder_get_envelopes_list</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_get_envelopes_list(struct mailfolder * folder,
struct mailmessage_list * result);
</PRE
><P
> This function will fill the list of parsed header fields
structure in the <B
CLASS="COMMAND"
>mailmessage</B
> structures
of the given list of messages (<B
CLASS="COMMAND"
>result</B
>).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-GET-MESSAGE"
>mailfolder_get_message</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_get_message(struct mailfolder * folder,
uint32_t num, mailmessage ** result);
</PRE
><P
> This function will return the message identified by a
message index (<B
CLASS="COMMAND"
>num</B
>)
This will return a <B
CLASS="COMMAND"
>mailmessage</B
> structure
in <B
CLASS="COMMAND"
>(* result)</B
> (see <A
HREF="x3198.htm#MAILMESSAGE"
>the Section called <I
>Message</I
></A
>).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="MAILFOLDER-GET-MESSAGE-BY-UID"
>mailfolder_get_message_by_uid</A
></H2
><PRE
CLASS="PROGRAMLISTING"
>int mailfolder_get_message_by_uid(struct mailfolder * folder,
const char * uid, mailmessage ** result);
</PRE
><P
> This function will return the message identified by a
unique identifier (<B
CLASS="COMMAND"
>uid</B
>)
This will return a <B
CLASS="COMMAND"
>mailmessage</B
> structure
in <B
CLASS="COMMAND"
>(* result)</B
> (see <A
HREF="x3198.htm#MAILMESSAGE"
>the Section called <I
>Message</I
></A
>).
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN3193"
>Example</A
></H2
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN3195"
></A
><P
><B
>Example 5-2. use of folder</B
></P
><PRE
CLASS="PROGRAMLISTING"
>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);
}
</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x3015.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x3198.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Storage</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c2988.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Message</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
