summaryrefslogtreecommitdiffabout
path: root/libetpan/src/driver/interface/maildriver.h
blob: 16e830b69a08fd6a997457cb97e9a0e355df7b09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
/*
 * libEtPan! -- a mail stuff library
 *
 * Copyright (C) 2001, 2005 - DINH Viet Hoa
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the libEtPan! project nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

/*
 * $Id$
 */

#ifndef MAILDRIVER_H

#define MAILDRIVER_H

#include <libetpan/maildriver_types.h>
#include <libetpan/maildriver_types_helper.h>

#ifdef __cplusplus
extern "C" {
#endif

/* mailsession */

/*
  mailsession_new creates a new session, using the given driver

  @return the created session is returned
*/

mailsession * mailsession_new(mailsession_driver * sess_driver);

/*
  mailsession_free release the memory used by the session
*/

void mailsession_free(mailsession * session);

/*
  mailsession_parameters is used to make calls specific to the driver

  @param id   is the command to send to the driver,
           usually, commands can be found in the header of the driver

  @param value is the parameter of the specific call 

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_parameters(mailsession * session,
			   int id, void * value);

/*
  There are drivers of two kinds : stream drivers (driver that connects
  to servers through TCP or other means of connection) and file drivers
  (driver that are based on filesystem)

  The following function can only be used by stream drivers.
  mailsession_connect_stream connects a stream to the session

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_connect_stream(mailsession * session, mailstream * s);

/*
  The following function can only be used by file drivers.
  mailsession_connect_path selects the main path of the session

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_connect_path(mailsession * session, char * path);

/*
  NOTE: works only on stream drivers

  mailsession_starttls switches the current connection to TLS (secure layer)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_starttls(mailsession * session);

/*
  mailsession_login notifies the login and the password to authenticate
  to the session

  @param userid    the given string is only needed at this function call
    (it will be duplicated if necessary)
  @param password  the given string is only needed at this function call
    (it will be duplicated if necessary)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_login(mailsession * session,
		      char * userid, char * password);

/*
  NOTE: this function doesn't often work on filsystem drivers

  mailsession_logout deconnects the session and closes the stream.

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_logout(mailsession * session);

/*
  mailsession_noop does no operation on the session, but it can be
  used to poll for the status of the connection.

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_noop(mailsession * session);

/*
  NOTE: driver's specific should be used

  mailsession_build_folder_name will return an allocated string with
  that contains the complete path of the folder to create

  @param session the sesion
  @param mb is the parent mailbox
  @param name is the name of the folder to create
  @param result the complete path of the folder to create will be
    stored in (* result), this name have to be freed with free()

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_build_folder_name(mailsession * session, char * mb,
				  char * name, char ** result);

/*
  NOTE: driver's specific should be used

  mailsession_create_folder creates the folder that corresponds to the
  given name

  @param session the session
  @param mb is the name of the mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_create_folder(mailsession * session, char * mb);


/*
  NOTE: driver's specific should be used

  mailsession_delete_folder deletes the folder that corresponds to the
  given name

  @param session the session
  @param mb is the name of the mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_delete_folder(mailsession * session, char * mb);


/*
  mailsession_rename_folder changes the name of the folder

  @param session the session
  @param mb is the name of the mailbox whose name has to be changed
  @param new_name is the destination name (the parent
    of the new folder folder can be other)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_rename_folder(mailsession * session,
			      char * mb, char * new_name);

/*
  mailsession_check_folder makes a checkpoint of the session
  
  @param session the session
  
  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_check_folder(mailsession * session);


/*
  NOTE: this function is not implemented in most drivers

  mailsession_examine_folder selects a mailbox as readonly
  
  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_examine_folder(mailsession * session, char * mb);


/*
  mailsession_select_folder selects a mailbox
  
  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_select_folder(mailsession * session, char * mb);


/*
  mailsession_expunge_folder deletes all messages marked \Deleted
  
  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_expunge_folder(mailsession * session);


/*
  mailsession_status_folder queries the status of the folder
  (number of messages, number of recent messages, number of unseen messages)
  
  @param session the session
  @param mb mailbox to query
  @param result_messages the number of messages is stored
    in (* result_messages)
  @param result_recent the number of messages is stored
    in (* result_recent)
  @param result_unseen the number of messages is stored
    in (* result_unseen)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_status_folder(mailsession * session, char * mb,
    uint32_t * result_messages, uint32_t * result_recent,
    uint32_t * result_unseen);


/*
  mailsession_messages_number queries the number of messages in the folder

  @param session the session
  @param mb mailbox to query
  @param result the number of messages is stored in (* result)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_messages_number(mailsession * session, char * mb,
				uint32_t * result);

/*
  mailsession_recent_number queries the number of recent messages in the folder

  @param session the session
  @param mb mailbox to query
  @param result the number of recent messages is stored in (* result)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_recent_number(mailsession * session,
			      char * mb, uint32_t * result);

/*
  mailsession_unseen_number queries the number of unseen messages in the folder

  @param session the session
  @param mb mailbox to query
  @param result the number of unseen messages is stored in (* result)

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_unseen_number(mailsession * session, char * mb,
			      uint32_t * result);

/*
  NOTE: driver's specific should be used

  mailsession_list_folders returns the list of all sub-mailboxes
  of the given mailbox

  @param session the session
  @param mb the mailbox
  @param result list of mailboxes if stored in (* result),
    this structure have to be freed with mail_list_free()

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_list_folders(mailsession * session, char * mb,
			     struct mail_list ** result);

/*
  NOTE: driver's specific should be used

  mailsession_lsub_folders returns the list of subscribed
  sub-mailboxes of the given mailbox

  @param session the session
  @param mb the mailbox
  @param result list of mailboxes if stored in (* result),
    this structure have to be freed with mail_list_free()

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_lsub_folders(mailsession * session, char * mb,
			     struct mail_list ** result);

/*
  NOTE: driver's specific should be used

  mailsession_subscribe_folder subscribes to the given mailbox

  @param session the session
  @param mb the mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_subscribe_folder(mailsession * session, char * mb);

/*
  NOTE: driver's specific should be used

  mailsession_unsubscribe_folder unsubscribes to the given mailbox

  @param session the session
  @param mb the mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_unsubscribe_folder(mailsession * session, char * mb);

/*
  mailsession_append_message adds a RFC 2822 message to the current
  given mailbox

  @param session the session
  @param message is a string that contains the RFC 2822 message
  @param size this is the size of the message

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_append_message(mailsession * session,
			       char * message, size_t size);

int mailsession_append_message_flags(mailsession * session,
    char * message, size_t size, struct mail_flags * flags);

/*
  NOTE: some drivers does not implement this

  mailsession_copy_message copies a message whose number is given to
  a given mailbox. The mailbox must be accessible from the same session.

  @param session the session
  @param num the message number
  @param mb the destination mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_copy_message(mailsession * session,
			     uint32_t num, char * mb);

/*
  NOTE: some drivers does not implement this

  mailsession_move_message copies a message whose number is given to
  a given mailbox. The mailbox must be accessible from the same session.

  @param session the session
  @param num the message number
  @param mb the destination mailbox

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_move_message(mailsession * session,
			     uint32_t num, char * mb);

/*
  mailsession_get_messages_list returns the list of message numbers
  of the current mailbox.

  @param session the session
  @param result the list of message numbers will be stored in (* result),
    this structure have to be freed with mailmessage_list_free()

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_get_messages_list(mailsession * session,
				  struct mailmessage_list ** result);

/*
  mailsession_get_envelopes_list fills the parsed fields in the
  mailmessage structures of the mailmessage_list.

  @param session the session
  @param result this is the list of mailmessage structures

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_get_envelopes_list(mailsession * session,
				   struct mailmessage_list * result);

/*
  NOTE: some drivers does not implement this

  mailsession_remove_message removes the given message from the mailbox.
  The message is permanently deleted.

  @param session the session
  @param num is the message number

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_remove_message(mailsession * session, uint32_t num);


/*
  NOTE: this function is not implemented in most drivers

  mailsession_search_message returns a list of message numbers that
  corresponds to the given criteria.

  @param session the session
  @param charset is the charset to use (it can be NULL)
  @param key is the list of criteria
  @param result the search result is stored in (* result),
    this structure have to be freed with mail_search_result_free()

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

#if 0
int mailsession_search_messages(mailsession * session, char * charset,
				struct mail_search_key * key,
				struct mail_search_result ** result);
#endif

/*
  mailsession_get_message returns a mailmessage structure that corresponds
  to the given message number.
  * WARNING * mailsession_get_message_by_uid() should be used instead.

  @param session the session
  @param num the message number
  @param result the allocated mailmessage structure will be stored
    in (* result), this structure have to be freed with mailmessage_free() 

  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_get_message(mailsession * session,
			    uint32_t num, mailmessage ** result);

/*
  mailsession_get_message_by_uid returns a mailmessage structure
  that corresponds to the given message unique identifier.
  This is currently implemented only for cached drivers.
  * WARNING * That will deprecates the use of mailsession_get_message()
  
  @param session the session
  @param uid the message unique identifier
  @param result the allocated mailmessage structure will be stored
    in (* result), this structure have to be freed with mailmessage_free() 
  
  @return MAIL_NO_ERROR is returned on success, MAIL_ERROR_XXX is returned
    on error
*/

int mailsession_get_message_by_uid(mailsession * session,
    const char * uid, mailmessage ** result);

#ifdef __cplusplus
}
#endif

#endif