From 4cf82ee54b4486bafb6e4b748793d100d9234d3e Mon Sep 17 00:00:00 2001
From: Dan Kalowsky <kalowsky@php.net>
Date: Mon, 29 Jul 2002 18:06:17 +0000
Subject: [PATCH] updates to the imap-get-quota command documentation showing
 the new RFC compliant version example.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@90333 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/imap/functions/imap-get-quota.xml | 51 +++++++++++++++++++--
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/reference/imap/functions/imap-get-quota.xml b/reference/imap/functions/imap-get-quota.xml
index 1ae186b827..5b6cd6e534 100644
--- a/reference/imap/functions/imap-get-quota.xml
+++ b/reference/imap/functions/imap-get-quota.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/imap.xml, last change in rev 1.2 -->
   <refentry id="function.imap-get-quota">
    <refnamediv>
@@ -23,12 +23,17 @@
     </para>
     <para>
      This function is currently only available to users of the c-client2000
-     library.
+     or greater library.
     </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. -->
     <para>
      <parameter>imap_stream</parameter> should be the value returned from
-     an <function>imap_status</function> call.  This stream is required to
-     be opened as the mail admin user for the quota function to work.
+     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.
      <parameter>quota_root</parameter> should normally be in the form of
      user.name where name is the mailbox you wish to retrieve information
      about.
@@ -53,7 +58,43 @@ imap_close($mbox);
      </example>
     </para>
     <para>
-     See also <function>imap_open</function>, <function>imap_set_quota</function>.
+     As of PHP version 4.3, the function more properly reflects the
+     functionality as dictated by the RFC 2087.  The array return value has
+     changed to support an unlimited number of returned resources (i.e.
+     messages, or sub-folders) with each named resource receiving an individual
+     array key.  Each key value then contains an another array with the usage
+     and limit values within it.  The example below shows the updated returned
+     output.
+    </para>
+    <para>
+     <example>
+      <title><function>imap_get_quota</function> 4.3 or greater
+      example</title>
+      <programlisting role="php"> 
+<![CDATA[
+$mbox = imap_open("{your.imap.host}","mailadmin","password",OP_HALFOPEN)
+      or die("can't connect: ".imap_last_error());
+       
+$quota_values = imap_get_quota($mbox, "user.kalowsky");
+if(is_array($quota_values)) {
+   $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><!-- To be uncommented when imap_get_quotaroot works --><!-- , <function>imap_get_quotaroot</function> -->.
     </para>
    </refsect1>
   </refentry>