author | zautrix <zautrix> | 2005-03-18 20:17:03 (UTC) |
---|---|---|
committer | zautrix <zautrix> | 2005-03-18 20:17:03 (UTC) |
commit | 9e549686b23b6dffdcbd09c9b10dc2cb795fbcdf (patch) (unidiff) | |
tree | 2528e6cc740225ca0f47d5ac8ff70f7d3bb10621 /libetpan/src/driver/interface/maildriver.h | |
parent | 9319998f20f03dcc217fbb39656755dc65226276 (diff) | |
download | kdepimpi-9e549686b23b6dffdcbd09c9b10dc2cb795fbcdf.zip kdepimpi-9e549686b23b6dffdcbd09c9b10dc2cb795fbcdf.tar.gz kdepimpi-9e549686b23b6dffdcbd09c9b10dc2cb795fbcdf.tar.bz2 |
Initial revision
Diffstat (limited to 'libetpan/src/driver/interface/maildriver.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | libetpan/src/driver/interface/maildriver.h | 546 |
1 files changed, 546 insertions, 0 deletions
diff --git a/libetpan/src/driver/interface/maildriver.h b/libetpan/src/driver/interface/maildriver.h new file mode 100644 index 0000000..16e830b --- a/dev/null +++ b/libetpan/src/driver/interface/maildriver.h | |||
@@ -0,0 +1,546 @@ | |||
1 | /* | ||
2 | * libEtPan! -- a mail stuff library | ||
3 | * | ||
4 | * Copyright (C) 2001, 2005 - 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 AUTHORS 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 AUTHORS 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 | int mailsession_append_message_flags(mailsession * session, | ||
404 | char * message, size_t size, struct mail_flags * flags); | ||
405 | |||
406 | /* | ||
407 | NOTE: some drivers does not implement this | ||
408 | |||
409 | mailsession_copy_message copies a message whose number is given to | ||
410 | a given mailbox. The mailbox must be accessible from the same session. | ||
411 | |||
412 | @param session the session | ||
413 | @param num the message number | ||
414 | @param mb the destination mailbox | ||
415 | |||
416 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
417 | on error | ||
418 | */ | ||
419 | |||
420 | int mailsession_copy_message(mailsession * session, | ||
421 | uint32_t num, char * mb); | ||
422 | |||
423 | /* | ||
424 | NOTE: some drivers does not implement this | ||
425 | |||
426 | mailsession_move_message copies a message whose number is given to | ||
427 | a given mailbox. The mailbox must be accessible from the same session. | ||
428 | |||
429 | @param session the session | ||
430 | @param num the message number | ||
431 | @param mb the destination mailbox | ||
432 | |||
433 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
434 | on error | ||
435 | */ | ||
436 | |||
437 | int mailsession_move_message(mailsession * session, | ||
438 | uint32_t num, char * mb); | ||
439 | |||
440 | /* | ||
441 | mailsession_get_messages_list returns the list of message numbers | ||
442 | of the current mailbox. | ||
443 | |||
444 | @param session the session | ||
445 | @param result the list of message numbers will be stored in (* result), | ||
446 | this structure have to be freed with mailmessage_list_free() | ||
447 | |||
448 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
449 | on error | ||
450 | */ | ||
451 | |||
452 | int mailsession_get_messages_list(mailsession * session, | ||
453 | struct mailmessage_list ** result); | ||
454 | |||
455 | /* | ||
456 | mailsession_get_envelopes_list fills the parsed fields in the | ||
457 | mailmessage structures of the mailmessage_list. | ||
458 | |||
459 | @param session the session | ||
460 | @param result this is the list of mailmessage structures | ||
461 | |||
462 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
463 | on error | ||
464 | */ | ||
465 | |||
466 | int mailsession_get_envelopes_list(mailsession * session, | ||
467 | struct mailmessage_list * result); | ||
468 | |||
469 | /* | ||
470 | NOTE: some drivers does not implement this | ||
471 | |||
472 | mailsession_remove_message removes the given message from the mailbox. | ||
473 | The message is permanently deleted. | ||
474 | |||
475 | @param session the session | ||
476 | @param num is the message number | ||
477 | |||
478 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
479 | on error | ||
480 | */ | ||
481 | |||
482 | int mailsession_remove_message(mailsession * session, uint32_t num); | ||
483 | |||
484 | |||
485 | /* | ||
486 | NOTE: this function is not implemented in most drivers | ||
487 | |||
488 | mailsession_search_message returns a list of message numbers that | ||
489 | corresponds to the given criteria. | ||
490 | |||
491 | @param session the session | ||
492 | @param charset is the charset to use (it can be NULL) | ||
493 | @param key is the list of criteria | ||
494 | @param result the search result is stored in (* result), | ||
495 | this structure have to be freed with mail_search_result_free() | ||
496 | |||
497 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
498 | on error | ||
499 | */ | ||
500 | |||
501 | #if 0 | ||
502 | int mailsession_search_messages(mailsession * session, char * charset, | ||
503 | struct mail_search_key * key, | ||
504 | struct mail_search_result ** result); | ||
505 | #endif | ||
506 | |||
507 | /* | ||
508 | mailsession_get_message returns a mailmessage structure that corresponds | ||
509 | to the given message number. | ||
510 | * WARNING * mailsession_get_message_by_uid() should be used instead. | ||
511 | |||
512 | @param session the session | ||
513 | @param num the message number | ||
514 | @param result the allocated mailmessage structure will be stored | ||
515 | in (* result), this structure have to be freed with mailmessage_free() | ||
516 | |||
517 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
518 | on error | ||
519 | */ | ||
520 | |||
521 | int mailsession_get_message(mailsession * session, | ||
522 | uint32_t num, mailmessage ** result); | ||
523 | |||
524 | /* | ||
525 | mailsession_get_message_by_uid returns a mailmessage structure | ||
526 | that corresponds to the given message unique identifier. | ||
527 | This is currently implemented only for cached drivers. | ||
528 | * WARNING * That will deprecates the use of mailsession_get_message() | ||
529 | |||
530 | @param session the session | ||
531 | @param uid the message unique identifier | ||
532 | @param result the allocated mailmessage structure will be stored | ||
533 | in (* result), this structure have to be freed with mailmessage_free() | ||
534 | |||
535 | @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned | ||
536 | on error | ||
537 | */ | ||
538 | |||
539 | int mailsession_get_message_by_uid(mailsession * session, | ||
540 | const char * uid, mailmessage ** result); | ||
541 | |||
542 | #ifdef __cplusplus | ||
543 | } | ||
544 | #endif | ||
545 | |||
546 | #endif | ||