home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser 2002 January / STC_CD_01_2002.iso / APP / CAT505 / DOC / NEWPROTO.TXT < prev   
Text File  |  2000-10-30  |  11KB  |  318 lines
  1.  
  2.  
  3. Neues Protokoll für CAT
  4. ***********************
  5.  
  6. In CAT 3.0 gibt es ein neues Protokoll, um Informationen zur gerade
  7. angezeigten Nachricht abzufragen.
  8.  
  9. Basisnachricht:
  10.  
  11. 0x8003
  12.  
  13. Aufbau:
  14.  
  15. msgbuf[0] = 0x8003; (* Message-ID *)
  16. msgbuf[1] = apId;   (* CAT bzw. Kommunikationspartner, Absender halt *)
  17. msgbuf[2] = 0;      (* Oversize, immer 0 *)
  18. msgbuf[3] = sub-opcode;
  19. msgbuf[4+5] = Länge des Buffers;
  20. msgbuf[6+7] = Adresse des Buffers;
  21.  
  22. Die Kommunikation läuft hauptsächlich unidirectional ab, d.h. eine
  23. Applikation fordert etwas an und CAT antwortet. Nur sehr wenige Nachrichten
  24. werden von CAT unaufgefordert verschickt.
  25.  
  26. Prinzipiell läuft es so: Die Applikation möchte etwas wissen und fragt bei
  27. CAT nach. Dazu übergibt es einen Buffer und die Länge dieses Buffers. CAT
  28. kopiert die gewünschte Information in den Buffer. Da man teilweise auch
  29. variabel lange Daten abfragen möchte, gibt es folgende Möglichkeit: Das ACC
  30. fragt mit Bufferlänge 0 an und erhält als Antwort in der Bufferlänge die
  31. notwendige Länge des Buffers, um die gewünschte Information aufnehmen zu
  32. können. Da die Länge, die CAT zurückliefert, die reine Länge der Daten ist,
  33. sollte man noch ein Byte für das anhängenden Nullzeichen als Stringabschlu₧
  34. hinzurechnen. Bei einer Länge von 0 ist die Information nicht verfügbar.
  35. Man kann sie trotzdem abfragen, erhält aber halt einen leeren String
  36. zurück. Nach der Längenabfrage kann die andere Applikation mit einem
  37. passend allozierten Buffer nochmal anfragen. Der Buffer mu₧ unter Systemen
  38. mit memory protection von CAT beschreibbar sein. CAT selber stellt keinen
  39. Buffer dafür zur Verfügung.
  40.  
  41. Sollte der übergebene Buffer für die Daten nicht ausreichen, so gibt CAT
  42. keinerlei Daten zurück, sondern liefert eine ERROR-Antwort zurück.
  43.  
  44. Dieses Protokoll sollte auch für andere Frontends (namentlich: THE_DOT)
  45. implementierbar sein, da auch eine Teilimplementation mit den notwendigen
  46. Funktionen z.B. für CATalog möglich ist. Dafür reicht es, die An- und
  47. Abmeldung zu implementieren und die Abfragen für Name, Betreff und Gruppe.
  48.  
  49. Alle Werte bis auf die apId sind übrigens unsigned!
  50.  
  51. Folgende Sub-Opcodes sind definiert:
  52.  
  53. 00:     ACKNOWLEDGE (kein Buffer)
  54. 01:     ERROR (kein Buffer)
  55. 02:     Anmeldung bei CAT
  56. 03:     Abmeldung bei CAT
  57. 04:     Abfrage Absender
  58. 05:     Abfrage Realname
  59. 06:     Abfrage Empfänger
  60. 07:     Abfrage MsgId (#-Zeile)
  61. 08:     Abfrage lange MsgId (I-Zeile)
  62. 09:     Abfrage '-'-Zeile
  63. 10:     Abfrage Ref-Id (R-Zeile)
  64. 11:     Abfrage Stichwort
  65. 12:     Abfrage Organization (O-Zeile)
  66. 13:     Abfrage Gateway (Y-Zeile)
  67. 14:     Abfrage Distribution (D-Zeile)
  68. 15:     Abfrage Mime (M-Zeile)
  69. 16:     Abfrage Status persönliche Nachricht
  70. 17:     Abfrage Followup-To (F-Zeile)
  71. 18:     Abfrage Reply-To
  72. 19:     Abfrage Message-Text
  73. 20:     Abfrage Message-Datum
  74. 21:     Abfrage Status-Datum
  75. 22:     Abfrage Gruppe
  76. 23:     Abfrage Originaltext, wie in Datenbank gespeichert
  77. 24:     Abfrage eigene Nachricht
  78. 25:     Abfrage eindeutige Id
  79. 26:     Abfrage Absender aus Sender-Zeile
  80. 27:     Abfrage Absendername im Fenster
  81. 28:     Abfrage voller Message-Text
  82. 100:    Neue Nachricht in Fenster (CAT => ACC)
  83. 101:    CAT wird beendet
  84.  
  85. Weitere Sub-Opcodes werden bei Bedarf eingeführt.
  86.  
  87. Einige Sub-Opcodes sind zwar definiert und werden von CAT auch bearbeitet,
  88. aber da die Daten nicht vorhanden sind, wird immer 0 als Länge
  89. zurückgegeben und keine Daten. Dies betrifft insbesondere Followup-To und
  90. teilweise ReplyTo.
  91.  
  92. Im folgenden werden die Sub-opcodes etwas genauer beschrieben:
  93.  
  94. 00: ACKNOWLEDGE
  95.  
  96. Das ist die Antwort von CAT auf die An-/Abmeldung vom ACC, wenn diese
  97. geklappt hat. Ansonsten bekommt das ACC ERROR zurück. msgbuf[4-7] sind 0,
  98. da kein Buffer übergeben wird.
  99.  
  100. 01: ERROR
  101.  
  102. Das ist die Antwort von CAT auf die An-/Abmeldung vom ACC, wenn diese nicht
  103. geklappt hat. Dürfte nur bei extremen Speichermangel passieren. Au₧erdem
  104. wird ERROR bei jeder nicht implementierten Funktion zurückgegeben.
  105. msgBuf[4] enthält den sub-opcode, der zu dem Fehler führte. msgbuf[5-7]
  106. sind 0.
  107.  
  108. 02: Anmeldung bei CAT
  109.  
  110. Dies schickt ein ACC an CAT zur Anmeldung. Damit wird es über
  111. Nachrichtenwechsel automatisch informiert und kann die Informationen dann
  112. von CAT abfragen. msgbuf[4-7] sind 0, da kein Buffer übergeben wird.
  113.  
  114. 03: Abmeldung bei CAT
  115.  
  116. Damit meldet sich ein ACC wieder bei CAT ab. Das ACC wird aus der Liste der
  117. beteiligten Empfänger ausgetragen und erhält als Antwort ein ACKNOWLEDGE.
  118. msgbuf[4-7] sind 0, da kein Buffer übergeben wird.
  119.  
  120. Die folgenden Funktionen sind alles Abfrage-Funktionen, die ein Element
  121. einer Nachricht abfragen können. Bei allen Elementen ist es möglich, das
  122. CAT nichts zurückliefert. In dem Fall wird in dem Buffer einfach ein leerer
  123. String zurückgegeben. Wenn nur die Länge abgefragt wird durch eine
  124. übergebene Bufferlängee von 0, gibt CAT auch eine 0 als Länge zurück. Die
  125. Antwort besteht immer aus der gleichen Nachricht wie die Anfrage.
  126.  
  127. 04: Abfrage Absender
  128.  
  129. Absender der Nachricht, falls vorhanden (Mailadresse).
  130.  
  131. 05: Abfrage Realname
  132.  
  133. Realname des Absenders, falls vorhanden.
  134.  
  135. 06: Abfrage Empfänger
  136.  
  137. Empfänger der Nachricht, falls vorhanden (meistens nur bei PMs)
  138.  
  139. 07: Abfrage MsgId (#-Zeile)
  140.  
  141. Message-Id aus der #-Zeile, ist immer vorhanden
  142.  
  143. 08: Abfrage lange MsgId (I-Zeile)
  144.  
  145. Lange Message-Id, meistens vorhanden
  146.  
  147. 09: Abfrage '-'-Zeile
  148.  
  149. Verkettung nach oben
  150.  
  151. 10: Abfrage Ref-Id (R-Zeile)
  152.  
  153. Verkettung über lange Id
  154.  
  155. 11: Abfrage Stichwort
  156.  
  157. Stichwort der Nachricht, kann auch leer sein.
  158.  
  159. 12: Abfrage Organization (O-Zeile)
  160.  
  161. O-Zeile aus Outfile
  162.  
  163. 13: Abfrage Gateway (Y-Zeile)
  164.  
  165. Y-Zeile aus Outfile
  166.  
  167. 14: Abfrage Distribution (D-Zeile)
  168.  
  169. D-Zeile aus Outfile. Inhalt: K, L, M, N: Keine, Lokal, MausNet, Net
  170.  
  171. 15: Abfrage Mime (M-Zeile)
  172.  
  173. Inhalt der M-Zeile. Eventuelle Fortsetzung im Text wird nicht
  174. zurückgegeben.
  175.  
  176. 16: Abfrage Status persönliche Nachricht
  177.  
  178. Nur bei PMs vorhanden, sondern wird nichts zurückgeliefert.
  179.  
  180. 17: Abfrage Follow-Up To (F-Zeile)
  181.  
  182. Wird zurückgegeben, wenn es im Outfile vorhanden war, also momentan noch
  183. gar nicht. Au₧erdem kann CAT es noch nicht. Daher liefert das immer einen
  184. leeren String.
  185.  
  186. 18: Abfrage Reply-To
  187.  
  188. Wird zurückgegeben, wenn es im Outfile vorhanden war, also momentan noch
  189. gar nicht. Au₧erdem kann CAT es noch nicht. Daher liefert das immer einen
  190. leeren String.
  191.  
  192. 19: Abfrage Message-Text
  193.  
  194. Liefert den gesamten Text der Nachricht zurück, wie er in der Datenbank
  195. gespeichert ist. Länge ist theoretisch nicht begrenzt, praktisch momentan
  196. auf 64 KB. Es wird von CAT momentan der Text zurückgegeben, wie er an den
  197. Editor übergeben wurde. Eventuelle Filterungen von MIME-Opcodes sind dort
  198. schon durchgeführt worden und der Text wurde noch nicht umbrochen, d.h. es
  199. können lange Zeilen vorkommen. Der Text wird im internen Format von CAT
  200. übergeben, d.h. als Zeilenende dient ein einzelnes LF.
  201.  
  202. 20: Abfrage Message-Datum
  203.  
  204. Liefert Erstellungsdatum der Nachricht im GEMDOS-Format zurück. Im ersten
  205. Wort im Buffer das Datum, im zweiten die Zeit. Theoretisch könnte man das
  206. auch komplett in den Messagebuffer packen und mü₧te nicht einen
  207. Speicherblock übergeben, aber zur Vereinheitlichung der Implementation wird
  208. auch hier der übergebene Speicherblock benutzt.
  209.  
  210. 21: Abfrage Statusdatum
  211.  
  212. Liefert Statusdatum der persönlichen Nachricht im GEMDOS-Format zurück.
  213. Wenn es keine PM ist, wird nur 0 als Zeit und Datum zurückgeliefert.
  214. Ansonsten gilt das gleiche wie bei 20.
  215.  
  216. 22: Abfrage Gruppe
  217.  
  218. Liefert den Namen der aktuellen Gruppe.
  219.  
  220. 23: Abfrage Originaltext
  221.  
  222. Liefert den gesamten Text der Nachricht zurück, wie er in der Datenbank
  223. gespeichert ist. Länge ist theoretisch nicht begrenzt, praktisch momentan
  224. auf 64 KB. Es wird von CAT der Text zurückgegeben, wie er in der Datenbank
  225. gespeichert wurde, d.h. es wurden keine Filterungen durchgeführt, keine
  226. Infozeilen in den Text eingeblendet etc. Der Text wird im internen Format
  227. von CAT übergeben, d.h. als Zeilenende dient ein einzelnes LF.
  228.  
  229. 24: Abfrage eigene Nachricht
  230.  
  231. Fragt nach, ob im Fenster eine eigene Nachricht dargestellt wird. Liefert
  232. nur in der persönlichen Gruppe bei eigenen Nachrichten TRUE zurück. Im
  233. Buffer wird ein Wort übergeben, das 1 ist für eine eigene persönliche
  234. Nachricht, und sonst 0. Weitere Werte werden nicht zurückgeliefert.
  235.  
  236. 25: Abfrage eindeutige Id
  237.  
  238. Fragt nach einer eindeutigen ID pro Nachricht. Gibt einen unsigned long
  239. zurück, der die Nachricht innerhalb eines CAT-Laufes innerhalb einer
  240. Datenbank eindeutig identifiziert.
  241.  
  242. 26: Abfrage Absender aus Sender-Zeile
  243.  
  244. Liefert den Absender zurück, wie er in der Sender-Zeile (S-Zeile) im
  245. Outfile kam
  246.  
  247. 27: Abfrage Absendername im Fenster
  248.  
  249. Liefert den Namen zurück, den CAT im Fenster anzeigt. Bei eigenen
  250. persönlichen Nachrichten ist das der des Empfängers, sonst der des
  251. Absenders.
  252.  
  253. 28: Abfrage voller Messagetext
  254. Wie 19: Abfrage Message-Text, aber ew wird immer der volle Message-Text
  255. zurückgeliefert also incl. Header egal ob diese gerade angezeigt wird
  256. oder nicht.
  257.  
  258. Die folgende Nachricht wird nur von CAT an die angemeldeten Applikationen
  259. verschickt, und zwar jedesmal, wenn im obersten Anzeigefenster eine neue
  260. Nachricht dargestellt wird. Die Nachricht wird auch verschickt, wenn ein
  261. Anzeigefenster nur getoppt wird.
  262.  
  263. 100: Neue Nachricht in Fenster
  264.  
  265. msgbuf[4-7] sind 0, da kein Buffer übergeben wird.
  266.  
  267. Die folgende Nachricht wird nur von CAT an die angemeldeten Applikationen
  268. verschickt, und zwar jedesmal, wenn CAT beendet wird.
  269.  
  270. 101: CAT wird beendet
  271.  
  272. Wird verschickt, wenn CAT beendet wird. msgbuf[4-7] sind 0.
  273.  
  274. Hier noch die Definition der einzelnen Nachrichten, wie sie in CAT
  275. implementiert ist:
  276.  
  277. CONST
  278.   CatProtoMsg   = 8003H;        (* Neues CAT-Protokoll *)
  279.  
  280.   (* Sub-Opcodes für neues CAT-Protokoll *)
  281.   (* Doku: Siehe NEWPROTO.TXT            *)
  282.  
  283.   CAT_ACK           = 0;
  284.   CAT_ERROR         = 1;
  285.   CAT_LOGIN         = 2;
  286.   CAT_LOGOFF        = 3;
  287.   CAT_SENDER        = 4;
  288.   CAT_RNAME         = 5;
  289.   CAT_RECEIVER      = 6;
  290.   CAT_MAUS_ID       = 7;
  291.   CAT_MSG_ID        = 8;
  292.   CAT_MAUS_REF      = 9;
  293.   CAT_REF           = 10;
  294.   CAT_TOPIC         = 11;
  295.   CAT_BOX           = 12;
  296.   CAT_GATE          = 13;
  297.   CAT_DIST          = 14;
  298.   CAT_MIME          = 15;
  299.   CAT_STATUS        = 16;
  300.   CAT_FOLLOWUP      = 17;
  301.   CAT_REPLYTO       = 18;
  302.   CAT_TEXT          = 19;
  303.   CAT_MSG_DATE      = 20;
  304.   CAT_STATUS_DATE   = 21;
  305.   CAT_GROUP         = 22;
  306.   CAT_ORG_TEXT      = 23;
  307.   CAT_IS_OWN        = 24;
  308.   CAT_UNIQUE_ID     = 25;
  309.   CAT_REAL_SENDER   = 26;
  310.   CAT_WDW_NAME      = 27;
  311.   CAT_FTEXT         = 28;        ab CAT 4.18
  312.  
  313.   CAT_NEW_MSG       = 100;
  314.   CAT_TERMINATE     = 101;
  315.  
  316.  
  317.  
  318.