%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das CardDAV2XML-Paket}

    Dieses Paket erlaubt es Adressb"ucher eines CardDAV-Servers,
    z.B.  von Nextcloud\texttrademark \ oder ownCloud\texttrademark \,
    in eine XML-Datei zu speichern, welche dann z.B. von einem
    Grandstream\texttrademark \ VoIP-Telefon gelesen werden kann.
    

\section{Die Einleitung}

    In diesem Paket wurden verschiedenste PHP-Komponenten zusammengestellt,
    die zusammen ein komplettes Paket ergeben.


\section{Die Funktionen}

    Das CardDAV2XML-Paket besteht aus folgenden Komponenten:

    \begin{itemize}
         \item{CardDAV2XML} Das Hauptskript f"ur den Datenexport von
            einem CardDAV-Server in eine XML-Datei.\\
            Lizenz: MIT (Massachusetts Institute of Technology)\\
            (\url{https://github.com/jens-maus/carddav2fb})

        \item{CardDAV-PHP} Stellt die CardDAV PHP-Klassen zur Verf"ugung.\\
            Lizenz: AGPLv3 (GNU Affero General Public License)\\
            (\url{https://github.com/jens-maus/CardDAV-PHP})

        \item{Fritz!Box PHP-API} Stellt die Schnittstelle zur
            FRITZ!Box\texttrademark \ bereit.\\
            Lizenz: CC-by-SA 3.0 (Creative Commons Attribution ShareAlike)\\
            (\url{https://github.com/jens-maus/fritzbox\_api\_php})

        \item{vCard-parser} Erm"oglicht den einfachen Zugriff auf vCards.\\
            Lizenz: MIT (Massachusetts Institute of Technology)\\
            (\url{https://github.com/jens-maus/vCard-parser})
    \end{itemize}


\section{Die Lizenzen}

    Die verwendeten Dateien unterliegen den im Absatz 'Die Funktionen'
    genannten Lizenzen.


\section{Die Voraussetzungen}

    Dieses Paket ben"otigt ein installiertes php7-cli-Paket um
    funktionieren zu k"onnen.


\section{Die Installation}

    Das CardDAV2XML-Paket wird "uber das Setup-Men"u installiert. Wird
    eine "altere Paketversion vorgefunden, so wird diese deinstalliert
    bevor die neuen Programmdateien installiert werden. Nach dem
    Installieren der Programmdateien wird direkt der Konfigurations-Editor
    gestartet um die Konfiguration anzupassen. Nach Beendigung dieses
    Schrittes werden die Konfigurationsdateien generiert und alle
    ben"otigten Programme gestartet.


\section{Das Men"u im Setup-Programm}

    Das Men"u im Setup-Programm ist wie folgt aufgebaut:

    \begin{itemize}
        \item CardDAV2XML administration
        \begin{itemize}
            \item View documentation: Anzeigen der Dokumentation
            \item Edit configuration: Bearbeiten der Konfiguration
            \item Advanced configuration file handling: Konfigurationen
                verwalten
            \item Force XML file export: Dateiexport in eine XML-Datei ansto"sen
            \item View log file: Logdatei der letzten Aktualisierung ansehen
            \item Exit: Untermen"u verlassen
        \end{itemize}
    \end{itemize}

    Die Men"upunkte d"urften selbsterkl"arend sein, da sie keinerlei
    weitere Eingaben erwarten. Aus diesem Grund wird auf deren Funktion
    nicht weiter eingegangen.


\section{Die "Anderung der Konfiguration}

    Die Konfiguration kann "uber den Men"upunkt `Edit configuration'
    ge"andert werden. Standardm"a"sig wird der Editor aufgerufen, der in
    der Environment-Konfiguration "uber die Variable 'EDITOR' festgelegt
    wurde. Nachdem der Editor beendet wurde wird abgefragt, ob die
    Konfiguration aktiviert werden soll. Wird dies best"atigt, werden
    "uber ein Skript die Anpassungen umgehend wirksam gemacht.


\section{Die Konfigurationsdatei}

    In der Konfigurationsdatei, die "uber das Men"u zug"anglich ist,
    sind folgende Parameter vorhanden; wer sie von Hand editieren will
    findet sie in der Datei \texttt{/etc/config.d/carddav2xml}.


\section{Die Parameter}

\begin{description}
%%  JED - show this description only in the help file
 %  \config{CARDDAV2XML\_DO\_DEBUG (Optionaler Parameter)}{CARDDAV2XML\_DO\_DEBUG}{CARDDAV2XMLDODEBUG}
 %      Um den Debug-Modus zu aktivieren muss diese Variable lediglich auf
 %      den Wert `yes' gestellt werden, die Einstellung `no' deaktiviert
 %      den Debug-Modus.
 %
 %      G"ultige Werte: yes, no
 %
 %      Standardeinstellung: \texttt{CARDDAV2XML\_DO\_DEBUG='no'}

    \config{START\_CARDDAV2XML}{START\_CARDDAV2XML}{STARTCARDDAV2XML}
        F"ur die Aktivierung des CardDAV2XML-Programms muss dieser Parameter
        lediglich auf den Wert `yes' gestellt werden. Die Einstellung `no'
        deaktiviert das CardDAV2XML-Programm.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_CARDDAV2XML='no'}

    \config{CARDDAV2XML\_N}{CARDDAV2XML\_N}{CARDDAV2XMLN}
        "Uber diesen Parameter wird die Anzahl der erstellten
        Konfigurationen festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2XML\_N='1'}

    \config{CARDDAV2XML\_x\_ACTIVE}{CARDDAV2XML\_x\_ACTIVE}{CARDDAV2XMLxACTIVE}
        "Uber diesen Parameter wird der zugeh"orige Datensatz aktiviert
        bzw. deaktiviert.

        G"ultige Werte: yes oder no

        Standardwert: \texttt{CARDDAV2XML\_1\_ACTIVE='no'}

    \config{CARDDAV2XML\_x\_COMMENT}{CARDDAV2XML\_x\_COMMENT}{CARDDAV2XMLxCOMMENT}
        "Uber diesen Parameter kann auf Wunsch ein Kommentar eingegeben
        werden, welcher einzig der Beschreibung dieses Datensatzes dient.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{CARDDAV2XML\_1\_COMMENT='Export GS XML file'}

    \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_N}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_N}{CARDDAV2XMLxSOURCEPBOOKN}
        "Uber diesen Parameter wird die Anzahl der in eine XML-Datei
        zu exportierenden CardDAV-Adressb"ucher angegeben, welche
        "uber die folgenden Parameter definiert werden.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_N='1'}

    \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_ACTIVE}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_ACTIVE}{CARDDAV2XMLxSOURCEPBOOKyACTIVE}
        "Uber diesen Parameter wird der zugeh"orige Datensatz aktiviert
        bzw. deaktiviert.

        G"ultige Werte: yes oder no

        Standardwert: \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_ACTIVE='no'}

    \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_COMMENT}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_COMMENT}{CARDDAV2XMLxSOURCEPBOOKyCOMMENT}
        "Uber diesen Parameter kann ein Kommentar eingegeben werden,
        welcher einzig der Beschreibung dieses Datensatzes dient.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_COMMENT='Adressbuch von Frank'}

    \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_URL}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_URL}{CARDDAV2XMLxSOURCEPBOOKyURL}
        "Uber diesen Parameter wird die URL f"ur den Zugriff auf das
        gew"unschte CardDAV-Adressbuch angegeben.

        G"ultige Werte: URL

        Standardeinstellung: \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_URL=}\\
            \texttt{'https://server.local.lan/owncloud/remote.php/carddav/addressbooks}\\
            \texttt{/user/kontakte'}

%%  JED - show this description only in the help file
 %  \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_USER}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_USER}{CARDDAV2XMLxSOURCEPBOOKyUSER}
 %      "Uber diese Parameter werden der f"ur den Zugriff auf das
 %      CardDAV-Adressbuch ben"otigte Login und das zugeh"orige Kennwort
 %      angegeben.\\\\
 %      \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}
 %
 %      G"ultige Werte: Username bzw. Kennwort
 %
 %      Beispiel:
 %
 %      \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_USER='frank'\\
 %              CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_PASS='geheim'}

    \index{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_USER}
    \config{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_USER / CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_PASS}{CARDDAV2XML\_x\_SOURCE\_PBOOK\_y\_PASS}{CARDDAV2XMLxSOURCEPBOOKyPASS}
        "Uber diese Parameter werden der f"ur den Zugriff auf das
        CardDAV-Adressbuch ben"otigte Login und das zugeh"orige Kennwort
        angegeben.\\\\
        \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}

        G"ultige Werte: Benutzername bzw. Kennwort

        Beispiel:

        \texttt{CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_USER='frank'\\
                CARDDAV2XML\_1\_SOURCE\_PBOOK\_1\_PASS='geheim'}

    \config{CARDDAV2XML\_x\_OUTPUT\_FORMAT}{CARDDAV2XML\_x\_OUTPUT\_FORMAT}{CARDDAV2XMLxOUTPUTFORMAT}
        "Uber diesen Parameter wird das gew"unschte Ausgabeformat der
        Adressdaten bestimmt. Zur Auswahl stehen die folgenden drei
        Formate:\\

        G"ultige Werte:\\

        \begin{itemize}
            \item{console} Ausgabe auf die Standardkonsole.
            \item{grandstream} Ausgabe im Grandstream\texttrademark \ XML-Format.
            \item{slims} Ausgabe im Logitech\texttrademark \ Mediaserver Dateiformat.
        \end{itemize}

        Beispiel: \texttt{CARDDAV2XML\_1\_OUTPUT\_FORMAT='grandstream'}

    \config{CARDDAV2XML\_x\_OUTPUT\_FILE}{CARDDAV2XML\_x\_OUTPUT\_FILE}{CARDDAV2XMLxOUTPUTFILE}
        "Uber diesen Parameter wird der absolute Pfad zur gew"unschten
        Ausgabedatei festgelegt.

        G"ultige Werte: absoluter Pfad und Dateiname

        Beispiel: \texttt{CARDDAV2XML\_1\_OUTPUT\_FILE='/var/www/htdocs/grandstream/phonebook.xml'}

    \config{CARDDAV2XML\_x\_OUTPUT\_FILE\_ACCESS}{CARDDAV2XML\_x\_OUTPUT\_FILE\_ACCESS}{CARDDAV2XMLxOUTPUTFILEACCESS}
        "Uber diesen Parameter werden die zu setzenden Dateizugriffsrechte
        f"ur die Ausgabedatei festgelegt. Es werden drei durch einen
        Doppelpunkt getrennte Informationen ben"otigt, erst der Name
        eines Systembenutzer, dann der Name einer Systemgruppe und
        abschlie"send die Dateizugriffsrechte.\\
        Wird dieser Parameter nicht gesetzt, so wird standardm"a"sig
        die Einstellung `root:root:0644' verwendet.

        G"ultige Werte: Systembenutzer:Systemgruppe:Zugriffsrechte

        Beispiel: \texttt{CARDDAV2XML\_1\_OUTPUT\_FILE\_ACCESS='wwrun:nogroup:0444'}

    \config{CARDDAV2XML\_x\_DIAL\_PREFIX\_SEARCH}{CARDDAV2XML\_x\_DIAL\_PREFIX\_SEARCH}{CARDDAV2XMLxDIALPREFIXSEARCH}
        "Uber diesen Parameter wird das regul"are Suchmuster festgelegt,
        welches zum Auffinden des Rufnummernprefixes verwendet werden 
        soll.

        G"ultige Werte: regul"arer Ausdruck

        Standardwert: \texttt{CARDDAV2XML\_1\_DIAL\_PREFIX\_SEARCH='/\^{}+49[\^{}0-9]*/'}

    \config{CARDDAV2XML\_x\_DIAL\_PREFIX\_REPLACE}{CARDDAV2XML\_x\_DIAL\_PREFIX\_REPLACE}{CARDDAV2XMLxDIALPREFIXREPLACE}
        "Uber diesen Parameter wird festgelegt durch welche Ziffer der
        Rufnummernprefix ersetzt werden soll.

        G"ultige Werte: Ziffern

        Standardwert: \texttt{CARDDAV2XML\_1\_DIAL\_PREFIX\_REPLACE='0'}

    \config{CARDDAV2XML\_x\_ABOOK\_GROUP\_N}{CARDDAV2XML\_x\_ABOOK\_GROUP\_N}{CARDDAV2XMLxABOOKGROUPN}
        "Uber diesen Parameter wird die Anzahl der zu exportierenden
        Adressbuchgruppen festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2XML\_1\_ABOOK\_GROUP\_N='4'}

    \config{CARDDAV2XML\_x\_ABOOK\_GROUP\_y\_ACTIVE}{CARDDAV2XML\_x\_ABOOK\_GROUP\_y\_ACTIVE}{CARDDAV2XMLxABOOKGROUPyACTIVE}
        "Uber diesen Parameter wird der zugeh"orige Datensatz aktiviert
        bzw. deaktiviert.

        G"ultige Werte: yes oder no

        Standardwert: \texttt{CARDDAV2XML\_1\_ABOOK\_GROUP\_1\_ACTIVE='no'}

    \config{CARDDAV2XML\_x\_ABOOK\_GROUP\_y\_NAME}{CARDDAV2XML\_x\_ABOOK\_GROUP\_y\_NAME}{CARDDAV2XMLxABOOKGROUPyNAME}
         "Uber diesen Parameter wird der Name einer zu exportierenden
         Adressbuchgruppe angegeben.

        G"ultige Werte: Adressbuchgruppenname

        Beispiel:
        
        \texttt{CARDDAV2XML\_1\_ABOOK\_GROUP\_1\_NAME='Alle'\\
                CARDDAV2XML\_1\_ABOOK\_GROUP\_2\_NAME='Arbeit'\\
                CARDDAV2XML\_1\_ABOOK\_GROUP\_3\_NAME='Privat'\\
                CARDDAV2XML\_1\_ABOOK\_GROUP\_4\_NAME='zu Hause'}

    \config{CARDDAV2XML\_x\_DEFAULT\_DIALLINE (Optionaler Parameter}{CARDDAV2XML\_x\_DEFAULT\_DIALLINE}{CARDDAV2XMLxDEFAULTDIALLINE}
        "Uber diesen optionalen Parameter kann auf Wunsch die standardm"a"sig
        zu verwendende Leitungsnummer angegeben werden, die z.B. von einem
        Grandstream\texttrademark-VoIP-Telefon f"ur den Rufaufbau verwendet
        werden soll.

        G"ultige Werte: Zahl

        Standardwert: \texttt{CARDDAV2XML\_1\_DEFAULT\_DIALLINE=$''$}

    \config{CARDDAV2XML\_x\_CONTACT\_N}{CARDDAV2XML\_x\_CONTACT\_N}{CARDDAV2XMLxCONTACTN}
        "Uber diesen Parameter wird die Anzahl der zu einer exportierten
        Datei hinzuzuf"ugenden Adressbucheintr"age festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2XML\_1\_CONTACT\_N='1'}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_ACTIVE}{CARDDAV2XML\_x\_CONTACT\_y\_ACTIVE}{CARDDAV2XMLxCONTACTyACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der
        zugeh"orige Datensatz aktiviert, `no' deaktiviert ihn.

        G"ultige Werte: yes oder no

        Standardwert: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_ACTIVE='no'}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_NUMBER}{CARDDAV2XML\_x\_CONTACT\_y\_NUMBER}{CARDDAV2XMLxCONTACTyNUMBER}
        "Uber diesen Parameter wird die Rufnummer des hinzuzuf"ugenden
        Adressbucheintrages festgelegt.

        G"ultige Werte: g"ultige Rufnummer

        Beispiel: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_NUMBER='**622'}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_FNAME}{CARDDAV2XML\_x\_CONTACT\_y\_FNAME}{CARDDAV2XMLxCONTACTyFNAME}
        "Uber diesen Parameter wird der Vorname des hinzuzuf"ugenden
        Adressbucheintrages festgelegt.

        G"ultige Werte: Vorname

        Beispiel: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_FNAME='Birgit'}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_LNAME}{CARDDAV2XML\_x\_CONTACT\_y\_LNAME}{CARDDAV2XMLxCONTACTyLNAME}
        "Uber diesen Parameter wird der Nachname des hinzuzuf"ugenden
        Adressbucheintrages festgelegt.

        G"ultige Werte: Nachname

        Beispiel: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_FNAME='Wichtig'}

%   \config{CARDDAV2XML\_x\_CONTACT\_y\_TYPE}{CARDDAV2XML\_x\_CONTACT\_y\_TYPE}{CARDDAV2XMLxCONTACTyTYPE}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_GROUP}{CARDDAV2XML\_x\_CONTACT\_y\_GROUP}{CARDDAV2XMLxCONTACTyGROUP}
        "Uber diesen Parameter wird der Adressbuchgruppenname
        des hinzuzuf"ugenden Adressbucheintrages festgelegt.

        G"ultige Werte: Name einer Adressbuchgruppe

        Beispiel: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_GROUP='zu Hause'}

    \config{CARDDAV2XML\_x\_CONTACT\_y\_DIALLINE}{CARDDAV2XML\_x\_CONTACT\_y\_DIALLINE}{CARDDAV2XMLxCONTACTyDIALLINE}
        "Uber diesen Parameter wird die zu verwendende Leitungsnummer
        angegeben, die z.B. von einem Grandstream\texttrademark-VoIP-
        Telefon f"ur den Rufaufbau verwendet werden soll.

        G"ultige Werte: Zahl

        Standardwert: \texttt{CARDDAV2XML\_1\_CONTACT\_1\_DIALLINE='0'}

    \config{CARDDAV2XML\_x\_CRON\_SCHEDULE}{CARDDAV2XML\_x\_CRON\_SCHEDULE}{CARDDAV2XMLxCRONSCHEDULE}
        "Uber diesen Parameter wird festgelegt zu welchem Zeitpunkt
        bzw. in welchem Intervall automatisch ein Adressbuchabgleich
        durchgef"uhrt werden sollen. Die f"unf Teilparameter haben dabei
        folgende Bedeutung:\\
        1 - Minuten, 2 - Stunden, 3 - Tag des Monats, 4 - Monat, 5 - Wochentag.

        D.h. bei Verwendung der Standardeinstellung wird jeden Sonntag
        um 00:15h das FRITZ!Box\texttrademark-Adressbuch durch den
        Inhalt des CardDAV- Adressbuchs "uberschrieben. Wer N"aheres
        "uber die verwendete Befehlssyntax erfahren m"ochte, sollte
        "uber eine Internet-Suchmaschine nach `man' und `crontab'
        suchen.

        G"ultige Werte: Crontab-spezifischer Parametereintrag

        Standardeinstellung: \texttt{CARDDAV2XML\_1\_CRON\_SCHEDULE='15 0 * * 0'}

    \config{CARDDAV2XML\_x\_CRON\_POST\_EXEC}{CARDDAV2XML\_x\_CRON\_POST\_EXEC}{CARDDAV2XMLxCRONPOSTEXEC}
        "Uber diesen Parameter kann auf Wunsch ein Befehl angegeben
        werden, der direkt im Anschluss an einen Dateiexport ausgef"uhrt
        werden soll, um z.B. die erzeugte Datei automatisiert auf
        einen anderen Server zu kopieren.

        G"ultige Werte: absoluter Befehlspfad

        Beispiel: \texttt{CARDDAV2XML\_1\_CRON\_POST\_EXEC='/usr/bin/copy-phonebook-to-server.sh'}
\end{description}
