1 files changed, 546 insertions, 0 deletions

diff --git a/libetpan/src/driver/interface/maildriver.h b/libetpan/src/driver/interface/maildriver.h
new file mode 100644
index 0000000..16e830b
--- a/dev/null
+++ b/libetpan/src/driver/interface/maildriver.h
@@ -0,0 +1,546 @@
+/*
+ * libEtPan! -- a mail stuff library
+ *
+ * Copyright (C) 2001, 2005 - DINH Viet Hoa
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. Neither the name of the libEtPan! project nor the names of its
+ *    contributors may be used to endorse or promote products derived
+ *    from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+/*
+ * $Id$
+ */
+
+#ifndef MAILDRIVER_H
+
+#define MAILDRIVER_H
+
+#include <libetpan/maildriver_types.h>
+#include <libetpan/maildriver_types_helper.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* mailsession */
+
+/*
+  mailsession_new creates a new session, using the given driver
+
+  @return the created session is returned
+*/
+
+mailsession * mailsession_new(mailsession_driver * sess_driver);
+
+/*
+  mailsession_free release the memory used by the session
+*/
+
+void mailsession_free(mailsession * session);
+
+/*
+  mailsession_parameters is used to make calls specific to the driver
+
+  @param id   is the command to send to the driver,
+           usually, commands can be found in the header of the driver
+
+  @param value is the parameter of the specific call 
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_parameters(mailsession * session,
+                           int id, void * value);
+
+/*
+  There are drivers of two kinds : stream drivers (driver that connects
+  to servers through TCP or other means of connection) and file drivers
+  (driver that are based on filesystem)
+
+  The following function can only be used by stream drivers.
+  mailsession_connect_stream connects a stream to the session
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_connect_stream(mailsession * session, mailstream * s);
+
+/*
+  The following function can only be used by file drivers.
+  mailsession_connect_path selects the main path of the session
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_connect_path(mailsession * session, char * path);
+
+/*
+  NOTE: works only on stream drivers
+
+  mailsession_starttls switches the current connection to TLS (secure layer)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_starttls(mailsession * session);
+
+/*
+  mailsession_login notifies the login and the password to authenticate
+  to the session
+
+  @param userid    the given string is only needed at this function call
+    (it will be duplicated if necessary)
+  @param password  the given string is only needed at this function call
+    (it will be duplicated if necessary)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_login(mailsession * session,
+                      char * userid, char * password);
+
+/*
+  NOTE: this function doesn't often work on filsystem drivers
+
+  mailsession_logout deconnects the session and closes the stream.
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_logout(mailsession * session);
+
+/*
+  mailsession_noop does no operation on the session, but it can be
+  used to poll for the status of the connection.
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_noop(mailsession * session);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_build_folder_name will return an allocated string with
+  that contains the complete path of the folder to create
+
+  @param session the sesion
+  @param mb is the parent mailbox
+  @param name is the name of the folder to create
+  @param result the complete path of the folder to create will be
+    stored in (* result), this name have to be freed with free()
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_build_folder_name(mailsession * session, char * mb,
+                                  char * name, char ** result);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_create_folder creates the folder that corresponds to the
+  given name
+
+  @param session the session
+  @param mb is the name of the mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_create_folder(mailsession * session, char * mb);
+
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_delete_folder deletes the folder that corresponds to the
+  given name
+
+  @param session the session
+  @param mb is the name of the mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_delete_folder(mailsession * session, char * mb);
+
+
+/*
+  mailsession_rename_folder changes the name of the folder
+
+  @param session the session
+  @param mb is the name of the mailbox whose name has to be changed
+  @param new_name is the destination name (the parent
+    of the new folder folder can be other)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_rename_folder(mailsession * session,
+                              char * mb, char * new_name);
+
+/*
+  mailsession_check_folder makes a checkpoint of the session
+  
+  @param session the session
+  
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_check_folder(mailsession * session);
+
+
+/*
+  NOTE: this function is not implemented in most drivers
+
+  mailsession_examine_folder selects a mailbox as readonly
+  
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_examine_folder(mailsession * session, char * mb);
+
+
+/*
+  mailsession_select_folder selects a mailbox
+  
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_select_folder(mailsession * session, char * mb);
+
+
+/*
+  mailsession_expunge_folder deletes all messages marked \Deleted
+  
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_expunge_folder(mailsession * session);
+
+
+/*
+  mailsession_status_folder queries the status of the folder
+  (number of messages, number of recent messages, number of unseen messages)
+  
+  @param session the session
+  @param mb mailbox to query
+  @param result_messages the number of messages is stored
+    in (* result_messages)
+  @param result_recent the number of messages is stored
+    in (* result_recent)
+  @param result_unseen the number of messages is stored
+    in (* result_unseen)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_status_folder(mailsession * session, char * mb,
+    uint32_t * result_messages, uint32_t * result_recent,
+    uint32_t * result_unseen);
+
+
+/*
+  mailsession_messages_number queries the number of messages in the folder
+
+  @param session the session
+  @param mb mailbox to query
+  @param result the number of messages is stored in (* result)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_messages_number(mailsession * session, char * mb,
+                                uint32_t * result);
+
+/*
+  mailsession_recent_number queries the number of recent messages in the folder
+
+  @param session the session
+  @param mb mailbox to query
+  @param result the number of recent messages is stored in (* result)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_recent_number(mailsession * session,
+                              char * mb, uint32_t * result);
+
+/*
+  mailsession_unseen_number queries the number of unseen messages in the folder
+
+  @param session the session
+  @param mb mailbox to query
+  @param result the number of unseen messages is stored in (* result)
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_unseen_number(mailsession * session, char * mb,
+                              uint32_t * result);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_list_folders returns the list of all sub-mailboxes
+  of the given mailbox
+
+  @param session the session
+  @param mb the mailbox
+  @param result list of mailboxes if stored in (* result),
+    this structure have to be freed with mail_list_free()
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_list_folders(mailsession * session, char * mb,
+                             struct mail_list ** result);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_lsub_folders returns the list of subscribed
+  sub-mailboxes of the given mailbox
+
+  @param session the session
+  @param mb the mailbox
+  @param result list of mailboxes if stored in (* result),
+    this structure have to be freed with mail_list_free()
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_lsub_folders(mailsession * session, char * mb,
+                             struct mail_list ** result);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_subscribe_folder subscribes to the given mailbox
+
+  @param session the session
+  @param mb the mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_subscribe_folder(mailsession * session, char * mb);
+
+/*
+  NOTE: driver's specific should be used
+
+  mailsession_unsubscribe_folder unsubscribes to the given mailbox
+
+  @param session the session
+  @param mb the mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_unsubscribe_folder(mailsession * session, char * mb);
+
+/*
+  mailsession_append_message adds a RFC 2822 message to the current
+  given mailbox
+
+  @param session the session
+  @param message is a string that contains the RFC 2822 message
+  @param size this is the size of the message
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_append_message(mailsession * session,
+                               char * message, size_t size);
+
+int mailsession_append_message_flags(mailsession * session,
+    char * message, size_t size, struct mail_flags * flags);
+
+/*
+  NOTE: some drivers does not implement this
+
+  mailsession_copy_message copies a message whose number is given to
+  a given mailbox. The mailbox must be accessible from the same session.
+
+  @param session the session
+  @param num the message number
+  @param mb the destination mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_copy_message(mailsession * session,
+                             uint32_t num, char * mb);
+
+/*
+  NOTE: some drivers does not implement this
+
+  mailsession_move_message copies a message whose number is given to
+  a given mailbox. The mailbox must be accessible from the same session.
+
+  @param session the session
+  @param num the message number
+  @param mb the destination mailbox
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_move_message(mailsession * session,
+                             uint32_t num, char * mb);
+
+/*
+  mailsession_get_messages_list returns the list of message numbers
+  of the current mailbox.
+
+  @param session the session
+  @param result the list of message numbers will be stored in (* result),
+    this structure have to be freed with mailmessage_list_free()
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_get_messages_list(mailsession * session,
+                                  struct mailmessage_list ** result);
+
+/*
+  mailsession_get_envelopes_list fills the parsed fields in the
+  mailmessage structures of the mailmessage_list.
+
+  @param session the session
+  @param result this is the list of mailmessage structures
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_get_envelopes_list(mailsession * session,
+                                   struct mailmessage_list * result);
+
+/*
+  NOTE: some drivers does not implement this
+
+  mailsession_remove_message removes the given message from the mailbox.
+  The message is permanently deleted.
+
+  @param session the session
+  @param num is the message number
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_remove_message(mailsession * session, uint32_t num);
+
+
+/*
+  NOTE: this function is not implemented in most drivers
+
+  mailsession_search_message returns a list of message numbers that
+  corresponds to the given criteria.
+
+  @param session the session
+  @param charset is the charset to use (it can be NULL)
+  @param key is the list of criteria
+  @param result the search result is stored in (* result),
+    this structure have to be freed with mail_search_result_free()
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+#if 0
+int mailsession_search_messages(mailsession * session, char * charset,
+                                struct mail_search_key * key,
+                                struct mail_search_result ** result);
+#endif
+
+/*
+  mailsession_get_message returns a mailmessage structure that corresponds
+  to the given message number.
+  * WARNING * mailsession_get_message_by_uid() should be used instead.
+
+  @param session the session
+  @param num the message number
+  @param result the allocated mailmessage structure will be stored
+    in (* result), this structure have to be freed with mailmessage_free() 
+
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_get_message(mailsession * session,
+                            uint32_t num, mailmessage ** result);
+
+/*
+  mailsession_get_message_by_uid returns a mailmessage structure
+  that corresponds to the given message unique identifier.
+  This is currently implemented only for cached drivers.
+  * WARNING * That will deprecates the use of mailsession_get_message()
+  
+  @param session the session
+  @param uid the message unique identifier
+  @param result the allocated mailmessage structure will be stored
+    in (* result), this structure have to be freed with mailmessage_free() 
+  
+  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
+    on error
+*/
+
+int mailsession_get_message_by_uid(mailsession * session,
+    const char * uid, mailmessage ** result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif