summaryrefslogtreecommitdiff
path: root/doc/texinfo/mbox.texi
blob: 0a631640e3f6afb7cc57042529c4afd6e4f37a64 (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
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004,2006,
@c 2007 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

@smallexample
@code{/* Prefix @emph{mu_mbox_} is reserved */}
@code{#include <mailutils/mbox.h>}

@end smallexample

The most common mailbox format on UNIX platform is @emph{mbox}. Mbox is a
text file that contains messages separated by a special format string.

@smallexample
From SP envelope-sender SP date [SP moreinfo]
@end smallexample

@table @code
@item "From "
 is sometimes call the @emph{From_}.
@item  envelope-sender
 is a word with no space.
@item date
 has the same format as @code{asctime ()}
@item moreinfo
 are optional values that are seldom used.
@end table

A @var{mu_mbox_t} is created, initialized and destroyed by @code{mu_mbox_create ()}
and @code{mu_mbox_destroy ()}. When opening, @code{mu_mbox_open ()} will do a quick
check to see if the format is a valid format or an empty file. The scanning
of the mailbox is done by @code{mu_mbox_scan ()}, the function, takes callback
functions called during the scanning to provide information on progress and
new messages found. The scanning will cache some of the headers fields for
speed, new fields could be add with @code{mu_mbox_add_hcache ()}. On Closing
the @var{mu_mbox_t}, @code{mu_mbox_close ()} will free any resources like, headers
cache, locks etc ... The messages with attributes marked deleted will only
be removed on @code{mu_mbox_expunge ()}, if there is a need to save the
modification without purging @code{mu_mbox_save ()} is more appropriate.
New messages are added to the mbox with @code{mu_mbox_append ()}.
Attributes are saved in the @emph{Status:} header
field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.

@subsubsection Initialization
@cindex Mbox Initialization

@deftypefun int mu_mbox_create (mu_mbox_t *@var{mbox})

Allocate and initialize a @var{mbox} handle.

@table @code
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun void mu_mbox_destroy (mu_mbox_t @var{mbox})

When a POP3 session is finished, the structure must be @code{free ()}'ed to
reclaim memory.
@end deftypefun

@subsubsection Carrier
@cindex Mbox channel

@deftypefun int mu_mbox_set_carrier (mu_mbox_t, stream_t @var{carrier});

Another type of stream can be provided, the @var{carrier}
is set in the @var{mu_mbox_t} handle. Any  previous @var{carrier} stream in
the handle, will be close and destroy. Since the parsing code
maintain only the offsets off the message the @var{carrier} stream must be
seekable.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_get_carrier (mu_mbox_t, stream_t *@var{carrier});

Return the @var{mu_mbox_t} carrier. If none was set, a new file stream will be
created.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_open (mu_mbox_t, const char *@var{filename}, int @var{flags})

Open carrier stream with @var{filename} and @var{flags}. The stream will be
quickly examine to see if it is a mbox format.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_NO_ENTRY
@item MU_ERROR_NO_ACCESS
@item MU_ERROR_NOT_SUPPORTED
@end table
@end deftypefun

@deftypefun int mu_mbox_close (mu_mbox_t)

Close the carrier stream and resources particular to the mailbox.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_uidnext (mu_mbox_t, unsigned long *@var{uidnext})

Return the uidnext, if the @var{mu_mbox_t} was not scan @code{mu_mbox_scan ()}
is called first.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item same as @code{mu_mbox_scan ()}
@end table
@end deftypefun

@deftypefun int mu_mbox_uidvalidity (mu_mbox_t, unsigned long *@var{uidvalidity})

Return the uidvalidity, if the @var{mu_mbox_t} was not scan @code{mu_mbox_scan ()}
is called first.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item same as @code{mu_mbox_scan ()}
@end table
@end deftypefun

@deftypefun int mu_mbox_get_uid (mu_mbox_t, unsigned int @var{msgno}, unsigned long *@var{uid})

Return the @var{uid} of the message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_get_attribute (mu_mbox_t, unsigned int @var{msgno}, attribute_t *@var{attribute})

Return an @var{attribute} to indicate the status of message number @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_get_separator (mu_mbox_t, unsigned int @var{msgno}, char **@var{sep})

Return an allocated string in @var{sep} containing the value "From " separating
each message in Unix mbox format. The string should be @code{free ()}ed by
the caller.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_set_separator (mu_mbox_t, unsigned int @var{msgno}, const char *@var{sep})

The variable @var{sep} should contain a valid "From " separator that will be use
when the expunging.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_get_hstream (mu_mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})

Return a @var{stream} to read the header of message @var{msgno}. The
@var{stream} should be destroy after usage.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_set_hstream (mu_mbox_t, unsigned int @var{msgno}, stream_t @var{stream})

Use @var{stream} when expunging for message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_hsize (mu_mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the @var{size} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_hlines (mu_mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the number of @var{lines} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_get_bstream (mu_mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})

Return a @var{stream} to read the body of message @var{msgno}. The
@var{stream} should be destroy after usage.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_set_bstream (mu_mbox_t, unsigned int @var{msgno}, stream_t @var{stream})

Use @var{stream} when expunging for message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_bsize (mu_mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the @var{size} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_blines (mu_mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})

Return the number of @var{lines} of message @var{msgno}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_get_size (mu_mbox_t, unsigned int *@var{size})

Return the @var{size} of mailbox.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_hcache (mu_mbox_t, const char **@var{array}, size_t @var{len})

Set the @var{array} of fields as the header to cache when doing the scanning.
If @var{array} is NULL the header cache is emptied.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_add_hcache (mu_mbox_t, const char **@var{array}, size_t @var{len})

Add to the current cache for the scan, the fields in @var{array}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_value_hcache (mu_mbox_t, unsigned int @var{msgno}, const char *@var{field}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})

Get the value of @var{field} in the header cache for @var{msgno}. The
result is copied in a @var{buffer} of @var{buflen} and @var{writen} is set
to the number of byte put in @var{buffer}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_ENTRY
@end table
@end deftypefun

@deftypefun int mu_mbox_save (mu_mbox_t)

Save the changes to the messages back to the mailbox, but do not
remove messages mark for deletion in the process.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_expunge (mu_mbox_t)

Save the changes to the mailbox and in the process remove all messages
marked for deletion.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_append (mu_mbox_t, const char *@var{sep}, stream_t @var{stream})

Append to the mailbox an rfc822 message represented by @var{stream}.
The variable @var{sep} should contain a valid "From " separator or
NULL to get the default.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_append_hb (mu_mbox_t, const char *@var{sep}, stream_t @var{hstream}, stream_t @var{bstream})

Append to the mailbox an rfc822 message represented by a header, @var{hstream},
and a body, @var{bstream}. The variable @var{sep} should contain a valid
"From " separator or NULL to get the default.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_scan (mu_mbox_t, unsigned int @var{start}, unsigned int *@var{count})

Start scanning the mailbox for new messages. The variable @var{start} can be
a message number starting point. The result of the scanning will be in
@var{count}. The scanning will trigger the @code{mu_mbox_newmsg_cb()} callback
for each new message and @code{mu_mbox_progress_cb ()} at different interval
to notify progression. The return values of the those callback should be
0 is different then 0 the scanning will be stop an the function returns
MU_ERROR_INTERRUPTED.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_INTERRUPTED
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@deftypefun int mu_mbox_count (mu_mbox_t, unsigned int *@var{count})

Same as @code{mu_mbox_scan ()} but does not call the callbacks.

@end deftypefun
@deftypefun int mu_mbox_set_progress_cb (mu_mbox_t, int (*@var{callback}) (int @var{percentage}, void *)), void *@var{arg})

Set the callback function for progress. The variable @var{arg} will be pass
back in the callback as the second argument. The first argument of the
callback represents a @var{percentage} of the scanning progress.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_newmsg_cb (mu_mbox_t, int (*@var{callback}) (int @var{count}, void *)), void *@var{arg})

Set the callback function for new messages. The variable @var{arg} will be
pass back in the callback as the second argument. The  first argument
is the total of messages found.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int mu_mbox_set_error_cb (mu_mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})

Set the callback function for errors. The variable @var{arg} will be
pass back in the callback as the second argument.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun
@deftypefun int  mu_mbox_has_newmail (mu_mbox_t)

Return nonzero if there is new mail append to the mu_mbox_t.
@end deftypefun

Return to:

Send suggestions and report system problems to the System administrator.