Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 77fdebe6 77fdebe69045f6fdc4e61918ef9226aeb331cf2a by Wojciech Polak
Options

Updated to the current API.

1 parent aa33e6e1
Inline Side-by-side
Showing 19 changed files with 1222 additions and 478 deletions
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{address_} is reserved */} 7 @code{/* Prefix @emph{address_} is reserved. */}
8 @code{#include <mailutils/address.h>} 8 @code{#include <mailutils/address.h>}
9 @end smallexample 9 @end smallexample
10 10
...@@ -19,19 +19,19 @@ RFC 822 for the details. @samp{[]} pairs mean "optional", @samp{/} means ...@@ -19,19 +19,19 @@ RFC 822 for the details. @samp{[]} pairs mean "optional", @samp{/} means
19 "one or the other", and double-quoted characters are literals. 19 "one or the other", and double-quoted characters are literals.
20 20
21 @smallexample 21 @smallexample
22 addr-spec = local-part "@" domain 22 addr-spec = @var{local-part} "@@" @var{domain}
23 mailbox = addr-spec ["(" display-name ")"] / 23 mailbox = @var{addr-spec} ["(" @var{display-name} ")"] /
24 [display-name] "<" [route] addr-spec ">" 24 [@var{display-name}] "<" [@var{route}] @var{addr-spec} ">"
25 mailbox-list = mailbox ["," mailbox-list] 25 mailbox-list = @var{mailbox} ["," @var{mailbox-list}]
26 group = display-name ":" [mailbox-list] ";" 26 group = @var{display-name} ":" [@var{mailbox-list}] ";"
27 address = mailbox / group / unix-mbox 27 address = @var{mailbox} / @var{group} / @var{unix-mbox}
28 address-list = address ["," address-list] 28 address-list = @var{address} ["," @var{address-list}]
29 @end smallexample 29 @end smallexample
30 30
31 unix-mbox is a non-standard extension meant to deal with the common 31 Unix-mbox is a non-standard extension meant to deal with the common
32 practice of using user names as addresses in mail utilities. It allows 32 practice of using user names as addresses in mail utilities. It allows
33 addresses such as "root" to be parsed correctly. These are NOT valid 33 addresses such as "root" to be parsed correctly. These are @strong{not}
34 internet email addresses, they must be qualified before use. 34 valid internet email addresses, they must be qualified before use.
35 35
36 Several address functions have a set of common arguments with consistent 36 Several address functions have a set of common arguments with consistent
37 semantics, these are described here to avoid repetition. 37 semantics, these are described here to avoid repetition.
...@@ -43,7 +43,7 @@ counts to access messages and attributes of messages. ...@@ -43,7 +43,7 @@ counts to access messages and attributes of messages.
43 43
44 If @var{len} is greater than @code{0} it is the length of the buffer 44 If @var{len} is greater than @code{0} it is the length of the buffer
45 @var{buf}, and as much of the component as possible will be copied 45 @var{buf}, and as much of the component as possible will be copied
46 into the buffer. The buffer will be null terminated. 46 into the buffer. The buffer will be @code{NULL} terminated.
47 47
48 The size of a particular component may be queried by providing @code{0} 48 The size of a particular component may be queried by providing @code{0}
49 for the @var{len} of the buffer, in which case the buffer is optional. 49 for the @var{len} of the buffer, in which case the buffer is optional.
...@@ -67,7 +67,7 @@ The index @var{no} is outside of the range of available addresses. ...@@ -67,7 +67,7 @@ The index @var{no} is outside of the range of available addresses.
67 67
68 @macro ADDRESSEINVAL 68 @macro ADDRESSEINVAL
69 @item EINVAL 69 @item EINVAL
70 Invalid usage, usually a required argument was @code{null}. 70 Invalid usage, usually a required argument was @code{NULL}.
71 @end macro 71 @end macro
72 72
73 @deftp {Data Type} address_t 73 @deftp {Data Type} address_t
...@@ -77,6 +77,10 @@ data structure to the user. Functions are provided to retrieve information ...@@ -77,6 +77,10 @@ data structure to the user. Functions are provided to retrieve information
77 about an address in the address list. 77 about an address in the address list.
78 @end deftp 78 @end deftp
79 79
80 @c
81 @c Functions.
82 @c
83
80 @deftypefun int address_create (address_t *@var{addr}, const char *@var{string}) 84 @deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
81 This function allocates and initializes @var{addr} by parsing the 85 This function allocates and initializes @var{addr} by parsing the
82 RFC822 address-list @var{string}. 86 RFC822 address-list @var{string}.
...@@ -92,7 +96,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -92,7 +96,7 @@ The return value is @code{0} on success and a code number on error conditions:
92 @deftypefun int address_createv (address_t *@var{addr}, const char *@var{sv}, size_t @var{len}) 96 @deftypefun int address_createv (address_t *@var{addr}, const char *@var{sv}, size_t @var{len})
93 This function allocates and initializes @var{addr} by parsing the 97 This function allocates and initializes @var{addr} by parsing the
94 array of pointers to RFC822 address-lists in @var{sv}. If @var{len} is 98 array of pointers to RFC822 address-lists in @var{sv}. If @var{len} is
95 @code{-1}, then @var{sv} must be null-terminated in the fashion of @var{argv}, 99 @code{-1}, then @var{sv} must be @code{NULL} terminated in the fashion of @var{argv},
96 otherwise @var{len} is the length of the array. 100 otherwise @var{len} is the length of the array.
97 101
98 The return value is @code{0} on success and a code number on error conditions: 102 The return value is @code{0} on success and a code number on error conditions:
...@@ -107,8 +111,14 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -107,8 +111,14 @@ The return value is @code{0} on success and a code number on error conditions:
107 The @var{addr} is destroyed. 111 The @var{addr} is destroyed.
108 @end deftypefun 112 @end deftypefun
109 113
110 @deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 114 @c
115 @c address_get_
116 @c
117
118 @deftypefun int address_get_nth (address_t @var{addr}, size_t @var{no}, address_t *@var{ret})
119 @end deftypefun
111 120
121 @deftypefun int address_get_email (address_t @var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t *@var{n})
112 Accesses the @var{no}th email address component of the address list. This 122 Accesses the @var{no}th email address component of the address list. This
113 address is the plain email address, correctly quoted, suitable for 123 address is the plain email address, correctly quoted, suitable for
114 using in an smtp dialog, for example, or as the address part of 124 using in an smtp dialog, for example, or as the address part of
...@@ -124,12 +134,21 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -124,12 +134,21 @@ The return value is @code{0} on success and a code number on error conditions:
124 @end table 134 @end table
125 @end deftypefun 135 @end deftypefun
126 136
127 @deftypefun int address_aget_email (address_t *@var{addr}, size_t @var{no}, char** @var{bufp}) 137 @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})
138 Accesses the local-part of an email addr-spec extracted while
139 parsing the @var{no}th email address.
128 140
129 As above, but mallocs the email address, if present, 141 The return value is @code{0} on success and a code number on error conditions:
142 @table @code
143 @ADDRESSEINVAL
144 @ADDRESSENOENT
145 @end table
146 @end deftypefun
130 147
131 and write a pointer to it into @var{bufp}. @var{bufp} will be @code{NULL} 148 @deftypefun int address_get_domain (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
132 if there is no email address to return. 149 Accesses the domain of an email addr-spec extracted while
150 parsing the @var{no}th email address. This will be @code{0}
151 length for a unix-mbox.
133 152
134 The return value is @code{0} on success and a code number on error conditions: 153 The return value is @code{0} on success and a code number on error conditions:
135 @table @code 154 @table @code
...@@ -138,8 +157,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -138,8 +157,7 @@ The return value is @code{0} on success and a code number on error conditions:
138 @end table 157 @end table
139 @end deftypefun 158 @end deftypefun
140 159
141 @deftypefun int address_get_personal (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 160 @deftypefun int address_get_personal (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
142
143 Accesses the display-name describing the @var{no}th email address. This 161 Accesses the display-name describing the @var{no}th email address. This
144 display-name is optional, so may not be present. If it is not present, but 162 display-name is optional, so may not be present. If it is not present, but
145 there is an RFC822 comment after the address, that comment will be 163 there is an RFC822 comment after the address, that comment will be
...@@ -159,8 +177,7 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -159,8 +177,7 @@ The return value is @code{0} on success and a code number on error conditions:
159 @end table 177 @end table
160 @end deftypefun 178 @end deftypefun
161 179
162 @deftypefun int address_get_comments (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 180 @deftypefun int address_get_comments (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
163
164 Accesses the comments extracted while parsing the @var{no}th email address. 181 Accesses the comments extracted while parsing the @var{no}th email address.
165 These comments have no defined meaning, and are not currently collected. 182 These comments have no defined meaning, and are not currently collected.
166 183
...@@ -171,11 +188,11 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -171,11 +188,11 @@ The return value is @code{0} on success and a code number on error conditions:
171 @end table 188 @end table
172 @end deftypefun 189 @end deftypefun
173 190
174 @deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 191 @deftypefun int address_get_route (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
175 192 Accesses the route of an email addr-spec extracted while
176 Accesses the email addr-spec extracted while 193 parsing the @var{no}th email address. This is a rarely used RFC822 address
177 parsing the @var{no}th email address. This will be @code{0} 194 syntax, but is legal in SMTP as well. The entire route is returned as
178 length for a unix-mbox. 195 a string, those wishing to parse it should look at @file{mailutils/parse822.h}.
179 196
180 The return value is @code{0} on success and a code number on error conditions: 197 The return value is @code{0} on success and a code number on error conditions:
181 @table @code 198 @table @code
...@@ -184,10 +201,14 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -184,10 +201,14 @@ The return value is @code{0} on success and a code number on error conditions:
184 @end table 201 @end table
185 @end deftypefun 202 @end deftypefun
186 203
187 @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}) 204 @c
205 @c address_aget_
206 @c
188 207
189 Accesses the local-part of an email addr-spec extracted while 208 @deftypefun int address_aget_email (address_t @var{addr}, size_t @var{no}, char **@var{bufp})
190 parsing the @var{no}th email address. 209 As above, but mallocs the email address, if present,
210 and write a pointer to it into @var{bufp}. @var{bufp} will be @code{NULL}
211 if there is no email address to return.
191 212
192 The return value is @code{0} on success and a code number on error conditions: 213 The return value is @code{0} on success and a code number on error conditions:
193 @table @code 214 @table @code
...@@ -196,40 +217,25 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -196,40 +217,25 @@ The return value is @code{0} on success and a code number on error conditions:
196 @end table 217 @end table
197 @end deftypefun 218 @end deftypefun
198 219
199 @deftypefun int address_get_domain (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 220 @deftypefun int address_aget_local_part (address_t @var{addr}, size_t @var{no}, char **@var{buf})
200
201 Accesses the domain of an email addr-spec extracted while
202 parsing the @var{no}th email address. This will be @code{0}
203 length for a unix-mbox.
204
205 The return value is @code{0} on success and a code number on error conditions:
206 @table @code
207 @ADDRESSEINVAL
208 @ADDRESSENOENT
209 @end table
210 @end deftypefun 221 @end deftypefun
211 222
212 @deftypefun int address_get_route (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 223 @deftypefun int address_aget_domain (address_t @var{addr}, size_t @var{no}, char **@var{buf})
213 224 @end deftypefun
214 Accesses the route of an email addr-spec extracted while
215 parsing the @var{no}th email address. This is a rarely used RFC822 address
216 syntax, but is legal in SMTP as well. The entire route is returned as
217 a string, those wishing to parse it should look at @file{mailutils/parse822.h}.
218 225
219 The return value is @code{0} on success and a code number on error conditions: 226 @deftypefun int address_aget_personal (address_t @var{addr}, size_t @var{no}, char **@var{buf})
220 @table @code
221 @ADDRESSEINVAL
222 @ADDRESSENOENT
223 @end table
224 @end deftypefun 227 @end deftypefun
225 228
226 @deftypefun int address_is_group (address_t *@var{addr}, size_t @var{no}, size_t @var{len}, int* @var{yes}) 229 @c
230 @c -----------
231 @c
227 232
233 @deftypefun int address_is_group (address_t @var{addr}, size_t @var{no}, int *@var{yes})
228 Sets *@var{yes} to @code{1} if this address is just the name of a group, 234 Sets *@var{yes} to @code{1} if this address is just the name of a group,
229 @code{0} otherwise. This is faster than checking if the address has 235 @code{0} otherwise. This is faster than checking if the address has
230 a non-zero length personal, and a zero-length local_part and domain. 236 a non-zero length personal, and a zero-length local_part and domain.
231 237
232 @var{yes} can be @code{null}, though that doesn't serve much purpose other 238 @var{yes} can be @code{NULL}, though that doesn't serve much purpose other
233 than determining that @var{no} refers to an address. 239 than determining that @var{no} refers to an address.
234 240
235 Currently, there is no way to determine the end of the group. 241 Currently, there is no way to determine the end of the group.
...@@ -241,10 +247,8 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -241,10 +247,8 @@ The return value is @code{0} on success and a code number on error conditions:
241 @end table 247 @end table
242 @end deftypefun 248 @end deftypefun
243 249
244 @deftypefun int address_to_string (address_t *@var{addr}, char* @var{buf}, size_t @var{len}, size_t* @var{n}) 250 @deftypefun int address_to_string (address_t *@var{addr}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
245 251 Returns the entire address list as a single RFC822 formatted address list.
246 Returns the entire address list as a single RFC822 formatted address
247 list.
248 252
249 The return value is @code{0} on success and a code number on error conditions: 253 The return value is @code{0} on success and a code number on error conditions:
250 @table @code 254 @table @code
...@@ -253,16 +257,33 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -253,16 +257,33 @@ The return value is @code{0} on success and a code number on error conditions:
253 @end table 257 @end table
254 @end deftypefun 258 @end deftypefun
255 259
256 @deftypefun int address_get_count (address_t @var{addr}, size_t* @var{count}) 260 @deftypefun int address_get_count (address_t @var{addr}, size_t *@var{count})
257
258 Returns a count of the addresses in the address list. 261 Returns a count of the addresses in the address list.
259 262
260 If @var{addr} is @code{null}, the count is @code{0}. If @var{count} is 263 If @var{addr} is @code{NULL}, the count is @code{0}. If @var{count} is
261 not @code{null}, the count will be written to *@var{count}. 264 not @code{NULL}, the count will be written to *@var{count}.
262 265
263 The return value is @code{0}. 266 The return value is @code{0}.
264 @end deftypefun 267 @end deftypefun
265 268
269 @deftypefun int address_get_group_count (address_t @var{addr}, size_t *)
270 @end deftypefun
271
272 @deftypefun int address_get_email_count (address_t @var{addr}, size_t *)
273 @end deftypefun
274
275 @deftypefun int address_get_unix_mailbox_count (address_t @var{addr}, size_t *)
276 @end deftypefun
277
278 @deftypefun int address_contains_email (address_t @var{addr}, const char *@var{email})
279 @end deftypefun
280
281 @deftypefun int address_union (address_t *@var{a}, address_t @var{b})
282 @end deftypefun
283
284 @deftypefun size_t address_format_string (address_t @var{addr}, char *@var{buf}, size_t @var{buflen})
285 @end deftypefun
286
266 @subheading Example 287 @subheading Example
267 @smallexample 288 @smallexample
268 @include addr.inc 289 @include addr.inc
......
...@@ -4,87 +4,146 @@ ...@@ -4,87 +4,146 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{attribute_} is reserved */} 7 @code{/* Prefix @emph{attribute_} is reserved. */}
8 @code{#include <mailutils/attribute.h>} 8 @code{#include <mailutils/attribute.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int attribute_create (attribute_t *@var{pattribute}) 11 @deftypefun int attribute_create (attribute_t *@var{attr}, void *)
12 @end deftypefun 12 @end deftypefun
13 13
14 @deftypefun void attribute_destroy (attribute_t *@var{pattribute}) 14 @deftypefun void attribute_destroy (attribute_t *@var{attr}, void *)
15 @end deftypefun 15 @end deftypefun
16 16
17 @deftypefun int attribute_is_seen (attribute_t @var{attribute}) 17 @deftypefun void* attribute_get_owner (attribute_t @var{attr})
18 @end deftypefun 18 @end deftypefun
19 19
20 @deftypefun int attribute_is_answered (attribute_t @var{attribute}) 20 @deftypefun int attribute_is_modified (attribute_t @var{attr})
21 @end deftypefun 21 @end deftypefun
22 22
23 @deftypefun int attribute_is_flagged (attribute_t @var{attribute}) 23 @deftypefun int attribute_clear_modified (attribute_t @var{attr})
24 @end deftypefun 24 @end deftypefun
25 25
26 @deftypefun int attribute_is_deleted (attribute_t @var{attribute}) 26 @deftypefun int attribute_set_modified (attribute_t @var{attr})
27 @end deftypefun 27 @end deftypefun
28 28
29 @deftypefun int attribute_is_draft (attribute_t @var{attribute}) 29 @c
30 @c _is_
31 @c
32
33 @deftypefun int attribute_is_userflag (attribute_t @var{attr})
34 @end deftypefun
35
36 @deftypefun int attribute_is_seen (attribute_t @var{attr})
37 @end deftypefun
38
39 @deftypefun int attribute_is_answered (attribute_t @var{attr})
40 @end deftypefun
41
42 @deftypefun int attribute_is_flagged (attribute_t @var{attr})
43 @end deftypefun
44
45 @deftypefun int attribute_is_deleted (attribute_t @var{attr})
46 @end deftypefun
47
48 @deftypefun int attribute_is_draft (attribute_t @var{attr})
49 @end deftypefun
50
51 @deftypefun int attribute_is_recent (attribute_t @var{attr})
30 @end deftypefun 52 @end deftypefun
31 53
32 @deftypefun int attribute_is_recent (attribute_t @var{attribute}) 54 @deftypefun int attribute_is_read (attribute_t @var{attr})
33 @end deftypefun 55 @end deftypefun
34 56
35 @deftypefun int attribute_is_read (attribute_t @var{attribute}) 57 @c
58 @c _set_
59 @c
60
61 @deftypefun int attribute_set_userflag (attribute_t @var{attr}, int)
36 @end deftypefun 62 @end deftypefun
37 63
38 @deftypefun int attribute_set_seen (attribute_t @var{attribute}) 64 @deftypefun int attribute_set_seen (attribute_t @var{attr})
39 @end deftypefun 65 @end deftypefun
40 66
41 @deftypefun int attribute_set_answered (attribute_t @var{attribute}) 67 @deftypefun int attribute_set_answered (attribute_t @var{attr})
42 @end deftypefun 68 @end deftypefun
43 69
44 @deftypefun int attribute_set_flagged (attribute_t @var{attribute}) 70 @deftypefun int attribute_set_flagged (attribute_t @var{attr})
45 @end deftypefun 71 @end deftypefun
46 72
47 @deftypefun int attribute_set_deleted (attribute_t @var{attribute}) 73 @deftypefun int attribute_set_deleted (attribute_t @var{attr})
48 @end deftypefun 74 @end deftypefun
49 75
50 @deftypefun int attribute_set_draft (attribute_t @var{attribute}) 76 @deftypefun int attribute_set_draft (attribute_t @var{attr})
51 @end deftypefun 77 @end deftypefun
52 78
53 @deftypefun int attribute_set_recent (attribute_t @var{attribute}) 79 @deftypefun int attribute_set_recent (attribute_t @var{attr})
54 @end deftypefun 80 @end deftypefun
55 81
56 @deftypefun int attribute_set_read (attribute_t @var{attribute}) 82 @deftypefun int attribute_set_read (attribute_t @var{attr})
57 @end deftypefun 83 @end deftypefun
58 84
59 @deftypefun int attribute_unset_seen (attribute_t @var{attribute}) 85 @c
86 @c _unset_
87 @c
88
89 @deftypefun int attribute_unset_userflag (attribute_t @var{attr}, int)
60 @end deftypefun 90 @end deftypefun
61 91
62 @deftypefun int attribute_unset_answered (attribute_t @var{attribute}) 92 @deftypefun int attribute_unset_seen (attribute_t @var{attr})
63 @end deftypefun 93 @end deftypefun
64 94
65 @deftypefun int attribute_unset_flagged (attribute_t @var{attribute}) 95 @deftypefun int attribute_unset_answered (attribute_t @var{attr})
66 @end deftypefun 96 @end deftypefun
67 97
68 @deftypefun int attribute_unset_deleted (attribute_t @var{attribute}) 98 @deftypefun int attribute_unset_flagged (attribute_t @var{attr})
69 @end deftypefun 99 @end deftypefun
70 100
71 @deftypefun int attribute_unset_draft (attribute_t @var{attribute}) 101 @deftypefun int attribute_unset_deleted (attribute_t @var{attr})
72 @end deftypefun 102 @end deftypefun
73 103
74 @deftypefun int attribute_unset_recent (attribute_t @var{attribute}) 104 @deftypefun int attribute_unset_draft (attribute_t @var{attr})
75 @end deftypefun 105 @end deftypefun
76 106
77 @deftypefun int attribute_unset_read (attribute_t @var{attribute}) 107 @deftypefun int attribute_unset_recent (attribute_t @var{attr})
78 @end deftypefun 108 @end deftypefun
79 109
80 @deftypefun int attribute_is_equal (attribute_t @var{att1}, attribute_t @var{att2}) 110 @deftypefun int attribute_unset_read (attribute_t @var{attr})
111 @end deftypefun
112
113 @c
114 @c ----------
115 @c
116
117 @deftypefun int attribute_get_flags (attribute_t @var{attr}, int *)
118 @end deftypefun
119
120 @deftypefun int attribute_set_flags (attribute_t @var{attr}, int)
121 @end deftypefun
122
123 @deftypefun int attribute_unset_flags (attribute_t @var{attr}, int)
124 @end deftypefun
125
126 @deftypefun int attribute_set_set_flags (attribute_t @var{attr}, int (*@var{_set_flags}) (attribute_t, int), void *)
127 @end deftypefun
128
129 @deftypefun int attribute_set_unset_flags (attribute_t @var{attr}, int (*@var{_unset_flags}) (attribute_t, int), void *)
130 @end deftypefun
131
132 @deftypefun int attribute_set_get_flags (attribute_t @var{attr}, int (*@var{_get_flags}) (attribute_t, int *), void *)
133 @end deftypefun
134
135 @c
136 @c ----------
137 @c
138
139 @deftypefun int attribute_is_equal (attribute_t @var{attr1}, attribute_t @var{attr2})
81 @end deftypefun 140 @end deftypefun
82 141
83 @deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src}) 142 @deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src})
84 @end deftypefun 143 @end deftypefun
85 144
86 @deftypefun int string_to_attribute (const char *@var{buf}, attribute_t *@var{pattr}) 145 @deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{writen})
87 @end deftypefun 146 @end deftypefun
88 147
89 @deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{pwriten}) 148 @deftypefun int string_to_flags (const char *@var{buf}, int *)
90 @end deftypefun 149 @end deftypefun
......
...@@ -4,37 +4,108 @@ ...@@ -4,37 +4,108 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{auth_} is reserved */} 7 @code{/* Prefixes @emph{authority_}, @emph{ticket_}, and @emph{wicket_t} are reserved */}
8 @code{#include <mailutils/auth.h>} 8 @code{#include <mailutils/auth.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 There are many ways to authenticate to a server. To be flexible the 12 There are many ways to authenticate to a server. To be flexible the
13 authentication process is provided by two objects @code{auth_t} and 13 authentication process is provided by three objects @code{authority_t},
14 @code{ticket_t}. The @code{auth_t} can implement different protocol like 14 @code{ticket_t}, and @code{wicket_t}. The @code{authority_t} can implement
15 APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox 15 different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
16 does not understand or know how to authenticate it falls back to 16 if a mailbox does not understand or know how to authenticate it falls back
17 user/passwd authentication. The @code{ticket_t} is a way for 17 to user/passwd authentication. The @code{ticket_t} is a way for
18 Mailboxes and Mailers provide a way to authenticate when the URL does not 18 Mailboxes and Mailers provide a way to authenticate when the URL does not
19 contain enough information. The default action is to call the function 19 contain enough information. The default action is to call the function
20 @code{auth_authenticate} which will get the @emph{user} and @emph{passwd} 20 @code{authority_authenticate()} which will get the @emph{user} and @emph{passwd}
21 if not set, this function can be overridden by a custom method. 21 if not set, this function can be overridden by a custom method.
22 22
23 @deftypefun int auth_create (auth_t *@var{pauth}, void *@var{owner}) 23 @c
24 @c Ticket
25 @c
26
27 @deftypefun int ticket_create (ticket_t *, void *@var{owner})
28 @end deftypefun
29
30 @deftypefun void ticket_destroy (ticket_t *, void *@var{owner})
31 @end deftypefun
32
33 @deftypefun int ticket_set_destroy (ticket_t, void (*) (ticket_t), void *@var{owner})
34 @end deftypefun
35
36 @deftypefun void* ticket_get_owner (ticket_t)
37 @end deftypefun
38
39 @deftypefun int ticket_set_pop (ticket_t, int (*@var{_pop}) (ticket_t, url_t, const char *, char **), void *)
40 @end deftypefun
41
42 @deftypefun int ticket_pop (ticket_t, url_t, const char *, char **)
43 @end deftypefun
44
45 @deftypefun int ticket_set_data (ticket_t, void *, void *@var{owner})
46 @end deftypefun
47
48 @deftypefun int ticket_get_data (ticket_t, void **)
49 @end deftypefun
50
51 @c
52 @c Authority
53 @c
54
55 @sp 1
56
57 @deftypefun int authority_create (authority_t *, ticket_t, void *)
58 @end deftypefun
59
60 @deftypefun void authority_destroy (authority_t *, void *)
61 @end deftypefun
62
63 @deftypefun void* authority_get_owner (authority_t)
24 @end deftypefun 64 @end deftypefun
25 65
26 @deftypefun void auth_destroy (auth_t *@var{pauth}, void *@var{owner}) 66 @deftypefun int authority_set_ticket (authority_t, ticket_t)
27 @end deftypefun 67 @end deftypefun
28 68
29 @deftypefun int auth_prologue (auth_t @var{auth}) 69 @deftypefun int authority_get_ticket (authority_t, ticket_t *)
30 @end deftypefun 70 @end deftypefun
31 71
32 @deftypefun int auth_authenticate (auth_t @var{auth}, char **@var{user}, char **@var{passwd}) 72 @deftypefun int authority_authenticate (authority_t)
33 @end deftypefun 73 @end deftypefun
34 74
35 @deftypefun int auth_epilogue (auth_t @var{auth}) 75 @deftypefun int authority_set_authenticate (authority_t, int (*@var{_authenticate}) (authority_t), void *)
36 @end deftypefun 76 @end deftypefun
37 77
78 @deftypefun int authority_create_null (authority_t *@var{authority}, void *@var{owner})
79 @end deftypefun
80
81 @c
82 @c Wicket
83 @c
84
85 @sp 1
86
87 @deftypefun int wicket_create (wicket_t *, const char *)
88 @end deftypefun
89
90 @deftypefun void wicket_destroy (wicket_t *)
91 @end deftypefun
92
93 @deftypefun int wicket_set_filename (wicket_t, const char *)
94 @end deftypefun
95
96 @deftypefun int wicket_get_filename (wicket_t, char *, size_t, size_t *)
97 @end deftypefun
98
99 @deftypefun int wicket_set_ticket (wicket_t, int (*) (wicket_t, const char *, const char *, ticket_t *))
100 @end deftypefun
101
102 @deftypefun int wicket_get_ticket (wicket_t, ticket_t *, const char *, const char *)
103 @end deftypefun
104
105 @c
106 @c An example.
107 @c
108
38 @sp 1 109 @sp 1
39 A simple example of an authenticate function: 110 A simple example of an authenticate function:
40 111
......
...@@ -4,32 +4,48 @@ ...@@ -4,32 +4,48 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{body_} is reserved */} 7 @code{/* Prefix @emph{body_} is reserved. */}
8 @code{#include <mailutils/body.h>} 8 @code{#include <mailutils/body.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int body_create (body_t *@var{body}, void *@var{owner}) 11 @deftypefun int body_create (body_t *@var{body}, void *@var{owner})
12 Initialize an object @var{bdy}. 12 Initialize an object @var{body}.
13 @end deftypefun 13 @end deftypefun
14 14
15 @deftypefun void body_destroy (body_t *@var{pbody}) 15 @deftypefun void body_destroy (body_t *@var{body})
16 The resources allocate are release. 16 The resources allocated are release.
17 @end deftypefun 17 @end deftypefun
18 18
19 @deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{pstream}) 19 @deftypefun void* body_get_owner (body_t @var{body})
20 @end deftypefun
21
22 @deftypefun int body_is_modified (body_t @var{body})
23 @end deftypefun
24
25 @deftypefun int body_clear_modified (body_t @var{body})
26 @end deftypefun
27
28 @c
29 @c -----------
30 @c
31
32 @deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{stream})
20 @end deftypefun 33 @end deftypefun
21 34
22 @deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner}) 35 @deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner})
23 @end deftypefun 36 @end deftypefun
24 37
25 @deftypefun int body_get_filename __P ((body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten})) 38 @deftypefun int body_get_filename (body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
39 @end deftypefun
40
41 @deftypefun int body_size (body_t @var{body}, size_t *@var{size})
26 @end deftypefun 42 @end deftypefun
27 43
28 @deftypefun int body_set_filename (body_t @var{body}, const char*@var{buffer}) 44 @deftypefun int body_set_size (body_t @var{body}, int (*@var{_size}) (body_t, size_t *), void *@var{owner})
29 @end deftypefun 45 @end deftypefun
30 46
31 @deftypefun int body_size (body_t @var{body}, size_t*@var{psize}) 47 @deftypefun int body_lines (body_t @var{body}, size_t *@var{lines})
32 @end deftypefun 48 @end deftypefun
33 49
34 @deftypefun int body_lines (body_t @var{body}, size_t *@var{plines}) 50 @deftypefun int body_set_lines (body_t @var{body}, int (*@var{_lines}) (body_t, size_t *), void *@var{owner})
35 @end deftypefun 51 @end deftypefun
......
...@@ -4,40 +4,44 @@ ...@@ -4,40 +4,44 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{envelope_} is reserved */} 7 @code{/* Prefix @emph{envelope_} is reserved. */}
8 @code{#include <mailutils/envelope.h>} 8 @code{#include <mailutils/envelope.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *); 11 @deftypefun int envelope_create (envelope_t *, void *)
12 Get the date that the message was delivered to the mailbox, in 12 Primarily for internal use.
13 something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
14 @end deftypefun 13 @end deftypefun
15 14
16 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *); 15 @deftypefun void envelope_destroy (envelope_t *, void *)
17 Get the address that this message was reportedly received from. This 16 Primarily for internal use.
18 would be the "mail from" argument if the message was delivered
19 or received via SMTP, for example.
20 @end deftypefun 17 @end deftypefun
21 18
22 @deftypefun int envelope_get_message (envelope_t, message_t *); 19 @deftypefun void* envelope_get_owner (envelope_t)
23 @end deftypefun 20 @end deftypefun
24 21
25 @deftypefun int envelope_create (envelope_t *, void *); 22 @c
26 Primarily for internal use. 23 @c ----------
27 @end deftypefun 24 @c
28 25
29 @deftypefun void envelope_destroy (envelope_t *, void *); 26 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *)
30 Primarily for internal use. 27 Get the address that this message was reportedly received from. This
28 would be the "mail from" argument if the message was delivered
29 or received via SMTP, for example.
31 @end deftypefun 30 @end deftypefun
32 31
33 @deftypefun int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *); 32 @deftypefun int envelope_set_sender (envelope_t, int (*@var{_sender}) (envelope_t, char *, size_t, size_t *), void *)
34 Primarily for internal use. The implementation of envelope_t depends 33 Primarily for internal use. The implementation of @code{envelope_t} depends
35 on the mailbox type, this allows the function which actually gets 34 on the mailbox type, this allows the function which actually gets
36 the sender to be set by the creator of an @code{envelope_t}. 35 the sender to be set by the creator of an @code{envelope_t}.
37 @end deftypefun 36 @end deftypefun
38 37
39 @deftypefun int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *); 38 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *)
40 Primarily for internal use. The implementation of envelope_t depends 39 Get the date that the message was delivered to the mailbox, in
40 something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
41 @end deftypefun
42
43 @deftypefun int envelope_set_date (envelope_t, int (*@var{_date}) (envelope_t, char *, size_t, size_t *), void *)
44 Primarily for internal use. The implementation of @code{envelope_t} depends
41 on the mailbox type, this allows the function which actually gets 45 on the mailbox type, this allows the function which actually gets
42 the date to be set by the creator of an @code{envelope_t}. 46 the date to be set by the creator of an @code{envelope_t}.
43 @end deftypefun 47 @end deftypefun
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{folder_} is reserve */} 7 @code{/* Prefix @emph{folder_} is reserved. */}
8 @code{#include <mailutils/folder.h>} 8 @code{#include <mailutils/folder.h>}
9 9
10 @end smallexample 10 @end smallexample
...@@ -12,13 +12,13 @@ ...@@ -12,13 +12,13 @@
12 @smallexample 12 @smallexample
13 @group 13 @group
14 folder_t url_t 14 folder_t url_t
15 -/var/mail- +---//---->/-----------------\ +-->/-----------\ 15 -/var/mail- +---//--->/-----------------\ +-->/-----------\
16 ( alain *-)-+ | | url_t *-|----+ | port | 16 ( alain *-)-+ | | url_t *-|---+ | port |
17 ----------- | | |-----------------+ | hostname | 17 ---------- | | |-----------------+ | hostname |
18 ( jakob *-)-+--+ | observer_t *-| | file | 18 ( jakob *-)-+--+ | observer_t *-| | file |
19 ----------- | |-----------------+ | ... | 19 ---------- | |-----------------+ | ... |
20 ( jeff *-)-+ | stream_t | \-----------/ 20 ( jeff *-)-+ | stream_t | \-----------/
21 ----------- | |-----------------| 21 ---------- | |-----------------|
22 ( sean *-)-+ | auth_t | 22 ( sean *-)-+ | auth_t |
23 ---------- |-----------------| 23 ---------- |-----------------|
24 | mailbox_t(1) | 24 | mailbox_t(1) |
...@@ -30,6 +30,29 @@ ...@@ -30,6 +30,29 @@
30 @end group 30 @end group
31 @end smallexample 31 @end smallexample
32 32
33 Data structures:
34
35 @smallexample
36 @group
37 struct list_response
38 @{
39 int type;
40 int separator;
41 char *name;
42 @};
43
44 struct folder_list
45 @{
46 struct list_response **element;
47 size_t num;
48 @};
49 @end group
50 @end smallexample
51
52 @c
53 @c Constructor/Destructor and possible types.
54 @c
55
33 @deftypefun int folder_create (folder_t *, const char *@var{url}) 56 @deftypefun int folder_create (folder_t *, const char *@var{url})
34 @end deftypefun 57 @end deftypefun
35 58
...@@ -54,33 +77,59 @@ ...@@ -54,33 +77,59 @@
54 @deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox}) 77 @deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox})
55 @end deftypefun 78 @end deftypefun
56 79
57 @deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, iterator_t *) 80 @deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
81 @end deftypefun
82
83 @deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
58 @end deftypefun 84 @end deftypefun
59 85
60 @deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcar}, iterator_t *) 86 @deftypefun int folder_list_destroy (struct folder_list *)
61 @end deftypefun 87 @end deftypefun
62 88
89 @c
90 @c Stream Settings.
91 @c
92
63 @deftypefun int folder_get_stream (folder_t, stream_t *) 93 @deftypefun int folder_get_stream (folder_t, stream_t *)
64 @end deftypefun 94 @end deftypefun
65 95
66 @deftypefun int folder_set_stream (folder_t, stream_t) 96 @deftypefun int folder_set_stream (folder_t, stream_t)
67 @end deftypefun 97 @end deftypefun
68 98
99 @c
100 @c Notifications.
101 @c
102
69 @deftypefun int folder_get_observable (folder_t, observable_t *) 103 @deftypefun int folder_get_observable (folder_t, observable_t *)
70 @end deftypefun 104 @end deftypefun
71 105
72 @deftypefun int folder_get_debug (folder_t, debug_t *) 106 @c
107 @c Debug.
108 @c
109
110 @deftypefun int folder_has_debug (folder_t)
111 @end deftypefun
112
113 @deftypefun int folder_get_debug (folder_t, mu_debug_t *)
73 @end deftypefun 114 @end deftypefun
74 115
75 @deftypefun int folder_set_debug (folder_t, debug_t) 116 @deftypefun int folder_set_debug (folder_t, mu_debug_t)
76 @end deftypefun 117 @end deftypefun
77 118
119 @c
120 @c Authentication.
121 @c
122
78 @deftypefun int folder_get_authority (folder_t, authority_t *) 123 @deftypefun int folder_get_authority (folder_t, authority_t *)
79 @end deftypefun 124 @end deftypefun
80 125
81 @deftypefun int folder_set_authority (folder_t, authority_t) 126 @deftypefun int folder_set_authority (folder_t, authority_t)
82 @end deftypefun 127 @end deftypefun
83 128
129 @c
130 @c URL.
131 @c
132
84 @deftypefun int folder_get_url (folder_t, url_t *) 133 @deftypefun int folder_get_url (folder_t, url_t *)
85 @end deftypefun 134 @end deftypefun
86 135
......
...@@ -36,11 +36,11 @@ etc ..). ...@@ -36,11 +36,11 @@ etc ..).
36 folder_t url_t 36 folder_t url_t
37 -/var/mail- +- .. ->+-----------------+ +-->+------------+ 37 -/var/mail- +- .. ->+-----------------+ +-->+------------+
38 ( alain *-)-+ | | url_t *-|---+ | port | 38 ( alain *-)-+ | | url_t *-|---+ | port |
39 ----------- | | |-----------------| | hostname | 39 ---------- | | |-----------------| | hostname |
40 ( jakob *-)-+--+ | auth_t *-|---+ | file | 40 ( jakob *-)-+--+ | auth_t *-|---+ | file |
41 ----------- | |-----------------| | | ... | 41 ---------- | |-----------------| | | ... |
42 ( jeff *-)-+ | stream_t | | +------------+ 42 ( jeff *-)-+ | stream_t | | +------------+
43 ----------- | |-----------------| | 43 ---------- | |-----------------| |
44 ( shaleh*-)-+ | ..... | | auth_t 44 ( shaleh*-)-+ | ..... | | auth_t
45 ---------- |-----------------| +-->+------------+ 45 ---------- |-----------------| +-->+------------+
46 +---|-* mailbox_t[] | | ticket_t | 46 +---|-* mailbox_t[] | | ticket_t |
...@@ -165,4 +165,3 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha ...@@ -165,4 +165,3 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
165 @node Mailcap 165 @node Mailcap
166 @subsection Mailcap 166 @subsection Mailcap
167 @include mailcap.texi 167 @include mailcap.texi
168
......
...@@ -4,31 +4,43 @@ ...@@ -4,31 +4,43 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{header_} is reserved */} 7 @code{/* Prefix @emph{header_} is reserved. */}
8 @code{#include <mailutils/header.h>} 8 @code{#include <mailutils/header.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII 12 So far we plan support for RFC822 and plan for RFC1522. With RFC1522 non-ASCII
13 characters will be encoded. 13 characters will be encoded.
14 14
15 @deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner}) 15 @deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner})
16 Initialize a @var{hdr} to a supported type. If @var{blurb} is not NULL, it is 16 Initialize a @var{hdr} to a supported type. If @var{blurb} is not @code{NULL},
17 parsed. 17 it is parsed.
18 @end deftypefun 18 @end deftypefun
19 19
20 @deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner}) 20 @deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner})
21 The resources allocated for @var{hdr} are freed. 21 The resources allocated for @var{hdr} are freed.
22 @end deftypefun 22 @end deftypefun
23 23
24 @deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, size_t n, int @var{replace}) 24 @deftypefun void* header_get_owner (header_t *@var{hdr})
25 Set the field-name @var{fn} to field-value @var{fv} of size @var{n} in 25 @end deftypefun
26 @var{hdr}. If @var{replace} is non-zero the initial value is replaced, if zero 26
27 it is appended. 27 @deftypefun int header_is_modified (header_t @var{hdr})
28 @end deftypefun
29
30 @deftypefun int header_clear_modified (header_t @var{hdr})
31 @end deftypefun
32
33 @c
34 @c Set and get field values by field name.
35 @c
28 36
29 Some basic macros are already provided for rfc822. 37 @deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, int @var{n})
38
39 Some basic macros are already provided for RFC822.
30 40
31 @table @code 41 @table @code
42 @item MU_HEADER_UNIX_FROM
43 From
32 @item MU_HEADER_RETURN_PATH 44 @item MU_HEADER_RETURN_PATH
33 Return-Path 45 Return-Path
34 @item MU_HEADER_RECEIVED 46 @item MU_HEADER_RECEIVED
...@@ -37,6 +49,8 @@ Received ...@@ -37,6 +49,8 @@ Received
37 Date 49 Date
38 @item MU_HEADER_FROM 50 @item MU_HEADER_FROM
39 From 51 From
52 @item MU_HEADER_SENDER
53 Sender
40 @item MU_HEADER_RESENT_FROM 54 @item MU_HEADER_RESENT_FROM
41 Resent-From 55 Resent-From
42 @item MU_HEADER_SUBJECT 56 @item MU_HEADER_SUBJECT
...@@ -67,6 +81,10 @@ Message-ID ...@@ -67,6 +81,10 @@ Message-ID
67 Resent-Message-ID 81 Resent-Message-ID
68 @item MU_HEADER_IN_REPLY_TO 82 @item MU_HEADER_IN_REPLY_TO
69 In-Reply-To 83 In-Reply-To
84 @item MU_HEADER_REFERENCE
85 Reference
86 @item MU_HEADER_REFERENCES
87 References
70 @item MU_HEADER_ENCRYPTED 88 @item MU_HEADER_ENCRYPTED
71 Encrypted 89 Encrypted
72 @item MU_HEADER_PRECEDENCE 90 @item MU_HEADER_PRECEDENCE
...@@ -75,10 +93,38 @@ Precedence ...@@ -75,10 +93,38 @@ Precedence
75 Status 93 Status
76 @item MU_HEADER_CONTENT_LENGTH 94 @item MU_HEADER_CONTENT_LENGTH
77 Content-Length 95 Content-Length
96 @item MU_HEADER_CONTENT_LANGUAGE
97 Content-Language
98 @item MU_HEADER_CONTENT_TRANSFER_ENCODING
99 Content-transfer-encoding
100 @item MU_HEADER_CONTENT_ID
101 Content-ID
78 @item MU_HEADER_CONTENT_TYPE 102 @item MU_HEADER_CONTENT_TYPE
79 Content-Type 103 Content-Type
104 @item MU_HEADER_CONTENT_DESCRIPTION
105 Content-Description
106 @item MU_HEADER_CONTENT_DISPOSITION
107 Content-Disposition
108 @item MU_HEADER_CONTENT_MD5
109 Content-MD5
80 @item MU_HEADER_MIME_VERSION 110 @item MU_HEADER_MIME_VERSION
81 MIME-Version 111 MIME-Version
112 @item MU_HEADER_X_UIDL
113 X-UIDL
114 @item MU_HEADER_X_UID
115 X-UID
116 @item MU_HEADER_X_IMAPBASE
117 X-IMAPbase
118 @item MU_HEADER_ENV_SENDER
119 X-Envelope-Sender
120 @item MU_HEADER_ENV_DATE
121 X-Envelope-Date
122 @item MU_HEADER_FCC
123 Fcc
124 @item MU_HEADER_DELIVERY_DATE
125 Delivery-date
126 @item MU_HEADER_ENVELOPE_TO
127 Envelope-to
82 @end table 128 @end table
83 @end deftypefun 129 @end deftypefun
84 130
...@@ -91,11 +137,74 @@ The number of bytes written is put in @var{n}. ...@@ -91,11 +137,74 @@ The number of bytes written is put in @var{n}.
91 The value is allocated. 137 The value is allocated.
92 @end deftypefun 138 @end deftypefun
93 139
94 @deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{pstream}) 140 @c
141 @c Get field values as an address_t.
142 @c
143
144 @deftypefun int header_get_address (header_t @var{hdr}, const char *@var{buf}, address_t *@var{addr})
145 @end deftypefun
146
147 @c
148 @c Stream
149 @c
150
151 @deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{stream})
152 @end deftypefun
153
154 @deftypefun int header_set_stream (header_t @var{hdr}, stream_t @var{stream}, void *)
155 @end deftypefun
156
157 @c
158 @c
159 @c
160
161 @deftypefun int header_get_field_count (header_t @var{hdr}, size_t *@var{count})
162 @end deftypefun
163
164 @deftypefun int header_get_field_value (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
165 @end deftypefun
166
167 @deftypefun int header_get_field_name (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
168 @end deftypefun
169
170 @deftypefun int header_aget_field_value (header_t @var{hdr}, size_t @var{index}, char **)
171 @end deftypefun
172
173 @deftypefun int header_aget_field_name (header_t @var{hdr}, size_t @var{index}, char **)
174 @end deftypefun
175
176 @deftypefun int header_get_value_unfold (header_t @var{hdr}, const char *@var{name}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
177 @end deftypefun
178
179 @deftypefun int header_aget_value_unfold (header_t @var{hdr}, const char *@var{name}, char **@var{value})
180 @end deftypefun
181
182 @deftypefun int header_get_field_value_unfold (header_t @var{hdr}, size_t @var{num}, char *@var{buf}, size_t @var{buflen}, size_t *@var{nwritten})
183 @end deftypefun
184
185 @deftypefun int header_aget_field_value_unfold (header_t @var{hdr}, size_t @var{num}, char **@var{value});
186 @end deftypefun
187
188 @deftypefun int header_size (header_t @var{hdr}, size_t *);
189 @end deftypefun
190
191 @deftypefun int header_lines (header_t @var{hdr}, size_t *);
192 @end deftypefun
193
194 @deftypefun int header_set_set_value (header_t @var{hdr}, int (*@var{_set_value}) (header_t, const char *, const char *, int), void *);
195 @end deftypefun
196
197 @deftypefun int header_set_get_value (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
198 @end deftypefun
199
200 @deftypefun int header_set_get_fvalue (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
201 @end deftypefun
202
203 @deftypefun int header_set_size (header_t @var{hdr}, int (*@var{_size}) (header_t, size_t *), void *);
95 @end deftypefun 204 @end deftypefun
96 205
97 @deftypefun int header_set_size (header_t @var{hdr}, size_t *@var{size}) 206 @deftypefun int header_set_lines (header_t @var{hdr}, int (*@var{_lines}) (header_t, size_t *), void *);
98 @end deftypefun 207 @end deftypefun
99 208
100 @deftypefun int header_set_lines (header_t @var{hdr}, size_t *@var{lpines}) 209 @deftypefun int header_set_fill (header_t @var{hdr}, int (*@var{_fill}) (header_t, char *, size_t, off_t, size_t *), void *@var{owner});
101 @end deftypefun 210 @end deftypefun
......
...@@ -4,11 +4,14 @@ ...@@ -4,11 +4,14 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{iterator_} is reserved */} 7 @code{/* Prefix @emph{iterator_} is reserved. */}
8 @code{#include <mailutils/iterator.h>} 8 @code{#include <mailutils/iterator.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int iterator_create (iterator_t *) 11 @deftypefun int iterator_create (iterator_t *@var{iterator}, list_t)
12 @end deftypefun
13
14 @deftypefun int iterator_dup (iterator_t *@var{iterator}, iterator_t @var{orig})
12 @end deftypefun 15 @end deftypefun
13 16
14 @deftypefun void iterator_destroy (iterator_t *) 17 @deftypefun void iterator_destroy (iterator_t *)
...@@ -20,8 +23,11 @@ ...@@ -20,8 +23,11 @@
20 @deftypefun int iterator_next (iterator_t) 23 @deftypefun int iterator_next (iterator_t)
21 @end deftypefun 24 @end deftypefun
22 25
23 @deftypefun int iterator_current (iterator_t, void **pitem) 26 @deftypefun int iterator_current (iterator_t, void **@var{item})
24 @end deftypefun 27 @end deftypefun
25 28
26 @deftypefun int iterator_is_done (iterator_t) 29 @deftypefun int iterator_is_done (iterator_t)
27 @end deftypefun 30 @end deftypefun
31
32 @deftypefun int iterator_get_list (iterator_t @var{iterator}, list_t *@var{list})
33 @end deftypefun
......
...@@ -30,18 +30,19 @@ This is a pointer to authentication or authorization data. It ...@@ -30,18 +30,19 @@ This is a pointer to authentication or authorization data. It
30 is defined as follows: 30 is defined as follows:
31 31
32 @smallexample 32 @smallexample
33 typedef int (*mu_auth_fp) (void *@var{return_data}, 33 @group
34 typedef int (*mu_auth_fp) (struct mu_auth_data **@var{return_data},
34 void *@var{key}, 35 void *@var{key},
35 void *@var{func_data}, 36 void *@var{func_data},
36 void *@var{call_data}); 37 void *@var{call_data});
38 @end group
37 @end smallexample 39 @end smallexample
40
38 @noindent 41 @noindent
39 Its arguments are: 42 Its arguments are:
40 43
41 @table @var 44 @table @var
42 @item return_data 45 @item return_data
43 @footnote{Actually it shoud have been @code{struct mu_auth_data** return_data}.
44 This will be fixed in the next release}.
45 Upon successful return authorization handler leaves in this memory 46 Upon successful return authorization handler leaves in this memory
46 location a pointer to the filled @code{mu_auth_data} structure 47 location a pointer to the filled @code{mu_auth_data} structure
47 with the user's information. 48 with the user's information.
...@@ -118,7 +119,6 @@ struct mu_auth_module @{ ...@@ -118,7 +119,6 @@ struct mu_auth_module @{
118 @subsection Initializing @file{libmuauth} 119 @subsection Initializing @file{libmuauth}
119 120
120 @deftypefun void mu_auth_init (void) 121 @deftypefun void mu_auth_init (void)
121
122 This function registers the command line capability ``auth''. It must be 122 This function registers the command line capability ``auth''. It must be
123 called after registering @file{libmuauth} modules and before calling 123 called after registering @file{libmuauth} modules and before calling
124 @code{mu_agrp_parse()}. If an error occurs, this function prints 124 @code{mu_agrp_parse()}. If an error occurs, this function prints
...@@ -126,27 +126,24 @@ diagnostic message and aborts the program. ...@@ -126,27 +126,24 @@ diagnostic message and aborts the program.
126 @end deftypefun 126 @end deftypefun
127 127
128 @deftypefun void MU_AUTH_REGISTER_ALL_MODULES (void) 128 @deftypefun void MU_AUTH_REGISTER_ALL_MODULES (void)
129
130 This macro registers all default modules and calls @code{mu_auth_init()}. 129 This macro registers all default modules and calls @code{mu_auth_init()}.
131 @end deftypefun 130 @end deftypefun
132 131
133 @node Module Creation and Destruction 132 @node Module Creation and Destruction
134 @subsection Module Creation and Destruction 133 @subsection Module Creation and Destruction
135 134
136 @deftypefun int mu_auth_data_alloc (struct mu_auth_data **ptr, const char *name, const char *passwd, uid_t uid, gid_t gid, const char *gecos, const char *dir, const char *shell, const char *mailbox, int change_uid) 135 @deftypefun int mu_auth_data_alloc (struct mu_auth_data **@var{ptr}, const char *@var{name}, const char *@var{passwd}, uid_t @var{uid}, gid_t @var{gid}, const char *@var{gecos}, const char *@var{dir}, const char *@var{shell}, const char *@var{mailbox}, int @var{change_uid})
137 136
138 Create a @code{mu_auth_data} structure and initialize it with the given 137 Create a @code{mu_auth_data} structure and initialize it with the given
139 values. Returns 0 on success and 1 otherwise. 138 values. Returns 0 on success and 1 otherwise.
140 @end deftypefun 139 @end deftypefun
141 140
142 @deftypefun void mu_auth_data_free (struct mu_auth_data *@var{ptr}) 141 @deftypefun void mu_auth_data_free (struct mu_auth_data *@var{ptr})
143
144 Free the @code{mu_auth_data} structure allocated by a call to 142 Free the @code{mu_auth_data} structure allocated by a call to
145 @code{mu_auth_data_alloc()}. 143 @code{mu_auth_data_alloc()}.
146 @end deftypefun 144 @end deftypefun
147 145
148 @deftypefun void mu_auth_register_module (struct mu_auth_module *@var{mod}) 146 @deftypefun void mu_auth_register_module (struct mu_auth_module *@var{mod})
149
150 Register the module defined by the @var{mod} argument. 147 Register the module defined by the @var{mod} argument.
151 @end deftypefun 148 @end deftypefun
152 149
...@@ -154,8 +151,7 @@ Register the module defined by the @var{mod} argument. ...@@ -154,8 +151,7 @@ Register the module defined by the @var{mod} argument.
154 @subsection Obtaining Authorization Information 151 @subsection Obtaining Authorization Information
155 @cindex libmuauth, obtaining authorization information 152 @cindex libmuauth, obtaining authorization information
156 153
157 @deftypefun int mu_auth_runlist (list_t @var{flist}, void *@var{return_data}, void *@var{key}, void *@var{call_data}); 154 @deftypefun int mu_auth_runlist (list_t @var{flist}, struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{call_data});
158
159 The list is expected to contain @code{mu_auth_fp} pointers. Each of them 155 The list is expected to contain @code{mu_auth_fp} pointers. Each of them
160 is dereferenced and executed until either the list is exhausted or any 156 is dereferenced and executed until either the list is exhausted or any
161 of the functions returns non-zero, whichever occurs first. The 157 of the functions returns non-zero, whichever occurs first. The
...@@ -170,10 +166,8 @@ return code from the succeeded function. ...@@ -170,10 +166,8 @@ return code from the succeeded function.
170 @end deftypefun 166 @end deftypefun
171 167
172 @deftypefun {struct mu_auth_data *} mu_get_auth_by_name (const char *@var{username}) 168 @deftypefun {struct mu_auth_data *} mu_get_auth_by_name (const char *@var{username})
173
174 Search the information about given user by its username. Similar to 169 Search the information about given user by its username. Similar to
175 system's @code{getpwnam} call). 170 system's @code{getpwnam} call).
176
177 @end deftypefun 171 @end deftypefun
178 172
179 @deftypefun {struct mu_auth_data *} mu_get_auth_by_uid (uid_t @var{uid}) 173 @deftypefun {struct mu_auth_data *} mu_get_auth_by_uid (uid_t @var{uid})
...@@ -182,7 +176,6 @@ system's @code{getpwuid} call). ...@@ -182,7 +176,6 @@ system's @code{getpwuid} call).
182 @end deftypefun 176 @end deftypefun
183 177
184 @deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass}) 178 @deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass})
185
186 Authenticate the user whose data are in @var{auth_data} using password 179 Authenticate the user whose data are in @var{auth_data} using password
187 @var{pass}. Return 0 if the user is authenticated. 180 @var{pass}. Return 0 if the user is authenticated.
188 @end deftypefun 181 @end deftypefun
...@@ -191,20 +184,17 @@ Authenticate the user whose data are in @var{auth_data} using password ...@@ -191,20 +184,17 @@ Authenticate the user whose data are in @var{auth_data} using password
191 @subsection Existing Modules 184 @subsection Existing Modules
192 @cindex libmuauth modules 185 @cindex libmuauth modules
193 186
194 @deftypefun int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data); 187 @deftypefun int mu_auth_nosupport (struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{func_data}, void *@var{call_data});
195
196 The ``not-supported'' module. Always returns @code{ENOSYS}. 188 The ``not-supported'' module. Always returns @code{ENOSYS}.
197 @end deftypefun 189 @end deftypefun
198 190
199 @defvar mu_auth_system_module 191 @defvar mu_auth_system_module
200
201 This module is always registered even if @file{libmuauth} is not linked. 192 This module is always registered even if @file{libmuauth} is not linked.
202 It performs usual authentication using system user database 193 It performs usual authentication using system user database
203 (@file{/etc/password} et al.) 194 (@file{/etc/password} et al.)
204 @end defvar 195 @end defvar
205 196
206 @defvar mu_auth_generic_module 197 @defvar mu_auth_generic_module
207
208 This module is always registered even if @file{libmuauth} is not linked. 198 This module is always registered even if @file{libmuauth} is not linked.
209 Both its authorization handlers are @code{mu_auth_nosupport}. Its 199 Both its authorization handlers are @code{mu_auth_nosupport}. Its
210 authentication handler computes the MD5 or DES hash over the supplied 200 authentication handler computes the MD5 or DES hash over the supplied
...@@ -214,13 +204,11 @@ member itself and returns 1 if both strings match. ...@@ -214,13 +204,11 @@ member itself and returns 1 if both strings match.
214 @end defvar 204 @end defvar
215 205
216 @defvar mu_auth_pam_module 206 @defvar mu_auth_pam_module
217
218 Implements PAM authentication. Both authorization handlers are 207 Implements PAM authentication. Both authorization handlers are
219 @code{mu_auth_nosupport()}. 208 @code{mu_auth_nosupport()}.
220 @end defvar 209 @end defvar
221 210
222 @defvar mu_auth_sql_module 211 @defvar mu_auth_sql_module
223
224 Implements authentication and authorization via MySQL database. The 212 Implements authentication and authorization via MySQL database. The
225 credentials for accessing the database are taken from global variables 213 credentials for accessing the database are taken from global variables
226 @code{sql_host}, @code{sql_port}, @code{sql_user}, @code{sql_passwd} 214 @code{sql_host}, @code{sql_port}, @code{sql_user}, @code{sql_passwd}
...@@ -232,7 +220,6 @@ information on command line options used to set these variables. ...@@ -232,7 +220,6 @@ information on command line options used to set these variables.
232 @end defvar 220 @end defvar
233 221
234 @defvar mu_auth_virtual_module 222 @defvar mu_auth_virtual_module
235
236 Implements @code{mu_get_auth_by_name} method using virtual mail domains. 223 Implements @code{mu_get_auth_by_name} method using virtual mail domains.
237 Neither @code{mu_get_auth_by_uid} nor @code{mu_authenticate} is 224 Neither @code{mu_get_auth_by_uid} nor @code{mu_authenticate} is
238 implemented. This module must be used together with @code{generic} 225 implemented. This module must be used together with @code{generic}
......
...@@ -389,7 +389,7 @@ match_part_checker (const char *name, list_t tags, list_t args) ...@@ -389,7 +389,7 @@ match_part_checker (const char *name, list_t tags, list_t args)
389 @end smallexample 389 @end smallexample
390 @end deftypefun 390 @end deftypefun
391 391
392 @deftypefun void *sieve_get_data (sieve_machine_t @var{mach}) 392 @deftypefun void* sieve_get_data (sieve_machine_t @var{mach})
393 This function returns the application-specific data associated with 393 This function returns the application-specific data associated with
394 the instance of sieve machine. See @code{sieve_machine_init()}. 394 the instance of sieve machine. See @code{sieve_machine_init()}.
395 @end deftypefun 395 @end deftypefun
......
...@@ -4,28 +4,73 @@ ...@@ -4,28 +4,73 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{locker_} is reserved */} 7 @code{/* Prefix @emph{locker_} is reserved. */}
8 @code{#include <mailutils/locker.h>} 8 @code{#include <mailutils/locker.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags}) 11 @deftypefun int locker_set_default_flags (int @var{flags}, enum mu_locker_set_mode @var{mode})
12 @end deftypefun 12 @end deftypefun
13 13
14 @deftypefun void locker_destroy (locker_t * @var{plocker}) 14 @deftypefun void locker_set_default_retry_timeout (time_t @var{to})
15 @end deftypefun 15 @end deftypefun
16 16
17 @deftypefun int locker_lock (locker_t @var{locker}, int @var{flag}) 17 @deftypefun void locker_set_default_retry_count (size_t @var{n})
18 @table @code
19 @item MU_LOCKER_RDLOCK
20 @item MU_LOCKER_WRLOCK
21 @item MU_LOCKER_PID
22 @item MU_LOCKER_FCNTL
23 @item MU_LOCKER_TIME
24 @end table
25 @end deftypefun 18 @end deftypefun
26 19
27 @deftypefun int locker_touchlock (locker_t @var{locker}) 20 @deftypefun void locker_set_default_expire_timeout (time_t @var{t})
28 @end deftypefun 21 @end deftypefun
29 22
30 @deftypefun int locker_unlock (locker_t @var{locker}) 23 @deftypefun void locker_set_default_external_program (char *@var{path})
24 @end deftypefun
25
26 A flags of 0 means that the default will be used.
27
28 @deftypefun int locker_create (locker_t *, const char *@var{filename}, int @var{flags})
29 @end deftypefun
30
31 @deftypefun void locker_destroy (locker_t *)
32 @end deftypefun
33
34 Time is measured in seconds.
35
36 @deftypefun int locker_set_flags (locker_t, int)
37 @end deftypefun
38
39 @deftypefun int locker_set_expire_time (locker_t, int)
40 @end deftypefun
41
42 @deftypefun int locker_set_retries (locker_t, int)
43 @end deftypefun
44
45 @deftypefun int locker_set_retry_sleep (locker_t, int)
46 @end deftypefun
47
48 @deftypefun int locker_set_external (locker_t, const char *@var{program})
49 @end deftypefun
50
51 @deftypefun int locker_get_flags (locker_t, int *)
52 @end deftypefun
53
54 @deftypefun int locker_get_expire_time (locker_t, int*)
55 @end deftypefun
56
57 @deftypefun int locker_get_retries (locker_t, int *)
58 @end deftypefun
59
60 @deftypefun int locker_get_retry_sleep (locker_t, int *)
61 @end deftypefun
62
63 @deftypefun int locker_get_external (locker_t, char **)
64 @end deftypefun
65
66 @deftypefun int locker_lock (locker_t)
67 @end deftypefun
68
69 @deftypefun int locker_touchlock (locker_t)
70 @end deftypefun
71
72 @deftypefun int locker_unlock (locker_t)
73 @end deftypefun
74
75 @deftypefun int locker_remove_lock (locker_t)
31 @end deftypefun 76 @end deftypefun
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{mailbox_} is reserved */} 7 @code{/* Prefix @emph{mailbox_} is reserved. */}
8 @code{#include <mailutils/mailbox.h>} 8 @code{#include <mailutils/mailbox.h>}
9 @end smallexample 9 @end smallexample
10 10
...@@ -17,13 +17,13 @@ from the data structure. ...@@ -17,13 +17,13 @@ from the data structure.
17 @smallexample 17 @smallexample
18 @group 18 @group
19 mailbox_t url_t 19 mailbox_t url_t
20 -/var/mail- +---//---->/-----------------\ +-->/-----------\ 20 -/var/mail- +---//--->/-----------------\ +-->/-----------\
21 ( alain ) | | url_t *-|----+ | port | 21 ( alain ) | | url_t *-|---+ | port |
22 ----------- | |-----------------+ | hostname | 22 ---------- | |-----------------+ | hostname |
23 ( jakob *-)----+ | observer_t *-| | file | 23 ( jakob *-)----+ | observer_t *-| | file |
24 ----------- |-----------------+ | ... | 24 ---------- |-----------------+ | ... |
25 ( jeff ) | stream_t | \-----------/ 25 ( jeff ) | stream_t | \-----------/
26 ----------- |-----------------| 26 ---------- |-----------------|
27 ( sean ) | locker_t | 27 ( sean ) | locker_t |
28 ---------- |-----------------| 28 ---------- |-----------------|
29 | message_t(1) | 29 | message_t(1) |
...@@ -35,35 +35,19 @@ from the data structure. ...@@ -35,35 +35,19 @@ from the data structure.
35 @end group 35 @end group
36 @end smallexample 36 @end smallexample
37 37
38 @deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message}) 38 @c
39 The @var{message} is appended to the mailbox @var{mbox}. 39 @c Constructor/destructor and possible types.
40 40 @c
41 The return value is @code{0} on success and a code number on error conditions:
42 @table @code
43 @item MU_ERROR_INVALID_PARAMETER
44 @var{mbox} is null or @var{message} is invalid.
45 @end table
46 @end deftypefun
47
48 @deftypefun int mailbox_close (mailbox_t @var{mbox})
49 The stream attach to @var{mbox} is closed.
50 41
51 The return value is @code{0} on success and a code number on error conditions: 42 @deftypefun int mailbox_create (mailbox_t *@var{mbox}, const char *@var{name})
52 @table @code 43 The function @code{mailbox_create} allocates and initializes @var{mbox}.
53 @item MU_ERROR_INVALID_PARAMETER
54 @var{mbox} is null.
55 @end table
56 @end deftypefun
57
58 @deftypefun int mailbox_create (mailbox_t *@var{pmbox}, const char *@var{name})
59 The function @code{mailbox_create} allocates and initializes @var{pmbox}.
60 The concrete mailbox type instantiate is based on the scheme of the url @var{name}. 44 The concrete mailbox type instantiate is based on the scheme of the url @var{name}.
61 45
62 The return value is @code{0} on success and a code number on error conditions: 46 The return value is @code{0} on success and a code number on error conditions:
63 @table @code 47 @table @code
64 48
65 @item MU_ERR_OUT_PTR_NULL 49 @item MU_ERR_OUT_PTR_NULL
66 The pointer @var{pmbox} supplied is NULL. 50 The pointer @var{mbox} supplied is @code{NULL}.
67 @item MU_ERR_NO_HANDLER 51 @item MU_ERR_NO_HANDLER
68 The url @var{name} supplied is invalid or not supported. 52 The url @var{name} supplied is invalid or not supported.
69 @item EINVAL 53 @item EINVAL
...@@ -72,198 +56,215 @@ Not enough memory to allocate resources. ...@@ -72,198 +56,215 @@ Not enough memory to allocate resources.
72 @end table 56 @end table
73 @end deftypefun 57 @end deftypefun
74 58
75 @deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{name}) 59 @deftypefun int mailbox_create_default (mailbox_t *@var{mbox}, const char *@var{name})
76 Create a mailbox with @code{mailbox_create ()} based on the environment 60 Create a mailbox with @code{mailbox_create()} based on the environment
77 variable @emph{$MAIL} or the string formed by 61 variable @env{MAIL} or the string formed by
78 @emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null, 62 @emph{_PATH_MAILDIR}/@var{user}" or @env{LOGNAME} if @var{user} is null,
79 @end deftypefun 63 @end deftypefun
80 64
81 @deftypefun void mailbox_destroy (mailbox_t *@var{pmbox}) 65 @deftypefun void mailbox_destroy (mailbox_t *@var{mbox})
82 Destroys and releases resources held by @var{pmbox}. 66 Destroys and releases resources held by @var{mbox}.
83 @end deftypefun 67 @end deftypefun
84 68
85 @deftypefun int mailbox_expunge (mailbox_t @var{mbox}) 69 @deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag})
86 All messages marked for deletion are removed. 70 A connection is open, if no stream was provided, a stream
71 is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
72 See @code{stream_create()} for @var{flag}'s description.
87 73
88 The return value is @code{0} on success and a code number on error conditions: 74 The return value is @code{0} on success and a code number on error conditions:
89 @table @code 75 @table @code
76 @item EAGAIN
77 @itemx EINPROGRESS
78 Operation in progress.
79 @item EBUSY
80 Resource busy.
90 @item MU_ERROR_INVALID_PARAMETER 81 @item MU_ERROR_INVALID_PARAMETER
91 @var{mbox} is null. 82 @var{mbox} is @code{NULL} or flag is invalid.
83 @item ENOMEM
84 Not enough memory.
92 @end table 85 @end table
93 @end deftypefun 86 @end deftypefun
94 87
95 @deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder}) 88 @deftypefun int mailbox_close (mailbox_t @var{mbox})
96 Get the @var{folder}. 89 The stream attach to @var{mbox} is closed.
97 90
98 The return value is @code{0} on success and a code number on error conditions: 91 The return value is @code{0} on success and a code number on error conditions:
99 @table @code 92 @table @code
100 @item MU_ERROR_INVALID_PARAMETER 93 @item MU_ERROR_INVALID_PARAMETER
101 @var{mbox} is null. 94 @var{mbox} is @code{NULL}.
102 @end table 95 @end table
103 @end deftypefun 96 @end deftypefun
104 97
105 @deftypefun int mailbox_get_debug (mailbox_t @var{mbox}, debug_t *@var{debug}) 98 @deftypefun int mailbox_flush (mailbox_t @var{mbox}, int @var{expunge})
106 Get a debug object.
107 The return value is @code{0} on success and a code number on error conditions:
108 @table @code
109 @item MU_ERROR_INVALID_PARAMETER
110 @var{mbox} is null.
111 @item ENOMEM
112 @end table
113 @end deftypefun 99 @end deftypefun
114 100
115 @deftypefun int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{plocker}) 101 @deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
116 Return the @var{locker} object. 102 Get the @var{folder}.
117 103
118 The return value is @code{0} on success and a code number on error conditions: 104 The return value is @code{0} on success and a code number on error conditions:
119 @table @code 105 @table @code
120 @item MU_ERROR_INVALID_PARAMETER 106 @item MU_ERROR_INVALID_PARAMETER
121 @var{mbox} is null. 107 @var{mbox} is @code{NULL}.
122 @end table 108 @end table
123 @end deftypefun 109 @end deftypefun
124 110
125 @deftypefun int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{pmessage}) 111 @deftypefun int mailbox_set_folder (mailbox_t @var{mbox}, folder_t @var{folder})
126 Retrieve message number @var{msgno}, @var{pmessage} is allocated and 112 @end deftypefun
127 initialized. 113
114 @deftypefun int mailbox_uidvalidity (mailbox_t @var{mbox}, unsigned long *@var{number});
115 Give the uid validity of @var{mbox}.
128 116
129 The return value is @code{0} on success and a code number on error conditions: 117 The return value is @code{0} on success and a code number on error conditions:
130 @table @code 118 @table @code
131 @item MU_ERROR_INVALID_PARAMETER 119 @item MU_ERROR_INVALID_PARAMETER
132 @var{mbox} is null or @var{msgno} is invalid. 120 @var{mbox} is @code{NULL}.
133 @item ENOMEM
134 Not enough memory.
135 @end table 121 @end table
136 @end deftypefun 122 @end deftypefun
137 123
138 @deftypefun int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t*@var{observable}) 124 @deftypefun int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{number});
139 Get the observable object. 125 Give the next predicted uid for @var{mbox}.
140 126
141 The return value is @code{0} on success and a code number on error conditions: 127 The return value is @code{0} on success and a code number on error conditions:
142 @table @code 128 @table @code
143 @item MU_ERROR_INVALID_PARAMETER 129 @item MU_ERROR_INVALID_PARAMETER
144 @var{mbox} is null. 130 @var{mbox} is @code{NULL}.
145 @item ENOMEM
146 Not enough memory.
147 @end table 131 @end table
148 @end deftypefun 132 @end deftypefun
149 133
150 @deftypefun int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property}) 134 @c
151 Get the property object. 135 @c Messages.
136 @c
137
138 @deftypefun int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{message})
139 Retrieve message number @var{msgno}, @var{message} is allocated and
140 initialized.
141
152 The return value is @code{0} on success and a code number on error conditions: 142 The return value is @code{0} on success and a code number on error conditions:
153 @table @code 143 @table @code
154 @item MU_ERROR_INVALID_PARAMETER 144 @item MU_ERROR_INVALID_PARAMETER
155 @var{mbox} is null. 145 @var{mbox} is @code{NULL} or @var{msgno} is invalid.
156 @item ENOMEM 146 @item ENOMEM
147 Not enough memory.
157 @end table 148 @end table
158 @end deftypefun 149 @end deftypefun
159 150
160 @deftypefun int mailbox_get_size (mailbox_t @var{mbox}, off_t *@var{psize}) 151 @deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
161 Gives the @var{mbox} size. 152 The @var{message} is appended to the mailbox @var{mbox}.
162 153
163 The return value is @code{0} on success and a code number on error conditions: 154 The return value is @code{0} on success and a code number on error conditions:
164 @table @code 155 @table @code
165 @item MU_ERROR_INVALID_PARAMETER 156 @item MU_ERROR_INVALID_PARAMETER
166 @var{mbox} is null. 157 @var{mbox} is @code{NULL} or @var{message} is invalid.
167 @end table 158 @end table
168 @end deftypefun 159 @end deftypefun
169 160
170 @deftypefun int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{pstream}) 161 @deftypefun int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{number});
171 The mailbox stream is put in @var{pstream}. 162 Give the number of messages in @var{mbox}.
172 163
173 The return value is @code{0} on success and a code number on error conditions: 164 The return value is @code{0} on success and a code number on error conditions:
174 @table @code 165 @table @code
175 @item MU_ERROR_INVALID_PARAMETER 166 @item MU_ERROR_INVALID_PARAMETER
176 @var{mbox} is invalid or @var{pstream} is NULL. 167 @var{mbox} is @code{NULL}.
177 @end table 168 @end table
178 @end deftypefun 169 @end deftypefun
179 170
180 @deftypefun int mailbox_get_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket}) 171 @deftypefun int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{number});
181 The return value is @code{0} on success and a code number on error conditions: 172 Give the number of recent messages in @var{mbox}.
182 173
174 The return value is @code{0} on success and a code number on error conditions:
183 @table @code 175 @table @code
184 @item MU_ERROR_INVALID_PARAMETER 176 @item MU_ERROR_INVALID_PARAMETER
185 @var{mbox} is null. 177 @var{mbox} is @code{NULL}.
186 @end table 178 @end table
187 @end deftypefun 179 @end deftypefun
188 180
189 @deftypefun int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{purl}) 181 @deftypefun int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{number});
190 Gives the constructed @var{url}. 182 Give the number of first unseen message in @var{mbox}.
191 183
192 The return value is @code{0} on success and a code number on error conditions: 184 The return value is @code{0} on success and a code number on error conditions:
193 @table @code 185 @table @code
194 @item MU_ERROR_INVALID_PARAMETER 186 @item MU_ERROR_INVALID_PARAMETER
195 @var{mbox} is null. 187 @var{mbox} is @code{NULL}.
196 @end table 188 @end table
197 @end deftypefun 189 @end deftypefun
198 190
199 @deftypefun int mailbox_is_modified (mailbox_t @var{mbox}) 191 @deftypefun int mailbox_expunge (mailbox_t @var{mbox})
200 Check if the mailbox been modified by an external source. 192 All messages marked for deletion are removed.
201 193
202 The return value is @code{0} on success and a code number on error conditions: 194 The return value is @code{0} on success and a code number on error conditions:
203 @table @code 195 @table @code
204 @item MU_ERROR_INVALID_PARAMETER 196 @item MU_ERROR_INVALID_PARAMETER
205 @var{mbox} is null. 197 @var{mbox} is @code{NULL}.
206 @end table 198 @end table
207 @end deftypefun 199 @end deftypefun
208 200
209 @deftypefun int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{pnumber}); 201 @deftypefun int mailbox_save_attributes (mailbox_t @var{mbox})
210 Give the number of first unseen message in @var{mbox}. 202 @end deftypefun
203
204 @c
205 @c Update and Scanning.
206 @c
207
208 @deftypefun int mailbox_get_size (mailbox_t @var{mbox}, off_t *@var{size})
209 Gives the @var{mbox} size.
211 210
212 The return value is @code{0} on success and a code number on error conditions: 211 The return value is @code{0} on success and a code number on error conditions:
213 @table @code 212 @table @code
214 @item MU_ERROR_INVALID_PARAMETER 213 @item MU_ERROR_INVALID_PARAMETER
215 @var{mbox} is null. 214 @var{mbox} is @code{NULL}.
216 @end table 215 @end table
217 @end deftypefun 216 @end deftypefun
218 217
219 @deftypefun int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{pnumber}); 218 @deftypefun int mailbox_is_updated (mailbox_t @var{mbox})
220 Give the number of messages in @var{mbox}. 219 @end deftypefun
220
221 @deftypefun int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{count});
222 Scan the mailbox for new messages starting at message @var{msgno}.
221 223
222 The return value is @code{0} on success and a code number on error conditions: 224 The return value is @code{0} on success and a code number on error conditions:
223 @table @code 225 @table @code
224 @item MU_ERROR_INVALID_PARAMETER 226 @item MU_ERROR_INVALID_PARAMETER
225 @var{mbox} is null. 227 @var{mbox} is @code{NULL}.
228 @item ENOMEM
229 Not enough memory.
226 @end table 230 @end table
227 @end deftypefun 231 @end deftypefun
228 232
229 @deftypefun int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{pnumber}); 233 @c
230 Give the number of recent messages in @var{mbox}. 234 @c Mailbox Stream.
235 @c
236
237 @deftypefun int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{stream})
238 The mailbox stream is put in @var{stream}.
231 239
232 The return value is @code{0} on success and a code number on error conditions: 240 The return value is @code{0} on success and a code number on error conditions:
233 @table @code 241 @table @code
234 @item MU_ERROR_INVALID_PARAMETER 242 @item MU_ERROR_INVALID_PARAMETER
235 @var{mbox} is null. 243 @var{mbox} is invalid or @var{stream} is @code{NULL}.
236 @end table 244 @end table
237 @end deftypefun 245 @end deftypefun
238 246
239 @deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag}) 247 @deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream})
240 A connection is open, if no stream was provided, a stream 248 Set the @var{stream} connection to use for the mailbox.
241 is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
242 See @code{stream_create} for @var{flag}'s description.
243 249
244 The return value is @code{0} on success and a code number on error conditions: 250 The return value is @code{0} on success and a code number on error conditions:
245 @table @code 251 @table @code
246 @item EAGAIN
247 @itemx EINPROGRESS
248 Operation in progress.
249 @item EBUSY
250 Resource busy.
251 @item MU_ERROR_INVALID_PARAMETER 252 @item MU_ERROR_INVALID_PARAMETER
252 @var{mbox} is null or flag is invalid. 253 @var{mbox} or @var{stream} is @code{NULL}.
253 @item ENOMEM
254 Not enough memory.
255 @end table 254 @end table
256 @end deftypefun 255 @end deftypefun
257 256
258 @deftypefun int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{pcount}); 257 @c
259 Scan the mailbox for new messages starting at message @var{msgno}. 258 @c Lock Settings.
259 @c
260
261 @deftypefun int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{locker})
262 Get the @var{locker_t} object.
260 263
261 The return value is @code{0} on success and a code number on error conditions: 264 The return value is @code{0} on success and a code number on error conditions:
262 @table @code 265 @table @code
263 @item MU_ERROR_INVALID_PARAMETER 266 @item MU_ERROR_INVALID_PARAMETER
264 @var{mbox} is null. 267 @var{mbox} is @code{NULL}.
265 @item ENOMEM
266 Not enough memory.
267 @end table 268 @end table
268 @end deftypefun 269 @end deftypefun
269 270
...@@ -273,46 +274,80 @@ Set the type of locking done by the @var{mbox}. ...@@ -273,46 +274,80 @@ Set the type of locking done by the @var{mbox}.
273 The return value is @code{0} on success and a code number on error conditions: 274 The return value is @code{0} on success and a code number on error conditions:
274 @table @code 275 @table @code
275 @item MU_ERROR_INVALID_PARAMETER 276 @item MU_ERROR_INVALID_PARAMETER
276 @var{mbox} is null. 277 @var{mbox} is @code{NULL}.
277 @end table 278 @end table
278 @end deftypefun 279 @end deftypefun
279 280
280 @deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream}) 281 @c
281 Set the @var{stream} connection to use for the mailbox. 282 @c Property.
283 @c
282 284
285 @deftypefun int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property})
286 Get the property object.
283 The return value is @code{0} on success and a code number on error conditions: 287 The return value is @code{0} on success and a code number on error conditions:
284 @table @code 288 @table @code
285 @item MU_ERROR_INVALID_PARAMETER 289 @item MU_ERROR_INVALID_PARAMETER
286 @var{mbox} or @var{stream} is NULL. 290 @var{mbox} is @code{NULL}.
291 @item ENOMEM
287 @end table 292 @end table
288 @end deftypefun 293 @end deftypefun
289 294
290 @deftypefun int mailbox_set_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket}) 295 @c
291 The @var{ticket} will be set on the @code{auth_t} object on creation. 296 @c URL.
297 @c
298
299 @deftypefun int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{url})
300 Gives the constructed @var{url}.
292 301
293 The return value is @code{0} on success and a code number on error conditions: 302 The return value is @code{0} on success and a code number on error conditions:
294 @table @code 303 @table @code
295 @item MU_ERROR_INVALID_PARAMETER 304 @item MU_ERROR_INVALID_PARAMETER
296 @var{mbox} is null. 305 @var{mbox} is @code{NULL}.
297 @end table 306 @end table
298 @end deftypefun 307 @end deftypefun
299 308
300 @deftypefun int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{pnumber}); 309 @c
301 Give the next predicted uid for @var{mbox}. 310 @c Debug.
311 @c
312
313 @deftypefun int mailbox_has_debug (mailbox_t @var{mbox})
314 @end deftypefun
302 315
316 @deftypefun int mailbox_get_debug (mailbox_t @var{mbox}, mu_debug_t *@var{debug})
317 Get a debug object.
303 The return value is @code{0} on success and a code number on error conditions: 318 The return value is @code{0} on success and a code number on error conditions:
304 @table @code 319 @table @code
305 @item MU_ERROR_INVALID_PARAMETER 320 @item MU_ERROR_INVALID_PARAMETER
306 @var{mbox} is null. 321 @var{mbox} is @code{NULL}.
322 @item ENOMEM
307 @end table 323 @end table
308 @end deftypefun 324 @end deftypefun
309 325
310 @deftypefun int mailbox_uidvalidity (mailbox_t @var{mbox}, size_t *@var{pnumber}); 326 @deftypefun int mailbox_set_debug (mailbox_t @var{mbox}, mu_debug_t @var{debug})
311 Give the uid validity of @var{mbox}. 327 @end deftypefun
328
329 @c
330 @c Events.
331 @c
332
333 @deftypefun int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t *@var{observable})
334 Get the observable object.
312 335
313 The return value is @code{0} on success and a code number on error conditions: 336 The return value is @code{0} on success and a code number on error conditions:
314 @table @code 337 @table @code
315 @item MU_ERROR_INVALID_PARAMETER 338 @item MU_ERROR_INVALID_PARAMETER
316 @var{mbox} is null. 339 @var{mbox} is @code{NULL}.
340 @item ENOMEM
341 Not enough memory.
317 @end table 342 @end table
318 @end deftypefun 343 @end deftypefun
344
345 @c
346 @c Locking
347 @c
348
349 @deftypefun int mailbox_lock (mailbox_t @var{mbox})
350 @end deftypefun
351
352 @deftypefun int mailbox_unlock (mailbox_t @var{mbox})
353 @end deftypefun
......
...@@ -4,61 +4,68 @@ ...@@ -4,61 +4,68 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{mu_mailcap_} is reserved */} 7 @code{/* Prefix @emph{mu_mailcap_} is reserved. */}
8 @code{#include <mailutils/mailcap.h>} 8 @code{#include <mailutils/mailcap.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 The standard @cite{RFC 1524} (A User Agent Configuration Mechanism) suggests a file format 12 The standard @cite{RFC 1524} (A User Agent Configuration Mechanism)
13 to be used to inform a mail user agent about facilities for handling mail in various 13 suggests a file format to be used to inform a mail user agent about
14 format. The configuration file is known also as mailcap and it is tipically found 14 facilities for handling mail in various format. The configuration
15 in UNIX platforms, a example of @file{/etc/mailcap}: 15 file is known also as mailcap and it is tipically found in UNIX
16 platforms, a example of @file{/etc/mailcap}:
16 17
17 @smallexample 18 @smallexample
19 @group
18 application/pgp; gpg < %s | metamail; needsterminal; \ 20 application/pgp; gpg < %s | metamail; needsterminal; \
19 test=test %@{encapsulation@}=entity ; copiousoutput 21 test=test %@{encapsulation@}=entity ; copiousoutput
22 @end group
20 @end smallexample 23 @end smallexample
21 24
22 A mailcap file consits of a set of mailcap entries per line, lines beginning with @samp{#} are 25 A mailcap file consits of a set of mailcap entries per line, lines
23 considered comments and ignored. Long mailcap entry may be continued on multiple lines if 26 beginning with @samp{#} are considered comments and ignored. Long
24 each line ends with a backslash character @samp{\}, the multiline will be considered a single 27 mailcap entry may be continued on multiple lines if each line ends
25 mailcap entry. The overall format in BNF: 28 with a backslash character @samp{\}, the multiline will be considered
29 a single mailcap entry. The overall format in @acronym{BNF}:
26 30
27 @smallexample 31 @smallexample
28 Mailcap-File = *Mailcap-Line 32 @group
29 Mailcap-Line = Comment | Mailcap-Entry 33 Mailcap-File = *@var{mailcap-line}
30 Comment = NEWLINE | "#" * CHAR NEWLINE 34 Mailcap-Line = @var{comment} | @var{mailcap-entry}
31 NEWLINE = <newline as defined by OS convention> 35 Comment = @var{newline} | "#" * @var{char} @var{newline}
36 Newline = <newline as defined by OS convention>
37 @end group
32 @end smallexample 38 @end smallexample
33 39
34 Each mailcap entry consists of a number of fields, separated by semi-colons. 40 Each mailcap entry consists of a number of fields, separated
35 The first two filds are required and must occur in the secified order, the remaining 41 by semi-colons. The first two filds are required and must occur
36 fields are optional. 42 in the secified order, the remaining fields are optional.
37 43
38 @smallexample 44 @smallexample
39 Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ] 45 Mailcap-Entry = @var{typefield} ";" @var{view-command} ";" *[ ";" @var{field} ]
40 @end smallexample 46 @end smallexample
41 47
42 @deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t 48 @deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t
43 The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects are used to hold information 49 The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects
44 and it is an opaque data structure to the user. Functions are provided to retrieve information 50 are used to hold information and it is an opaque data structure
51 to the user. Functions are provided to retrieve information
45 from the data structure. 52 from the data structure.
46 @end deftp 53 @end deftp
47 54
48 @smallexample 55 @smallexample
49 @group 56 @group
50 mu_mailcap_t mu_mailcap_entry_t 57 mu_mailcap_t mu_mailcap_entry_t
51 -/etc/mailcap- +----->/------------------------\ +-->/--------------------\ 58 -/etc/mailcap- +--->/------------------------\ +-->/------------------\
52 ( alain ) | mu_mailcap_entry[0]*--|----+ | typefield | 59 ( alain ) | mu_mailcap_entry[0]*--|--+ | typefield |
53 | mu_mailcap_entry[1] | | view-command | 60 | mu_mailcap_entry[1] | | view-command |
54 | ..... | | field[0] | 61 | ..... | | field[0] |
55 | mu_mailcap_entry[n] | | ..... | 62 | mu_mailcap_entry[n] | | ..... |
56 \------------------------/ | field[n] | 63 \------------------------/ | field[n] |
57 \--------------------/ 64 \------------------/
58 @end group 65 @end group
59 @end smallexample 66 @end smallexample
60 67
61 @subheading An example of parsing a mailcap file: 68 @subheading An Example of Parsing a Mailcap File:
62 @smallexample 69 @smallexample
63 @include mailcap.inc 70 @include mailcap.inc
64 @end smallexample 71 @end smallexample
...@@ -68,7 +75,7 @@ The function allocates, parses the buffer from the @var{stream} and initializes ...@@ -68,7 +75,7 @@ The function allocates, parses the buffer from the @var{stream} and initializes
68 The return value is @code{0} on success and a code number on error conditions: 75 The return value is @code{0} on success and a code number on error conditions:
69 @table @code 76 @table @code
70 @item MU_ERROR_INVALID_PARAMETER 77 @item MU_ERROR_INVALID_PARAMETER
71 @var{mailcap} is null or @var{stream} is invalid. 78 @var{mailcap} is @code{NULL} or @var{stream} is invalid.
72 @end table 79 @end table
73 @end deftypefun 80 @end deftypefun
74 81
...@@ -82,18 +89,12 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -82,18 +89,12 @@ The return value is @code{0} on success and a code number on error conditions:
82 @table @code 89 @table @code
83 90
84 @item EINVAL 91 @item EINVAL
85 @var{mailcap} or @var{count} is null. 92 @var{mailcap} or @var{count} is @code{NULL}.
86 @end table 93 @end table
87 @end deftypefun 94 @end deftypefun
88 95
89 @deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t no, mu_mailcap_entry_t*@var{entry}) 96 @deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t @var{no}, mu_mailcap_entry_t *@var{entry})
90 Returns in @var{entry} the mailcap entry of @var{no} 97 Returns in @var{entry} the mailcap entry of @var{no}.
91 @end deftypefun
92
93 @deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
94 @end deftypefun
95
96 @deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
97 @end deftypefun 98 @end deftypefun
98 99
99 @deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count}) 100 @deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count})
...@@ -102,9 +103,62 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -102,9 +103,62 @@ The return value is @code{0} on success and a code number on error conditions:
102 @table @code 103 @table @code
103 104
104 @item EINVAL 105 @item EINVAL
105 @var{entry} or @var{count} is null. 106 @var{entry} or @var{count} is @code{NULL}.
106 @end table 107 @end table
107 @end deftypefun 108 @end deftypefun
108 109
109 @deftypefun int mu_mailcap_entry_get_field (mu_mailcap_entry_t @var{entry}, size_t @var{no}, char * @var{buffer}, size_t @var{buflen}, size_t * @var{pn}) 110 @deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
111 @end deftypefun
112
113 @deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
114 @end deftypefun
115
116 @deftypefun int mu_mailcap_entry_get_field (mu_mailcap_entry_t @var{entry}, size_t @var{no}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
117 @end deftypefun
118
119 @deftypefun int mu_mailcap_entry_get_value (mu_mailcap_entry_t @var{entry}, const char *@var{key}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
120 @end deftypefun
121
122 @deftypefun int mu_mailcap_entry_get_compose (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
123 Helper function saving in buffer, the argument of "compose" field.
124 @end deftypefun
125
126 @deftypefun int mu_mailcap_entry_get_composetyped (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
127 Helper function saving in buffer, the argument of "composetyped" field.
128 @end deftypefun
129
130 @deftypefun int mu_mailcap_entry_get_edit (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
131 Helper function saving in buffer, the argument of "edit" field.
132 @end deftypefun
133
134 @deftypefun int mu_mailcap_entry_get_textualnewlines (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
135 Helper function saving in buffer, the argument of "textualnewlines" field.
136 @end deftypefun
137
138 @deftypefun int mu_mailcap_entry_get_test (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
139 Helper function saving in buffer, the argument of "test" field.
140 @end deftypefun
141
142 @deftypefun int mu_mailcap_entry_get_x11bitmap (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
143 Helper function saving in buffer, the argument of "x11-bitmap" field.
144 @end deftypefun
145
146 @deftypefun int mu_mailcap_entry_get_description (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
147 Helper function saving in buffer, the argument of "description" field.
148 @end deftypefun
149
150 @deftypefun int mu_mailcap_entry_get_nametemplate (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
151 Helper function saving in buffer, the argument of "nametemplate" field.
152 @end deftypefun
153
154 @deftypefun int mu_mailcap_entry_get_notes (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
155 Helper function saving in buffer, the argument of "notes" field.
156 @end deftypefun
157
158 @deftypefun int mu_mailcap_entry_needsterminal (mu_mailcap_entry_t @var{entry}, int *@var{on})
159 Helper function. Returns *@var{on} != 0 if the flag "needsterminal" is in the record.
160 @end deftypefun
161
162 @deftypefun int mu_mailcap_entry_copiousoutput (mu_mailcap_entry_t @var{entry}, int *@var{on})
163 Helper function. Returns *@var{on} != 0 if the flag "copiousoutput" is in the record.
110 @end deftypefun 164 @end deftypefun
......
...@@ -4,20 +4,22 @@ ...@@ -4,20 +4,22 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{mailer_} is reserved */} 7 @code{/* Prefix @emph{mailer_} is reserved. */}
8 @code{#include <mailutils/mailer.h>} 8 @code{#include <mailutils/mailer.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 The API is still changing. 12 @c
13 @c Constructor/Destructor.
14 @c
13 15
14 @deftypefun int mailer_create (mailer_t *, const char *) 16 @deftypefun int mailer_create (mailer_t *, const char *@var{url})
15 @end deftypefun 17 @end deftypefun
16 18
17 @deftypefun void mailer_destroy (mailer_t *) 19 @deftypefun void mailer_destroy (mailer_t *)
18 @end deftypefun 20 @end deftypefun
19 21
20 @deftypefun int mailer_open (mailer_t, int flags) 22 @deftypefun int mailer_open (mailer_t, int @var{flags})
21 @end deftypefun 23 @end deftypefun
22 24
23 @deftypefun int mailer_close (mailer_t) 25 @deftypefun int mailer_close (mailer_t)
...@@ -25,22 +27,19 @@ The API is still changing. ...@@ -25,22 +27,19 @@ The API is still changing.
25 27
26 @deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to}); 28 @deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to});
27 29
28 If from is not @var{NULL}, it must contain a single fully qualified 30 If @var{from} is not @code{NULL}, it must contain a single fully qualified
29 RFC2822 email address which will be used as the envelope from 31 RFC2822 email address which will be used as the envelope from
30 address. This is the address to which delivery status notifications 32 address. This is the address to which delivery status notifications
31 are sent, so it never matters what it is set to until it REALLY matters. 33 are sent, so it never matters what it is set to until it @strong{really}
32 This is equivalent to sendmail's @var{-f} flag. 34 matters. This is equivalent to Sendmail's @option{-f} flag.
33 35
34 The default for @var{from} is provided by the specific mailer. 36 The default for @var{from} is provided by the specific mailer.
35 37
36 If to is not @var{NULL}, then the message will be sent to the list of 38 If to is not @code{NULL}, then the message will be sent to the list of
37 addresses that it specifies. 39 addresses that it specifies.
38 40
39 The default for @var{to} is to use the contents of the standard "To:", "Cc:", 41 The default for @var{to} is to use the contents of the standard "To:", "Cc:",
40 and "Bcc:" fields, this is equivalent to sendmail's @var{-t} flag. 42 and "Bcc:" fields, this is equivalent to Sendmail's @option{-t} flag.
41
42 Note: the previous implementation of mailer_send_message() was equivalent
43 to having both @var{from} and @var{to} be @var{NULL}.
44 @end deftypefun 43 @end deftypefun
45 44
46 @deftypefun int mailer_get_property (mailer_t, property_t *) 45 @deftypefun int mailer_get_property (mailer_t, property_t *)
...@@ -52,10 +51,10 @@ to having both @var{from} and @var{to} be @var{NULL}. ...@@ -52,10 +51,10 @@ to having both @var{from} and @var{to} be @var{NULL}.
52 @deftypefun int mailer_set_stream (mailer_t, stream_t) 51 @deftypefun int mailer_set_stream (mailer_t, stream_t)
53 @end deftypefun 52 @end deftypefun
54 53
55 @deftypefun int mailer_get_debug (mailer_t, debug_t *) 54 @deftypefun int mailer_get_debug (mailer_t, mu_debug_t *)
56 @end deftypefun 55 @end deftypefun
57 56
58 @deftypefun int mailer_set_debug (mailer_t, debug_t) 57 @deftypefun int mailer_set_debug (mailer_t, mu_debug_t)
59 @end deftypefun 58 @end deftypefun
60 59
61 @deftypefun int mailer_get_observable (mailer_t, observable_t *) 60 @deftypefun int mailer_get_observable (mailer_t, observable_t *)
...@@ -64,6 +63,12 @@ to having both @var{from} and @var{to} be @var{NULL}. ...@@ -64,6 +63,12 @@ to having both @var{from} and @var{to} be @var{NULL}.
64 @deftypefun int mailer_get_url (mailer_t, url_t *) 63 @deftypefun int mailer_get_url (mailer_t, url_t *)
65 @end deftypefun 64 @end deftypefun
66 65
66 @deftypefun int mailer_check_from (address_t @var{from})
67 @end deftypefun
68
69 @deftypefun int mailer_check_to (address_t @var{to})
70 @end deftypefun
71
67 @sp 1 72 @sp 1
68 @subheading Some Usage Notes 73 @subheading Some Usage Notes
69 74
...@@ -73,71 +78,74 @@ Some possible use cases the API must support are: ...@@ -73,71 +78,74 @@ Some possible use cases the API must support are:
73 78
74 1 - fill in header addresses 79 1 - fill in header addresses
75 80
76 2 - mailer_send_message(mailer, msg, NULL, NULL); 81 2 - @code{mailer_send_message(mailer, msg, NULL, NULL)}
77 82
78 - from will be filled in if missing, 83 - from will be filled in if missing,
79 84
80 - bcc's will be deleted before delivery to a non-bcc address, 85 - Bcc's will be deleted before delivery to a non-bcc address,
81 86
82 - message-id and date will be added, if missing, 87 - message-id and date will be added, if missing,
83 88
84 - a to: or apparently-to: will be added if non is present (for RFC 89 - a To: or Apparently-To: will be added if non is present (for RFC
85 compliance) 90 compliance)
86 91
87 - MTA-style .forward ( and sieve-style redirect ) 92 - MTA-style @file{.forward} (and Sieve-style redirect)
88 93
89 1 - get the envelope from of the message to be forwarded 94 1 - get the envelope from of the message to be forwarded
90 95
91 2 - mailer_send_message(mailer, msg, from, to) 96 2 - @code{mailer_send_message(mailer, msg, from, to)}
92 97
93 - MUA-style bounce 98 - MUA-style bounce
94 99
95 1 - add Resent-[to,from,....] 100 1 - add Resent-[To,From,...]
96 101
97 2 - mailer_send_message(mailer, msg, NULL, to) 102 2 - @code{mailer_send_message(mailer, msg, NULL, to)}
98 103
99 - DSN "bounce" 104 - DSN "bounce"
100 105
101 1 - compose DSN 106 1 - compose DSN
102 107
103 2 - mailer_deliver(mailer, msg, address_t( "<>" ), to) 108 2 - @code{mailer_deliver(mailer, msg, address_t("<>"), to)}
104 109
105 Don't want mail loops, so the null but valid SMTP address of <> is 110 Don't want mail loops, so the null but valid SMTP address of @samp{<>}
106 the envelope from. 111 is the envelope From.
107 112
108 @subheading The Sendmail Mailer 113 @subheading The Sendmail Mailer
109 114
110 @file{/sbin/sendmail} isn't always sendmail... sometimes its a 115 @file{/sbin/sendmail} isn't always Sendmail... Sometimes it's a
111 sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands 116 Sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands
112 only a recipient list, @option{-f} and @option{-oi}, these seem 117 only a recipient list, @option{-f} and @option{-oi}, these seem
113 to be pretty basic. Cross fingers. 118 to be pretty basic. Cross fingers.
114 119
115 Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying @option{-f} 120 Pipe to "/sbin/sendmail -oi [-f @var{from}] [@var{to}...]", supplying
116 if there was a from, and supplying the recipient list from the to 121 @option{-f} if there was a from, and supplying the recipient list from
117 (if there is no recipient list, assume it will read the message 122 the to (if there is no recipient list, assume it will read the message
118 contents for the recipients). 123 contents for the recipients).
119 124
120 Note: since the stdout and stderr of sendmail is closed, we have no 125 @strong{Caution:} since the @code{stdout} and @code{stderr} of Sendmail
121 way of ever giving feedback on failure. Also, what should the return 126 is closed, we have no way of ever giving feedback on failure. Also, what
122 code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM, 127 should the return code be from @code{mailer_send_message()} when Sendmail
123 which is less than descriptive! 128 returns @samp{1}? @samp{1} maps to @code{EPERM}, which is less than
129 descriptive!
124 130
125 @subheading The SMTP Mailer 131 @subheading The SMTP Mailer
126 132
127 This mailer does NOT canonicalize the message. This must be done before 133 This mailer does @strong{not} canonicalize the message. This must be
128 sending the message, or it may be assumed that the MTA will do so. 134 done before sending the message, or it may be assumed that the MTA
135 will do so.
129 136
130 It does blind out the Bcc: header before sending, though. 137 It does blind out the Bcc: header before sending, though.
131 138
132 Note: mutt always puts the recipient addresses on the command line, even 139 @strong{Caution:} Mutt always puts the recipient addresses on the
133 bcc ones, do we strip the bcc before forwarding with SMTP? 140 command line, even Bcc: ones, do we strip the Bcc: before forwarding
141 with SMTP?
134 142
135 @subheading Non-RFC822 Addresses 143 @subheading Non-RFC822 Addresses
136 144
137 An address that has no domain is not and RFC822 email address. What 145 An address that has no domain is not and RFC822 email address. What
138 do I do with them? Should the user of the API be responsible for 146 do I do with them? Should the user of the API be responsible for
139 determining what is mean by email to "john" means? Or should the 147 determining what is mean by email to "John" means? Or should the
140 be able to configure sendmail to decide globally what this means. 148 be able to configure Sendmail to decide globally what this means.
141 If so, we can pass the address to sendmail, but we have to decide 149 If so, we can pass the address to Sendmail, but we have to decide
142 for SMTP! So, right now these addresses are rejected. 150 for SMTP! So, right now these addresses are rejected.
143 This could be changed. 151 This could be changed.
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{message_} is reserve */} 7 @code{/* Prefix @emph{message_} is reserved. */}
8 @code{#include <mailutils/message.h>} 8 @code{#include <mailutils/message.h>}
9 9
10 @end smallexample 10 @end smallexample
...@@ -15,21 +15,25 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}. ...@@ -15,21 +15,25 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
15 @smallexample 15 @smallexample
16 @group 16 @group
17 mailbox_t 17 mailbox_t
18 __________ message_t 18 ---------- message_t
19 (message[1]) +------>+-----------------------+ 19 (message[1]) +------>+--------------------+
20 ---------- | | envelope_t | 20 ---------- | | envelope_t |
21 (message[2]) | |-----------------------| 21 (message[2]) | |--------------------|
22 ---------- | | header_t | 22 ---------- | | header_t |
23 (message[3])--------+ |-----------------------| 23 (message[3])--------+ |--------------------|
24 ---------- | body_t | 24 ---------- | body_t |
25 (message[n]) |-----------------------| 25 (message[n]) |--------------------|
26 ---------- | attribute_t | 26 ---------- | attribute_t |
27 |-----------------------| 27 |--------------------|
28 | stream_t | 28 | stream_t |
29 +-----------------------+ 29 +--------------------+
30 @end group 30 @end group
31 @end smallexample 31 @end smallexample
32 32
33 @c
34 @c Basic.
35 @c
36
33 @deftypefun void message_create (message_t *@var{msg}, void *@var{owner}) 37 @deftypefun void message_create (message_t *@var{msg}, void *@var{owner})
34 @end deftypefun 38 @end deftypefun
35 39
...@@ -37,57 +41,110 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}. ...@@ -37,57 +41,110 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
37 The resources allocate for @var{msg} are freed. 41 The resources allocate for @var{msg} are freed.
38 @end deftypefun 42 @end deftypefun
39 43
40 @deftypefun int message_get_header (message_t @var{msg}, header_t *@var{pheader}) 44 @deftypefun int message_create_copy (message_t *@var{to}, message_t *@var{from})
45 @end deftypefun
46
47 @deftypefun void* message_get_owner (message_t @var{msg})
48 @end deftypefun
49
50 @deftypefun int message_is_modified (message_t @var{msg})
51 @end deftypefun
52
53 @deftypefun int message_clear_modified (message_t @var{msg})
54 @end deftypefun
55
56 @deftypefun int message_get_mailbox (message_t @var{msg}, mailbox_t *@var{mbox})
57 @end deftypefun
58
59 @deftypefun int message_set_mailbox (message_t @var{msg}, mailbox_t @var{mbox}, void *@var{owner})
60 @end deftypefun
61
62 @c
63 @c ------------
64 @c
65
66 @deftypefun int message_ref (message_t @var{msg})
67 @end deftypefun
68
69 @deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *@var{envelope})
70 @end deftypefun
71
72 @deftypefun int message_set_envelope (message_t @var{msg}, envelope_t @var{envelope}, void *@var{owner})
73 @end deftypefun
74
75 @deftypefun int message_get_header (message_t @var{msg}, header_t *@var{header})
41 Retrieve @var{msg} header. 76 Retrieve @var{msg} header.
42 @end deftypefun 77 @end deftypefun
43 78
44 @deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner}) 79 @deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner})
45 @end deftypefun 80 @end deftypefun
46 81
47 @deftypefun int message_get_body (message_t @var{msg}, body_t *@var{pbody}) 82 @deftypefun int message_get_body (message_t @var{msg}, body_t *@var{body})
48 @end deftypefun 83 @end deftypefun
49 84
50 @deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner}) 85 @deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner})
51 @end deftypefun 86 @end deftypefun
52 87
53 @deftypefun int message_is_multipart (message_t @var{msg}, int *@var{pmulti}) 88 @deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{stream})
54 Set *@var{pmulti} to non-zero value if @var{msg} is multi-part.
55 @end deftypefun 89 @end deftypefun
56 90
57 @deftypefun int message_get_num_parts (message_t @var{msg}, size_t *nparts) 91 @deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream}, void *@var{owner})
58 @end deftypefun 92 @end deftypefun
59 93
60 @deftypefun int message_get_part (message_t @var{msg}, size_t part, message_t *msg) 94 @deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{attribute})
61 @end deftypefun 95 @end deftypefun
62 96
63 @deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{pstream}) 97 @deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *@var{owner})
64 @end deftypefun 98 @end deftypefun
65 99
66 @deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream},void *@var{owner} ) 100 @deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable})
67 @end deftypefun 101 @end deftypefun
68 102
69 @deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{pattribute}) 103 @c
104 @c ------------
105 @c
106
107 @deftypefun int message_is_multipart (message_t @var{msg}, int *@var{multi})
108 Set *@var{multi} to non-zero value if @var{msg} is multi-part.
70 @end deftypefun 109 @end deftypefun
71 110
72 @deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *owner) 111 @deftypefun int message_set_is_multipart (message_t @var{msg}, int (*@var{_is_multipart}) (message_t, int *), void *);
73 @end deftypefun 112 @end deftypefun
74 113
75 @deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *penvelope) 114 @deftypefun int message_size (message_t @var{msg}, size_t *@var{size})
76 @end deftypefun 115 @end deftypefun
77 116
78 @deftypefun int message_set_envelope (message_t @var{msg}, envelope_t envelope, void *@var{owner}) 117 @deftypefun int message_set_size (message_t @var{msg}, int (*@var{_size}) (message_t, size_t *), void *@var{owner})
79 @end deftypefun 118 @end deftypefun
80 119
81 @deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid}) 120 @deftypefun int message_lines (message_t @var{msg}, size_t *@var{size})
82 @end deftypefun 121 @end deftypefun
83 122
84 @deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten}) 123 @deftypefun int message_set_lines (message_t @var{msg}, int (*@var{_lines}) (message_t, size_t *), void *@var{owner})
85 @end deftypefun 124 @end deftypefun
86 125
87 @deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl})(message_t, char *, size_t, size_t *), void *@var{owner}) 126 @deftypefun int message_get_num_parts (message_t @var{msg}, size_t *@var{nparts})
88 @end deftypefun 127 @end deftypefun
89 128
90 @deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable}) 129 @deftypefun int message_set_get_num_parts (message_t @var{msg}, int (*@var{_get_num_parts}) (message_t, size_t *), void *@var{owner})
130 @end deftypefun
131
132 @deftypefun int message_get_part (message_t @var{msg}, size_t @var{part}, message_t *@var{msg})
133 @end deftypefun
134
135 @deftypefun int message_set_get_part (message_t @var{msg}, int (*@var{_get_part}) (message_t, size_t, message_t *), void *@var{owner})
136 @end deftypefun
137
138 @deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
139 @end deftypefun
140
141 @deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl}) (message_t, char *, size_t, size_t *), void *@var{owner})
142 @end deftypefun
143
144 @deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid})
145 @end deftypefun
146
147 @deftypefun int message_set_uid (message_t @var{msg}, int (*@var{_get_uid}) (message_t, size_t *), void *@var{owner})
91 @end deftypefun 148 @end deftypefun
92 149
93 @deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg}) 150 @deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg})
...@@ -101,3 +158,12 @@ Set *@var{pmulti} to non-zero value if @var{msg} is multi-part. ...@@ -101,3 +158,12 @@ Set *@var{pmulti} to non-zero value if @var{msg} is multi-part.
101 158
102 @deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}); 159 @deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data});
103 @end deftypefun 160 @end deftypefun
161
162 @deftypefun int message_get_attachment_name (message_t @var{msg}, char *@var{name}, size_t @var{bufsize}, size_t *@var{size});
163 @end deftypefun
164
165 @deftypefun int message_aget_attachment_name (message_t @var{msg}, char **@var{name});
166 @end deftypefun
167
168 @deftypefun int message_save_to_mailbox (message_t @var{msg}, ticket_t @var{ticket}, mu_debug_t @var{debug}, const char *@var{toname});
169 @end deftypefun
......
...@@ -4,60 +4,157 @@ ...@@ -4,60 +4,157 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{parse822_} is reserved */} 7 @code{/* Prefix @emph{parse822_} is reserved. */}
8 @code{#include <mailutils/parse822.h>} 8 @code{#include <mailutils/parse822.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 Internet Message Format, see Address node for the discussion. 12 @deftypefun int parse822_is_char (char @var{c})
13 @end deftypefun
14
15 @deftypefun int parse822_is_digit (char @var{c})
16 @end deftypefun
17
18 @deftypefun int parse822_is_ctl (char @var{c})
19 @end deftypefun
20
21 @deftypefun int parse822_is_space (char @var{c})
22 @end deftypefun
23
24 @deftypefun int parse822_is_htab (char @var{c})
25 @end deftypefun
26
27 @deftypefun int parse822_is_lwsp_char (char @var{c})
28 @end deftypefun
29
30 @deftypefun int parse822_is_special (char @var{c})
31 @end deftypefun
32
33 @deftypefun int parse822_is_atom_char (char @var{c})
34 @end deftypefun
35
36 @deftypefun int parse822_is_q_text (char @var{c})
37 @end deftypefun
38
39 @deftypefun int parse822_is_d_text (char @var{c})
40 @end deftypefun
41
42 @deftypefun int parse822_is_smtp_q (char @var{c})
43 @end deftypefun
44
45 @deftypefun int parse822_skip_crlf (const char **@var{p}, const char *@var{e})
46 @end deftypefun
47
48 @deftypefun int parse822_skip_lwsp_char (const char **@var{p}, const char *@var{e})
49 @end deftypefun
50
51 @deftypefun int parse822_skip_lwsp (const char **@var{p}, const char *@var{e})
52 @end deftypefun
53
54 @deftypefun int parse822_skip_comments (const char **@var{p}, const char *@var{e})
55 @end deftypefun
56
57 @deftypefun int parse822_skip_nl (const char **@var{p}, const char *@var{e})
58 @end deftypefun
59
60 @deftypefun int parse822_digits (const char **@var{p}, const char *@var{e}, int @var{min}, int @var{max}, int *@var{digits})
61 @end deftypefun
62
63 @deftypefun int parse822_special (const char **@var{p}, const char *@var{e}, char @var{c})
64 @end deftypefun
65
66 @deftypefun int parse822_comment (const char **@var{p}, const char *@var{e}, char **@var{comment})
67 @end deftypefun
68
69 @deftypefun int parse822_atom (const char **@var{p}, const char *@var{e}, char **@var{atom})
70 @end deftypefun
71
72 @deftypefun int parse822_quoted_pair (const char **@var{p}, const char *@var{e}, char **@var{qpair})
73 @end deftypefun
74
75 @deftypefun int parse822_quoted_string (const char **@var{p}, const char *@var{e}, char **@var{qstr})
76 @end deftypefun
77
78 @deftypefun int parse822_word (const char **@var{p}, const char *@var{e}, char **@var{word})
79 @end deftypefun
13 80
14 @deftypefun int parse822_address_list (address_t* a, const char* s) 81 @deftypefun int parse822_phrase (const char **@var{p}, const char *@var{e}, char **@var{phrase})
15 @end deftypefun 82 @end deftypefun
16 83
17 @deftypefun int parse822_mail_box (const char** p, const char* e, address_t* a) 84 @deftypefun int parse822_d_text (const char **@var{p}, const char *@var{e}, char **@var{dtext})
18 @end deftypefun 85 @end deftypefun
19 86
20 @deftypefun int parse822_group (const char** p, const char* e, address_t* a) 87 @c
88 @c From RFC 822, 6.1 Address Specification Syntax
89 @c
90
91 @deftypefun int parse822_address_list (address_t *@var{a}, const char *@var{s})
92 @end deftypefun
93
94 @deftypefun int parse822_mail_box (const char **@var{p}, const char *@var{e}, address_t *@var{a})
95 @end deftypefun
96
97 @deftypefun int parse822_group (const char **@var{p}, const char *@var{e}, address_t *@var{a})
98 @end deftypefun
99
100 @deftypefun int parse822_address (const char **@var{p}, const char *@var{e}, address_t *@var{a})
21 @end deftypefun 101 @end deftypefun
22 102
23 @deftypefun int parse822_address (const char** p, const char* e, address_t* a) 103 @deftypefun int parse822_route_addr (const char **@var{p}, const char *@var{e}, address_t *@var{a})
24 @end deftypefun 104 @end deftypefun
25 105
26 @deftypefun int parse822_route_addr (const char** p, const char* e, address_t* a) 106 @deftypefun int parse822_route (const char **@var{p}, const char *@var{e}, char **@var{route})
27 @end deftypefun 107 @end deftypefun
28 108
29 @deftypefun int parse822_route (const char** p, const char* e, char** route) 109 @deftypefun int parse822_addr_spec (const char **@var{p}, const char *@var{e}, address_t *@var{a})
30 @end deftypefun 110 @end deftypefun
31 111
32 @deftypefun int parse822_addr_spec (const char** p, const char* e, address_t* a) 112 @deftypefun int parse822_unix_mbox (const char **@var{p}, const char *@var{e}, address_t *@var{a})
33 @end deftypefun 113 @end deftypefun
34 114
35 @deftypefun int parse822_unix_mbox (const char** p, const char* e, address_t* a) 115 @deftypefun int parse822_local_part (const char **@var{p}, const char *@var{e}, char **@var{local_part})
36 @end deftypefun 116 @end deftypefun
37 117
38 @deftypefun int parse822_local_part (const char** p, const char* e, char** local_part) 118 @deftypefun int parse822_domain (const char **@var{p}, const char *@var{e}, char **@var{domain})
39 @end deftypefun 119 @end deftypefun
40 120
41 @deftypefun int parse822_domain (const char** p, const char* e, char** domain) 121 @deftypefun int parse822_sub_domain (const char **@var{p}, const char *@var{e}, char **@var{sub_domain})
42 @end deftypefun 122 @end deftypefun
43 123
44 @deftypefun int parse822_sub_domain (const char** p, const char* e, char** sub_domain) 124 @deftypefun int parse822_domain_ref (const char **@var{p}, const char *@var{e}, char **@var{domain_ref})
45 @end deftypefun 125 @end deftypefun
46 126
47 @deftypefun int parse822_domain_ref (const char** p, const char* e, char** domain_ref) 127 @deftypefun int parse822_domain_literal (const char **@var{p}, const char *@var{e}, char **@var{domain_literal})
48 @end deftypefun 128 @end deftypefun
49 129
50 @deftypefun int parse822_domain_literal (const char** p, const char* e, char** domain_literal) 130 @c
131 @c RFC 822 Quoting Functions
132 @c
133
134 @deftypefun int parse822_quote_string (char **@var{quoted}, const char *@var{raw})
51 @end deftypefun 135 @end deftypefun
52 136
53 @deftypefun int parse822_quote_string (char** quoted, const char* raw) 137 @deftypefun int parse822_quote_local_part (char **@var{quoted}, const char *@var{raw})
138 @end deftypefun
139
140 @deftypefun int parse822_field_body (const char **@var{p}, const char *@var{e}, char **@var{fieldbody})
141 @end deftypefun
142
143 @deftypefun int parse822_field_name (const char **@var{p}, const char *@var{e}, char **@var{fieldname})
144 @end deftypefun
145
146 @c
147 @c From RFC 822, 5.1 Date and Time Specification Syntax
148 @c
149
150 @deftypefun int parse822_day (const char **@var{p}, const char *@var{e}, int *@var{day})
54 @end deftypefun 151 @end deftypefun
55 152
56 @deftypefun int parse822_quote_local_part (char** quoted, const char* raw) 153 @deftypefun int parse822_date (const char **@var{p}, const char *@var{e}, int *@var{day}, int *@var{mon}, int *@var{year})
57 @end deftypefun 154 @end deftypefun
58 155
59 @deftypefun int parse822_field_body (const char** p, const char *e, char** fieldbody) 156 @deftypefun int parse822_time (const char **@var{p}, const char *@var{e}, int *@var{h}, int *@var{m}, int *@var{s}, int *@var{tz}, const char **@var{tz_name})
60 @end deftypefun 157 @end deftypefun
61 158
62 @deftypefun int parse822_field_name (const char** p, const char *e, char** fieldname) 159 @deftypefun int parse822_date_time (const char **@var{p}, const char *@var{e}, struct tm *@var{tm}, mu_timezone *@var{tz})
63 @end deftypefun 160 @end deftypefun
......
...@@ -33,37 +33,53 @@ The stream is set non blocking. ...@@ -33,37 +33,53 @@ The stream is set non blocking.
33 @item MU_STREAM_NO_CHECK 33 @item MU_STREAM_NO_CHECK
34 @findex MU_STREAM_NO_CHECK 34 @findex MU_STREAM_NO_CHECK
35 Stream is destroyed without checking for the owner. 35 Stream is destroyed without checking for the owner.
36 @item MU_STREAM_SEEKABLE
37 @findex MU_STREAM_SEEKABLE
38
36 @item MU_STREAM_NO_CLOSE 39 @item MU_STREAM_NO_CLOSE
37 @findex MU_STREAM_NO_CLOSE 40 @findex MU_STREAM_NO_CLOSE
38 Stream doesn't close it's underlying resource when it is closed or destroyed. 41 Stream doesn't close it's underlying resource when it is closed or destroyed.
42 @item MU_STREAM_ALLOW_LINKS
43 @findex MU_STREAM_ALLOW_LINKS
44
39 @end table 45 @end table
40 46
41 @deftypefun int file_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 47 @deftypefun int file_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
42 @end deftypefun 48 @end deftypefun
43 49
44 @deftypefun int tcp_stream_create (stream_t *@var{pstream}, const char *@var{host}, int @var{port}, int @var{flags}) 50 @deftypefun int tcp_stream_create (stream_t *@var{stream}, const char *@var{host}, int @var{port}, int @var{flags})
45 @end deftypefun 51 @end deftypefun
46 52
47 @deftypefun int mapfile_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 53 @deftypefun int mapfile_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
48 @end deftypefun 54 @end deftypefun
49 55
50 @deftypefun int memory_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 56 @deftypefun int memory_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
51 @end deftypefun 57 @end deftypefun
52 58
53 @deftypefun int encoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding}) 59 @deftypefun int encoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
54 @end deftypefun 60 @end deftypefun
55 61
56 @deftypefun int decoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding}) 62 @deftypefun int decoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
57 @end deftypefun 63 @end deftypefun
58 64
59 @deftypefun int stdio_stream_create (stream_t *@var{pstream}, FILE* @var{stdio}, int @var{flags}) 65 @deftypefun int stdio_stream_create (stream_t *@var{stream}, FILE *@var{stdio}, int @var{flags})
60 If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on 66 If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
61 @var{stdio} when the stream is closed. 67 @var{stdio} when the stream is closed.
62 @end deftypefun 68 @end deftypefun
63 69
64 @deftypefun void stream_destroy (stream_t *@var{pstream}, void *@var{owner}) 70 @deftypefun int prog_stream_create (stream_t *@var{stream}, char *@var{progname}, int @var{flags})
71 @end deftypefun
72
73 @deftypefun int filter_prog_stream_create (stream_t *@var{stream}, char *@var{progname}, stream_t @var{input})
65 @end deftypefun 74 @end deftypefun
66 75
76 @deftypefun void stream_destroy (stream_t *@var{stream}, void *@var{owner})
77 @end deftypefun
78
79 @c
80 @c ---------
81 @c
82
67 @deftypefun int stream_open (stream_t @var{stream}) 83 @deftypefun int stream_open (stream_t @var{stream})
68 @end deftypefun 84 @end deftypefun
69 85
...@@ -73,22 +89,25 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on ...@@ -73,22 +89,25 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
73 @deftypefun int stream_is_seekable (stream_t @var{stream}) 89 @deftypefun int stream_is_seekable (stream_t @var{stream})
74 @end deftypefun 90 @end deftypefun
75 91
76 @deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd}) 92 @deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{fd})
77 @end deftypefun 93 @end deftypefun
78 94
79 @deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 95 @deftypefun int stream_get_fd2 (stream_t @var{stream}, int *@var{fd1}, int *@var{fd2})
80 @end deftypefun 96 @end deftypefun
81 97
82 @deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 98 @deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
83 @end deftypefun 99 @end deftypefun
84 100
85 @deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize}) 101 @deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
86 @end deftypefun 102 @end deftypefun
87 103
88 @deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size}) 104 @deftypefun int stream_size (stream_t @var{stream}, off_t *@var{size})
89 @end deftypefun 105 @end deftypefun
90 106
91 @deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 107 @deftypefun n int stream_truncate (stream_t @var{stream}, off_t @var{size})
108 @end deftypefun
109
110 @deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
92 @end deftypefun 111 @end deftypefun
93 112
94 @deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size}) 113 @deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size})
...@@ -97,16 +116,33 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on ...@@ -97,16 +116,33 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
97 @deftypefun int stream_flush (stream_t @var{stream}) 116 @deftypefun int stream_flush (stream_t @var{stream})
98 @end deftypefun 117 @end deftypefun
99 118
100 These functions will typically only be useful to implementors of streams. 119 @c
120 @c These functions will typically only be useful to implementors of streams.
121 @c
101 122
102 @deftypefun int stream_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner}) 123 @deftypefun int stream_create (stream_t *@var{stream}, int @var{flags}, void *@var{owner})
103 Used to implement a new kind of stream. 124 Used to implement a new kind of stream.
104 @end deftypefun 125 @end deftypefun
105 126
106 @deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{pflags}) 127 @deftypefun void* stream_get_owner (stream_t @var{stream})
128 @end deftypefun
129
130 @deftypefun void stream_set_owner (stream_t @var{stream}, void *@var{owner})
131 @end deftypefun
132
133 @deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{flags})
107 @end deftypefun 134 @end deftypefun
108 135
109 @deftypefun int stream_get_state (stream_t @var{stream}, int *@var{pstate}) 136 @deftypefun int stream_set_flags (stream_t @var{stream}, int @var{flags})
137 @end deftypefun
138
139 @deftypefun int stream_get_property (stream_t @var{stream}, property_t *)
140 @end deftypefun
141
142 @deftypefun int stream_set_property (stream_t @var{stream}, property_t, void *)
143 @end deftypefun
144
145 @deftypefun int stream_get_state (stream_t @var{stream}, int *@var{state})
110 @table @code 146 @table @code
111 @item MU_STREAM_STATE_OPEN 147 @item MU_STREAM_STATE_OPEN
112 Last action was @code{stream_open}. 148 Last action was @code{stream_open}.
...@@ -119,7 +155,52 @@ Last action was @code{stream_close}. ...@@ -119,7 +155,52 @@ Last action was @code{stream_close}.
119 @end table 155 @end table
120 @end deftypefun 156 @end deftypefun
121 157
122 An example using @code{tcp_stream_create} to make a simple web client: 158 @deftypefun int stream_set_destroy (stream_t @var{stream}, void (*@var{_destroy}) (stream_t), void *@var{owner})
159 @end deftypefun
160
161 @deftypefun int stream_set_open (stream_t @var{stream}, int (*@var{_open}) (stream_t), void *@var{owner})
162 @end deftypefun
163
164 @deftypefun int stream_set_close (stream_t @var{stream}, int (*@var{_close}) (stream_t), void *@var{owner})
165 @end deftypefun
166
167 @deftypefun int stream_set_fd (stream_t @var{stream}, int (*@var{_get_fd}) (stream_t, int *, int *), void *@var{owner})
168 @end deftypefun
169
170 @deftypefun int stream_set_read (stream_t @var{stream}, int (*@var{_read}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
171 @end deftypefun
172
173 @deftypefun int stream_set_readline (stream_t @var{stream}, int (*@var{_readline}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
174 @end deftypefun
175
176 @deftypefun int stream_set_size (stream_t @var{stream}, int (*@var{_size}) (stream_t, off_t *), void *@var{owner})
177 @end deftypefun
178
179 @deftypefun int stream_set_truncate (stream_t @var{stream}, int (*@var{_truncate}) (stream_t, off_t), void *@var{owner})
180 @end deftypefun
181
182 @deftypefun int stream_set_write (stream_t @var{stream}, int (*@var{_write}) (stream_t, const char *, size_t, off_t, size_t *), void *@var{owner})
183 @end deftypefun
184
185 @deftypefun int stream_set_flush (stream_t @var{stream}, int (*@var{_flush}) (stream_t), void *@var{owner})
186 @end deftypefun
187
188 @deftypefun int stream_set_strerror (stream_t @var{stream}, int (*@var{_fp}) (stream_t, char **), void *@var{owner})
189 @end deftypefun
190
191 @deftypefun int stream_sequential_readline (stream_ts @var{stream}, char *@var{buf}, size_t @var{size}, size_t *@var{nbytes})
192 @end deftypefun
193
194 @deftypefun int stream_sequential_write (stream_t @var{stream}, char *@var{buf}, size_t @var{size})
195 @end deftypefun
196
197 @deftypefun int stream_seek (stream_t @var{stream}, off_t @var{off}, int @var{whence})
198 @end deftypefun
199
200 @deftypefun int stream_strerror (stream_t @var{stream}, char **@var{p})
201 @end deftypefun
202
203 An example using @code{tcp_stream_create()} to make a simple web client:
123 204
124 @smallexample 205 @smallexample
125 @include http.inc 206 @include http.inc
......
...@@ -13,13 +13,15 @@ The POP URL scheme contains a POP server, optional port number ...@@ -13,13 +13,15 @@ The POP URL scheme contains a POP server, optional port number
13 and the authentication mechanism. The general form is 13 and the authentication mechanism. The general form is
14 14
15 @smallexample 15 @smallexample
16 @url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]} 16 @group
17 @url{pop://[<@var{user}>[;AUTH=<@var{auth}>]@@]<@var{host}>[:<@var{port}>]}
17 or 18 or
18 @url{pop://[<user>[:<passwd>]@@]<host>[:<port>]} 19 @url{pop://[<@var{user}>[:<@var{passwd}>]@@]<@var{host}>[:<@var{port}>]}
20 @end group
19 @end smallexample 21 @end smallexample
20 22
21 If @emph{:port} is omitted the default value is 110. Different forms of 23 If @emph{:port} is omitted the default value is 110. Different forms of
22 authentication can be specified with @emph{;AUTH=type}. 24 authentication can be specified with @emph{;AUTH=@var{type}}.
23 The special string @emph{;AUTH=*} indicates that the client will use 25 The special string @emph{;AUTH=*} indicates that the client will use
24 a default scheme base on the capability of the server. 26 a default scheme base on the capability of the server.
25 27
...@@ -38,13 +40,15 @@ The IMAP URL scheme contains an IMAP server, optional port number ...@@ -38,13 +40,15 @@ The IMAP URL scheme contains an IMAP server, optional port number
38 and the authentication mechanism. The general form is 40 and the authentication mechanism. The general form is
39 41
40 @smallexample 42 @smallexample
41 @url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]} 43 @group
44 @url{imap://[<@var{user}>[;AUTH=<@var{type}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
42 or 45 or
43 @url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]} 46 @url{imap://[<@var{user}>[:<@var{passwd}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
47 @end group
44 @end smallexample 48 @end smallexample
45 49
46 If @emph{:port} is omitted the default value is 220. Different forms of 50 If @emph{:port} is omitted the default value is 143. Different forms of
47 authentication can be specified with @emph{;AUTH=type}. 51 authentication can be specified with @emph{;AUTH=@var{type}}.
48 The special string @emph{;AUTH=*} indicates that the client will use 52 The special string @emph{;AUTH=*} indicates that the client will use
49 a default scheme base on the capability of the server. 53 a default scheme base on the capability of the server.
50 54
...@@ -63,17 +67,21 @@ the mailbox recognize the type of mailbox and take the appropriate ...@@ -63,17 +67,21 @@ the mailbox recognize the type of mailbox and take the appropriate
63 action. 67 action.
64 68
65 @smallexample 69 @smallexample
66 @url{file://path} 70 @group
71 @url{file://@var{path}}
67 @url{file://var/mail/user} 72 @url{file://var/mail/user}
68 @url{file://home/obelix/Mail} 73 @url{file://home/obelix/Mail}
74 @end group
69 @end smallexample 75 @end smallexample
70 76
71 For MMDF, MH local mailboxes URLs are provided, but it is preferable to 77 For MMDF, MH local mailboxes URLs are provided, but it is preferable to
72 use @url{file://path} and let the library figure out which one. 78 use @url{file://@var{path}} and let the library figure out which one.
73 79
74 @smallexample 80 @smallexample
75 @url{mmdf://path} 81 @group
76 @url{mh://path} 82 @url{mmdf://@var{path}}
83 @url{mh://@var{path}}
84 @end group
77 @end smallexample 85 @end smallexample
78 86
79 @subheading Mailto 87 @subheading Mailto
...@@ -82,7 +90,7 @@ After setting a mailer, @url{mailto:} is used to tell the mailer where ...@@ -82,7 +90,7 @@ After setting a mailer, @url{mailto:} is used to tell the mailer where
82 and to whom the message is for. 90 and to whom the message is for.
83 91
84 @smallexample 92 @smallexample
85 @url{mailto://hostname} 93 @url{mailto://@var{hostname}}
86 @end smallexample 94 @end smallexample
87 95
88 Mailto can be used to generate short messages, for example to subscribe 96 Mailto can be used to generate short messages, for example to subscribe
...@@ -95,70 +103,99 @@ to mailing lists. ...@@ -95,70 +103,99 @@ to mailing lists.
95 103
96 For more complete information see @cite{RFC 2368}. 104 For more complete information see @cite{RFC 2368}.
97 105
98 @subheading URL functions 106 @c
107 @c URL Functions
108 @c
109
110 @subheading URL Functions
99 111
100 Helper functions are provided to retrieve and set the @emph{URL} fields. 112 Helper functions are provided to retrieve and set the @emph{URL} fields.
101 113
102 @deftypefun int url_create (url_t *@var{url}, const char *@var{name}) 114 @deftypefun int url_create (url_t *@var{url}, const char *@var{name})
103 Create and the @var{url} data structure, but do not parse it. 115 Create the url data structure, but do not parse it.
104 @end deftypefun 116 @end deftypefun
105 117
106 @deftypefun void url_destroy (url_t *) 118 @deftypefun void url_destroy (url_t *@var{url})
107 Destroy the url and free it's resources. 119 Destroy the url and free its resources.
108 @end deftypefun 120 @end deftypefun
109 121
110 @deftypefun int url_parse (url_t @var{url}) 122 @deftypefun int url_parse (url_t)
111 Parses the url, after calling this the get functions can be called. 123 Parses the url, after calling this the get functions can be called.
112 124
113 The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth= 125 The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth=
114 of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is: 126 of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is:
115 127
116 @smallexample 128 @smallexample
129 @group
117 url = 130 url =
118 scheme ":" [ "//" 131 scheme ":" [ "//"
119 132
120 [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ] 133 [ @var{user} [ ( ":" @var{password} ) | ( ";auth=" @var{auth} ) ] "@@" ]
121 134
122 host [ ":" port ] 135 @var{host} [ ":" @var{port} ]
123 136
124 [ ( "/" urlpath ) | ( "?" query ) ] ] 137 [ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
138 @end group
125 @end smallexample 139 @end smallexample
126 140
127 This is a generalized URL syntax, and may not be exactly appropriate 141 This is a generalized URL syntax, and may not be exactly appropriate
128 for any particular scheme. 142 for any particular scheme.
143 @end deftypefun
144
145 @deftypefun int url_get_scheme (const url_t, char *, size_t, size_t *)
146 @end deftypefun
147
148 @deftypefun int url_get_user (const url_t, char *, size_t, size_t *)
149 @end deftypefun
150
151 @deftypefun int url_get_passwd (const url_t, char *, size_t, size_t *)
152 @end deftypefun
129 153
154 @deftypefun int url_get_auth (const url_t, char *, size_t, size_t *)
130 @end deftypefun 155 @end deftypefun
131 156
132 @deftypefun const char* url_to_string (const url_t @var{url}) 157 @deftypefun int url_get_host (const url_t, char *, size_t, size_t *)
133 @end deftypefun 158 @end deftypefun
134 159
135 @deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n}) 160 @deftypefun int url_get_port (const url_t, long *)
136 @end deftypefun 161 @end deftypefun
137 162
138 @deftypefun int url_get_user (const url_t @var{url}, char *@var{usr}, size_t @var{len}, size_t *@var{n}) 163 @deftypefun int url_get_path (const url_t, char *, size_t, size_t *)
139 @end deftypefun 164 @end deftypefun
140 165
141 @deftypefun int url_get_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, size_t *@var{n}) 166 @deftypefun int url_get_query (const url_t, char *, size_t, size_t *)
142 @end deftypefun 167 @end deftypefun
143 168
144 @deftypefun int url_get_host (const url_t @var{url}, char *@var{host}, size_t @var{len}, size_t *@var{n}) 169 @deftypefun {const char*} url_to_string (const url_t)
145 @end deftypefun 170 @end deftypefun
146 171
147 @deftypefun int url_get_port (const url_t @var{url}, long *@var{port}) 172 @deftypefun int url_is_scheme (url_t, const char *@var{scheme})
148 @end deftypefun 173 @end deftypefun
149 174
150 @deftypefun int url_get_path (const url_t @var{url}, char *@var{path}, size_t @var{len}, size_t *@var{n}) 175 @deftypefun int url_is_same_scheme (url_t, url_t)
151 @end deftypefun 176 @end deftypefun
152 177
153 @deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n}) 178 @deftypefun int url_is_same_user (url_t, url_t)
154 @end deftypefun 179 @end deftypefun
155 180
156 @deftypefun char* url_decode (const char* @var{string}) 181 @deftypefun int url_is_same_path (url_t, url_t)
157 Decodes an @cite{RFC 1738} % encoded string, returning the decoded string 182 @end deftypefun
183
184 @deftypefun int url_is_same_host (url_t, url_t)
185 @end deftypefun
186
187 @deftypefun int url_is_same_port (url_t, url_t)
188 @end deftypefun
189
190 @deftypefun char* url_decode (const char *@var{string})
191 Decodes an @cite{RFC 1738} encoded string, returning the decoded string
158 in allocated memory. If the string is not encoded, this degenerates to 192 in allocated memory. If the string is not encoded, this degenerates to
159 a @code{strdup()}. 193 a @code{strdup()}.
160 @end deftypefun 194 @end deftypefun
161 195
196 @deftypefun int url_is_ticket (url_t @var{ticket}, url_t @var{url})
197 @end deftypefun
198
162 @subheading Example 199 @subheading Example
163 @smallexample 200 @smallexample
164 @include url-parse.inc 201 @include url-parse.inc
......