Location: PHPKode > scripts > Virtual Mail ManaGer Interface > virtual-mail-manager-interface/doc/developer.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <title>Virtual Mail ManaGer Interface - Developer's Guide</title>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <link rel=stylesheet type="text/css" href="site.css">
</head>
<body bgcolor="#FFFFFF">

<h2>Developer's guide</h2>

<h3><a name="1">1. General</a></h3>

<h3><a name="1.1">1.1 Terminology</a></h3>

<p>It is necessary not to confuse some terms: Whenever I am talking about
  a <i>user</i>, I'm thinking of the real unix user - as opposed to the
  <i>virtual user</i> which is created by VMailMgr.</p>

<h3><a name="1.2">1.2 How to use</a></h3>

<p>The VMailMgr Interface is a PHP class. I suggest you to first create a new
  class which extends the base class in order to specify whether you are
  using TCP/IP or UNIX Domain sockets.</p>

<pre>
  include_once(dirname(__FILE__) . '/vm/vm.php');
</pre>  
  
<p>TCP/IP sockets:</p>

<pre>
  class my_vmailmgr extends vmailmgr {
    var $tcp_host = "localhost";
    var $tcp_port = 322;
  }
</pre>

<p>.. or UNIX Domain sockets:</p>

<pre>
  class my_vmailmgr extends vmailmgr {
    var $unix_socket = "/tmp/.vmailmgrd";
  }
</pre>

<p>
  Finally, create an instance of this class:
</p>

<pre>
  $vm = new my_vmailmgr($domain, $password);
</pre>

<h3><a name="1.3">1.3 Which password?</a></h3>

<p>There are certain commands that can be performed both with the user's
  password and the virtual user's password:</p>

<div align="center">

<table width="450" bgcolor="#CCCCCC" cellspacing="1" cellpadding="3">
<tr>
  <td bgcolor="#EEEEEE" width="250">&nbsp;</td>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>virtual user</b></td>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>user</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" colspan="3"><b>2. Basic Functions</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">2.1 Add Account</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">2.2 Add Alias</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">2.3 Remove Account/Alias</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">2.4 Information on particular user</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">2.5 List available users</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" colspan="3"><b>3. Set Attributes</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.1 Password</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.2 Forwards</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.3 Hardquota</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.4 Softquota</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.5 Message Size</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.6 Message Count</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.7 Expiry</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.8 Personal</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">3.9 Catch All</td>
  <td bgcolor="#FFFFFF" align="center">&nbsp;</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" colspan="3"><b>4. Autoresponder</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">4.1 Set</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">4.2 Get</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">4.3 Enable/Disable</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF">4.4 Status (enabled or disabled?)</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
  <td bgcolor="#FFFFFF" align="center">x</td>
</tr>
</table>

</div>

<p><b>Note:</b> The first parameter of vmmi's constructor still remains $domain.
  Do not attempt to create an instance like:</p>

<pre>
  $vm = new my_vmailmgr("hide@address.com", $password);
</pre>

<p>This won't work. The following is correct:</p>

<pre>
  $vm = new my_vmailmgr("example.com", $password);
</pre>

<p>There's a working example on chapter 1.4.</p>

<h3><a name="1.4">1.4 Verifying Passwords</a></h3>

<p>Unfortunately, the VMailMgr daemon does not offer a command to verify
  a password. I suggest you to use a command that does not apply any changes.
  This adds some overhead, but unfortunately there is no alternative. To
  verify the user's password I recommend:</p>

<pre>
  $vm = new my_vmailmgr("example.com", <b>$password_to_verify</b>);
  if($vm->list_users() !== false) {
    echo "Password OK";
  }
  else {
    echo "Password invalid";
  }
</pre>

<p>To verify the virtual user's password I recommend:</p>

<pre>
  $vm = new my_vmailmgr("example.com", <b>$password_to_verify</b>);
  if($vm->user_info(<b>$user_to_check</b>) !== false) {
    echo "Password OK";
  }
  else {
    echo "Password invalid";
  }
</pre>

<p>Make sure you do also type-checking (!== instead of != or just a plain !).</p>

<p><b>Hint:</b> You might also want to have a look at 'login.php'.</p>

<h3><a name="1.5">1.5 Why set_enabled() instead of enable() and disable()?</a></h3>

<p>There are several set_enabled() functions instead of enable()/disable() pairs.
  You may wonder why? Because it allows more elegant code. Suppose we have the
  following (fragment of a) HTML form:</p>

<pre>
  &lt;select name="enable"&gt;
    &lt;option value="yes"&gt;yes
    &lt;option value="no"&gt;no
  &lt/select&gt;
</pre>

<p>With enable()/disable() we'd have to write:</p>

<pre>
  if($_REQUEST['enable'] == 'yes') {
    $vm->enable();
  }
  else {
    $vm->disable();
  }
</pre>

<p>But with set_enable() we can just write:</p>

<pre>
  $vm->set_enable($_REQUEST['enable'] == 'yes');
</pre>

<p>Of course you could use the ternary operator "?:", but that's not the point.</p>

<h3><a name="2">2. Basic Functions</a></h3>

<h3><a name="2.1">2.1 Add Account</a></h3>

<p>bool <b>add_account</b> ( string user, string password [, array forwards] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="2.2">2.2 Add Alias</a></h3>

<p>bool <b>add_alias</b> ( string user [, string password [, array forwards]] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="2.3">2.3 Remove Account/Alias</a></h3>

<p>bool <b>delete_user</b> ( string user )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="2.4">2.4 Information on particular user</a></h3>

<p>array <b>user_info</b> ( string user )</p>

<p>Returns an array with user info on success, false on failure. This array looks
  like:</p>

<div align="center">

<table width="500" bgcolor="#CCCCCC" cellspacing="1" cellpadding="3">
<tr>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>key</b></td>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>type</b></td>
  <td bgcolor="#EEEEEE" width="300" align="center"><b>explanation</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">flags</td>
  <td bgcolor="#FFFFFF" align="center">array</td>
  <td bgcolor="#FFFFFF" align="center">(see table below)</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">username</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Username</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">password</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Has this account a password set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">mailboxdir</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Path to virtual user's mailbox</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">personal</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Personal info</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">hardquota</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Hardquota in bytes, "-" if not set</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">softquota</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Softquota in bytes, "-" if not set</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">messagesize</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Maximum message size, "-" if not set</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">messagecount</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Maximum message count, "-" if not set</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">creation</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Account creation time as UNIX timestamp</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">expiry</td>
  <td bgcolor="#FFFFFF" align="center">string</td>
  <td bgcolor="#FFFFFF" align="center">Account expiry time as UNIX timestamp, "-" if not set</td>
</tr>
</table>

</div>

<p>The flags-key is itself an array which can have the following values.
  These values are defined in ./lib/vdomain/vdomain.h of VMailMgr's
  sourcecode.</p>
  
<p><b>Note:</b> The only flag that appears to be set (as of VMailMgr 0.95)
  is 'mailbox_enabled' - the other one's are (somehow) redundant anyway.</p>

<div align="center">

<table width="500" bgcolor="#CCCCCC" cellspacing="1" cellpadding="3">
<tr>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>key</b></td>
  <td bgcolor="#EEEEEE" width="100" align="center"><b>type</b></td>
  <td bgcolor="#EEEEEE" width="300" align="center"><b>explanation</b></td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">pass</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Password set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">dest</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">(Probably) destination mailbox set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">hardquota</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Hardquota set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">softquota</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Softquota set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">msgsize</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Message size limit set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">msgcount</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Message count limit set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">expiry</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Expiry date set?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">mailbox_enabled</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Mailbox enabled?</td>
</tr>
<tr>
  <td bgcolor="#FFFFFF" align="center">personal</td>
  <td bgcolor="#FFFFFF" align="center">bool</td>
  <td bgcolor="#FFFFFF" align="center">Personal info set?</td>
</tr>
</table>

</div>

<h3><a name="2.5">2.5 List available users</a></h3>

<p>bool <b>list_users</b> ()</p>

<p>Returns an array with user info on success, false on failure. See chapter
  2.4 for a description of the array.</p>

<h3><a name="3">3. Set Attributes</a></h3>

<h3><a name="3.1">3.1 Password</a></h3>

<p>bool <b>set_password</b> ( string user, string password )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.2">3.2 Forwards</a></h3>

<p>bool <b>set_forwards</b> ( string user [, array forwards] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.3">3.3 Hardquota</a></h3>

<p>bool <b>set_hardquota</b> ( string user [, string quota] )</p>

<p><i>quota</i> is given in bytes.</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.4">3.4 Softquota</a></h3>

<p>bool <b>set_softquota</b> ( string user [, string quota] )</p>

<p><i>quota</i> is given in bytes.</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.5">3.5 Message Size</a></h3>

<p>bool <b>set_messagesize</b> ( string user [, string size] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.6">3.6 Message Count</a></h3>

<p>bool <b>set_messagecount</b> ( string user [, string count] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.7">3.7 Expiry</a></h3>

<p>bool <b>set_expiry</b> ( string user [, string timestamp] )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.8">3.8 Enable/Disable</a></h3>

<p>bool <b>set_enabled</b> ( string user, bool enable )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.9">3.9 Personal</a></h3>

<p>bool <b>set_personal</b> ( string user [, string text] )</p>

<p><i>text</i> is a string with arbitrary content. <i>vmmi</i> uses it to
  store the virtual user's full name.</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="3.10">3.10 Catch All</a></h3>

<p>bool <b>set_catchall</b> ( [string user] )</p>

<p>If <i>user</i> is omitted, catchall is removed.</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="4">4. Autoresponder</a></h3>

<h3><a name="4.1">4.1 Set</a></h3>

<p>bool <b>autoresponse_set</b> ( string user, string message )</p>

<p>'message' also has to include mail headers. Make sure to at least
  provide 'From:' and 'Subject:'. Example:</p>
  
<pre>
  $vm->autoresponse_set("foobar", "From: Foo Bar &lt;hide@address.com&gt;
Subject: Autoresponse: %S

This is my autoresponse message.");
</pre>

<p>Returns true on success, false on failure.</p>

<h3><a name="4.2">4.2 Get</a></h3>

<p>string <b>autoresponse_get</b> ( string user )</p>

<p>Returns autoresponse message on success, false on failure.</p>

<p><b>Hint:</b> Have a look at 4.5 Parse</p>

<h3><a name="4.3">4.3 Enable/Disable</a></h3>

<p>bool <b>autoresponse_set_enabled</b> ( string user, bool enable )</p>

<p>Returns true on success, false on failure.</p>

<h3><a name="4.4">4.4 Status (enabled or disabled?)</a></h3>

<p>bool <b>autoresponse_isset</b> ( string user )</p>

<p>Returns true if autoresponse is activated, false if disabled.</p>

<h3><a name="4.5">4.5 Parse</a></h3>

<p>array <b>autoresponse_parse</b> ( string message )</p>

<p>This is a helper function intended to parse a message returned by autoresponse_get().
  The array corresponding to the example autoresponse set in 4.1 would look
  like this (output generated with var_dump()):</p>

<pre>
  array(2) {
    ["body"]=>
    string(87) "This is my autoresponse message."
    ["headers"]=>
    array(2) {
      ["Subject"]=>
      string(16) "Autoresponse: %S"
      ["From"]=>
      string(14) "Foo Bar &lt;hide@address.com&gt;"
    }
  }
</pre>

<h3><a name="5">5. Advanced Functions</a></h3>

<h3><a name="5.1">5.1 Send raw message to daemon</a></h3>

<p>The most low-level function you can get is:

<p>string <b>send</b> ( string data )</p>

<p>Sends <i>data</i> to the VMailMgr daemon and returns a response string,
  false on failure. The VMailMgr protocol requires you to prepend every
  message with a two-byte length index. This function will help:</p>

<p>string <b>arglen</b> ( string data )</p>

<p>Returns <i>data</i> length encoded as two bytes. But you might prefer
  5.2, as it isn't as low-level as this.</p>

<h3><a name="5.2">5.2 Send your own command to daemon</a></h3>

<p>This is a wrapper function around send() which takes care of prepending
  length bytes and formatting the command just like VMailMgr wants it.</p>

<p>bool <b>raw</b> ( string cmd, array args )</p>

<p><i>cmd</i> is the command sent to VMailMgr, <i>args</i> an array of
  arguments. Example:</p>

<pre>
  $vm->raw("deluser", array("example.com", "user", "password"));
</pre>

<p>This would delete a user.</p>

<p><b>Hint:</b> You might want to have a look at 'vm.php'. All commands discussed
  here are invoking raw().</p>

<h3><a name="5.3">5.3 Retrieve last response from daemon</a></h3>

<p>This varies depending on whether you are "inside" or "outside" the class. As you know
  raw() only returns a bool value whether your command succeded or failed. When you need
  the rest of VMailMgr's response (for example with commands like "listdomain" and
  "lookup"), you can get it from:</p>

<pre>
  $this->response;
</pre>

<p>This variable has to be <i>considered</i> private (as you know PHP 4.x does
  not yet support <i>real</i> private member variables). From "outside" the class
  use the following command instead:</p>

<p>string <b>last_response</b> ()</p>

<p>Returns VMailMgr's last response. The header is already stripped. If you
  need the full response, use send() instead.</p>

<h3><a name="6">6. Important VMailMgr Documents</a></h3>

<p>For your convenience, I've included local copies of important VMailMgr documents.</p>

<h3><a name="6.1">6.1 Client-Server Interaction (Protocol description)</a></h3>

<p><a href="protocol.txt" target="_blank">protocol.txt</a></p>

<h3><a name="6.2">6.2 Record Format</a></h3>

<p><a href="record-format.txt" target="_blank">record-format.txt</a></p>

<p align="center"><small>by <a href="http://daniel.lorch.cc/" target="_blank">Daniel Lorch</a> 2002</small></p>

</body>
</html>
Return current item: Virtual Mail ManaGer Interface