Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File15.13.2.3  Example: no|Link's XAcc protocol                        TOS

Das no|Link-Accessory wurde für die Ansteuerung von Infrarotgeräten 
konzipiert und beinhaltet eine XAcc-Kommunikationsschicht für die 
Ansteuerung durch spezielle Applikationen. Zum momentanen Zeitpunkt 
wird das Media-Link-Interface von Catch Computer unterstützt. Eine 
weitere Anpassung an das no|Remote-Interface von no|Software ist in 
Arbeit.

Das no|Link-Accessory verwaltet alle Informationen, die zur 
Ansteuerung der verwendeten Infrarot- oder sonstiger Hardware benötigt 
werden. Jedem hardwareabhängigen Code (z.B einem Infrarotsignal) wird 
ein Befehl zugeordnet, und für jedes Gerät (z.B. Videorekorder) 
existiert eine Liste solcher Befehle.

Will nun z.B. eine Applikation für die Fernbedienung eines 
Videorekorders ein Infrarotsignal für die Play-Taste senden, so 
schickt es no|Link eine XAcc-Nachricht, in der das Kommando <senden>, 
das Gerät <VIDEOREKORDER> und der Befehl <PLAY> codiert sind.

Damit eine Applikation mit no|Link vollständig kommunizieren kann, muß 
diese das Request/Reply-Protokoll unterstützen, was als Extended- 
Feature in der XDSC-Beschreibung durch ein "RQ" bekannt gemacht wird. 
Nur so ist es möglich, die Liste der eingetragenen Geräte von no|Link 
erhalten zu können.

Wenn die Applikation auch Codes vom Accessory empfangen können will 
(nur mit entsprechender Hardware möglich), so muß als Extended-Feature 
in der XDSC-Beschreibung zusätzlich ein "RR" (Remote Receive) 
enthalten sein. Alle Applikationen, die mit noLink arbeiten wollen, 
müssen den XAcc-Level 1 unterstützen.

Als Application-Type enthält das no|Link-Accessory im XDSC "\2RC" 
(Remote Control).

Die vollständige XAcc-Identifikation von no|Link lautet zur Zeit 
folgendermaßen (in C-Syntax):

    char xaccNoLinkIdent[] =    "Infrarot Manager\0"
                                "XDSC\0"
                                "1Fernsteuerschnittstelle\0"
                                "2RC\0"
                                "XRQ\0"
                                "NnoRci\0";

Eine denkbare XAcc-Identifikation für eine no|Link-Applikation könnte 
so aussehen:

    char xaccIdentstring[] =    "VideoControl\0"
                                "XDSC\0"
                                "1Video Fernbedienung\0"
                                "XRQ\0"
                                "Nno|Video ACC\0";

Die Kommunikation zwischen Applikation und dem no|Link-Accessory 
findet hauptsächlich über ACC_TEXT Messages statt.

Das Accessory versteht zur Zeit folgende Befehle, die als String 
mittels einer ACC_TEXT Message versendet werden müssen (<X> := 
<Gerät>:<Befehl>):

 "S <X>"  Senden eines Befehls, z.B: "S VIDEO:PLAY".

 "P <X>"  Präparieren eines Befehls, z.B: "P VIDEO:PLAY". Hierbei wird 
          der Infrarot-Hardware der Code für diesen Befehl mitgeteilt, 
          aber noch nicht abgeschickt.

 "S"      Senden des zuletzt präparierten Befehls.

 "T <X>"  Test der Existenz eines Befehls.

          Insbesondere bei der Neuinstallation einer Fernsteuerungs- 
          Applikation sollten alle Geräte und Befehle, die diese 
          Applikation verwendet, dem Accessory mitgeteilt werden!

          Wenn no|Link den mitgelieferten Befehl nicht kennt, so wird 
          der Benutzer aufgefordert, die nötige "Lernprozedur" zu 
          tätigen bzw. dem neuen Befehl einen schon vorhandenen 
          zuzuweisen.

          Es sollte in jeder Fernsteuerungsapplikation eine Funktion 
          geben, die es dem Benutzer ermöglicht, alle unterstützten 
          Befehle zu "testen" - am besten über einen "Anmelden"- 
          Button.

Die Testfunktion ist die einzige, die u.U. eine Interaktion mit dem 
Benutzer führt. Alle anderen vollführen keine Ausgabe.

Als Antwort erhält die Applikation eine ACC_ACK-Message, bei der in 
msg[3] der Erfolg der Behandlung des Befehls vermerkt ist:

 1 Operation war erfolgreich

 0 Gerät/Befehl ist nicht vorhanden bzw. Fehler bei der Bearbeitung

Geräte- und Befehlsnamen dürfen maximal 32 Zeichen lang sein und 
dürfen KEINEN ':' enthalten. Es wird nicht zwischen Groß- und 
Kleinschreibung unterschieden.

Eine Applikation kann vom Accessory eine Liste der eingetragenen 
Geräte anfordern. Hierfür muß die Applikation das neue XAcc- Request/ 
Reply-Protokoll verstehen (siehe oben bzw. XACC.H).

Um die Liste anzufordern, wird von der Applikation ein ACC_REQUEST an 
das Accessory geschickt, wobei diese Nachricht folgendermaßen 
aufgebaut sein muß:

    msg[0] = ACC_REQUEST (0x480)
    msg[1] = apid
    msg[2] = 0
    msg[3] = 0x04       /* Datentyp: Code */
    msg[4] = 'D'        /* 'D' steht für "devices" */
    msg[5] = 0
    msg[6] = 0
    msg[7] = 0

Als Antwort erhält die Applikation, wenn ein Fehler auftrat eine 
ACC_ACK- Message mit msg[3] == 0, oder bei Erfolg eine ACC_REPLY- 
Message:

    msg[0] = ACC_REPLY (0x481)
    msg[1] = apid von no|Link
    msg[2] = 0
    msg[3] = 0x02       /* Datentyp: Environment-String */
    msg[4]+msg[5] = Pointer auf einen global zugreifbaren
                    Speicher, in dem die Liste der Geräte
                    in folgendem Format steht:
                    "DEVICEINFOS:\0Gerät1\0Gerät2\0"
    msg[6]+msg[7] = long-value, der die Größe des Buffers
                    angibt (inkl. der abschließenden zwei
                    NULL-Bytes)


Der Empfang einer ACC_REPLY-Message muß abschließend mit einer 
ACC_ACK- Message bestätigt werden, damit das no|Link-Accessory seine 
Resourcen wieder freigeben kann!