691 lines
12 KiB
HTML
691 lines
12 KiB
HTML
<!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
|
|
> |