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.13.2.2.2  Single-tasking GEM versions                           TOS

The communication between the main application and the accessories is 
initiated in the following way:

  1. When a main application is started (or terminated), all desk 
     accessories receive an AC_CLOSE message from the AES screen- 
     manager. In response they must send an identification to the main 
     application according to the following format:

          msg[0]:  ACC_ID (0x400)
          msg[1]:  Sender's apID
          msg[2]:  Length of the message - 16, giving 0
          msg[3]:  Program version number and message groups
          msg[4]:  and
          msg[5]:  Pointer to sender's name
          msg[6]:  Menu number (menu_id) as returned by menu_register
          msg[7]:  Reserved (see ACC_ACC)

     The low byte of msg[3] contains a bitmap indicating which message 
     groups are understood by the sender. Bit zero is set for message 
     group 1, bit one for message group 2, and so on. This is 
     independent of the message types which the sender might itself 
     send to others. The sender of a message must ensure that it is 
     understood by the receiver. The high byte is used to indicate a 
     program version number using an arbitrary encoding scheme. The 
     pointer to the sender's name is stored in a machine-dependent 
     format. The name itself is a character string following C 
     conventions, i.e. a string of characters terminated by a zero 
     byte. To avoid name conflicts, long names are preferred to short 
     abbreviations. The name must be available at the given address at 
     any time, it may not be removed after initialization. As the 
     version number is stored in msg[3], it should not occur again in 
     the name. (Note: See the section 'Extended names' for more 
     details on names.) Accessories using more than one menu entry 
     must issue one ACC_ID message for each entry used. Accessories 
     without a menu entry must use a number of -1.

     Since msg[1] and msg[2] have the same meaning for all message 
     types, they are no longer mentioned from now on.

  2. In response to an ACC_ID message the main application sends an 
     identification back to the accessory. The format is identical, 
     except that there is no menu number and thus msg[6] can be used 
     for any other purpose if neccessary. The same applies to msg[7].

  3. In addition to the ACC_ID message, the main application informs 
     all previously installed accessories about the new one by sending 
     them the message:

          msg[0]:  ACC_ACC (0x403)
          msg[3]:  Program version number and message groups
          msg[4]:  and
          msg[5]:  Pointer to accessory's name
          msg[6]:  Accessory's menu number (menu_id)
          msg[7]:  Accessory's apID

  4. A desk accessory receiving the ACC_ACC message from the main 
     application sends an ACC_ID message to the thereby installed 
     accessory, identical to the one previously sent to the main 
     application.

  5. When an accessory is activated by receiving an AC_OPEN message, 
     it sends the following message to the main application:
     msg[0]: ACC_OPEN
     Just before the accessory returns control to another program, it 
     sends the message
     msg[0]: ACC_CLOSE
     When receiving ACC_OPEN, the main application restores all system 
     variables it has changed to their original values (if possible 
     and neccessary). After receiving ACC_CLOSE, it may set them again 
     to any desired value.

     Accessories should change system variables only after sending 
     ACC_OPEN and restore them before ACC_CLOSE.

     There have been some problems with the implementation of ACC_OPEN 
     and ACC_CLOSE that should be mentioned. The system was designed 
     with windowless accessories in mind, i.e. accessories that only 
     display a dialog box. For these accessories, the above procedure 
     is well-defined. Accessories that use windows however have no way 
     to find out if they have been activated or deactivated, because 
     they do not receive a message to indicate this (starting from AES 
     4.0, this problem is solved). Therefore such accessories must be 
     careful with ACC_OPEN and ACC_CLOSE. The most important thing is 
     to guarantee that ACC_OPEN and ACC_CLOSE always occur in pairs, 
     and that in between no other program gains control. How exactly 
     this is implemented depends on the specific application. 
     Sometimes the best implementation is not to use ACC_OPEN and 
     ACC_CLOSE at all.

After initialization is completed, all participating programs know the 
identity of all other ones, either by receiving an ACC_ID message or 
by receiving an ACC_ACC message. The main application is always 
informed about accessory activities. If in addition it proves 
neccessary to inform one accessory about the activation of another 
one, this can be accomplished by sending special messages (starting 
from 0x800).