path: root/libetpan/include/libetpan/maildriver.h

/*
 * 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