home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / utilities / organisers / hierarchy / !Hierarchy / doc / dTransProt next >
Encoding:
Text File  |  1995-01-17  |  8.6 KB  |  235 lines
  1. ---------------------------------------------------------------------
  2.           Format eines User Message Blocks (R0 = 17-19)
  3. ---------------------------------------------------------------------
  4.  
  5. Entry:
  6.  
  7.   R1 +  0   Blockgröße, 20-256 Bytes (word-aligned)
  8.   R1 +  4   vor Ausführung von Wimp_SendMessage unbenutzt
  9.   R1 +  8   vor Ausführung von Wimp_SendMessage unbenutzt
  10.   R1 + 12   your_ref (0, wenn die Nachricht original, also keine
  11.                Antwort ist)
  12.   R1 + 16   message action (z.B. Message_DataSave = 1)
  13.   R1 + 20   message data (Inhalt hängt von message action ab)
  14.  
  15.   ...
  16.  
  17. Exit:
  18.  
  19.   R1 +  4   Task Handle des Absenders
  20.   R1 +  8   my_ref (einmaliger von Wimp generierter Wert >= 0)
  21.  
  22. ---------------------------------------------------------------------
  23.                         Message_DataSave
  24. ---------------------------------------------------------------------
  25.  
  26.   ...
  27.   
  28.   R1 + 20  Window Handle
  29.   R1 + 24  Icon Handle
  30.   R1 + 28  Maus-X-Koordinate (absolut)
  31.   R1 + 28  Maus-Y-Koordinate (absolut)
  32.   R1 + 36  geschätzte Anzahl der zu übertragenden Daten
  33.               in Bytes
  34.   R1 + 40  Typ der zu übertragenden Daten / Datei
  35.   R1 + 44  vorgesehener Dateiendname (leafname) der
  36.               Daten (+ 0-Terminator)
  37.  
  38. Die ersten vier Werte stammen von Wimp_GetPointerInfo. Der
  39. Rest muß vom Programm eingesetzt werden. Ist noch nicht bekannt,
  40. wie groß eine Datei ist, sollte man anfangen zu überlegen, wie
  41. groß die Datei mindestens sein wird.
  42.  
  43. Zusätzlich zu den üblichen dreistelligen Hexadezimalzahlen sind
  44. folgende Werte für die Benutzung im Data Transfer Protocol
  45. definiert worden:
  46.  
  47.       &1000        Verzeichnis
  48.       &2000        Applikationsverzeichnis
  49.       &FFFFFFFF    Typenlose Datei (mit Load/Exec Address)
  50.  
  51. ---------------------------------------------------------------------
  52.                         Message_DataSaveAck
  53. ---------------------------------------------------------------------
  54.  
  55.   ...
  56.   
  57.   R1 + 12  your_ref = my_ref der vorausgegangen Message_DataSave
  58.   
  59.   ...
  60.   
  61.   R1 + 20  Window Handle
  62.   R1 + 24  Icon Handle
  63.   R1 + 28  Maus-X-Koordinate (absolut)
  64.   R1 + 28  Maus-Y-Koordinate (absolut)
  65.   R1 + 36  geschätzte Anzahl der zu übertragenden Daten
  66.               in Bytes (-1, falls die Datei 'unsave' ist)
  67.   R1 + 40  Typ der zu übertragenden Daten / Datei
  68.   R1 + 44  kompletter Pfadname der Datei oder <Wimp$Scrap>
  69.               (+ 0-Terminator)
  70.  
  71. Die Werte von R1 + 20 bis R1 + 32 stammen aus der vorangegangen
  72. Message_DataSave <DateiEndName>. Ist der Empfänger der Daten
  73. - also der Absender dieser Message_DataSaveAck - kein Filer,
  74. dann hat er bei R1 + 36 (Dateigröße in Bytes) -1 einzusetzen.
  75. Dies zeigt der übertragenden Applikation, daß die Daten nicht
  76. gesichert werden, also nicht in einer permanenten Datei landen.
  77. Der Filer setzt bei R1 + 36 natürlich nicht -1 ein und gibt ab
  78. R1 + 44 den kompletten Pfadnamen der zu erzeugenden Datei an.
  79.  
  80. ---------------------------------------------------------------------
  81.                         Message_DataLoad
  82. ---------------------------------------------------------------------
  83.  
  84.   ...
  85.   
  86.   R1 + 12  your_ref = my_ref der vorausgegangenen
  87.               Message_DataSaveAck
  88.  
  89.   ...
  90.   
  91.   R1 + 20  Window Handle
  92.   R1 + 24  Icon Handle
  93.   R1 + 28  Maus-X-Koordinate (absolut)
  94.   R1 + 28  Maus-Y-Koordinate (absolut)
  95.   R1 + 36  geschätzte Anzahl der Daten in Bytes
  96.   R1 + 40  Typ der Daten / Datei
  97.   R1 + 44  voller Pfadname der Datei oder <Wimp$Scrap>
  98.            (+ 0-Terminator)
  99.  
  100. Der Empfänger dieser Message_DataLoad sollte den Datei-Typ
  101. prüfen und je nach Wert die Datei laden. War der Ladevorgang
  102. erfolgreich, dann sollte der Empfänger mit Message_DataLoadAck
  103. antworten.
  104.  
  105. Was zu beachten ist: bei R1+36 sollte die Größe der zu ladenden
  106. Datei wenn möglich genau angegeben werden. Ich habe den (vermutlich)
  107. typischen Fehler gemacht und den Message-Block der vorausgehenden
  108. Message_DataSaveAck größtenteils unverändert übernommen. Das Problem
  109. zeigte sich allerdings erst nach einem Update von !Zap auf Version
  110. 1.20, das sich weigert, eine Datei zu laden, die -1 Bytes groß ist.
  111.  
  112. Bekommt der Absender dieser Message_DataLoad keine Bestätigung
  113. in Form von Message_DataLoadAck, dann sollte er die Datei
  114. <Wimp$Scrap> löschen und folgenden Fehler ausgeben:
  115.         'Data transfer failed: Receiver died'
  116.  
  117. ---------------------------------------------------------------------
  118.                         Message_DataLoadAck
  119. ---------------------------------------------------------------------
  120.  
  121.   ...
  122.   
  123.   R1 + 12  your_ref = my_ref der vorausgegangenen Message_DataLoad
  124.  
  125.   ...
  126.   
  127.   R1 + 20  Window Handle
  128.   R1 + 24  Icon Handle
  129.   R1 + 28  Maus-X-Koordinate (absolut)
  130.   R1 + 28  Maus-Y-Koordinate (absolut)
  131.   R1 + 36  geschätzte Anzahl der Daten in Bytes
  132.   R1 + 40  Typ der Daten / Datei
  133.   R1 + 44  voller Pfadname der Datei oder <Wimp$Scrap>
  134.            (+ 0-Terminator)
  135.  
  136. Der Absender dieser Message_DataLoadAck braucht effektiv nur den
  137. Typ der Message (bei R1 + 16) auf 4 = Message_DataLoadAck setzen
  138. und bei R1 + 12 (your_ref) den Wert von R1 + 8 (my_ref) einsetzen.
  139.  
  140. Der Empfänger dieser Message ist der Absender der vorausgegange-
  141. nen Message_DataLoad.
  142.  
  143. ---------------------------------------------------------------------
  144.                       Message_DataOpen
  145. ---------------------------------------------------------------------
  146.  
  147.   ...
  148.   
  149.   R1 + 20  Window Handle des Verzeichnisfensters in dem die
  150.               angeklickte Datei liegt.
  151.   R1 + 24  unbenutzt
  152.   R1 + 28  absolute x-Koordinate des Datei-Icons
  153.   R1 + 32  absolute y-Koordinate des Datei-Icons
  154.   R1 + 36  0
  155.   R1 + 40  Typ der Datei
  156.   R1 + 44  voller Pfadname der Datei (+ 0-Terminator)
  157.  
  158. Die Koordinaten des Icons können benutzt werden, um ein
  159. klein wenig Mac- bzw. Atari-Feeling auf den Archimedes zu
  160. bringen, indem man eine 'Zoom-Box' von den Koordinaten des
  161. Icons bis zum neu zu öffnenden Fenster mit dem Inhalt der
  162. Datei animiert. (Hat das schon mal jemand auf dem Archi
  163. gesehen? Braucht man das?)
  164.  
  165. Diese Message wird vom Filer an alle aktiven Applikationen
  166. verschickt, wenn der Benutzer eine Datei per Doppelklick
  167. öffnen will. Message_DataOpen wird immer als Broadcast-
  168. Message verschickt.
  169.  
  170. Bestätigt wird diese Message mit Message_DataLoadAck. Dies
  171. muß auf jeden Fall vor dem nächsten Aufruf von Wimp_Poll
  172. geschehen. Es ist also sinnvoll, erst die Message des
  173. Filers zu bestätigen und dann die Datei zu laden.
  174.  
  175. ---------------------------------------------------------------------
  176.                            Message_RAMFetch
  177. ---------------------------------------------------------------------
  178.  
  179.   R1 + 12  your_ref = my_ref der vorausgegangenen
  180.               Message_DataSave / Message_RAMTransmit
  181.   ...
  182.   
  183.   R1 + 20  Addresse des Übertragungsbuffers
  184.   R1 + 24  Größe des Buffers in Bytes
  185.  
  186. Wird als User_Message_Recorded gesendet, damit bei einem
  187. Ausbleiben der Bestätigung auf das 'alte' Protokoll zu-
  188. rückgegriffen wird bzw. eine bereits eingeleitete Übertra-
  189. gung abgebrochen werden kann.
  190.  
  191. Tritt der letzte Fall ein, so erzeugt das übertragende
  192. Programm eine Fehlermeldung. Der Empfänger meldet einen
  193. Fehler, wenn es die übertragenen Daten nicht verarbeiten
  194. kann (z.B. wegen Speichermangel). Es sollten dann auch
  195. keine Message_RAMFetch mehr gesendet werden.
  196.  
  197. Die empfangende Applikation kann sich bei der Einrichtung
  198. des Buffers nach der geschätzten Größe der zu übertragenden
  199. Datei richten, sollte aber darauf vorbereit sein, mehr
  200. Daten zu empfangen.
  201.  
  202. ---------------------------------------------------------------------
  203.                        Message_RAMTransmit
  204. ---------------------------------------------------------------------
  205.  
  206.   R1 + 12  your_ref = my_ref der vorausgegangenen
  207.               Message_DataSave / Message_RAMTransmit
  208.   ...
  209.   
  210.   R1 + 20  Addresse des Übertragungsbuffers
  211.   R1 + 24  Anzahl der in den Buffer geschriebenen Bytes
  212.  
  213. Die übertragende Applikation sendet Message_RAMTransmit als
  214. Antwort auf Message_RAMFetch. Wenn die Anzahl der übertragenen
  215. Bytes kleiner als der eingerichtete Buffer ist, dann ist dies
  216. die letzte Message dieses Typs, ansonsten gibt es noch Daten
  217. zu übertragen und der Empfänger wird eine weitere Message
  218. vom Typ Message_RAMFetch senden. (siehe 'doc.General', Zeilen
  219. 275ff)
  220.  
  221. Alle Message_RAMTransmit sollten als User_Message_Recorded
  222. gesendet werden. Wird keine Bestätigung von der empfangenden
  223. Applikation (Message_RAMFetch) gegeben, sollte der Datentransfer
  224. von der übertragenden Applikation abgebrochen werden, indem
  225. kein weiteres Message_RAMTransmit erfolgt. Es liegt ebenfalls
  226. an der übertragenden Applikation, gegebenenfalls eine Fehler-
  227. meldung auszugeben.
  228.  
  229. Die letzte Nachricht dieses Typs sollte als User_Message
  230. gesendet werden, da der Empfänger keine weitere Message_RAMFetch
  231. als Bestätigung senden wird. Beachten Sie, daß die letzte
  232. Message_RAMTransmit auch gleichzeitig die erste und einzige
  233. Message dieses Typs sein kann, wenn der Übertragungsbuffer
  234. groß genug ist.
  235.