This object provides access to the vpopmaild daemon using PHP sockets.  
You must ./configure PHP with  enable-sockets to use this object, but 
you don't have to learn how to use them, it is all hidden.

Note that to use this object, you must provide a Domain, UserName
and password to the constructor when you create it.  If this is 
incorrect, the object will reject all other operations.  When this 
happens, you must destroy the existing object (unset()) and create 
another, or just give up and die.

The test directory contains a set of PHP command line programs
to test each of the functions in the deamon interface.  See the
README file in that directory for details.



It currently contains the following functions:


=========================================================
=                                                       =
=                Function Headers only                  = 
=                                                       =
=========================================================
More complete descriptions appear below this list.


Utility Functions:


function vpopmaild( $Domain, $User, $Password, 
                    $Host='localhost', $Port=89 )  {  (Constructor)

function Quit() {

function error_message() {

function GetLoginUser()  {


=========================================================

List Functions:


function ListAlias( $Domain, $User='' ) {

function ListDir( $Domain, $User='', $Path='' ) {

function ListDomains( $Sort = 'HDT' ) {

function ListLists( $Domain ) {

function ListUsers( $Domain ) {


=========================================================

Domain Functions:


function ListDomains( $Sort = 'HDT' ) {

function AddDomain( $Domain, $Password ) {

function DelDomain( $Domain ) {

function GetLimits( $Domain ) {

function SetLimits( $Domain, $Limits );


=========================================================

User Functions:


function ListUsers( $Domain ) {

function AddUser( $Domain, $User, $Password, $Gecos ) {

function DelUser( $Domain, $User ) {

function GetLastAuth( $Domain, $User ) {

function GetLastAuthIP( $Domain, $User ) {

function ModUser( $Domain, $User, $UserInfo ) {

function UserInfo( $Domain, $User ) {


=========================================================

File Functions:


function RmDir( $Domain, $User='', $Path='' );

function ListDir( $Domain, $User='', $Path='' ) {

function MkDir( $Domain, $User, $Path );

function RmFile( $Domain, $User='', $Path='' );

function ReadFile( $Domain, $User='', $Path='' ) {

function WriteFile( $Contents, $Domain, $User='', $Path='' );


=========================================================

Internal Functions:

function SockWrite( $Data ) {

function SockRead( $MaxLen=2048 ) {

function RawSockRead( $MaxLen=2048 ) {



=========================================================
=                                                       =
=                Function Descriptions                  = 
=                                                       =
=========================================================

Utility Functions:

----------------------------------------------------------------------

The constructor:

function vpopmaild( $Domain, $User, $Password, $Host='localhost', $Port=89 )  {

$Domain, $User, $Password represent the user you want to login as.

$Host and $Port are optional, with defaults.  

You should check for an error message with the error_message 
function after attempting to create a vpopmaild object.  If 
there is an error present, you can't do anything else.


----------------------------------------------------------------------

function Quit() {

You should call this before exiting the program to give the server
a chance to clean up gracefully.  The world probably won't end if
you don't but it is possible that sessions will be closed faster
if you do.


----------------------------------------------------------------------

function error_message() {

Return the most recent error message, if any from vpopmaild
operations.  This message will be text, ready for display.


----------------------------------------------------------------------

function GetLoginUser()  {

Retrive an array full of information about the currently logged in
user.

User info for logged in user: Array 
(
    [vpopmail_dir] => /mail
    [uid] => 77
    [gid] => 72
    [name] => postmaster
    [comment] => Postmaster
    [quota] => NOQUOTA
    [dir] => /mail/domains/test.com/postmaster
    [encrypted_password] => $1$zkJe.3SH$7HOl1RbwfKcibL67iXjsh/
    [clear_text_password] => password
    [domain_admin_privileges] => 1
    [system_admin_privileges] => 1
)


=========================================================

List Functions:


----------------------------------------------------------------------

function ListAlias( $Domain, $User='' ) {

Return an array where each element is the name of an alias within
$Domain.  Mailing lists are listed in with other aliases.


----------------------------------------------------------------------

function ListDir( $Domain, $User='', $Path='' ) {

Directory Info for test.com/:
Array
(
    [0] => 0
    [10] => A
    [34] => john
    [40] => qmadmin
    [43] => vpopmail
    [45] => .vpasswd.lock
    [56] => .dir-control
    [89] => .qmail-default
    [115] => vpasswd
    [125] => postmaster
    [137] => lozejibdqihuf
)

NOTE: A large number of entries were left out. 


----------------------------------------------------------------------

function ListDomains( $Sort = 'HDT' ) {

Retrieve an array full of information about a domain.  You must be
a system admin to use this call.

Order to display domains:

  TDH  = top-level, mid-level, host
  DTH  = mid-level, top-level, host
  HDT  = host, mid-level, top-level

where you usually see

   host.mid-level.top-level

   mail.developersdesk.com


Want all the .com together - use TDH
Want domain.com, domain.net, domain.org together - use DTH
Want them all mixed up in host name order - use HDT

If DomainOrder is not specified, you get HDT.

This example data uses DTH mode.  The data is DomainName => ParentName, 
If they both match, the domain is real, if they are different it
is an alias of ParentName.


Array
(
    [0-0-mydomain.com] => 0-0-mydomain.com
    [0-0-mydomain.net] => 0-0-mydomain.com
    [0-0-mydomain.org] => 0-0-mydomain.com
    [0800commerce.nl] => 0800commerce.nl
    [fun.21cn.com] => fun.21cn.com
    [private.21cn.com] => private.21cn.com
    [263.net] => 263.net
    [2dayhealth.com] => 2dayhealth.com
)


----------------------------------------------------------------------

function ListLists( $Domain ) {

Return an array where each element is the name of a mailing
list within $Domain.


----------------------------------------------------------------------

function ListUsers( $Domain ) {

Retrieve an array full of information about a domain.  You must be
a system admin to list any domain, or the domain admin of the domain
you wish to list.  The users are in alpha order by Username.

Array (
    [04wcyrti] => Array
        (
            [passwd] => $1$cBacCPRA$LxzczMu7dpn5KjZphYPKU0
            [uid] => 1
            [gid] => 0
            [flags] => 0
            [gecos] => Brigitte
            [dir] => /mail/domains/test.com/9/04wcyrti
            [shell] => NOQUOTA
            [clear_pw] => Fisher
        )

    [095wvsp] => Array
        (
            [passwd] => $1$2lpyyZHz$XmcuvLSZDbOnIaDD9Yf93.
            [uid] => 1
            [gid] => 0
            [flags] => 0
            [gecos] => Antone
            [dir] => /mail/domains/test.com/F/095wvsp
            [shell] => NOQUOTA
            [clear_pw] => Winn
        )
    )


=========================================================

Domain Functions:


----------------------------------------------------------------------

function AddDomain( $Domain, $Password ) {

Create a domain.

Returns true if there was an error.  The error string can be
retrieved with the ErrorMessage() method.


----------------------------------------------------------------------

function DelDomain( $Domain ) {

Delete a domain.

Returns true if there was an error.  The error string can be
retrieved with the ErrorMessage() method.


----------------------------------------------------------------------

function GetLimits( $Domain ) {


Limits for test.com:
Array
(
    [maxpopaccounts:] => -1
    [maxaliases:] => 1
    [maxforwards:] => -1
    [maxautoresponders:] => 3
    [maxmailinglists:] => 3
    [quota:] => 1
    [maxmsgcount:] => 1
    [default_quota:] => 1
    [default_maxmsgcount:] => 1
    [perm_account:] => 1
    [perm_alias:] => 1
    [perm_forward:] => 1
    [perm_autoresponder:] => 1
    [perm_maillist:] => 1
    [perm_quota:] => 1
    [perm_defaultquota:] => 1
)


----------------------------------------------------------------------

function SetLimits( $Domain, $Limits );


This function may still be subject to change.


=========================================================

User Functions:


----------------------------------------------------------------------

function AddUser( $Domain, $User, $Password, $Gecos ) {

Create a user.

Returns true if there was an error.  The error string can be
retrieved with the ErrorMessage() method.


----------------------------------------------------------------------

function DelUser( $Domain, $User ) {

Delete a user.

Returns true if there was an error.  The error string can be
retrieved with the ErrorMessage() method.


----------------------------------------------------------------------

function GetLastAuth( $Domain, $User ) {

LastAuth for postmaster@test.com: 1077379947


----------------------------------------------------------------------

function GetLastAuthIP( $Domain, $User ) {

LastAuthIP for postmaster@test.com: 0.0.0.0


----------------------------------------------------------------------

function ModUser( $Domain, $User, $UserInfo ) {

Modify information about a user.


----------------------------------------------------------------------

function UserInfo( $Domain, $User ) {

$Domain, $User select the user to retrieve information on.  Sys
admins can specify any value for both.  Domain admins must specify
their own domain, and individual users must specify themselves.


User Info for postmaster@test.com: Array
(
    [name] => postmaster
    [comment] => Postmaster
    [quota] => NOQUOTA
    [dir] => /mail/domains/test.com/postmaster
    [encrypted_password] => $1$zkJe.3SH$7HOl1RbwfKcibL67iXjsh/
    [clear_text_password] => password
    [system_admin_privileges] => 1
)


=========================================================

File Functions:


----------------------------------------------------------------------

function RmDir( $Domain, $User='', $Path='' );

Remove a directory.


----------------------------------------------------------------------

function MkDir( $Domain, $User, $Path );

Create a new directory.


----------------------------------------------------------------------

function WriteFile( $Contents, $Domain, $User='', $Path='' );

Write new contents to a file.   $Contents is an array containing
one line of the file per element.

$Contents = array( 
   'This is the first line',
   'This is the second line',
   'This is the third line',
   'This is the last line',
   );


----------------------------------------------------------------------

function ReadFile( $Domain, $User='', $Path='' ) {


ReadFile( 'test.com', '', '.qmail-default' );  was executed.

File Info for test.com/.qmail-default:
Array
(
    [0] => | /mail/bin/delivermail '' /mail/domains/test.com/postmaster
)


----------------------------------------------------------------------

function RmFile( $Domain, $User='', $Path='' );

Remove a File.


=========================================================

IP Map Functions:


----------------------------------------------------------------------

function GetIPMap( $IP ) {

Return the name of the domain associated with an IP address.


----------------------------------------------------------------------

function AddIPMap( $Domain, $IP ) {

Associate a domain with an IP address.


----------------------------------------------------------------------

function DelIPMap( $Domain, $IP ) {

Remove an association between an IP address and a domain.


----------------------------------------------------------------------

function ShowIPMap() {

Return an array, indexed by IP address, with the value for each key
being the associated domain name.  If more than one domain name is
associated with an IP address, it is an error, but the object will 
return a comma separated list of domain names.

VPopMail should probably check for this condition, but it does not.


=========================================================

Internal Functions:


----------------------------------------------------------------------

function SockWrite( $Data ) {

Internal function to write a string to a socket.  

Returns true if there is an error.  Currently the only error
detected is if the write length does not match the length of
the string being written.

We might need to adjust this to retry if part of the buffer is
sent, and only error out if there is a real error.  I think
not sending everything is legal, say if MTU is less than buffer
length.


----------------------------------------------------------------------

function SockRead( $MaxLen=2048 ) {

Internal function to read from a socket.  This function tales
care of the blank line problem, and should work if the blank
lines exist or not.

Returns the data string.  Blank lines are skipped.

We might want to switch to binary reads, loading as much data
as is available, then parsing it into lines within this function
as a way to speed things up.  It may help, or it may not, the
only way to find out is to benchmark both.

----------------------------------------------------------------------