repo_zf1/documentation/manual/de/module_specs/Zend_Gdata_Gapps.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.gapps">
    <title>Google Apps Provisionierung verwenden</title>

    <para>
        Google Apps ist ein Service der es Domain Administratoren erlaubt Ihren Benutzern einen gemanagten
        Zugriff auf Google Services wie Mail, Kalender und Dokumente &amp; Tabellenkalkulationen zu bieten.
        Die Provisionierungs API bietet ein programmmäßiges Interface um dieses Service zu konfigurieren.
        Im speziellen erlaubt es diese API den Administratoren Benutzerzugänge, Nicknamen und Email Listen
        zu erstellen, zu empfangen, zu verändern und zu löschen.
    </para>

    <para>
        Diese Bibliothek implementiert die Version 2.0 der Provisionierungs API. Zugriff zum eigenen Konto über
        die Provisionierungs API muß manuell für jede Domain aktiviert werden die das Google Apps Kontrollpanel
        verwendet. Nur bestimmte Kontotpen sind fähig dieses Feature einzuschalten.
    </para>

    <para>
        Für weitere Information zur Google Apps Provisionierungs API, inklusive Anleitungen für das einschalten
        des API Zugriffs, kann in die
        <ulink url="http://code.google.com/apis/calendar/overview.html">Provisionierungs API V2.0 Referenz</ulink>
        gesehen werden.
    </para>

    <note>
        <title>Authentifizierung</title>
        <para>
            Die Provisionierungs API unterstützt keine Authentifizierung über AuthSub und anonymer Zugriff ist
            nicht gestattet. Alle HTTP Verbindungen müssen mit Hilfe der ClientAuth Authentifizierung
            authentifiziert werden.
        </para>
    </note>

    <sect2 id="zend.gdata.gapps.domain">
        <title>Die aktuelle Domain setzen</title>

        <para>
            Um die Provisionierungs API zu verwenden muß die Domain, die administriert werden soll, in allen
            Anfrage URIs spezifiziert werden. Um die Entwicklung zu vereinfachen, wird diese Information sowohl
            im Gapps Service und den Abfrageklassen gespeichert um Sie zu verwenden wenn Abfragen erstellt werden.
        </para>

        <sect3 id="zend.gdata.gapps.domain.service">
            <title>Setzen der Domain für die Serviceklasse</title>

            <para>
                Um die Domain für die von der Serviceklasse durchgeführten Anfragen zu setzen kann entweder
                <code>setDomain()</code> aufgerufen oder die Domain bei der Instanzierung der Serviceklasse
                spezifiziert werden. Zum Beispiel:
            </para>

            <programlisting role="php"><![CDATA[
$domain = "example.com";
$gdata = new Zend_Gdata_Gapps($client, $domain);
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.domain.query">
            <title>Die Domain für die Abfrageklasse setzen</title>

            <para>
                Das Setzen der Domain für Anfrage die durch die Abfrageklasse durchgeführt werden ist ähnlich dem
                setzen für die Serviceklasse-entweder wird <code>setDomain()</code> aufgerufen, oder die Domain
                wird bei der Erstellung der Abfrage angegeben. Zum Beispiel:
            </para>

            <programlisting role="php"><![CDATA[
$domain = "example.com";
$query = new Zend_Gdata_Gapps_UserQuery($domain, $arg);
]]></programlisting>

            <para>
                Wenn eine Serviceklassen Factorymethode verwendet wird um eine Abfrage zu erstellen, setzt
                die Serviceklasse die Domain der Abfrage automatisch so das Sie ihrer eigenen Domain entspricht.
                Als Ergebnis ist es nicht notwendig die Domain als Teil der Konstruktorargumente zu spezifizieren.
            </para>

            <programlisting role="php"><![CDATA[
$domain = "example.com";
$gdata = new Zend_Gdata_Gapps($client, $domain);
$query = $gdata->newUserQuery($arg);
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.gdata.gapps.users">
        <title>Interaktion mit Benutzern</title>

        <para>
            Jeder Benutzerzugang zu einer Google Apps gehosteten Domain wird als Instanz von
            <classname>Zend_Gdata_Gapps_UserEntry</classname> repräsentiert. Diese Klasse bietet Zugriff zu allen Zugangseigenschaften
            inklusive Name, Benutzername, Passwort, Zugriffsrehte und aktuellen Quoten.
        </para>

        <sect3 id="zend.gdata.gapps.users.creating">
            <title>Erstellen eines Benutzerzugangs</title>

            <para>
                Benutzerzugänge können durch den Aufruf der einfachen <code>createUser()</code> Methode erstellt
                werden:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->createUser('foo', 'Random', 'User', '••••••••');
]]></programlisting>

            <para>
                Benutzer können durch das instanzieren eines  UserEntry erstellt werden, indem ein Benutzername,
                ein Name, ein Familienname und ein Passwort angegeben werden und anschließend
                <code>insertUser()</code> am Serviceobjekt aufgerufen wird um den Eintrag zum Server zu laden.
            </para>

            <programlisting role="php"><![CDATA[
$user = $gdata->newUserEntry();
$user->login = $gdata->newLogin();
$user->login->username = 'foo';
$user->login->password = '••••••••';
$user->name = $gdata->newName();
$user->name->givenName = 'Irgendwer';
$user->name->familyName = 'Benutzer';
$user = $gdata->insertUser($user);
]]></programlisting>

            <para>
                Das Passwort den Benutzers sollte normalerweise als Klartext angegeben werden. Operional kann
                das Passwort als SHA-1 Schlüssel angegeben werden wenn <code>login->passwordHashFunction</code>
                auf 'SHA-1' gesetzt ist.
            </para>

        </sect3>

        <sect3 id="zend.gdata.gapps.users.retrieving">
            <title>Einen Benutzerzugang erhalten</title>

            <para>
                Individuelle Benutzerzugänge kann man erhalten indem die einfache <code>retrieveUser()</code>
                Methode aufgerufen wird. Wenn der Benutzer nicht gefunden wird, wird <code>null</code>
                zurückgegeben.
            </para>

            <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');

echo 'Benutzername: ' . $user->login->userName . "\n";
echo 'Name: ' . $user->login->givenName . "\n";
echo 'Familienname: ' . $user->login->familyName . "\n";
echo 'Unterbrochen: ' . ($user->login->suspended ? 'Ja' : 'Nein') . "\n";
echo 'Administrator: ' . ($user->login->admin ? 'Ja' : 'Nein') . "\n"
echo 'Muss das Passwort ändern: ' .
     ($user->login->changePasswordAtNextLogin ? 'Ja' : 'Nein') . "\n";
echo 'Hat den Regeln zugestimmt: ' .
     ($user->login->agreedToTerms ? 'Ja' : 'Nein') . "\n";
]]></programlisting>

            <para>
                Benutzer kann man auch erhalten indem eine Instanz von <classname>Zend_Gdata_Gapps_UserQuery</classname> erstellt wird,
                und dessen username Eigenschaft dem Benutzernamen des Benutzers entspricht den man erhalten will
                und <code>getUserEntry()</code> auf einem Serviceobjekt mit dieser Abfrage aufruft.
            </para>

            <programlisting role="php"><![CDATA[
$query = $gdata->newUserQuery('foo');
$user = $gdata->getUserEntry($query);

echo 'Benutzername: ' . $user->login->userName . "\n";
echo 'Name: ' . $user->login->givenName . "\n";
echo 'Familien Name: ' . $user->login->familyName . "\n";
echo 'Unterbrochen: ' . ($user->login->suspended ? 'Ja' : 'Nein') . "\n";
echo 'Administrator: ' . ($user->login->admin ? 'Ja' : 'Nein') . "\n"
echo 'Muss das Passwort ändern: ' .
     ($user->login->changePasswordAtNextLogin ? 'Ja' : 'Nein') . "\n";
echo 'Hat den Regeln zugestimmt: ' .
     ($user->login->agreedToTerms ? 'Ja' : 'Nein') . "\n";
]]></programlisting>

            <para>
                Wenn der spezifizierte Benutzer nicht gefunden werden kann wird eine ServiceException mit einem
                Fehlercode von <classname>Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST</classname> geworfen. ServiceExceptions werden
                in <xref linkend="zend.gdata.gapps.exceptions" /> behandelt.
            </para>

        </sect3>

        <sect3 id="zend.gdata.gapps.users.retrievingAll">
            <title>Alle Benutzer in einer Domain erhalten</title>

            <para>
                Um alle Benutzer in einer Domäne zu erhalten kann die einfache <code>retrieveAllUsers()</code>
                Methode aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveAllUsers();

foreach ($feed as $user) {
    echo "  * " . $user->login->username . ' (' . $user->name->givenName .
        ' ' . $user->name->familyName . ")\n";
}
]]></programlisting>

            <para>
                Das wird ein <classname>Zend_Gdata_Gapps_UserFeed</classname> Objekt erstellen welches jeden Benutzer dieser Domain
                enthält.
            </para>

            <para>
                Alternativ kann <code>getUserFeed()</code> ohne Optionen aufgerufen werden. Es ist zu beachten
                das dieser Feed bei größeren Domains durch den Server in Seiten ausgegeben werden kann. Über
                weitere Informationen der Ausgabe in Seiten siehe
                <xref linkend="zend.gdata.introduction.paging" />.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->getUserFeed();

foreach ($feed as $user) {
    echo "  * " . $user->login->username . ' (' . $user->name->givenName .
        ' ' . $user->name->familyName . ")\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.users.updating">
            <title>Einen Benutzerzugang aktualisieren</title>

            <para>
                Der einfachste Weg um einen Benutzerzugang zu aktualisieren ist es den Benutzer wie in der
                vorherigen Sektion beschrieben zu empfangen, jegliche gewünschte Änderungen durchzuführen und
                anschließend <code>save()</code> auf diesem Benutzer aufzurufen. Jede gemachte Änderung wird
                an den Server weitergegeben.
            </para>

            <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->name->givenName = 'Foo';
$user->name->familyName = 'Bar';
$user = $user->save();
]]></programlisting>

            <sect4 id="zend.gdata.gapps.users.updating.resettingPassword">
                <title>Ein Benutzerpasswort resetieren</title>

                <para>
                    Ein Benutzerpasswort kann zu einem neuen Wert resetiert werden indem die
                    <code>login->password</code> Eigenschaft aktualisiert wird.
                </para>

                <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->password = '••••••••';
$user = $user->save();
]]></programlisting>

                <para>
                    Es ist zu beachten das es nicht möglich ist ein Passwort auf diesem Weg wiederherzustellen da
                    gespeicherte Passwörter aus Sicherheitsgründern nicht über die Provisionierungs API
                    verfügbar gemacht werden.
                </para>

            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.forcingPasswordChange">
                <title>Einen Benutzer zwingen sein Passwort zu ändern</title>

                <para>
                    Ein Benutzer kann dazu gezwungen werden sein Passwort bei seinem nächsten Login zu ändern,
                    indem die <code>login->changePasswordAtNextLogin</code> Eigenschaft auf <code>true</code>
                    gesetzt wird.
                </para>

                <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->changePasswordAtNextLogin = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Genauso kann das rückgängig gemacht werden indem die
                    <code>login->changePasswordAtNextLogin</code> Eigenschaft auf <code>false</code> gesetzt wird.
                </para>

            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.suspendingAccount">
                <title>Einen Benutzerzugang unterbrechen</title>

                <para>
                    Benutzer können daran gehindert werden sich anzumelden ohne das Ihr Benutzerzugang
                    gelöscht wird indem Ihr Benutzerzugang <emphasis>unterbrochen</emphasis> wird. Zugänge
                    können unterbrochen oder wiederhergestellt werden indem die einfachen
                    <code>suspendUser()</code> und <code>restoreUser()</code> Methoden verwendet werden:
                </para>

                <programlisting role="php"><![CDATA[
$gdata->suspendUser('foo');
$gdata->restoreUser('foo');
]]></programlisting>

                <para>
                    Alternativ kann die Eigenschaft <code>login->suspended</code> des Benutzerzugangs auf
                    <code>true</code> gesetzt werden.
                </para>

                <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->suspended = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Um den Benutzerzugang wiederherzustellen muß die <code>login->suspended</code> Eigenschaft
                    auf <code>false</code> gesetzt werden.
                </para>

            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.grantingAdminRights">
                <title>Administrative Rechte vergeben</title>

                <para>
                    Benutzern kann die Möglichkeit gegeben werden die Domain zu verwalten durch das setzen
                    Ihrer <code>login->admin</code> Eigenschaft auf <code>true</code>.
                </para>

                <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->admin = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Und wie erwartet, entfernt das Setzen der Eigenschaft <code>login->admin</code>, des
                    Benutzers auf <code>false</code>, dessen administrative Rechte.
                </para>

            </sect4>

        </sect3>

        <sect3 id="zend.gdata.gapps.users.deleting">
            <title>Löschen eines Benutzerzugangs</title>

            <para>
                Einen Benutzerzugang zu löschen zu dem man bereits ein UserEntry hat, ist so einfach wie der
                Aufruf von <code>delete()</code> auf diesem Eintrag.
            </para>

            <programlisting role="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->delete();
]]></programlisting>

            <para>
                Wenn man keinen Zugriff auf ein UserEntry Objekt für einen Zugang hat, kann die einfache
                <code>deleteUser()</code> Methode verwendet werden.
            </para>

            <programlisting role="php"><![CDATA[
$gdata->deleteUser('foo');
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.gdata.gapps.nicknames">
        <title>Mit Spitznamen interagieren</title>

        <para>
            Spitznamen arbeiten als Email Aliase für bestehende Benutzer. Jeder Spitzname enthält genau zwei
            Schlüsseleigenschaften: Seinen Namen und seinen Eigentümer. Jede Email die zu einem Spitznamen
            adressiert wurde wird zu dem Benutzer weitergeleitet der diesen Spitznamen besitzt.
        </para>

        <para>
            Spitznamen werden repräsentiert als Instanz von <classname>Zend_Gdata_Gapps_NicknameEntry</classname>.
        </para>

        <sect3 id="zend.gdata.gapps.nicknames.creating">
            <title>Erstellen eines Spitznamens</title>

            <para>
                Spitznamen können durch den Aufruf der einfachen <code>createNickname()</code> Methode
                erstellt werden:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->createNickname('foo', 'bar');
]]></programlisting>

            <para>
                Spitznamen können auch durch das instanzieren eines NichnameEntry erstellt werden, wobei der
                Spitzname mit einem Namen und einem Eigentümer ausgestattet wird, und dann
                <code>insertNickname()</code> auf einem Service Objekt aufgerufen wird, um den Eintrag zu einem
                Server hochzuladen.
            </para>

            <programlisting role="php"><![CDATA[
$nickname = $gdata->newNicknameEntry();
$nickname->login = $gdata->newLogin('foo');
$nickname->nickname = $gdata->newNickname('bar');
$nickname = $gdata->insertNickname($nickname);
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrieving">
            <title>Einen Spitznamen empfangen</title>

            <para>
                Spitznamen können durch den Aufruf der bequemen <code>retrieveNickname()</code> Methode
                empfangen werden. Sie gibt <code>null</code> zurück wenn der Benutzer nicht gefunden wurde.
            </para>

            <programlisting role="php"><![CDATA[
$nickname = $gdata->retrieveNickname('bar');

echo 'Spitzname: ' . $nickname->nickname->name . "\n";
echo 'Eigentümer: ' . $nickname->login->username . "\n";
]]></programlisting>

            <para>
                Individuelle Spitznamen können durch Erstellung einer <classname>Zend_Gdata_Gapps_NicknameQuery</classname> Instanz
                erhalten werden, indem dessen nickname Eigenschaft dem Spitznamen gleichgesetzt wird der
                empfangen werden soll, und  <code>getNicknameEntry()</code> auf einem Server Objekt mit dieser
                Abfrage aufgerufen wird.
            </para>

            <programlisting role="php"><![CDATA[
$query = $gdata->newNicknameQuery('bar');
$nickname = $gdata->getNicknameEntry($query);

echo 'Spitzname: ' . $nickname->nickname->name . "\n";
echo 'Eigentümer: ' . $nickname->login->username . "\n";
]]></programlisting>

            <para>
                Genau wie bei den Benutzern wird eine ServiceException geworfen wenn kein entsprechender
                Spitzname gefunden wurde und ein Fehlercode von <classname>Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST</classname>
                zurückgegeben. Auch das wird in <xref linkend="zend.gdata.gapps.exceptions" /> beschrieben.
            </para>

        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrievingUser">
            <title>Alle Spitznamen eines Benutzers erhalten</title>

            <para>
                Um alle Spitznamen zu erhalten die einem angegebenen Benutzer assoziiert sind, kann die
                bequeme <code>retrieveNicknames()</code> Methode aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveNicknames('foo');

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . "\n";
}
]]></programlisting>

            <para>
                Das erzeugt ein <classname>Zend_Gdata_Gapps_NicknameFeed</classname> Objekt welches jeden mit dem spezifizierten
                Benutzer assoziierten Spitznamen enthält.
            </para>

            <para>
                Alternativ setzt das Erstellen einer neuen <classname>Zend_Gdata_Gapps_NicknameQuery</classname> dessen username
                Eigenschaft auf den gewünschten Benutzer, und überträgt die Abfrage durch den Aufruf von
                <code>getNicknameFeed()</code> auf dem Service Objekt.
            </para>

            <programlisting role="php"><![CDATA[
$query = $gdata->newNicknameQuery();
$query->setUsername('foo');
$feed = $gdata->getNicknameFeed($query);

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . "\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrievingAll">
            <title>Empfangen aller Spitznamen in einer Domain</title>
            <para>
                Um alle Spitznamen in einerm Feed zu empfangen, muß einfach die bequeme Methode
                <code>retrieveAllNicknames()</code> aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveAllNicknames();

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . ' => ' .
        $nickname->login->username . "\n";
}
]]></programlisting>

            <para>
                Das wird ein <classname>Zend_Gdata_Gapps_NicknameFeed</classname> Objekt erstellen welches jeden Spitznamen in der
                Domain enthält.
            </para>

            <para>
                Alternativ kann <code>getNicknameFeed()</code> auf einem Service Objekt ohne Argumente aufgerufen
                werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->getNicknameFeed();

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . ' => ' .
        $nickname->login->username . "\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.deleting">
            <title>Löschen eines Spitznamens</title>

            <para>
                Um einen Spitznamen zu löschen zu dem man bereits einen NicknameEntry hält muß einfach nur
                <code>delete()</code> auf diesem Eintrag aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$nickname = $gdata->retrieveNickname('bar');
$nickname->delete();
]]></programlisting>

            <para>
                Für Spitznamen zu denen man keinen NicknameEntry hält, kann die bequeme
                <code>deleteNickname()</code> Methode verwendet werden.
            </para>

            <programlisting role="php"><![CDATA[
$gdata->deleteNickname('bar');
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.gdata.gapps.emailLists">
        <title>Mit Email Listen interagieren</title>

        <para>
            Email Listen erlauben verschiedenen Benutzern Emails zu empfangen die zu einer einzelnen Email
            Adresse adressiert sind. Benutzer müssen keine Teilnehmer dieser Domain sein um sich in eine
            Email Liste einzuschreiben, wen deren komplette Email Adresse (inklusive Domain) verwendet wird.
        </para>

        <para>
            Jede Email Liste einer Domain wird als Instanz von <classname>Zend_Gdata_Gapps_EmailListEntry</classname> repräsentiert.
        </para>

        <sect3 id="zend.gdata.gapps.emailLists.creating">
            <title>Erstellen einer Email Liste</title>

            <para>
                Email Listen können durch den Aufruf der bequemen <code>createEmailList()</code> Methode
                erstellt werden:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->createEmailList('friends');
]]></programlisting>

            <para>
                Email Listen können auch durch die Instanzierung von EmailListEntry erstellt werden, indem
                ein Name für die Liste angegeben wird, und anschließend <code>insertEmailList()</code> auf
                dem Service Objekt aufgerufen wird um den Eintrag zum Server hochzuladen.
            </para>

            <programlisting role="php"><![CDATA[
$list = $gdata->newEmailListEntry();
$list->emailList = $gdata->newEmailList('friends');
$list = $gdata->insertEmailList($list);
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.emailList.retrieve">
            <title>Empfangen aller Email Listen bei denen ein Empfänger eingeschrieben ist</title>

            <para>
                Um alle Email Lsiten zu denen ein spezieller Empfänger eingeschrieben ist zu empfangen, muß die
                bequeme <code>retrieveEmailLists()</code> Methode aufgerufen werden:
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveEmailLists('baz@somewhere.com');

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

            <para>
                Das erstellt ein <classname>Zend_Gdata_Gapps_EmailListFeed</classname> Objekt welches jede Email Liste enthält die
                mit dem speziellen Empfänger assoziiert ist.
            </para>

            <para>
                Alternativ kann ein neues <classname>Zend_Gdata_Gapps_EmailListQuery</classname> erstellt werden, dessen recipient
                Eigenschaft auf die gewünschte Email Adresse gesetzt werden, und die Abfrage durch den Aufruf
                von <code>getEmailListFeed()</code> auf dem Service Objekt übermittelt werden.
            </para>

            <programlisting role="php"><![CDATA[
$query = $gdata->newEmailListQuery();
$query->setRecipient('baz@somewhere.com');
$feed = $gdata->getEmailListFeed($query);

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.emailLists.retrievingAll">
            <title>Empfangen aller Email Listen in einer Domain</title>

            <para>
                Um alle Email Listen in einer Domain zu erhalten, muß die bequeme
                <code>retrieveAllEmailLists()</code> Methode aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveAllEmailLists();

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

            <para>
                Das erzeugt ein <classname>Zend_Gdata_Gapps_EmailListFeed</classname> Objekt welches jede Email Liste der Domain
                enthält.
            </para>

            <para>
                Alternativ kann <code>getEmailListFeed()</code> auf dem Service Objekt ohne Argumente aufgerufen
                werden.
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->getEmailListFeed();

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.emailList.deleting">
            <title>Löschen einer Email Liste</title>

            <para>
                Um eine Email Liste zu löschen, muß die bequeme deleteEmailList() Methode aufgerufen werden:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->deleteEmailList('friends');
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.gdata.gapps.emailListRecipients">
        <title>Mit den Empfängern von Email Listen interagieren</title>

        <para>
            Jeder Empfänger der bei einer Email Liste eingeschrieben ist, wird durch eine Instanz von
            <classname>Zend_Gdata_Gapps_EmailListRecipient</classname> repräsentiert. Durch diese Klasse können individuelle
            Empfänger hinzugefügt und von Email Listen entfernt werden.
        </para>

        <sect3 id="zend.gdata.gapps.emailListRecipients.adding">
            <title>Einen Empfängern zu einer Email Liste hinzufügen</title>

            <para>
                Um einen Empfänger zu einer Email Liste hinzuzufügen, muß einfach die bequeme
                <code>addRecipientToEmailList()</code> Methode aufgerufen werden:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->addRecipientToEmailList('bar@somewhere.com', 'friends');
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.gapps.emailListRecipients.retrieving">
            <title>Eine Liste von Empfängern einer Email Liste erhalten</title>

            <para>
                Die bequeme <code>retrieveAllRecipients()</code> Methode kann verwendet werden um die Liste
                der Empfänger einer Email Liste zu erhalten:
            </para>

            <programlisting role="php"><![CDATA[
$feed = $gdata->retrieveAllRecipients('friends');

foreach ($feed as $recipient) {
    echo '  * ' . $recipient->who->email . "\n";
}
]]></programlisting>

            <para>
                Alternativ kann ein neuer EmailListRecipientQuery erstellt werdne, dessen emailListName
                Eigenschaft auf die gewünschte Email Liste gesetzt werden, und
                <code>getEmailListRecipientFeed()</code> auf dem Service Objekt aufgerufen werden.
            </para>

            <programlisting role="php"><![CDATA[
$query = $gdata->newEmailListRecipientQuery();
$query->setEmailListName('friends');
$feed = $gdata->getEmailListRecipientFeed($query);

foreach ($feed as $recipient) {
    echo '  * ' . $recipient->who->email . "\n";
}
]]></programlisting>

            <para>
                Das Erstellt ein <classname>Zend_Gdata_Gapps_EmailListRecipientFeed</classname> Objekt welche jeden Empfänger für die
                ausgewählte Email Liste enthält.
            </para>

        </sect3>

        <sect3 id="zend.gdata.gapps.emailListRecipients.removing">
            <title>Einen Empfänger von einer Email Liste entfernen</title>

            <para>
                Um einen Empfänger von einer Email Liste zu entfernen, muß die bequeme
                <code>removeRecipientFromEmailList()</code> Methode aufgerufen werden:
                method:
            </para>

            <programlisting role="php"><![CDATA[
$gdata->removeRecipientFromEmailList('baz@somewhere.com', 'friends');
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.gdata.gapps.exceptions">
        <title>Fehler handhaben</title>

        <para>
            Zusätzlich zur Standardsuite von Ausnahmen die von <classname>Zend_Gdata</classname> geworfen werden, können Anfragen die
            die Provisionierungs API verwenden auch eine <classname>Zend_Gdata_Gapps_ServiceException</classname>
            werfen. Diese Ausnahme zeigt das ein API spezieller Fehler aufgetreten ist welche verhindert das
            die Anfrage fertiggestellt werden kann.
        </para>

        <para>
            Jede ServiceException Instanz kann einen oder mehrere Fehler Objekte enthalten. Jedes dieser
            Objekte enthalten einen Fehlercode, Grund und (optional) die Eingave welche die Ausnahme
            getriggert hat. Eine komplette Liste von bekannten Fehlercodes wird in der Zend Framework API
            Dokumentation unter <classname>Zend_Gdata_Gapps_Error</classname> angeboten. Zusätzlich ist die maßgebliche
            Fehlerliste online unter <ulink
            url="http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#appendix_d">Google
            Apps Provisioning API V2.0 Reference: Appendix D</ulink> vorhanden.
        </para>

        <para>
            Wärend die komplette Liste von Fehler die empfangen wurden in ServiceException als Array vorhanden
            sind das man durch den Aufruf von <code>getErrors()</code> erhalten kann, ist es oft bequemer
            zu wissen ob ein spezieller Fehler aufgetreten ist. Für diese Fälle kann das Vorhandensein eines
            Fehler durch den Aufruf von <code>hasError()</code> erkannt werden.
        </para>

        <para>
            Das folgende Beispiel demonstriert wie erkannt werden kann ob eine angefragte Ressource nicht
            existiert und der Fehler korrekt behandelt werden kann:
        </para>

        <programlisting role="php"><![CDATA[
function retrieveUser ($username) {
    $query = $gdata->newUserQuery($username);
    try {
        $user = $gdata->getUserEntry($query);
    } catch (Zend_Gdata_Gapps_ServiceException $e) {
        // Den Benutzer auf null setzen wen er nicht gefunden wurde
        if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
            $user = null;
        } else {
            throw $e;
        }
    }
    return $user;
}
]]></programlisting>

    </sect2>

</sect1>