%
% yowsup.tex
% Last Update: $Id$
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Kapitel Yowsup %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Das Yowsup-Paket}

\section{Die Einleitung}

    Yowsup erlaubt den Zugriff auf den Wh***App-Service von der Kommandozeile.
    Es handelt sich dabei um eine Python-Bibliothek welche das Erstellen
    von Anwendungen erlaubt die auf den Wh***App-Service zugreifen k"onnen.


\section{Die Funktionen}

    Das Yowsup-Paket besteht aus folgender Komponente:

    \begin{itemize}
        \item yowsup - Das Python-Programmpaket.\\
              (\url{https://github.com/tgalal/yowsup})
    \end{itemize}


\section{Die Voraussetzungen}

    Zur korrekten Funktion ist die Installation diverser Python-Pakete
    erforderlich, welche automatisch mitinstalliert werden, falls sie
    nicht auf der Festplatte gefunden werden.


\section{Die Installation}

    Das Yowsup-Paket wird "uber das Setup-Men"u installiert. Wird
    eine "altere Paketversion vorgefunden, so wird diese deinstalliert
    bevor die neuen Programmdateien installiert werden.


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

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

    \begin{itemize}
        \item View documentation: Anzeigen der Dokumentation
        \item Edit configuration: Bearbeiten der Konfiguration
        \item Advanced configuration file handling: Konfigurationen verwalten
        \item Send test message: Eine Testnachricht versenden
        \item Start Yosup Client: Das Yowsup Klientenprogramm starten
        \item Return: Untermen"u verlassen
    \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 unter /etc/config.d/yowsup.

\section{Die Parameter}

\begin{description}
%%  JED - show this description only in the help file
%  \config{YOWSUP\_DO\_DEBUG}{YOWSUP\_DO\_DEBUG}{YOWSUPDODEBUG}
%      Optionaler Parameter: Um den Debug-Modus zu aktivieren muss dieser
%      Parameter auf den Wert `yes' gesetzt werden. Um den Debug-Modus zu
%      deaktivieren  muss der Wert auf `no' gesetzt werde.
%
%      G"ultige Werte: yes, no
%
%      Standardeinstellung: \texttt{YOWSUP\_DO\_DEBUG='no'}

    \config{START\_YOWSUP}{START\_YOWSUP}{STARTYOWSUP}
       Um das Yowsup-Paket zu aktivieren muss dieser Parameter auf den Wert
       `yes' gesetzt werden. Um das Yosup-Paket zu deaktivieren muss der Wert
       auf `no' gesetzt werde.

       G"ultige Werte: yes, no

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

    \config{YOWSUP\_CCODE}{YOWSUP\_CCODE}{YOWSUPCCODE}
        "Uber diesen Parameter wird die zur Telefonnummer geh"orige
        Landesvorwahl festgelegt.

        G"ultige Werte: Landesvorwahlen ohne f"uhrende Nullen, z.B. 31, 32,
                        33, 34, 351, 352, 41, 420, 423, 43, 44, 48, 49

        Standardeinstellung: \texttt{YOWSUP\_CCODE='49'}

    \config{YOWSUP\_PHONE}{YOWSUP\_PHONE}{YOWSUPPHONE}
        "Uber diesen Parameter wird die zu verwendende Telefonnummer, inklusive
        der "uber den Parameter \jump{YOWSUPCCODE}{YOWSUP\_CCODE} festgelegten
        Landesvorwahl, festgelegt. Ein f"uhrendes Pluszeichen ('+') oder f"uhrende
        Nullen ('00') sind nicht zugelassen.

        G"ultige Werte: Telefonnummer inkl. der Landesvorwahl

        Beispiel: \texttt{YOWSUP\_PHONE='49123456789'}

    \config{YOWSUP\_PASS}{YOWSUP\_PASS}{YOWSUPPASS}
        "Uber diesen Parameter wird das im Zuge des Konfigurationsprozesses
        ermittelte Kennwort festgelegt, welches f"ur die Anmeldung an Wh***App
        erforderlich ist.

        G"ultige Werte: Kennwort

        Standardeinstellung: \texttt{YOWSUP\_PASS=$''$}
\end{description}

\section{Verschiedenes}

\begin{description}
    \config{Der Registierungsprozess}{Der Registierungsprozess}{DerRegistierungsprozess}
        Um das Programm verwenden zu k"onnen, ist eine einmalige
        Wh***App-Registrierung notwendig. Hierzu m"ussen folgende
        Schritte abgearbeitet werden.\\
        Hinweis: Bei der Erstellung der folgenden Beschreibung wurde
        auf Informationen von folgender Webseite zur"uck gegriffen:\\
        http://www.johannespetz.de/yowsup-cli-linux-whatsapp-
               nachrichten-verschicken/

        \begin{itemize}
            \item[1.] Im ersten Schritt m"ussen in der Konfigurationsdatei
                      die Parameter YOWSUP\_CCODE und YOWSUP\_PHONE gesetzt
                      werden. Der Parameter YOWSUP\_PASS bleibt anfangs leer.

            \item[2.] Danach muss mit Hilfe des yowsup-cli-Programms die
                      Mobilfunknummer registriert werden, welche f"ur den
                      Zugriff auf Wh***App verwendet werden soll. Dazu
                      erh"alt man einen SMS Freischaltungskode, der von
                      Wh***App an die "uber den Parameter YOWSUP\_PHONE
                      festgelegte Rufnummer geschickt wird.
                      Hierzu gibt man den folgenden an der Konsole ein,
                      welche eine "ahnlich geartete Ausgabe erzeugt:

                      \begin{verbatim}
# yowsup-cli registration --config /root/.yowsup-config
      --requestcode sms

Antwort: INFO:yowsup.common.http.warequest:{"status":"sent",
         "length":6,"method":"sms","retry_after":1805}

          status: sent
          retry_after: 1805
          length: 6
          method: sms
                      \end{verbatim}

            \item[3.] Nach kurzer Zeit sollte eine SMS mit dem ben"otigten
                      Freischaltungskode auf dem Telefon eingegangen sein.
                      Dieser Freischaltungskode muss nun "uber die Kommandozeile
                      best"atigt werden. Die `000-000' steht hierbei f"ur den
                      "ubermittelten Freischaltungskode.\\
                      \achtung{Unbedingt das Kennwort merken (pw: ...)!}

                      \begin{verbatim}
# yowsup-cli registration --config /root/.yowsup-config
      --register 000-000

Antwort: INFO:yowsup.common.http.warequest:{"status":"ok",
         "login":"4912345678987","pw":"AAAaaaBBBbbbCCCccc",
         "type":"new","expiration":1483019354,"kind":"free",
         "price":"0,89\u20ac","cost":"0.89","currency":"EUR",
         "price_expiration":1454669732}

         status: ok
         kind: free
         pw: AAAaaaBBBbbbCCCccc
         price: 0,89 EUR
         price_expiration: 1454669732
         currency: EUR
         cost: 0.89
         expiration: 1483019354
         login: 4912345678987
         type: new
                      \end{verbatim}

                      Die beiden Ablaufdaten (expiration dates) lassen
                      sich auf einfache Weise mittels des date-Befehls
                      in ein lesbares Format konvertieren. Im Beispiel
                      ergeben sich folgenden Daten f"ur die G"ultigkeit
                      des angezeigten Preises und die des Kontos:

                      \begin{verbatim}
price_expiration: # date --date=@1454669732
                  Fri Feb  5 11:55:32 CET 2016

expiration: # date --date=@1483019354
            Thu Dec 29 14:49:14 CET 2016
                      \end{verbatim}

            \item[4.] Nachdem der Registrierungbefehl abgesandt und die
                      Authentifizierung durchgef"uhrt wurde, zeigt die Ausgabe
                      ein Kennwort (pw:) an, welches man nun "uber den Parameter
                      YOWSUP\_PASS in die Konfiguration eintr"agt.
        \end{itemize}

    \config{Das Yowsup-Klientenprogramm}{Das Yowsup-Klientenprogramm}{DasYowsupKlientenprogramm}
        "Uber das Men"u bzw. die Kommandozeile kann das
        Yowsup-Klientenprogramm (yowsup-cli) gestartet werden.
        Beendet wird das Programm mittels CTRL-C.

        Der Kommandozeilenbefehl lautet hierbei:
        \begin{verbatim}
# yowsup-cli demos --config /root/.yowsup-config --yowsup
        \end{verbatim}

        Sobald der Client gestartet wurde, kann man diesen mit bestimmten
        Kommandos bedienen. "Uber das Kommand `/help' erh"alt man z.B.
        folgende Ausgabe:

        \begin{verbatim}
Yowsup Cli client
=================
Type /help for available commands

[offline]:/help
----------------------------------------------
/account    delete                           Delete your account
/group      participants [group_jid]         Get pariticipants in
                                             a group
/group      setSubject   [jid] [subject]     Change group subject
/help                                        Print this message
/seq                                         Send init seq
/contacts   sync         [contacts]          Sync contacts, contacts
                                             should be comma separated
                                             phone numbers, with no
                                             spaces
/keys       set                              Send prekeys
/keys       get          [jid]               Get shared keys
/presence   available                        Set presence as available
/presence   subscribe    [contact]           Subscribe to contact's
                                             presence updates
/presence   unsubscribe  [contact]           Unsubscribe from
                                             contact's presence
                                             updates
/presence   name         [name]              Set presence name
/presence   unavailable                      Set presence as
                                             unavailable
/ping                                        Ping server
/L                                           Quick login
/state      paused       [jid]               Send paused state
/state      typing       [jid]               Send typing state
/groups     create       [subject]           Create a new group with
                                             the specified subject
/groups     list                             List all groups you
                                             belong to
/test                                        halawa
/disconnect                                  Disconnect
/login                   [username] [b64password]
                                             Login to WhatsApp
/ib         clean        [dirtyType]         Send clean dirty
/message    broadcast    [numbers] [content] Broadcast message.
                                             Numbers should be comma
                                             separated phone numbers
/message    send         [number] [content]  Send message to a friend
----------------------------------------------
[offline]:
        \end{verbatim}

        Mit `/L' kann man sich in den angegebenen Account einloggen.

        Nachrichten werden automatisch empfangen und k"onnen gelesen
        werden, allerdings ohne Nicknamen. Es werden immer nur die
        Telefonnummer angezeigt.

    \config{Das Yowsup-Kommandozeilenprogramm}{Das Yowsup-Kommandozeilenprogramm}{DasYowsupKommandozeilenprogramm}
        Um von der Kommandozeile Nachrichten direkt zu versenden, z.B.
        aus einem Monitorprogramm heraus, gibt man folgenden Befehl
        ein.

        \begin{verbatim}
# yowsup-cli demos --config /root/.yowsup-config
      --send 49<Telefonnummer> 'Hallo Welt'
        \end{verbatim}

        Hinweis: Beim erstmaligen Aufruf dieses Befehls werden erst
        noch Schl"usseldateien erzeugt, welches dann im Verzeichnis
        /root/.yowsub abgelegt werden. Der Befehl erzeugt dabei
        eine "ahnlich geartete Ausgabe:

        \begin{verbatim}
# yowsup-cli demos --config /root/.yowsup-config
      --send 49<Telefonnummer> 'Hallo Welt'

Ausgabe: INFO:yowsup.layers.axolotl.layer:Axolotl layer
         is generating keys
        \end{verbatim}
\end{description}
