Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 2e878c30 2e878c30999411781ca304afab2cfa1b49505a06 by Alain Magloire
Options

Added the new docs

1 parent 3d4474e7
Inline Side-by-side
Showing 29 changed files with 1672 additions and 184 deletions
...@@ -26,7 +26,9 @@ EXTRA_DIST = \ ...@@ -26,7 +26,9 @@ EXTRA_DIST = \
26 ## Sam, the examples dir is not part of the distribution so this will not work 26 ## Sam, the examples dir is not part of the distribution so this will not work
27 ## but we should probably have a "addrmsg" program and reenable this. 27 ## but we should probably have a "addrmsg" program and reenable this.
28 ## Alain. 28 ## Alain.
29 #ex-address.texi: ${top_srcdir}/examples/addr.c 29 #ex-address.texi: ${top_srcdir}/doc/examples/addr.c
30 # sed -es/{/@{/g -e s/}/@}/g < $< > $@
31 #sfrom.texi: ${top_srcdir}/doc/examples/sfrom.c
30 # sed -es/{/@{/g -e s/}/@}/g < $< > $@ 32 # sed -es/{/@{/g -e s/}/@}/g < $< > $@
31 33
32 #mailutils.info: mailutils.texi version.texi ex-address.texi 34 #mailutils.info: mailutils.texi version.texi ex-address.texi
......
1 @example
2 @code{/* Prefix @emph{address_} is reserve */}
1 @code{#include <mailutils/address.h>} 3 @code{#include <mailutils/address.h>}
2 4
5 @end example
3 The internet address format is defined in RFC 822. RFC 822 has been 6 The internet address format is defined in RFC 822. RFC 822 has been
4 updated, and is now superceeded by RFC 2822, which 7 updated, and is now superceeded by RFC 2822, which
5 makes some corrections and clarifications. References to RFC 822 8 makes some corrections and clarifications. References to RFC 822
......
1 @example
2 @code{/* Prefix @emph{attribute_} is reserve */}
1 @code{#include <mailutils/attribute.h>} 3 @code{#include <mailutils/attribute.h>}
2 4
5 @end example
6
3 @deftypefun int attribute_create (attribute_t *@var{pattribute}) 7 @deftypefun int attribute_create (attribute_t *@var{pattribute})
4 @end deftypefun 8 @end deftypefun
5 9
......
1 @example
2 @code{/* Prefix @emph{auth_} is reserve */}
3 @code{#include <mailutils/auth.h>}
4
5 @end example
6
1 There are many ways to authenticate to a server, to be flexible the 7 There are many ways to authenticate to a server, to be flexible the
2 authentication process is provided by two objects @code{auth_t} and 8 authentication process is provided by two objects @code{auth_t} and
3 @code{ticket_t}. The @code{auth_t} can implement different protocol like 9 @code{ticket_t}. The @code{auth_t} can implement different protocol like
......
1 @example
2 @code{/* Prefix @emph{body_} is reserve */}
1 @code{#include <mailutils/body.h>} 3 @code{#include <mailutils/body.h>}
2 4
5 @end example
6
3 @deftypefun int body_create (body_t *@var{body}, void *@var{owner}) 7 @deftypefun int body_create (body_t *@var{body}, void *@var{owner})
4 Initialize an object @var{bdy}. 8 Initialize an object @var{bdy}.
5 @end deftypefun 9 @end deftypefun
......
1 @menu
2 * POP3:: POP3
3 * IMAP4:: IMAP4
4 * Mbox:: Mbox
5 * Mh:: Mh
6 * Maildir:: Maildir
7 * SMTP:: SMTP
8 * Sendmail:: Sendmail
9 * NNTP:: NNTP
10 * Parse822:: Parse822
11 @end menu
12
13 @node POP3
14 @comment node-name, next, previous, up
15 @section POP3
16 @cindex POP3
17 @include pop3.texi
18
19 @node IMAP4
20 @comment node-name, next, previous, up
21 @section IMAP4
22 @cindex IMAP4
23 @include imap4.texi
24
25 @node Mbox
26 @comment node-name, next, previous, up
27 @section Mbox
28 @cindex Mbox
29 @include mbox.texi
30
31 @node Mh
32 @comment node-name, next, previous, up
33 @section Mh
34 @cindex Mh
35 @include mh.texi
36
37 @node Maildir
38 @comment node-name, next, previous, up
39 @section Maildir
40 @cindex Maildir
41 @include maildir.texi
42
43 @node SMTP
44 @comment node-name, next, previous, up
45 @section SMTP
46 @cindex SMTP
47 @include smtp.texi
48
49 @node Sendmail
50 @comment node-name, next, previous, up
51 @section Sendmail
52 @cindex Sendmail
53 @include sendmail.texi
54
55 @node NNTP
56 @comment node-name, next, previous, up
57 @section NNTP
58 @cindex NNTP
59 @include nntp.texi
60
61 @node Parse822
62 @comment node-name, next, previous, up
63 @section Parse822
64 @cindex Parse822
65 @include parse822.texi
1 @example
2 @code{/* Prefix @emph{envelope_} is reserve */}
3 @code{#include <mailutils/envelope.h>}
4
5 @end example
6
7 @deftypefun int envelope_create (envelope_t *, void *);
8 @end deftypefun
9
10 @deftypefun void envelope_destroy (envelope_t *, void *);
11 @end deftypefun
12
13 @deftypefun int envelope_get_message (envelope_t, message_t *);
14 @end deftypefun
15
16 @deftypefun int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *);
17 @end deftypefun
18
19 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *);
20 @end deftypefun
21
22 @deftypefun int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *);
23 @end deftypefun
24
25 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *);
26 @end deftypefun
1 @example
2 @code{/* Prefix @emph{folder_} is reserve */}
3 @code{#include <mailutils/folder.h>}
4
5 @end example
6
7 @example
8 @group
9 folder_t url_t
10 -/var/mail- +---//---->/-----------------\ +-->/-----------\
11 ( alain *-)-+ | | url_t *-|----+ | port |
12 ----------- | | |-----------------+ | hostname |
13 ( jakob *-)-+--+ | observer_t *-| | file |
14 ----------- | |-----------------+ | ... |
15 ( jeff *-)-+ | stream_t | \-----------/
16 ----------- | |-----------------|
17 ( sean *-)-+ | auth_t |
18 ---------- |-----------------|
19 | mailbox_t(1) |
20 |-----------------|
21 | mailbox_t(2) |
22 | ...... |
23 | mailbox_t(n) |
24 \-----------------/
25 @end group
26 @end example
27
28 @deftypefun int folder_create (folder_t *, const char *@var{url})
29 @end deftypefun
30
31 @deftypefun void folder_destroy (folder_t *)
32 @end deftypefun
33
34 @deftypefun int folder_open (folder_t, int @var{flag})
35 @end deftypefun
36
37 @deftypefun int folder_close (folder_t)
38 @end deftypefun
39
40 @deftypefun int folder_delete (folder_t, const char *@var{mailbox})
41 @end deftypefun
42
43 @deftypefun int folder_rename (folder_t, const char *, const char *@var{mailbox})
44 @end deftypefun
45
46 @deftypefun int folder_subscribe (folder_t, const char *@var{mailbox})
47 @end deftypefun
48
49 @deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox})
50 @end deftypefun
51
52 @deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, iterator_t *)
53 @end deftypefun
54
55 @deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcar}, iterator_t *)
56 @end deftypefun
57
58 @deftypefun int folder_get_stream (folder_t, stream_t *)
59 @end deftypefun
60
61 @deftypefun int folder_set_stream (folder_t, stream_t)
62 @end deftypefun
63
64 @deftypefun int folder_get_observable (folder_t, observable_t *)
65 @end deftypefun
66
67 @deftypefun int folder_get_debug (folder_t, debug_t *)
68 @end deftypefun
69
70 @deftypefun int folder_set_debug (folder_t, debug_t)
71 @end deftypefun
72
73 @deftypefun int folder_get_authority (folder_t, authority_t *)
74 @end deftypefun
75
76 @deftypefun int folder_set_authority (folder_t, authority_t)
77 @end deftypefun
78
79 @deftypefun int folder_get_url (folder_t, url_t *)
80 @end deftypefun
81
82 @deftypefun int folder_set_url (folder_t, url_t)
83 @end deftypefun
1 @menu
2 * Folder:: Folder.
3 * Mailbox:: Mailbox.
4 * Mailer:: Protocol Used to Send Mail.
5 * Message:: Message.
6 * Envelope:: Envelope.
7 * Headers:: Headers.
8 * Body:: Body.
9 * Attribute:: Attribute.
10 * Stream:: Stream.
11 * Iterator:: Iterator.
12 * Authenticator:: Authenticator.
13 * Address:: Address.
14 * Locker:: Locker.
15 * URL:: Unified Ressource Locator.
16
17 @end menu
18
19 Where ever the mail is and whatever format it is store in, the same operations
20 to manipulate emails are common. To unified the C API, GNU mailutils offers
21 an heteroclite set of objects that work in aggregation to do operations on
22 emails. Each object do a specific task and delegate non related tasks to
23 others. The object comes alive by specifying a @emph{URL} parameter when
24 created, it will indicate the storage format or protocol
25 (POP3, IMAP4, MH, MAILDIR, etc ..).
26
27 @example
28 @group
29
30 folder_t url_t
31 -/var/mail- +- .. ->+-----------------+ +-->+------------+
32 ( alain *-)-+ | | url_t *-|---+ | port |
33 ----------- | | |-----------------| | hostname |
34 ( jakob *-)-+--+ | auth_t *-|---+ | file |
35 ----------- | |-----------------| | | ... |
36 ( jeff *-)-+ | stream_t | | +------------+
37 ----------- | |-----------------| |
38 ( shaleh*-)-+ | ..... | | auth_t
39 ---------- |-----------------| +-->+------------+
40 +---|-* mailbox_t[] | | ticket_t |
41 mailbox_t | +-----------------+ +------------+
42 +----------------+<-+
43 | locker_t *--|-------------+
44 |----------------| |
45 | url_t | | locker_t
46 |----------------| +-------->+---------+
47 | stream_t | | lock |
48 |----------------| | unlock |
49 | message_t[] *-|-------+ +---------+
50 +----------------+ | envelope_t
51 | +-------->+-----------+
52 message_t | | | date |
53 +----------------+<------+ | | from |
54 | envelope_t *-|------------------+ | to |
55 |----------------| header_t +-----------+
56 | header_t *-|------------>+--------------+
57 |----------------| | stream_t |
58 | body_t *-|----+ +--------------+
59 +----------------+ | body_t
60 +-->+--------------+
61 | stream_t |
62 +--------------+
63 @end group
64 @end example
65
66 For example writing a simple @code{from} command that will list the
67 @emph{From} and @emph{Subject} headers of every mail in a mailbox.
68
69 @example
70 @include sfrom.c.texi
71 @end example
72
73 @example
74 @cartouche
75 % MAIL=pop://alain@@localhost ./sfrom
76 Passwd: xxxx
77 Jim Meyering <meyering@@foo.org> fetish(shellutils) beta
78 Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
79 @dots{}
80 @end cartouche
81 @end example
82
83 @node Folder
84 @comment node-name, next, previous, up
85 @section Folder
86 @cindex Folder
87
88 @include folder.texi
89
90 @node Mailbox
91 @comment node-name, next, previous, up
92 @section Mailbox
93 @cindex Mailbox
94
95 @include mailbox.texi
96
97 @node Mailer
98 @comment node-name, next, previous, up
99 @section Mailer
100 @cindex Mailer
101
102 @include mailer.texi
103
104 @node Message
105 @comment node-name, next, previous, up
106 @section Message
107 @cindex Message
108
109 @include message.texi
110
111 @node Envelope
112 @comment node-name, next, previous, up
113 @section Envelope
114 @cindex Envelope
115
116 @include envelope.texi
117
118 @node Headers
119 @comment node-name, next, previous, up
120 @section Headers
121 @cindex Headers
122
123 @include headers.texi
124
125 @node Body
126 @comment node-name, next, previous, up
127 @section Body
128 @cindex Body
129
130 @include body.texi
131
132 @node Attribute
133 @comment node-name, next, previous, up
134 @section Attribute
135 @cindex Attribute
136
137 @include attribute.texi
138
139 @node Stream
140 @comment node-name, next, previous, up
141 @section Stream
142 @cindex Stream
143
144 @include stream.texi
145
146 @node Iterator
147 @comment node-name, next, previous, up
148 @section Iterator
149 @cindex Iterator
150
151 @include iterator.texi
152
153 @node Authenticator
154 @comment node-name, next, previous, up
155 @section Authenticator
156 @cindex Authenticator
157
158 @include auth.texi
159
160 @node Address
161 @comment node-name, next, previous, up
162 @section Address
163 @cindex Address
164
165 @include address.texi
166
167 @node Locker
168 @comment node-name, next, previous, up
169 @section Locker
170 @cindex Locker
171
172 @include locker.texi
173
174 @node URL
175 @comment node-name, next, previous, up
176 @section URL
177 @cindex URL
178
179 @include url.texi
1 @example
2 @code{/* Prefix @emph{header_} is reserve */}
3 @code{#include <mailutils/header.h>}
4
5 @end example
6
1 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII 7 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII
2 characters will be encoded. 8 characters will be encoded.
3 9
......
1 @example
2 @code{/* Prefix @emph{imap4_} is reserve */}
3 @code{#include <mailutils/imap4.h>}
4
5 @end example
6
7 Internet Message Access Protocol - Version (4rev1). Not implemented.
8
9 @subsection Commands
10
11 @subsubsection Initialisation
12 @cindex IMAP4 Inintialisation
13
14 @deftypefun int imap4_create (imap4_t *)
15 @end deftypefun
16
17 @deftypefun int imap4_open (imap4_t, const char *@var{hostname}, unsigned int @var{port}, int @var{flags})
18 @end deftypefun
19
20 @deftypefun int imap4d_set_timeout (imap4_t, unsigned int @var{seconds})
21 @end deftypefun
22
23 @subsubsection Append
24 @cindex IMAP4 Append
25
26 @deftypefun int imap4_append (imap4_t)
27 @end deftypefun
28
29 @subsubsection Capability
30 @cindex IMAP4 Capability
31
32 @deftypefun int imap4_capability (imap4_t)
33 @end deftypefun
34
35 @subsubsection Create
36 @cindex IMAP4 Create
37
38 @deftypefun int imap4_create_mailbox (imap4_t, const char *@var{mbox})
39 @end deftypefun
40
41 @subsubsection Check
42 @cindex IMAP4 Check
43
44 @deftypefun int imap4_check (imap4_t)
45 @end deftypefun
46
47 @subsubsection Close
48 @cindex IMAP4 Close
49
50 @deftypefun int imap4_close (imap4_t)
51 @end deftypefun
52
53 @subsubsection Copy
54 @cindex IMAP4 Copy
55
56 @deftypefun int imap4_copy (imap4_t)
57 @end deftypefun
58
59 @subsubsection UID Copy
60 @cindex IMAP4 UID Copy
61
62 @deftypefun int imap4_uid_copy (imap4_t)
63 @end deftypefun
64
65 @subsubsection Delete
66 @cindex IMAP4 Delete
67
68 @deftypefun int imap4_delete (imap4_t)
69 @end deftypefun
70
71 @subsubsection Fetch
72 @cindex IMAP4 Fetch
73
74 @deftypefun int imap4_fetch (imap4_t)
75 @end deftypefun
76
77 @subsubsection UID Fetch
78 @cindex IMAP4 UID Fetch
79
80 @deftypefun int imap4_uid_fetch (imap4_t)
81 @end deftypefun
82
83 @subsubsection Examine
84 @cindex IMAP4 Examine
85
86 @deftypefun int imap4_examine (imap4_t)
87 @end deftypefun
88
89 @subsubsection Expunge
90 @cindex IMAP4 Expunge
91
92 @deftypefun int imap4_expunge (imap4_t)
93 @end deftypefun
94
95 @subsubsection List
96 @cindex IMAP4 List
97
98 @deftypefun int imap4_list (imap4_t)
99 @end deftypefun
100
101 @subsubsection Lsub
102 @cindex IMAP4 Lsub
103
104 @deftypefun int imap4_lsub (imap4_t)
105 @end deftypefun
106
107 @subsubsection Namespace
108 @cindex IMAP4 Namespace
109
110 @deftypefun int imap4_namespace (imap4_t)
111 @end deftypefun
112
113 @subsubsection Rename
114 @cindex IMAP4 Rename
115
116 @deftypefun int imap4_rename (imap4_t)
117 @end deftypefun
118
119 @subsubsection Search
120 @cindex IMAP4 Search
121
122 @deftypefun int imap4_search (imap4_t)
123 @end deftypefun
124
125 @subsubsection UID Search
126 @cindex IMAP4 UID Search
127
128 @deftypefun int imap4_uid_search (imap4_t)
129 @end deftypefun
130
131 @subsubsection Select
132 @cindex IMAP4 Select
133
134 @deftypefun int imap4_select (imap4_t)
135 @end deftypefun
136
137 @subsubsection Status
138 @cindex IMAP4 Status
139
140 @deftypefun int imap4_status (imap4_t)
141 @end deftypefun
142
143 @subsubsection Store
144 @cindex IMAP4 Store
145
146 @deftypefun int imap4_store (imap4_t)
147 @end deftypefun
148
149 @subsubsection UID Store
150 @cindex IMAP4 UID Store
151
152 @deftypefun int imap4_uid_store (imap4_t)
153 @end deftypefun
154
155 @subsubsection Subscribe
156 @cindex IMAP4 Subscribe
157
158 @deftypefun int imap4_subscribe (imap4_t)
159 @end deftypefun
160
161 @subsubsection Unsubscribe
162 @cindex IMAP4 Unsubscribe
163
164 @deftypefun int imap4_unsubscribe (imap4_t)
165 @end deftypefun
1 @example
2 @code{/* Prefix @emph{iterator_} is reserve */}
3 @code{#include <mailutils/iterator.h>}
4
5 @end example
6
7 @deftypefun int iterator_create (iterator_t *)
8 @end deftypefun
9
10 @deftypefun void iterator_destroy (iterator_t *)
11 @end deftypefun
12
13 @deftypefun int iterator_first (iterator_t)
14 @end deftypefun
15
16 @deftypefun int iterator_next (iterator_t)
17 @end deftypefun
18
19 @deftypefun int iterator_current (iterator_t, void **pitem)
20 @end deftypefun
21
22 @deftypefun int iterator_is_done (iterator_t)
23 @end deftypefun
24
1 @example
2 @code{/* Prefix @emph{locker_} is reserve */}
1 @code{#include <mailutils/locker.h>} 3 @code{#include <mailutils/locker.h>}
2 4
5 @end example
6
3 @deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags}) 7 @deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags})
4 @end deftypefun 8 @end deftypefun
5 9
......
1 @example
2 @code{/* Prefix @emph{mailbox_} is reserve */}
1 @code{#include <mailutils/mailbox.h>} 3 @code{#include <mailutils/mailbox.h>}
4
5 @end example
6
2 @deftp {Data Type} mailbox_t 7 @deftp {Data Type} mailbox_t
3 The @code{mailbox_t} object is used to hold information and it is an opaque 8 The @code{mailbox_t} object is used to hold information and it is an opaque
4 data structure to the user. Functions are provided to retrieve the information. 9 data structure to the user. Functions are provided to retrieve the information.
...@@ -9,15 +14,15 @@ data structure to the user. Functions are provided to retrieve the information. ...@@ -9,15 +14,15 @@ data structure to the user. Functions are provided to retrieve the information.
9 -/var/mail- +---//---->/-----------------\ +-->/-----------\ 14 -/var/mail- +---//---->/-----------------\ +-->/-----------\
10 ( alain ) | | url_t *-|----+ | port | 15 ( alain ) | | url_t *-|----+ | port |
11 ----------- | |-----------------+ | hostname | 16 ----------- | |-----------------+ | hostname |
12 ( jakob *-)----+ | auth_t *-|----+ | file | 17 ( jakob *-)----+ | observer_t *-| | file |
13 ----------- |-----------------+ | | ... | 18 ----------- |-----------------+ | ... |
14 ( jeff ) | stream_t | | \-----------/ 19 ( jeff ) | stream_t | \-----------/
15 ----------- |-----------------| | 20 ----------- |-----------------|
16 ( sean ) | locker_t | | auth_t 21 ( sean ) | locker_t |
17 ---------- |-----------------| +-->/----------\ 22 ---------- |-----------------|
18 | message_t(1) | | user | 23 | message_t(1) |
19 |-----------------| | passwd | 24 |-----------------|
20 | message_t(2) | \----------/ 25 | message_t(2) |
21 | ...... | 26 | ...... |
22 | message_t(n) | 27 | message_t(n) |
23 \-----------------/ 28 \-----------------/
...@@ -29,7 +34,7 @@ The @var{message} is appended to the mailbox @var{mbox}. ...@@ -29,7 +34,7 @@ The @var{message} is appended to the mailbox @var{mbox}.
29 34
30 The return value is @code{0} on success and a code number on error conditions: 35 The return value is @code{0} on success and a code number on error conditions:
31 @table @code 36 @table @code
32 @item EINVAL 37 @item MU_ERROR_INVALID_PARAMETER
33 @var{mbox} is null or @var{message} is invalid. 38 @var{mbox} is null or @var{message} is invalid.
34 @end table 39 @end table
35 @end deftypefun 40 @end deftypefun
...@@ -39,7 +44,7 @@ The stream attach to @var{mbox} is closed. ...@@ -39,7 +44,7 @@ The stream attach to @var{mbox} is closed.
39 44
40 The return value is @code{0} on success and a code number on error conditions: 45 The return value is @code{0} on success and a code number on error conditions:
41 @table @code 46 @table @code
42 @item EINVAL 47 @item MU_ERROR_INVALID_PARAMETER
43 @var{mbox} is null. 48 @var{mbox} is null.
44 @end table 49 @end table
45 @end deftypefun 50 @end deftypefun
...@@ -50,7 +55,7 @@ The concrete mailbox type instanciate is based on the scheme of the url @var{nam ...@@ -50,7 +55,7 @@ The concrete mailbox type instanciate is based on the scheme of the url @var{nam
50 55
51 The return value is @code{0} on success and a code number on error conditions: 56 The return value is @code{0} on success and a code number on error conditions:
52 @table @code 57 @table @code
53 @item EINVAL 58 @item MU_ERROR_INVALID_PARAMETER
54 The url @var{name} supplied is invalid or not supported. 59 The url @var{name} supplied is invalid or not supported.
55 @var{pmbox} is NULL. 60 @var{pmbox} is NULL.
56 @item ENOMEM 61 @item ENOMEM
...@@ -58,7 +63,7 @@ Not enough memory to allocate resources. ...@@ -58,7 +63,7 @@ Not enough memory to allocate resources.
58 @end table 63 @end table
59 @end deftypefun 64 @end deftypefun
60 65
61 @deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{user}) 66 @deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{name})
62 The environment variable @emph{$MAIL} or the string formed by 67 The environment variable @emph{$MAIL} or the string formed by
63 @emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null, 68 @emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null,
64 for a default mailbox and calls @code{mailbox_create}. 69 for a default mailbox and calls @code{mailbox_create}.
...@@ -73,17 +78,17 @@ All messages marked for deletion are removed. ...@@ -73,17 +78,17 @@ All messages marked for deletion are removed.
73 78
74 The return value is @code{0} on success and a code number on error conditions: 79 The return value is @code{0} on success and a code number on error conditions:
75 @table @code 80 @table @code
76 @item EINVAL 81 @item MU_ERROR_INVALID_PARAMETER
77 @var{mbox} is null. 82 @var{mbox} is null.
78 @end table 83 @end table
79 @end deftypefun 84 @end deftypefun
80 85
81 @deftypefun int mailbox_get_auth (mailbox_t @var{mbox}, auth_t *@var{pauth}) 86 @deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
82 Retrieve the @var{*pauth} of the @var{mbox}. 87 Get the @var{folder}.
83 88
84 The return value is @code{0} on success and a code number on error conditions: 89 The return value is @code{0} on success and a code number on error conditions:
85 @table @code 90 @table @code
86 @item EINVAL 91 @item MU_ERROR_INVALID_PARAMETER
87 @var{mbox} is null. 92 @var{mbox} is null.
88 @end table 93 @end table
89 @end deftypefun 94 @end deftypefun
...@@ -92,7 +97,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -92,7 +97,7 @@ The return value is @code{0} on success and a code number on error conditions:
92 Get a debug object. 97 Get a debug object.
93 The return value is @code{0} on success and a code number on error conditions: 98 The return value is @code{0} on success and a code number on error conditions:
94 @table @code 99 @table @code
95 @item EINVAL 100 @item MU_ERROR_INVALID_PARAMETER
96 @var{mbox} is null. 101 @var{mbox} is null.
97 @item ENOMEM 102 @item ENOMEM
98 @end table 103 @end table
...@@ -103,7 +108,7 @@ Return the @var{locker} object. ...@@ -103,7 +108,7 @@ Return the @var{locker} object.
103 108
104 The return value is @code{0} on success and a code number on error conditions: 109 The return value is @code{0} on success and a code number on error conditions:
105 @table @code 110 @table @code
106 @item EINVAL 111 @item MU_ERROR_INVALID_PARAMETER
107 @var{mbox} is null. 112 @var{mbox} is null.
108 @end table 113 @end table
109 @end deftypefun 114 @end deftypefun
...@@ -114,7 +119,7 @@ initialized. ...@@ -114,7 +119,7 @@ initialized.
114 119
115 The return value is @code{0} on success and a code number on error conditions: 120 The return value is @code{0} on success and a code number on error conditions:
116 @table @code 121 @table @code
117 @item EINVAL 122 @item MU_ERROR_INVALID_PARAMETER
118 @var{mbox} is null or @var{msgno} is invalid. 123 @var{mbox} is null or @var{msgno} is invalid.
119 @item ENOMEM 124 @item ENOMEM
120 Not enough memory. 125 Not enough memory.
...@@ -126,7 +131,7 @@ Get the observable object. ...@@ -126,7 +131,7 @@ Get the observable object.
126 131
127 The return value is @code{0} on success and a code number on error conditions: 132 The return value is @code{0} on success and a code number on error conditions:
128 @table @code 133 @table @code
129 @item EINVAL 134 @item MU_ERROR_INVALID_PARAMETER
130 @var{mbox} is null. 135 @var{mbox} is null.
131 @item ENOMEM 136 @item ENOMEM
132 Not enough memory. 137 Not enough memory.
...@@ -137,7 +142,7 @@ Not enough memory. ...@@ -137,7 +142,7 @@ Not enough memory.
137 Get the property object. 142 Get the property object.
138 The return value is @code{0} on success and a code number on error conditions: 143 The return value is @code{0} on success and a code number on error conditions:
139 @table @code 144 @table @code
140 @item EINVAL 145 @item MU_ERROR_INVALID_PARAMETER
141 @var{mbox} is null. 146 @var{mbox} is null.
142 @item ENOMEM 147 @item ENOMEM
143 @end table 148 @end table
...@@ -148,7 +153,7 @@ Gives the @var{mbox} size. ...@@ -148,7 +153,7 @@ Gives the @var{mbox} size.
148 153
149 The return value is @code{0} on success and a code number on error conditions: 154 The return value is @code{0} on success and a code number on error conditions:
150 @table @code 155 @table @code
151 @item EINVAL 156 @item MU_ERROR_INVALID_PARAMETER
152 @var{mbox} is null. 157 @var{mbox} is null.
153 @end table 158 @end table
154 @end deftypefun 159 @end deftypefun
...@@ -158,7 +163,7 @@ The mailbox stream is put in @var{pstream}. ...@@ -158,7 +163,7 @@ The mailbox stream is put in @var{pstream}.
158 163
159 The return value is @code{0} on success and a code number on error conditions: 164 The return value is @code{0} on success and a code number on error conditions:
160 @table @code 165 @table @code
161 @item EINVAL 166 @item MU_ERROR_INVALID_PARAMETER
162 @var{mbox} is invalid or @var{pstream} is NULL. 167 @var{mbox} is invalid or @var{pstream} is NULL.
163 @end table 168 @end table
164 @end deftypefun 169 @end deftypefun
...@@ -167,7 +172,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -167,7 +172,7 @@ The return value is @code{0} on success and a code number on error conditions:
167 The return value is @code{0} on success and a code number on error conditions: 172 The return value is @code{0} on success and a code number on error conditions:
168 173
169 @table @code 174 @table @code
170 @item EINVAL 175 @item MU_ERROR_INVALID_PARAMETER
171 @var{mbox} is null. 176 @var{mbox} is null.
172 @end table 177 @end table
173 @end deftypefun 178 @end deftypefun
...@@ -177,17 +182,17 @@ Gives the constructed @var{url}. ...@@ -177,17 +182,17 @@ Gives the constructed @var{url}.
177 182
178 The return value is @code{0} on success and a code number on error conditions: 183 The return value is @code{0} on success and a code number on error conditions:
179 @table @code 184 @table @code
180 @item EINVAL 185 @item MU_ERROR_INVALID_PARAMETER
181 @var{mbox} is null. 186 @var{mbox} is null.
182 @end table 187 @end table
183 @end deftypefun 188 @end deftypefun
184 189
185 @deftypefun int mailbox_is_updated (mailbox_t @var{mbox}) 190 @deftypefun int mailbox_is_modified (mailbox_t @var{mbox})
186 Check if the mailbox is up-to-date. 191 Check if the mailbox been modified by an external source.
187 192
188 The return value is @code{0} on success and a code number on error conditions: 193 The return value is @code{0} on success and a code number on error conditions:
189 @table @code 194 @table @code
190 @item EINVAL 195 @item MU_ERROR_INVALID_PARAMETER
191 @var{mbox} is null. 196 @var{mbox} is null.
192 @end table 197 @end table
193 @end deftypefun 198 @end deftypefun
...@@ -197,7 +202,7 @@ Give the number of first unseen message in @var{mbox}. ...@@ -197,7 +202,7 @@ Give the number of first unseen message in @var{mbox}.
197 202
198 The return value is @code{0} on success and a code number on error conditions: 203 The return value is @code{0} on success and a code number on error conditions:
199 @table @code 204 @table @code
200 @item EINVAL 205 @item MU_ERROR_INVALID_PARAMETER
201 @var{mbox} is null. 206 @var{mbox} is null.
202 @end table 207 @end table
203 @end deftypefun 208 @end deftypefun
...@@ -207,7 +212,7 @@ Give the number of messages in @var{mbox}. ...@@ -207,7 +212,7 @@ Give the number of messages in @var{mbox}.
207 212
208 The return value is @code{0} on success and a code number on error conditions: 213 The return value is @code{0} on success and a code number on error conditions:
209 @table @code 214 @table @code
210 @item EINVAL 215 @item MU_ERROR_INVALID_PARAMETER
211 @var{mbox} is null. 216 @var{mbox} is null.
212 @end table 217 @end table
213 @end deftypefun 218 @end deftypefun
...@@ -217,7 +222,7 @@ Give the number of recent messages in @var{mbox}. ...@@ -217,7 +222,7 @@ Give the number of recent messages in @var{mbox}.
217 222
218 The return value is @code{0} on success and a code number on error conditions: 223 The return value is @code{0} on success and a code number on error conditions:
219 @table @code 224 @table @code
220 @item EINVAL 225 @item MU_ERROR_INVALID_PARAMETER
221 @var{mbox} is null. 226 @var{mbox} is null.
222 @end table 227 @end table
223 @end deftypefun 228 @end deftypefun
...@@ -234,7 +239,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -234,7 +239,7 @@ The return value is @code{0} on success and a code number on error conditions:
234 Operation in progress. 239 Operation in progress.
235 @item EBUSY 240 @item EBUSY
236 Resource busy. 241 Resource busy.
237 @item EINVAL 242 @item MU_ERROR_INVALID_PARAMETER
238 @var{mbox} is null or flag is invalid. 243 @var{mbox} is null or flag is invalid.
239 @item ENOMEM 244 @item ENOMEM
240 Not enough memory. 245 Not enough memory.
...@@ -246,29 +251,19 @@ Scan the mailbox for new messages starting at message @var{msgno}. ...@@ -246,29 +251,19 @@ Scan the mailbox for new messages starting at message @var{msgno}.
246 251
247 The return value is @code{0} on success and a code number on error conditions: 252 The return value is @code{0} on success and a code number on error conditions:
248 @table @code 253 @table @code
249 @item EINVAL 254 @item MU_ERROR_INVALID_PARAMETER
250 @var{mbox} is null. 255 @var{mbox} is null.
251 @item ENOMEM 256 @item ENOMEM
252 Not enough memory. 257 Not enough memory.
253 @end table 258 @end table
254 @end deftypefun 259 @end deftypefun
255 260
256 @deftypefun int mailbox_set_auth (mailbox_t @var{mbox}, auth_t @var{auth})
257 Set the type of authentication for the mailbox.
258
259 The return value is @code{0} on success and a code number on error conditions:
260 @table @code
261 @item EINVAL
262 @var{mbox} is null.
263 @end table
264 @end deftypefun
265
266 @deftypefun int mailbox_set_locker (mailbox_t @var{mbox}, locker_t @var{locker}) 261 @deftypefun int mailbox_set_locker (mailbox_t @var{mbox}, locker_t @var{locker})
267 Set the type of locking done by the @var{mbox}. 262 Set the type of locking done by the @var{mbox}.
268 263
269 The return value is @code{0} on success and a code number on error conditions: 264 The return value is @code{0} on success and a code number on error conditions:
270 @table @code 265 @table @code
271 @item EINVAL 266 @item MU_ERROR_INVALID_PARAMETER
272 @var{mbox} is null. 267 @var{mbox} is null.
273 @end table 268 @end table
274 @end deftypefun 269 @end deftypefun
...@@ -278,7 +273,7 @@ Set the @var{stream} connection to use for the mailbox. ...@@ -278,7 +273,7 @@ Set the @var{stream} connection to use for the mailbox.
278 273
279 The return value is @code{0} on success and a code number on error conditions: 274 The return value is @code{0} on success and a code number on error conditions:
280 @table @code 275 @table @code
281 @item EINVAL 276 @item MU_ERROR_INVALID_PARAMETER
282 @var{mbox} or @var{stream} is NULL. 277 @var{mbox} or @var{stream} is NULL.
283 @end table 278 @end table
284 @end deftypefun 279 @end deftypefun
...@@ -288,7 +283,7 @@ The @var{ticket} will be set on the @code{auth_t} object on creation. ...@@ -288,7 +283,7 @@ The @var{ticket} will be set on the @code{auth_t} object on creation.
288 283
289 The return value is @code{0} on success and a code number on error conditions: 284 The return value is @code{0} on success and a code number on error conditions:
290 @table @code 285 @table @code
291 @item EINVAL 286 @item MU_ERROR_INVALID_PARAMETER
292 @var{mbox} is null. 287 @var{mbox} is null.
293 @end table 288 @end table
294 @end deftypefun 289 @end deftypefun
...@@ -298,7 +293,7 @@ Give the next predicted uid for @var{mbox}. ...@@ -298,7 +293,7 @@ Give the next predicted uid for @var{mbox}.
298 293
299 The return value is @code{0} on success and a code number on error conditions: 294 The return value is @code{0} on success and a code number on error conditions:
300 @table @code 295 @table @code
301 @item EINVAL 296 @item MU_ERROR_INVALID_PARAMETER
302 @var{mbox} is null. 297 @var{mbox} is null.
303 @end table 298 @end table
304 @end deftypefun 299 @end deftypefun
...@@ -308,8 +303,7 @@ Give the uid validity of @var{mbox}. ...@@ -308,8 +303,7 @@ Give the uid validity of @var{mbox}.
308 303
309 The return value is @code{0} on success and a code number on error conditions: 304 The return value is @code{0} on success and a code number on error conditions:
310 @table @code 305 @table @code
311 @item EINVAL 306 @item MU_ERROR_INVALID_PARAMETER
312 @var{mbox} is null. 307 @var{mbox} is null.
313 @end table 308 @end table
314 @end deftypefun 309 @end deftypefun
315
......
1 @example
2 @code{/* Prefix @emph{maildir_} is reserve */}
3 @code{#include <mailutils/maildir.h>}
4
5 @end example
6
7 QMail mailbox format. Not implemented.
1 @example
2 @code{/* Prefix @emph{mailer_} is reserve */}
3 @code{#include <mailutils/mailer.h>}
4
5 @end example
1 6
2 The API is still shaky and undefined. 7 The API is still shaky and undefined.
3 8
9 @deftypefun int mailer_create (mailer_t *, const char *)
10 @end deftypefun
11
12 @deftypefun void mailer_destroy (mailer_t *)
13 @end deftypefun
14
15 @deftypefun int mailer_open (mailer_t, int flags)
16 @end deftypefun
17
18 @deftypefun int mailer_close (mailer_t)
19 @end deftypefun
20
21 @deftypefun int mailer_send_message (mailer_t, message_t)
22 @end deftypefun
23
24 @deftypefun int mailer_get_property (mailer_t, property_t *)
25 @end deftypefun
26
27 @deftypefun int mailer_get_stream (mailer_t, stream_t *)
28 @end deftypefun
29
30 @deftypefun int mailer_set_stream (mailer_t, stream_t)
31 @end deftypefun
32
33 @deftypefun int mailer_get_debug (mailer_t, debug_t *)
34 @end deftypefun
35
36 @deftypefun int mailer_set_debug (mailer_t, debug_t)
37 @end deftypefun
38
39 @deftypefun int mailer_get_observable (mailer_t, observable_t *)
40 @end deftypefun
41
42 @deftypefun int mailer_get_url (mailer_t, url_t *)
43 @end deftypefun
......
...@@ -62,7 +62,7 @@ by the Foundation. ...@@ -62,7 +62,7 @@ by the Foundation.
62 @setchapternewpage off 62 @setchapternewpage off
63 63
64 @titlepage 64 @titlepage
65 @title mailutils, library API. 65 @title mailutils, SDK.
66 @subtitle version @value{VERSION}, @value{UPDATED} 66 @subtitle version @value{VERSION}, @value{UPDATED}
67 @author Alain Magloire et al. 67 @author Alain Magloire et al.
68 68
...@@ -92,6 +92,8 @@ by the Foundation. ...@@ -92,6 +92,8 @@ by the Foundation.
92 @end titlepage 92 @end titlepage
93 @page 93 @page
94 94
95 @summarycontents
96 @page
95 97
96 @node Top, Introduction, (dir), (dir) 98 @node Top, Introduction, (dir), (dir)
97 @comment node-name, next, previous, up 99 @comment node-name, next, previous, up
...@@ -102,26 +104,17 @@ This document was produced for version @value{VERSION} of @sc{gnu} ...@@ -102,26 +104,17 @@ This document was produced for version @value{VERSION} of @sc{gnu}
102 @end ifinfo 104 @end ifinfo
103 @menu 105 @menu
104 * Introduction:: GNU @sc{mailutils} 106 * Introduction:: GNU @sc{mailutils}
105 * Mailbox:: Mailbox API. 107 * C API:: C API.
106 * Mailer:: Protocol Used to Send Mail. 108 * Framework:: Framework.
107 * Message:: Message API. 109 * Programs:: Programs.
108 * Headers:: Headers API.
109 * Body:: Body API.
110 * Attribute:: Attribute.
111 * Stream:: Stream API.
112 * Authenticator:: Authenticator.
113 * Address:: Address.
114 * Locker:: Locker.
115 * Encoding:: Encoding API.
116 * URL:: Unified Ressource Locator.
117 * Reporting Bugs:: Reporting Bugs. 110 * Reporting Bugs:: Reporting Bugs.
118 * Acknowledgement:: Thanks and Credits. 111 * Acknowledgement:: Thanks and Credits.
119 * Concept Index :: 112 * Concept Index:: All @sc{Mailutils} Functions.
120 * Index:: All @sc{Mailutils} Functions. 113 * Index::
121 114
122 @end menu 115 @end menu
123 116
124 @node Introduction, Mailbox, Top, Top 117 @node Introduction, C API, Top, Top
125 @comment node-name, next, previous, up 118 @comment node-name, next, previous, up
126 @chapter Introduction 119 @chapter Introduction
127 @cindex Introduction 120 @cindex Introduction
...@@ -130,127 +123,122 @@ This document was produced for version @value{VERSION} of @sc{gnu} ...@@ -130,127 +123,122 @@ This document was produced for version @value{VERSION} of @sc{gnu}
130 provide a rich set of functions for accessing different mailbox formats and 123 provide a rich set of functions for accessing different mailbox formats and
131 mailers. 124 mailers.
132 125
133 @example 126 @section References
134 @group
135
136 mailbox_t url_t
137 -/var/mail- +---//---->+-----------------+ +-->+------------+
138 ( alain ) | | url_t *-|----+ | port |
139 ----------- | |-----------------| | hostname |
140 ( jakob *-)----+ | auth_t *-|----+ | file |
141 ----------- |-----------------| | | ... |
142 ( jeff ) | locker_t *-|--+ | +------------+
143 ----------- |-----------------| | |
144 ( shaleh ) | stream_t | | | auth_t
145 ---------- |-----------------| | +-->+------------+
146 +---|-* message_t[] | | | ticket_t |
147 message_t | +-----------------+ | +------------+
148 +----------------+<----+ |
149 | envelope_t | |
150 |----------------| header_t | locker_t
151 | header_t *-|------------>+--------------+ +---->+------+
152 |----------------| | stream_t | +------+
153 | body_t *-|----+ +--------------+
154 +----------------+ | body_t
155 +---+--------------+
156 | stream_t |
157 +--------------+
158 @end group
159 @end example
160
161 For example writing a simple @code{from} command that will list the
162 @emph{From} and @emph{Subject} headers of every mail in a folder.
163
164 @example
165 @include sfrom.c.texi
166 @end example
167
168 @node Mailbox, Mailer, Introduction, Top
169 @comment node-name, next, previous, up
170 @chapter Mailbox
171 @cindex Mailbox
172 127
173 @include mailbox.texi 128 For more information on,
174 129
175 @node Mailer, Message, Mailbox, Top 130 @itemize @bullet
176 @comment node-name, next, previous, up 131 @item
177 @chapter Mailer 132 SMTP RFCs:
178 @cindex Mailer
179 133
180 @include mailer.texi 134 @itemize @minus
135 @item
136 @cite{RFC 2821: Simple Mail Transfer Protocol}
181 137
182 @node Message, Headers , Mailer, Top 138 @item
183 @comment node-name, next, previous, up 139 @cite{RFC 2822: Internet Message Format}
184 @chapter Message
185 @cindex Message
186 140
187 @include message.texi 141 @item
142 @cite{RFC 2368: The mailto URL scheme}
143 @end itemize
188 144
189 @node Headers , Body, Message, Top 145 @item
190 @comment node-name, next, previous, up 146 on POP3
191 @chapter Headers
192 @cindex Headers
193 147
194 @include headers.texi 148 @itemize @minus
149 @item
150 @cite{RFC 1734: POP3 AUTHentication command}
195 151
196 @node Body, Attribute, Headers, Top 152 @item
197 @comment node-name, next, previous, up 153 @cite{RFC 1957: Some Observations on Implementations of the Post Office
198 @chapter Body 154 Protocol (POP3)}
199 @cindex Body
200 155
201 @include body.texi 156 @item
157 @cite{RFC 1939: Post Office Protocol - Version 3}
202 158
203 @node Attribute, Stream, Body, Top 159 @item
204 @comment node-name, next, previous, up 160 @cite{RFC 2449: POP3 Extension Mechanism}
205 @chapter Attribute
206 @cindex Attribute
207 161
208 @include attribute.texi 162 @item
163 @cite{RFC 2384: POP URL Scheme}
164 @end itemize
209 165
210 @node Stream, Authenticator, Attribute, Top 166 @item
211 @comment node-name, next, previous, up 167 On IMAP4
212 @chapter Stream
213 @cindex Stream
214 168
215 @include stream.texi 169 @itemize @minus
170 @item
171 @cite{RFC 2088: IMAP4 non-synchronizing literals}
216 172
217 @node Authenticator, Address, Stream, Top 173 @item
218 @comment node-name, next, previous, up 174 @cite{RFC 2193: IMAP4 Mailbox Referrals}
219 @chapter Authenticator
220 @cindex Authenticator
221 175
222 @include auth.texi 176 @item
177 @cite{RFC 2221: IMAP4 Login Referrals}
223 178
224 @node Address, Locker, Authenticator, Top 179 @item
225 @comment node-name, next, previous, up 180 @cite{RFC 2342: IMAP4 Namespace}
226 @chapter Address
227 @cindex Address
228 181
229 @include address.texi 182 @item
183 @cite{RFC 1738: Uniform Resource Locators (URL)}
230 184
231 @node Locker, Encoding, Address, Top 185 @item
232 @comment node-name, next, previous, up 186 @cite{RFC 2192: IMAP URL Scheme}
233 @chapter Locker 187 @end itemize
234 @cindex Locker 188
189 @item
190 On MIME
235 191
236 @include locker.texi 192 @itemize @minus
193 @item
194 @cite{RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1}
237 195
238 @node Encoding, URL, Locker , Top 196 @item
197 @cite{RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One:
198 Format of Internet Message Bodies}
199
200 @item
201 @cite{RFC 2047: MIME (Multipurpose Internet Mail Extensions) Part Three:
202 Message Header Extensions for Non-ASCII Text}
203
204 @item
205 @cite{RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part Five:
206 Conformance Criteria and Examples}
207
208 @item
209 @cite{RFC 2111: Content-ID and Message-ID Uniform Resource Locators}
210 @end itemize
211
212 @item
213 Misc
214 @cite{RFC 3028: Sieve: A Mail Filtering Language}
215
216 @item
217 @cite{Internet Email Protocols a Developer's Guide by Kevin Johnson}
218 @end itemize
219
220 @node C API, Framework, Introduction, Top
239 @comment node-name, next, previous, up 221 @comment node-name, next, previous, up
240 @chapter Encoding 222 @chapter C API
241 @cindex Encoding 223 @cindex C API
242 224
243 @include encoding.texi 225 @include c-api.texi
244 226
245 @node URL, Reporting Bugs, Encoding, Top 227 @node Framework, Programs, C API, Top
246 @comment node-name, next, previous, up 228 @comment node-name, next, previous, up
247 @chapter URL 229 @chapter Framework
248 @cindex URL 230 @cindex Framework
249 231
250 @include url.texi 232 @include framework.texi
251 233
234 @node Programs, Reporting Bugs, Framework, Top
235 @comment node-name, next, previous, up
236 @chapter Programs
237 @cindex Programs
238
239 @include programs.texi
252 240
253 @node Reporting Bugs, Acknowledgement, URL, Top 241 @node Reporting Bugs, Acknowledgement, Programs, Top
254 @comment node-name, next, previous, up 242 @comment node-name, next, previous, up
255 @chapter Reporting Bugs 243 @chapter Reporting Bugs
256 @cindex Reporting Bugs 244 @cindex Reporting Bugs
...@@ -266,14 +254,16 @@ Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field. ...@@ -266,14 +254,16 @@ Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field.
266 In no particular order, 254 In no particular order,
267 Jakob Kaivo @email{jkaivo@@ndn.net}, 255 Jakob Kaivo @email{jkaivo@@ndn.net},
268 Jeff Bailey @email{jbailey@@gnu.org}, 256 Jeff Bailey @email{jbailey@@gnu.org},
269 Sean 'Shaleh' Perry @email{shaleh@@debian.org}, 257 Sean Perry @email{shaleh@@debian.org},
270 Thomas Fletcher @email{thomasf@@qnx.com}, 258 Thomas Fletcher @email{thomasf@@qnx.com},
271 Dave Inglis @email{dinglis@@qnx.com}, 259 Dave Inglis @email{dinglis@@qnx.com},
272 Brian Edmond @email{briane@@qnx.com}, 260 Brian Edmond @email{briane@@qnx.com},
273 Sam Roberts @email{sroberts@@uniserve.com}. 261 Sam Roberts @email{sroberts@@uniserve.com},
274 262 Sergey Poznyakoff @email{gray@@Mirddin.farlep.net},
263 Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}.
275 @page 264 @page
276 @node Concept Index , Index, Acknowledgement, Top 265
266 @node Concept Index, Index, Acknowledgement, Top
277 @comment node-name, next, previous, up 267 @comment node-name, next, previous, up
278 @unnumbered Concept Index 268 @unnumbered Concept Index
279 269
...@@ -282,7 +272,8 @@ This is a general index of all issues discussed in this manual ...@@ -282,7 +272,8 @@ This is a general index of all issues discussed in this manual
282 @printindex cp 272 @printindex cp
283 @page 273 @page
284 274
285 @node Index, , Concept Index , Top 275 @node Index, , Concept Index, Top
276 @comment node-name, next, previous, up
286 @unnumbered Index 277 @unnumbered Index
287 278
288 This is an alphabetical list of all @sc{mailutils} functions. 279 This is an alphabetical list of all @sc{mailutils} functions.
......
1 @example
2 @code{/* Prefix @emph{mbox_} is reserve */}
3 @code{#include <mailutils/mbox.h>}
4
5 @end example
6
7 Standard Unix Mailbox. Not implemented.
1 @example
1 @code{#include <mailutils/message.h>} 2 @code{#include <mailutils/message.h>}
3 @code{/* Prefix @emph{message_} is reserve */}
4
5 @end example
2 6
3 The @code{message_t} object is a convenient way to manipulate messages. It 7 The @code{message_t} object is a convenient way to manipulate messages. It
4 encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}. 8 encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
......
1 @example
2 @code{/* Prefix @emph{mh_} is reserve */}
3 @code{#include <mailutils/mh.h>}
4
5 @end example
6
7 Mail Handler mailbox format. Not implemented.
1 Mime stuff in the Body. 1 @example
2 @code{/* Prefix @emph{pop3_} is reserve */}
3 @code{#include <mailutils/pop3.h>}
4
5 @end example
6
7 Multipurpose Internet Mail Extensions (MIME).
8
9 @deftypefun int mime_create (mime_t *pmime, message_t msg, int flags)
10 @end deftypefun
11
12 @deftypefun void mime_destroy (mime_t *pmime)
13 @end deftypefun
14
15 @deftypefun int mime_is_multipart (mime_t mime)
16 @end deftypefun
17
18 @deftypefun int mime_get_num_parts (mime_t mime, size_t *nparts)
19 @end deftypefun
20
21 @deftypefun int mime_get_part (mime_t mime, size_t part, message_t *msg)
22 @end deftypefun
23
24 @deftypefun int mime_add_part (mime_t mime, message_t msg)
25 @end deftypefun
26
27 @deftypefun int mime_get_message (mime_t mime, message_t *msg)
28 @end deftypefun
......
1 @example
2 @code{/* Prefix @emph{nntp_} is reserve */}
3 @code{#include <mailutils/nntp.h>}
4
5 @end example
6
7 Network News Transfer Protocol. Not implemented.
8
9 @subsection Commands
10
11 @subsubsection Initialisation
12 @cindex NNTP Initialisation
13 @deftypefun int nntp_create (nnpt_t *)
14 @end deftypefun
15
16 @deftypefun int nntp_destroy (nnpt_t *)
17 @end deftypefun
18
19 @deftypefun int nntp_open (nnpt_t)
20 @end deftypefun
21
22 @subsubsection Article
23 @cindex NNTP Article
24 @deftypefun int nntp_article (nnpt_t)
25 @end deftypefun
26
27 @subsubsection Body
28 @cindex NNTP Body
29 @deftypefun int nntp_body (nntp_t)
30 @end deftypefun
31
32 @subsubsection Group
33 @cindex NNTP Group
34 @deftypefun int nntp_group (nntp_t)
35 @end deftypefun
36
37 @subsubsection Head
38 @cindex NNTP Head
39 @deftypefun int nntp_head (nntp_t)
40 @end deftypefun
41
42 @subsubsection Help
43 @cindex NNTP Help
44 @deftypefun int nntp_help (nntp_t)
45 @end deftypefun
46
47 @subsubsection IHave
48 @cindex NNTP IHave
49 @deftypefun int nntp_ihave (nntp_t)
50 @end deftypefun
51
52 @subsubsection Last
53 @cindex NNTP Last
54 @deftypefun int nntp_last (nntp_t)
55 @end deftypefun
56
57 @subsubsection List
58 @cindex NNTP List
59 @deftypefun int nntp_list (nntp_t)
60 @end deftypefun
61
62 @subsubsection NewGroups
63 @cindex NNTP NewGroups
64 @deftypefun int nntp_newgroups (nntp_t)
65 @end deftypefun
66
67 @subsubsection NewNews
68 @cindex NNTP NewNews
69 @deftypefun int nntp_newnews (nntp_t)
70 @end deftypefun
71
72 @subsubsection Next
73 @cindex NNTP Next
74 @deftypefun int nntp_next (nntp_t)
75 @end deftypefun
76
77 @subsubsection Post
78 @cindex NNTP Post
79 @deftypefun int nntp_post (nntp_t)
80 @end deftypefun
81
82 @subsubsection Quit
83 @cindex NNTP Quit
84 @deftypefun int nntp_quit (nntp_t)
85 @end deftypefun
86
87 @subsubsection Slave
88 @cindex NNTP Slave
89 @deftypefun int nntp_slave (nntp_t)
90 @end deftypefun
91
92 @subsubsection Stat
93 @cindex NNTP Stat
94 @deftypefun int nntp_stat (nntp_t)
95 @end deftypefun
1 @example
2 @code{/* Prefix @emph{parse822_} is reserve */}
3 @code{#include <mailutils/parse822.h>}
4
5 @end example
6
7 Internet Message Format, see Address node for the discusion.
8
9 @deftypefun int parse822_address_list (address_t* a, const char* s)
10 @end deftypefun
11
12 @deftypefun int parse822_mail_box (const char** p, const char* e, address_t* a)
13 @end deftypefun
14
15 @deftypefun int parse822_group (const char** p, const char* e, address_t* a)
16 @end deftypefun
17
18 @deftypefun int parse822_address (const char** p, const char* e, address_t* a)
19 @end deftypefun
20
21 @deftypefun int parse822_route_addr (const char** p, const char* e, address_t* a)
22 @end deftypefun
23
24 @deftypefun int parse822_route (const char** p, const char* e, char** route)
25 @end deftypefun
26
27 @deftypefun int parse822_addr_spec (const char** p, const char* e, address_t* a)
28 @end deftypefun
29
30 @deftypefun int parse822_unix_mbox (const char** p, const char* e, address_t* a)
31 @end deftypefun
32
33 @deftypefun int parse822_local_part (const char** p, const char* e, char** local_part)
34 @end deftypefun
35
36 @deftypefun int parse822_domain (const char** p, const char* e, char** domain)
37 @end deftypefun
38
39 @deftypefun int parse822_sub_domain (const char** p, const char* e, char** sub_domain)
40 @end deftypefun
41
42 @deftypefun int parse822_domain_ref (const char** p, const char* e, char** domain_ref)
43 @end deftypefun
44
45 @deftypefun int parse822_domain_literal (const char** p, const char* e, char** domain_literal)
46 @end deftypefun
47
48 @deftypefun int parse822_quote_string (char** quoted, const char* raw)
49 @end deftypefun
50
51 @deftypefun int parse822_quote_local_part (char** quoted, const char* raw)
52 @end deftypefun
53
54
55 @deftypefun int parse822_field_body (const char** p, const char *e, char** fieldbody)
56 @end deftypefun
57
58 @deftypefun int parse822_field_name (const char** p, const char *e, char** fieldname)
59 @end deftypefun
1 @example
2 @code{/* Prefix @emph{pop3_} is reserve */}
3 @code{#include <mailutils/pop3.h>}
4
5 @end example
6
7 The Post Office Protocol Version 3 (POP3) purpose is to permit a client to
8 download a maildrop from a remote server. It does not provide complexe or
9 extensive operation on the maildrop.
10
11 @example
12
13 +----------+
14 +--------+ | | +---------------+ /-------\
15 | Client | --->| Server | ---> | AUTHORIZATION |--+--->| Close |<-+
16 +--------+ | Greeting | +---------------+ | \-------/ |
17 | | +--------------------+ |
18 +----------+ | |
19 | |
20 | +-------------+ +--------+ |
21 +->| TRANSACTION |----->| UPDATE |---+
22 +-------------+ +--------+
23 @end example
24
25 After the establisment of the TCP connection the server issues a greeting.
26
27 @example
28 @cartouche
29 +OK POP3 Server ready <1047.990840869@@caesar.rome.it>
30 @end cartouche
31 @end example
32
33 The POP3 session is now in the AUTHORIZATION State. The allowed commands
34 are:
35 @itemize @bullet
36 @item
37 User
38 @item
39 Pass
40 @item
41 Quit
42 @item
43 Capa (extension)
44 @item
45 Auth (extension)
46 @end itemize
47
48 When the client successfully authenticate the server acquires an exclusive
49 access lock on the mailbox and holds it the entire duration of the session.
50 The POP3 session enters The TRANSACTION State and the client may issues
51 commands to access the mailbox:
52 @itemize @bullet
53 @item
54 Stat
55 @item
56 List
57 @item
58 Retr
59 @item
60 Dele
61 @item
62 Noop
63 @item
64 Rset
65 @item
66 Top
67 @item
68 Uidl (extension)
69 @item
70 Quit
71 @item
72 Capa (externsion)
73 @end itemize
74
75 When the command @emph{Quit} is issue the POP3 session enters the UPDATE state.
76 The servers removes all messages marked deleted, releases the exclusive lock
77 and closes the TCP connection.
78
79 @subsection Commands
80 @cindex pop3_t
81
82 An opaque structure @emph{pop3_t} is use as a handle for the session, it is
83 allocate and initiliaze by calling @code{pop3_create ()}. All Functions will
84 wait for a reply from the POP3 server before returning. The duration of
85 the waiting can be set by calling @code{pop3_set_timeout ()}, the default
86 is 10 minutes@footnote{@strong{Caution:} Although the @cite{RFC 1939}
87 specifies that the minimum default timeout is ten minutes many servers has
88 shorter idle period, care should be taken to at least send a
89 @code{pop3_noop ()} between lengthy period of times.}. Once a succesfull
90 connection is establish with @code{pop3_open ()}, two builtin authentications
91 are provided @code{pop3_apop ()} or @code{pop3_user ()}, @code{pop3_pass ()}.
92 The @code{pop3_stat ()} and @code{pop3_list ()} functions can be use to get the
93 messages count and sizes. Downloading of messages are done via a stream
94 provided by @code{pop3_retr ()} or @code{pop3_top ()}@footnote{
95 @strong{Caution:} Some Internet Service Providers do not permit to leave mail
96 on server and the message will be deleted once downloaded.}.
97 The @code{stream_t} should be
98 destroy to indicate to the library that the action is finish. POP3 only
99 provide a single channel for operation, it means only one operation can be
100 done at a time, all the functions will return MU_ERROR_OPERATION_IN_PROGRESS
101 if call during another operation. The functions @code{pop3_list_all ()},
102 @code{pop3_uidl_all ()} and @code{pop3_capa ()} give an @code{iterator_t},
103 when iterating @code{iterator_current ()} will give an object that should
104 be cast appropriatly and @code{free ()} by the caller, the @code{iterator_t}
105 must also be destroy, @code{iterator_destroy ()}.
106
107 @subsubsection Initialisation
108 @cindex POP3 Initialisation
109
110 @deftypefun int pop3_create (pop3_t *)
111
112 A valid @code{pop3_t} handle must be create first.
113
114 @table @code
115 @item MU_ERROR_NO_MEMORY
116 @item MU_ERROR_INVALID_PARAMETER
117 @end table
118 @end deftypefun
119
120 @deftypefun void pop3_destroy (pop3_t *)
121
122 When the POP3 session is finished, the structure must be free to reclaim
123 memory.
124 @end deftypefun
125
126 @deftypefun int pop3_open (pop3_t, const char *@var{host}, unsigned port, int @var{flags})
127
128 A connection is establish by calling @code{pop3d_open()}. If non-blocking
129 the function should be recall until the return value is no MU_ERROR_TRY_AGAIN
130 or MU_ERROR_IN_PROGRESS.
131
132 @table @code
133 @item MU_ERROR_NO_MEMORY
134 @item MU_ERROR_INVALID_PARAMETER
135 @item MU_ERROR_IO
136 @item MU_ERROR_IN_PROGRESS
137 @item MU_ERROR_TRY_AGAIN
138 @item MU_ERROR_OPERATION_DENIED
139 @item MU_ERROR_TIMEOUT
140 @item MU_ERROR_NO_LOCK
141 @end table
142 @end deftypefun
143
144 @deftypefun int pop3_set_carrier (pop3_t, stream_t @var{carrier});
145
146 A connection may have been started elsewhere, in this case the @code{stream_t}
147 object is set on the @code{pop3_t} handle.
148
149 @table @code
150 @item MU_ERROR_INVALID_PARAMETER
151 @end table
152 @end deftypefun
153
154 @deftypefun int pop3_get_carrier (pop3_t, stream_t *@var{carrier});
155 @table @code
156 @item MU_ERROR_INVALID_PARAMETER
157 @item MU_ERROR_NO_MEMORY
158 @end table
159 @end deftypefun
160
161 @subsubsection Apop
162 @cindex POP3 Apop
163
164 @deftypefun int pop3_apop (pop3_t, const char *@var{user}, const char *@var{secret})
165
166 Apop offers an alternative to User/Pass authentication. For intermitent
167 use of POP3, for example checking for new mail, it is the prefered
168 authentication. It reduces the risk of passwd capture. The @var{user}
169 and the shared @var{secret} are pass to @code{pop3_apop ()}, the MD5 digest
170 is calculated by applying the timestamp given by the server in the greeting
171 followed by the @var{secret} and a @emph{APOP user digest} command is send.
172
173 @table @code
174 @item MU_ERROR_INVALID_PARAMETER
175 @item MU_ERROR_IO
176 @item MU_ERROR_TIMEOUT
177 @item MU_ERROR_TRY_AGAIN
178 @item MU_ERROR_OPERATION_DENIED
179 @end table
180 @end deftypefun
181
182 @subsubsection Auth
183 @cindex POP3 Auth
184
185 @deftypefun int pop3_auth (pop3_t, const char *@var{auth})
186
187 To allow the use of mechanism such as @emph{SASL}, @cite{RFC 2449}, extended
188 POP3 mechanism whith AUTH. It permits the client to choose an alternate
189 way of authenticate. @strong{Caution:} The @code{pop_auth()} is a simple
190 cover function that sends @emph{AUTH auth}, functions @code{pop3_sendline},
191 @code{pop3_readline}, @code{pop3_response} or the pop3 stream
192 @code{pop3_get_carrier ()} should be use appropriately to deal with the
193 challenges.
194
195 @table @code
196 @item MU_ERROR_INVALID_PARAMETER
197 @item MU_ERROR_IO
198 @item MU_ERROR_TIMEOUT
199 @item MU_ERROR_TRY_AGAIN
200 @item MU_ERROR_OPERATION_DENIED
201 @end table
202 @end deftypefun
203
204 @subsubsection Capa
205 @cindex POP3 Capa
206
207 @deftypefun int pop3_capa (pop3_t, iterator_t *)
208
209 The CAPA command is send to the sever and the list of capabilities is
210 return in an @var{iterator}. The @code{iterator_current ()} should be cast
211 to a @code{char **} and the string should be free by the caller.
212 @strong{Caution:} The iterator must be destroy after use, it will discard
213 any remaining response from CAPA and clear the way for new operations.
214
215 @table @code
216 @item MU_ERROR_INVALID_PARAMETER
217 @item MU_ERROR_IO
218 @item MU_ERROR_TIMEOUT
219 @item MU_ERROR_TRY_AGAIN
220 @item MU_ERROR_OPERATION_DENIED
221 @end table
222
223 @example
224 #include <mailutils/pop3.h>
225
226 void print_capabilities (pop3_t pop3)
227 @{
228 iterator_t capa_iterator;
229 status = pop3_capa (pop3, &capa_iterator);
230 if (status == 0)
231 @{
232 for (iterator_first (capa_iterator);
233 !iterator_is_done (capa_iterator);
234 iterator_next (capa_iterator))
235 @{
236 char *capa;
237 iterator_current (capa_iterator, (void **)&capa);
238 printf ("CAPA: %s\n", capa);
239 free (capa);
240 @}
241 iterator_destroy (&capa_iterator);
242 @}
243 else
244 printf ("NONE\n");
245 @}
246 @end example
247
248 @end deftypefun
249
250 @subsubsection Dele
251 @cindex POP3 Dele
252
253 @deftypefun int pop3_dele (pop3_t, unsigned @var{msgno})
254
255 Sends A Dele to the servers who will mark the @var{msgno} for deletion.
256 The @var{msgno} may not refer to a message already marked deleted.
257 If successfull any future reference to @var{msgno} in other operations will
258 be an error, unless unmarked by RSET.
259
260 @table @code
261 @item MU_ERROR_INVALID_PARAMETER
262 @item MU_ERROR_IO
263 @item MU_ERROR_TIMEOUT
264 @item MU_ERROR_TRY_AGAIN
265 @item MU_ERROR_OPERATION_DENIED
266 @end table
267
268 @end deftypefun
269
270 @subsubsection List
271 @cindex POP3 List
272 @cindex struct pop3_list
273
274 @deftypefun int pop3_list (pop3_t, unsigned @var{msgno}, size_t *@var{size})
275
276 Sends a List for a specific @var{msgno} and returns the @var{size}.
277
278 @table @code
279 @item MU_ERROR_INVALID_PARAMETER
280 @item MU_ERROR_IO
281 @item MU_ERROR_TIMEOUT
282 @item MU_ERROR_TRY_AGAIN
283 @item MU_ERROR_OPERATION_DENIED
284 @end table
285 @end deftypefun
286
287 @deftypefun int pop3_list_all (pop3_t, unsigned @var{msgno}, iterator_t *)
288
289 Sends A LIST with no argument to the server. The @var{iterator} must be
290 destroy after use, it will discard any remaining response from LIST and
291 clear the way for new operations. The @code{iterator_current ()} returns
292 a @code{struct pop3_list *} that must be @code{free ()}.
293
294 @example
295 struct pop3_list
296 @{
297 unsigned int msgno;
298 size_t size;
299 @};
300 @end example
301
302 @table @code
303 @item MU_ERROR_INVALID_PARAMETER
304 @item MU_ERROR_IO
305 @item MU_ERROR_TIMEOUT
306 @item MU_ERROR_TRY_AGAIN
307 @item MU_ERROR_OPERATION_DENIED
308 @end table
309
310 @example
311 #include <mailutils/pop3.h>
312
313 void print_list (pop3_t pop3)
314 @{
315 iterator_t list_iterator;
316 status = pop3_list_all (pop3, &list_iterator);
317 if (status == 0)
318 @{
319 for (iterator_first (list_iterator);
320 !iterator_is_done (list_iterator);
321 iterator_next (list_iterator))
322 @{
323 struct pop_list *pl;
324 iterator_current (list_iterator, (void **)&pl);
325 printf ("Msg: %d Size: %s\n", pl->msgno, pl->size);
326 free (pl);
327 @}
328 iterator_destroy (&capa_iterator);
329 @}
330 else
331 printf ("NONE\n");
332 @}
333 @end example
334
335 @end deftypefun
336
337 @subsubsection Noop
338 @cindex POP3 Noop
339
340 @deftypefun int pop3_noop (pop3_t)
341
342 Sends a NOOP, usefull to reset the timeout on the server.
343
344 @table @code
345 @item MU_ERROR_INVALID_PARAMETER
346 @item MU_ERROR_IO
347 @item MU_ERROR_TIMEOUT
348 @item MU_ERROR_TRY_AGAIN
349 @item MU_ERROR_OPERATION_DENIED
350 @end table
351 @end deftypefun
352
353 @subsubsection Pass
354 @cindex POP3 Pass
355
356 @deftypefun int pop3_pass (pop3_t, const char *@var{passwd})
357
358 Sends the PASS, to authenticate after the USER command.
359
360 @table @code
361 @item MU_ERROR_INVALID_PARAMETER
362 @item MU_ERROR_IO
363 @item MU_ERROR_TIMEOUT
364 @item MU_ERROR_TRY_AGAIN
365 @item MU_ERROR_OPERATION_DENIED
366 @end table
367 @end deftypefun
368
369 @subsubsection Quit
370 @cindex POP3 Quit
371
372 @deftypefun int pop3_quit (pop3_t)
373
374 Enter the UPDATE state. The server will delet all mesages marked
375 deleted before closing the connection.
376
377 @table @code
378 @item MU_ERROR_INVALID_PARAMETER
379 @item MU_ERROR_IO
380 @item MU_ERROR_TIMEOUT
381 @item MU_ERROR_TRY_AGAIN
382 @item MU_ERROR_OPERATION_DENIED
383 @end table
384 @end deftypefun
385
386 @subsubsection Retr
387 @cindex POP3 Retr
388
389 @deftypefun int pop3_retr (pop3_t, unsigned @var{msgno}, stream_t *)
390
391 If successfull a @code{stream_t} is created to allow dowloading of the message,
392 byte-stuff lines or handle internally, CRLFs are converted to LF. All other
393 operations will failed until the stream is destroyed by the caller.
394
395 @table @code
396 @item MU_ERROR_INVALID_PARAMETER
397 @item MU_ERROR_IO
398 @item MU_ERROR_TIMEOUT
399 @item MU_ERROR_TRY_AGAIN
400 @item MU_ERROR_OPERATION_DENIED
401 @end table
402 @end deftypefun
403
404 @subsubsection Rset
405 @cindex POP3 Rset
406
407 @deftypefun int pop3_rset (pop3_t)
408
409 Sends a RSET to unmarked the messages maked deleted.
410
411 @table @code
412 @item MU_ERROR_INVALID_PARAMETER
413 @item MU_ERROR_IO
414 @item MU_ERROR_TIMEOUT
415 @item MU_ERROR_TRY_AGAIN
416 @item MU_ERROR_OPERATION_DENIED
417 @end table
418 @end deftypefun
419
420 @subsubsection Stat
421 @cindex POP3 Stat
422
423 @deftypefun int pop3_stat (pop3_t, unsigned @var{msgno}, unsigned *@var{msg_count}, size_t *@var{size})
424
425 Call a drop listing for the maildrop. The number of messages in the mailbox
426 and the size of the mailbox in octets. @strong{Caution:} The size is in RFC
427 822 where line termination is CRLF, messages marked as deleted are not counted
428 in either total.
429
430 @table @code
431 @item MU_ERROR_INVALID_PARAMETER
432 @item MU_ERROR_IO
433 @item MU_ERROR_TIMEOUT
434 @item MU_ERROR_TRY_AGAIN
435 @item MU_ERROR_OPERATION_DENIED
436 @end table
437 @end deftypefun
438
439 @subsubsection Top
440 @cindex POP3 Top
441
442 @deftypefun int pop3_top (pop3_t, unsigned @var{msgno}, unsigned @var{lines}, stream_t *)
443
444 If successfull a @code{stream_t} is created to allow dowloading of the header,
445 byte-stuff lines or handle internally, CRLFs are converted to LF. All other
446 operations will failed until the stream is destroyed by the caller.
447
448 @table @code
449 @item MU_ERROR_INVALID_PARAMETER
450 @item MU_ERROR_IO
451 @item MU_ERROR_TIMEOUT
452 @item MU_ERROR_TRY_AGAIN
453 @item MU_ERROR_OPERATION_DENIED
454 @end table
455 @end deftypefun
456
457 @subsubsection Uidl
458 @cindex POP3 Uidl
459
460 @deftypefun int pop3_uidl (pop3_t, unsigned @var{msgno}, char **@var{uidl})
461
462 The Uniq Identifier is return in @var{uidl}, the string must be free,
463 by the caller.
464
465 @table @code
466 @item MU_ERROR_INVALID_PARAMETER
467 @item MU_ERROR_IO
468 @item MU_ERROR_TIMEOUT
469 @item MU_ERROR_TRY_AGAIN
470 @item MU_ERROR_OPERATION_DENIED
471 @end table
472 @end deftypefun
473
474 @deftypefun int pop3_uidl_all (pop3_t, iterator_t *)
475
476 An @code{iterator_t} object is return to iterate through the response and
477 must be destroy by the caller. The @code{iterator_current ()} is a
478 @code{char **} that must be @code{free ()} by the caller.
479
480 @table @code
481 @item MU_ERROR_INVALID_PARAMETER
482 @item MU_ERROR_IO
483 @item MU_ERROR_TIMEOUT
484 @item MU_ERROR_TRY_AGAIN
485 @item MU_ERROR_OPERATION_DENIED
486 @end table
487 @end deftypefun
488
489 @subsubsection User
490 @cindex POP3 User
491
492 @deftypefun int pop3_user (pop3_t, const char *@var{user})
493
494 Sends the User command.
495
496 @table @code
497 @item MU_ERROR_INVALID_PARAMETER
498 @item MU_ERROR_IO
499 @item MU_ERROR_TIMEOUT
500 @item MU_ERROR_TRY_AGAIN
501 @item MU_ERROR_OPERATION_DENIED
502 @end table
503 @end deftypefun
504
505 @subsubsection Help functions
506
507 @deftypefun int pop3_writeline (pop3_t, const char *@var{format}, ...);
508
509 Copy in the internal buffer of @code{pop3_t} the string, @code{pop3_send ()}
510 should be call later to flush the string to POP3 server.
511
512 @table @code
513 @item MU_ERROR_INVALID_PARAMETER
514 @item MU_ERROR_IO
515 @item MU_ERROR_TIMEOUT
516 @item MU_ERROR_TRY_AGAIN
517 @item MU_ERROR_OPERATION_DENIED
518 @end table
519 @end deftypefun
520
521 @deftypefun int pop3_sendline (pop3_t, const char *@var{cmd});
522
523 Cover function.
524
525 @table @code
526 @item MU_ERROR_INVALID_PARAMETER
527 @item MU_ERROR_IO
528 @item MU_ERROR_TIMEOUT
529 @item MU_ERROR_TRY_AGAIN
530 @item MU_ERROR_OPERATION_DENIED
531 @end table
532
533 @example
534 int pop3_sendline (pop3_t pop3, const char *line)
535 @{
536 /* .. */
537 pop3_writeline (pop3_t, line);
538 /* .. */
539 pop_send (pop3);
540 /* .. */
541 @}
542 @end example
543
544 @end deftypefun
545
546 @deftypefun int pop3_send (pop3_t, const char *@var{cmd});
547
548 Flushes out the strings int the @code{pop3_t} internal buffer to the channel.
549
550 @table @code
551 @item MU_ERROR_INVALID_PARAMETER
552 @item MU_ERROR_IO
553 @item MU_ERROR_TIMEOUT
554 @item MU_ERROR_TRY_AGAIN
555 @item MU_ERROR_OPERATION_DENIED
556 @end table
557 @end deftypefun
558
559 @deftypefun int pop3_response (pop3_t, char *@var{buffer}, size_t @var{len}, size_t *@var{plen})
560
561 The last response from the last command is save and can be examine after
562 a failure.
563
564 @table @code
565 @item MU_ERROR_INVALID_PARAMETER
566 @item MU_ERROR_IO
567 @item MU_ERROR_TIMEOUT
568 @item MU_ERROR_TRY_AGAIN
569 @item MU_ERROR_OPERATION_DENIED
570 @end table
571
572 @end deftypefun
1
2 @section frm
3 List header from a mailbox.
4
5 @section imap4d
6 Imap4 daemon.
7
8 @section mail
9 Send and receive mail.
10
11 @section parse822
12 Parse RFC 822 fields.
13
14 @section pop3d
15 POP3 daemon.
16
17 @section readmsg
18 Extract messages from a folder.
19
20 @section sendmsg
21 Send a message.
22
23 @section sieve
24 Filter a mailbox.
25
1 @example
2 @code{/* Prefix @emph{sendmail_} is reserve */}
3 @code{#include <mailutils/sendmail.h>}
4
5 @end example
6
7 Spawning Sedmail daemon to deliver mail. Not implemented.
...@@ -74,13 +74,3 @@ main (int argc, const char **argv) ...@@ -74,13 +74,3 @@ main (int argc, const char **argv)
74 mailbox_destroy (&mbox); 74 mailbox_destroy (&mbox);
75 return 0; 75 return 0;
76 @} 76 @}
77
78 @example
79 @cartouche
80 % MAIL=pop://alain@@localhost ./sfrom
81 Passwd: xxxx
82 Jim Meyering <meyering@@foo.org> fetish(shellutils) beta
83 Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
84 @dots{}
85 @end cartouche
86 @end example
......
1 @example
2 @code{/* Prefix @emph{smtp_} is reserve */}
3 @code{#include <mailutils/smtp.h>}
4
5 @end example
6
7 Simple Mail Transfer Protocol. Not implemented.
8
9 @subsection Commands
10 @cindex smtp_t
11
12 @subsubsection Initialisation
13 @cindex SMTP Initialisation
14 @deftypefun int smtp_create (smtp_t *)
15 @end deftypefun
16
17 @deftypefun void smtp_destroy (smtp_t *)
18 @end deftypefun
19
20 @deftypefun int smtp_open (smtp_t, const char *@var{host}, unsigned int @var{port}, int @var{flags})
21 @end deftypefun
22
23
24 @subsubsection Data
25 @cindex SMTP Data
26 @deftypefun int smtp_data (smtp_t, stream_t @var{stream})
27 @end deftypefun
28
29 @subsubsection Helo
30 @cindex SMTP Helo
31 @deftypefun int smtp_helo (smtp_t, const char *@var{domain})
32 @end deftypefun
33
34 @deftypefun int smtp_ehlo (smtp_t, const char *@var{domain})
35 @end deftypefun
36
37 @subsubsection Expn
38 @cindex SMTP Expn
39 @deftypefun int smtp_expn (smtp_t, const char *@var{list}, iterator_t *)
40 @end deftypefun
41
42 @subsubsection Help
43 @cindex SMTP Help
44 @deftypefun int smtp_help (smtp_t, const char *@var{help}, iterator_t *)
45 @end deftypefun
46
47 @subsubsection Mail From
48 @cindex SMTP Mail From
49 @deftypefun int smtp_mail_from (smtp_t, const char *@var{address}, const char *@var{param})
50 @end deftypefun
51
52 @subsubsection Noop
53 @cindex SMTP Noop
54 @deftypefun int smtp_noop (smtp_t)
55 @end deftypefun
56
57 @subsubsection Quit
58 @cindex SMTP Quit
59 @deftypefun int smtp_quit (smtp_t)
60 @end deftypefun
61
62 @subsubsection Recpt To
63 @cindex SMTP Recpt To
64 @deftypefun int smtp_rcpt_to (smtp_t, const char *@var{address}, const char *@var{param})
65 @end deftypefun
66
67 @subsubsection Reset
68 @cindex SMTP Reset
69 @deftypefun int smtp_reset (smtp_t)
70 @end deftypefun
71
72 @subsubsection Verify
73 @cindex SMTP Verify
74 @deftypefun int smtp_verify (smtp_t, const char *@var{user})
75 @end deftypefun
76
77 @subsubsection Help functions
78 @cindex SMTP Help functions
79 @deftypefun extern int smtp_readline (smtp_t, char *@var{buffer}, size_t @var{len}, size_t *@var{len})
80 @end deftypefun
81
82 @deftypefun extern int smtp_response (smtp_t, char *@var{buffer}, size_t @var{len}, size_t *@var{len})
83 @end deftypefun
84
85 @deftypefun extern int smtp_writeline (smtp_t, const char *@var{format}, @var{...})
86 @end deftypefun
87
88 @deftypefun extern int smtp_sendline (smtp_t, const char *@var{line})
89 @end deftypefun
90
91 @deftypefun extern int smtp_send (smtp_t
92 @end deftypefun
...@@ -4,7 +4,7 @@ A mailbox and mailer can be described in a URL, the string will contain the ...@@ -4,7 +4,7 @@ A mailbox and mailer can be described in a URL, the string will contain the
4 necessary information to initialize @code{mailbox_t}, or @code{mailer_t} 4 necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
5 properly. 5 properly.
6 6
7 @section POP3 7 @subsection POP3
8 The POP URL scheme contains a pop server, optional port number 8 The POP URL scheme contains a pop server, optional port number
9 and the authentication mechanism. The general form is 9 and the authentication mechanism. The general form is
10 10
...@@ -25,12 +25,12 @@ a default scheme base on the capability of the server. ...@@ -25,12 +25,12 @@ a default scheme base on the capability of the server.
25 25
26 For more complete information see @cite{rfc2368}. 26 For more complete information see @cite{rfc2368}.
27 27
28 @section IMAP 28 @subsection IMAP
29 imap://..... 29 imap://.....
30 30
31 Description of the fields and examples are needed. 31 Description of the fields and examples are needed.
32 32
33 @section File 33 @subsection File
34 34
35 Local folder should be handle by this URL. It is preferable to let 35 Local folder should be handle by this URL. It is preferable to let
36 the mailbox recognize the type of mailbox and take the appropriate 36 the mailbox recognize the type of mailbox and take the appropriate
...@@ -50,7 +50,7 @@ use @url{file://path} and let the library figure out which one. ...@@ -50,7 +50,7 @@ use @url{file://path} and let the library figure out which one.
50 @url{mh://path} 50 @url{mh://path}
51 @end example 51 @end example
52 52
53 @section Mailto 53 @subsection Mailto
54 54
55 After setting a mailer, @url{mailto:} is used to tell the mailer where 55 After setting a mailer, @url{mailto:} is used to tell the mailer where
56 and to whom the message is for. 56 and to whom the message is for.
...@@ -67,7 +67,7 @@ to mailing lists. ...@@ -67,7 +67,7 @@ to mailing lists.
67 67
68 For more complete information see @cite{rfc2368}. 68 For more complete information see @cite{rfc2368}.
69 69
70 @section URL functions 70 @subsection URL functions
71 71
72 Helper functions are provided to retrieve and set the @emph{URL} fields. 72 Helper functions are provided to retrieve and set the @emph{URL} fields.
73 73
...@@ -91,7 +91,7 @@ Initialize and parse the @var{url} ...@@ -91,7 +91,7 @@ Initialize and parse the @var{url}
91 @end example 91 @end example
92 @end deftp 92 @end deftp
93 93
94 @section URL registration 94 @subsection URL registration
95 95
96 @deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, size_t *@var{n}) 96 @deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, size_t *@var{n})
97 @end deftypefun 97 @end deftypefun
...@@ -105,7 +105,7 @@ Initialize and parse the @var{url} ...@@ -105,7 +105,7 @@ Initialize and parse the @var{url}
105 @deftypefun int url_get_id (const url_t @var{url}, int *@var{id}) 105 @deftypefun int url_get_id (const url_t @var{url}, int *@var{id})
106 @end deftypefun 106 @end deftypefun
107 107
108 @section Helper functions 108 @subsection Helper functions
109 109
110 @example 110 @example
111 #include <mailutils/url.h> 111 #include <mailutils/url.h>
......