summaryrefslogtreecommitdiffabout
path: root/kmicromail/libetpan/imap/mailimap.h
Unidiff
Diffstat (limited to 'kmicromail/libetpan/imap/mailimap.h') (more/less context) (ignore whitespace changes)
-rw-r--r--kmicromail/libetpan/imap/mailimap.h598
1 files changed, 598 insertions, 0 deletions
diff --git a/kmicromail/libetpan/imap/mailimap.h b/kmicromail/libetpan/imap/mailimap.h
new file mode 100644
index 0000000..8dfa3d4
--- a/dev/null
+++ b/kmicromail/libetpan/imap/mailimap.h
@@ -0,0 +1,598 @@
1/*
2 * libEtPan! -- a mail stuff library
3 *
4 * Copyright (C) 2001, 2002 - DINH Viet Hoa
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * 3. Neither the name of the libEtPan! project nor the names of its
16 * contributors may be used to endorse or promote products derived
17 * from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 * SUCH DAMAGE.
30 */
31
32/*
33 * $Id$
34 */
35
36#ifndef MAILIMAP_H
37
38#define MAILIMAP_H
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44#include <libetpan/mailimap_types.h>
45#include <libetpan/mailimap_types_helper.h>
46#include <libetpan/mailimap_helper.h>
47
48#include <libetpan/mailimap_socket.h>
49#include <libetpan/mailimap_ssl.h>
50
51/*
52 mailimap_connect()
53
54 This function will connect the IMAP session with the given stream.
55
56 @param session the IMAP session
57 @param s stream to use
58
59 @return the return code is one of MAILIMAP_ERROR_XXX or
60 MAILIMAP_NO_ERROR codes
61
62 note that on success, MAILIMAP_NO_ERROR_AUTHENTICATED or
63 MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned
64
65 MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned when you need to
66 use mailimap_login() to authenticate, else
67 MAILIMAP_NO_ERROR_AUTHENTICATED is returned.
68*/
69
70int mailimap_connect(mailimap * session, mailstream * s);
71
72/*
73 mailimap_append()
74
75 This function will append a given message to the given mailbox
76 by sending an APPEND command.
77
78 @param session the IMAP session
79 @param mailbox name of the mailbox
80 @param flag_list flags of the message
81 @param date_time timestamp of the message
82 @param literal content of the message
83 @param literal_size size of the message
84
85 @return the return code is one of MAILIMAP_ERROR_XXX or
86 MAILIMAP_NO_ERROR codes
87*/
88
89int mailimap_append(mailimap * session, const char * mailbox,
90 struct mailimap_flag_list * flag_list,
91 struct mailimap_date_time * date_time,
92 const char * literal, size_t literal_size);
93
94/*
95 mailimap_noop()
96
97 This function will poll for an event on the server by
98 sending a NOOP command to the IMAP server
99
100 @param session IMAP session
101
102 @return the return code is one of MAILIMAP_ERROR_XXX or
103 MAILIMAP_NO_ERROR_XXX codes
104*/
105
106int mailimap_noop(mailimap * session);
107
108/*
109 mailimap_logout()
110
111 This function will logout from an IMAP server by sending
112 a LOGOUT command.
113
114 @param session IMAP session
115
116 @return the return code is one of MAILIMAP_ERROR_XXX or
117 MAILIMAP_NO_ERROR codes
118*/
119
120int mailimap_logout(mailimap * session);
121
122/*
123 mailimap_capability()
124
125 This function will query an IMAP server for his capabilities
126 by sending a CAPABILITY command.
127
128 @param session IMAP session
129 @param result The result of this command is a list of
130 capabilities and it is stored into (* result).
131
132 @return the return code is one of MAILIMAP_ERROR_XXX or
133 MAILIMAP_NO_ERROR codes
134 */
135
136int mailimap_capability(mailimap * session,
137 struct mailimap_capability_data ** result);
138
139/*
140 mailimap_check()
141
142 This function will request for a checkpoint of the mailbox by
143 sending a CHECK command.
144
145 @param session IMAP session
146
147 @return the return code is one of MAILIMAP_ERROR_XXX or
148 MAILIMAP_NO_ERROR codes
149 */
150
151int mailimap_check(mailimap * session);
152
153/*
154 mailimap_close()
155
156 This function will close the selected mailbox by sending
157 a CLOSE command.
158
159 @param session IMAP session
160
161 @return the return code is one of MAILIMAP_ERROR_XXX or
162 MAILIMAP_NO_ERROR codes
163 */
164
165int mailimap_close(mailimap * session);
166
167/*
168 mailimap_expunge()
169
170 This function will permanently remove from the selected mailbox
171 message that have the \Deleted flag set.
172
173 @param session IMAP session
174
175 @return the return code is one of MAILIMAP_ERROR_XXX or
176 MAILIMAP_NO_ERROR codes
177*/
178
179int mailimap_expunge(mailimap * session);
180
181/*
182 mailimap_copy()
183
184 This function will copy the given messages from the selected mailbox
185 to the given mailbox.
186
187 @param session IMAP session
188 @param set This is a set of message numbers.
189 @param mb This is the destination mailbox.
190
191 @return the return code is one of MAILIMAP_ERROR_XXX or
192 MAILIMAP_NO_ERROR codes
193 */
194
195int mailimap_copy(mailimap * session, struct mailimap_set * set,
196 const char * mb);
197
198/*
199 mailimap_uid_copy()
200
201 This function will copy the given messages from the selected mailbox
202 to the given mailbox.
203
204 @param session IMAP session
205 @param set This is a set of message unique identifiers.
206 @param mb This is the destination mailbox.
207
208 @return the return code is one of MAILIMAP_ERROR_XXX or
209 MAILIMAP_NO_ERROR codes
210 */
211
212int mailimap_uid_copy(mailimap * session,
213 struct mailimap_set * set, const char * mb);
214
215/*
216 mailimap_create()
217
218 This function will create a mailbox.
219
220 @param session IMAP session
221 @param mb This is the name of the mailbox to create.
222
223 @return the return code is one of MAILIMAP_ERROR_XXX or
224 MAILIMAP_NO_ERROR codes
225*/
226
227int mailimap_create(mailimap * session, const char * mb);
228
229/*
230 mailimap_delete()
231
232 This function will delete a mailox.
233
234 @param session IMAP session
235 @param mb This is the name of the mailbox to delete.
236
237 @return the return code is one of MAILIMAP_ERROR_XXX or
238 MAILIMAP_NO_ERROR codes
239*/
240
241int mailimap_delete(mailimap * session, const char * mb);
242
243/*
244 mailimap_examine()
245
246 This function will select the mailbox for read-only operations.
247
248 @param session IMAP session
249 @param mb This is the name of the mailbox to select.
250
251 @return the return code is one of MAILIMAP_ERROR_XXX or
252 MAILIMAP_NO_ERROR codes
253*/
254
255int mailimap_examine(mailimap * session, const char * mb);
256
257/*
258 mailimap_fetch()
259
260 This function will retrieve data associated with the given message
261 numbers.
262
263 @param session IMAP session
264 @param set set of message numbers
265 @param fetch_type type of information to be retrieved
266 @param result The result of this command is a clist
267 and it is stored into (* result). Each element of the clist is a
268 (struct mailimap_msg_att *).
269
270 @return the return code is one of MAILIMAP_ERROR_XXX or
271 MAILIMAP_NO_ERROR codes
272*/
273
274int
275mailimap_fetch(mailimap * session, struct mailimap_set * set,
276 struct mailimap_fetch_type * fetch_type, clist ** result);
277
278/*
279 mailimap_fetch()
280
281 This function will retrieve data associated with the given message
282 numbers.
283
284 @param session IMAP session
285 @param set set of message unique identifiers
286 @param fetch_type type of information to be retrieved
287 @param result The result of this command is a clist
288 and it is stored into (* result). Each element of the clist is a
289 (struct mailimap_msg_att *).
290
291 @return the return code is one of MAILIMAP_ERROR_XXX or
292 MAILIMAP_NO_ERROR codes
293*/
294
295int
296mailimap_uid_fetch(mailimap * session,
297 struct mailimap_set * set,
298 struct mailimap_fetch_type * fetch_type, clist ** result);
299
300/*
301 mailimap_fetch_list_free()
302
303 This function will free the result of a fetch command.
304
305 @param fetch_list This is the clist containing
306 (struct mailimap_msg_att *) elements to free.
307*/
308
309void mailimap_fetch_list_free(clist * fetch_list);
310
311/*
312 mailimap_list()
313
314 This function will return the list of the mailbox
315 available on the server.
316
317 @param session IMAP session
318 @param mb This is the reference name that informs
319 of the level of hierarchy
320 @param list_mb mailbox name with possible wildcard
321 @param result This will store a clist of (struct mailimap_mailbox_list *)
322 in (* result)
323
324 @return the return code is one of MAILIMAP_ERROR_XXX or
325 MAILIMAP_NO_ERROR codes
326*/
327
328int mailimap_list(mailimap * session, const char * mb,
329 const char * list_mb, clist ** result);
330
331/*
332 mailimap_login()
333
334 This function will authenticate the client.
335
336 @param session IMAP session
337 @param userid login of the user
338 @param password password of the user
339
340 @return the return code is one of MAILIMAP_ERROR_XXX or
341 MAILIMAP_NO_ERROR codes
342*/
343
344int mailimap_login(mailimap * session,
345 const char * userid, const char * password);
346
347/*
348 mailimap_lsub()
349
350 This function will return the list of the mailbox
351 that the client has subscribed to.
352
353 @param session IMAP session
354 @param mb This is the reference name that informs
355 of the level of hierarchy
356 @param list_mb mailbox name with possible wildcard
357 @param result This will store a list of (struct mailimap_mailbox_list *)
358 in (* result)
359
360 @return the return code is one of MAILIMAP_ERROR_XXX or
361 MAILIMAP_NO_ERROR codes
362*/
363
364int mailimap_lsub(mailimap * session, const char * mb,
365 const char * list_mb, clist ** result);
366
367/*
368 mailimap_list_result_free()
369
370 This function will free the clist of (struct mailimap_mailbox_list *)
371
372 @param list This is the clist to free.
373*/
374
375void mailimap_list_result_free(clist * list);
376
377/*
378 mailimap_rename()
379
380 This function will change the name of a mailbox.
381
382 @param session IMAP session
383 @param mb current name
384 @param new_name new name
385
386 @return the return code is one of MAILIMAP_ERROR_XXX or
387 MAILIMAP_NO_ERROR codes
388*/
389
390int mailimap_rename(mailimap * session,
391 const char * mb, const char * new_name);
392
393/*
394 mailimap_search()
395
396 All mails that match the given criteria will be returned
397 their numbers in the result list.
398
399 @param session IMAP session
400 @param charset This indicates the charset of the strings that appears
401 in the searching criteria
402 @param key This is the searching criteria
403 @param result The result is a clist of (uint32_t *) and will be
404 stored in (* result).
405
406 @return the return code is one of MAILIMAP_ERROR_XXX or
407 MAILIMAP_NO_ERROR codes
408*/
409
410int
411mailimap_search(mailimap * session, const char * charset,
412 struct mailimap_search_key * key, clist ** result);
413
414/*
415 mailimap_uid_search()
416
417
418 All mails that match the given criteria will be returned
419 their unique identifiers in the result list.
420
421 @param session IMAP session
422 @param charset This indicates the charset of the strings that appears
423 in the searching criteria
424 @param key This is the searching criteria
425 @param result The result is a clist of (uint32_t *) and will be
426 stored in (* result).
427
428 @return the return code is one of MAILIMAP_ERROR_XXX or
429 MAILIMAP_NO_ERROR codes
430*/
431
432int
433mailimap_uid_search(mailimap * session, const char * charset,
434 struct mailimap_search_key * key, clist ** result);
435
436/*
437 mailimap_search_result_free()
438
439 This function will free the result of the a search.
440
441 @param search_result This is a clist of (uint32_t *) returned
442 by mailimap_uid_search() or mailimap_search()
443*/
444
445void mailimap_search_result_free(clist * search_result);
446
447/*
448 mailimap_select()
449
450 This function will select a given mailbox so that messages in the
451 mailbox can be accessed.
452
453 @param session IMAP session
454 @param mb This is the name of the mailbox to select.
455
456 @return the return code is one of MAILIMAP_ERROR_XXX or
457 MAILIMAP_NO_ERROR codes
458*/
459
460int
461mailimap_select(mailimap * session, const char * mb);
462
463/*
464 mailimap_status()
465
466 This function will return informations about a given mailbox.
467
468 @param session IMAP session
469 @param mb This is the name of the mailbox
470 @param status_att_list This is the list of mailbox information to return
471 @param result List of returned values
472
473 @return the return code is one of MAILIMAP_ERROR_XXX or
474 MAILIMAP_NO_ERROR codes
475*/
476
477int
478mailimap_status(mailimap * session, const char * mb,
479 struct mailimap_status_att_list * status_att_list,
480 struct mailimap_mailbox_data_status ** result);
481
482/*
483 mailimap_uid_store()
484
485 This function will alter the data associated with some messages
486 (flags of the messages).
487
488 @param session IMAP session
489 @param set This is a list of message numbers.
490 @param store_att_flags This is the data to associate with the
491 given messages
492
493 @return the return code is one of MAILIMAP_ERROR_XXX or
494 MAILIMAP_NO_ERROR codes
495*/
496
497int
498mailimap_store(mailimap * session,
499 struct mailimap_set * set,
500 struct mailimap_store_att_flags * store_att_flags);
501
502/*
503 mailimap_uid_store()
504
505 This function will alter the data associated with some messages
506 (flags of the messages).
507
508 @param session IMAP session
509 @param set This is a list of message unique identifiers.
510 @param store_att_flags This is the data to associate with the
511 given messages
512
513 @return the return code is one of MAILIMAP_ERROR_XXX or
514 MAILIMAP_NO_ERROR codes
515*/
516
517int
518mailimap_uid_store(mailimap * session,
519 struct mailimap_set * set,
520 struct mailimap_store_att_flags * store_att_flags);
521
522/*
523 mailimap_subscribe()
524
525 This function adds the specified mailbox name to the
526 server's set of "active" or "subscribed" mailboxes.
527
528 @param session IMAP session
529 @param mb This is the name of the mailbox
530
531 @return the return code is one of MAILIMAP_ERROR_XXX or
532 MAILIMAP_NO_ERROR codes
533*/
534
535int mailimap_subscribe(mailimap * session, const char * mb);
536
537/*
538 mailimap_unsubscribe()
539
540 This function removes the specified mailbox name to the
541 server's set of "active" or "subscribed" mailboxes.
542
543 @param session IMAP session
544 @param mb This is the name of the mailbox
545
546 @return the return code is one of MAILIMAP_ERROR_XXX or
547 MAILIMAP_NO_ERROR codes
548*/
549
550int mailimap_unsubscribe(mailimap * session, const char * mb);
551
552/*
553 mailimap_starttls()
554
555 This function starts change the mode of the connection to
556 switch to SSL connection.
557
558 @param session IMAP session
559
560 @return the return code is one of MAILIMAP_ERROR_XXX or
561 MAILIMAP_NO_ERROR_XXX codes
562 */
563
564int mailimap_starttls(mailimap * session);
565
566/*
567 mailimap_new()
568
569 This function returns a new IMAP session.
570
571 @param progr_rate When downloading messages, a function will be called
572 each time the amount of bytes downloaded reaches a multiple of this
573 value, this can be 0.
574 @param progr_fun This is the function to call to notify the progress,
575 this can be NULL.
576
577 @return an IMAP session is returned.
578 */
579
580mailimap * mailimap_new(size_t imap_progr_rate,
581 progress_function * imap_progr_fun);
582
583/*
584 mailimap_free()
585
586 This function will free the data structures associated with
587 the IMAP session.
588
589 @param session IMAP session
590 */
591
592void mailimap_free(mailimap * session);
593
594#ifdef __cplusplus
595}
596#endif
597
598#endif