understanding fields in cyrus.header file

[Bron Gondwana]

On Wed, Feb 10, 2010 at 12:00:04AM +0000, Gavin McCullagh wrote:
> Hi,
> 
> On Wed, 10 Feb 2010, Bron Gondwana wrote:
> 
> > <user-flags>
> > > Junk NonJunk $Forwarded Old
> > 
> > Check out mailbox_read_header and mailbox_read_header_acl from
> > imap/mailbox.c in the source code if you want a more detailed
> > answer (in C!)
> 
> I guess I'd better do that as while I could guess the rest, I don't
> understand what the user-flags mean.  On the plus side, I'm starting to
> think I won't need to do any translation of them, which is the main thing
> for me.

Ok - here's a quick primer on user flags :) (from memory - any mistakes
are my own!)

You can set flags on messages in IMAP.  In fact, it's the only thing you
CAN change on a message after it's been appended to a mailbox!  You use
the IMAP "STORE" operation to change the flags.

There are two types of flags - system flags, which are defined in the spec.
\Answered, \Flagged, \Seen (this one is somewhat special in Cyrus because
it's stored per user), \Recent (this is special in ALL IMAP servers - it's
a readonly flag), \Deleted (used by expunge).

Anything else is a user flag.  They are defined by the user.  Cyrus can
handle up to 128 of them.  Each record in the cyrus.index file contains
a bitmask of all the flags:

imap/mailbox.h:

#define MAX_USER_FLAGS (16*8)

struct mailbox {
  ...
  char *flagname[MAX_USER_FLAGS];
}

struct index_record {
  ...
  bit32 user_flags[MAX_USER_FLAGS/32];
}

The cyrus.header file contains a list of names (separated by spaces) that
correspond to the offsets in the bitmap for that flag.  Note that the limit
of 128 flag names applies to the mailbox - a different mailbox may have a
different offset for the same named flag.

Note that the flag name list will consist of every flag that's ever been
set on the mailbox!  I haven't actually checked if there's anything that
cleans out no-longer-used names.  It's theoretically possible (probably
during the process_records part of mailbox_expunge would be the most
sensible place to do it)o

Hope that all made sense!

Bron.