Storage Folder Format
			---------------------

The mail folders are a mini file system, abeit a rather simplistic one. After the header at the start of the file there is a heirarchy of nodes, with each node containing child nodes and/or data. Each node is typed with a 32 bit value so that the application program can know what is in the data segment of the node. Nodes can be deleted, reparented etc. Space left after a delete or resize of a node has to be removed with a compact call.

Note:
All these formats are given in a "C" like psuedo code. There are 2 formats for these files, I will only discuss the v2 format. All byte offsets are from the start of the file.


struct StoreageFileHeader
{
	int32 Magic;		// = STORAGE_MAGIC (0x123400FF) for a v1 format file
						// = STORAGE2_MAGIC (0x123400FE) for a v2 format file
	int32 Version;		// Application defined version number
	int32 Reserved1;	// Unused
	int32 Reserved2;	// Unused
	char Password[32];	// Password for the storage
	int32 Reserved2[4]; // Unused
};

assert(sizeof(StoreageFileHeader) == 64);

The root nodes starts directly after this 64 byte header.

A node looks like this:

struct StorageFileNode
{
	int32 Magic;		// = STORAGE_ITEM_MAGIC (0x123400AA) for v1 file
						// = STORAGE2_ITEM_MAGIC (0x123400AB) for v2 file

	// object descriptor
	int32 Type;			// Application defined object type
	int32 DataLoc;		// Byte offset to this objects data segment
	int32 DataSize;		// Size of this objects data segment in bytes

	// heirarchy descriptor
	int32 ParentLoc;	// Byte offset of this objects parent
	int32 DirLoc;		// Byte offset of this objects child directory
	int32 DirCount;		// Number of elements in the child directory array
	int32 DirAlloc;		// Numder of allocated elements in child directory
};

assert(sizeof(StorageFileNode) == 32);

The Directory of child nodes pointed to by DirLoc is an array of StorageFileNode's in the file, of size DirAlloc, but of which only DirCount is currently used. This is because growing the array of StorageFileNode is a costly exercise, so it's best to allocate more than you need and then fill these unused entries when needed. Basically when a directory or data segment needs to grow it gets copied onto the end of the file and the space used previously will be reclaimed on the next compact.