adding documentation of get-quotaroot

#could have sworn I did this before but a cvs update didn't bring it back


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@91029 c90b9560-bf6c-de11-be94-00142212c4b1

reference/imap/functions/imap-get-quota.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/imap.xml, last change in rev 1.2 -->
   <refentry id="function.imap-get-quota">
    <refnamediv>
@@ -27,9 +27,10 @@
     </para>
     <para>
      NOTE: For this function to work, the mail stream is required to be opened
-     as the mail-admin user.<!-- To be uncommented once imap_get_quotaroot is
-     working --><!-- For a non-admin user version of this function, please see
-     the <function>imap_get_quotaroot</function> function of PHP. -->
+     as the mail-admin user.  For a non-admin user version of this function, 
+     please see the <function>imap_get_quotaroot</function> function of PHP.
+    </para>
+    <para>
      <parameter>imap_stream</parameter> should be the value returned from
      an <function>imap_open</function> call.  NOTE: This stream is required 
      to be opened as the mail admin user for the get_quota function to work.
@@ -65,6 +66,9 @@ imap_close($mbox);
      and limit values within it.  The example below shows the updated returned
      output.
     </para>
+    <para>
+      For backwards compatibility reasons, the originial access methods are 
+      still available for use, although it is suggested to update.
     <para>
      <example>
       <title><function>imap_get_quota</function> 4.3 or greater
@@ -93,7 +97,7 @@ imap_close($mbox);
      </example>
     </para>
     <para>
-     See also <function>imap_open</function>, <function>imap_set_quota</function><!-- To be uncommented when imap_get_quotaroot works --><!-- , <function>imap_get_quotaroot</function> -->.
+     See also <function>imap_open</function>, <function>imap_set_quota</function>, <function>imap_get_quotaroot</function>.
     </para>
    </refsect1>
   </refentry>

reference/imap/functions/imap-get-quotaroot.xml

@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.imap-get-quotaroot">
+   <refnamediv>
+    <refname>imap_get_quotaroot</refname>
+    <refpurpose>
+     Retrieve the quota settings per user
+    </refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+     <methodsynopsis>
+      <type>array</type><methodname>imap_get_quotaroot</methodname>
+      <methodparam><type>int</type><parameter>imap_stream</parameter></methodparam>
+      <methodparam><type>string</type><parameter>quota_root</parameter></methodparam>
+     </methodsynopsis>
+    <para>
+     Returns an array of integer values pertaining to the specified user 
+     mailbox.  All values contain a key based upon the resource name, and a
+     corresponding array with the usage and limit values within.  
+    </para>
+    <para>
+     The limit value represents the total amount of space
+     allowed for this user's total mailbox usage.  The usage value represents 
+     the user's current total mailbox capacity.  This function will return 
+     &false; in the case of call failure, and an array of information about 
+     the connection upon an un-parsable response from the server.
+    </para>
+    <para>
+     This function is currently only available to users of the c-client2000
+     or greater library.
+    </para>
+    <para>
+     <parameter>imap_stream</parameter> should be the value returned from
+     an <function>imap_open</function> call.  This stream should be opened 
+     as the user whose mailbox you wish to check.
+     <parameter>quota_root</parameter> should normally be in the form of
+     which mailbox (i.e. INBOX).
+    </para>
+    <para>
+     <example>
+      <title><function>imap_get_quotaroot</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+$mbox = imap_open("{your.imap.host}","kalowsky","password",OP_HALFOPEN)
+      or die("can't connect: ".imap_last_error());
+ 
+$quota = imap_get_quotaroot($mbox, "INBOX");
+if(is_array($quota)) {
+   $storage = $quota_values['STORAGE'];
+   print "STORAGE usage level is: " .  $storage['usage'];
+   print "STORAGE limit level is: " .  $storage['limit'];
+
+   $message = $quota_values['MESSAGE']; 
+   print "MESSAGE usage level is: " .  $message['usage'];
+   print "MESSAGE usage level is: " .  $message['limit'];
+
+   /* ...  */ 
+
+} 
+ 
+imap_close($mbox); 
+]]>
+      </programlisting>
+     </example>
+    </para>
+    <para>
+     See also <function>imap_open</function>, <function>imap_set_quota</function>, <function>imap_get_quota</function>.
+    </para>
+   </refsect1>
+  </refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->