Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File13.3  Drag&Drop protocol                                           TOS

The Drag&Drop protocol was developed by Atari for MultiTOS. This is a 
very flexible protocol which is not itself part of the operating 
system, and therefore could also be applied under other operating 
systems provided these supported multitasking and pipes.

AES messages in this protocol are only used to bring the communicating 
partners in touch with each other; all the remaining data transfer 
takes place via a pipe, which one can access with the usual GEMDOS 
file functions.

To initiate a Drag&Drop communication, one creates in the directory 
U:\PIPE a file with the name 'DRAGDROP.xx', where each 'x' represents 
a letter from 'A' to 'Z'. Thanks to this, up to 676 simultaneous 
Drag&Drop procedures can take place in theory, which should certainly 
suffice. For creating the pipe one should use the function Fcreate, as 
this returns a tidy error message should a pipe with the same name 
exist already. In addition, when creating the pipe the hidden bit (bit 
1) should be set; with this the reading end receives an End-of- file 
(EOF) when the other end of the pipe is closed.

Subsequently the message AP_DRAGDROP is sent to the receiver. As there 
is no provision for an acknowledgement for this message, the sender 
must make use of the Fselect function to ascertain whether someone on 
the opposite side has opened the pipe for reading and is ready to 
receive. In this connection Atari recommends a timeout of three to 
four seconds.

Warning: The sender is unfortunately not in the position to establish 
in advance whether the destination application supports the Drag&Drop 
protocol at all. Thus it is possible that the user only receives an 
appropriate message after the expiry of the timeout interval. For this 
reason, all applications that do not support this protocol should 
return a negative acknowledgement, so that the annoying waiting time 
is avoided. On the other hand, if the receiver is ready to receive the 
data, it should return the identifier DD_OK (with the value 0).

Next, both parties have to agree on the type of data to be sent; the 
crucial point of the Drag&Drop protocol namely lies in the various 
kinds of data types, which are represented as a four character long 
string of letters. For this the receiver sends a preference-sorted 
list of eight filetypes that it can use to the sender. For instance, a 
text processor could communicate in this manner that it supports files 
in Rich Text Format (RTF) and ASCII format, and that it gives 
preference to the former. Important: If fewer than eight data-types 
are understood, the rest of the list must be filled with NULL-bytes, 
so that always exactly 32 bytes are transmitted.

From the list conveyed by the receiver, the sender can then decide 
which data format is to be used. The transmitted list only serves as a 
guideline for that, however; hence the sender may use a different 
order, or also offer other formats.

Transmission of the actual data then proceeds in the following steps:

   . First a header is transmitted that contains all information about 
     the data - its format and its length. The receiver can then react 
     accordingly. The header is constructed as follows:

      Position  Length       Meaning 
         0      2 bytes      Length of the header 
         2      4 bytes      Data-type (e.g. ARGS) 
         6      4 bytes      Length of data to be transmitted 
         10     Variable(n)  Name of the data (NULL-terminated) 
        10+n    Variable     Filename (NULL-terminated) 

     As the length of the header has to be included, it can be easily 
     extended for future purposes.

   . After it has read in the header, the receiver can react to it. 
     Thus it can inform the sender, for instance, that it agrees with 
     the suggested data format, or not. This is done by sending 
     various status bytes.

   . As soon as the receiver has replied with DD_OK, the transmission 
     of the data starts; for this, exactly as many bytes are written 
     as were specified in the header, and subsequently the pipe is 
     closed.

Important note: Normally a process is terminated by the kernel if it 
writes to a pipe that has not been opened by anyone for reading. This 
can be avoided by ignoring the signal SIGPIPE. Furthermore, neither of 
the partners should use a wind_update, since otherwise it could lead 
to a deadlock in some circumstances if one of the two sides attempts 
to make a screen output (e.g. an alert box).

Tip: A sample source text for the Drag&Drop protocol can be found, for 
instance, in the magazine ST-Computer (issue 12/1993).

See also:
AV protocol   GEM   Style guidelines   Test for pipes   OLGA protocol