home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ST-Computer Leser 2002 January
/
STC_CD_01_2002.iso
/
APP
/
CAT505
/
DOC
/
CATPROTO.TXT
next >
Wrap
Text File
|
1997-10-26
|
10KB
|
246 lines
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
Lücke 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 für CatMsg *)
enableWatchDog = 0;
disableWatchDog = 1;
CatAffirm = 2;
CatAsk = 3;
CatAccept = 4;
CatForget = 5;
CatGreetings = 6;
CatTerminate = 7;
CatFiltered = 8;
(* Sub-Opcodes für 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). Für etwas anderes als
einen Watchdog darf in mess[5] keine 0 stehen.
6 version Cat-CB Anmeldung angekommen, Protokoll-Versionsnummer zum
überprüfen als Anlage.
WdwManager
9 art ACC->Cat, Anforderung der offenen Fenster, mess[5+6]
enthalten eine Adresse für 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 für 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 für 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 zurück, d.h. auch in dem
zurückgegebenen Buffer enthalten die ersten 4 Bytes ein Langwort mit der
Gesamtlänge.
Was steht nun in diesem Buffer, nachdem CAT ihn gefüllt hat? Einiges! CAT
füllt 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. Füllbyte davor *)
Nachrichtentext (* an nächster gerader Adresse, ggf. Füllbyte 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 <InfoStrings> *)
textLen : CARDINAL; (* letztes Byte im <Text> *)
StatusBits : BITSET; (* siehe unten *)
up,
down,
left,
right : CARDINAL; (* interne Nummern der verknüpften 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 dafür 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 ausgeführt, wenn die
ID nicht im Header enthalten ist, d.h. kann eigentlich gar nicht mehr auftreten.
Für externe Programme ist dieses Feld auch uninteressant, da die ID entweder
in der Struktur vorhanden ist oder leer ist.