Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit b8975450 b89754507e2bdc1e147741d748f468e745c26bcf by Sergey Poznyakoff
Options

Reorganized directory structure

1 parent 5d3b3b4f
Expand all
Inline Side-by-side
Showing 59 changed files with 0 additions and 4577 deletions
1 @example
2 @code{/* Prefix @emph{address_} is reserved */}
3 @code{#include <mailutils/address.h>}
4
5 @end example
6 The internet address format is defined in RFC 822. RFC 822 has been
7 updated, and is now superceeded by RFC 2822, which
8 makes some corrections and clarifications. References to RFC 822
9 here apply equally to RFC 2822.
10
11 The RFC 822 format is more flexible than many people realize, here
12 is a quick summary of the syntax this parser implements, see
13 RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or
14 the other", and double-quoted characters are literals.
15
16 @example
17 addr-spec = local-part "@" domain
18 mailbox = addr-spec ["(" display-name ")"] /
19 [display-name] "<" [route] addr-spec ">"
20 mailbox-list = mailbox ["," mailbox-list]
21 group = display-name ":" [mailbox-list] ";"
22 address = mailbox / group / unix-mbox
23 address-list = address ["," address-list]
24 @end example
25
26 unix-mbox is a non-standard extention meant to deal with the common
27 practice of using user names as addresses in mail utilities. It allows
28 addresses such as "root" to be parsed correctly. These are NOT valid
29 internet email addresses, they must be qualified before use.
30
31 Several address functions have a set of common arguments with consistent
32 semantics, these are described here to avoid repetition.
33
34 Since an address-list may contain multiple addresses, they are accessed
35 by a @strong{one-based} index number, @var{no}. The index is one-based
36 because pop, imap, and other message stores commonly use one-based
37 counts to access messages and attributes of messages.
38
39 If @var{len} is greater than @code{0} it is the length of the buffer
40 @var{buf}, and as much of the component as possible will be copied
41 into the buffer. The buffer will be nul terminated.
42
43 The size of a particular component may be queried by providing @code{0}
44 for the @var{len} of the buffer, in which case the buffer is optional.
45 In this case, if @var{n} is provided *@var{n} is assigned the length of
46 the component string.
47
48 @macro ADDRESSENOMEM
49 @item ENOMEM
50 Not enough memory to allocate resources.
51 @end macro
52
53 @macro ADDRESSEPARSE
54 @item ENOENT
55 Invalid RFC822 syntax, parsing failed.
56 @end macro
57
58 @macro ADDRESSENOENT
59 @item ENOENT
60 The index @var{no} is outside of the range of available addresses.
61 @end macro
62
63 @macro ADDRESSEINVAL
64 @item EINVAL
65 Invalid usage, usually a required argument was @code{nul}.
66 @end macro
67
68 @deftp {Data Type} address_t
69 The @code{address_t} object is used to hold information about a parsed
70 RFC822 address list, and is an opaque
71 data structure to the user. Functions are provided to retrieve information
72 about an address in the address list.
73
74 @end deftp
75
76 @deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
77 This function allocates and initializes @var{addr} by parsing the
78 RFC822 address-list @var{string}.
79
80 The return value is @code{0} on success and a code number on error conditions:
81 @table @code
82 @ADDRESSEINVAL
83 @ADDRESSENOMEM
84 @ADDRESSEPARSE
85 @end table
86 @end deftypefun
87
88 @deftypefun void address_destroy (address_t *@var{addr})
89 The @var{addr} is destroyed.
90 @end deftypefun
91
92 @deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
93
94 Accesses the @var{no}th email address component of the address list. This
95 address is the plain email address, correctly quoted, suitable for
96 using in an smtp dialog, for example, or as the address part of
97 a contact book entry.
98
99 The return value is @code{0} on success and a code number on error conditions:
100 @table @code
101 @ADDRESSEINVAL
102 @ADDRESSENOENT
103 @end table
104 @end deftypefun
105
106 @deftypefun int address_get_personal (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
107
108 Accesses the display-name describing the @var{no}th email address. This
109 display-name is optional, so may not be present. If it is not present, but
110 there is an RFC822 comment after the address, that comment will be
111 returned as the personal phrase, as this is a common usage of the comment
112 even though it is not defined in the internet mail standard.
113
114 A group is a kind of a special case. It has a display-name, followed
115 by an optional mailbox-list. The display-name will be allocated an address
116 all it's own, but all the other elements (local-part, domain, etc.) will
117 be zero-length. So "a group: ;" is valid, will have a count of 1, but
118 address_get_email(), and all the rest, will return zero-length output.
119
120 The return value is @code{0} on success and a code number on error conditions:
121 @table @code
122 @ADDRESSEINVAL
123 @ADDRESSENOENT
124 @end table
125 @end deftypefun
126
127
128 @deftypefun int address_get_comments (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
129
130 Accesses the comments extracted while parsing the @var{no}th email address.
131 These comments have no defined meaning, and are not currently collected.
132
133 The return value is @code{0} on success and a code number on error conditions:
134 @table @code
135 @ADDRESSEINVAL
136 @ADDRESSENOENT
137 @end table
138 @end deftypefun
139
140
141 @deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
142
143 Accesses the email addr-spec extracted while
144 parsing the @var{no}th email address. This will be @code{0}
145 length for a unix-mbox.
146
147 The return value is @code{0} on success and a code number on error conditions:
148 @table @code
149 @ADDRESSEINVAL
150 @ADDRESSENOENT
151 @end table
152 @end deftypefun
153
154 @deftypefun int address_get_local_part (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
155
156 Accesses the local-part of an email addr-spec extracted while
157 parsing the @var{no}th email address.
158
159 The return value is @code{0} on success and a code number on error conditions:
160 @table @code
161 @ADDRESSEINVAL
162 @ADDRESSENOENT
163 @end table
164 @end deftypefun
165
166 @deftypefun int address_get_domain (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
167
168 Accesses the domain of an email addr-spec extracted while
169 parsing the @var{no}th email address. This will be @code{0}
170 length for a unix-mbox.
171
172 The return value is @code{0} on success and a code number on error conditions:
173 @table @code
174 @ADDRESSEINVAL
175 @ADDRESSENOENT
176 @end table
177 @end deftypefun
178
179 @deftypefun int address_get_route (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
180
181 Accesses the route of an email addr-spec extracted while
182 parsing the @var{no}th email address. This is a rarely used RFC822 address
183 syntax, but is legal in SMTP as well. The entire route is returned as
184 a string, those wishing to parse it should look at <mailutils/parse822.h>.
185
186 The return value is @code{0} on success and a code number on error conditions:
187 @table @code
188 @ADDRESSEINVAL
189 @ADDRESSENOENT
190 @end table
191 @end deftypefun
192
193 @deftypefun int address_is_group (address_t *@var{addr}, size_t @var{no}, size_t @var{len}, int* @var{yes})
194
195 Sets *@var{yes} to @code{1} if this address is just the name of a group,
196 @code{0} otherwise. This is faster than checking if the address has
197 a non-zero length personal, and a zero-length local_part and domain.
198
199 @var{yes} can be @code{nul}, though that doesn't serve much purpose other
200 than determining that @var{no} refers to an address.
201
202 Currently, there is no way to determine the end of the group.
203
204 The return value is @code{0} on success and a code number on error conditions:
205 @table @code
206 @ADDRESSEINVAL
207 @ADDRESSENOENT
208 @end table
209 @end deftypefun
210
211 @deftypefun int address_to_string (address_t *@var{addr}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
212
213 Returns the entire address list as a single RFC822 formatted address
214 list.
215
216 The return value is @code{0} on success and a code number on error conditions:
217 @table @code
218 @ADDRESSEINVAL
219 @ADDRESSENOMEM
220 @end table
221 @end deftypefun
222
223
224 @deftypefun int address_get_count (address_t @var{addr}, size_t* @var{count})
225
226 Returns a count of the addresses in the address list.
227
228 If @var{addr} is @code{nul}, the count is @code{0}. If @var{count} is
229 not @code{nul}, the count will be written to *@var{count}.
230
231 The return value is @code{0}.
232 @end deftypefun
233
234 @section Example
235 @example
236 @include ex-address.texi
237 @end example
238
1 @example
2 @code{/* Prefix @emph{attribute_} is reserved */}
3 @code{#include <mailutils/attribute.h>}
4
5 @end example
6
7 @deftypefun int attribute_create (attribute_t *@var{pattribute})
8 @end deftypefun
9
10 @deftypefun void attribute_destroy (attribute_t *@var{pattribute})
11 @end deftypefun
12
13 @deftypefun int attribute_is_seen (attribute_t @var{attribute})
14 @end deftypefun
15
16 @deftypefun int attribute_is_answered (attribute_t @var{attribute})
17 @end deftypefun
18
19 @deftypefun int attribute_is_flagged (attribute_t @var{attribute})
20 @end deftypefun
21
22 @deftypefun int attribute_is_deleted (attribute_t @var{attribute})
23 @end deftypefun
24
25 @deftypefun int attribute_is_draft (attribute_t @var{attribute})
26 @end deftypefun
27
28 @deftypefun int attribute_is_recent (attribute_t @var{attribute})
29 @end deftypefun
30
31 @deftypefun int attribute_is_read (attribute_t @var{attribute})
32 @end deftypefun
33
34 @deftypefun int attribute_set_seen (attribute_t @var{attribute})
35 @end deftypefun
36
37 @deftypefun int attribute_set_answered (attribute_t @var{attribute})
38 @end deftypefun
39
40 @deftypefun int attribute_set_flagged (attribute_t @var{attribute})
41 @end deftypefun
42
43 @deftypefun int attribute_set_deleted (attribute_t @var{attribute})
44 @end deftypefun
45
46 @deftypefun int attribute_set_draft (attribute_t @var{attribute})
47 @end deftypefun
48
49 @deftypefun int attribute_set_recent (attribute_t @var{attribute})
50 @end deftypefun
51
52 @deftypefun int attribute_set_read (attribute_t @var{attribute})
53 @end deftypefun
54
55
56 @deftypefun int attribute_unset_seen (attribute_t @var{attribute})
57 @end deftypefun
58
59 @deftypefun int attribute_unset_answered (attribute_t @var{attribute})
60 @end deftypefun
61
62 @deftypefun int attribute_unset_flagged (attribute_t @var{attribute})
63 @end deftypefun
64
65 @deftypefun int attribute_unset_deleted (attribute_t @var{attribute})
66 @end deftypefun
67
68 @deftypefun int attribute_unset_draft (attribute_t @var{attribute})
69 @end deftypefun
70
71 @deftypefun int attribute_unset_recent (attribute_t @var{attribute})
72 @end deftypefun
73
74 @deftypefun int attribute_unset_read (attribute_t @var{attribute})
75 @end deftypefun
76
77 @deftypefun int attribute_is_equal (attribute_t @var{att1}, attribute_t @var{att2})
78 @end deftypefun
79
80 @deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src})
81 @end deftypefun
82
83 @deftypefun int string_to_attribute (const char *@var{buf}, attribute_t *@var{pattr})
84 @end deftypefun
85
86 @deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{pwriten})
87 @end deftypefun
88
1 @example
2 @code{/* Prefix @emph{auth_} is reserved */}
3 @code{#include <mailutils/auth.h>}
4
5 @end example
6
7 There are many ways to authenticate to a server. To be flexible the
8 authentication process is provided by two objects @code{auth_t} and
9 @code{ticket_t}. The @code{auth_t} can implement different protocol like
10 APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox
11 does not understand or know how to authenticate it falls back to
12 user/passwd authentication. The @code{ticket_t} is a way for
13 Mailboxes and Mailers provide a way to authenticate when the URL does not
14 contain enough information. The default action is to call the function
15 @code{auth_authenticate} which will get the @emph{user} and @emph{passwd}
16 if not set, this function can be overriden by a custom method.
17
18 @deftypefun int auth_create (auth_t *@var{pauth}, void *@var{owner})
19 @end deftypefun
20
21 @deftypefun void auth_destroy (auth_t *@var{pauth}, void *@var{owner})
22 @end deftypefun
23
24 @deftypefun int auth_prologue (auth_t @var{auth})
25 @end deftypefun
26
27 @deftypefun int auth_authenticate (auth_t @var{auth}, char **@var{user}, char **@var{passwd})
28 @end deftypefun
29
30 @deftypefun int auth_epilogue (auth_t @var{auth})
31 @end deftypefun
32
33 A simple example of an authenticate function:
34 @example
35 #include <mailutils/auth.h>
36 #include <stdio.h>
37 #include <string.h>
38
39 int
40 my_authenticate (auth_t auth, char **user, char **passwd)
41 @{
42 char u[128] = "";
43 char p[128] = "";
44
45 /* prompt the user name */
46 printf ("User: ");
47 fflush (stdout);
48 fgets (u, sizeof (u), stdin);
49 u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */
50
51 /* prompt the passwd */
52 printf ("Passwd: "); fflush (stdout);
53 echo_off ();
54 fgets (p, sizeof(p), stdin);
55 echo_on ();
56 p[strlen (p) - 1] = '\0';
57
58 /* duplicate */
59 *user = strdup (u);
60 *passwd = strdup (p);
61 return 0;
62 @}
63 @end example
1 @example
2 @code{/* Prefix @emph{body_} is reserved */}
3 @code{#include <mailutils/body.h>}
4
5 @end example
6
7 @deftypefun int body_create (body_t *@var{body}, void *@var{owner})
8 Initialize an object @var{bdy}.
9 @end deftypefun
10
11 @deftypefun void body_destroy (body_t *@var{pbody})
12 The resources allocate are release.
13 @end deftypefun
14
15 @deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{pstream})
16 @end deftypefun
17
18 @deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner})
19 @end deftypefun
20
21 @deftypefun int body_get_filename __P ((body_t @var{body}, char *@var{buffer}, size_t@var{buflen}, size_t *@var{pwriten})
22 @end deftypefun
23
24 @deftypefun int body_set_filename (body_t @var{body}, const char*@var{buffer})
25 @end deftypefun
26
27 @deftypefun int body_size (body_t @var{body}, size_t*@var{psize})
28 @end deftypefun
29
30 @deftypefun int body_lines (body_t @var{body}, size_t *@var{plines})
31 @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 @section RFC1522
2 @cindex RFC1522
3
4 @section Quoted Printable
5 @cindex Quoted Printable
6
7 @section Base64
8 @cindex Base64
9
1 @example
2 @code{/* Prefix @emph{envelope_} is reserved */}
3 @code{#include <mailutils/envelope.h>}
4 @end example
5
6 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *);
7
8 Get the date that the message was delivered to the mailbox, in
9 something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999.
10
11 @end deftypefun
12
13 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *);
14
15 Get the address that this message was reportedly received from. This
16 would be the "mail from" argument if the message was delivered
17 or received via SMTP, for example.
18
19 @end deftypefun
20
21 @deftypefun int envelope_get_message (envelope_t, message_t *);
22 @end deftypefun
23
24 @deftypefun int envelope_create (envelope_t *, void *);
25 Primarily for internal use.
26 @end deftypefun
27
28 @deftypefun void envelope_destroy (envelope_t *, void *);
29 Primarily for internal use.
30 @end deftypefun
31
32 @deftypefun int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *);
33
34 Primarily for internal use. The implementation of envelope_t depends
35 on the mailbox type, this allows the function which actually gets
36 the sender to be set by the creator of an envelope_t.
37
38 @end deftypefun
39
40 @deftypefun int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *);
41
42 Primarily for internal use. The implementation of envelope_t depends
43 on the mailbox type, this allows the function which actually gets
44 the date to be set by the creator of an envelope_t.
45
46 @end deftypefun
1 #include <stdio.h>
2 #include <errno.h>
3 #include <mailutils/address.h>
4
5 #define EPARSE ENOENT
6
7 static const char* err_name(int e)
8 @{
9 struct @{
10 int e;
11 const char* s;
12 @} map[] = @{
13 #define E(e) @{ e, #e @},
14 E(ENOENT)
15 E(EINVAL)
16 E(ENOMEM)
17 #undef E
18 @{ 0, NULL @}
19 @};
20 static char s[sizeof(int) * 8 + 3];
21 int i;
22
23 for(i = 0; map[i].s; i++) @{
24 if(map[i].e == e)
25 return map[i].s;
26 @}
27 sprintf(s, "[%d]", e);
28
29 return s;
30 @}
31
32 static int parse(const char* str)
33 @{
34 size_t no = 0;
35 size_t pcount = 0;
36 int status;
37
38 char buf[BUFSIZ];
39
40 address_t address = NULL;
41
42 status = address_create(&address, str);
43
44 address_get_count(address, &pcount);
45
46 if(status) @{
47 printf("%s=> error %s\n\n", str, err_name(status));
48 return 0;
49 @} else @{
50 printf("%s=> pcount %d\n", str, pcount);
51 @}
52
53 for(no = 1; no <= pcount; no++) @{
54 size_t got = 0;
55 int isgroup;
56
57 address_is_group(address, no, &isgroup);
58
59 printf("%d ", no);
60
61 if(isgroup) @{
62 address_get_personal(address, no, buf, sizeof(buf), &got);
63
64 printf("group <%s>\n", buf);
65 @} else @{
66 address_get_email(address, no, buf, sizeof(buf), 0);
67
68 printf("email <%s>\n", buf);
69 @}
70
71 address_get_personal(address, no, buf, sizeof(buf), &got);
72
73 if(got && !isgroup) printf(" personal <%s>\n", buf);
74
75 address_get_comments(address, no, buf, sizeof(buf), &got);
76
77 if(got) printf(" comments <%s>\n", buf);
78
79 address_get_local_part(address, no, buf, sizeof(buf), &got);
80
81 if(got) @{
82 printf(" local-part <%s>", buf);
83
84 address_get_domain(address, no, buf, sizeof(buf), &got);
85
86 if(got) printf(" domain <%s>", buf);
87
88 printf("\n");
89 @}
90
91 address_get_route(address, no, buf, sizeof(buf), &got);
92
93 if(got) printf(" route <%s>\n", buf);
94 @}
95 address_destroy(&address);
96
97 printf("\n");
98
99 return 0;
100 @}
101
102 static int parseinput(void)
103 @{
104 char buf[BUFSIZ];
105
106 while(fgets(buf, sizeof(buf), stdin) != 0) @{
107 buf[strlen(buf) - 1] = 0;
108 parse(buf);
109 @}
110
111 return 0;
112 @}
113
114 int main(int argc, const char *argv[])
115 @{
116 argc = 1;
117
118 if(!argv[argc]) @{
119 return parseinput();
120 @}
121 for(; argv[argc]; argc++) @{
122 if(strcmp(argv[argc], "-") == 0) @{
123 parseinput();
124 @} else @{
125 parse(argv[argc]);
126 @}
127 @}
128
129 return 0;
130 @}
1 #include <mailutils/url.h>
2 #include <stdio.h>
3 #include <string.h>
4
5 int
6 main ()
7 @{
8 char str[1024];
9 char buffer[1024];
10 long port = 0;
11 int len = sizeof (buffer);
12 url_t u = NULL;
13
14 while (fgets (str, sizeof (str), stdin) != NULL)
15 @{
16 int rc;
17
18 str[strlen (str) - 1] = '\0'; /* chop newline */
19 if(strspn(str, " \t") == strlen(str))
20 continue; /* skip empty lines */
21 if ((rc = url_create(&u, str)) != 0)
22 @{
23 printf(stderr, "url_create %s ERROR: [%d] %s",
24 str, rc, strerror(rc));
25 exit (1);
26 @}
27 if ((rc = url_parse (u)) != 0)
28 @{
29 printf ("%s --> FAILED: [%d] %s\n",
30 str, rc, strerror(rc));
31 continue;
32 @}
33 printf ("%s --> SUCCESS\n", str);
34
35 url_get_scheme (u, buffer, len, NULL);
36 printf (" scheme <%s>\n", buffer);
37
38 url_get_user (u, buffer, len, NULL);
39 printf (" user <%s>\n", buffer);
40
41 url_get_passwd (u, buffer, len, NULL);
42 printf (" passwd <%s>\n", buffer);
43
44 url_get_auth (u, buffer, len, NULL);
45 printf (" auth <%s>\n", buffer);
46
47 url_get_host (u, buffer, len, NULL);
48 printf (" host <%s>\n", buffer);
49
50 url_get_port (u, &port);
51 printf (" port %ld\n", port);
52
53 url_get_path (u, buffer, len, NULL);
54 printf (" path <%s>\n", buffer);
55
56 url_get_query (u, buffer, len, NULL);
57 printf (" query <%s>\n", buffer);
58
59 url_destroy (&u);
60
61 @}
62 return 0;
63 @}
64
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:: Uniform Resource Locators.
16
17 @end menu
18
19 Whereever the mail is and whatever format it is stored in, the same operations
20 to manipulate emails are common. To unified the C API, GNU mailutils offers
21 a heteroclite set of objects that work in aggregation to do operations on
22 emails. Each object do a specific task and delegates 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 reserved */}
3 @code{#include <mailutils/header.h>}
4
5 @end example
6
7 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII
8 characters will be encoded.
9
10 @deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner})
11 Initialize a @var{hdr} to a supported type. If @var{blurb} is not NULL, it is
12 parsed.
13 @end deftypefun
14
15 @deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner})
16 The resources allocated for @var{hdr} are freed.
17 @end deftypefun
18
19 @deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, size_t n, int @var{replace})
20 Set the field-name @var{fn} to field-value @var{fv} of size @var{n} in
21 @var{hdr}. If @var{replace} is non-zero the initial value is replaced, if zero
22 it is appended.
23
24 Some basic macros are already provided for rfc822.
25
26 @table @code
27 @item MU_HDR_RETURN_PATH
28 Return-Path
29 @item MU_HDR_RECEIVED
30 Received
31 @item MU_HDR_DATE
32 Date
33 @item MU_HDR_FROM
34 From
35 @item MU_HDR_RESENT_FROM
36 Resent-From
37 @item MU_HDR_SUBJECT
38 Subject
39 @item MU_HDR_SENDER
40 Sender
41 @item MU_HDR_RESENT_SENDER
42 Resent-SENDER
43 @item MU_HDR_TO
44 To
45 @item MU_HDR_RESENT_TO
46 Resent-To
47 @item MU_HDR_CC
48 Cc
49 @item MU_HDR_RESENT_CC
50 Resent-Cc
51 @item MU_HDR_BCC
52 Bcc
53 @item MU_HDR_RESENT_BCC
54 Resent-Bcc
55 @item MU_HDR_REPLY_TO
56 Reply-To
57 @item MU_HDR_RESENT_REPLY_TO
58 Resent-Reply-To
59 @item MU_HDR_MESSAGE_ID
60 Message-ID
61 @item MU_HDR_RESENT_MESSAGE_ID
62 Resent-Message-ID
63 @item MU_HDR_IN_REPLY_TO
64 In-Reply-To
65 @item MU_HDR_ENCRYPTED
66 Encrypted
67 @item MU_HDR_PRECEDENCE
68 Precedence
69 @item MU_HDR_STATUS
70 Status
71 @item MU_HDR_CONTENT_LENGTH
72 Content-Length
73 @item MU_HDR_CONTENT_TYPE
74 Content-Type
75 @item MU_HDR_MIME_VERSION
76 MIME-Version
77 @end table
78
79 @end deftypefun
80
81 @deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n})
82 Value of field-name @var{fn} is returned in buffer @var{fv} of size @var{len}.
83 The number of bytes written is put in @var{n}.
84 @end deftypefun
85
86 @deftypefun int header_aget_value (header_t @var{hdr}, const char *@var{fn}, char **@var{fv})
87 The value is allocated.
88 @end deftypefun
89
90 @deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{pstream})
91 @end deftypefun
92
93 @deftypefun int header_set_size (header_t @var{hdr}, size_t *@var{size})
94 @end deftypefun
95
96 @deftypefun int header_set_lines (header_t @var{hdr}, size_t *@var{lpines})
97 @end deftypefun
1 @example
2 @code{/* Prefix @emph{imap4_} is reserved */}
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 reserved */}
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 reserved */}
3 @code{#include <mailutils/locker.h>}
4
5 @end example
6
7 @deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags})
8 @end deftypefun
9
10 @deftypefun void locker_destroy (locker_t * @var{plocker})
11 @end deftypefun
12
13 @deftypefun int locker_lock (locker_t @var{locker}, int @var{flag})
14 @table @code
15 @item MU_LOCKER_RDLOCK
16 @item MU_LOCKER_WRLOCK
17 @item MU_LOCKER_PID
18 @item MU_LOCKER_FCNTL
19 @item MU_LOCKER_TIME
20 @end table
21 @end deftypefun
22
23 @deftypefun int locker_touchlock (locker_t @var{locker})
24 @end deftypefun
25
26 @deftypefun int locker_unlock (locker_t @var{locker})
27 @end deftypefun
1 @example
2 @code{/* Prefix @emph{mailbox_} is reserved */}
3 @code{#include <mailutils/mailbox.h>}
4
5 @end example
6
7 @deftp {Data Type} mailbox_t
8 The @code{mailbox_t} object is used to hold information and it is an opaque
9 data structure to the user. Functions are provided to retrieve information
10 from the data structure.
11 @end deftp
12 @example
13 @group
14 mailbox_t url_t
15 -/var/mail- +---//---->/-----------------\ +-->/-----------\
16 ( alain ) | | url_t *-|----+ | port |
17 ----------- | |-----------------+ | hostname |
18 ( jakob *-)----+ | observer_t *-| | file |
19 ----------- |-----------------+ | ... |
20 ( jeff ) | stream_t | \-----------/
21 ----------- |-----------------|
22 ( sean ) | locker_t |
23 ---------- |-----------------|
24 | message_t(1) |
25 |-----------------|
26 | message_t(2) |
27 | ...... |
28 | message_t(n) |
29 \-----------------/
30 @end group
31 @end example
32
33 @deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
34 The @var{message} is appended to the mailbox @var{mbox}.
35
36 The return value is @code{0} on success and a code number on error conditions:
37 @table @code
38 @item MU_ERROR_INVALID_PARAMETER
39 @var{mbox} is null or @var{message} is invalid.
40 @end table
41 @end deftypefun
42
43 @deftypefun int mailbox_close (mailbox_t @var{mbox})
44 The stream attach to @var{mbox} is closed.
45
46 The return value is @code{0} on success and a code number on error conditions:
47 @table @code
48 @item MU_ERROR_INVALID_PARAMETER
49 @var{mbox} is null.
50 @end table
51 @end deftypefun
52
53 @deftypefun int mailbox_create (mailbox_t *@var{pmbox}, const char *@var{name})
54 The function @code{mailbox_create} allocates and initializes @var{pmbox}.
55 The concrete mailbox type instanciate is based on the scheme of the url @var{name}.
56
57 The return value is @code{0} on success and a code number on error conditions:
58 @table @code
59 @item MU_ERROR_INVALID_PARAMETER
60 The url @var{name} supplied is invalid or not supported.
61 @var{pmbox} is NULL.
62 @item ENOMEM
63 Not enough memory to allocate resources.
64 @end table
65 @end deftypefun
66
67 @deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{name})
68 Create a mailbox with @code{mailbox_create ()} based on the environment
69 variable @emph{$MAIL} or the string formed by
70 @emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null,
71 @end deftypefun
72
73 @deftypefun void mailbox_destroy (mailbox_t *@var{pmbox})
74 Destroys and releases resources held by @var{pmbox}.
75 @end deftypefun
76
77 @deftypefun int mailbox_expunge (mailbox_t @var{mbox})
78 All messages marked for deletion are removed.
79
80 The return value is @code{0} on success and a code number on error conditions:
81 @table @code
82 @item MU_ERROR_INVALID_PARAMETER
83 @var{mbox} is null.
84 @end table
85 @end deftypefun
86
87 @deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
88 Get the @var{folder}.
89
90 The return value is @code{0} on success and a code number on error conditions:
91 @table @code
92 @item MU_ERROR_INVALID_PARAMETER
93 @var{mbox} is null.
94 @end table
95 @end deftypefun
96
97 @deftypefun int mailbox_get_debug (mailbox_t @var{mbox}, debug_t *@var{debug})
98 Get a debug object.
99 The return value is @code{0} on success and a code number on error conditions:
100 @table @code
101 @item MU_ERROR_INVALID_PARAMETER
102 @var{mbox} is null.
103 @item ENOMEM
104 @end table
105 @end deftypefun
106
107 @deftypefun int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{plocker})
108 Return the @var{locker} object.
109
110 The return value is @code{0} on success and a code number on error conditions:
111 @table @code
112 @item MU_ERROR_INVALID_PARAMETER
113 @var{mbox} is null.
114 @end table
115 @end deftypefun
116
117 @deftypefun int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{pmessage})
118 Retreive message number @var{msgno}, @var{pmessage} is allocated and
119 initialized.
120
121 The return value is @code{0} on success and a code number on error conditions:
122 @table @code
123 @item MU_ERROR_INVALID_PARAMETER
124 @var{mbox} is null or @var{msgno} is invalid.
125 @item ENOMEM
126 Not enough memory.
127 @end table
128 @end deftypefun
129
130 @deftypefun int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t*@var{observable})
131 Get the observable object.
132
133 The return value is @code{0} on success and a code number on error conditions:
134 @table @code
135 @item MU_ERROR_INVALID_PARAMETER
136 @var{mbox} is null.
137 @item ENOMEM
138 Not enough memory.
139 @end table
140 @end deftypefun
141
142 @deftypefun int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property})
143 Get the property object.
144 The return value is @code{0} on success and a code number on error conditions:
145 @table @code
146 @item MU_ERROR_INVALID_PARAMETER
147 @var{mbox} is null.
148 @item ENOMEM
149 @end table
150 @end deftypefun
151
152 @deftypefun int mailbox_get_size (mailbox_t @var{mbox}, off_t *@var{psize})
153 Gives the @var{mbox} size.
154
155 The return value is @code{0} on success and a code number on error conditions:
156 @table @code
157 @item MU_ERROR_INVALID_PARAMETER
158 @var{mbox} is null.
159 @end table
160 @end deftypefun
161
162 @deftypefun int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{pstream})
163 The mailbox stream is put in @var{pstream}.
164
165 The return value is @code{0} on success and a code number on error conditions:
166 @table @code
167 @item MU_ERROR_INVALID_PARAMETER
168 @var{mbox} is invalid or @var{pstream} is NULL.
169 @end table
170 @end deftypefun
171
172 @deftypefun int mailbox_get_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
173 The return value is @code{0} on success and a code number on error conditions:
174
175 @table @code
176 @item MU_ERROR_INVALID_PARAMETER
177 @var{mbox} is null.
178 @end table
179 @end deftypefun
180
181 @deftypefun int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{purl})
182 Gives the constructed @var{url}.
183
184 The return value is @code{0} on success and a code number on error conditions:
185 @table @code
186 @item MU_ERROR_INVALID_PARAMETER
187 @var{mbox} is null.
188 @end table
189 @end deftypefun
190
191 @deftypefun int mailbox_is_modified (mailbox_t @var{mbox})
192 Check if the mailbox been modified by an external source.
193
194 The return value is @code{0} on success and a code number on error conditions:
195 @table @code
196 @item MU_ERROR_INVALID_PARAMETER
197 @var{mbox} is null.
198 @end table
199 @end deftypefun
200
201 @deftypefun int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{pnumber});
202 Give the number of first unseen message in @var{mbox}.
203
204 The return value is @code{0} on success and a code number on error conditions:
205 @table @code
206 @item MU_ERROR_INVALID_PARAMETER
207 @var{mbox} is null.
208 @end table
209 @end deftypefun
210
211 @deftypefun int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{pnumber});
212 Give the number of messages in @var{mbox}.
213
214 The return value is @code{0} on success and a code number on error conditions:
215 @table @code
216 @item MU_ERROR_INVALID_PARAMETER
217 @var{mbox} is null.
218 @end table
219 @end deftypefun
220
221 @deftypefun int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{pnumber});
222 Give the number of recent messages in @var{mbox}.
223
224 The return value is @code{0} on success and a code number on error conditions:
225 @table @code
226 @item MU_ERROR_INVALID_PARAMETER
227 @var{mbox} is null.
228 @end table
229 @end deftypefun
230
231 @deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag})
232 A connection is open, if no stream was provided, a stream
233 is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
234 See @code{stream_create} for @var{flag}'s description.
235
236 The return value is @code{0} on success and a code number on error conditions:
237 @table @code
238 @item EAGAIN
239 @itemx EINPROGRESS
240 Operation in progress.
241 @item EBUSY
242 Resource busy.
243 @item MU_ERROR_INVALID_PARAMETER
244 @var{mbox} is null or flag is invalid.
245 @item ENOMEM
246 Not enough memory.
247 @end table
248 @end deftypefun
249
250 @deftypefun int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{pcount});
251 Scan the mailbox for new messages starting at message @var{msgno}.
252
253 The return value is @code{0} on success and a code number on error conditions:
254 @table @code
255 @item MU_ERROR_INVALID_PARAMETER
256 @var{mbox} is null.
257 @item ENOMEM
258 Not enough memory.
259 @end table
260 @end deftypefun
261
262 @deftypefun int mailbox_set_locker (mailbox_t @var{mbox}, locker_t @var{locker})
263 Set the type of locking done by the @var{mbox}.
264
265 The return value is @code{0} on success and a code number on error conditions:
266 @table @code
267 @item MU_ERROR_INVALID_PARAMETER
268 @var{mbox} is null.
269 @end table
270 @end deftypefun
271
272 @deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream})
273 Set the @var{stream} connection to use for the mailbox.
274
275 The return value is @code{0} on success and a code number on error conditions:
276 @table @code
277 @item MU_ERROR_INVALID_PARAMETER
278 @var{mbox} or @var{stream} is NULL.
279 @end table
280 @end deftypefun
281
282 @deftypefun int mailbox_set_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
283 The @var{ticket} will be set on the @code{auth_t} object on creation.
284
285 The return value is @code{0} on success and a code number on error conditions:
286 @table @code
287 @item MU_ERROR_INVALID_PARAMETER
288 @var{mbox} is null.
289 @end table
290 @end deftypefun
291
292 @deftypefun int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{pnumber});
293 Give the next predicted uid for @var{mbox}.
294
295 The return value is @code{0} on success and a code number on error conditions:
296 @table @code
297 @item MU_ERROR_INVALID_PARAMETER
298 @var{mbox} is null.
299 @end table
300 @end deftypefun
301
302 @deftypefun int mailbox_uidvalidity (mailbox_t @var{mbox}, size_t *@var{pnumber});
303 Give the uid validity of @var{mbox}.
304
305 The return value is @code{0} on success and a code number on error conditions:
306 @table @code
307 @item MU_ERROR_INVALID_PARAMETER
308 @var{mbox} is null.
309 @end table
310 @end deftypefun
1 @example
2 @code{/* Prefix @emph{maildir_} is reserved */}
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 reserved */}
3 @code{#include <mailutils/mailer.h>}
4
5 @end example
6
7 The API is still shaky and undefined.
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
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename mailutils.info
4 @settitle mailutils, Programming Manual
5 @c %**end of header
6
7 @c This file has the new style title page commands.
8 @c Run `makeinfo' rather than `texinfo-format-buffer'.
9
10 @c smallbook
11
12 @c tex
13 @c \overfullrule=0pt
14 @c end tex
15
16 @include version.texi
17
18 @c Combine indices.
19 @syncodeindex ky cp
20 @syncodeindex pg cp
21 @syncodeindex tp cp
22
23 @defcodeindex op
24 @syncodeindex op fn
25 @syncodeindex vr fn
26
27 @ifinfo
28 @direntry
29 * mailutils: (libmailutils). The GNU mailutils library API.
30 @end direntry
31 This file documents @sc{mailutils}, library API.
32
33
34 Published by the Free Software Foundation,
35 59 Temple Place - Suite 330
36 Boston, MA 02111-1307, USA
37
38 Copyright 1999, 2000 Free Software Foundation, Inc.
39
40 Permission is granted to make and distribute verbatim copies of
41 this manual provided the copyright notice and this permission notice
42 are preserved on all copies.
43
44 @ignore
45 Permission is granted to process this file through TeX and print the
46 results, provided the printed document carries copying permission
47 notice identical to this one except for the removal of this paragraph
48 (this paragraph not being relevant to the printed manual).
49
50 @end ignore
51 Permission is granted to copy and distribute modified versions of this
52 manual under the conditions for verbatim copying, provided that the entire
53 resulting derived work is distributed under the terms of a permission
54 notice identical to this one.
55
56 Permission is granted to copy and distribute translations of this manual
57 into another language, under the above conditions for modified versions,
58 except that this permission notice may be stated in a translation approved
59 by the Foundation.
60 @end ifinfo
61
62 @setchapternewpage off
63
64 @titlepage
65 @title mailutils, SDK.
66 @subtitle version @value{VERSION}, @value{UPDATED}
67 @author Alain Magloire et al.
68
69 @page
70 @vskip 0pt plus 1filll
71 Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
72
73 @sp 2
74 Published by the Free Software Foundation, @*
75 59 Temple Place - Suite 330, @*
76 Boston, MA 02111-1307, USA
77
78 Permission is granted to make and distribute verbatim copies of
79 this manual provided the copyright notice and this permission notice
80 are preserved on all copies.
81
82 Permission is granted to copy and distribute modified versions of this
83 manual under the conditions for verbatim copying, provided that the entire
84 resulting derived work is distributed under the terms of a permission
85 notice identical to this one.
86
87 Permission is granted to copy and distribute translations of this manual
88 into another language, under the above conditions for modified versions,
89 except that this permission notice may be stated in a translation approved
90 by the Foundation.
91
92 @end titlepage
93 @page
94
95 @summarycontents
96 @page
97
98 @node Top, Introduction, (dir), (dir)
99 @comment node-name, next, previous, up
100
101 @ifinfo
102 This document was produced for version @value{VERSION} of @sc{gnu}
103 @sc{mailutils}.
104 @end ifinfo
105 @menu
106 * Introduction:: GNU @sc{mailutils}
107 * Concrete API:: Concrete API.
108 * Framework:: Framework.
109 * Programs:: Programs.
110 * Reporting Bugs:: Reporting Bugs.
111 * Acknowledgement:: Thanks and Credits.
112 * Concept Index:: All @sc{Mailutils} Functions.
113 * Index::
114
115 @end menu
116
117 @node Introduction, Concrete API, Top, Top
118 @comment node-name, next, previous, up
119 @chapter Introduction
120 @cindex Introduction
121
122 @sc{gnu} @sc{Mailutils} offers a general purpose library whose aim is to
123 provide a rich set of functions for accessing different mailbox formats and
124 mailers.
125
126 @section References
127
128 For more information on,
129
130 @itemize @bullet
131 @item
132 SMTP
133
134 @itemize @minus
135 @item
136 @cite{RFC 2821: Simple Mail Transfer Protocol}
137
138 @item
139 @cite{RFC 2368: The mailto URL scheme}
140 @end itemize
141
142 @item
143 POP3
144
145 @itemize @minus
146 @item
147 @cite{RFC 1939: Post Office Protocol - Version 3}
148
149 @item
150 @cite{RFC 1734: POP3 AUTHentication command}
151
152 @item
153 @cite{RFC 1957: Some Observations on Implementations of the Post Office
154 Protocol (POP3)}
155
156 @item
157 @cite{RFC 2449: POP3 Extension Mechanism}
158
159 @item
160 @cite{RFC 2384: POP URL Scheme}
161 @end itemize
162
163 @item
164 IMAP4
165
166 @itemize @minus
167 @item
168 @cite{RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1}
169
170 @item
171 @cite{RFC 2088: IMAP4 non-synchronizing literals}
172
173 @item
174 @cite{RFC 2193: IMAP4 Mailbox Referrals}
175
176 @item
177 @cite{RFC 2221: IMAP4 Login Referrals}
178
179 @item
180 @cite{RFC 2342: IMAP4 Namespace}
181
182 @item
183 @cite{RFC 2192: IMAP URL Scheme}
184
185 @item
186 @cite{RFC 1731: IMAP4 Authentication Mechanisms}
187
188 @item
189 @cite{RFC 2245: Anonymous SASL Mechanism}
190
191 @end itemize
192
193 @item
194 message formats
195
196 @itemize @minus
197 @item
198 @cite{RFC 2822: Internet Message Format}
199
200 @item
201 @cite{RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One:
202 Format of Internet Message Bodies}
203
204 @item
205 @cite{RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two:
206 Media Types}
207
208 @item
209 @cite{RFC 2047: Multipurpose Internet Mail Extensions (MIME) Part Three:
210 Message Header Extensions for Non-ASCII Text}
211
212 @item
213 @cite{RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part Five:
214 Conformance Criteria and Examples}
215
216 @item
217 @cite{RFC 2111: Content-ID and Message-ID Uniform Resource Locators}
218 @end itemize
219
220 @item
221 miscellaneous related topics
222
223 @itemize @minus
224 @item
225 @cite{RFC 3028: Sieve: A Mail Filtering Language}
226
227 @item
228 @cite{RFC 2298: An Extensible Message Format for Message Disposition
229 Notifications}
230
231 @item
232 @cite{RFC 1738: Uniform Resource Locators (URL)}
233
234 @item
235 @cite{Internet Email Protocols: A Developer's Guide, by Kevin Johnson}
236 @end itemize
237
238 @end itemize
239
240 @node Concrete API, Framework, Introduction, Top
241 @comment node-name, next, previous, up
242 @chapter Concrete API
243 @cindex Concrete API
244
245 @include c-api.texi
246
247 @node Framework, Programs, Concrete API, Top
248 @comment node-name, next, previous, up
249 @chapter Framework
250 @cindex Framework
251
252 @include framework.texi
253
254 @node Programs, Reporting Bugs, Framework, Top
255 @comment node-name, next, previous, up
256 @chapter Programs
257 @cindex Programs
258
259 @include programs.texi
260
261 @node Reporting Bugs, Acknowledgement, Programs, Top
262 @comment node-name, next, previous, up
263 @chapter Reporting Bugs
264 @cindex Reporting Bugs
265
266 Email bug reports to @email{bug-mailutils@@gnu.org}.
267 Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field.
268
269 @node Acknowledgement, Concept Index , Reporting Bugs, Top
270 @comment node-name, next, previous, up
271 @chapter Acknowledgement
272 @cindex Acknowledgement
273
274 In no particular order,
275 Jakob Kaivo @email{jkaivo@@ndn.net},
276 Jeff Bailey @email{jbailey@@gnu.org},
277 Sean Perry @email{shaleh@@debian.org},
278 Thomas Fletcher @email{thomasf@@qnx.com},
279 Dave Inglis @email{dinglis@@qnx.com},
280 Brian Edmond @email{briane@@qnx.com},
281 Sam Roberts @email{sroberts@@uniserve.com},
282 Sergey Poznyakoff @email{gray@@Mirddin.farlep.net},
283 Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}.
284 @page
285
286 @node Concept Index, Index, Acknowledgement, Top
287 @comment node-name, next, previous, up
288 @unnumbered Concept Index
289
290 This is a general index of all issues discussed in this manual
291
292 @printindex cp
293 @page
294
295 @node Index, , Concept Index, Top
296 @comment node-name, next, previous, up
297 @unnumbered Index
298
299 This is an alphabetical list of all @sc{mailutils} functions.
300
301 @printindex fn
302
303 @contents
304
305 @bye
1 @example
2 @code{/* Prefix @emph{mbox_} is reserved */}
3 @code{#include <mailutils/mbox.h>}
4
5 @end example
6
7 The most common mailbox format on UNIX platform is @emph{mbox}. Mbox file
8 is messages separated by the special format string.
9 @example
10 From SP envelope-sender SP date [SP moreinfo]
11 @end example
12
13 @table @code
14 @item "From "
15 is sometimes call the @emph{From_}.
16 @item evelope-sender
17 is a word with no space.
18 @item date
19 has the same format as @code{asctime ()}
20 @item moreinfo
21 are optional values that are seldom used.
22 @end table
23
24 A @var{mbox_t} is created, initialised and destroyed by @code{mbox_create ()}
25 and @code{mbox_destroy ()}. When opening, @code{mbox_open ()} will do a quick
26 check to see if the format is a valid format or an empty file. The scanning
27 of the mailbox is done by @code{mbox_scan ()}.
28 The function, @code{mbox_scan ()}, takes callback functions called during the
29 scanning to provide information. The scanning will cache some of the headers
30 fields for speed. Closing the mailbox, @code{mbox_close ()} will free
31 any ressources like, headers cache, locks etc ... All the messages with
32 attributes marked deleted will only be removed on @code{mbox_expunge ()}.
33 If only the attributes need to be save but the messages not removed, this
34 can be done by @code{mbox_save_attributes ()}. New messages are added with
35 @code{mbox_append ()}. Attributes are saved in the @emph{Status:} header
36 field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.
37
38 @subsubsection Initialisation
39 @cindex Mbox Initialisation
40
41 @deftypefun int mbox_create (mbox_t *@var{mbox})
42
43 Allocate and initialize a @var{mbox} handle.
44
45 @table @code
46 @item MU_ERROR_NO_MEMORY
47 @item MU_ERROR_INVALID_PARAMETER
48 @end table
49 @end deftypefun
50
51 @deftypefun void mbox_destroy (mbox_t @var{mbox})
52
53 When a POP3 session is finished, the structure must be @code{free ()}'ed to
54 reclaim memory.
55 @end deftypefun
56
57 @subsubsection Carrier
58 @cindex Mbox channel
59
60 @deftypefun int mbox_set_carrier (mbox_t, stream_t @var{carrier});
61
62 Another type of stream can be provided to work on, the @var{carrier}
63 is set in the @var{mbox_t} handle. Any previous @var{carrier} stream in
64 the handle, will be close and release. Since the parsing code
65 maintain only the offsets off the message the @var{carrier} stream must be
66 seekable.
67
68 @table @code
69 @item MU_ERROR_INVALID_PARAMETER
70 @end table
71 @end deftypefun
72
73 @deftypefun int mbox_get_carrier (mbox_t, stream_t *@var{carrier});
74
75 Return the @var{mbox_t} carrier. If none was set, a new file stream will be
76 created.
77
78 @table @code
79 @item MU_ERROR_INVALID_PARAMETER
80 @item MU_ERROR_NO_MEMORY
81 @end table
82 @end deftypefun
83
84 @deftypefun int mbox_open (mbox_t, const char *@var{filename}, int @var{flags})
85
86 Open carrier stream with @var{filename} and @var{flags}. The stream will be
87 quickly examine to see if it is a mbox format.
88
89 @table @code
90 @item MU_ERROR_INVALID_PARAMETER
91 @item MU_ERROR_NO_MEMORY
92 @item MU_ERROR_NO_ENTRY
93 @item MU_ERROR_NO_ACCESS
94 @item MU_ERROR_NOT_SUPPORTED
95 @end table
96 @end deftypefun
97
98 @deftypefun int mbox_close (mbox_t)
99
100 Close the carrier stream and ressources particular to the mailbox.
101
102 @table @code
103 @item MU_ERROR_INVALID_PARAMETER
104 @item MU_ERROR_NO_MEMORY
105 @end table
106 @end deftypefun
107
108 @deftypefun int mbox_uidnext (mbox_t, unsigned long *@var{uidnext})
109
110 Return the uidnext, if the @var{mbox_t} was not scan @code{mbox_scan ()}
111 is called first.
112
113 @table @code
114 @item MU_ERROR_INVALID_PARAMETER
115 @item same as @code{mbox_scan ()}
116 @end table
117 @end deftypefun
118
119 @deftypefun int mbox_uidvalidity (mbox_t, unsigned long *@var{uidvalidity})
120
121 Return the uidvalidity, if the @var{mbox_t} was not scan @code{mbox_scan ()}
122 is called first.
123
124 @table @code
125 @item MU_ERROR_INVALID_PARAMETER
126 @item same as @code{mbox_scan ()}
127 @end table
128 @end deftypefun
129
130 @deftypefun int mbox_get_attribute (mbox_t, unsigned int @var{msgno}, attribute_t *@var{attribute})
131
132 Return an @var{attribute} to indicate the status of message number @var{msgno}.
133
134 @table @code
135 @item MU_ERROR_INVALID_PARAMETER
136 @item MU_ERROR_NO_MEMORY
137 @end table
138 @end deftypefun
139
140 @deftypefun int mbox_get_separator (mbox_t, unsigned int @var{msgno}, char **@var{sep})
141
142 Return an allocated string in @var{sep} containing the value "From " separating
143 each message in Unix mbox format. The string should be @code{free ()}ed by
144 the caller.
145
146 @table @code
147 @item MU_ERROR_INVALID_PARAMETER
148 @item MU_ERROR_NO_MEMORY
149 @end table
150 @end deftypefun
151
152 @deftypefun int mbox_set_separator (mbox_t, unsigned int @var{msgno}, const char *@var{sep})
153
154 The variable @var{sep} should contain a valid "From " separtor that will be use
155 when the expunging.
156
157 @table @code
158 @item MU_ERROR_INVALID_PARAMETER
159 @item MU_ERROR_NO_MEMORY
160 @end table
161 @end deftypefun
162
163 @deftypefun int mbox_get_hstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})
164
165 Return a @var{stream} to read the header of message @var{msgno}. The
166 @var{stream} should be destroy after usage.
167
168 @table @code
169 @item MU_ERROR_INVALID_PARAMETER
170 @item MU_ERROR_NO_MEMORY
171 @end table
172 @end deftypefun
173
174 @deftypefun int mbox_set_hstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})
175
176 Use @var{stream} when expunging for message @var{msgno}.
177
178 @table @code
179 @item MU_ERROR_INVALID_PARAMETER
180 @end table
181 @end deftypefun
182
183 @deftypefun int mbox_set_hsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
184
185 Return the @var{size} of message @var{msgno}.
186
187 @table @code
188 @item MU_ERROR_INVALID_PARAMETER
189 @end table
190 @end deftypefun
191
192 @deftypefun int mbox_set_hlines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
193
194 Return the number of @var{lines} of message @var{msgno}.
195
196 @table @code
197 @item MU_ERROR_INVALID_PARAMETER
198 @end table
199 @end deftypefun
200
201 @deftypefun int mbox_get_bstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})
202
203 Return a @var{stream} to read the body of message @var{msgno}. The
204 @var{stream} should be destroy after usage.
205
206 @table @code
207 @item MU_ERROR_INVALID_PARAMETER
208 @item MU_ERROR_NO_MEMORY
209 @end table
210 @end deftypefun
211
212 @deftypefun int mbox_set_bstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})
213
214 Use @var{stream} when expunging for message @var{msgno}.
215
216 @table @code
217 @item MU_ERROR_INVALID_PARAMETER
218 @end table
219 @end deftypefun
220
221 @deftypefun int mbox_set_bsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
222
223 Return the @var{size} of message @var{msgno}.
224
225 @table @code
226 @item MU_ERROR_INVALID_PARAMETER
227 @end table
228 @end deftypefun
229
230 @deftypefun int mbox_set_blines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
231
232 Return the number of @var{lines} of message @var{msgno}.
233
234 @table @code
235 @item MU_ERROR_INVALID_PARAMETER
236 @end table
237 @end deftypefun
238
239 @deftypefun int mbox_get_size (mbox_t, unsigned int *@var{size})
240
241 Return the @var{size} of mailbox.
242
243 @table @code
244 @item MU_ERROR_INVALID_PARAMETER
245 @end table
246 @end deftypefun
247
248 @deftypefun int mbox_save (mbox_t)
249
250 Save the changes to the messages back to the mailbox, but do not
251 remove messages mark for deletion in the process.
252
253 @table @code
254 @item MU_ERROR_INVALID_PARAMETER
255 @end table
256 @end deftypefun
257
258 @deftypefun int mbox_mak_deleted (mbox_t, unsigned int @var{msgno})
259
260 Mark @var{msgno} for deletion.
261
262 @table @code
263 @item MU_ERROR_INVALID_PARAMETER
264 @end table
265 @end deftypefun
266
267 @deftypefun int mbox_unmak_deleted (mbox_t, unsigned int @var{msgno})
268
269 Unmark @var{msgno} if it was marked for deletion.
270
271 @table @code
272 @item MU_ERROR_INVALID_PARAMETER
273 @end table
274 @end deftypefun
275
276 @deftypefun int mbox_expunge (mbox_t)
277
278 Save the changes to the mailbox and in the process remove all messages
279 marked for deletion.
280
281 @table @code
282 @item MU_ERROR_INVALID_PARAMETER
283 @end table
284 @end deftypefun
285
286 @deftypefun int mbox_append (mbox_t, const char *@var{sep}, stream_t @var{stream})
287
288 Append to the mailbox an rfc822 message represented by @var{stream}.
289 The variable @var{sep} should contain a valid "From " separator or
290 NULL to get the default.
291
292 @table @code
293 @item MU_ERROR_INVALID_PARAMETER
294 @end table
295 @end deftypefun
296
297 @deftypefun int mbox_append_hb (mbox_t, const char *@var{sep}, stream_t @var{hstream}, stream_t @var{bstream})
298
299 Append to the mailbox an rfc822 message represented by a header, @var{hstream},
300 and a body, @var{bstream}. The variable @var{sep} should contain a valid
301 "From " separator or NULL to get the default.
302
303 @table @code
304 @item MU_ERROR_INVALID_PARAMETER
305 @end table
306 @end deftypefun
307
308 @deftypefun int mbox_scan (mbox_t, unsigned int start, unsigned int *@var{count})
309
310 Start scanning the mailbox for new messages. The variable @var{start} can be
311 a message number starting point. The result of the scanning will be in
312 @var{count}. The scanning will trigger the @code{mbox_newmsg_cb()} callback
313 for each new message and @code{mbox_progress_cb ()} at different interval
314 to notify progression. The return values of the those callback should be
315 0 is different then 0 the scanning will be stop an the function returns
316 MU_ERROR_INTERRUPTED.
317
318 @table @code
319 @item MU_ERROR_INVALID_PARAMETER
320 @item MU_ERROR_INTERRUPTED
321 @item MU_ERROR_NO_MEMORY
322 @end table
323 @end deftypefun
324
325 @deftypefun int mbox_set_progress_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})
326
327 Set the callback function for progress. The variable @var{arg} will be pass
328 back in the callback as the second argument.
329 @table @code
330 @item MU_ERROR_INVALID_PARAMETER
331 @end table
332 @end deftypefun
333
334 @deftypefun int mbox_set_newmsg_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})
335
336 Set the callback function for new messages. The variable @var{arg} will be
337 pass back in the callback as the second argument.
338
339 @table @code
340 @item MU_ERROR_INVALID_PARAMETER
341 @end table
342 @end deftypefun
1 @example
2 @code{#include <mailutils/message.h>}
3 @code{/* Prefix @emph{message_} is reserve */}
4
5 @end example
6
7 The @code{message_t} object is a convenient way to manipulate messages. It
8 encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
9
10 @example
11 @group
12 mailbox_t
13 __________ message_t
14 (message[1]) +------>+-----------------------+
15 ---------- | | envelope_t |
16 (message[2]) | |-----------------------|
17 ---------- | | header_t |
18 (message[3])--------+ |-----------------------|
19 ---------- | body_t |
20 (message[n]) |-----------------------|
21 ---------- | attribute_t |
22 |-----------------------|
23 | stream_t |
24 +-----------------------+
25 @end group
26 @end example
27
28 @deftypefun void message_create (message_t *@var{msg}, void *@var{owner})
29 @end deftypefun
30
31 @deftypefun void message_destroy (message_t *@var{msg}, void *@var{owner})
32 The resources allocate for @var{msg} are freed.
33 @end deftypefun
34
35 @deftypefun int message_get_header (message_t @var{msg}, header_t *@var{pheader})
36 Retrieve @var{msg} header.
37 @end deftypefun
38
39 @deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner})
40 @end deftypefun
41
42 @deftypefun int message_get_body (message_t @var{msg}, body_t *@var{pbody})
43 @end deftypefun
44
45 @deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner})
46 @end deftypefun
47
48 @deftypefun int message_is_multipart (message_t @var{msg})
49 Return non-zero value if message is multi-part.
50 @end deftypefun
51
52 @deftypefun int message_get_num_parts (message_t @var{msg}, size_t *nparts)
53 @end deftypefun
54
55 @deftypefun int message_get_part (message_t @var{msg}, size_t part, message_t *msg)
56 @end deftypefun
57
58 @deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{pstream})
59 @end deftypefun
60
61 @deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream},void *@var{owner} )
62 @end deftypefun
63
64 @deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{pattribute})
65 @end deftypefun
66
67 @deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *owner)
68 @end deftypefun
69
70 @deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *penvelope)
71 @end deftypefun
72
73 @deftypefun int message_set_envelope (message_t @var{msg}, envelope_t envelope, void *@var{owner})
74 @end deftypefun
75
76 @deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid})
77 @end deftypefun
78
79 @deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten})
80 @end deftypefun
81
82 @deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl})(message_t, char *, size_t, size_t *), void *@var{owner})
83 @end deftypefun
84
85 @deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable})
86 @end deftypefun
87
88 @deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg})
89 @end deftypefun
90
91 @deftypefun int message_save_attachment (message_t @var{msg}, const char *@var{filename}, void **@var{data})
92 @end deftypefun
93
94 @deftypefun int message_encapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data})
95 @end deftypefun
96
97 @deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data});
98 @end deftypefun
1 @example
2 @code{/* Prefix @emph{mh_} is reserved */}
3 @code{#include <mailutils/mh.h>}
4
5 @end example
6
7 Mail Handler mailbox format. Not implemented.
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 reserved */}
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 reserved */}
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
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
2
3
4
5
6
7 Network Working Group J. Myers
8 Request for Comments: 1734 Carnegie Mellon
9 Category: Standards Track December 1994
10
11
12 POP3 AUTHentication command
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22
23 1. Introduction
24
25 This document describes the optional AUTH command, for indicating an
26 authentication mechanism to the server, performing an authentication
27 protocol exchange, and optionally negotiating a protection mechanism
28 for subsequent protocol interactions. The authentication and
29 protection mechanisms used by the POP3 AUTH command are those used by
30 IMAP4.
31
32
33 2. The AUTH command
34
35 AUTH mechanism
36
37 Arguments:
38 a string identifying an IMAP4 authentication mechanism,
39 such as defined by [IMAP4-AUTH]. Any use of the string
40 "imap" used in a server authentication identity in the
41 definition of an authentication mechanism is replaced with
42 the string "pop".
43
44 Restrictions:
45 may only be given in the AUTHORIZATION state
46
47 Discussion:
48 The AUTH command indicates an authentication mechanism to
49 the server. If the server supports the requested
50 authentication mechanism, it performs an authentication
51 protocol exchange to authenticate and identify the user.
52 Optionally, it also negotiates a protection mechanism for
53 subsequent protocol interactions. If the requested
54 authentication mechanism is not supported, the server
55
56
57
58 Myers [Page 1]
59
60 RFC 1734 POP3 AUTH December 1994
61
62
63 should reject the AUTH command by sending a negative
64 response.
65
66 The authentication protocol exchange consists of a series
67 of server challenges and client answers that are specific
68 to the authentication mechanism. A server challenge,
69 otherwise known as a ready response, is a line consisting
70 of a "+" character followed by a single space and a BASE64
71 encoded string. The client answer consists of a line
72 containing a BASE64 encoded string. If the client wishes
73 to cancel an authentication exchange, it should issue a
74 line with a single "*". If the server receives such an
75 answer, it must reject the AUTH command by sending a
76 negative response.
77
78 A protection mechanism provides integrity and privacy
79 protection to the protocol session. If a protection
80 mechanism is negotiated, it is applied to all subsequent
81 data sent over the connection. The protection mechanism
82 takes effect immediately following the CRLF that concludes
83 the authentication exchange for the client, and the CRLF of
84 the positive response for the server. Once the protection
85 mechanism is in effect, the stream of command and response
86 octets is processed into buffers of ciphertext. Each
87 buffer is transferred over the connection as a stream of
88 octets prepended with a four octet field in network byte
89 order that represents the length of the following data.
90 The maximum ciphertext buffer length is defined by the
91 protection mechanism.
92
93 The server is not required to support any particular
94 authentication mechanism, nor are authentication mechanisms
95 required to support any protection mechanisms. If an AUTH
96 command fails with a negative response, the session remains
97 in the AUTHORIZATION state and client may try another
98 authentication mechanism by issuing another AUTH command,
99 or may attempt to authenticate by using the USER/PASS or
100 APOP commands. In other words, the client may request
101 authentication types in decreasing order of preference,
102 with the USER/PASS or APOP command as a last resort.
103
104 Should the client successfully complete the authentication
105 exchange, the POP3 server issues a positive response and
106 the POP3 session enters the TRANSACTION state.
107
108 Possible Responses:
109 +OK maildrop locked and ready
110 -ERR authentication exchange failed
111
112
113
114 Myers [Page 2]
115
116 RFC 1734 POP3 AUTH December 1994
117
118
119
120 Examples:
121 S: +OK POP3 server ready
122 C: AUTH KERBEROS_V4
123 S: + AmFYig==
124 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
125 +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
126 WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
127 S: + or//EoAADZI=
128 C: DiAF5A4gA+oOIALuBkAAmw==
129 S: +OK Kerberos V4 authentication successful
130 ...
131 C: AUTH FOOBAR
132 S: -ERR Unrecognized authentication type
133
134 Note: the line breaks in the first client answer are
135 for editorial clarity and are not in real authentica-
136 tors.
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170 Myers [Page 3]
171
172 RFC 1734 POP3 AUTH December 1994
173
174
175 3. Formal Syntax
176
177 The following syntax specification uses the augmented Backus-Naur
178 Form (BNF) notation as specified in RFC 822.
179
180 Except as noted otherwise, all alphabetic characters are case-
181 insensitive. The use of upper or lower case characters to define
182 token strings is for editorial clarity only. Implementations MUST
183 accept these strings in a case-insensitive fashion.
184
185 ATOM_CHAR ::= <any CHAR except atom_specials>
186
187 atom_specials ::= "(" / ")" / "{" / SPACE / CTLs / "%" / "*" /
188 <"> / "\"
189
190 auth ::= "AUTH" 1*(SPACE / TAB) auth_type *(CRLF base64)
191 CRLF
192
193 auth_type ::= 1*ATOM_CHAR
194
195 base64 ::= *(4base64_CHAR) [base64_terminal]
196
197 base64_char ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" /
198 "I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" /
199 "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" /
200 "Y" / "Z" /
201 "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" /
202 "i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" /
203 "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" /
204 "y" / "z" /
205 "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" /
206 "8" / "9" / "+" / "/"
207 ;; Case-sensitive
208
209 base64_terminal ::= (2base64_char "==") / (3base64_char "=")
210
211 CHAR ::= <any 7-bit US-ASCII character except NUL,
212 0x01 - 0x7f>
213
214 continue_req ::= "+" SPACE base64 CRLF
215
216 CR ::= <ASCII CR, carriage return, 0x0C>
217
218 CRLF ::= CR LF
219
220 CTL ::= <any ASCII control character and DEL,
221 0x00 - 0x1f, 0x7f>
222
223
224
225
226 Myers [Page 4]
227
228 RFC 1734 POP3 AUTH December 1994
229
230
231 LF ::= <ASCII LF, line feed, 0x0A>
232
233 SPACE ::= <ASCII SP, space, 0x20>
234
235 TAB ::= <ASCII HT, tab, 0x09>
236
237
238
239 4. References
240
241 [IMAP4-AUTH] Myers, J., "IMAP4 Authentication Mechanisms", RFC 1731,
242 Carnegie Mellon, December 1994.
243
244
245
246 5. Security Considerations
247
248 Security issues are discussed throughout this memo.
249
250
251
252 6. Author's Address
253
254 John G. Myers
255 Carnegie-Mellon University
256 5000 Forbes Ave
257 Pittsburgh, PA 15213
258
259 EMail: jgm+@cmu.edu
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282 Myers [Page 5]
283
1
2
3
4
5
6
7 Network Working Group R. Nelson
8 Request for Comments: 1957 Crynwr Software
9 Updates: 1939 June 1996
10 Category: Informational
11
12
13 Some Observations on Implementations
14 of the Post Office Protocol (POP3)
15
16 Status of this Memo
17
18 This memo provides information for the Internet community. This memo
19 does not specify an Internet standard of any kind. Distribution of
20 this memo is unlimited.
21
22 Observations
23
24 Sometimes an implementation is mistaken for a standard. POP3 servers
25 and clients are no exception. The widely-used UCB POP3 server,
26 popper, which has been further developed by Qualcomm, always has
27 additional information following the status indicator. So, the
28 status indicator always has a space following it. Two POP3 clients
29 have been observed to expect that space, and fail when it has not
30 been found. The RFC does not require the space, hence this memo.
31 These clients are the freely copyable Unix "popclient" and the
32 proprietary "netApp Systems Internet Series". The authors of both of
33 these have been contacted, and new releases will not expect the
34 space, but old versions should be supported.
35
36 In addition, two popular clients require optional parts of the RFC.
37 Netscape requires UIDL, and Eudora requires TOP.
38
39 The optional APOP authentication command has not achieved wide
40 penetration yet. Newer versions of the Qualcomm POP server implement
41 it. Known client implementations of APOP include GNU Emacs VM client
42 and Eudora Lite and Eudora Pro.
43
44 Security Considerations
45
46 Security issues are not discussed in this memo.
47
48 References
49
50 [1] Myers, J., and M. Rose, "Post Office Protocol - Version 3",
51 STD 53, RFC 1939, May 1996.
52
53
54
55
56
57
58 Nelson Informational [Page 1]
59
60 RFC 1957 Notes on POP3 Implementations June 1996
61
62
63 Author's Address
64
65 Russell Nelson
66 Crynwr Software
67 521 Pleasant Valley Rd.
68 Potsdam, NY 13676
69
70 Phone: +1.315.268.1925
71 FAX: +1.315.268.9201
72 EMail: nelson@crynwr.com
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114 Nelson Informational [Page 2]
115
This diff could not be displayed because it is too large.
1 Known errors in RFC 2060 as of 13 September 1998:
2
3 1) The SELECT and EXAMINE response list does not mention UIDVALIDITY.
4
5 2) In the definition of store_att_flags, #flag should be 1#flag; in other
6 words, at least one flag must be given. To do an empty list of flags,
7 you must use the parenthesized form: "()".
8
9 3) The example in 6.4.6 is missing parenthesis around the FETCH attributes.
10 It should read:
11
12 Example: C: A003 STORE 2:4 +FLAGS (\Deleted)
13 S: * 2 FETCH (FLAGS (\Deleted \Seen))
14 S: * 3 FETCH (FLAGS (\Deleted))
15 S: * 4 FETCH (FLAGS (\Deleted \Flagged \Seen))
16 S: A003 OK STORE completed
17
18 4) Section 7.4.2 has an example of "a two part message consisting of a
19 text and a BASE645-encoded text attachment". "BASE645" should be
20 BASE64.
21
22 5) In the example in 7.4.2 discussed above, there is a spurious close
23 parenthesis at the end of the example.
24
25 6) Spurious obsolete response "MAILBOX" is listed in mailbox_data and
26 should be removed.
27
28 7) There is a spurious "<" in the mailbox_data rule that should be removed.
29
30 8) CRLF is missing from the continue_req rule.
31
32 9) The atom in resp_text_code should specifically exclude "]".
33
34 10) The example in 6.3.11 does not show the command continuation request.
35
36 11) NEWNAME is missing from resp_text_code.
37
38 12) There is a missing open parenthesis in the media_basic grammar rule.
39
40 13) Status attributes are incorrectly defined in mailbox_data rule.
41
42 14) The UID FETCH example is missing an "OK" in the response.
43
44 15) Multipart extension data incorrectly specifies that language must be
45 given along with disposition.
This diff could not be displayed because it is too large.
1
2
3
4
5
6
7 Network Working Group J. Myers
8 Request for Comments: 2088 Carnegie Mellon
9 Cateogry: Standards Track January 1997
10
11
12 IMAP4 non-synchronizing literals
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 1. Abstract
23
24 The Internet Message Access Protocol [IMAP4] contains the "literal"
25 syntactic construct for communicating strings. When sending a
26 literal from client to server, IMAP4 requires the client to wait for
27 the server to send a command continuation request between sending the
28 octet count and the string data. This document specifies an
29 alternate form of literal which does not require this network round
30 trip.
31
32 2. Conventions Used in this Document
33
34 In examples, "C:" and "S:" indicate lines sent by the client and
35 server respectively.
36
37 3. Specification
38
39 The non-synchronizing literal is added an alternate form of literal,
40 and may appear in communication from client to server instead of the
41 IMAP4 form of literal. The IMAP4 form of literal, used in
42 communication from client to server, is referred to as a
43 synchronizing literal.
44
45 Non-synchronizing literals may be used with any IMAP4 server
46 implementation which returns "LITERAL+" as one of the supported
47 capabilities to the CAPABILITY command. If the server does not
48 advertise the LITERAL+ capability, the client must use synchronizing
49 literals instead.
50
51 The non-synchronizing literal is distinguished from the original
52 synchronizing literal by having a plus ('+') between the octet count
53 and the closing brace ('}'). The server does not generate a command
54 continuation request in response to a non-synchronizing literal, and
55
56
57
58 Myers Standards Track [Page 1]
59
60 RFC 2088 LITERAL January 1997
61
62
63 clients are not required to wait before sending the octets of a non-
64 synchronizing literal.
65
66 The protocol receiver of an IMAP4 server must check the end of every
67 received line for an open brace ('{') followed by an octet count, a
68 plus ('+'), and a close brace ('}') immediately preceeding the CRLF.
69 If it finds this sequence, it is the octet count of a non-
70 synchronizing literal and the server MUST treat the specified number
71 of following octets and the following line as part of the same
72 command. A server MAY still process commands and reject errors on a
73 line-by-line basis, as long as it checks for non-synchronizing
74 literals at the end of each line.
75
76 Example: C: A001 LOGIN {11+}
77 C: FRED FOOBAR {7+}
78 C: fat man
79 S: A001 OK LOGIN completed
80
81 4. Formal Syntax
82
83 The following syntax specification uses the augmented Backus-Naur
84 Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4].
85 Non-terminals referenced but not defined below are as defined by
86 [IMAP4].
87
88 literal ::= "{" number ["+"] "}" CRLF *CHAR8
89 ;; Number represents the number of CHAR8 octets
90
91 6. References
92
93 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4",
94 draft-crispin-imap-base-XX.txt, University of Washington, April 1996.
95
96 [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet Text
97 Messages", STD 11, RFC 822.
98
99 7. Security Considerations
100
101 There are no known security issues with this extension.
102
103 8. Author's Address
104
105 John G. Myers
106 Carnegie-Mellon University
107 5000 Forbes Ave.
108 Pittsburgh PA, 15213-3890
109
110 Email: jgm+@cmu.edu
111
112
113
114 Myers Standards Track [Page 2]
115
1
2
3
4
5
6
7 Network Working Group E. Levinson
8 Request for Comments: 2111 XIson, Inc.
9 Category: Standards Track March 1997
10
11
12 Content-ID and Message-ID Uniform Resource Locators
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 Abstract
23
24 The Uniform Resource Locator (URL) schemes, "cid:" and "mid:" allow
25 references to messages and the body parts of messages. For example,
26 within a single multipart message, one HTML body part might include
27 embedded references to other parts of the same message.
28
29 1. Introduction
30
31 The use of [MIME] within email to convey Web pages and their
32 associated images requires a URL scheme to permit the HTML to refer
33 to the images or other data included in the message. The Content-ID
34 Uniform Resource Locator, "cid:", serves that purpose.
35
36 Similarly Net News readers use Message-IDs to link related messages
37 together. The Message-ID URL provides a scheme, "mid:", to refer to
38 such messages as a "resource".
39
40 The "mid" (Message-ID) and "cid" (Content-ID) URL schemes provide
41 identifiers for messages and their body parts. The "mid" scheme uses
42 (a part of) the message-id of an email message to refer to a specific
43 message. The "cid" scheme refers to a specific body part of a
44 message; its use is generally limited to references to other body
45 parts in the same message as the referring body part. The "mid"
46 scheme may also refer to a specific body part within a designated
47 message, by including the content-ID's address.
48
49 A note on terminology. The terms "body part" and "MIME entity" are
50 used interchangeably. They refer to the headers and body of a MIME
51 message, either the message itself or one of the body parts contained
52 in a Multipart message.
53
54
55
56
57
58 Levinson Standards Track [Page 1]
59
60 RFC 2111 CID and MID URLs March 1997
61
62
63 2. The MID and CID URL Schemes
64
65 RFC1738 [URL] reserves the "mid" and "cid" schemes for Message-ID and
66 Content-ID respectively. This memorandum defines the syntax for
67 those URLs. Because they use the same syntactic elements they are
68 presented together.
69
70 The URLs take the form
71
72 content-id = url-addr-spec
73
74 message-id = url-addr-spec
75
76 url-addr-spec = addr-spec ; URL encoding of RFC 822 addr-spec
77
78 cid-url = "cid" ":" content-id
79
80 mid-url = "mid" ":" message-id [ "/" content-id ]
81
82 Note: in Internet mail messages, the addr-spec in a Content-ID
83 [MIME] or Message-ID [822] header are enclosed in angle brackets
84 (<>). Since addr-spec in a Message-ID or Content-ID might contain
85 characters not allowed within a URL; any such character (including
86 "/", which is reserved within the "mid" scheme) must be hex-
87 encoded using the %hh escape mechanism in [URL].
88
89 A "mid" URL with only a "message-id" refers to an entire message.
90 With the appended "content-id", it refers to a body part within a
91 message, as does a "cid" URL. The Content-ID of a MIME body part is
92 required to be globally unique. However, in many systems that store
93 messages, body parts are not indexed independently their context
94 (message). The "mid" URL long form was designed to supply the
95 context needed to support interoperability with such systems.
96
97 A implementation conforming to this specification is required to
98 support the "mid" URL long form (message-id/content-id). Conforming
99 implementations can choose to, but are not required to, take
100 advantage of the content-id's uniqueness and interpret a "cid" URL to
101 refer to any body part within the message store.
102
103 In limited circumstances (e.g., within multipart/alternate), a single
104 message may contain several body parts that have the same Content-ID.
105 That occurs, for example, when identical data can be accessed through
106 different methods [MIME, sect. 7.2.3]. In those cases, conforming
107 implementations are required to use the rules of the containing MIME
108 entity (e.g., multi-part/alternate) to select the body part to which
109 the Content-ID refers.
110
111
112
113
114 Levinson Standards Track [Page 2]
115
116 RFC 2111 CID and MID URLs March 1997
117
118
119 A "cid" URL is converted to the corresponding Content-ID message
120 header [MIME] by removing the "cid:" prefix, converting %hh hex-
121 escaped characters to their ASCII equivalents and enclosing the
122 remaining parts with an angle bracket pair, "<" and ">". For
123 example, "mid:foo4%25foo1@bar.net" corresponds to
124
125 Message-ID: <foo4%foo1@bar.net>
126
127 A "mid" URL is converted to a Message-ID or Message-ID/Content-ID
128 pair in a similar fashion.
129
130 Both message-id and content-id are required to be globally unique.
131 That is, no two different messages will ever have the same Message-ID
132 addr-spec; no different body parts will ever have the same Content-ID
133 addr-spec. A common technique used by many message systems is to use
134 a time and date stamp along with the local host's domain name, e.g.,
135 950124.162336@XIson.com.
136
137 Some Examples
138
139 The following message contains an HTML body part that refers to an
140 image contained in another body part. Both body parts are contained
141 in a Multipart/Related MIME entity. The HTML IMG tag contains a
142 cidurl which points to the image.
143
144 From: foo1@bar.net
145 To: foo2@bar.net
146 Subject: A simple example
147 Mime-Version: 1.0
148 Content-Type: multipart/related; boundary="boundary-example-1";
149 type=Text/HTML
150
151 --boundary-example 1
152 Content-Type: Text/HTML; charset=US-ASCII
153
154 ... text of the HTML document, which might contain a hyperlink
155 to the other body part, for example through a statement such as:
156 <IMG SRC="cid:foo4*foo1@bar.net" ALT="IETF logo">
157
158 --boundary-example-1
159 Content-ID: foo4*foo1@bar.net
160 Content-Type: IMAGE/GIF
161 Content-Transfer-Encoding: BASE64
162
163
164
165
166
167
168
169
170 Levinson Standards Track [Page 3]
171
172 RFC 2111 CID and MID URLs March 1997
173
174
175 R0lGODlhGAGgAPEAAP/////ZRaCgoAAAACH+PUNvcHlyaWdodCAoQykgMTk5
176 NSBJRVRGLiBVbmF1dGhvcml6ZWQgZHVwbGljYXRpb24gcHJvaGliaXRlZC4A
177 etc...
178
179 --boundary-example-1--
180
181 The following message points to another message (hopefully still in
182 the recipient's message store).
183
184 From: bar@none.com
185 To: phooey@all.com
186 Subject: Here's how to do it
187 Content-type: text/html; charset=usascii
188
189 ... The items in my
190 <A HREF= "mid:960830.1639@XIson.com/partA.960830.1639@XIson.com">
191 previous message</A>, shows how the approach you propose can be
192 used to accomplish ...
193
194 3. Security Considerations
195
196 The URLs defined here provide an addressing or referencing mechanism.
197 The values of these URLs disclose no more about the originators
198 environment than the corresponding Message-ID and Content-ID values.
199 Where concern exists about such disclosures the originator of a
200 message using mid and cid URLs must take precautions to insure that
201 confidential information is not disclosed. Those precautions should
202 already be in place to handle existing mail use of the Message-ID and
203 Content-ID.
204
205 4. References
206
207 [822] Crocker, D., "Standard for the Format of ARPA Internet Text
208 Messages," August 1982, University of Delaware, STD 11, RFC
209 822.
210
211 [MIME] N. Borenstein, N. Freed, "MIME (Multipurpose Internet Mail
212 Extensions) Part One: Mechanisms for Specifying and
213 Describing the Format of Internet Message Bodies,"
214 September 1993, RFC 1521.
215
216 [URL] Berners-Lee, T., Masinter, L., and McCahill, M., "Uniform
217 Resource Locators (URL)," December 1994.
218
219 [MULREL] E. Levinson, "The MIME Multipart/Related Content-type,"
220 December 1995, RFC 1874.
221
222
223
224
225
226 Levinson Standards Track [Page 4]
227
228 RFC 2111 CID and MID URLs March 1997
229
230
231 5. Acknowledgments
232
233 The original concept of "mid" and "cid" URLs were part of the Tim
234 Berners-Lee's original vision of the World Wide Web. The ideas and
235 design have benefited greatly by discussions with Harald Alvestrand,
236 Dan Connolly, Roy Fielding, Larry Masinter, Jacob Palme, and others
237 in the MHTML working group.
238
239 6. Author's Address
240
241 Edward Levinson
242 47 Clive Street
243 Metuchen, NJ 08840-1060
244 USA
245 +1 908 549 3716
246 <XIson@cnj.digex.net>
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282 Levinson Standards Track [Page 5]
283
1
2
3
4
5
6
7 Network Working Group M. Gahrns
8 Request for Comments: 2221 Microsoft
9 Category: Standards Track October 1997
10
11
12 IMAP4 Login Referrals
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 Copyright Notice
23
24 Copyright (C) The Internet Society (1997). All Rights Reserved.
25
26 1. Abstract
27
28 When dealing with large amounts of users and many IMAP4 [RFC-2060]
29 servers, it is often necessary to move users from one IMAP4 server to
30 another. For example, hardware failures or organizational changes
31 may dictate such a move.
32
33 Login referrals allow clients to transparently connect to an
34 alternate IMAP4 server, if their home IMAP4 server has changed.
35
36 A referral mechanism can provide efficiencies over the alternative
37 'proxy method', in which the local IMAP4 server contacts the remote
38 server on behalf of the client, and then transfers the data from the
39 remote server to itself, and then on to the client. The referral
40 mechanism's direct client connection to the remote server is often a
41 more efficient use of bandwidth, and does not require the local
42 server to impersonate the client when authenticating to the remote
43 server.
44
45 2. Conventions used in this document
46
47 In examples, "C:" and "S:" indicate lines sent by the client and
48 server respectively.
49
50 A home server, is an IMAP4 server that contains the user's inbox.
51
52 A remote server is a server that contains remote mailboxes.
53
54
55
56
57
58 Gahrns Standards Track [Page 1]
59
60 RFC 2221 IMAP4 Login Referrals October 1997
61
62
63 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
64 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
65 document are to be interpreted as described in [RFC-2119].
66
67 3. Introduction and Overview
68
69 IMAP4 servers that support this extension MUST list the keyword
70 LOGIN-REFERRALS in their CAPABILITY response. No client action is
71 needed to invoke the LOGIN-REFERRALS capability in a server.
72
73 A LOGIN-REFERRALS capable IMAP4 server SHOULD NOT return a referral
74 to a server that will return a referral. A client MUST NOT follow
75 more than 10 levels of referral without consulting the user.
76
77 A LOGIN-REFERRALS response code MUST contain as an argument a valid
78 IMAP server URL as defined in [IMAP-URL].
79
80 A home server referral consists of either a tagged NO or OK, or an
81 untagged BYE response that contains a LOGIN-REFERRALS response code.
82
83 Example: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/] Remote Server
84
85 NOTE: user;AUTH=* is specified as required by [IMAP-URL] to avoid a
86 client falling back to anonymous login.
87
88 4. Home Server Referrals
89
90 A home server referral may be returned in response to an AUTHENTICATE
91 or LOGIN command, or it may appear in the connection startup banner.
92 If a server returns a home server referral in a tagged NO response,
93 that server does not contain any mailboxes that are accessible to the
94 user. If a server returns a home server referral in a tagged OK
95 response, it indicates that the user's personal mailboxes are
96 elsewhere, but the server contains public mailboxes which are
97 readable by the user. After receiving a home server referral, the
98 client can not make any assumptions as to whether this was a
99 permanent or temporary move of the user.
100
101 4.1. LOGIN and AUTHENTICATE Referrals
102
103 An IMAP4 server MAY respond to a LOGIN or AUTHENTICATE command with a
104 home server referral if it wishes to direct the user to another IMAP4
105 server.
106
107 Example: C: A001 LOGIN MIKE PASSWORD
108 S: A001 NO [REFERRAL IMAP://MIKE@SERVER2/] Specified user
109 is invalid on this server. Try SERVER2.
110
111
112
113
114 Gahrns Standards Track [Page 2]
115
116 RFC 2221 IMAP4 Login Referrals October 1997
117
118
119 Example: C: A001 LOGIN MATTHEW PASSWORD
120 S: A001 OK [REFERRAL IMAP://MATTHEW@SERVER2/] Specified
121 user's personal mailboxes located on Server2, but
122 public mailboxes are available.
123
124 Example: C: A001 AUTHENTICATE GSSAPI
125 <authentication exchange>
126 S: A001 NO [REFERRAL IMAP://user;AUTH=GSSAPI@SERVER2/]
127 Specified user is invalid on this server. Try
128 SERVER2.
129
130 4.2. BYE at connection startup referral
131
132 An IMAP4 server MAY respond with an untagged BYE and a REFERRAL
133 response code that contains an IMAP URL to a home server if it is not
134 willing to accept connections and wishes to direct the client to
135 another IMAP4 server.
136
137 Example: S: * BYE [REFERRAL IMAP://user;AUTH=*@SERVER2/] Server not
138 accepting connections. Try SERVER2
139
140 5. Formal Syntax
141
142 The following syntax specification uses the augmented Backus-Naur
143 Form (BNF) as described in [ABNF].
144
145 This amends the "resp_text_code" element of the IMAP4 grammar
146 described in [RFC-2060]
147
148 resp_text_code =/ "REFERRAL" SPACE <imapurl>
149 ; See [IMAP-URL] for definition of <imapurl>
150 ; See [RFC-2060] for base definition of resp_text_code
151
152 6. Security Considerations
153
154 The IMAP4 login referral mechanism makes use of IMAP URLs, and as
155 such, have the same security considerations as general internet URLs
156 [RFC-1738], and in particular IMAP URLs [IMAP-URL].
157
158 A server MUST NOT give a login referral if authentication for that
159 user fails. This is to avoid revealing information about the user's
160 account to an unauthorized user.
161
162 With the LOGIN-REFERRALS capability, it is potentially easier to
163 write a rogue 'password catching' server that collects login data and
164 then refers the client to their actual IMAP4 server. Although
165 referrals reduce the effort to write such a server, the referral
166 response makes detection of the intrusion easier.
167
168
169
170 Gahrns Standards Track [Page 3]
171
172 RFC 2221 IMAP4 Login Referrals October 1997
173
174
175 7. References
176
177 [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version
178 4rev1", RFC 2060, December 1996.
179
180 [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft,
181 September 1997.
182
183 [RFC-1738], Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform
184 Resource Locators (URL)", RFC 1738, December 1994.
185
186 [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate
187 Requirement Levels", RFC 2119, March 1997.
188
189 [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for
190 Syntax Specifications: ABNF", Work in Progress.
191
192 8. Acknowledgments
193
194 Many valuable suggestions were received from private discussions and
195 the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin,
196 Mark Keasling Chris Newman and Larry Osterman made significant
197 contributions to this document.
198
199 9. Author's Address
200
201 Mike Gahrns
202 Microsoft
203 One Microsoft Way
204 Redmond, WA, 98072
205
206 Phone: (206) 936-9833
207 EMail: mikega@microsoft.com
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226 Gahrns Standards Track [Page 4]
227
228 RFC 2221 IMAP4 Login Referrals October 1997
229
230
231 10. Full Copyright Statement
232
233 Copyright (C) The Internet Society (1997). All Rights Reserved.
234
235 This document and translations of it may be copied and furnished to
236 others, and derivative works that comment on or otherwise explain it
237 or assist in its implmentation may be prepared, copied, published
238 andand distributed, in whole or in part, without restriction of any
239 kind, provided that the above copyright notice and this paragraph are
240 included on all such copies and derivative works. However, this
241 document itself may not be modified in any way, such as by removing
242 the copyright notice or references to the Internet Society or other
243 Internet organizations, except as needed for the purpose of
244 developing Internet standards in which case the procedures for
245 copyrights defined in the Internet Standards process must be
246 followed, or as required to translate it into languages other than
247 English.
248
249 The limited permissions granted above are perpetual and will not be
250 revoked by the Internet Society or its successors or assigns.
251
252 This document and the information contained herein is provided on an
253 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
254 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
255 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
256 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
257 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282 Gahrns Standards Track [Page 5]
283
1
2
3
4
5
6
7 Network Working Group C. Newman
8 Request for Comments: 2245 Innosoft
9 Category: Standards Track November 1997
10
11
12 Anonymous SASL Mechanism
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 Copyright Notice
23
24 Copyright (C) The Internet Society (1997). All Rights Reserved.
25
26 Abstract
27
28 It is common practice on the Internet to permit anonymous access to
29 various services. Traditionally, this has been done with a plain
30 text password mechanism using "anonymous" as the user name and
31 optional trace information, such as an email address, as the
32 password. As plaintext login commands are not permitted in new IETF
33 protocols, a new way to provide anonymous login is needed within the
34 context of the SASL [SASL] framework.
35
36 1. Conventions Used in this Document
37
38 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
39 in this document are to be interpreted as defined in "Key words for
40 use in RFCs to Indicate Requirement Levels" [KEYWORDS].
41
42 2. Anonymous SASL mechanism
43
44 The mechanism name associated with anonymous access is "ANONYMOUS".
45 The mechanism consists of a single message from the client to the
46 server. The client sends optional trace information in the form of a
47 human readable string. The trace information should take one of
48 three forms: an Internet email address, an opaque string which does
49 not contain the '@' character and can be interpreted by the system
50 administrator of the client's domain, or nothing. For privacy
51 reasons, an Internet email address should only be used with
52 permission from the user.
53
54
55
56
57
58 Newman Standards Track [Page 1]
59
60 RFC 2245 Anonymous SASL Mechanism November 1997
61
62
63 A server which permits anonymous access will announce support for the
64 ANONYMOUS mechanism, and allow anyone to log in using that mechanism,
65 usually with restricted access.
66
67 The formal grammar for the client message using Augmented BNF [ABNF]
68 follows.
69
70 message = [email / token]
71
72 TCHAR = %x20-3F / %x41-7E
73 ;; any printable US-ASCII character except '@'
74
75 email = addr-spec
76 ;; as defined in [IMAIL], except with no free
77 ;; insertion of linear-white-space, and the
78 ;; local-part MUST either be entirely enclosed in
79 ;; quotes or entirely unquoted
80
81 token = 1*255TCHAR
82
83 3. Example
84
85
86 Here is a sample anonymous login between an IMAP client and server.
87 In this example, "C:" and "S:" indicate lines sent by the client and
88 server respectively. If such lines are wrapped without a new "C:" or
89 "S:" label, then the wrapping is for editorial clarity and is not
90 part of the command.
91
92 Note that this example uses the IMAP profile [IMAP4] of SASL. The
93 base64 encoding of challenges and responses, as well as the "+ "
94 preceding the responses are part of the IMAP4 profile, not part of
95 SASL itself. Newer profiles of SASL will include the client message
96 with the AUTHENTICATE command itself so the extra round trip below
97 (the server response with an empty "+ ") can be eliminated.
98
99 In this example, the user's opaque identification token is "sirhc".
100
101 S: * OK IMAP4 server ready
102 C: A001 CAPABILITY
103 S: * CAPABILITY IMAP4 IMAP4rev1 AUTH=CRAM-MD5 AUTH=ANONYMOUS
104 S: A001 OK done
105 C: A002 AUTHENTICATE ANONYMOUS
106 S: +
107 C: c2lyaGM=
108 S: A003 OK Welcome, trace information has been logged.
109
110
111
112
113
114 Newman Standards Track [Page 2]
115
116 RFC 2245 Anonymous SASL Mechanism November 1997
117
118
119 4. Security Considerations
120
121 The anonymous mechanism grants access to information by anyone. For
122 this reason it should be disabled by default so the administrator can
123 make an explicit decision to enable it.
124
125 If the anonymous user has any write privileges, a denial of service
126 attack is possible by filling up all available space. This can be
127 prevented by disabling all write access by anonymous users.
128
129 If anonymous users have read and write access to the same area, the
130 server can be used as a communication mechanism to anonymously
131 exchange information. Servers which accept anonymous submissions
132 should implement the common "drop box" model which forbids anonymous
133 read access to the area where anonymous submissions are accepted.
134
135 If the anonymous user can run many expensive operations (e.g., an
136 IMAP SEARCH BODY command), this could enable a denial of service
137 attack. Servers are encouraged to limit the number of anonymous
138 users and reduce their priority or limit their resource usage.
139
140 If there is no idle timeout for the anonymous user and there is a
141 limit on the number of anonymous users, a denial of service attack is
142 enabled. Servers should implement an idle timeout for anonymous
143 users.
144
145 The trace information is not authenticated so it can be falsified.
146 This can be used as an attempt to get someone else in trouble for
147 access to questionable information. Administrators trying to trace
148 abuse need to realize this information may be falsified.
149
150 A client which uses the user's correct email address as trace
151 information without explicit permission may violate that user's
152 privacy. Information about who accesses an anonymous archive on a
153 sensitive subject (e.g., sexual abuse) has strong privacy needs.
154 Clients should not send the email address without explicit permission
155 of the user and should offer the option of supplying no trace token
156 -- thus only exposing the source IP address and time. Anonymous
157 proxy servers could enhance this privacy, but would have to consider
158 the resulting potential denial of service attacks.
159
160 Anonymous connections are susceptible to man in the middle attacks
161 which view or alter the data transferred. Clients and servers are
162 encouraged to support external integrity and encryption mechanisms.
163
164 Protocols which fail to require an explicit anonymous login are more
165 susceptible to break-ins given certain common implementation
166 techniques. Specifically, Unix servers which offer user login may
167
168
169
170 Newman Standards Track [Page 3]
171
172 RFC 2245 Anonymous SASL Mechanism November 1997
173
174
175 initially start up as root and switch to the appropriate user id
176 after an explicit login command. Normally such servers refuse all
177 data access commands prior to explicit login and may enter a
178 restricted security environment (e.g., the Unix chroot function) for
179 anonymous users. If anonymous access is not explicitly requested,
180 the entire data access machinery is exposed to external security
181 attacks without the chance for explicit protective measures.
182 Protocols which offer restricted data access should not allow
183 anonymous data access without an explicit login step.
184
185 5. References
186
187 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
188 Specifications: ABNF", RFC 2234, November 1997.
189
190 [IMAIL] Crocker, D., "Standard for the Format of Arpa Internet Text
191 Messages", STD 11, RFC 822, August 1982.
192
193 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
194 4rev1", RFC 2060, December 1996.
195
196 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
197 Requirement Levels", RFC 2119, March 1997.
198
199 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
200 RFC 2222, October 1997.
201
202 6. Author's Address
203
204 Chris Newman
205 Innosoft International, Inc.
206 1050 Lakes Drive
207 West Covina, CA 91790 USA
208
209 Email: chris.newman@innosoft.com
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226 Newman Standards Track [Page 4]
227
228 RFC 2245 Anonymous SASL Mechanism November 1997
229
230
231 7. Full Copyright Statement
232
233 Copyright (C) The Internet Society (1997). All Rights Reserved.
234
235 This document and translations of it may be copied and furnished to
236 others, and derivative works that comment on or otherwise explain it
237 or assist in its implementation may be prepared, copied, published
238 and distributed, in whole or in part, without restriction of any
239 kind, provided that the above copyright notice and this paragraph are
240 included on all such copies and derivative works. However, this
241 document itself may not be modified in any way, such as by removing
242 the copyright notice or references to the Internet Society or other
243 Internet organizations, except as needed for the purpose of
244 developing Internet standards in which case the procedures for
245 copyrights defined in the Internet Standards process must be
246 followed, or as required to translate it into languages other than
247 English.
248
249 The limited permissions granted above are perpetual and will not be
250 revoked by the Internet Society or its successors or assigns.
251
252 This document and the information contained herein is provided on an
253 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
254 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
255 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
256 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
257 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282 Newman Standards Track [Page 5]
283
This diff could not be displayed because it is too large.
This diff could not be displayed because it is too large.
This diff could not be displayed because it is too large.
This diff could not be displayed because it is too large.
1 @example
2 @code{/* Prefix @emph{sendmail_} is reserved */}
3 @code{#include <mailutils/sendmail.h>}
4
5 @end example
6
7 Spawning Sendmail daemon to deliver mail. Not implemented.
1 /* sfrom, Simple From */
2 #include <stdio.h>
3 #include <unistd.h>
4 #include <stdlib.h>
5 #include <string.h>
6 #include <mailutils/registrar.h>
7 #include <mailutils/list.h>
8 #include <mailutils/mailbox.h>
9
10 #define BUFFER_SIZE 64
11 int
12 main (int argc, const char **argv)
13 @{
14 char from[BUFFER_SIZE];
15 char subject[BUFFER_SIZE];
16 char *mail;
17 mailbox_t mbox;
18 int status
19 size_t msgno, total = 0;
20
21 mail = (argc == 2) ? argv[1] : getenv ("MAIL");
22
23 /* Register the type of mailbox. IMAP4, POP3 and local format */
24 @{
25 list_t registrar;
26 registrar_get_list (&registrar);
27 list_append (registrar, imap_record);
28 list_append (registrar, path_record);
29 list_append (registrar, pop_record);
30 @}
31
32 status = mailbox_create (&mbox, mail);
33 if (status != 0)
34 @{
35 fprintf (stderr, "mailbox_create: %s\n", strerror (status));
36 exit (EXIT_FAILURE);
37 @}
38
39 status = mailbox_open (mbox, MU_STREAM_READ);
40 if (status != 0)
41 @{
42 fprintf (stderr, "mailbox_open: %s\n", strerror (status));
43 exit (EXIT_FAILURE);
44 @}
45
46 mailbox_messages_count (mbox, &total);
47
48 for (msgno = 1; msgno <= total; msgno++)
49 @{
50 message_t msg;
51 header_t hdr;
52
53 if ((status = mailbox_get_message (mbox, msgno, &msg)) != 0
54 || (status = message_get_header (msg, &hdr)) != 0)
55 @{
56 fprintf (stderr, "Error message:%s\n",
57 strerror (status));
58 exit (EXIT_FAILURE);
59 @}
60
61 status = header_get_value (hdr, MU_HEADER_FROM, from,
62 sizeof (from), NULL);
63 if (status != 0)
64 strcpy (from, "(NO FROM)");
65
66 status = header_get_value (hdr, MU_HEADER_SUBJECT, subject,
67 sizeof (subject), NULL);
68 if (status != 0)
69 strcpy (subject, "(NO SUBJECT)");
70
71 printf ("%s\t%s\n", from, subject);
72 @}
73
74 mailbox_close (mbox);
75 mailbox_destroy (&mbox);
76 return 0;
77 @}
1 @example
2 @code{/* Prefix @emph{smtp_} is reserved */}
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
1 @code{#include <mailutils/stream.h>}
2
3 @deftypefun int stream_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner})
4 @table @code
5 @item MU_STREAM_READ
6 @findex MU_STREAM_READ
7 The stream is open read only.
8 @item MU_STREAM_WRITE
9 @findex MU_STREAM_WRITE
10 The stream is open write only.
11 @item MU_STREAM_RDWR
12 @findex MU_STREAM_RDWR
13 The stream is open read and write.
14 @item MU_STREAM_APPEND
15 @findex MU_STREAM_APPEND
16 The stream is open in append mode for writing.
17 @item MU_STREAM_CREAT
18 @findex MU_STREAM_CREAT
19 The stream is created.
20 @item MU_STREAM_NONBLOCK
21 @findex MU_STREAM_NONBLOCK
22 The stream is set non blocking.
23 @item MU_STREAM_NO_CHECK
24 @findex MU_STREAM_NO_CHECK
25 Stream is destroyed without checking for the owner.
26 @end table
27 @end deftypefun
28
29 @deftypefun void stream_destroy (stream_t *@var{pstream}, void *@var{owner})
30 @end deftypefun
31
32 @deftypefun int stream_open (stream_t @var{stream}, const char *@var{name}, int@var{port}, int @var{flag})
33 @end deftypefun
34
35 @deftypefun int stream_close (stream_t @var{stream})
36 @end deftypefun
37
38 @deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd})
39 @end deftypefun
40
41 @deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
42 @end deftypefun
43
44 @deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
45 @end deftypefun
46
47 @deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize})
48 @end deftypefun
49
50 @deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size})
51 @end deftypefun
52
53 @deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
54 @end deftypefun
55
56 @deftypefun int stream_flush (stream_t @var{stream})
57 @end deftypefun
58
59 @deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{pflags})
60 @end deftypefun
61
62 @deftypefun int stream_get_state (stream_t @var{stream}, int *@var{pstate})
63 @table @code
64 @item MU_STREAM_STATE_OPEN
65 Last action was @code{stream_open}.
66 @item MU_STREAM_STATE_READ
67 Last action was @code{stream_read} or @code{stream_readline}.
68 @item MU_STREAM_STATE_WRITE
69 Last action was @code{stream_write}.
70 @item MU_STREAM_STATE_CLOSE
71 Last action was @code{stream_close}.
72 @end table
73 @end deftypefun
74
75 @deftypefun int file_stream_create (stream_t *@var{pstream})
76 @end deftypefun
77
78 @deftypefun int mapfile_stream_create (stream_t *@var{pstream})
79 @end deftypefun
80
81 @deftypefun int encoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
82 @end deftypefun
83
84 @deftypefun int decoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
85 @end deftypefun
86
87 @deftypefun int tcp_stream_create (stream_t *@var{pstream})
88 @end deftypefun
89
90
91 An example using @code{tcp_stream_create} to make a simple web client:
92 @example
93 #include <stdlib.h>
94 #include <stdio.h>
95 #include <errno.h>
96 #include <string.h>
97 #include <unistd.h>
98 #include <sys/select.h>
99
100 #include <mailutils/io.h>
101
102 const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
103 char rbuf[1024];
104
105 int
106 main(int argc, char **argv)
107 @{
108 int ret, off = 0, fd;
109 stream_t stream;
110 size_t nb;
111 fd_set fds;
112
113 argc = argc, argv = argv;
114
115 ret = tcp_stream_create (&stream);
116 if (ret != 0)
117 @{
118 fprintf (stderr, "tcp_stream_create: %s\n",
119 mailutils_error(ret));
120 exit (EXIT_FAILURE);
121 @}
122
123 connect_again:
124 ret = stream_open (stream, "www.netscape.com", 80,
125 MU_STREAM_NONBLOCK);
126 if (ret != 0)
127 @{
128 if (ret == MU_ERROR_EAGAIN)
129 @{
130 ret = stream_get_fd(stream, &fd);
131 if (ret != 0)
132 @{
133 fprintf (stderr, "stream_get_fd: %s\n",
134 mailutils_error(ret));
135 exit (EXIT_FAILURE);
136 @}
137 FD_ZERO (&fds);
138 FD_SET (fd, &fds);
139 select (fd+1, NULL, &fds, NULL, NULL);
140 goto connect_again;
141 @}
142 fprintf (stderr, "stream_open: %s\n", mailutils_error (ret));
143 exit (EXIT_FAILURE);
144 @}
145
146 ret = stream_get_fd (stream, &fd);
147 if (ret != 0)
148 @{
149 fprintf(stderr, "stream_get_fd: %s\n", strerror(ret));
150 exit (EXIT_FAILURE);
151 @}
152
153 write_again:
154 ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
155 if (ret != 0 )
156 @{
157 if (ret == EAGAIN)
158 @{
159 FD_ZERO (&fds);
160 FD_SET (fd, &fds);
161 select (fd + 1, NULL, &fds, NULL, NULL);
162 off += nb;
163 goto write_again;
164 @}
165 fprintf (stderr, "stream_write: %s\n", strerror(ret));
166 exit (EXIT_FAILURE)
167 @}
168
169 if (nb != strlen (wbuf))
170 @{
171 fprintf(stderr, "stream_write: %s\n", "nb != wbuf length");
172 exit (EXIT_FAILURE);
173 @}
174
175 do
176 @{
177 read_again:
178 ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
179 if (ret != 0)
180 @{
181 if (ret == EAGAIN)
182 @{
183 FD_ZERO (&fds);
184 FD_SET (fd, &fds);
185 select (fd + 1, &fds, NULL, NULL, NULL);
186 goto read_again;
187 @}
188 fprintf (stderr, "stream_read: %s\n", strerror(ret));
189 exit(EXIT_FAILURE);
190 @}
191 write (2, rbuf, nb);
192 @} while (nb);
193
194 ret = stream_close (stream);
195 if (ret!= 0)
196 @{
197 fprintf (stderr, "stream_close: %s\n", strerror(ret));
198 exit (EXIT_FAILURE);
199 @}
200
201 stream_destroy (&stream, NULL);
202 exit (EXIT_SUCCESS);
203 @}
204 @end example
1
2 @comment See rfc2368, rfc2369, rfc2384
3 A mailbox or a mailer can be described in a URL, the string will contain the
4 necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
5 properly.
6
7 @subsection POP3
8 The POP URL scheme contains a POP server, optional port number
9 and the authentication mechanism. The general form is
10
11 @example
12 @url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]}
13 or
14 @url{pop://[<user>[:<passwd>]@@]<host>[:<port>]}
15 @end example
16
17 If @emph{:port} is omitted the default value is 110. Different forms of
18 authentication can be specified with @emph{;AUTH=type}.
19 The special string @emph{;AUTH=*} indicates that the client will use
20 a default scheme base on the capability of the server.
21
22 @example
23 @url{pop://obelix@@gaulois.org}
24 @url{pop://asterix;AUTH=*@@france.com}
25 @url{pop://falbala;AUTH=+APOP@@france.com}
26 @url{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
27 @url{pop://obelix:menhir@@village.gaulois.org:2000}
28 @end example
29
30 For more complete information see @cite{rfc2368}.
31
32 @subsection IMAP
33 The IMAP URL scheme contains an IMAP server, optional port number
34 and the authentication mechanism. The general form is
35
36 @example
37 @url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]}
38 or
39 @url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]}
40 @end example
41
42 If @emph{:port} is omitted the default value is 220. Different forms of
43 authentication can be specified with @emph{;AUTH=type}.
44 The special string @emph{;AUTH=*} indicates that the client will use
45 a default scheme base on the capability of the server.
46
47 @example
48 @url{imap://obelix@@imap.gaulois.org}
49 @url{imap://asterix;AUTH=*@@imap.france.com}
50 @url{imap://asterix:potion@@imap.france.com}
51 @end example
52
53 For more complete information see @cite{rfc2192}.
54
55 @subsection File
56
57 Local folder should be handle by this URL. It is preferable to let
58 the mailbox recognize the type of mailbox and take the appropriate
59 action.
60
61 @example
62 @url{file://path}
63 @url{file://var/mail/user}
64 @url{file://home/obelix/Mail}
65 @end example
66
67 For MMDF, MH local mailboxes URLs are provided, but it is preferable to
68 use @url{file://path} and let the library figure out which one.
69
70 @example
71 @url{mmdf://path}
72 @url{mh://path}
73 @end example
74
75 @subsection Mailto
76
77 After setting a mailer, @url{mailto:} is used to tell the mailer where
78 and to whom the message is for.
79
80 @example
81 @url{mailto://hostname}
82 @end example
83
84 Mailto can be used to generate short messages, for example to subscribe
85 to mailing lists.
86
87 @example
88 @url{mailto://bug-mailutils@@gnu.org?body=subscribe}
89 @url{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
90 @end example
91
92 For more complete information see @cite{rfc2368}.
93
94 @subsection URL functions
95
96 Helper functions are provided to retrieve and set the @emph{URL} fields.
97
98 @deftypefun int url_create (url_t *@var{url}, const char *@var{name})
99 Create and the @var{url} data structure, but do not parse it.
100 @end deftypefun
101
102 @deftypefun void url_destroy (url_t *)
103 Destroy the url and free it's resources.
104 @end deftypefun
105
106 @deftypefun int url_parse (url_t @var{url})
107 Parses the url, after calling this the get functions can be called.
108
109 The syntax, condensed from RFC 1738, and extended with the ;auth=
110 of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:
111
112 @example
113 url =
114 scheme ":" = "//"
115
116 [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]
117
118 host [ ":" port ]
119
120 [ ( "/" urlpath ) | ( "?" query ) ]
121 @end example
122
123 This is a generalized URL syntax, and may not be exactly appropriate
124 for any particular scheme.
125
126 @end deftypefun
127
128 @deftypefun const char* url_to_string (const url_t @var{url})
129 @end deftypefun
130
131 @deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n})
132 @end deftypefun
133
134 @deftypefun int url_get_user (const url_t @var{url}, char *@var{usr}, size_t @var{len}, size_t *@var{n})
135 @end deftypefun
136
137 @deftypefun int url_get_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, size_t *@var{n})
138 @end deftypefun
139
140 @deftypefun int url_get_host (const url_t @var{url}, char *@var{host}, size_t @var{len}, size_t *@var{n})
141 @end deftypefun
142
143 @deftypefun int url_get_port (const url_t @var{url}, long *@var{port})
144 @end deftypefun
145
146 @deftypefun int url_get_path (const url_t @var{url}, char *@var{path}, size_t @var{len}, size_t *@var{n})
147 @end deftypefun
148
149 @deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n})
150 @end deftypefun
151
152 @deftypefun char* url_decode (const char* s)
153 Decodes an RFC 1738 % encoded string, returning the decoded string in
154 allocated memory. If the string is not encoded, this degenerates to
155 a strdup().
156 @end deftypefun
157
158 @section Example
159 @example
160 @include ex-url.texi
161 @end example
162