Dokumentation zum erweiterten CAT-Messageprotokoll (29.04.96) CAT kann mit einem Watchdog ber ein eigenes Protokoll kommunizieren. Dieses Protokoll wurde zur Version 2.0 von CAT um einiges erweitert, was aber nie komplett dokumentiert wurde. Dieses Dokument soll diese Lcke schliežen. Die gesamte Kommunikation l„uft ber eine AES-Nachricht ab, die Unterscheidung der einzelnen Anforderungen wird dabei ber Sub-Opcodes erledigt, die im Messagebuffer abgelegt werden. Es gilt folgender grundlegener Aufbau des AES-Messagebuffers: mess[0] = 0x8000; (* CatMsg *) mess[1] = apId; (* Die von CAT bzw. dem Kommunikationspartner *) mess[2] = oversize; (* immer 0 *) mess[3] = Sub-Opcode; (* Siehe Tabelle *) mess[4-7]: Message-spezifische Daten Folgende Sub-Opcodes sind definiert: (* Sub-Opcodes fr CatMsg *) enableWatchDog = 0; disableWatchDog = 1; CatAffirm = 2; CatAsk = 3; CatAccept = 4; CatForget = 5; CatGreetings = 6; CatTerminate = 7; CatFiltered = 8; (* Sub-Opcodes fr das erweiterte Protokoll: *) WdwManager = 9; CatWinInfo = 10; CatWhatsIn = 11; CatPosition = 12; CatNewMess = 13; CatInform = 14; (* nicht implementiert *) CatWinDirty = 15; (* nicht implementiert *) CatProtoVersion = 1; (* Das ist Version Nummer 1 *) Die Sub-Opcodes haben dabei folgende Bedeutung: msg[3] msg[4] CatGreetings 6 0 CB->Cat Anmeldung bei Cat (evtl. kommt in mess[5] noch eine Unterscheidung, ob es sich um einen WatchDog handelt, also dort am besten eine Null eintragen). Fr etwas anderes als einen Watchdog darf in mess[5] keine 0 stehen. 6 version Cat-CB Anmeldung angekommen, Protokoll-Versionsnummer zum berprfen als Anlage. WdwManager 9 art ACC->Cat, Anforderung der offenen Fenster, mess[5+6] enthalten eine Adresse fr den Buffer, in den CAT die Information hineinschreibt. mess[7] enth„lt die Maximalanzahl an Fenstern, die in den Buffer passen (pro Eintrag ein Integer, also 2 Byte) "art" enth„lt die Art der Fenster, die geliefert werden sollen: 0: MsgFenster, 1: Editoren, 2: Stichwortlisten Aktuell ist nur die Anforderung der Information ber die MsgFenster m”glich, mehr ist nicht implementiert. 9 art Cat->ACC, offene Fenster, mess[5+6] enth„lt den Pointer auf den Buffer, der vorher bergeben wurde. In dem Buffer steht die Liste der Fensterhandles, wenn das vom AES aus klappt. mess[7] enth„lt die Anzahl der Fenster, die von CAT geliefert werden. CatWinInfo 10 whdl ACC->Cat, Informationen anfordern. mess[5+6] enh„lt eine Adresse, die sagt, wo die Informationen sollen , Format der Information wie "winInfo" (siehe unten). mess[7] enth„lt die L„nge des Buffers in mess[5+6]. Achtung: Das eine Wort kann dazu evtl. nicht ausreichen! 10 whdl Cat->ACC, Information wurde geschrieben, Bufferadresse wieder in mess[5+6], L„nge in 7 (unver„ndert). Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse und die L„nge auf 0. CatWhatsIn 11 whdl CB->Cat, Welche Informationen werden im angegebenen Fenster dargestellt? mess[5+6] enth„lt einen Zeiger auf folgende Struktur: RECORD gruppe: CARDINAL; (* Gruppennummer, 0 = Privat *) num : CARDINAL; (* interne Nachrichtenummer, 0-65534 *) size : LONGCARD; (* Anzahl Bytes fr alle Informationen, * die man mit CatWinInfo anfordern kann *) END; 11 whdl Cat->CB mess[5+6] enth„lt wieder den Zeiger auf obige Struktur Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse auf 0. CatPosition 12 whdl CB->Cat, Informationen ber MsgPositionen. mess[7] gibt an, um welche Art es sich handelt: 0 Neue, 1 letzte Position, 2 ab Datum, 3 ab Nummer. In den letzten beiden F„llen wird in mess[5+6] noch eine Adresse auf einen String bergeben, der das Datum bzw. die ID enth„lt. Er ist nullterminiert. 12 whdl Cat->CB, mess[5] interne Msgenummer; 0xffff heižt: Nicht gefunden CatNewMess 13 whdl CB->Cat, neuen Inhalt setzen: mess[5] Gruppe mess[6] interne MsgNummer 13 whdl Cat->CB mess[5] = 0 -> hat geklappt, mess[5] # 0 -> geht nich.. Zu der Funktion CatWinInfo ist eine n„here Erl„uterung unumg„nglich. Insbesondere kann es passieren, daž das eine Wort in dem Buffer nicht ausreicht fr die Gesamtanzahl der Bytes! Daher gilt zus„tzlich folgendes: Wenn die per CatWhatsIn erfragte Gr”že nicht in ein Wort pažt (d.h. > 65535 ist), dann ist der zu allozierende Buffer um 4 Byte zu vergr”žern und das erste Langwort in diesem Buffer gibt dann die Gr”že des allozierten Buffers ohne diese 4 Byte an. In der Nachricht ist in msg[7] dann eine 0 zu bergeben! CAT gibt genau diesen Buffer auch wieder zurck, d.h. auch in dem zurckgegebenen Buffer enthalten die ersten 4 Bytes ein Langwort mit der Gesamtl„nge. Was steht nun in diesem Buffer, nachdem CAT ihn gefllt hat? Einiges! CAT fllt den Buffer mit der internen Nachrichtenstruktur, mit allen Headertexten und mit dem kompletten Nachrichtentext (wenn denn der Buffer grož genug ist). Das sieht dann so aus: Nachrichtenstruktur Infotexte (* an n„chster gerader Adresse, ggf. Fllbyte davor *) Nachrichtentext (* an n„chster gerader Adresse, ggf. Fllbyte davor *) Die Struktur am Anfang des Blocks ist folgende: MessageType = RECORD MailNr, (* interne Nachrichtennummer *) MailAnz : CARDINAL; (* Anzahl der Nachrichten in der Gruppe *) KommentierteID : String255; (* Referenz-Id (256 Bytes) *) fromOther : BOOLEAN; (* Wurde die ID von der anderen Msg gelesen? *) MailID, Betreff, Absender, Empfaenger, mid, rid, box, gate, mime, name : Str255Ptr; (* zeigen auf Positionen in "InfoStrings" *) Gruppe : CARDINAL; (* Interne Gruppennummer *) Datum, StatusDatum (* nur pers”nliche *) : DateType; infoLen : CARDINAL; (* letztes Byte in *) textLen : CARDINAL; (* letztes Byte im *) StatusBits : BITSET; (* siehe unten *) up, down, left, right : CARDINAL; (* interne Nummern der verknpften Nachrichten *) KommentarAnzahl : CARDINAL; statusDate : LONGCARD; (* Bei pers”nlichen: Statusdatum im MT-Format *) tauschDate : LONGCARD; (* Datum im MausTauschformat *) EigeneNachricht : BOOLEAN; Status : CHAR; Text, InfoStrings : BigTextPtr; (* Zeiger auf Speicherbl”cke *) distribution : tDistribution; (* Distribution der Nachricht *) END; Folgende Typen werden dabei verwendet: TYPE tDistribution = (dNone, dLokal, dMausNet, dNet); DateType = ARRAY[0..18] OF CHAR; (* Datum aus der Datenbank, * fertig formatiert als Text *) String255 = ARRAY[0..255] OF CHAR; Str255Ptr = POINTER TO String255; BigText = ARRAY[0..MAX(CARDINAL)] OF CHAR; BigTextPtr = POINTER TO BigText; Die Statusbits sind wie folgt definiert: (* Statusbits einer Msg *) CONST bGelesen = 0; bFiltered = 1; bInteressant = 2; bTeilloeschung = 3; bTotalloeschung = 4; bKommentieren = 5; bAntworten = 6; bUser1 = 7; bUser2 = 8; bVererben = 9; bComToOwnMessage = 10; bOwnMessage = 14; bOldComToOwnMessage = 13; (* da einige Betaversionen das so hatten, wird in einer šbergangsphase beides *) (* erkannt und ggf. 13 entfernt und dafr 10 gesetzt *) (* Vorl„ufig bis bei der Maus die Message-Ids diesen Namen auch verdienen: *) bOldDupe = 15; Aužerdem steht oben noch so etwas dubioses wie "Bei pers”nlichen: Statusdatum im MT-Format", und das bei einem LONGCARD, dabei weiž doch jeder, daž das Datum im MausTausch ein String ist. Mit dieser Formulierung ist folgende Codierung gemeint: (* Maus-Datumsstring in ein Cat-Datum umwandeln *) Ein Maustausch-Datum hat folgendes Format: Jahr|Jahr|Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute Von dem Jahr wird nun 1990 abgezogen und das ganze in eine Zahl in folgendem Format gewandelt: Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute Aus einem Text "199604292210" wird somit die Zahl 0604292210. Sekundenangaben im Maustauschformat werden hierbei nicht verarbeitet. Und noch eine Erl„uterung, und zwar zum Feld "fromOther". In diesem Feld steht nur dann TRUE, wenn CAT beim Lesen der Nachricht die ID der kommentierten Nachricht schon aus dieser gelesen hat. Dies wird nur dann ausgefhrt, wenn die ID nicht im Header enthalten ist, d.h. kann eigentlich gar nicht mehr auftreten. Fr externe Programme ist dieses Feld auch uninteressant, da die ID entweder in der Struktur vorhanden ist oder leer ist.