home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser 2002 January / STC_CD_01_2002.iso / APP / CAT505 / DOC / CATPROTO.TXT next >
Text File  |  1997-10-26  |  10KB  |  246 lines
  1. Dokumentation zum erweiterten CAT-Messageprotokoll      (29.04.96)
  2.  
  3. CAT kann mit einem Watchdog über ein eigenes Protokoll kommunizieren.
  4. Dieses Protokoll wurde zur Version 2.0 von CAT um einiges erweitert,
  5. was aber nie komplett dokumentiert wurde. Dieses Dokument soll diese
  6. Lücke schlie₧en.
  7.  
  8. Die gesamte Kommunikation läuft über eine AES-Nachricht ab, die 
  9. Unterscheidung der einzelnen Anforderungen wird dabei über Sub-Opcodes
  10. erledigt, die im Messagebuffer abgelegt werden. Es gilt folgender
  11. grundlegener Aufbau des AES-Messagebuffers:
  12.  
  13. mess[0] = 0x8000;       (* CatMsg *)
  14. mess[1] = apId;         (* Die von CAT bzw. dem Kommunikationspartner *)
  15. mess[2] = oversize;     (* immer 0 *)
  16. mess[3] = Sub-Opcode;   (* Siehe Tabelle *)
  17. mess[4-7]: Message-spezifische Daten
  18.  
  19. Folgende Sub-Opcodes sind definiert:
  20.  
  21.   (* Sub-Opcodes für CatMsg *)
  22.  
  23.   enableWatchDog  = 0;
  24.   disableWatchDog = 1;
  25.   CatAffirm       = 2;
  26.  
  27.   CatAsk          = 3;
  28.   CatAccept       = 4;
  29.   CatForget       = 5;
  30.   CatGreetings    = 6;
  31.   CatTerminate    = 7;
  32.   CatFiltered     = 8;
  33.  
  34.   (* Sub-Opcodes für das erweiterte Protokoll: *)
  35.  
  36.   WdwManager     = 9;
  37.   CatWinInfo     = 10;
  38.   CatWhatsIn     = 11;
  39.   CatPosition    = 12;
  40.   CatNewMess     = 13;
  41.   CatInform      = 14;      (* nicht implementiert *)
  42.   CatWinDirty    = 15;      (* nicht implementiert *)
  43.  
  44.   CatProtoVersion   = 1;    (* Das ist Version Nummer 1 *)
  45.   
  46.  
  47. Die Sub-Opcodes haben dabei folgende Bedeutung:
  48.  
  49. msg[3]  msg[4]
  50.  
  51. CatGreetings
  52.  6      0       CB->Cat Anmeldung bei Cat (evtl. kommt in mess[5] noch eine 
  53.                 Unterscheidung, ob es sich um einen WatchDog handelt, also 
  54.                 dort am besten eine Null eintragen). Für etwas anderes als
  55.                 einen Watchdog darf in mess[5] keine 0 stehen.
  56.  6      version Cat-CB  Anmeldung angekommen, Protokoll-Versionsnummer zum 
  57.                 überprüfen als Anlage. 
  58.  
  59. WdwManager
  60.  9      art     ACC->Cat, Anforderung der offenen Fenster, mess[5+6] 
  61.                 enthalten eine Adresse für den Buffer, in den CAT 
  62.                 die Information hineinschreibt. mess[7] enthält die 
  63.                 Maximalanzahl an Fenstern, die in den Buffer passen 
  64.                 (pro Eintrag ein Integer, also 2 Byte)
  65.                 "art" enthält die Art der Fenster, die geliefert 
  66.                 werden sollen: 0: MsgFenster, 1: Editoren, 2: 
  67.                 Stichwortlisten
  68.                 Aktuell ist nur die Anforderung der Information über
  69.                 die MsgFenster möglich, mehr ist nicht implementiert.
  70.  9      art     Cat->ACC, offene Fenster, mess[5+6] enthält den Pointer 
  71.                 auf den Buffer, der vorher übergeben wurde. In dem Buffer
  72.                 steht die Liste der Fensterhandles, wenn das vom AES aus 
  73.                 klappt. mess[7] enthält die Anzahl der Fenster, die von 
  74.                 CAT geliefert werden.
  75.  
  76. CatWinInfo
  77. 10      whdl    ACC->Cat, Informationen anfordern. mess[5+6] enhält eine 
  78.                 Adresse, die sagt, wo die Informationen sollen , Format der 
  79.                 Information wie "winInfo" (siehe unten). mess[7] 
  80.                 enthält die Länge des Buffers in mess[5+6].
  81.                 Achtung: Das eine Wort kann dazu evtl. nicht ausreichen!
  82. 10      whdl    Cat->ACC, Information wurde geschrieben, Bufferadresse 
  83.                 wieder in mess[5+6], Länge in 7 (unverändert). 
  84.                 Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse 
  85.                 und die Länge auf 0.
  86. CatWhatsIn
  87. 11      whdl    CB->Cat, Welche Informationen werden im angegebenen Fenster 
  88.                 dargestellt? mess[5+6] enthält einen Zeiger auf folgende 
  89.                 Struktur:
  90.                  RECORD
  91.                    gruppe: CARDINAL;    (* Gruppennummer, 0 = Privat *)
  92.                    num   : CARDINAL;    (* interne Nachrichtenummer, 0-65534 *)
  93.                    size  : LONGCARD;    (* Anzahl Bytes für alle Informationen,
  94.                                          * die man mit CatWinInfo anfordern kann
  95.                                          *)
  96.                  END;
  97.                  
  98. 11      whdl    Cat->CB mess[5+6] enthält wieder den Zeiger auf obige 
  99.                 Struktur
  100.                 Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse 
  101.                 auf 0.
  102.  
  103. CatPosition
  104. 12      whdl    CB->Cat, Informationen über MsgPositionen. mess[7] gibt an, 
  105.                 um welche Art es sich handelt: 0 Neue, 1 letzte Position, 2 
  106.                 ab Datum, 3 ab Nummer. In den letzten beiden Fällen wird in 
  107.                 mess[5+6] noch eine Adresse auf einen String übergeben, der 
  108.                 das Datum bzw. die ID enthält. Er ist nullterminiert.
  109. 12      whdl    Cat->CB, mess[5] interne Msgenummer; 0xffff hei₧t: Nicht 
  110.                 gefunden
  111.  
  112. CatNewMess
  113. 13      whdl    CB->Cat, neuen Inhalt setzen: mess[5] Gruppe mess[6] interne 
  114.                 MsgNummer
  115. 13      whdl    Cat->CB mess[5] = 0 -> hat geklappt, mess[5] # 0 -> geht 
  116.                 nich..
  117.  
  118. Zu der Funktion CatWinInfo ist eine nähere Erläuterung unumgänglich. 
  119. Insbesondere kann es passieren, da₧ das eine Wort in dem Buffer nicht 
  120. ausreicht für die Gesamtanzahl der Bytes! Daher gilt zusätzlich folgendes:
  121.  
  122. Wenn die per CatWhatsIn erfragte Grö₧e nicht in ein Wort pa₧t 
  123. (d.h. > 65535 ist), dann ist der zu allozierende Buffer um 4 Byte zu 
  124. vergrö₧ern und das erste Langwort in diesem Buffer gibt dann die Grö₧e
  125. des allozierten Buffers ohne diese 4 Byte an. In der Nachricht ist in msg[7]
  126. dann eine 0 zu übergeben!
  127. CAT gibt genau diesen Buffer auch wieder zurück, d.h. auch in dem 
  128. zurückgegebenen Buffer enthalten die ersten 4 Bytes ein Langwort mit der 
  129. Gesamtlänge.
  130.  
  131. Was steht nun in diesem Buffer, nachdem CAT ihn gefüllt hat? Einiges! CAT
  132. füllt den Buffer mit der internen Nachrichtenstruktur, mit allen Headertexten
  133. und mit dem kompletten Nachrichtentext (wenn denn der Buffer gro₧ genug ist).
  134.  
  135. Das sieht dann so aus:
  136.   Nachrichtenstruktur
  137.   Infotexte         (* an nächster gerader Adresse, ggf. Füllbyte davor *)
  138.   Nachrichtentext   (* an nächster gerader Adresse, ggf. Füllbyte davor *)
  139.  
  140. Die Struktur am Anfang des Blocks ist folgende:
  141.  
  142.      MessageType = RECORD
  143.        MailNr,                      (* interne Nachrichtennummer *)
  144.        MailAnz   : CARDINAL;        (* Anzahl der Nachrichten in der Gruppe *)
  145.        KommentierteID : String255;  (* Referenz-Id (256 Bytes)              *)
  146.        fromOther : BOOLEAN;         (* Wurde die ID von der anderen Msg gelesen? *)
  147.        MailID,
  148.        Betreff,
  149.        Absender,
  150.        Empfaenger,
  151.        mid,
  152.        rid,
  153.        box,
  154.        gate,
  155.        mime,
  156.        name     : Str255Ptr; (* zeigen auf Positionen in "InfoStrings" *)
  157.        Gruppe   : CARDINAL;   (* Interne Gruppennummer *)
  158.        Datum,
  159.        StatusDatum            (* nur persönliche *)
  160.                 : DateType;
  161.        infoLen  : CARDINAL;   (* letztes Byte in <InfoStrings> *)
  162.        textLen  : CARDINAL;   (* letztes Byte im <Text> *)
  163.  
  164.        StatusBits : BITSET;   (* siehe unten *)
  165.  
  166.        up,
  167.        down,
  168.        left,                  
  169.        right  : CARDINAL;       (* interne Nummern der verknüpften Nachrichten *)
  170.        KommentarAnzahl
  171.                 : CARDINAL;
  172.        statusDate      : LONGCARD;     (* Bei persönlichen: Statusdatum im MT-Format *)
  173.        tauschDate      : LONGCARD;     (* Datum im MausTauschformat *)
  174.        EigeneNachricht : BOOLEAN;
  175.        Status : CHAR;
  176.        Text,
  177.        InfoStrings  : BigTextPtr;       (* Zeiger auf Speicherblöcke *)
  178.        distribution : tDistribution;    (* Distribution der Nachricht *)
  179.      END;
  180.  
  181. Folgende Typen werden dabei verwendet:
  182.  
  183. TYPE tDistribution = (dNone, dLokal, dMausNet, dNet);
  184.  
  185.      DateType    = ARRAY[0..18] OF CHAR;  (* Datum aus der Datenbank, 
  186.                                            * fertig formatiert als Text
  187.                                            *)
  188.  
  189.      String255   = ARRAY[0..255] OF CHAR;
  190.      Str255Ptr   = POINTER TO String255;
  191.  
  192.      BigText     = ARRAY[0..MAX(CARDINAL)] OF CHAR;
  193.      BigTextPtr  = POINTER TO BigText;
  194.  
  195. Die Statusbits sind wie folgt definiert:
  196.  
  197.       (* Statusbits einer Msg *)
  198. CONST bGelesen = 0; 
  199.       bFiltered = 1; 
  200.       bInteressant = 2; 
  201.       bTeilloeschung = 3;
  202.       bTotalloeschung = 4; 
  203.       bKommentieren = 5; 
  204.       bAntworten = 6; 
  205.       bUser1 = 7;
  206.       bUser2 = 8; 
  207.       bVererben = 9; 
  208.       bComToOwnMessage = 10;
  209.  
  210.       bOwnMessage = 14;
  211.  
  212.       bOldComToOwnMessage = 13;
  213.       (* da einige Betaversionen das so hatten, wird in einer Übergangsphase beides *)
  214.       (* erkannt und ggf. 13 entfernt und dafür 10 gesetzt *)
  215.  
  216.       (* Vorläufig bis bei der Maus die Message-Ids diesen Namen auch verdienen: *)
  217.       bOldDupe = 15;
  218.  
  219.  
  220.  
  221. Au₧erdem steht oben noch so etwas dubioses wie "Bei persönlichen: 
  222. Statusdatum im MT-Format", und das bei einem LONGCARD, dabei wei₧ doch 
  223. jeder, da₧ das Datum im MausTausch ein String ist. Mit dieser
  224. Formulierung ist folgende Codierung gemeint: 
  225.  
  226.   (* Maus-Datumsstring in ein Cat-Datum umwandeln *)
  227. Ein Maustausch-Datum hat folgendes Format:
  228.  Jahr|Jahr|Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute
  229.  
  230. Von dem Jahr wird nun 1990 abgezogen und das ganze in eine Zahl in folgendem
  231. Format gewandelt:
  232.  Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute 
  233.  
  234. Aus einem Text "199604292210" wird somit die Zahl 0604292210.
  235.  
  236. Sekundenangaben im Maustauschformat werden hierbei nicht verarbeitet.
  237.  
  238.  
  239. Und noch eine Erläuterung, und zwar zum Feld "fromOther". In diesem Feld 
  240. steht nur dann TRUE, wenn CAT beim Lesen der Nachricht die ID der kommentierten
  241. Nachricht schon aus dieser gelesen hat. Dies wird nur dann ausgeführt, wenn die 
  242. ID nicht im Header enthalten ist, d.h. kann eigentlich gar nicht mehr auftreten.
  243. Für externe Programme ist dieses Feld auch uninteressant, da die ID entweder
  244. in der Struktur vorhanden ist oder leer ist.
  245.  
  246.