Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit f0dd0645 f0dd0645ce9001c93eea31e0e736c5dabe9de669 by Alain Magloire
Options

First draft documenting the API of the lower POP3 implementation rewrite.

1 parent 33f79834
Inline Side-by-side
Showing 1 changed file with 379 additions and 367 deletions
1 @c This is part of the GNU Mailutils manual. 1 @c This is part of the GNU Mailutils manual.
2 @c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc. 2 @c Copyright (C) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
3 @c See file mailutils.texi for copying conditions. 3 @c See file mailutils.texi for copying conditions.
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 @example 5 @example
6 @code{/* Prefix @emph{pop3_} is reserved */} 6 @code{/* Prefix @emph{ pop3_ } is reserved */}
7 @code{#include <mailutils/pop3.h>} 7 @code{#include <mailutils/pop3.h>}
8 8
9 @end example 9 @end example
10 10
11 The purpose of the Post Office Protocol Version 3 (POP3) is to permit a 11 The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client to download a maildrop from a remote server. It does
12 client to download a maildrop from a remote server. It does not provide 12 not provide complex or extensive operation on the maildrop. When the client successfully authenticates, the server acquires an
13 complex or extensive operation on the maildrop. When the client successfully 13 exclusive access lock on the mailbox and holds it the entire duration of the session. After the authentication, the session enters
14 authenticates, the server acquires an exclusive access lock on the mailbox and 14 transaction state and the client may issues commands to access messages in the mailbox.
15 holds it the entire duration of the session. After the authentication, the
16 session enters transaction state and the client may issues commands to access
17 messages in the mailbox.
18 @itemize @bullet 15 @itemize @bullet
19 @item 16 @item
20 Authorization state 17 Authorization state
21 @itemize @bullet 18 @itemize @bullet
22 @item 19 @item
23 User 20 USER
24 @item 21 @item
25 Pass 22 PASS
26 @item 23 @item
27 Quit 24 QUIT
28 @item 25 @item
29 Capa (extension) 26 CAPA (extension)
30 @item 27 @item
31 Auth (extension) 28 AUTH (extension)
32 @end itemize 29 @end itemize
33 @item 30 @item
34 Transaction state 31 Transaction state
35 @itemize @bullet 32 @itemize @bullet
36 @item 33 @item
37 Stat 34 STAT
38 @item 35 @item
39 List 36 LIST
40 @item 37 @item
41 Retr 38 RETR
42 @item 39 @item
43 Dele 40 DELE
44 @item 41 @item
45 Noop 42 NOOP
46 @item 43 @item
47 Rset 44 RSET
48 @item 45 @item
49 Top 46 TOP
50 @item 47 @item
51 Uidl (extension) 48 UIDL (extension)
52 @item 49 @item
53 Quit 50 QUIT
54 @item 51 @item
55 Capa (extension) 52 CAPA (extension)
56 @end itemize 53 @end itemize
57 @end itemize 54 @end itemize
58 55
59 When the command Quit is issue the session enters the update state. 56 When the command QUIT is issue the session enters the update state.
60 The servers removes all messages marked deleted, releases the exclusive lock 57 The servers removes all messages marked deleted, releases the exclusive lock
61 and closes the TCP connection. 58 and closes the TCP connection.
62 59
63 @subsection Commands 60 @subsection Commands
64 @cindex pop3_t 61 @cindex pop3_t
65 62
66 An opaque structure @var{pop3_t} is use as a handle for the session, it is 63 An opaque structure @var{pop3_t} is use as a handle for the session, it is allocated and initialized by calling @code{pop3_create ()}.
67 allocated and initialized by calling @code{pop3_create ()}. All Functions will 64 All Functions will wait for a reply from the POP3 server before returning. The duration of the wait can be set by calling
68 wait for a reply from the POP3 server before returning. The duration of 65 @code{pop3_set_timeout ()}, the default is 2 minutes. On the server side, there is also an idle timeout of 10 minutes
69 the wait can be set by calling @code{pop3_set_timeout ()}, the default 66 before the POP3 server closes the connection. Although the @cite{RFC 1939} specifies that the minimum default timeout to be ten
70 is 10 minutes@footnote{@strong{Caution:} Although the @cite{RFC 1939} 67 minutes many servers has shorter idle period, care should be taken to at least send a @code{pop3_noop ()} between lengthy period
71 specifies that the minimum default timeout is ten minutes many servers has 68 of idle time. Once a successful connection is established with @code{pop3_connect ()}, two built-ins authentications are
72 shorter idle period, care should be taken to at least send a 69 provided @code{pop3_apop ()} or @code{pop3_user ()}/@code{pop3_pass ()}. The @code{pop3_stat ()} and @code{pop3_list ()} functions
73 @code{pop3_noop ()} between lengthy period of times.}. Once a successful 70 can be use to get the number and size of messages. The functions @code{pop3_list_all ()}, @code{pop3_uidl_all ()} and
74 connection is established with @code{pop3_connect ()}, two builtins 71 @code{pop3_capa ()} provide the information by going throught there iterators; @code{pop3_list_iterate ()}, @code{pop3_uidl_iterate ()}
75 authentications are provided @code{pop3_apop ()} or 72 and @code{pop3_capa_iterate ()}. Downloading of messages is done via a two methods @code{pop3_retr ()} or @code{pop3_top ()}
76 @code{pop3_user ()}/@code{pop3_pass ()}. The @code{pop3_stat ()} and 73 @footnote{@strong{Caution:} Some Internet Service Providers do not permit to leave mail on
77 @code{pop3_list ()} functions can be use to get the number and size of 74 server and the message will be deleted once downloaded.}. The functions @code{pop3_retr ()} or @code{pop3_top ()} initiates the
78 messages. Downloading of messages is done via a stream provided by 75 dowloading of the message, the content is retrive with @code{pop_retr_read ()} or @code{pop3_top_read ()}.
79 @code{pop3_retr ()} or @code{pop3_top ()}@footnote{@strong{Caution:} Some 76 POP3 provides only a single channel for operation, it means only one operation can be done at a time, all the functions
80 Internet Service Providers do not permit to leave mail 77 will return POP3_OPERATION_IN_PROGRESS if a different operation is call during another.
81 on server and the message will be deleted once downloaded.}. 78
82 The @code{stream_t} should be destroyed to indicate to the library that the
83 action is finished. POP3 only provide a single channel for operation, it
84 means only one operation can be done at a time, all the functions will return
85 MU_ERROR_OPERATION_IN_PROGRESS if call during another operation. The
86 functions @code{pop3_list_all ()}, @code{pop3_uidl_all ()} and
87 @code{pop3_capa ()} return iterators @code{pop3_list_current ()},
88 @code{pop3_uidl_current ()} are provided as cover function. The iterator must
89 be destroy when finish.
90
91 In a multithreaded application, only one thread should access @var{pop3_t}
92 handles.
93 79
94 @subsubsection Initialization 80 @subsubsection Initialization
95 @cindex POP3 Initialization 81 @cindex POP3 Initialization
96 82
97 @deftypefun int pop3_create (pop3_t * @var{pop3}) 83 @deftypefun int pop3_create (pop3_t *@var{pop3})
98 84
99 Allocate and initialize a @var{pop3} handle. 85 Allocate and initialize a @var{pop3}, only memory is allocated.
100 86
87 Errors:
101 @table @code 88 @table @code
102 @item MU_ERROR_NO_MEMORY 89 @item POP3_NO_MEMORY
103 @item MU_ERROR_INVALID_PARAMETER 90 @item POP3_INVALID_PARAMETER
104 @end table 91 @end table
105 @end deftypefun 92 @end deftypefun
106 93
107 @deftypefun void pop3_destroy (pop3_t *@var{pop3}) 94 @deftypefun void pop3_destroy (pop3_t *@var{pop3})
108 95
109 When a POP3 session is finished, the structure must be @code{free ()}'ed to 96 When a POP3 session is finished, any data use by the library is release.
110 reclaim memory.
111 @end deftypefun 97 @end deftypefun
112 98
113 @deftypefun int pop3_connect (pop3_t, const char *@var{host}, unsigned @var{port}, int @var{flags}) 99 @deftypefun int pop3_connect (pop3_t @var{pop3}, const char *@var{hostname}, int @var{port}, int @var{flags})
114 100
115 A connection is established by calling @code{pop3d_open ()}, the previous 101 A connection is established on @var{hostname:port}, if there was any previous connection it is close first. If non-blocking the
116 connection is close first. If non-blocking the function should be recalled 102 function should be recalled until the return value is not POP3_TRY_AGAIN or POP3_IN_PROGRESS.
117 until the return value is not MU_ERROR_TRY_AGAIN or MU_ERROR_IN_PROGRESS.
118 103
104 Errors:
119 @table @code 105 @table @code
120 @item MU_ERROR_NO_MEMORY 106 @item POP3_NO_MEMORY
121 @item MU_ERROR_INVALID_PARAMETER 107 @item POP3_TRY_AGAIN
122 @item MU_ERROR_IO 108 @item POP3_TIMEOUT
123 @item MU_ERROR_IN_PROGRESS 109 @item POP3_CONN_REFUSED
124 @item MU_ERROR_TRY_AGAIN 110 @item POP3_NO_CONN
125 @item MU_ERROR_OPERATION_DENIED 111 @item POP3_INTERRUPTED
126 @item MU_ERROR_TIMEOUT
127 @item MU_ERROR_NO_LOCK
128 @end table 112 @end table
113
129 @end deftypefun 114 @end deftypefun
130 115
131 @subsubsection Carrier 116 @deftypefun int pop3_disconnect (pop3_t @var{pop3})
132 @cindex POP3 channel 117
118 Disconnect an establised POP3 session.
119
120 Errors:
121 @table @code
122 @item POP3_NO_CONN
123 @item POP3_INTERRUPTED
124 @end table
125
126 @end deftypefun
127 @cindex POP3 carrier
133 128
134 @deftypefun int pop3_set_carrier (pop3_t, stream_t @var{carrier}); 129 @deftypefun int pop3_set_carrier (pop3_t @var{pop3}, pop3_carrier_t @var{carrier})
135 130
136 The type of stream use to contact as server will be set to @var{carrier} 131 The pop3 library abstracts the creation of the stream to the server and let the user overrides the access methods. The default,
137 in the @var{pop3_t} handle. Any previous @var{carrier} stream in 132 when no special carrier is provided, is to provide a carrier implemented with sockets and the use of @code{select ()}.
138 the handle, will be close and release.
139 133
134 Errors:
140 @table @code 135 @table @code
141 @item MU_ERROR_INVALID_PARAMETER 136 @item POP3_INVALID_PARAMETER
142 @end table 137 @end table
138
139 @deftp {Data Type} pop3_carrier_t
140 The @code{pop3_carrier_t} is defined as follows:
141
142 @example
143 @group
144 struct _pop3_carrier;
145 typedef struct _pop3_carrier* pop3_carrier_t;
146
147 #define POP3_CARRIER_NON_BLOCKING 1
148
149 struct _pop3_carrier @{
150 int (*open) (pop3_carrier_t, const char *hostname, int port, int flags);
151 int (*close) (pop3_carrier_t);
152
153 int (*read) (pop3_carrier_t, void *, size_t, size_t *);
154 int (*write) (pop3_carrier_t, const void *, size_t, size_t *);
155
156 int (*is_readready) (pop3_carrier_t, int timeout_seconds, int *ready);
157 int (*is_writeready) (pop3_carrier_t, int timeout_seconds, int *ready);
158
159 void (*destroy) (pop3_carrier_t *carrier);
160
161 void *data;
162 @};
163 @end group
164 @end example
165
166 @end deftp
167
168 The errors return by the carrier functions
169 @table @code
170 @item POP3_CARRIER_BAD
171 @item POP3_CARRIER_TRY_AGAIN
172 @item POP3_CARRIER_TIMEOUT
173 @item POP3_CARRIER_CONN_REFUSED
174 @item POP3_CARRIER_NOT_CONNECTED
175 @item POP3_CARRIER_INTERRUPTED
176 @end table
177
143 @end deftypefun 178 @end deftypefun
144 179
145 @deftypefun int pop3_get_carrier (pop3_t, stream_t *@var{carrier}); 180 @subsubsection Authentication State
181 @cindex POP3 APOP
182
183 @deftypefun int pop3_apop (pop3_t @var{pop3}, const char *@var{user}, const char *@var{secret})
146 184
147 Return the @var{pop3_t} carrier. If none was set, a new tcp stream will be 185 APOP offers an alternative to USER/PASS authentication. For intermittent use of POP3, like checking for new mail, it is the
148 created. 186 preferred way to authenticate. It reduces the risk of password capture. The @var{user} and the shared @var{secret} are pass
187 to @code{pop3_apop ()}, the MD5 digest is calculated by applying the timestamp given by the server in the greeting followed by
188 the @var{secret}.
149 189
190 @end deftypefun
191
192 @cindex POP3 USER
193
194 @deftypefun int pop3_user (pop3_t, const char *@var{user})
195
196 Sends the USER command.
197
198 Errors:
150 @table @code 199 @table @code
151 @item MU_ERROR_INVALID_PARAMETER 200 @item POP3_INVALID_PARAMETER
152 @item MU_ERROR_NO_MEMORY 201 @item POP3_OPERATION_DENIED
202 @item any carrier errors.
153 @end table 203 @end table
154 @end deftypefun 204 @end deftypefun
155 205
156 @subsubsection Apop 206 @cindex POP3 PASS
157 @cindex POP3 Apop
158 207
159 @deftypefun int pop3_apop (pop3_t, const char *@var{user}, const char *@var{secret}) 208 @deftypefun int pop3_pass (pop3_t, const char *@var{passwd})
160 209
161 Apop offers an alternative to User/Pass authentication. For intermittent 210 Sends the PASS, to authenticate after the USER command.
162 use of POP3, like checking for new mail, it is the preferred the
163 authentication. It reduces the risk of password capture. The @var{user}
164 and the shared @var{secret} are pass to @code{pop3_apop ()}, the MD5 digest
165 is calculated by applying the times tamp given by the server in the greeting
166 followed by the @var{secret}.
167 211
212 Errors:
168 @table @code 213 @table @code
169 @item MU_ERROR_INVALID_PARAMETER 214 @item POP3_INVALID_PARAMETER
170 @item MU_ERROR_IO 215 @item POP3_OPERATION_DENIED
171 @item MU_ERROR_TIMEOUT 216 @item any carrier errors
172 @item MU_ERROR_TRY_AGAIN
173 @item MU_ERROR_OPERATION_DENIED
174 @end table 217 @end table
175 @end deftypefun 218 @end deftypefun
176 219
177 @subsubsection Capa 220 @cindex POP3 CAPA
178 @cindex POP3 Capa 221
222 @deftypefun int pop3_capa (pop3_t @var{pop3})
223
224 The CAPA command is send to the sever and the list of capabilities is retrieve by calling @code{pop3_capa_iterate()}.
225
226 Errors:
227 @table @code
228 @item POP3_INVALID_PARAMETER
229 @item POP3_OPERATION_DENIED
230 @item any carrier errors.
231 @end table
232 @end deftypefun
179 233
180 @deftypefun int pop3_capa (pop3_t, pop3_capa_iterator_t *@var{iterator}) 234 @deftypefun int pop3_capa_iterate (pop3_t @var{pop3}, char **@var{capa})
181 235
182 The Capa command is send to the sever and the list of capabilities is 236 To iterate through the capabilities response from the server, this function should be call in the loop. @var{capa} will be set
183 return in an @var{iterator}. @code{iterator_current ()} gives an allocated 237 to @code{NULL} to indicate termination. Any other operations then @code{pop3_capa_iterate ()} will return
184 string that should be @code{free ()}'ed. 238 @var{POP3_OPERATION_IN_PROGRESS} until the CAPA command is complete.
185 @strong{Caution:} The iterator must be destroy after use, it will discard
186 any remaining responses from CAPA and clear the way for new operations.
187 239
240 Errors:
188 @table @code 241 @table @code
189 @item MU_ERROR_INVALID_PARAMETER 242 @item POP3_INVALID_PARAMETER
190 @item MU_ERROR_IO 243 @item POP3_OPERATION_DENIED
191 @item MU_ERROR_TIMEOUT 244 @item any carrier errors.
192 @item MU_ERROR_TRY_AGAIN
193 @item MU_ERROR_OPERATION_DENIED
194 @end table 245 @end table
246 @end deftypefun
195 247
196 @example 248 @example
197 #include <stdio.h> 249 #include <stdio.h>
198 #include <stdlib.h> 250 #include <stdlib.h>
199 #include <mailutils/pop3.h> 251 #include <mailutils/pop3.h>
200 252
253 /* Assuming the pop3 is a valid connection. */
201 void print_capabilities (pop3_t pop3) 254 void print_capabilities (pop3_t pop3)
202 @{ 255 @{
203 pop3_capa_iterator_t iterator; 256 status = pop3_capa (pop3);
204 status = pop3_capa (pop3, &iterator);
205 if (status == 0) 257 if (status == 0)
206 @{ 258 @{
207 for (pop3_capa_first (iterator); 259 char *capa;
208 !pop3_capa_is_done (iterator); 260 while ((status = pop3_capa_iterate(pop3, &capa) == 0) && capa != NULL)
209 pop3_capa_next (iterator))
210 @{ 261 @{
211 char *capa; 262 printf ("CAPA: %s\n", capa);
212 if (pop3_capa_current (iterator, &capa) == 0) 263 free (capa);
213 @{;
214 printf ("CAPA: %s\n", capa);
215 free (capa);
216 @}
217 @} 264 @}
218 pop3_capa_destroy (&iterator);
219 @} 265 @}
220 else 266 else
221 printf ("NONE\n"); 267 printf ("NONE\n");
222 @} 268 @}
223 @end example 269 @end example
224 270
225 @end deftypefun
226 271
227 @subsubsection Dele 272 @subsubsection Transaction State
228 @cindex POP3 Dele 273 @cindex POP3 DELE
229 274
230 @deftypefun int pop3_dele (pop3_t, unsigned @var{msgno}) 275 @deftypefun int pop3_dele (pop3_t @var{pop3}, unsigned @var{msgno})
231 276
232 Sends a Dele to the servers who will mark the @var{msgno} for deletion. 277 Sends a DELE to the servers who will mark the @var{msgno} for deletion. The @var{msgno} may not refer to a message already marked
233 The @var{msgno} may not refer to a message already marked deleted. 278 deleted. If successful any future reference to @var{msgno} in other operations will be an error, unless unmarked by RSET.
234 If successful any future reference to @var{msgno} in other operations will
235 be an error, unless unmarked by RSET.
236 279
280 Errors:
237 @table @code 281 @table @code
238 @item MU_ERROR_INVALID_PARAMETER 282 @item POP3_INVALID_PARAMETER
239 @item MU_ERROR_IO 283 @item POP3_OPERATION_DENIED
240 @item MU_ERROR_TIMEOUT 284 @item POP3_OPERATION_IN_PROGRESS
241 @item MU_ERROR_TRY_AGAIN 285 @item any carrier errors.
242 @item MU_ERROR_OPERATION_DENIED
243 @end table 286 @end table
244 287
245 @end deftypefun 288 @end deftypefun
246 289
247 @subsubsection List 290 @cindex POP3 LIST
248 @cindex POP3 List
249 @cindex struct pop3_list 291 @cindex struct pop3_list
250 292
251 @deftypefun int pop3_list (pop3_t, unsigned @var{msgno}, size_t *@var{size}) 293 @deftypefun int pop3_list (pop3_t @var{pop3}, unsigned @var{msgno}, size_t *@var{size})
252 294
253 Sends a List for a specific @var{msgno} and returns the @var{size}. 295 Sends a List for a specific @var{msgno} and returns the @var{size}.
254 296
297 Errors:
298 @table @code
299 @item POP3_INVALID_PARAMETER
300 @item POP3_OPERATION_DENIED
301 @item POP3_OPERATION_IN_PROGRESS
302 @item any carrier errors.
303 @end table
304 @end deftypefun
305
306 @deftypefun int pop3_list_all (pop3_t @var{pop3})
307
308 Sends a LIST with no argument to the server. The @var{iterator} must be destroy after use, it will discard any remaining response
309 from LIST and clear the way for new operations. A cover function @code{pop3_list_current ()} around to scan properly the string
310 return by the @code{iterator_current ()}.
311
312 Errors:
255 @table @code 313 @table @code
256 @item MU_ERROR_INVALID_PARAMETER 314 @item POP3_INVALID_PARAMETER
257 @item MU_ERROR_IO 315 @item POP3_OPERATION_DENIED
258 @item MU_ERROR_TIMEOUT 316 @item POP3_OPERATION_IN_PROGRESS
259 @item MU_ERROR_TRY_AGAIN 317 @item any carrier errors.
260 @item MU_ERROR_OPERATION_DENIED
261 @end table 318 @end table
262 @end deftypefun 319 @end deftypefun
263 320
264 @deftypefun int pop3_list_all (pop3_t, iterator_t *@var{iterator}) 321 @deftypefun int pop3_list_iterate (pop3_t @var{pop3}, unsigned int *@var{msgno}, sie_t *@var{size})
265 322
266 Sends A List with no argument to the server. The @var{iterator} must be 323 To iterate through the capabilities response from the server, this function should be call in the loop. @var{msgno} will be set
267 destroy after use, it will discard any remaining response from LIST and 324 to @code{0} to indicate termination. Any other operations then @code{pop3_list_iterate ()} will return
268 clear the way for new operations. A cover function @code{pop3_list_current ()} 325 @var{POP3_OPERATION_IN_PROGRESS} until the LIST command is complete.
269 around to scan properly the string return by the @code{iterator_current ()}. 326
327 Errors:
328 @table @code
329 @item POP3_INVALID_PARAMETER
330 @item POP3_OPERATION_DENIED
331 @item POP3_OPERATION_IN_PROGRESS
332 @item any carrier errors.
333 @end table
334 @end deftypefun
270 335
271 @example 336 @example
272 #include <stdio.h> 337 #include <stdio.h>
273 #include <stdlib.h> 338 #include <stdlib.h>
274 #include <mailutils/pop3.h> 339 #include <mailutils/pop3.h>
275 340
341 /* Assuming pop3 is a valid session. */
276 void print_list (pop3_t pop3) 342 void print_list (pop3_t pop3)
277 @{ 343 @{
278 pop3_list_iterator_t iterator; 344 status = pop3_list_all (pop3);
279 status = pop3_list_all (pop3, &iterator);
280 if (status == 0) 345 if (status == 0)
281 @{ 346 @{
282 for (pop3_list_first (iterator); 347 unsigned int msgno = 0;
283 !pop3_list_is_done (iterator); 348 size_t size = 0;
284 pop3_list_next (iterator)) 349 while ((status = pop3_list_iterate (pop3, &msgno, &size)) == 0 && msgno != 0)
285 @{ 350 @{
286 unsigned int msgno, size; 351 printf ("LIST: %u %d\n", msgno, size);
287 if (pop3_list_current (iterator, &msgno, &size) == 0)
288 @{
289 printf ("LIST: %d %d\n", msgno, size);
290 @}
291 @} 352 @}
292 pop3_list_destroy (&iterator);
293 @} 353 @}
294 else 354 else
295 printf ("NONE\n"); 355 printf ("NONE\n");
296 @} 356 @}
297 @end example 357 @end example
298 358
299 @table @code 359 @cindex POP3 NOOP
300 @item MU_ERROR_INVALID_PARAMETER
301 @item MU_ERROR_IO
302 @item MU_ERROR_TIMEOUT
303 @item MU_ERROR_TRY_AGAIN
304 @item MU_ERROR_OPERATION_DENIED
305 @end table
306 360
307 @end deftypefun 361 @deftypefun int pop3_noop (pop3_t @var{pop3})
308
309 @deftypefun int pop3_list_current (pop3_t, unsigned int *@var{msgno}, size_t *@var{size})
310
311 Cover functions around @code{iterator_current ()} from an iterator created
312 by @code{pop3_list_all ()} to format the result.
313
314 @table @code
315 @item MU_ERROR_INVALID_PARAMETER
316 @item MU_ERROR_IO
317 @item MU_ERROR_TIMEOUT
318 @item MU_ERROR_TRY_AGAIN
319 @item MU_ERROR_OPERATION_DENIED
320 @end table
321
322 @end deftypefun
323
324 @subsubsection Noop
325 @cindex POP3 Noop
326
327 @deftypefun int pop3_noop (pop3_t)
328 362
329 Sends a NOOP, useful to reset the timeout on the server. 363 Sends a NOOP, useful to reset the timeout on the server.
330 364
365 Errors:
331 @table @code 366 @table @code
332 @item MU_ERROR_INVALID_PARAMETER 367 @item POP3_INVALID_PARAMETER
333 @item MU_ERROR_IO 368 @item POP3_OPERATION_DENIED
334 @item MU_ERROR_TIMEOUT 369 @item POP3_OPERATION_IN_PROGRESS
335 @item MU_ERROR_TRY_AGAIN 370 @item any carrier errors.
336 @item MU_ERROR_OPERATION_DENIED
337 @end table 371 @end table
338 @end deftypefun 372 @end deftypefun
339 373
340 @subsubsection Pass 374 @cindex POP3 RETR
341 @cindex POP3 Pass
342 375
343 @deftypefun int pop3_pass (pop3_t, const char *@var{passwd}) 376 @deftypefun int pop3_retr (pop3_t @var{pop3}, unsigned @var{msgno})
344 377
345 Sends the PASS, to authenticate after the USER command. 378 If successful @code{pop3_retr_read} should be call to download the message, byte-stuff lines or handle internally, CRLFs are
379 converted to LF. All other operations will fail until the downloaed is complete by the caller.
346 380
381 Errors:
347 @table @code 382 @table @code
348 @item MU_ERROR_INVALID_PARAMETER 383 @item POP3_INVALID_PARAMETER
349 @item MU_ERROR_IO 384 @item POP3_OPERATION_DENIED
350 @item MU_ERROR_TIMEOUT 385 @item POP3_OPERATION_IN_PROGRESS
351 @item MU_ERROR_TRY_AGAIN 386 @item any carrier errors.
352 @item MU_ERROR_OPERATION_DENIED
353 @end table 387 @end table
354 @end deftypefun 388 @end deftypefun
355 389
356 @subsubsection Quit 390 @deftypefun int pop3_retr_read (pop3_t @var{pop3}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
357 @cindex POP3 Quit
358
359 @deftypefun int pop3_quit (pop3_t)
360 391
361 Enter the UPDATE state. The server will delete all messages marked 392 After a @code{pop3_retr ()}, this function is use to get the content of the message, it will fill the @var{buffer} up to
362 deleted before closing the connection. 393 a maximum of @var{len} and return in @var{nread} how much the @var{buffer} contains. If @var{nread} is zero, it signals
394 the termination of the command. Any other operations then @code{pop3_retr_read ()} will return
395 @var{POP3_OPERATION_IN_PROGRESS} until the RETR command is completed.
363 396
397 Errors:
364 @table @code 398 @table @code
365 @item MU_ERROR_INVALID_PARAMETER 399 @item POP3_INVALID_PARAMETER
366 @item MU_ERROR_IO 400 @item POP3_OPERATION_DENIED
367 @item MU_ERROR_TIMEOUT 401 @item POP3_OPERATION_IN_PROGRESS
368 @item MU_ERROR_TRY_AGAIN 402 @item any carrier errors.
369 @item MU_ERROR_OPERATION_DENIED
370 @end table 403 @end table
371 @end deftypefun 404 @end deftypefun
372 405
373 @subsubsection Retr
374 @cindex POP3 Retr
375
376 @deftypefun int pop3_retr (pop3_t, unsigned @var{msgno}, stream_t *)
377
378 If successful a @code{stream_t} is created to allow downloading of the
379 message, byte-stuff lines or handle internally, CRLFs are converted to LF.
380 All other operations will fail until the stream is destroyed by the caller.
381
382 @example 406 @example
383 #include <stdio.h> 407 #include <stdio.h>
384 #include <mailutils/pop3.h> 408 #include <mailutils/pop3.h>
...@@ -386,73 +410,52 @@ All other operations will fail until the stream is destroyed by the caller. ...@@ -386,73 +410,52 @@ All other operations will fail until the stream is destroyed by the caller.
386 int 410 int
387 print_message (pop3_t pop3, unsigned int msgno) 411 print_message (pop3_t pop3, unsigned int msgno)
388 @{ 412 @{
389 stream_t stream; 413 int status = pop3_retr (pop3, msgno);
390 int status = pop3_retr (pop3, msgno, &stream);
391 if (status == 0) 414 if (status == 0)
392 @{ 415 @{
393 size_t n = 0; 416 size_t n = 0;
394 char buf[128]; 417 char buf[128];
395 while ((stream_readline (stream, buf, sizeof buf, &n) == 0) 418 while ((status = pop_retr_read (pop3, buf, sizeof buf, &n)) == 0) && n > 0)
396 && n) 419 @{
397 printf ("%s", buf); 420 printf ("%s", buf);
398 stream_destroy (&stream); 421 @}
399 @} 422 @}
400 return status; 423 return status;
401 @} 424 @}
402 @end example 425 @end example
403 426
404 @table @code 427 @cindex POP3 TOP
405 @item MU_ERROR_INVALID_PARAMETER
406 @item MU_ERROR_IO
407 @item MU_ERROR_TIMEOUT
408 @item MU_ERROR_TRY_AGAIN
409 @item MU_ERROR_OPERATION_DENIED
410 @end table
411 @end deftypefun
412
413 @subsubsection Rset
414 @cindex POP3 Rset
415 428
416 @deftypefun int pop3_rset (pop3_t) 429 @deftypefun int pop3_top (pop3_t @var{pop3}, unsigned int @var{msgno}, unsigned int @var{lines})
417 430
418 Sends a RSET to unmark the messages marked as deleted. 431 If successful @code{pop3_top_read} should be call to download the header, byte-stuff lines or handle internally, CRLFs are
432 converted to LF. All other operations will failed until the operation is completed by the caller.
419 433
434 Errors:
420 @table @code 435 @table @code
421 @item MU_ERROR_INVALID_PARAMETER 436 @item POP3_INVALID_PARAMETER
422 @item MU_ERROR_IO 437 @item POP3_OPERATION_DENIED
423 @item MU_ERROR_TIMEOUT 438 @item POP3_OPERATION_IN_PROGRESS
424 @item MU_ERROR_TRY_AGAIN 439 @item any carrier errors.
425 @item MU_ERROR_OPERATION_DENIED
426 @end table 440 @end table
427 @end deftypefun 441 @end deftypefun
428 442
429 @subsubsection Stat 443 @deftypefun int pop3_top_read (pop3_t @var{pop3}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
430 @cindex POP3 Stat
431 444
432 @deftypefun int pop3_stat (pop3_t, unsigned @var{msgno}, unsigned *@var{msg_count}, size_t *@var{size}) 445 After a @code{pop3_top ()}, this function is use to get the content of the message, it will fill the @var{buffer} up to
433 446 a maximum of @var{len} and return in @var{nread} how much the @var{buffer} contains. If @var{nread} is zero, it signals
434 The number of messages in the mailbox and the size of the mailbox in octets. 447 the termination of the command. Any other operations then @code{pop3_retr_read ()} will return
435 @strong{Caution:} The size is in RFC822 where line termination is CRLF, 448 @var{POP3_OPERATION_IN_PROGRESS} until the TOP command is completed.
436 messages marked as deleted are not counted in either total.
437 449
450 Errors:
438 @table @code 451 @table @code
439 @item MU_ERROR_INVALID_PARAMETER 452 @item POP3_INVALID_PARAMETER
440 @item MU_ERROR_IO 453 @item POP3_OPERATION_DENIED
441 @item MU_ERROR_TIMEOUT 454 @item POP3_OPERATION_IN_PROGRESS
442 @item MU_ERROR_TRY_AGAIN 455 @item any carrier errors.
443 @item MU_ERROR_OPERATION_DENIED
444 @end table 456 @end table
445 @end deftypefun 457 @end deftypefun
446 458
447 @subsubsection Top
448 @cindex POP3 Top
449
450 @deftypefun int pop3_top (pop3_t, unsigned int @var{msgno}, unsigned int @var{lines}, stream_t *@var{stream})
451
452 If successful a @code{stream} is created to allow downloading of the header,
453 byte-stuff lines or handle internally, CRLFs are converted to LF. All other
454 operations will failed until the stream is destroyed by the caller.
455
456 @example 459 @example
457 #include <stdio.h> 460 #include <stdio.h>
458 #include <mailutils/pop3.h> 461 #include <mailutils/pop3.h>
...@@ -460,51 +463,93 @@ operations will failed until the stream is destroyed by the caller. ...@@ -460,51 +463,93 @@ operations will failed until the stream is destroyed by the caller.
460 int 463 int
461 print_top (pop3_t pop3, unsigned int msgno, unsigned int lines) 464 print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
462 @{ 465 @{
463 stream_t stream; 466 int status = pop3_top (pop3, msgno, lines);
464 int status = pop3_top (pop3, msgno, lines, &stream);
465 if (status == 0) 467 if (status == 0)
466 @{ 468 @{
467 size_t n = 0; 469 size_t n = 0;
468 char buf[128]; 470 char buf[128];
469 while ((stream_readline (stream, buf, sizeof buf, &n) == 0) 471 while ((status = pop3_top_read (pop3, buf, sizeof buf, &n)) == 0)
470 && n) 472 && n > 0)
471 printf ("%s", buf); 473 printf ("%s", buf);
472 stream_destroy (&stream);
473 @} 474 @}
474 return status; 475 return status;
475 @} 476 @}
476 @end example 477 @end example
477 478
479
480 @cindex POP3 RSET
481
482 @deftypefun int pop3_rset (pop3_t @var{pop3})
483
484 Sends a RSET to unmark the messages marked as deleted.
485
486 Errors:
487 @table @code
488 @item POP3_INVALID_PARAMETER
489 @item POP3_OPERATION_DENIED
490 @item POP3_OPERATION_IN_PROGRESS
491 @item any carrier errors.
492 @end table
493 @end deftypefun
494
495 @cindex POP3 STAT
496
497 @deftypefun int pop3_stat (pop3_t @var{pop3}, unsigned @var{msgno}, unsigned *@var{msg_count}, size_t *@var{size})
498
499 The number of messages in the mailbox and the size of the mailbox in octets. @strong{Caution:} The size is in RFC822 where
500 line termination is CRLF, messages marked as deleted are not counted in either total.
501
502 Errors:
478 @table @code 503 @table @code
479 @item MU_ERROR_INVALID_PARAMETER 504 @item POP3_INVALID_PARAMETER
480 @item MU_ERROR_IO 505 @item POP3_OPERATION_DENIED
481 @item MU_ERROR_TIMEOUT 506 @item POP3_OPERATION_IN_PROGRESS
482 @item MU_ERROR_TRY_AGAIN 507 @item any carrier errors.
483 @item MU_ERROR_OPERATION_DENIED
484 @end table 508 @end table
485 @end deftypefun 509 @end deftypefun
486 510
487 @subsubsection Uidl 511 @cindex POP3 UIDL
488 @cindex POP3 Uidl 512
513 @deftypefun int pop3_uidl (pop3_t @var{pop3}, unsigned int @var{msgno}, char **@var{uidl})
514
515 The UIDL is return in @var{uidl}, the string must be @code{free ()}'ed, by the caller.
516
517 Errors:
518 @table @code
519 @item POP3_INVALID_PARAMETER
520 @item POP3_OPERATION_DENIED
521 @item POP3_OPERATION_IN_PROGRESS
522 @item any carrier errors.
523 @end table
524 @end deftypefun
489 525
490 @deftypefun int pop3_uidl (pop3_t, unsigned int @var{msgno}, char **@var{uidl}) 526 @deftypefun int pop3_uidl_all (pop3_t @var{pop3})
491 527
492 The Uniq Identifier is return in @var{uidl}, the string must be 528 A UIDL command is executed. The call should iterate with @code{pop3_uidl_iterate ()} to fetch the response.
493 @code{free ()}'ed, by the caller.
494 529
530 Errors:
495 @table @code 531 @table @code
496 @item MU_ERROR_INVALID_PARAMETER 532 @item POP3_INVALID_PARAMETER
497 @item MU_ERROR_IO 533 @item POP3_OPERATION_DENIED
498 @item MU_ERROR_TIMEOUT 534 @item POP3_OPERATION_IN_PROGRESS
499 @item MU_ERROR_TRY_AGAIN 535 @item any carrier errors.
500 @item MU_ERROR_OPERATION_DENIED
501 @end table 536 @end table
502 @end deftypefun 537 @end deftypefun
503 538
504 @deftypefun int pop3_uidl_all (pop3_t, iterator_t * @var{iterator}) 539 @deftypefun int pop3_uidl_iterate (pop3_t @var{pop3}, unsigned int *@var{msgno}, char **@var{uidl})
505 540
506 An @code{iterator} object is return to iterate through the response and 541 To iterate through the uidl responses from the server, @code{pop3_uidl_iterate ()} should be call in a loop, @var{msgno} will be set
507 must be destroyed by the caller. 542 to zero to indicate termination. Any other operations then @code{pop3_uidl;_iterate ()} will return
543 @var{POP3_OPERATION_IN_PROGRESS} until the UIDL command is completed. The @var{uidl} is @code{malloc()}
544 and should be @code{free()} by the caller.
545
546 Errors:
547 @table @code
548 @item POP3_INVALID_PARAMETER
549 @item POP3_OPERATION_DENIED
550 @item any carrier errors.
551 @end table
552 @end deftypefun
508 553
509 @example 554 @example
510 #include <stdio.h> 555 #include <stdio.h>
...@@ -513,83 +558,52 @@ must be destroyed by the caller. ...@@ -513,83 +558,52 @@ must be destroyed by the caller.
513 558
514 void print_uidl (pop3_t pop3) 559 void print_uidl (pop3_t pop3)
515 @{ 560 @{
516 pop3_uidl_iterator_t iterator; 561 status = pop3_uidl_all (pop3);
517 status = pop3_uidl_all (pop3, &iterator);
518 if (status == 0) 562 if (status == 0)
519 @{ 563 @{
520 for (pop3_uidl_first (iterator); 564 unsigned int msgno;
521 !pop3_uidl_is_done (iterator); 565 char *uidl;
522 pop3_uidl_next (iterator)) 566 while (pop3_uidl_iterate (pop3, &msgno, &uidl) == 0 && msgno != 0)
523 @{ 567 @{
524 unsigned int msgno; 568 printf ("LIST: %d %s\n", msgno, uidl);
525 char *uidl; 569 free (uidl);
526 if (pop3_uidl_current (iterator, &msgno, &uidl) == 0)
527 @{
528 printf ("LIST: %d %s\n", msgno, uidl);
529 free (uidl);
530 @}
531 @} 570 @}
532 pop3_uidl_destroy (&iterator);
533 @} 571 @}
534 else 572 else
535 printf ("NONE\n"); 573 printf ("NONE\n");
536 @} 574 @}
537 @end example 575 @end example
538 576
539 @table @code
540 @item MU_ERROR_INVALID_PARAMETER
541 @item MU_ERROR_IO
542 @item MU_ERROR_TIMEOUT
543 @item MU_ERROR_TRY_AGAIN
544 @item MU_ERROR_OPERATION_DENIED
545 @end table
546 @end deftypefun
547
548 @deftypefun int pop3_uidl_current (iterator_t @var{iterator}, unsigned int *@var{msgno}, char **@var{uidl})
549 577
550 Cover functions around @code{iterator_current ()} from an iterator created 578 @subsubsection Update State
551 by @code{pop3_uidl_all ()} to format the result. The variable @var{uidl} 579 @cindex POP3 QUIT
552 should be @code{free ()}'ed.
553 580
554 @table @code 581 @deftypefun int pop3_quit (pop3_t)
555 @item MU_ERROR_INVALID_PARAMETER
556 @item MU_ERROR_IO
557 @item MU_ERROR_TIMEOUT
558 @item MU_ERROR_TRY_AGAIN
559 @item MU_ERROR_OPERATION_DENIED
560 @end table
561 @end deftypefun
562
563 @subsubsection User
564 @cindex POP3 User
565
566 @deftypefun int pop3_user (pop3_t, const char *@var{user})
567 582
568 Sends the User command. 583 QUIT will be send to enter the update state, if the command is successfull, the connection is close and any statein
584 the library is cleared. On the server side, all messages marked deleted before closing the connection will be removed..
569 585
586 Errors:
570 @table @code 587 @table @code
571 @item MU_ERROR_INVALID_PARAMETER 588 @item POP3_INVALID_PARAMETER
572 @item MU_ERROR_IO 589 @item POP3_OPERATION_DENIED
573 @item MU_ERROR_TIMEOUT 590 @item POP3_OPERATION_IN_PROGRESS
574 @item MU_ERROR_TRY_AGAIN 591 @item any carrier errors.
575 @item MU_ERROR_OPERATION_DENIED
576 @end table 592 @end table
577 @end deftypefun 593 @end deftypefun
578 594
595
579 @subsubsection Help functions 596 @subsubsection Help functions
580 597
581 @deftypefun int pop3_writeline (pop3_t, const char *@var{format}, ...); 598 @deftypefun int pop3_writeline (pop3_t, const char *@var{format}, ...);
582 599
583 Copy in the internal buffer of @code{pop3_t} the formatted string, 600 Copy in the internal buffer of @code{pop3_t} the formatted string, @code{pop3_send ()} should be called later to flush the string
584 @code{pop3_send ()} should be called later to flush the string to the 601 to the POP3 server.
585 POP3 server.
586 602
603 Errors:
587 @table @code 604 @table @code
588 @item MU_ERROR_INVALID_PARAMETER 605 @item POP3_INVALID_PARAMETER
589 @item MU_ERROR_IO 606 @item any carrier errors.
590 @item MU_ERROR_TIMEOUT
591 @item MU_ERROR_TRY_AGAIN
592 @item MU_ERROR_OPERATION_DENIED
593 @end table 607 @end table
594 @end deftypefun 608 @end deftypefun
595 609
...@@ -597,27 +611,21 @@ POP3 server. ...@@ -597,27 +611,21 @@ POP3 server.
597 611
598 Cover function for @code{pop3_writeline ()} and @code{pop3_send ()}. 612 Cover function for @code{pop3_writeline ()} and @code{pop3_send ()}.
599 613
614 Errors:
600 @table @code 615 @table @code
601 @item MU_ERROR_INVALID_PARAMETER 616 @item POP3_INVALID_PARAMETER
602 @item MU_ERROR_IO 617 @item any carrier errors.
603 @item MU_ERROR_TIMEOUT
604 @item MU_ERROR_TRY_AGAIN
605 @item MU_ERROR_OPERATION_DENIED
606 @end table 618 @end table
607
608 @end deftypefun 619 @end deftypefun
609 620
610 @deftypefun int pop3_send (pop3_t, const char *@var{cmd}); 621 @deftypefun int pop3_send (pop3_t);
611 622
612 Flushes out the strings written by @code{pop3_writeline ()} in the internal 623 Flushes out the strings written by @code{pop3_writeline ()} in the internal buffer to the channel.
613 buffer to the channel.
614 624
625 Errors:
615 @table @code 626 @table @code
616 @item MU_ERROR_INVALID_PARAMETER 627 @item POP3_INVALID_PARAMETER
617 @item MU_ERROR_IO 628 @item any carrier errors.
618 @item MU_ERROR_TIMEOUT
619 @item MU_ERROR_TRY_AGAIN
620 @item MU_ERROR_OPERATION_DENIED
621 @end table 629 @end table
622 @end deftypefun 630 @end deftypefun
623 631
...@@ -626,14 +634,11 @@ buffer to the channel. ...@@ -626,14 +634,11 @@ buffer to the channel.
626 The last response from the last command is save and can be examine after 634 The last response from the last command is save and can be examine after
627 a failure or success. 635 a failure or success.
628 636
637 Errors:
629 @table @code 638 @table @code
630 @item MU_ERROR_INVALID_PARAMETER 639 @item POP3_INVALID_PARAMETER
631 @item MU_ERROR_IO 640 @item any carrier errors.
632 @item MU_ERROR_TIMEOUT
633 @item MU_ERROR_TRY_AGAIN
634 @item MU_ERROR_OPERATION_DENIED
635 @end table 641 @end table
636
637 @end deftypefun 642 @end deftypefun
638 643
639 @subsubsection Timeout 644 @subsubsection Timeout
...@@ -641,14 +646,21 @@ a failure or success. ...@@ -641,14 +646,21 @@ a failure or success.
641 646
642 @deftypefun int pop3_set_timeout (pop3_t, int @var{timeout}) 647 @deftypefun int pop3_set_timeout (pop3_t, int @var{timeout})
643 648
644 Set the timeout time for I/O on the carrier. The default is 10 minutes. 649 Set the timeout time for I/O on the carrier. The default is 10 minutes. The @var{timeout} is given in milliseconds.
645 The @var{timeout} is given in milliseconds.
646 650
651 Errors:
652 @table @code
653 @item POP3_INVALID_PARAMETER
654 @end table
647 @end deftypefun 655 @end deftypefun
648 656
649 @deftypefun int pop3_get_timeout (pop3_t, int *@var{timeout}) 657 @deftypefun int pop3_get_timeout (pop3_t, int *@var{timeout})
650 658
651 Get the timeout time for I/O on the carrier. 659 Get the timeout time for I/O on the carrier. The @var{timeout} is given in milliseconds.
652 The @var{timeout} is given in milliseconds. 660
661 Errors:
662 @table @code
663 @item POP3_INVALID_PARAMETER
664 @end table
653 665
654 @end deftypefun 666 @end deftypefun
......