Debian Codegraph @

doc/html/_sources/imap/developer/API/index-api.rst.txt

raw
1 .. _imap-developer-api-index:
2
3 .. Note: This document was converted from the original by Nic Bernstein
4 (Onlight). Any formatting mistakes are my fault and not the
5 original author's. Converted via the pandoc tool from HTML.
6
7 Index API
8 =========
9
10 Intro
11 -----
12
13 The Index API is implemented in ``imap/index.h`` and ``imap/index.c``.
14 It provides a snapshot view into the underlying mailbox (see `the
15 Mailbox API documentation <mailbox-api.html>`) which obeys IMAP
16 semantics, as well as all the searching and sorting logic.
17
18 Opening and closing
19 -------------------
20
21 ::
22
23 struct index_state *state = NULL;
24 struct index_init init;
25 int r;
26 const char *mboxname = "user.brong";
27
28 memset(&init, 0, sizeof(struct index_init));
29 init.userid = imapd_userid;
30 init.authstate = imapd_authstate;
31 init.out = imapd_out;
32
33 r = index_open(mboxname, &init, &state);
34 if (r) return r;
35
36 do_stuff(state);
37
38 index_close(&state);
39
40 The ``index_init`` interface sucks. So does passing lots of parameters.
41 For now, this will do! Just pass NULL if you're only reading, or use the
42 code already in imapd and you'll be fine.
43
44 The Index Model
45 ---------------
46
47 Ok - I think a few words about the index model and how it differs from
48 direct mailbox access are needed! In the past, index.c used pointers
49 directly into the mmaped ``cyrus.index`` file and maintained the old
50 mmaped copy if an expunge took place. Under the namelock regime, this is
51 no longer required because namelocks will avoid the file being
52 re-written.
53
54 Also, memory is now cheap. Rather than using locks to ensure
55 consistency, we just keep a copy of the ``struct index_record`` for even
56 message in the index, stored in memory. Since these are about 100 bytes
57 each, a 1 million email mailbox will take rougly 100Mb of memory. That's
58 not too bad on a modern server, and that's a **huge** mailbox.
59
60 So - the model works like this:
61
62 - Create the index state or re-lock (``index_lock``) the mailbox on an
63 existing index.
64 - call ``index_refresh``
65 - if any changes are to be made (i.e. flag updates for a store,
66 non-peek body fetch, expunge) then cycle through the refreshed state
67 map and update the records which are affected.
68 - call ``index_unlock`` (unlock the underlying mailbox and commit the
69 statuscache changes)
70
71 At this point the index lock is **released** and we have not yet
72 generated any network traffic. Now start generating the response.
73
74 - if expunges are allowed, call ``index_tellexpunge``
75 - call ``index_tellchanges`` to tell about all other changes
76 - return any response that the command itself required