summaryrefslogtreecommitdiff
path: root/doc/texinfo/mailbox.texi
blob: 7da37c7f85ce9aa731559810823874d7284dd18a (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
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999-2004, 2006-2007, 2010-2012, 2014-2017 Free
@c Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

@smallexample
@code{/* Prefix @emph{mu_mailbox_} is reserved. */}
@code{#include <mailutils/mailbox.h>}
@end smallexample

@deftp {Data Type} mu_mailbox_t
The @code{mu_mailbox_t} object is used to hold information and it is an opaque
data structure to the user. Functions are provided to retrieve information
from the data structure.
@end deftp

@smallexample
@group
                             mu_mailbox_t               mu_url_t
  -/var/mail-    +---//--->/------------------\   +-->/-----------\
 (  alain   )    |         |  mu_url_t      *-|---+   |  port     |
  ----------     |         |------------------+       |  hostname |
 (  jakob *-)----+         |  mu_observer_t *-|       |  file     |
  ----------               |------------------+       |  ...      |
 (  jeff    )              |  mu_stream_t     |       \-----------/
  ----------               |------------------|
 (  sean    )              |  mu_locker_t     |
  ----------               |------------------|
                           |  mu_message_t(1) |
                           |------------------|
                           |  mu_message_t(2) |
                           |  ......          |
                           |  mu_message_t(n) |
                           \------------------/
@end group
@end smallexample

@c
@c Constructor/destructor and possible types.
@c

@deftypefun  int mu_mailbox_create (mu_mailbox_t *@var{mbox}, const char *@var{name})
The function @code{mu_mailbox_create} allocates and initializes @var{mbox}.
The concrete mailbox type instantiate is based on the scheme of the url @var{name}.

The return value is @code{0} on success and a code number on error conditions:
@table @code

@item MU_ERR_OUT_PTR_NULL
The pointer @var{mbox} supplied is @code{NULL}.
@item MU_ERR_NO_HANDLER
The url @var{name} supplied is invalid or not supported.
@item EINVAL
@item ENOMEM
Not enough memory to allocate resources.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_create_default (mu_mailbox_t *@var{mbox}, const char *@var{name})
Create a mailbox with @code{mu_mailbox_create()} based on the environment
variable @env{MAIL} or the string formed by
@emph{_PATH_MAILDIR}/@var{user}" or @env{LOGNAME} if @var{user} is null,
@end deftypefun

@deftypefun  void mu_mailbox_destroy (mu_mailbox_t *@var{mbox})
Destroys and releases resources held by @var{mbox}.
@end deftypefun

@deftypefun  int mu_mailbox_open (mu_mailbox_t @var{mbox}, int @var{flag})
A connection is open, if no stream was provided, a stream
is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
See @code{stream_create()} for @var{flag}'s description.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EAGAIN
@itemx EINPROGRESS
Operation in progress.
@item EBUSY
Resource busy.
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL} or flag is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_close (mu_mailbox_t @var{mbox})
The stream attach to @var{mbox} is closed.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_flush (mu_mailbox_t @var{mbox}, int @var{expunge})
@end deftypefun

@deftypefun  int mu_mailbox_get_folder (mu_mailbox_t @var{mbox}, folder_t *@var{folder})
Get the @var{folder}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_folder (mu_mailbox_t @var{mbox}, mu_folder_t @var{folder})
@end deftypefun

@deftypefun  int mu_mailbox_uidvalidity (mu_mailbox_t @var{mbox}, unsigned long *@var{number});
Give the uid validity of @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_uidnext (mu_mailbox_t @var{mbox}, size_t *@var{number});
Give the next predicted uid for @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@c
@c Messages.
@c

@deftypefun  int mu_mailbox_get_message (mu_mailbox_t @var{mbox}, size_t @var{msgno}, mu_message_t *@var{message})
Retrieve message number @var{msgno}, @var{message} is allocated and
initialized.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL} or @var{msgno} is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_append_message (mu_mailbox_t @var{mbox}, mu_message_t @var{message})
The @var{message} is appended to the mailbox @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL} or @var{message} is invalid.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_messages_count (mu_mailbox_t @var{mbox}, size_t *@var{number});
Give the number of messages in @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_messages_recent (mu_mailbox_t @var{mbox}, size_t *@var{number});
Give the number of recent messages in @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_message_unseen (mu_mailbox_t @var{mbox}, size_t *@var{number});
Give the number of first unseen message in @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_expunge (mu_mailbox_t @var{mbox})
All messages marked for deletion are removed.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_save_attributes (mu_mailbox_t @var{mbox})
@end deftypefun

@c
@c Update and Scanning.
@c

@deftypefun  int mu_mailbox_get_size (mu_mailbox_t @var{mbox}, mu_off_t *@var{size})
Gives the @var{mbox} size.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_is_updated (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_scan (mu_mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{count});
Scan the mailbox for new messages starting at message @var{msgno}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@c
@c Mailbox Stream.
@c

@deftypefun  int mu_mailbox_get_stream (mu_mailbox_t @var{mbox}, mu_stream_t *@var{stream})
The mailbox stream is put in @var{stream}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is invalid or @var{stream} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_stream (mu_mailbox_t @var{mbox}, mu_stream_t @var{stream})
Set the @var{stream} connection to use for the mailbox.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} or @var{stream} is @code{NULL}.
@end table
@end deftypefun

@c
@c Lock Settings.
@c

@deftypefun  int mu_mailbox_get_locker (mu_mailbox_t @var{mbox}, mu_locker_t *@var{locker})
Get the @var{mu_locker_t} object.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_locker (mu_mailbox_t @var{mbox}, mu_locker_t @var{locker})
Set the type of locking done by the @var{mbox}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@c
@c Property.
@c

@deftypefun  int mu_mailbox_get_property (mu_mailbox_t @var{mbox}, mu_property_t *@var{property})
Get the property object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@item ENOMEM
@end table
@end deftypefun

@c
@c URL.
@c

@deftypefun  int mu_mailbox_get_url (mu_mailbox_t @var{mbox}, mu_url_t *@var{url})
Gives the constructed @var{url}.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@end table
@end deftypefun

@c
@c Debug.
@c

@deftypefun  int mu_mailbox_has_debug (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_get_debug (mu_mailbox_t @var{mbox}, mu_debug_t *@var{debug})
Get a debug object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@item ENOMEM
@end table
@end deftypefun

@deftypefun  int mu_mailbox_set_debug (mu_mailbox_t @var{mbox}, mu_debug_t @var{debug})
@end deftypefun

@c
@c Events.
@c

@deftypefun  int mu_mailbox_get_observable (mu_mailbox_t mbox @var{mbox}, mu_observable_t *@var{observable})
Get the observable object.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun

@c
@c Locking
@c

@deftypefun  int mu_mailbox_lock (mu_mailbox_t @var{mbox})
@end deftypefun

@deftypefun  int mu_mailbox_unlock (mu_mailbox_t @var{mbox})
@end deftypefun

Return to:

Send suggestions and report system problems to the System administrator.