Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File15.11.4.1  View a file                                             TOS

The VIEW_FILE message is used by the application to inform the viewer 
that a file is to be displayed.

msg[0]   = VIEW_FILE
msg[3/4] = filename // Must be global-readable (due to MiNT's memory
                    // protection)!
msg[5/6] = 0        // Reserved!
msg[7]   = 0        // Zero = new file, see below!

Notes about filename(9.10.1993)::

   ∙ If filename ends with a slash/backslash, or filename is a 
     directory, the file-selector should be opened with filename as 
     the current path.

   ∙ If the terminating byte (0) of filename is followed by another 
     string starting with an 'X' (0x58), this string gives the file 
     type that filename should be displayed as (using the strings from 
     'What kinds of files can be displayed?' as a guide) if possible. 
     This could be used to show hex-dumps ('XDump').

This message is always answered by the viewer:

If the file could not be displayed, respond with the VIEW_FAILED 
message:

retmsg[0]   = VIEW_FAILED
retmsg[3/4] = msg[3/4]  // Filename (same pointer!)
retmsg[5]   = errcode   // See below.
retmsg[6]   = 0         // Reserved!
retmsg[7]   = msg[7]    // 0 or window identification.

filename should always be the pointer received in VIEW_FILE, as only 
this way can the sender recognize which file was meant in case msg[7] 
is zero (and - of course - no new memory has to be allocated.

The errcode variable may be a GEMDOS error-code (<0) or one of the 
following:

VIEWERR_ERROR   - The error is unspecified
VIEWERR_SIZE    - The file is too large, or the wrong size
VIEWERR_COLOR   - Unsupported resolution or color
VIEWERR_WID     - Wrong window identification
VIEWERR_MEM     - Not enough memory

It is expected that the viewer informs the user about the error (by 
printing a message or displaying an alert box), since it will know 
what the problem is much better than the application.

If the file has been displayed, but no further communication is 
possible, the viewer sends the VIEW_OPEN message:

retmsg[0]   = VIEW_OPEN
retmsg[3/4] = msg[3/4]          // Filename (the recieved pointer)
retmsg[5]   = viewprot_version  // Currently 0
retmsg[6]   = 0                 // Reserved!
retmsg[7]   = 0                 // 0 = no further communication!

If the file has been displayed, and further communication is possible, 
the viewer sends the VIEW_OPEN message:

retmsg[0]   = VIEW_OPEN
retmsg[3/4] = msg[3/4]          // Filename (the recieved pointer)
retmsg[5]   = viewprot_version  // Currently 0
retmsg[6]   = 0                 // Reserved!
retmsg[7]   = wid               // Window ID (non-zero!)

The window identification wid refers to the AES identification of the 
window the file is being displayed in. This seems to be a unique 
number representing the file, which is used in further communication 
as an identifier.

The currently defined viewprot_version is 0.