imap-get-quota.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 34892f82742329af7e7b4b22be6ad21418fd9768 Maintainer: hholzgra Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 34892f82742329af7e7b4b22be6ad21418fd9768 Reviewer: samesch -->
<refentry xml:id="function.imap-get-quota" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>imap_get_quota</refname>
  <refpurpose>Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>imap_get_quota</methodname>
   <methodparam><type>IMAP\Connection</type><parameter>imap</parameter></methodparam>
   <methodparam><type>string</type><parameter>quota_root</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>imap_get_quota</function> ermittelt die aktuellen
   Quota-Einstellungen und tatsächlich genutzten Ressourcen für Postfächer.
  </para>
  <para>
   Für die Ausführung dieser Funktion ist ein IMAP-Benutzer mit
   Administrationsrechten erforderlich, eine nichtadministrative Variante der
   Funktion ist <function>imap_get_quotaroot</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &imap.imap-parameter.imap;
    <varlistentry>
     <term><parameter>quota_root</parameter></term>
     <listitem>
      <para>
       <parameter>quota_root</parameter> sollte normalerweise in der Form
       <literal>user.name</literal> angegeben werden. name ist dabei der Name
       des Postfachs, für das Informationen geliefert werden sollen.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt ein Array mit den zwei Integer-Elementen limit und usage zurück, die
   den insgesamt verfügbaren und den zur Zeit vom Postfach genutzten
   Speicherplatz angeben. Im Fehlerfall wird &false; zurückgegeben.
  </para>
  <para>
   Ab PHP 4.3 hält sich die Funktion genauer an die Vorgaben aus
   <link xlink:href="&url.rfc;2087">RFC2087</link>. Das Ergebnisarray
   unterstützt nun eine unbegrenzte Anzahl von Ressourcenwerten (d. h. der
   Nachrichten oder Unterordner). Für jede Ressource wird ein Arrayelement mit
   dem Namen der Ressource als Key angelegt, die einzelnen Arrayelemente sind
   wiederum Arrays mit Angaben zu Limit und Nutzung.
  </para>
  <para>
   Aus Gründen der Rückwärtskompatibilität werden außerdem weiterhin die
   beiden ursprünglichen Arrayelemente limit und usage zurückgegeben, ihre
   weitere Nutzung wird allerdings nicht empfohlen.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &imap.changelog.imap-param;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>imap_get_quota</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
      or die("Kann keine Verbindung aufbauen: " . imap_last_error());

$quota_value = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_value)) {
    echo "Aktuell genutzt: " . $quota_value['usage'];
    echo "Verfügbar (Limit): " . $quota_value['limit'];
}

imap_close($mbox);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Beispiel für <function>imap_get_quota</function> ab 4.3 und aufwärts</title>
    <programlisting role="php">
<![CDATA[
<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
      or die("Kann keine Verbindung aufbauen: " . imap_last_error());

$quota_values = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_values)) {
   $storage = $quota_values['STORAGE'];
   echo "Speicherplatz (aktuell genutzt): " .  $storage['usage'];
   echo "Speicherplatz (Limit): " .  $storage['limit'];

   $message = $quota_values['MESSAGE'];
   echo "Anzahl Nachrichten (aktuell): " .  $message['usage'];
   echo "Anzahl Nachrichten (Limit): " .  $message['limit'];

   /* ...  */
}

imap_close($mbox);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <para>
   Diese Funktion ist aktuell erst ab der Bibliotheksversion c-client2000
   verfügbar.
  </para>
  <para>
   Der angegebene <parameter>imap</parameter> muss als Mail-Administrator
   geöffnet werden, sonst schlägt diese Funktion fehl.
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>imap_open</function></member>
    <member><function>imap_set_quota</function></member>
    <member><function>imap_get_quotaroot</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->