Hi,

Here are some notes for you to write storage module for openwebmail.
We assume the module you want to write is storage_XYZ

ps: A simplest way is to modify an existing one to fit your requirement.


filename
---------
The file name should be storage_XYZ.pl, XYZ could be A-Za-z and _


location
--------
This storage_XYZ.pl should be put at the same directory 
as other storage module is.


package name
------------
The package name for this module is openwebmail::storage_XYZ
The first line of storage_XYZ.pl should be

package openwebmail::storage_XYZ;


functions
----------

A storage module have the following API

storage_getfolders:
return list of valid folders and calc the total folder usage(0..100%)
IN : folderpath ,r_folders, r_usage, user, uuid, ugig
OUT: 

storage_needfolderlock:
return true if folders need to be locked. mbox need this, maildir don't.
IN :
OUT: 0 or 1

storage_metainfo:
return metainfo of a folder
IN: folderpath
OUT: last modification time size

storage_get_folderfile_headerdb:
return foldername , headerdb
IN: username, foldername, folderdir, homedir
OUT: folderpathname , headerdb

storage_get_message_block:
return a message (by messageid)
IN: messageid headerdb folderpath
OUT: message

storage_get_message_block_offset:
return a message (by offset)
IN: offset, size, folderpath
OUT: message

storage_get_message_header:
return a message header (by messageid)
IN: messageid headerdb folderpath
OUT: header

storage_get_message_header_offset:
return a message header(by offset)
IN: offset, size, folderpath
OUT: header

storage_update_message_status:
same as update_message_status
IN: messageid, status, headerdb, folderpath
OUT:

storage_operate_message_with_ids:
same as operate_message_with_ids
IN: op, r_messageids, srcdir, srcdb, dstdir, dstdb
OUT: 

storage_add_message:
Add a message to a folder
IN: folderpath, r_message, r_attr
OUT

storage_remove_message_offset:
Remove a message from a folder
IN: offset, size, folderdir
OUT:

storage_folder_exist:
return true if a folder exist
IN: folderpath
OUT: 0 or 1

storage_folder_size:
return folder size
IN: folderpath
OUT: size in byte

storage_create_folder:
creatre a new folder
IN: folderpathname
OUT:

storage_delete_folder:
delete a folder
IN: folderpathname
OUT:

storage_empty_folder:
remove all messages from a folder
IN: folderpathname
OUT:


storage_folder_rename:
rename a folder
IN: oldfolderpathname newfolderpathname
OUT:

storage_compare_offset:
return comparaison of offset
IN: offseta,offsetb
OUT: comparaison



globals
---------
storage_module have *not* been tested in persistent mode

Openwebmail can run in persistent mode, 
so you have to be very careful about the global variables.

1. initialize all globals explicitly

2. it would be even better to use global as constent only

3. don't write code outside routines, 
   or they will be executed once in persistent mode

4. if you storage module has to chat with remote server,
   please do all the following thing in the API routine

   open the connection, 
   chat with server, 
   close connection

   This is the simplest way, and it can avoid the problem of lost connection
   or server rebooting.

5. if you really need global variables, please remember
   value of global variables will be kept forever when running in persistent mode

6. if you hope to save some connections to your storage server:

   a. you can use global variable to store connection handle
      but please don't do thing outside routines.

   b. the API routine should have the capability

      1. if the connection has not been initialized
         => initialize the connection handle
      2. if the connection is lost or dead
         => free old/stale connection handle
            reinitialize the connection handle


More about persistent CGI
-------------------------

storage_module have *not* been tested with SpeedyCGI.



TODO:

the use of persistent mode and SpeedyCGI may require a few API change
to avoid the use of $main::variables



