Hi,

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

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


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


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


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

package ow::quota_XYZ;


functions
----------
All functions follow this form

($retcode, $errmsg, retvals...)=routine($r_config, parameters);
where:
	$retcode:  0 means ok, else means error
	$errmsg:   message for sysadm, it will be logged to openwebmail.log
                   this won't be displayed to user
	$r_config: reference of the system config hash %config

A quota module would have only 1 API

#  0 : ok
# -1 : parameter format error
# -2 : quota system/internal error

# get user quotausage and quotalimit, must be uptodate
# if quotalimit returned as -1, which means quotalimit is not supported
($retcode, $errmsg, $usage, $quotalimit)=
	get_usage_limit($r_config, $user, $homedir, $uptodate);

ps: If $uptodate is 1,
    the most uptodate user quota information should be returned
    If $uptodate is 0,
    the quota info may be not so fresh, eg: from a cache,


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

1. only use 'my variable' for constant globals.
   If the global variable will be changed and referenced at runtime by routines,
   you need to delcare it with 'use vars qw(variable);'

ps: this is due to the closure effect in persistent mode perl.
    Once a my variable is referenced by a sub routine, then
    the subroutine will has its own copy of this my variable.
    Then further change in the global my variable won't be seen by the subroutine.

2. code outside routines will be executed only once
   (when the module is required by main program)
   So the outside routine code should be used for init only

3. if you module has to chat with remote server,
   please do all the following thing in each of the API routines

   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.

4. If you really need global variables, use 'use vars qw(variable)'.
   And please remember that value of global variables will be kept forever
   when running in persistent mode

5. if you hope to keep some connections to your remote server:

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

   b. all of the API routines 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

6. The signal handler for child process $SIG{CHLD} may have been set
   before calling the API routines, if your routine will fork new process,
   you may need to disable the handler temporarily by putting the following
   line in the routine

   local $SIG{CHLD}; undef $SIG{CHLD}


More about persistent CGI
-------------------------
1. a persistent CGI process serves one request at a time,
   if more than one request come, more processes are forked

2. a persistent CGI process won't end after a request is completed,
   it waits for a new request and the global variable will be kept
   across requests.

3. Normally, a persistent perl CGI runs under main:: package
   Just the same as pure CGI

4. But SpeedyCGI has a group mode which puts servers CGIs into one process,
   each CGI is running under a package other than main::,

   And here are the differences in group mode:

   a. one resident perl process can be used to wait requests for different CGIs

   b. you can not access variable with prefix like  $main:: or $::.

   c. Different CGI may share one copy of packages during differnt time
      So if package use global vraible to store state,
      the global may be changed or used by different CGIs