Diffstat (limited to 'kmicromail/libetpan/doc/DOCUMENTATION') (more/less context) (ignore whitespace changes)
| -rw-r--r-- | kmicromail/libetpan/doc/DOCUMENTATION | 654 |
1 files changed, 654 insertions, 0 deletions
diff --git a/kmicromail/libetpan/doc/DOCUMENTATION b/kmicromail/libetpan/doc/DOCUMENTATION new file mode 100644 index 0000000..4f66519 --- a/dev/null +++ b/kmicromail/libetpan/doc/DOCUMENTATION @@ -0,0 +1,654 @@ +1/ Introduction +--------------- + +libEtPan! is mainly a library that will handle all kind of mailbox access. +For example: IMAPrev4, POP3, NNTP, mbox, MH. + +You have two kinds of mailbox access, either using low-level functions +with a different interface for each kind of access or using higher-level +functions, using a driver to wrap the higher-level API. + + +2/ Low-level +------------ + +2.1/ IMAP4rev1 - Internet Message Access Protocol - Version 4rev1 +----------------------------------------------------------------- + +Each command of the IMAP4rev1 Standard (RFC 2060) is implemented in +the IMAP4rev1 module. Directory imap/. + +2.1.1/ References + +- RFC 2060 - INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1 +- draft-crispin-imapv-15.txt + +Not yet implemented : + +- draft-crispin-imapv-20.txt + +2.1.2/ Dependencies + +- tools/ + +2.1.3/ Files descriptions + +description of header files : +mailimap.[ch] -- functions that implements each IMAP4rev1 command +mailimap_helper.[ch] -- helper interface for the previous functions +mailimap_types.[ch] -- definition of types and constructors for these + types +mailimap_types_helper.[ch] -- contains function definitions that will help + to create data necessary to use IMAP4rev1 module +mailimap_socket.[ch] -- provides a function to connect to an + IMAP4rev1 server over TCP +mailimap_ssl.[ch] -- provides a function to connect to an + IMAP4rev1 server over TLS layer + +2.1.4/ Interface + +Include for this module is mailimap.h and includes all other headers. + + +The interface of IMAP4rev1 is documented in the following files : + +mailimap.h +mailimap_types.h +mailimap_types_helper.h + + +2.2/ POP3 - Post Office Protocol - Version 3 +-------------------------------------------- + +Each command of the POP3 Standard (RFC 1939 and RFC 2449) is implemented +in the POP3 module. Directory pop3/. + +2.1.1/ References + +- RFC 1939 - Post Office Protocol - Version 3 +- RFC 2449 - POP3 Extension Mechanism (CAPA) + +Not yet implemented : + +- RFC 1734 - POP3 AUTHentication command + +2.1.2/ Dependencies + +- tools/ + +2.2.3/ Files descriptions + +mailpop3.[ch] -- functions that implements each POP3 command +mailpop3_helper.[ch] -- helper interface for the previous functions +mailpop3_socket.[ch] -- provides a function to connect to a + POP3 server over TCP +mailpop3_ssl.[ch] -- provides a function to connect to a + POP3 server over TLS layer + +2.2.4/ Interface + +Include for this module is mailpop3.h and includes all other headers. + +There is not yet documentation for POP3 module. + + +2.3/ NNTP - Network News Transfer Protocol +------------------------------------------ + +Each command of the NNTP Standard (RFC 977 and RFC 2980) is implemented +in the NNTP module. Directory nntp/. + +2.3.1/ References + +- RFC 977 - Network News Transfer Protocol +- RFC 2980 - Common NNTP Extensions + +Not yet implemented : + +- RFC 1036 - Standard for Interchange of USENET Messages +- son of RFC 1036 : FTP://zoo.toronto.edu/pub/news.txt.Z + +2.3.2/ Dependencies + +- tools/ + +2.3.3/ Files descriptions + +newsnntp.[ch] -- functions that implements each NNTP command +newsnntp_socket.[ch] -- provides a function to connect to a + NNTP server over TCP +newsnntp_ssl.[ch] -- provides a function to connect to a + POP3 server over TLS layer + +2.3.4/ Interface + +Include for this module is newsnntp.h and includes all other headers. + +There is not yet documentation for NNTP module. + + +2.4/ mbox +--------- + +The mbox module provides a set of functions to manipulate mbox mailboxes. +These functions make a safe lock on the mailbox they work with. +This module will assign to each message a unique message identifier +so that we can work with message numbers in mbox files without other +programs interfer. +Directory mbox/. + +2.4.1/ References + +- http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html +- http://www.qmail.org/qmail-manual-html/man5/mbox.html + +2.4.2/ Dependencies + +- tools/ +- imf/ + +2.5.3/ Specific to libEtPan! + +- "X-LibEtPan-UID" header + +2.5.4/ Files descriptions + +mailmbox.[ch] -- functions to manipulate mbox mailboxes. +mailmbox_parse.[ch] -- this module is in charge of parsing the + mbox file content +mailmbox_types.[ch] -- definition of types and constructors for these + types + +2.4.5/ Interface + +Include for this module is mailmbox.h and includes all other headers. + +There is not yet documentation for mbox module. + + +2.5/ MH +------- + +The MH module provides a set of functions to manipulate MH mailboxes. +Directory mh/. + +2.5.1/ References + +- almost none + +2.5.2/ Dependencies + +- tools/ + +2.5.3/ Files descriptions + +mailmh.[ch] -- functions to manipulate MH mailboxes. + + +2.5.4/ Interface + +Include for this module is mailmh.h. + +There is not yet documentation for MH module. + + +2.6/ IMF - Internet Message Format +---------------------------------- + +The IMF module provides functions to parse data given in RFC 2822 +format (Internet Message Format). +Directory imf/. + +2.6.1/ References + +- RFC 2822 - Internet Message Format (Not entirely implemented) +- RFC 2076 - Common Internet Message Headers + +Not yet implemented : + +- RFC 2298 - An Extensible Message Format + for Message Disposition Notifications + +2.6.2/ Dependencies + +- tools/ + +2.6.3/ Files descriptions + +mailimf.[ch] -- functions to parse RFC 2822 messages. +mailimf_types.[ch] -- definition of types and constructors for these + types +mailimf_types_helper.[ch] -- contains function definitions that will help + to create data necessary to use IMF module. +mailimf_write.[ch] -- functions that output RFC 2822 messages or + sub-part of the messages in a (FILE *). + +2.6.4/ Interface + +Include for this module is mailimf.h and includes all other headers. + +The interface of IMAP4rev1 is documented in the following files : + +mailimf.h +mailimf_types.h +mailimf_types_helper.h +mailimf_write.h + + +2.7/ MIME - Multipurpose Internet Mail Extensions +------------------------------------------------- + +The MIME module provides functions to parse structure of MIME messages. +Directory mime/. + +2.7.1/ References + +- RFC 2045 - Multipurpose Internet Mail Extensions (MIME) Part One: Format of + Internet Message Bodies. +- RFC 2047 - MIME (Multipurpose Internet Mail Extensions) Part Three: Message + Header Extensions for Non-ASCII Text. +- RFC 2183 - Communicating Presentation Information in Internet Messages: + The Content-Disposition Header Field + +Not implemented : + +- RFC 2046 - Multipurpose Internet Mail Extensions (MIME) Part Two: Media + Types. + +2.7.2/ Dependencies + +- tools/ +- imf/ + +2.7.3/ Files descriptions + +mailmime.[ch] -- functions to parse the MIME fields (RFC 2045). +mailmime_content.[ch] -- functions to parse the MIME message. You get + the different parts and you can decode them. +mailmime_decode.[ch] -- functions to parse the MIME-encoded fields. +mailmime_disposition.[ch] -- functions to parse the Content-Disposition field + (RFC 2183) +mailmime_types.[ch] -- definition of types and constructors for these + types +mailmime_types_helper.[ch] -- contains function definitions that will help + to create data necessary to use MIME module. +mailmime_write.[ch] -- functions that output MIME messages or + sub-part of the messages in a (FILE *). + +2.7.4/ Interface + +Include for this module is mailmime.h and includes all other headers. + +There is not yet documentation for MIME module. + + +2.8/ SMTP - Simple Mail Transfer Protocol +----------------------------------------- + +Each command of the SMTP Standard (RFC 2821 and RFC 1891) is implemented +in the SMTP module. Directory smtp/. + +2.8.1/ References + +- RFC 2821 - Simple Mail Transfer Protocol (Not entirely implemented) +- RFC 1891 - SMTP Service Extension for Delivery Status Notifications + +2.8.2/ Depencencies + +- tools/ + +2.8.3/ Files descriptions + +mailsmtp.[ch] -- functions that implements each SMTP command +mailsmtp_helper.[ch] -- functions to get an easier use of SMTP module +mailsmtp_socket.[ch] -- provides a function to connect to a + SMTP server over TCP +mailsmtp_ssl.[ch] -- provides a function to connect to a + SMTP server over TLS layer +mailsmtp_types.h -- definition of types + +2.8.4/ Interface + +Include for this module is mailsmtp.h and includes all other headers. + +There is not yet documentation for MIME module. + + +2.9/ Miscellaneous + +2.9.1/ References + +- RFC 2234 - Augmented BNF for Syntax Specifications: ABNF +- RFC 2595 - Using TLS with IMAP, POP3 and ACAP + +2.9.2/ Tools + +tools/ directory contains some tools functions and useful data structures. + +alloc.h -- a wrapper on malloc() +carray.[ch] -- an array, that grows automatically when elements + are added. +charconv.[ch] -- character set converter. For example, it will + translate an iso-8859-1 string to an utf-8 string. +chash.[ch] -- a hash table which keys can be anything +cinthash.[ch] -- a hash table which keys are integers + (should be removed and replaced with chash) +clist.[ch] -- a double-linked list +connect.[ch] -- easy interface to connect a TCP server +hmac_md5.h +md5.[ch] +md5global.h -- MD5 calculation +mail.h -- some constants +maildb_helper.[ch] -- wrappers to DB 2.x 3.x or 4.x +maillock.[ch] -- safely lock a given file +mailstream.[ch] -- stream interface - buffered reading and writing + on files/socket/SSL connection +mailstream_helper.[ch] -- useful functions for stream + (for example: read a line) +mailstream_low.[ch] -- driver interface for a stream +mailstream_socket.[ch] -- stream driver for file descriptors (includes socket) +mailstream_ssl.[ch] -- stream driver for SSL connection +mailstream_types.h -- data structure definition +mapping.[ch] -- map parts of files in memory (no more used) +mmapstring.[ch] -- a string, that grows automatically when data + are added. + + +3/ Higher-level +--------------- + +The higher level will allow us to query folder informations or to get +messages information or content. + +There is four kinds of identities : +- storage +- folders +- session +- messages + +In the higher-level interface, you manipulate data types from IMF and +MIME module, plus additionnal data types of higher-level. + + +3.1/ Objects +------------ + +3.1.1/ Storage + +A storage (struct mail_storage) represents whether a server or +a main path, It can be an IMAP server, the root path of a MH or a mbox file. + + +3.1.2/ Folders + +A folder can be created from a storage. +Folders (struct mail_folder) are the mailboxes we can choose in the +server or as sub-folder of the main path. + +Folders for IMAP are the IMAP mailboxes, for MH this is one of the +folder of the MH storage, for mbox, there is only one folder, the +mbox file content; + + +3.1.3/ Session + +Storage and folders communicate with the lower-layer through the +mail session data structure. + +A mail session (struct mailsession) is a mail access to a server +or a mail access in the local file system. It allow us to send commands +to the mail access. + +A mail storage is using a mail session to communicate. +A folder folder also uses a mail session to get information or to send +information. It can be the same session or not, depdending of the +implementation. + + +3.1.4/ Messages + +From a session, we can get a message (struct mailmessage) to read. + + +3.2/ Drivers +------------ + +For a mail access, three drivers exist. +One for storage, one for session, one for message. +Note that the folder access rely only on session driver. + + +3.2.1/ storage driver interface + + mail_storage_driver is the driver structure for mail storage + + - name is the name of the driver + + - connect() connects the storage to the remote access or to + the path in the local filesystem. + + - get_folder() can have two kinds of behaviour. + Either it creates a new session and independant from the session + used by the storage and select the given mailbox or + it selects the given mailbox in the current session. + It depends on the efficiency of the mail driver. + + - free_data() frees the data created with mail_storage constructor. + + a constructor for each kind of access has to be implemented. + + +3.2.2/ session driver interface + + maildriver is the driver structure for mail sessions + + - name is the name of the driver + + - initialize() is the function that will initializes a data structure + specific to the driver, it returns a value that will be stored + in the field data of the session. + The field data of 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(). + + - uninitialize() frees the structure created with initialize() + + - parameters() implements functions specific to the given mail access + + - connect_stream() connects a stream to the session + + - connect_path() notify a main path to the session + + - starttls() changes the current stream to a TLS stream + + - login() notifies the user and the password to authenticate to the + session + + - logout() exits the session and closes the stream + + - noop() does no operation on the session, but it can be + used to poll for the status of the connection. + + - check_folder() makes a checkpoint of the session + + - select_folder() selects a mailbox + + - expunge_folder() deletes all messages marked \Deleted + + - status_folder() queries the status of the folder + (number of messages, number of recent messages, number of + unseen messages) + + - append_message() adds a RFC 2822 message to the current + given mailbox + + - get_messages_list() returns the list of message numbers + of the current mailbox. + + - get_envelopes_list() fills the parsed fields in the + mailmessage structures of the mail_envelopes_list. + + - remove_message() removes the given message from the mailbox. + The message is permanently deleted. + + - get_message returns a mailmessage structure that corresponds + to the given message number. + + +3.2.3/ message driver interface + + mailmessage_driver is the driver structure to get information from messages. + + - name is the name of the driver + + - initialize() is the function that will initializes a data structure + specific to the driver, it returns a value that will be stored + in the field data of the mailsession. + The field data of the session is the state of the session, + the internal data structure used by the driver. + It is called when initializing the mailmessage structure with + mailmessage_init(). + + - uninitialize() frees the structure created with initialize(). + It will be called by mailmessage_free(). + + - flush() will free from memory all temporary structures of the message + (for example, the MIME structure of the message). + + - fetch_result_free() will free all strings resulted by fetch() or + any fetch_xxx() functions that returns a string. + + - fetch() returns the content of the message (headers and text). + + - fetch_header() returns the content of the headers. + + - fetch_body() returns the message text (message content without headers) + + - fetch_size() returns the size of the message content. + + - get_bodystructure() returns the MIME structure of the message. + + - fetch_section() returns the content of a given MIME part + + - fetch_section_header() returns the header of the message + contained by the given MIME part. + + - fetch_section_mime() returns the MIME headers of the + given MIME part. + + - fetch_section_body() returns the text (if this is a message, this is the + message content without headers) of the given MIME part. + + - fetch_envelope() returns a mailimf_fields structure, with a list of + fields chosen by the driver. + + - get_flags() returns a the flags related to the message. + When you want to get flags of a message, you have to make sure to + call get_flags() at least once before using directly message->flags. + + +3.3/ Higher level interface +--------------------------- + +3.3.1/ Files descriptions + +generic_cache.[ch] -- functions that implements cache and + flags storing mechanism +imapdriver.[ch] -- IMAP driver for session +imapdriver_cached.[ch] -- IMAP driver for session, using cache, + IMAP already has flags. +imapdriver_cached_message.[ch] -- IMAP driver for message, using cache + IMAP already has flags. +imapdriver_message.[ch] -- IMAP driver for message +imapdriver_types.[ch] -- tools function for IMAP driver (types + conversion from IMAP module). +imapstorage.[ch] -- IMAP driver for storage +imfcache.[ch] -- implements cache for parsed fields +libetpan.h -- includes all necessary header files to + use libEtPan! +maildriver.[ch] -- wrappers to calls to the session driver +maildriver_tools.[ch] -- default implementation for drivers, + when the driver does not parse the + messages. +maildriver_types.[ch] -- data types declaration and constructors +maildriver_types_helper.[ch] -- easy data creation +mailmessage.[ch] -- wrappers to calls to the message driver +mailstorage.[ch] -- storage creation, calls to the storage + driver and implementation of folders. +mailstorage_tools.[ch] -- tools for storage (connection) +mailthread.[ch] -- threading: collection of the mails + into a treee +mboxdriver.[ch] -- mbox driver for session +mboxdriver_cached.[ch] -- mbox driver for session, using flags + and cache +mboxdriver_cached_message.[ch] -- mbox driver for message, using flags + and cache +mboxdriver_message.[ch] -- mbox driver for message +mboxdriver_tools.[ch] -- mbox driver common functions +mboxstorage.[ch] -- mbox driver for storage +mhdriver.[ch] -- MH driver for session +mhdriver_cached.[ch] -- MH driver for session, using flags + and cache +mhdriver_cached_message.[ch] -- MH driver for message, using flags + and cache. +mhdriver_message.[ch] -- MH driver for message +mhdriver_tools.[ch] -- MH driver common functions +mhstorage.[ch] -- MH driver for storage +nntpdriver.[ch] -- NNTP driver for session +nntpdriver_cached.[ch] -- NNTP driver for session, using flags + and cache +nntpdriver_cached_message.[ch] -- NNTP driver for message, using flags + and cache +nntpdriver_message.[ch] -- NNTP driver for message +nntpdriver_tools.[ch] -- NNTP driver common functions +nntpstorage.[ch] -- NNTP driver for storage +pop3driver.[ch] -- POP3 driver for session +pop3driver_cached.[ch] -- POP3 driver for session, using flags + and cache +pop3driver_cached_message.[ch] -- POP3 driver for message, using flags + and cache +pop3driver_message.[ch] -- POP3 driver for message +pop3driver_tools.[ch] -- POP3 driver common functions +pop3storage.[ch] -- POP3 driver for storage + + +3.3.2/ Interfaces + +Include for this module is libetpan.h and includes all other headers. + + +The interface of higher layer is documented in the following files : + +maildriver.h +maildriver_types.h +maildriver_types_helper.h +mailmessage.h +mailstorage.h +mailstorage_types.[h] +mailthread.h + + +4/ Architecture +--------------- + +(see layer.fig) + + +5/ Example of use +----------------- + +You can find some example in tests/ + + +6/ Constraints +-------------- + +- libEtPan! must run on a system where mmap() is available. + +- for mbox particularly, libEtPan! make assumption on the fact that a + file can be entirely mapped into memory. But if you don't read + mailboxes of 1 Go, it should be fine. + + + |