Session

Session driver

#include <libetpan/libetpan.h>

struct mailsession_driver {
  char * sess_name;

  int (* sess_initialize)(mailsession * session);
  void (* sess_uninitialize)(mailsession * session);

  int (* sess_parameters)(mailsession * session,
      int id, void * value);

  int (* sess_connect_stream)(mailsession * session, mailstream * s);
  int (* sess_connect_path)(mailsession * session, char * path);

  int (* sess_starttls)(mailsession * session);

  int (* sess_login)(mailsession * session, char * userid, char * password);
  int (* sess_logout)(mailsession * session);
  int (* sess_noop)(mailsession * session);

  /* folders operations */

  int (* sess_build_folder_name)(mailsession * session, char * mb,
      char * name, char ** result);

  int (* sess_create_folder)(mailsession * session, char * mb);
  int (* sess_delete_folder)(mailsession * session, char * mb);
  int (* sess_rename_folder)(mailsession * session, char * mb,
      char * new_name);
  int (* sess_check_folder)(mailsession * session);
  int (* sess_examine_folder)(mailsession * session, char * mb);
  int (* sess_select_folder)(mailsession * session, char * mb);
  int (* sess_expunge_folder)(mailsession * session);
  int (* sess_status_folder)(mailsession * session, char * mb,
      uint32_t * result_num, uint32_t * result_recent,
      uint32_t * result_unseen);
  int (* sess_messages_number)(mailsession * session, char * mb,
      uint32_t * result);
  int (* sess_recent_number)(mailsession * session, char * mb,
      uint32_t * result);
  int (* sess_unseen_number)(mailsession * session, char * mb,
      uint32_t * result);

  int (* sess_list_folders)(mailsession * session, char * mb,
      struct mail_list ** result);
  int (* sess_lsub_folders)(mailsession * session, char * mb,
      struct mail_list ** result);

  int (* sess_subscribe_folder)(mailsession * session, char * mb);
  int (* sess_unsubscribe_folder)(mailsession * session, char * mb);

  /* messages operations */

  int (* sess_append_message)(mailsession * session,
      char * message, size_t size);
  int (* sess_copy_message)(mailsession * session,
      uint32_t num, char * mb);
  int (* sess_move_message)(mailsession * session,
      uint32_t num, char * mb);

  int (* sess_get_message)(mailsession * session,
      uint32_t num, mailmessage ** result);

  int (* sess_get_message_by_uid)(mailsession * session,
      const char * uid, mailmessage ** result);
  
  int (* sess_get_messages_list)(mailsession * session,
      struct mailmessage_list ** result);
  int (* sess_get_envelopes_list)(mailsession * session,
      struct mailmessage_list * env_list);
  int (* sess_remove_message)(mailsession * session, uint32_t num);
};
        

This is a driver for a session.

• sess_name is the name of the driver.

• sess_initialize() is the function that will initializes a data structure (field sess_data in the session) specific to the driver. The field data (field sess_data in the session) is the state of the session, the internal data structure used by the driver. It is called when creating the mailsession structure with mailsession_new().

• sess_uninitialize() frees the structure created with sess_initialize()

• sess_parameters() implements functions specific to the given mail access.

• sess_connect_stream() connects a stream to the session.

• sess_connect_path() notify a main path to the session.

• sess_starttls() changes the current stream to a TLS stream (see the Section called TLS stream in Chapter 2).

• sess_login() notifies the user and the password to authenticate to the session.

• sess_logout() exits the session and closes the stream.

• sess_noop() does no operation on the session, but it can be used to poll for the status of the connection.

• sess_build_folder_name() will return an allocated string with that contains the complete path of the folder to create. Use of this method is deprecated.

• sess_create_folder() creates the folder that corresponds to the given name. Use of this method is deprecated.

• sess_delete_folder() deletes the folder that corresponds to the given name. Use of this method is deprecated.

• sess_rename_folder() change the name of the folder. Use of this method is deprecated.

• sess_check_folder() makes a checkpoint of the session.

• sess_examine_folder() selects a mailbox as readonly. Use of this method is deprecated.

• sess_select_folder() selects a mailbox.

• sess_expunge_folder() deletes all messages marked \Deleted.

• sess_status_folder() queries the status of the folder (number of messages, number of recent messages, number of unseen messages).

• sess_messages_number() queries the number of messages in the folder.

• sess_recent_number() queries the number of recent messages in the folder.

• sess_unseen_number() queries the number of unseen messages in the folder.

• sess_list_folders() returns the list of all sub-mailboxes of the given mailbox. Use of this method is deprecated.

• sess_lsub_folders() returns the list of subscribed sub-mailboxes of the given mailbox. Use of this method is deprecated.

• sess_subscribe_folder() subscribes to the given mailbox. Use of this method is deprecated.

• sess_unsubscribe_folder() unsubscribes to the given mailbox. Use of this method is deprecated.

• sess_append_message() adds a RFC 2822 message to the current given mailbox.

• sess_copy_message() copies a message whose number is given to a given mailbox. The mailbox must be accessible from the same session. Use of this method is deprecated.

• sess_move_message() moves a message whose number is given to a given mailbox. The mailbox must be accessible from the same session. Use of this method is deprecated.

• sess_get_messages_list() returns the list of message numbers of the current mailbox (see the Section called Message list).

• sess_get_envelopes_list() fills the parsed fields in the mailmessage structures (see the Section called Message) of the mailmessage_list (see the Section called Message list).

• sess_remove_message() removes the given message from the mailbox. The message is permanently deleted. Use of this method is deprecated.

• sess_get_message() returns a mailmessage structure (see the Section called Message) that corresponds to the given message number. Use of this method is deprecated.

• sess_get_message_by_uid() returns a mailmessage structure (see the Section called Message) that corresponds to the given message unique identifier.

mandatory functions are the following :

• sess_connect_stream() or connect_path()

• sess_logout()

• sess_get_messages_list()

• sess_get_envelopes_list()

we advise you to implement these functions :

• sess_select_folder() (in case a session can access several folders).

• sess_noop() (to check if the server is responding)

• sess_check_folder() (to make a checkpoint of the session)

• sess_status_folder(), sess_messages_number(), sess_recent_number(), sess_unseen_number() (to get stat of the folder)

• sess_append_message() (but can't be done in the case of POP3 at least).

• sess_login() in a case of an authenticated driver.

• sess_starttls() in a case of a stream driver, if the procotol supports STARTTLS.

• sess_get_message_by_uid() so that the application can remember the messages by UID and build its own list of messages.

• Everything that is specific to the driver will be implemented in sess_parameters().

Session

#include <libetpan/libetpan.h>

struct mailsession {
  void * sess_data;
  mailsession_driver * sess_driver;
};

mailsession * mailsession_new(mailsession_driver * sess_driver);

void mailsession_free(mailsession * session);
        

This is a session. This is an abstraction used to access the storage, using the network or the filesystem.

• sess_data is the state of the session. This is specific to the driver.

• sess_driver is the driver of the session.

mailsession_new() will create a new session using the given driver (sess_driver).

mailsession_free() will release the memory used by the session.

mailsession_parameters

#include <libetpan/libetpan.h>

int mailsession_parameters(mailsession * session,
			   int id, void * value);
        

This function make calls specific to the driver

mailsession_connect_stream

#include <libetpan/libetpan.h>

int mailsession_connect_stream(mailsession * session, mailstream * s);
        

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) This function can only be used by stream drivers and this connects a stream to the session

mailsession_connect_path

#include <libetpan/libetpan.h>

int mailsession_connect_path(mailsession * session, char * path);
        

This function can only be used by file drivers and selects the main path of the session.

mailsession_starttls

#include <libetpan/libetpan.h>

int mailsession_starttls(mailsession * session);
        

This switches the current connection to TLS (secure layer). This will only work with stream drivers.

mailsession_login

#include <libetpan/libetpan.h>

int mailsession_login(mailsession * session,
		      char * userid, char * password);
        

This notifies the login and the password to authenticate to the session.

mailsession_logout

#include <libetpan/libetpan.h>

int mailsession_logout(mailsession * session);
        

This function disconnects the session and closes the stream.

mailsession_noop

#include <libetpan/libetpan.h>

int mailsession_noop(mailsession * session);
        

This function does no operation on the session, but it can be used to poll for the status of the connection.

mailsession_check_folder

#include <libetpan/libetpan.h>

int mailsession_check_folder(mailsession * session);
        

This function makes a checkpoint of the session.

mailsession_select_folder

#include <libetpan/libetpan.h>

int mailsession_select_folder(mailsession * session, char * mb);
        

This function selects a mailbox.

mailsession_expunge_folder

#include <libetpan/libetpan.h>

int mailsession_expunge_folder(mailsession * session);
        

This function deletes all messages marked for deletion.

mailsession_status_folder

#include <libetpan/libetpan.h>

int mailsession_status_folder(mailsession * session, char * mb,
    uint32_t * result_messages, uint32_t * result_recent,
    uint32_t * result_unseen);
        

This function queries the status of the folder (number of messages, number of recent messages, number of unseen messages).

mailsession_messages_number

#include <libetpan/libetpan.h>

int mailsession_messages_number(mailsession * session, char * mb,
				uint32_t * result);
        

This function queries the number of messages in the folder.

mailsession_recent_number

#include <libetpan/libetpan.h>

int mailsession_recent_number(mailsession * session,
			      char * mb, uint32_t * result);
        

This function queries the number of recent messages in the folder.

mailsession_unseen_number

#include <libetpan/libetpan.h>

int mailsession_unseen_number(mailsession * session, char * mb,
			      uint32_t * result);
        

This function queries the number of unseen messages in the folder.

mailsession_append_message

#include <libetpan/libetpan.h>

int mailsession_append_message(mailsession * session,
			       char * message, size_t size);
        

This adds a RFC 2822 message to the current mailbox.

mailsession_get_messages_list

#include <libetpan/libetpan.h>

int mailsession_get_messages_list(mailsession * session,
				  struct mailmessage_list ** result);
        

This function returns the list of messages of the current mailbox.

mailsession_get_envelopes_list

#include <libetpan/libetpan.h>

int mailsession_get_envelopes_list(mailsession * session,
				   struct mailmessage_list * result);
        

This function fills the parsed fields in the mailmessage structures (see the Section called Message) of the mailmessage_list (see the Section called Message list).

mailsession_get_message

#include <libetpan/libetpan.h>

int mailsession_get_message(mailsession * session,
			    uint32_t num, mailmessage ** result);
        

This function returns a mailmessage (see the Section called Message) structure that corresponds to the given message number.

mailsession_get_message_by_uid

#include <libetpan/libetpan.h>

int mailsession_get_message_by_uid(mailsession * session,
    const char * uid, mailmessage ** result);
        

This function returns a mailmessage structure that corresponds to the given message unique identifier. This is currently implemented only for cached drivers.