15.3 Drag&Drop protocol

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).

15.3.1 D&D-listing_1

/* The following program fragment signals the sender of the
   Drag&Drop protocol that the particular program does not
   support this protocol. */

#define AP_DRAGDROP   63
#define DD_NAK         1

/* We are now in the event-loop;
   msg is the message buffer. */

case AP_DRAGDROP:
{
    static BYTE pipename[] = "U:\\PIPE\\DRAGDROP.AA";
    LONG fd;

    pipename[18] = msg[7] & 0x00ff;
    pipename[17] = (msg[7] & 0xff00) >> 8;

    fd = Fopen (pipename, 2);
    if (fd >= 0)
    {
        BYTE c = DD_NAK;

        Fwrite ((WORD) fd, 1, &c);
        Fclose ((WORD) fd);
    }
}
break;

15.3.2 Drag&Drop, Data-types for

Data-types are represented within the Drag&Drop protocol by a four character long letter string. The following list contains the data- types defined at present:

ARGS

represents a command line, so generally one or more filenames or directory names, separated from each other by a space. For filenames that themselves contain a space, special treatment is required: the filename is enclosed in single quotation marks, and should a single quote mark appear in the name, it is doubled up automatically.

Example:

(!I)Eric's file((!i) will be converted to (!I)'Eric('')s file'(!i).

PATH

is reserved to request information about the destination object selected by the user. The transmission in this case runs in the opposite direction; i.e. the sender reads exactly as many bytes as specified. For this, the receiver has to transmit the data directly after sending DD_OK. The data should contain the full pathname or filename of the destination window (terminated with a '\').

.XXX

represents an extension (of a filename) Examples:

.IMG	=	Graphic data in XIMG format
.GEM	=	Graphic data in metafile format
.TXT	=	Texts in ASCII format
.RTF	=	Texts in Rich Text Format

15.3.3 Drag&Drop, Status bytes for

The following list contains all the status bytes that may occur within a Drag&Drop communication:

#define DD_OK         0    /* OK, - continue                    */
#define DD_NAK        1    /* Abort Drag&Drop                   */
#define DD_EXT        2    /* Data format is not accepted       */
#define DD_LEN        3    /* Request for fewer data            */
#define DD_TRASH      4    /* Destination is a wastebasket icon */
#define DD_PRINTER    5    /* Destination is a printer icon     */
#define DD_CLIPBOARD  6    /* Destination is a clipboard icon   */

All other values are reserved for future purposes.

Note: The status byte DD_EXT is sent when the receiver does not like the offered data format. Following this the sender will transmit a new header with a different data format, or break off transmission on its part. This can be repeated until the sender and receiver have agreed on a format, or until it is established that there is no possibility of mutual understanding.