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
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Mailbox API — Cyrus IMAP 3.12.1 documentation</title>
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/underscore.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Developer Thoughts & Notes" href="../thoughts.html" />
<link rel="prev" title="Index API" href="index-api.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home">
Cyrus IMAP
</a>
<div class="version">
3.12.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../setup.html">Setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../developers.html">Developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../contribute.html">We need your help</a></li>
<li class="toctree-l2"><a class="reference internal" href="../documentation.html">Contribute docs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer.html">Contribute code and tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cyrusworks.html">Cyrus.Works</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../../developers.html#cyrus-internals">Cyrus Internals</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../API.html">Cyrus APIs</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="cyrusdb.html">CyrusDB API</a></li>
<li class="toctree-l4"><a class="reference internal" href="cyrusdb2.html">cyrusdb API</a></li>
<li class="toctree-l4"><a class="reference internal" href="index-api.html">Index API</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">Mailbox API</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../thoughts.html">Thoughts & Notes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidance.html">Guidance for Developers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../developers.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">Cyrus IMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../../developers.html">Developers</a></li>
<li class="breadcrumb-item"><a href="../API.html">Developer APIs</a></li>
<li class="breadcrumb-item active">Mailbox API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/developer/API/mailbox-api.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<span class="target" id="imap-developer-api-mailbox"></span><section id="mailbox-api">
<h1>Mailbox API<a class="headerlink" href="#mailbox-api" title="Permalink to this heading"></a></h1>
<section id="intro">
<h2>Intro<a class="headerlink" href="#intro" title="Permalink to this heading"></a></h2>
<p>The Mailbox API is implemented in <code class="docutils literal notranslate"><span class="pre">imap/mailbox.h</span></code> and
<code class="docutils literal notranslate"><span class="pre">imap/mailbox.c</span></code>. It wraps the data structures of the
<code class="docutils literal notranslate"><span class="pre">cyrus.header</span></code>, <code class="docutils literal notranslate"><span class="pre">cyrus.index</span></code> and <code class="docutils literal notranslate"><span class="pre">cyrus.cache</span></code> files in a
psuedo-object-oriented way, allowing easy changes to the mailbox while
keeping the internal cached data structures consistent.</p>
</section>
<section id="opening-and-closing">
<h2>Opening and closing<a class="headerlink" href="#opening-and-closing" title="Permalink to this heading"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">mailbox</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
<span class="nb">int</span> <span class="n">r</span><span class="p">;</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">mboxname</span> <span class="o">=</span> <span class="s2">"user.brong"</span><span class="p">;</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_open_iwl</span><span class="p">(</span><span class="n">mboxname</span><span class="p">,</span> <span class="o">&</span><span class="n">mailbox</span><span class="p">);</span>
<span class="o">//</span> <span class="ow">or</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_open_irl</span><span class="p">(</span><span class="n">mboxname</span><span class="p">,</span> <span class="o">&</span><span class="n">mailbox</span><span class="p">);</span>
<span class="o">//</span> <span class="ow">or</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_open_exclusive</span><span class="p">(</span><span class="n">mboxname</span><span class="p">,</span> <span class="o">&</span><span class="n">mailbox</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">r</span><span class="p">)</span> <span class="k">return</span> <span class="n">r</span><span class="p">;</span>
<span class="n">do_stuff</span><span class="p">(</span><span class="n">mailbox</span><span class="p">);</span>
<span class="n">mailbox_close</span><span class="p">(</span><span class="o">&</span><span class="n">mailbox</span><span class="p">);</span>
</pre></div>
</div>
<p>It is always necessary to obtain an index lock when opening a mailbox,
because the index header read must be consistent. The locks are as
follows:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Function</p></th>
<th class="head"><p>Namelock</p></th>
<th class="head"><p>Index Lock</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>mailbox_open_iwl</p></td>
<td><p>Shared</p></td>
<td><p>Exclusive</p></td>
</tr>
<tr class="row-odd"><td><p>mailbox_open_irl</p></td>
<td><p>Shared</p></td>
<td><p>Shared</p></td>
</tr>
<tr class="row-even"><td><p>mailbox_open_exclusive</p></td>
<td><p>Exclusive</p></td>
<td><p>Exclusive</p></td>
</tr>
</tbody>
</table>
<p>It should never be necessary to call <code class="docutils literal notranslate"><span class="pre">mailbox_open_exclusive</span></code>, but
it's included for completeness. Use <code class="docutils literal notranslate"><span class="pre">mailbox_open_iwl</span></code> if you expect
to need to write to the index (or even if you're not sure) and
<code class="docutils literal notranslate"><span class="pre">mailbox_open_irl</span></code> when you know you're only reading from the file and
wish to allow other readers to work concurrently.</p>
<p>Many actions are delayed until the mailbox is closed, or even until the
<em>last</em> mailbox is closed for things that require an exclusive namelock
to perform like deletion or repack. See below under "delayed actions"
for more detail.</p>
<p>To avoid opening the same file multiple times, the mailbox API refcounts
open mailboxes. If you open the same mailbox again (i.e. a URL fetch or
status command on the currently select mailbox) then the same mailbox
will be returned. It must be unlocked (see below or the open command
will return IMAP_MAILBOX_LOCKED). The matching close will reduce the
refcount, and only the final close will do the cleanup actions.</p>
</section>
<section id="locking-and-unlocking">
<h2>Locking and unlocking<a class="headerlink" href="#locking-and-unlocking" title="Permalink to this heading"></a></h2>
<p>You can keep a mailbox "open", maintaining the namelock, while releasing
the index lock to allow other processes to make changes to the mailbox.
By holding the namelock, you know that record numbers won't change, and
the underlying message files won't be deleted.</p>
<p><code class="docutils literal notranslate"><span class="pre">mailbox_close</span></code> will call <code class="docutils literal notranslate"><span class="pre">mailbox_unlock_index</span></code> if the index is
still locked, so it is not necessary to explicitly unlock the index
before closing.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_unlock_index</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
<span class="o">//</span> <span class="n">sleep</span> <span class="n">on</span> <span class="n">user</span> <span class="nb">input</span><span class="o">...</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_lock_index</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">LOCK_SHARED</span><span class="p">);</span>
<span class="o">//</span> <span class="ow">or</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">mailbox_lock_index</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">LOCK_EXCLUSIVE</span><span class="p">);</span>
</pre></div>
</div>
<p>For example, <code class="docutils literal notranslate"><span class="pre">mailbox_unlock_index</span></code> and <code class="docutils literal notranslate"><span class="pre">mailbox_lock_index</span></code> are
used extensively by the index module, allowing an imap client to
maintain a long lived connection selected to a mailbox and know that
messages won't magically disappear from under it - yet at the same time
allow new mail delivery to happen or other imap connections to query the
mailbox.</p>
<p>If you have built an accurate statuscache item for the locked mailbox,
you can pass this as the second parameter to mailbox_index_unlock. If
there have been any changes, mailbox_index_unlock will invalidated the
statuscache. If you give it the new value, then it will store that value
instead. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>struct statusdata sdata;
index_status(state, &sdata);
/* RECENT is zero for everyone else because we wrote a new
* recentuid! */
sdata.recent = 0;
mailbox_unlock_index(state->mailbox, &sdata);
</pre></div>
</div>
<p>See "delayed actions" below for delayed actions performed during an
unlock.</p>
</section>
<section id="creating-renaming-and-deleting">
<h2>Creating, renaming and deleting<a class="headerlink" href="#creating-renaming-and-deleting" title="Permalink to this heading"></a></h2>
<p><strong>WARNING:</strong> These functions only change the mailbox files on disk. They
don't update the mailboxes.db records or contact murder servers. In most
cases you are probably looking for the <code class="docutils literal notranslate"><span class="pre">mboxlist_</span></code> functions instead.</p>
<p>Creating a mailbox is somewhat longwinded - as there are many optional
parameters.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">mailbox_create</span><span class="p">(</span><span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">name</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">part</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">acl</span><span class="p">,</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">uniqueid</span><span class="p">,</span> <span class="nb">int</span> <span class="n">options</span><span class="p">,</span> <span class="n">unsigned</span> <span class="n">uidvalidity</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">mailbox</span> <span class="o">**</span><span class="n">mailboxptr</span><span class="p">);</span>
</pre></div>
</div>
<p>Most interesting to note is that on success, <code class="docutils literal notranslate"><span class="pre">mailboxptr</span></code> will contain
the same mailbox that <code class="docutils literal notranslate"><span class="pre">mailbox_open_exclusive</span></code> above would have
returned, with an exclusive namelock and an exclusive index lock. This
allows you to perform other consistency operations after creating the
mailbox with a full guarantee that no other process will even be able to
know of the mailbox's existence! You can still roll-back by deleting the
mailbox and the next process will get the namelock and see no mailbox
with that name.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">mailbox_rename_copy</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">oldmailbox</span><span class="p">,</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">newname</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">newpart</span><span class="p">,</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">userid</span><span class="p">,</span> <span class="nb">int</span> <span class="n">ignorequota</span><span class="p">,</span>
<span class="nb">int</span> <span class="n">silent</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">mailbox</span> <span class="o">**</span><span class="n">newmailboxptr</span><span class="p">);</span>
</pre></div>
</div>
<p>Very similar to mailbox_create - the new mailbox is created with an
exclusive name lock and returned. The old mailbox must be passed in with
an <strong>exclusive index lock</strong> but is fine with a shared namelock, as it
will be passed to <code class="docutils literal notranslate"><span class="pre">mailbox_delete</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">mailbox_delete</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">**</span><span class="n">mailboxptr</span><span class="p">);</span>
</pre></div>
</div>
<p>Just like <code class="docutils literal notranslate"><span class="pre">mailbox_close</span></code> above, this closes the mailbox. Before it
does so, it sets the OPT_MAILBOX_DELETED option flag in the index
header. The interesting work is actually done in <code class="docutils literal notranslate"><span class="pre">mailbox_close</span></code>. See
below under "delayed actions".</p>
<p><code class="docutils literal notranslate"><span class="pre">mailbox_delete</span></code> requires an exclusive index lock, but can complete
quite happily with only a shared namelock.</p>
</section>
<section id="reading-and-writing-records">
<h2>Reading and writing records<a class="headerlink" href="#reading-and-writing-records" title="Permalink to this heading"></a></h2>
<p>Ok - so you have a mailbox, it's opened, and the index is locked. Time
to start reading and writing some records!</p>
<p>At the mailbox level there is no concept of "message numbers" from imap,
only "record numbers". The canonical variable name to refer to record
numbers is <code class="docutils literal notranslate"><span class="pre">recno</span></code>. All records are read and written using
<code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">index_record</span></code> values.</p>
<p>Here at the API definitions used for reading and writing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">mailbox_read_index_record</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">mailbox</span><span class="p">,</span>
<span class="n">uint32_t</span> <span class="n">recno</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">);</span>
<span class="nb">int</span> <span class="n">mailbox_rewrite_index_record</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">mailbox</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">);</span>
<span class="nb">int</span> <span class="n">mailbox_append_index_record</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">mailbox</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">);</span>
<span class="nb">int</span> <span class="n">mailbox_commit</span><span class="p">(</span><span class="n">mailbox</span><span class="p">);</span>
</pre></div>
</div>
<p>An example of iterating through a mailbox</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">uint32_t</span> <span class="n">recno</span><span class="p">;</span>
<span class="n">struct</span> <span class="n">index_record</span> <span class="n">record</span><span class="p">;</span>
<span class="nb">int</span> <span class="n">make_changes</span><span class="p">;</span>
<span class="o">/*</span> <span class="n">DEPRECATED</span> <span class="o">*/</span>
<span class="k">for</span> <span class="p">(</span><span class="n">recno</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="n">recno</span> <span class="o"><=</span> <span class="n">mailbox</span><span class="o">-></span><span class="n">i</span><span class="o">.</span><span class="n">num_records</span><span class="p">;</span> <span class="n">recno</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">mailbox_read_index_record</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">recno</span><span class="p">,</span> <span class="o">&</span><span class="n">record</span><span class="p">))</span>
<span class="n">fatal</span><span class="p">(</span><span class="s2">"invalid record"</span><span class="p">,</span> <span class="n">EX_SOFTWARE</span><span class="p">);</span> <span class="o">//</span> <span class="ow">or</span> <span class="k">return</span> <span class="n">an</span> <span class="n">error</span>
<span class="k">if</span> <span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">internal_flags</span> <span class="o">&</span> <span class="n">FLAG_INTERNAL_EXPUNGED</span><span class="p">)</span>
<span class="k">continue</span><span class="p">;</span> <span class="o">//</span> <span class="n">skip</span> <span class="n">expunged</span> <span class="n">records</span>
<span class="n">make_changes</span> <span class="o">=</span> <span class="n">do_stuff</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="o">&</span><span class="n">record</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">make_changes</span><span class="p">)</span>
<span class="n">mailbox_rewrite_index_record</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="o">&</span><span class="n">record</span><span class="p">);</span>
<span class="p">}</span>
<span class="o">/*</span> <span class="n">the</span> <span class="n">new</span> <span class="n">way</span> <span class="o">*/</span>
<span class="nb">int</span> <span class="n">make_change</span><span class="p">;</span>
<span class="n">const</span> <span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">;</span>
<span class="n">struct</span> <span class="n">mailbox_iter</span> <span class="o">*</span><span class="nb">iter</span><span class="p">;</span>
<span class="nb">iter</span> <span class="o">=</span> <span class="n">mailbox_iter_init</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">ITER_SKIP_EXPUNGED</span><span class="p">);</span>
<span class="k">while</span> <span class="p">((</span><span class="n">record</span> <span class="o">=</span> <span class="n">mailbox_iter_step</span><span class="p">(</span><span class="nb">iter</span><span class="p">)))</span> <span class="p">{</span>
<span class="n">make_changes</span> <span class="o">=</span> <span class="n">do_stuff</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">record</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">make_changes</span><span class="p">)</span>
<span class="n">mailbox_rewrite_index_record</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">record</span><span class="p">);</span>
<span class="p">}</span>
<span class="n">mailbox_iter_done</span><span class="p">(</span><span class="o">&</span><span class="nb">iter</span><span class="p">);</span>
</pre></div>
</div>
<p>NOTE: <code class="docutils literal notranslate"><span class="pre">mailbox_rewrite_index_record</span></code> doesn't need a recno, as that's
cached inside the index_record struct.</p>
<p>NOTE: You need an exclusively locked index to use rewrite or append, but
only a shared index lock to use read.</p>
<p>There are a range of consistency checks done to ensure that a rewrite
doesn't violate IMAP semantics (an expunged message can never be
unexpunged, UIDs can't change, etc) and the internal tracking counts and
quota data are updated as well. They will be committed at unlock time,
see "delayed actions"</p>
<p>If you don't set the <code class="docutils literal notranslate"><span class="pre">record.silent</span></code> field to a true value before
rewriting or appending, the <code class="docutils literal notranslate"><span class="pre">record.modseq</span></code> and
<code class="docutils literal notranslate"><span class="pre">record.last_updated</span></code> values will be changed. This allows condstore to
work correctly.</p>
<section id="appending">
<h3>Appending<a class="headerlink" href="#appending" title="Permalink to this heading"></a></h3>
<p>To append a record, the file must have already been copied into place
(XXX - plan to move to a stage based system where the mailbox API
handles the staging, but that's not finished yet) and been parsed into
the record struct. The UID must be set already, and must be greater than
the UID of any existing record in the mailbox. There are a range of
consistency checks done.</p>
<p>The internal consistency counts are updated by append as well.</p>
</section>
<section id="committing">
<h3>Committing<a class="headerlink" href="#committing" title="Permalink to this heading"></a></h3>
<p>When you have finished making any changes, you need to "commit". This
will write the updated values for any index header fields, rewite the
<code class="docutils literal notranslate"><span class="pre">cyrus.header</span></code> file if needed and fsync all changes to disk.</p>
<p>It is a fatal error to unlock (or close) a mailbox that has had changes
without committing, as it can leave the mailbox in a corrupted state.</p>
</section>
<section id="cache-records">
<h3>Cache records<a class="headerlink" href="#cache-records" title="Permalink to this heading"></a></h3>
<p>Cache records are accessed through <code class="docutils literal notranslate"><span class="pre">record.crec</span></code> which is not filled
by read_index_record. The cache file is only read and mapped into
memory as needed, so you if you want to access cache records, the basic
API is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">int</span> <span class="n">mailbox_cacherecord</span><span class="p">(</span><span class="n">struct</span> <span class="n">mailbox</span> <span class="o">*</span><span class="n">mailbox</span><span class="p">,</span>
<span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">);</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">cacheitem_base</span><span class="p">(</span><span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">,</span> <span class="nb">int</span> <span class="n">field</span><span class="p">);</span>
<span class="n">unsigned</span> <span class="n">cacheitem_size</span><span class="p">(</span><span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">,</span> <span class="nb">int</span> <span class="n">field</span><span class="p">);</span>
<span class="n">struct</span> <span class="n">buf</span> <span class="o">*</span><span class="n">cacheitem_buf</span><span class="p">(</span><span class="n">struct</span> <span class="n">index_record</span> <span class="o">*</span><span class="n">record</span><span class="p">,</span> <span class="nb">int</span> <span class="n">field</span><span class="p">);</span>
</pre></div>
</div>
<p>You must always call <code class="docutils literal notranslate"><span class="pre">mailbox_cacherecord</span></code> on a record before trying
to access any of the cache items. "<code class="docutils literal notranslate"><span class="pre">field</span></code>" above is the individual
field (there are 10) in the cache record. There's more information on
those fields in the mailbox internal format documentation.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">recno</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="n">recno</span> <span class="o"><=</span> <span class="n">mailbox</span><span class="o">-></span><span class="n">i</span><span class="o">.</span><span class="n">num_records</span><span class="p">;</span> <span class="n">recno</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">mailbox_read_index_record</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="n">recno</span><span class="p">,</span> <span class="o">&</span><span class="n">record</span><span class="p">))</span>
<span class="n">fatal</span><span class="p">(</span><span class="s2">"invalid record"</span><span class="p">,</span> <span class="n">EX_SOFTWARE</span><span class="p">);</span> <span class="o">//</span> <span class="ow">or</span> <span class="k">return</span> <span class="n">an</span> <span class="n">error</span>
<span class="k">if</span> <span class="p">(</span><span class="n">record</span><span class="o">.</span><span class="n">internal_flags</span> <span class="o">&</span> <span class="n">FLAG_INTERNAL_EXPUNGED</span><span class="p">)</span>
<span class="k">continue</span><span class="p">;</span> <span class="o">//</span> <span class="n">skip</span> <span class="n">expunged</span> <span class="n">records</span>
<span class="k">if</span> <span class="p">(</span><span class="n">mailbox_cacherecord</span><span class="p">(</span><span class="n">mailbox</span><span class="p">,</span> <span class="o">&</span><span class="n">record</span><span class="p">))</span>
<span class="n">fatal</span><span class="p">(</span><span class="s2">"failed to read cache"</span><span class="p">,</span> <span class="n">EX_SOFTWARE</span><span class="p">);</span>
<span class="o">...</span>
<span class="n">envelope_length</span> <span class="o">=</span> <span class="n">cacheitem_size</span><span class="p">(</span><span class="o">&</span><span class="n">record</span><span class="p">,</span> <span class="n">CACHE_ENVELOPE</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <code class="docutils literal notranslate"><span class="pre">imap/mailbox.h</span></code> for the full list of constants.</p>
</section>
</section>
<section id="delayed-actions">
<h2>Delayed Actions<a class="headerlink" href="#delayed-actions" title="Permalink to this heading"></a></h2>
<p>Here's the bit you've been waiting for! What happens during unlock and
close</p>
<section id="first-unlock">
<h3>first, unlock<a class="headerlink" href="#first-unlock" title="Permalink to this heading"></a></h3>
<p>Anything that makes any changes sets the mailbox->has_changed flag. If
this is set, then before the index gets unlocked:</p>
<ul class="simple">
<li><p>the updatenotifier (idle) is called</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sync_log_mailbox</span></code> (replication) gets called</p></li>
<li><p>the statuscache value gets erased (or replaced if you passed in an
updated value).</p></li>
</ul>
</section>
<section id="then-close">
<h3>then: close<a class="headerlink" href="#then-close" title="Permalink to this heading"></a></h3>
<p>next the index is unlocked (see above)</p>
<p>third, any "unlink" commands scheduled for email files are run. These
can't be done until after the mailbox_commit to ensure consistency -
the file isn't deleted until the record is written as unlinked! But we
save the unlink until now so that other tasks aren't waiting for the
index lock while the unlinks run. Unlink is expensive in IO and time.</p>
<p>finally we check for MAILBOX_NEEDS_REPACK or MAILBOX_DELETED option
flags. If either is sets, then we make a non-blocking attempt to get an
exclusive namelock. If the non-blocking attempt fails, then another
process has the mailbox open, so save the cleanup for them! If it
succeeds, then go ahead with either <code class="docutils literal notranslate"><span class="pre">mailbox_delete_cleanup</span></code> or
<code class="docutils literal notranslate"><span class="pre">mailbox_index_repack</span></code> as appropriate.</p>
<p>After this it's just a matter of releasing malloc'd memory and finally
releasing the name lock.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index-api.html" class="btn btn-neutral float-left" title="Index API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../thoughts.html" class="btn btn-neutral float-right" title="Developer Thoughts & Notes" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1993–2025, The Cyrus Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
