summaryrefslogtreecommitdiffabout
path: root/kmicromail/libetpan/doc/DOCUMENTATION
authorzautrix <zautrix>2004-07-03 16:33:12 (UTC)
committer zautrix <zautrix>2004-07-03 16:33:12 (UTC)
commite3b89230f065c48c84b48c88edb6eb088374c487 (patch) (unidiff)
tree162ea2ef909a6f82ccfcedf45d80d6c821174912 /kmicromail/libetpan/doc/DOCUMENTATION
parent2dd6ac0b2d24c91d35ce674a6c26351352df2b15 (diff)
downloadkdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.zip
kdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.tar.gz
kdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.tar.bz2
Initial revision
Diffstat (limited to 'kmicromail/libetpan/doc/DOCUMENTATION') (more/less context) (ignore whitespace changes)
-rw-r--r--kmicromail/libetpan/doc/DOCUMENTATION654
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 @@
11/ Introduction
2---------------
3
4libEtPan! is mainly a library that will handle all kind of mailbox access.
5For example: IMAPrev4, POP3, NNTP, mbox, MH.
6
7You have two kinds of mailbox access, either using low-level functions
8with a different interface for each kind of access or using higher-level
9functions, using a driver to wrap the higher-level API.
10
11
122/ Low-level
13------------
14
152.1/ IMAP4rev1 - Internet Message Access Protocol - Version 4rev1
16-----------------------------------------------------------------
17
18Each command of the IMAP4rev1 Standard (RFC 2060) is implemented in
19the IMAP4rev1 module. Directory imap/.
20
212.1.1/ References
22
23- RFC 2060 - INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
24- draft-crispin-imapv-15.txt
25
26Not yet implemented :
27
28- draft-crispin-imapv-20.txt
29
302.1.2/ Dependencies
31
32- tools/
33
342.1.3/ Files descriptions
35
36description of header files :
37mailimap.[ch] -- functions that implements each IMAP4rev1 command
38mailimap_helper.[ch] -- helper interface for the previous functions
39mailimap_types.[ch] -- definition of types and constructors for these
40 types
41mailimap_types_helper.[ch] -- contains function definitions that will help
42 to create data necessary to use IMAP4rev1 module
43mailimap_socket.[ch] -- provides a function to connect to an
44 IMAP4rev1 server over TCP
45mailimap_ssl.[ch] -- provides a function to connect to an
46 IMAP4rev1 server over TLS layer
47
482.1.4/ Interface
49
50Include for this module is mailimap.h and includes all other headers.
51
52
53The interface of IMAP4rev1 is documented in the following files :
54
55mailimap.h
56mailimap_types.h
57mailimap_types_helper.h
58
59
602.2/ POP3 - Post Office Protocol - Version 3
61--------------------------------------------
62
63Each command of the POP3 Standard (RFC 1939 and RFC 2449) is implemented
64in the POP3 module. Directory pop3/.
65
662.1.1/ References
67
68- RFC 1939 - Post Office Protocol - Version 3
69- RFC 2449 - POP3 Extension Mechanism (CAPA)
70
71Not yet implemented :
72
73- RFC 1734 - POP3 AUTHentication command
74
752.1.2/ Dependencies
76
77- tools/
78
792.2.3/ Files descriptions
80
81mailpop3.[ch] -- functions that implements each POP3 command
82mailpop3_helper.[ch] -- helper interface for the previous functions
83mailpop3_socket.[ch] -- provides a function to connect to a
84 POP3 server over TCP
85mailpop3_ssl.[ch] -- provides a function to connect to a
86 POP3 server over TLS layer
87
882.2.4/ Interface
89
90Include for this module is mailpop3.h and includes all other headers.
91
92There is not yet documentation for POP3 module.
93
94
952.3/ NNTP - Network News Transfer Protocol
96------------------------------------------
97
98Each command of the NNTP Standard (RFC 977 and RFC 2980) is implemented
99in the NNTP module. Directory nntp/.
100
1012.3.1/ References
102
103- RFC 977 - Network News Transfer Protocol
104- RFC 2980 - Common NNTP Extensions
105
106Not yet implemented :
107
108- RFC 1036 - Standard for Interchange of USENET Messages
109- son of RFC 1036 : FTP://zoo.toronto.edu/pub/news.txt.Z
110
1112.3.2/ Dependencies
112
113- tools/
114
1152.3.3/ Files descriptions
116
117newsnntp.[ch] -- functions that implements each NNTP command
118newsnntp_socket.[ch] -- provides a function to connect to a
119 NNTP server over TCP
120newsnntp_ssl.[ch] -- provides a function to connect to a
121 POP3 server over TLS layer
122
1232.3.4/ Interface
124
125Include for this module is newsnntp.h and includes all other headers.
126
127There is not yet documentation for NNTP module.
128
129
1302.4/ mbox
131---------
132
133The mbox module provides a set of functions to manipulate mbox mailboxes.
134These functions make a safe lock on the mailbox they work with.
135This module will assign to each message a unique message identifier
136so that we can work with message numbers in mbox files without other
137programs interfer.
138Directory mbox/.
139
1402.4.1/ References
141
142- http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html
143- http://www.qmail.org/qmail-manual-html/man5/mbox.html
144
1452.4.2/ Dependencies
146
147- tools/
148- imf/
149
1502.5.3/ Specific to libEtPan!
151
152- "X-LibEtPan-UID" header
153
1542.5.4/ Files descriptions
155
156mailmbox.[ch] -- functions to manipulate mbox mailboxes.
157mailmbox_parse.[ch] -- this module is in charge of parsing the
158 mbox file content
159mailmbox_types.[ch] -- definition of types and constructors for these
160 types
161
1622.4.5/ Interface
163
164Include for this module is mailmbox.h and includes all other headers.
165
166There is not yet documentation for mbox module.
167
168
1692.5/ MH
170-------
171
172The MH module provides a set of functions to manipulate MH mailboxes.
173Directory mh/.
174
1752.5.1/ References
176
177- almost none
178
1792.5.2/ Dependencies
180
181- tools/
182
1832.5.3/ Files descriptions
184
185mailmh.[ch] -- functions to manipulate MH mailboxes.
186
187
1882.5.4/ Interface
189
190Include for this module is mailmh.h.
191
192There is not yet documentation for MH module.
193
194
1952.6/ IMF - Internet Message Format
196----------------------------------
197
198The IMF module provides functions to parse data given in RFC 2822
199format (Internet Message Format).
200Directory imf/.
201
2022.6.1/ References
203
204- RFC 2822 - Internet Message Format (Not entirely implemented)
205- RFC 2076 - Common Internet Message Headers
206
207Not yet implemented :
208
209- RFC 2298 - An Extensible Message Format
210 for Message Disposition Notifications
211
2122.6.2/ Dependencies
213
214- tools/
215
2162.6.3/ Files descriptions
217
218mailimf.[ch] -- functions to parse RFC 2822 messages.
219mailimf_types.[ch] -- definition of types and constructors for these
220 types
221mailimf_types_helper.[ch] -- contains function definitions that will help
222 to create data necessary to use IMF module.
223mailimf_write.[ch] -- functions that output RFC 2822 messages or
224 sub-part of the messages in a (FILE *).
225
2262.6.4/ Interface
227
228Include for this module is mailimf.h and includes all other headers.
229
230The interface of IMAP4rev1 is documented in the following files :
231
232mailimf.h
233mailimf_types.h
234mailimf_types_helper.h
235mailimf_write.h
236
237
2382.7/ MIME - Multipurpose Internet Mail Extensions
239-------------------------------------------------
240
241The MIME module provides functions to parse structure of MIME messages.
242Directory mime/.
243
2442.7.1/ References
245
246- RFC 2045 - Multipurpose Internet Mail Extensions (MIME) Part One: Format of
247 Internet Message Bodies.
248- RFC 2047 - MIME (Multipurpose Internet Mail Extensions) Part Three: Message
249 Header Extensions for Non-ASCII Text.
250- RFC 2183 - Communicating Presentation Information in Internet Messages:
251 The Content-Disposition Header Field
252
253Not implemented :
254
255- RFC 2046 - Multipurpose Internet Mail Extensions (MIME) Part Two: Media
256 Types.
257
2582.7.2/ Dependencies
259
260- tools/
261- imf/
262
2632.7.3/ Files descriptions
264
265mailmime.[ch] -- functions to parse the MIME fields (RFC 2045).
266mailmime_content.[ch] -- functions to parse the MIME message. You get
267 the different parts and you can decode them.
268mailmime_decode.[ch] -- functions to parse the MIME-encoded fields.
269mailmime_disposition.[ch] -- functions to parse the Content-Disposition field
270 (RFC 2183)
271mailmime_types.[ch] -- definition of types and constructors for these
272 types
273mailmime_types_helper.[ch] -- contains function definitions that will help
274 to create data necessary to use MIME module.
275mailmime_write.[ch] -- functions that output MIME messages or
276 sub-part of the messages in a (FILE *).
277
2782.7.4/ Interface
279
280Include for this module is mailmime.h and includes all other headers.
281
282There is not yet documentation for MIME module.
283
284
2852.8/ SMTP - Simple Mail Transfer Protocol
286-----------------------------------------
287
288Each command of the SMTP Standard (RFC 2821 and RFC 1891) is implemented
289in the SMTP module. Directory smtp/.
290
2912.8.1/ References
292
293- RFC 2821 - Simple Mail Transfer Protocol (Not entirely implemented)
294- RFC 1891 - SMTP Service Extension for Delivery Status Notifications
295
2962.8.2/ Depencencies
297
298- tools/
299
3002.8.3/ Files descriptions
301
302mailsmtp.[ch] -- functions that implements each SMTP command
303mailsmtp_helper.[ch] -- functions to get an easier use of SMTP module
304mailsmtp_socket.[ch] -- provides a function to connect to a
305 SMTP server over TCP
306mailsmtp_ssl.[ch] -- provides a function to connect to a
307 SMTP server over TLS layer
308mailsmtp_types.h -- definition of types
309
3102.8.4/ Interface
311
312Include for this module is mailsmtp.h and includes all other headers.
313
314There is not yet documentation for MIME module.
315
316
3172.9/ Miscellaneous
318
3192.9.1/ References
320
321- RFC 2234 - Augmented BNF for Syntax Specifications: ABNF
322- RFC 2595 - Using TLS with IMAP, POP3 and ACAP
323
3242.9.2/ Tools
325
326tools/ directory contains some tools functions and useful data structures.
327
328alloc.h -- a wrapper on malloc()
329carray.[ch] -- an array, that grows automatically when elements
330 are added.
331charconv.[ch] -- character set converter. For example, it will
332 translate an iso-8859-1 string to an utf-8 string.
333chash.[ch] -- a hash table which keys can be anything
334cinthash.[ch] -- a hash table which keys are integers
335 (should be removed and replaced with chash)
336clist.[ch] -- a double-linked list
337connect.[ch] -- easy interface to connect a TCP server
338hmac_md5.h
339md5.[ch]
340md5global.h -- MD5 calculation
341mail.h -- some constants
342maildb_helper.[ch] -- wrappers to DB 2.x 3.x or 4.x
343maillock.[ch] -- safely lock a given file
344mailstream.[ch] -- stream interface - buffered reading and writing
345 on files/socket/SSL connection
346mailstream_helper.[ch] -- useful functions for stream
347 (for example: read a line)
348mailstream_low.[ch] -- driver interface for a stream
349mailstream_socket.[ch] -- stream driver for file descriptors (includes socket)
350mailstream_ssl.[ch] -- stream driver for SSL connection
351mailstream_types.h -- data structure definition
352mapping.[ch] -- map parts of files in memory (no more used)
353mmapstring.[ch] -- a string, that grows automatically when data
354 are added.
355
356
3573/ Higher-level
358---------------
359
360The higher level will allow us to query folder informations or to get
361messages information or content.
362
363There is four kinds of identities :
364- storage
365- folders
366- session
367- messages
368
369In the higher-level interface, you manipulate data types from IMF and
370MIME module, plus additionnal data types of higher-level.
371
372
3733.1/ Objects
374------------
375
3763.1.1/ Storage
377
378A storage (struct mail_storage) represents whether a server or
379a main path, It can be an IMAP server, the root path of a MH or a mbox file.
380
381
3823.1.2/ Folders
383
384A folder can be created from a storage.
385Folders (struct mail_folder) are the mailboxes we can choose in the
386server or as sub-folder of the main path.
387
388Folders for IMAP are the IMAP mailboxes, for MH this is one of the
389folder of the MH storage, for mbox, there is only one folder, the
390mbox file content;
391
392
3933.1.3/ Session
394
395Storage and folders communicate with the lower-layer through the
396mail session data structure.
397
398A mail session (struct mailsession) is a mail access to a server
399or a mail access in the local file system. It allow us to send commands
400to the mail access.
401
402A mail storage is using a mail session to communicate.
403A folder folder also uses a mail session to get information or to send
404information. It can be the same session or not, depdending of the
405implementation.
406
407
4083.1.4/ Messages
409
410From a session, we can get a message (struct mailmessage) to read.
411
412
4133.2/ Drivers
414------------
415
416For a mail access, three drivers exist.
417One for storage, one for session, one for message.
418Note that the folder access rely only on session driver.
419
420
4213.2.1/ storage driver interface
422
423 mail_storage_driver is the driver structure for mail storage
424
425 - name is the name of the driver
426
427 - connect() connects the storage to the remote access or to
428 the path in the local filesystem.
429
430 - get_folder() can have two kinds of behaviour.
431 Either it creates a new session and independant from the session
432 used by the storage and select the given mailbox or
433 it selects the given mailbox in the current session.
434 It depends on the efficiency of the mail driver.
435
436 - free_data() frees the data created with mail_storage constructor.
437
438 a constructor for each kind of access has to be implemented.
439
440
4413.2.2/ session driver interface
442
443 maildriver is the driver structure for mail sessions
444
445 - name is the name of the driver
446
447 - initialize() is the function that will initializes a data structure
448 specific to the driver, it returns a value that will be stored
449 in the field data of the session.
450 The field data of the session is the state of the session,
451 the internal data structure used by the driver.
452 It is called when creating the mailsession structure with
453 mailsession_new().
454
455 - uninitialize() frees the structure created with initialize()
456
457 - parameters() implements functions specific to the given mail access
458
459 - connect_stream() connects a stream to the session
460
461 - connect_path() notify a main path to the session
462
463 - starttls() changes the current stream to a TLS stream
464
465 - login() notifies the user and the password to authenticate to the
466 session
467
468 - logout() exits the session and closes the stream
469
470 - noop() does no operation on the session, but it can be
471 used to poll for the status of the connection.
472
473 - check_folder() makes a checkpoint of the session
474
475 - select_folder() selects a mailbox
476
477 - expunge_folder() deletes all messages marked \Deleted
478
479 - status_folder() queries the status of the folder
480 (number of messages, number of recent messages, number of
481 unseen messages)
482
483 - append_message() adds a RFC 2822 message to the current
484 given mailbox
485
486 - get_messages_list() returns the list of message numbers
487 of the current mailbox.
488
489 - get_envelopes_list() fills the parsed fields in the
490 mailmessage structures of the mail_envelopes_list.
491
492 - remove_message() removes the given message from the mailbox.
493 The message is permanently deleted.
494
495 - get_message returns a mailmessage structure that corresponds
496 to the given message number.
497
498
4993.2.3/ message driver interface
500
501 mailmessage_driver is the driver structure to get information from messages.
502
503 - name is the name of the driver
504
505 - initialize() is the function that will initializes a data structure
506 specific to the driver, it returns a value that will be stored
507 in the field data of the mailsession.
508 The field data of the session is the state of the session,
509 the internal data structure used by the driver.
510 It is called when initializing the mailmessage structure with
511 mailmessage_init().
512
513 - uninitialize() frees the structure created with initialize().
514 It will be called by mailmessage_free().
515
516 - flush() will free from memory all temporary structures of the message
517 (for example, the MIME structure of the message).
518
519 - fetch_result_free() will free all strings resulted by fetch() or
520 any fetch_xxx() functions that returns a string.
521
522 - fetch() returns the content of the message (headers and text).
523
524 - fetch_header() returns the content of the headers.
525
526 - fetch_body() returns the message text (message content without headers)
527
528 - fetch_size() returns the size of the message content.
529
530 - get_bodystructure() returns the MIME structure of the message.
531
532 - fetch_section() returns the content of a given MIME part
533
534 - fetch_section_header() returns the header of the message
535 contained by the given MIME part.
536
537 - fetch_section_mime() returns the MIME headers of the
538 given MIME part.
539
540 - fetch_section_body() returns the text (if this is a message, this is the
541 message content without headers) of the given MIME part.
542
543 - fetch_envelope() returns a mailimf_fields structure, with a list of
544 fields chosen by the driver.
545
546 - get_flags() returns a the flags related to the message.
547 When you want to get flags of a message, you have to make sure to
548 call get_flags() at least once before using directly message->flags.
549
550
5513.3/ Higher level interface
552---------------------------
553
5543.3.1/ Files descriptions
555
556generic_cache.[ch] -- functions that implements cache and
557 flags storing mechanism
558imapdriver.[ch] -- IMAP driver for session
559imapdriver_cached.[ch] -- IMAP driver for session, using cache,
560 IMAP already has flags.
561imapdriver_cached_message.[ch] -- IMAP driver for message, using cache
562 IMAP already has flags.
563imapdriver_message.[ch] -- IMAP driver for message
564imapdriver_types.[ch] -- tools function for IMAP driver (types
565 conversion from IMAP module).
566imapstorage.[ch] -- IMAP driver for storage
567imfcache.[ch] -- implements cache for parsed fields
568libetpan.h -- includes all necessary header files to
569 use libEtPan!
570maildriver.[ch] -- wrappers to calls to the session driver
571maildriver_tools.[ch] -- default implementation for drivers,
572 when the driver does not parse the
573 messages.
574maildriver_types.[ch] -- data types declaration and constructors
575maildriver_types_helper.[ch] -- easy data creation
576mailmessage.[ch] -- wrappers to calls to the message driver
577mailstorage.[ch] -- storage creation, calls to the storage
578 driver and implementation of folders.
579mailstorage_tools.[ch] -- tools for storage (connection)
580mailthread.[ch] -- threading: collection of the mails
581 into a treee
582mboxdriver.[ch] -- mbox driver for session
583mboxdriver_cached.[ch] -- mbox driver for session, using flags
584 and cache
585mboxdriver_cached_message.[ch] -- mbox driver for message, using flags
586 and cache
587mboxdriver_message.[ch] -- mbox driver for message
588mboxdriver_tools.[ch] -- mbox driver common functions
589mboxstorage.[ch] -- mbox driver for storage
590mhdriver.[ch] -- MH driver for session
591mhdriver_cached.[ch] -- MH driver for session, using flags
592 and cache
593mhdriver_cached_message.[ch] -- MH driver for message, using flags
594 and cache.
595mhdriver_message.[ch] -- MH driver for message
596mhdriver_tools.[ch] -- MH driver common functions
597mhstorage.[ch] -- MH driver for storage
598nntpdriver.[ch] -- NNTP driver for session
599nntpdriver_cached.[ch] -- NNTP driver for session, using flags
600 and cache
601nntpdriver_cached_message.[ch] -- NNTP driver for message, using flags
602 and cache
603nntpdriver_message.[ch] -- NNTP driver for message
604nntpdriver_tools.[ch] -- NNTP driver common functions
605nntpstorage.[ch] -- NNTP driver for storage
606pop3driver.[ch] -- POP3 driver for session
607pop3driver_cached.[ch] -- POP3 driver for session, using flags
608 and cache
609pop3driver_cached_message.[ch] -- POP3 driver for message, using flags
610 and cache
611pop3driver_message.[ch] -- POP3 driver for message
612pop3driver_tools.[ch] -- POP3 driver common functions
613pop3storage.[ch] -- POP3 driver for storage
614
615
6163.3.2/ Interfaces
617
618Include for this module is libetpan.h and includes all other headers.
619
620
621The interface of higher layer is documented in the following files :
622
623maildriver.h
624maildriver_types.h
625maildriver_types_helper.h
626mailmessage.h
627mailstorage.h
628mailstorage_types.[h]
629mailthread.h
630
631
6324/ Architecture
633---------------
634
635(see layer.fig)
636
637
6385/ Example of use
639-----------------
640
641You can find some example in tests/
642
643
6446/ Constraints
645--------------
646
647- libEtPan! must run on a system where mmap() is available.
648
649- for mbox particularly, libEtPan! make assumption on the fact that a
650 file can be entirely mapped into memory. But if you don't read
651 mailboxes of 1 Go, it should be fine.
652
653
654