mailbox.texi
16.2 KB
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
Mail boxes come in different formats and may be on a remote hosts,
only accessible through Mail Delivery Agent(MDA). Regardeless
of the format and the protocol use, some common actions are needed like
reading, saving, deleting, scanning ... Those actions are provided via a
unify API mailbox_t.
All functions of the mailbox_t API return 0 if succesfull or non-zero
for failure, unless specify otherwise.
@section Init/Destroy
Initializing and destroying a mailbox_t object.
@deftypefun int mailbox_init (mailbox_t *@var{mbx}, const char * @var{url}, int @var{id})
Based on the type of the @var{url}, @var{mbx} is initialize to a known type,
if @var{id} is not zero, it represents the id of the mailbox. The @var{id}
will be use instead of doing heuristic search on the @var{url}.
@example
#include <mailutils.h>
@dots{}
mailbox_t foo, popmbx, bar;
/* same as @url{file:///var/mail/foo} */
mailbox_init (&mbox, "/var/mail/foo", 0);
mailbox_init (&mbox, "pop://popserver.bar.com/foo", 0);
mailbox_init (&mbox, "file:///home/bar/.hiddenmail/bar", 0);
@end example
@end deftypefun
@deftypefun int mailbox_init_default (mailbox_t *@var{mbx}, const char * @var{user})
Initialize the default mailbox of the system as set by the mail adminstrator.
It could be hardcoded or override by a configuration
@file{$sysconfig/mailutils.conf}.
@example
#include <mailutils.h>
@dots{}
/* If the default mailbox on this system is @file{/var/mail} */
mailbox_t mbx;
/* sets the mailbox name to @url{file:///var/mail/foo} */
mailbox_init_default (&mbx, "foo");
/*
If the user is log as @emph{bar}, sets the mailbox name
to @url{file:///var/mail/bar}
*/
mailbox_init_default (&mbx, NULL);
@end example
@end deftypefun
@deftypefun int mailbox_destroy (mailbox_t *@var{mbx})
All ressources allocated are release. If the stream is not open,
@code{mailbox_close} is call.
@end deftypefun
@section Open/Close
Opening and closing mailbox can be done any number of times. But be warned
on some cases like POP3, when opening, the lock can be persistent until
the stream is closed as required by the RFC.
@deftypefun int mailbox_open (mailbox_t @var{mbx}, int @var{flag})
Open the mailbox box stream. This funtion will call @code{mailbox_scan}.
@defmac MU_MB_RDONLY
Stream is open read-only.
@end defmac
@defmac MU_MB_WRONLY
Stream is open write-only.
@end defmac
@defmac MU_MB_RDWR
Stream is open read-write.
@end defmac
@defmac MU_MB_CREAT
If Folder does not exist it is created. May be a noop on remote hosts mailbox.
@end defmac
@defmac MU_MB_APPEND
The stream is opened in append mode.
@end defmac
@defmac MU_MB_ONONBLOCK
For sockets, open() nonblocking. Not supported.
@end defmac
@end deftypefun
@deftypefun int mailbox_close (mailbox_t @var{mbx})
Close the streams and release the locks.
@end deftypefun
@deftypefun int mailbox_is_open (mailbox_t @var{mbx})
Return a non-zero value if the stream is open, zero otherwise.
@end deftypefun
This is a very simple implementation of Unix @command{biff}.
@example
#include <mailutils.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#define NAP 120
int
main ()
@{
mailbox_t mbx;
size_t size = 0, size2 = 0;
if (mailbox_init_default (&mbx, NULL) != 0)
@{
fprintf ("Can't initiliaze system mailbox\n");
exit (EXIT_FAILURE);
@}
/* the open may fail if no mailbox was created,
will check this later */
mailbox_open (mbx, MU_MB_RDONLY);
mailbox_size (mbx, &size);
for (;;)
@{
if (! mailbox_is_open (mbx))
@{
if (mailbox_open (mbx, MU_MB_RDONLY) != 0);
@{
//fprintf (stderr, "Not exist ?\n");
@}
@}
else
@{
if (mailbox_size (mbx, &size2) == 0)
@{
if (size2 > size)
@{
printf ("You got mail\a\n");
@}
size = size2;
@}
@}
/* rest a while */
sleep (NAP);
/* It is a good habit to close the resources.
A mailbox could be a remote host and the locking
may interfere with normal delivery, for example with
POP, the lock is hold during the entire session.
*/
mailbox_close (mbx);
@}
return 0;
@}
@end example
@section Deletion
Messages can be marked for deletion but the action of removing them is only
taken when @code{mailbox_expunge} is called.
@deftypefun int mailbox_delete (mailbox_t @var{mbx}, size_t @var{msgno})
Mark message @var{msgno} for deletion.
@end deftypefun
@deftypefun int mailbox_undelete (mailbox_t @var{mbx}, size_t @var{msgno})
UnMark message @var{msgno} for deletion.
@end deftypefun
@deftypefun int mailbox_is_deleted (mailbox_t @var{mbx}, size_t @var{msgno})
Return 1 if message @var{msgno} is mark deleted.
@end deftypefun
@deftypefun int mailbox_num_deleted (mailbox_t @var{mbx})
Return the number of Mailbox marked to be delete.
@end deftypefun
@deftypefun int mailbox_expunge (mailbox_t @var{mbx})
All messages marked for deletion will be removed and the mailbox updated,
and notification functions executed.
@end deftypefun
@section Message
Messages are object that hold the offsets of the message in the mailbox.
Certain mailboxes allow new messages to be appended the existing folder,
int this case the stream must be @code{mailbox_open} with the proper
permission.
@deftypefun int mailbox_new_message (mailbox_t @var{mbx}, message_t *@var{msg})
Create a new message.
@end deftypefun
@deftypefun int mailbox_append_message (mailbox_t @var{mbx}, message_t @var{msg}, int @var{destroy})
@var{msg} will be append to the mailbox. When appending the header may be
modified. In the case of Unix Mbox, the header "From " is prepend.
If @var{destroy} is set non-zero @code{message_destroy} will be call after delivery.
@end deftypefun
@deftypefun int mailbox_get_message (mailbox_t @var{mbx}, size_t @var{msgno}, message_t *@var{msg})
@var{msg} is initialize, be warn when doing @code{mailbox_expunge} the
offsets to the mailbox are losts and accessing the @var{msg} is undefined.
To prevent this, it is possible to @code{message_clone} or set a notification.
@end deftypefun
@deftypefun int mailbox_destroy_message (mailbox_t @var{mbx}, message_t @var{msg})
Resources allocated to @var{msg} will be release. Notification functions for
this @var{msg} are executed.
@end deftypefun
@section Reading Contents/Headers
Low level Reading funtions for contents and headers.
@comment @deftypefun int mailbox_set_header (mailbox_t @var{mbx}, size_t @var{msgno}, const char *@var{header}, size_t @var{len}, int @var{replace})
@comment Fill the header of new message @var{msgno}. If @var{replace} is zero the
@comment buffer @var{header} will be append, otherwise it will overwrite any
@comment existing one.
@comment @end deftypefun
@comment @deftypefun int mailbox_set_body (mailbox_t @var{mbx}, message_t @var{msg}, const char *@var{body}, size_t @var{len}, int @var{replace})
@comment Fill the body of new @var{msg}. If @var{replace} is zero the buffer
@comment @var{body} will be append, otherwise it will overwrite any existing one.
@comment @end deftypefun
@deftypefun int mailbox_get_content (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
Read the body of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned in
@var{nread}.
@end deftypefun
@deftypefun int mailbox_get_mcontent (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
A buffer is allocated with @code{malloc(3)} return memory containing the body
of message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
@end deftypefun
@deftypefun int mailbox_get_header (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
Read the header of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned
in @var{nread}.
@end deftypefun
@deftypefun int mailbox_get_mheader (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
A buffer allocate with @code{malloc(3)} is return containing the header of
message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
@end deftypefun
@section Locking
Most mailboxes will lock before changing their contents. External usage of
those functions are discourage, since they may interfere with normal
operation and cause deadlocks. If however there is need to access the
mailbox outside the functions provided by the library, locking and unlocking
can be done explicitely. There is another level of internal
locking to provide synchronisation to the mailbox_t object.
@deftypefun int mailbox_lock (mailbox_t @var{mbx}, int @var{flag})
Grab the lock. In some cases, i.e Unix mbox this may involve creating
a .lock file in the spool directory.
@comment Say something about permission the program be gid on some OS.
@defmac MU_MB_RDLOCK
Read lock.
@end defmac
@defmac MU_MB_WRLOCK
Write lock.
@end defmac
@defmac MU_MB_RWLOCK
Read/Write lock.
@end defmac
@end deftypefun
Note on many mailboxes, RDLOCK is a noop.
@deftypefun int mailbox_unlock (mailbox_t @var{mbx})
Release the lock.
@end deftypefun
@section Mailbox Attributes
When creating certain mailboxes, you can set the owner, group and mode
@deftypefun int mailbox_set_owner (mailbox_t @var{mbx}, uid_t @var{uid})
Set the owner to @var{uid}. If the Mailbox was not @code{mailbox_open}
the action is delayed until the stream is opened.
@end deftypefun
@deftypefun int mailbox_set_group (mailbox_t @var{mbx}, gid_t @var{gid})
Set the group to @var{gid}. If the Mailbox was not @code{mailbox_open}
the action is delayed until the stream is opened.
@end deftypefun
@deftypefun int mailbox_set_mode (mailbox_t @var{mbx}, mode_t @var{mode})
Set the file permission to @var{mode}. If the Mailbox was not
@code{mailbox_open} the action is delayed until the stream is opened.
@end deftypefun
@section Scanning
Scan is done implicitely on @code{mailbox_open}.
@deftypefun int mailbox_scan (mailbox_t @var{mbx}, size_t *@var{msgs})
The mailbox is parse and @var{msgs} if not NULL contain the message count.
A notification function can be set to monitor progress.
@end deftypefun
@comment @deftypefun int mailbox_scan_progress (mailbox_t @var{mbx}, int (*@var{progress}) (mailbox_t @var{mbx}, int @var{count}, void *@var{arg}), void *@var{arg})
@comment When doing @var{mailbox_scan}, function @var{progress}(@var{mbx}, @var{count},
@comment @var{arg}) is called for each new message.
@comment @end deftypefun
@deftypefun int mailbox_is_updated (mailbox_t @var{mbx})
Return 1 if @var{mbx} is up to date 0 otherwise.
@end deftypefun
@deftypefun int mailbox_size (mailbox_t @var{mbx}, offt_t *@var{size})
@var{size} is assign the mailbox total size.
@end deftypefun
@deftypefun int mailbox_get_size (mailbox_t @var{mbx}, size_t @var{msgno}, size_t *@var{header}, size_t *@var{body})
For message @var{msgno} set @var{header} size and @var{body} size.
@end deftypefun
@deftypefun int mailbox_count (mailbox_t @var{mbx})
Return the number of messages in @var{mbx}.
@end deftypefun
@section Timeout
On remote mailboxes it is sometimes possible to reset the timeout. On most
local mailbox it is a noop.
@deftypefun int mailbox_set_timeout (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@deftypefun int mailbox_get_timeout (mailbox_t @var{mbx}, size_t @var{millis})
Not Implemented.
@end deftypefun
@section Notifications
A number of callbacks are provided on the mailbox to monitor the changes.
Setting timeout and notifications.
@deftypefun int mailbox_set_refresh (mailbox_t @var{mbx}, size_t @var{millis})
Sets the refresh time on how often @code{mailbox_scan} should be called.
By default it is disabled. Not Implemented.
@end deftypefun
@deftypefun int mailbox_get_refresh (mailbox_t @var{mbx}, size_t @var{millis})
Return the refresh time. Not Implemented.
@end deftypefun
@deftypefun int mailbox_set_update_cb (mailbox_t @var{mbx}, int (*@var{notification}) (mailbox_t @var{mbx}, void *@var{arg}), void *@var{arg})
@code{mailbox_scan} can be called periodically to see if new messages have
arrived, if the number of total messages has changed the notification
function is called, @code{notification (mbx, arg)}. Not Implemented.
@end deftypefun
@deftypefun int mailbox_set_scan_cb (mailbox_t @var{mbx}, int (*@var{notification}) (int @var{msgcount}, void *@var{arg}))
When parsing the mailbox every count call @code{notification (msgcount, arg)}.
Note that all locks are held, and @var{notification} should be very small and
simple, it should not access or do any action on the mailbox doing this may
cause undefined behaviour.
@end deftypefun
@section Registration and Type
Mailbox_t comes with a certain number of builtin types, you can query them
or add you own to the list.
@deftp {Data type} struct mailbox_type
@example
@{
char *name;
int id;
struct url_type *utype;
int (*_init) __P ((mailbox_t *, const char *name));
void (*_destroy) __P ((mailbox_t *));
@};
@end example
@end deftp
@deftypefun int mailbox_list_type (struct mailbox_type *@var{mtype}, size_t @var{len}, size_t *@var{n})
The @var{mtype} array will be initialize with the list of builtin up to
@var{len}. The number of struct maiblox_type is put in @var{n}.
@end deftypefun
@deftypefun int mailbox_list_mtype (struct mailbox_type **@var{mtype}, size_t *@var{n})
An array of size @var{n} is @code{malloc(3)} to hold the builtin list.
@end deftypefun
@deftypefun int mailbox_add_type (struct mailbox_type *@var{mtype})
Add a mailbox @var{mtype} to the list of builtin.
@end deftypefun
@deftypefun int mailbox_remove_type (struct mailbox_type *@var{mtype})
Remove a mailbox @var{mtype} to the list of builtin.
@end deftypefun
@deftypefun int mailbox_get_type (struct mailbox_type **@var{mtype}, int @var{urlid})
Base on the URL @var{urlid} return the mailbox_type.
@end deftypefun
@deftypefun int mailbox_get_name_type (mailbox_t @var{mbx}, int *@var{mbxid}, char *@var{name}, size_t @var{len}, size_t *@var{n})
Return the name type of the mailbox identify by @var{mbxid},
in buffer @var{name} of size @var{len}. The number of byte is put in @var{n}.
@end deftypefun
@deftypefun int mailbox_get_mname_type(mailbox_t @var{mbx}, int *@var{mbxid}, char **@var{name}, size_t *@var{n})
Return the name type of the mailbox identify by @var{mbxid}, in
a @code{malloc(3)} buffer @var{name} of size @var{n}.
@end deftypefun
All mailbox implementations provide this minimum set of the API. By using
the registration new mailbox type can be added.
@example
#include <mailutils.h>
#include <ftp0.h>
#include <stdlib.h>
/* extern url_ftp_init (url_t *url, const char *name); in <ftp0.h> */
/* extern url_ftp_destroy (url_t *url, const char *name); in <ftp0.h> */
struct url_type url_ftp =
@{
"ftp://", 6, /* protocol and len */
"ftp://<user>:<passwd>@@<hostname>:<port>", /* help string */
(int)&url_ftp, /* need a uniq id */
url_ftp_init, url_ftp_destroy /* constructor and destructor */
@};
/* extern mailbox_unix_init (); in <ftp0.h> */
/* extern mailbox_unix_destroy (); in <ftp0.h> */
struct mailbox_type mbx_ftp =
@{
"FTP MBOX", /* name type */
(int)&mbx_ftp, /* need a uniq id */
&url_unix_type, /* url id */
mailbox_unix_init, /* constructor */
mailbox_unix_destroy /* destructor */
@};
int main ()
@{
struct mailbox_type *mtype;
size_t size=0, i;
mailbox_add_type (&mbx_ftp);
/* check if it is added */
mailbox_list_mtype (&mtype, &size)
for (i = 0; i < size; i++)
@{
puts (mtype[i].name)
puts (mtype[i].description)
@}
free(*mtype);
@dots{}
return 0;
@}
@end example
@section Unix Mbox
@cindex Unix Mbox
TODO: describe particularities :
locking policy, appending envelope, describe the flags use in _open(..), etc...
@section POP3 Mbox
@cindex POP3 Mbox
TODO: describe timeout policies, describe the flags use in _open(..),
describe different authorisation supported.
@section IMAP Mbox
@cindex IMAP Mbox
Not implemented.
@section QMail Mbox
@cindex QMail Mbox
Not implemented.
@section MMDF Mbox
@cindex MMDF Mbox
Not implemented.