| 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 |