Diffstat (limited to 'kmicromail/libetpan/include/libetpan/maildriver.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | kmicromail/libetpan/include/libetpan/maildriver.h | 543 |
1 files changed, 543 insertions, 0 deletions
diff --git a/kmicromail/libetpan/include/libetpan/maildriver.h b/kmicromail/libetpan/include/libetpan/maildriver.h new file mode 100644 index 0000000..7da9aea --- a/dev/null +++ b/kmicromail/libetpan/include/libetpan/maildriver.h | |||
@@ -0,0 +1,543 @@ | |||
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 MAILDRIVER_H | ||
37 | |||
38 | #define MAILDRIVER_H | ||
39 | |||
40 | #include <libetpan/maildriver_types.h> | ||
41 | #include <libetpan/maildriver_types_helper.h> | ||
42 | |||
43 | #ifdef __cplusplus | ||
44 | extern "C" { | ||
45 | #endif | ||
46 | |||
47 | /* mailsession */ | ||
48 | |||
49 | /* | ||
50 | mailsession_new creates a new session, using the given driver | ||
51 | |||
52 | @return the created session is returned | ||
53 | */ | ||
54 | |||
55 | mailsession * mailsession_new(mailsession_driver * sess_driver); | ||
56 | |||
57 | /* | ||
58 | mailsession_free release the memory used by the session | ||
59 | */ | ||
60 | |||
61 | void mailsession_free(mailsession * session); | ||
62 | |||
63 | /* | ||
64 | mailsession_parameters is used to make calls specific to the driver | ||
65 | |||
66 | @param id is the command to send to the driver, | ||
67 | usually, commands can be found in the header of the driver | ||
68 | |||
69 | @param value is the parameter of the specific call | ||
70 | |||
71 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
72 | on error | ||
73 | */ | ||
74 | |||
75 | int mailsession_parameters(mailsession * session, | ||
76 | int id, void * value); | ||
77 | |||
78 | /* | ||
79 | There are drivers of two kinds : stream drivers (driver that connects | ||
80 | to servers through TCP or other means of connection) and file drivers | ||
81 | (driver that are based on filesystem) | ||
82 | |||
83 | The following function can only be used by stream drivers. | ||
84 | mailsession_connect_stream connects a stream to the session | ||
85 | |||
86 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
87 | on error | ||
88 | */ | ||
89 | |||
90 | int mailsession_connect_stream(mailsession * session, mailstream * s); | ||
91 | |||
92 | /* | ||
93 | The following function can only be used by file drivers. | ||
94 | mailsession_connect_path selects the main path of the session | ||
95 | |||
96 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
97 | on error | ||
98 | */ | ||
99 | |||
100 | int mailsession_connect_path(mailsession * session, char * path); | ||
101 | |||
102 | /* | ||
103 | NOTE: works only on stream drivers | ||
104 | |||
105 | mailsession_starttls switches the current connection to TLS (secure layer) | ||
106 | |||
107 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
108 | on error | ||
109 | */ | ||
110 | |||
111 | int mailsession_starttls(mailsession * session); | ||
112 | |||
113 | /* | ||
114 | mailsession_login notifies the login and the password to authenticate | ||
115 | to the session | ||
116 | |||
117 | @param userid the given string is only needed at this function call | ||
118 | (it will be duplicated if necessary) | ||
119 | @param password the given string is only needed at this function call | ||
120 | (it will be duplicated if necessary) | ||
121 | |||
122 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
123 | on error | ||
124 | */ | ||
125 | |||
126 | int mailsession_login(mailsession * session, | ||
127 | char * userid, char * password); | ||
128 | |||
129 | /* | ||
130 | NOTE: this function doesn't often work on filsystem drivers | ||
131 | |||
132 | mailsession_logout deconnects the session and closes the stream. | ||
133 | |||
134 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
135 | on error | ||
136 | */ | ||
137 | |||
138 | int mailsession_logout(mailsession * session); | ||
139 | |||
140 | /* | ||
141 | mailsession_noop does no operation on the session, but it can be | ||
142 | used to poll for the status of the connection. | ||
143 | |||
144 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
145 | on error | ||
146 | */ | ||
147 | |||
148 | int mailsession_noop(mailsession * session); | ||
149 | |||
150 | /* | ||
151 | NOTE: driver's specific should be used | ||
152 | |||
153 | mailsession_build_folder_name will return an allocated string with | ||
154 | that contains the complete path of the folder to create | ||
155 | |||
156 | @param session the sesion | ||
157 | @param mb is the parent mailbox | ||
158 | @param name is the name of the folder to create | ||
159 | @param result the complete path of the folder to create will be | ||
160 | stored in (* result), this name have to be freed with free() | ||
161 | |||
162 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
163 | on error | ||
164 | */ | ||
165 | |||
166 | int mailsession_build_folder_name(mailsession * session, char * mb, | ||
167 | char * name, char ** result); | ||
168 | |||
169 | /* | ||
170 | NOTE: driver's specific should be used | ||
171 | |||
172 | mailsession_create_folder creates the folder that corresponds to the | ||
173 | given name | ||
174 | |||
175 | @param session the session | ||
176 | @param mb is the name of the mailbox | ||
177 | |||
178 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
179 | on error | ||
180 | */ | ||
181 | |||
182 | int mailsession_create_folder(mailsession * session, char * mb); | ||
183 | |||
184 | |||
185 | /* | ||
186 | NOTE: driver's specific should be used | ||
187 | |||
188 | mailsession_delete_folder deletes the folder that corresponds to the | ||
189 | given name | ||
190 | |||
191 | @param session the session | ||
192 | @param mb is the name of the mailbox | ||
193 | |||
194 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
195 | on error | ||
196 | */ | ||
197 | |||
198 | int mailsession_delete_folder(mailsession * session, char * mb); | ||
199 | |||
200 | |||
201 | /* | ||
202 | mailsession_rename_folder changes the name of the folder | ||
203 | |||
204 | @param session the session | ||
205 | @param mb is the name of the mailbox whose name has to be changed | ||
206 | @param new_name is the destination name (the parent | ||
207 | of the new folder folder can be other) | ||
208 | |||
209 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
210 | on error | ||
211 | */ | ||
212 | |||
213 | int mailsession_rename_folder(mailsession * session, | ||
214 | char * mb, char * new_name); | ||
215 | |||
216 | /* | ||
217 | mailsession_check_folder makes a checkpoint of the session | ||
218 | |||
219 | @param session the session | ||
220 | |||
221 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
222 | on error | ||
223 | */ | ||
224 | |||
225 | int mailsession_check_folder(mailsession * session); | ||
226 | |||
227 | |||
228 | /* | ||
229 | NOTE: this function is not implemented in most drivers | ||
230 | |||
231 | mailsession_examine_folder selects a mailbox as readonly | ||
232 | |||
233 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
234 | on error | ||
235 | */ | ||
236 | |||
237 | int mailsession_examine_folder(mailsession * session, char * mb); | ||
238 | |||
239 | |||
240 | /* | ||
241 | mailsession_select_folder selects a mailbox | ||
242 | |||
243 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
244 | on error | ||
245 | */ | ||
246 | |||
247 | int mailsession_select_folder(mailsession * session, char * mb); | ||
248 | |||
249 | |||
250 | /* | ||
251 | mailsession_expunge_folder deletes all messages marked \Deleted | ||
252 | |||
253 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
254 | on error | ||
255 | */ | ||
256 | |||
257 | int mailsession_expunge_folder(mailsession * session); | ||
258 | |||
259 | |||
260 | /* | ||
261 | mailsession_status_folder queries the status of the folder | ||
262 | (number of messages, number of recent messages, number of unseen messages) | ||
263 | |||
264 | @param session the session | ||
265 | @param mb mailbox to query | ||
266 | @param result_messages the number of messages is stored | ||
267 | in (* result_messages) | ||
268 | @param result_recent the number of messages is stored | ||
269 | in (* result_recent) | ||
270 | @param result_unseen the number of messages is stored | ||
271 | in (* result_unseen) | ||
272 | |||
273 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
274 | on error | ||
275 | */ | ||
276 | |||
277 | int mailsession_status_folder(mailsession * session, char * mb, | ||
278 | uint32_t * result_messages, uint32_t * result_recent, | ||
279 | uint32_t * result_unseen); | ||
280 | |||
281 | |||
282 | /* | ||
283 | mailsession_messages_number queries the number of messages in the folder | ||
284 | |||
285 | @param session the session | ||
286 | @param mb mailbox to query | ||
287 | @param result the number of messages is stored in (* result) | ||
288 | |||
289 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
290 | on error | ||
291 | */ | ||
292 | |||
293 | int mailsession_messages_number(mailsession * session, char * mb, | ||
294 | uint32_t * result); | ||
295 | |||
296 | /* | ||
297 | mailsession_recent_number queries the number of recent messages in the folder | ||
298 | |||
299 | @param session the session | ||
300 | @param mb mailbox to query | ||
301 | @param result the number of recent messages is stored in (* result) | ||
302 | |||
303 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
304 | on error | ||
305 | */ | ||
306 | |||
307 | int mailsession_recent_number(mailsession * session, | ||
308 | char * mb, uint32_t * result); | ||
309 | |||
310 | /* | ||
311 | mailsession_unseen_number queries the number of unseen messages in the folder | ||
312 | |||
313 | @param session the session | ||
314 | @param mb mailbox to query | ||
315 | @param result the number of unseen messages is stored in (* result) | ||
316 | |||
317 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
318 | on error | ||
319 | */ | ||
320 | |||
321 | int mailsession_unseen_number(mailsession * session, char * mb, | ||
322 | uint32_t * result); | ||
323 | |||
324 | /* | ||
325 | NOTE: driver's specific should be used | ||
326 | |||
327 | mailsession_list_folders returns the list of all sub-mailboxes | ||
328 | of the given mailbox | ||
329 | |||
330 | @param session the session | ||
331 | @param mb the mailbox | ||
332 | @param result list of mailboxes if stored in (* result), | ||
333 | this structure have to be freed with mail_list_free() | ||
334 | |||
335 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
336 | on error | ||
337 | */ | ||
338 | |||
339 | int mailsession_list_folders(mailsession * session, char * mb, | ||
340 | struct mail_list ** result); | ||
341 | |||
342 | /* | ||
343 | NOTE: driver's specific should be used | ||
344 | |||
345 | mailsession_lsub_folders returns the list of subscribed | ||
346 | sub-mailboxes of the given mailbox | ||
347 | |||
348 | @param session the session | ||
349 | @param mb the mailbox | ||
350 | @param result list of mailboxes if stored in (* result), | ||
351 | this structure have to be freed with mail_list_free() | ||
352 | |||
353 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
354 | on error | ||
355 | */ | ||
356 | |||
357 | int mailsession_lsub_folders(mailsession * session, char * mb, | ||
358 | struct mail_list ** result); | ||
359 | |||
360 | /* | ||
361 | NOTE: driver's specific should be used | ||
362 | |||
363 | mailsession_subscribe_folder subscribes to the given mailbox | ||
364 | |||
365 | @param session the session | ||
366 | @param mb the mailbox | ||
367 | |||
368 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
369 | on error | ||
370 | */ | ||
371 | |||
372 | int mailsession_subscribe_folder(mailsession * session, char * mb); | ||
373 | |||
374 | /* | ||
375 | NOTE: driver's specific should be used | ||
376 | |||
377 | mailsession_unsubscribe_folder unsubscribes to the given mailbox | ||
378 | |||
379 | @param session the session | ||
380 | @param mb the mailbox | ||
381 | |||
382 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
383 | on error | ||
384 | */ | ||
385 | |||
386 | int mailsession_unsubscribe_folder(mailsession * session, char * mb); | ||
387 | |||
388 | /* | ||
389 | mailsession_append_message adds a RFC 2822 message to the current | ||
390 | given mailbox | ||
391 | |||
392 | @param session the session | ||
393 | @param message is a string that contains the RFC 2822 message | ||
394 | @param size this is the size of the message | ||
395 | |||
396 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
397 | on error | ||
398 | */ | ||
399 | |||
400 | int mailsession_append_message(mailsession * session, | ||
401 | char * message, size_t size); | ||
402 | |||
403 | /* | ||
404 | NOTE: some drivers does not implement this | ||
405 | |||
406 | mailsession_copy_message copies a message whose number is given to | ||
407 | a given mailbox. The mailbox must be accessible from the same session. | ||
408 | |||
409 | @param session the session | ||
410 | @param num the message number | ||
411 | @param mb the destination mailbox | ||
412 | |||
413 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
414 | on error | ||
415 | */ | ||
416 | |||
417 | int mailsession_copy_message(mailsession * session, | ||
418 | uint32_t num, char * mb); | ||
419 | |||
420 | /* | ||
421 | NOTE: some drivers does not implement this | ||
422 | |||
423 | mailsession_move_message copies a message whose number is given to | ||
424 | a given mailbox. The mailbox must be accessible from the same session. | ||
425 | |||
426 | @param session the session | ||
427 | @param num the message number | ||
428 | @param mb the destination mailbox | ||
429 | |||
430 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
431 | on error | ||
432 | */ | ||
433 | |||
434 | int mailsession_move_message(mailsession * session, | ||
435 | uint32_t num, char * mb); | ||
436 | |||
437 | /* | ||
438 | mailsession_get_messages_list returns the list of message numbers | ||
439 | of the current mailbox. | ||
440 | |||
441 | @param session the session | ||
442 | @param result the list of message numbers will be stored in (* result), | ||
443 | this structure have to be freed with mailmessage_list_free() | ||
444 | |||
445 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
446 | on error | ||
447 | */ | ||
448 | |||
449 | int mailsession_get_messages_list(mailsession * session, | ||
450 | struct mailmessage_list ** result); | ||
451 | |||
452 | /* | ||
453 | mailsession_get_envelopes_list fills the parsed fields in the | ||
454 | mailmessage structures of the mailmessage_list. | ||
455 | |||
456 | @param session the session | ||
457 | @param result this is the list of mailmessage structures | ||
458 | |||
459 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
460 | on error | ||
461 | */ | ||
462 | |||
463 | int mailsession_get_envelopes_list(mailsession * session, | ||
464 | struct mailmessage_list * result); | ||
465 | |||
466 | /* | ||
467 | NOTE: some drivers does not implement this | ||
468 | |||
469 | mailsession_remove_message removes the given message from the mailbox. | ||
470 | The message is permanently deleted. | ||
471 | |||
472 | @param session the session | ||
473 | @param num is the message number | ||
474 | |||
475 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
476 | on error | ||
477 | */ | ||
478 | |||
479 | int mailsession_remove_message(mailsession * session, uint32_t num); | ||
480 | |||
481 | |||
482 | /* | ||
483 | NOTE: this function is not implemented in most drivers | ||
484 | |||
485 | mailsession_search_message returns a list of message numbers that | ||
486 | corresponds to the given criteria. | ||
487 | |||
488 | @param session the session | ||
489 | @param charset is the charset to use (it can be NULL) | ||
490 | @param key is the list of criteria | ||
491 | @param result the search result is stored in (* result), | ||
492 | this structure have to be freed with mail_search_result_free() | ||
493 | |||
494 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
495 | on error | ||
496 | */ | ||
497 | |||
498 | #if 0 | ||
499 | int mailsession_search_messages(mailsession * session, char * charset, | ||
500 | struct mail_search_key * key, | ||
501 | struct mail_search_result ** result); | ||
502 | #endif | ||
503 | |||
504 | /* | ||
505 | mailsession_get_message returns a mailmessage structure that corresponds | ||
506 | to the given message number. | ||
507 | * WARNING * mailsession_get_message_by_uid() should be used instead. | ||
508 | |||
509 | @param session the session | ||
510 | @param num the message number | ||
511 | @param result the allocated mailmessage structure will be stored | ||
512 | in (* result), this structure have to be freed with mailmessage_free() | ||
513 | |||
514 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
515 | on error | ||
516 | */ | ||
517 | |||
518 | int mailsession_get_message(mailsession * session, | ||
519 | uint32_t num, mailmessage ** result); | ||
520 | |||
521 | /* | ||
522 | mailsession_get_message_by_uid returns a mailmessage structure | ||
523 | that corresponds to the given message unique identifier. | ||
524 | This is currently implemented only for cached drivers. | ||
525 | * WARNING * That will deprecates the use of mailsession_get_message() | ||
526 | |||
527 | @param session the session | ||
528 | @param uid the message unique identifier | ||
529 | @param result the allocated mailmessage structure will be stored | ||
530 | in (* result), this structure have to be freed with mailmessage_free() | ||
531 | |||
532 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
533 | on error | ||
534 | */ | ||
535 | |||
536 | int mailsession_get_message_by_uid(mailsession * session, | ||
537 | const char * uid, mailmessage ** result); | ||
538 | |||
539 | #ifdef __cplusplus | ||
540 | } | ||
541 | #endif | ||
542 | |||
543 | #endif | ||