A communication protocol for GEM applications XAcc

Contents Introduction Extended XAcc

2 Classic XAcc

The "classic" XAcc protocoll was finally defined on November 28, 1992. All known XAcc applications implement the protocol this way.

2.1 XAcc message groups

Both main applications and accessories can have widely different needs for communication with other programs. Therefore XAcc defines several groups of related messages (3) that deal with a certain range of data types. The message groups always indicate the messages understood by a program, not the messages it might send to other ones. If a program supports a certain message group, it must correctly respond to all corresponding messages, whether it can actually use the supplied data or not.

In addition to message groups, there are the so-called "basic messages", which must be supported by any XAcc-aware program, and program-specific so-called "special messages".

The basic messages deal solely with identification, but no real data exchange. They are already sufficient for programs that either do not exchange data with others at all or use only special messages to communicate with a number of other specific programs.

Message group 1 specifies the exchange of ASCII-format character data.

Message group 2 deals with the exchange of drawings and pictures using the GEM metafile format and the GEM bit-image file format.

Future extensions might include sound or spreadsheet data. In addition, a message group could be defined to handle command interchange between applications, e.g. for a "drag&drop" protocol (4).

2.2 XAcc messages

There are two kinds of XAcc messages: standard messages, which must be understood by every participating program, and special messages intended for communications between specific program combinations. The standard messages have numbers ranging from 0x400 to 0x7ff, special messages start from 0x800. The latter ones may only be sent after the receiver has been identified and is known to understand them. The following description is only concerned with standard messages.

In addition to XAcc standard messages, the AES messages normally sent by the screen manager may be used. The most useful ones are AC_OPEN and MN_SELECTED; the latter one requires a knowledge of the receiver and therefore belongs to the special messages.

2.2.1 Basic messages


ACC_ID    = 0x400
ACC_OPEN  = 0x401
ACC_CLOSE = 0x402
ACC_ACC   = 0x403
ACC_EXIT  = 0x404

These messages provide XAcc initialization and organization. This is the only part of XAcc which has to be implemented in a different way for single- and multitasking GEM versions. Note that the procedure described for 'multitasking' actually only depends on the existence of appl_search() and hence on an AES version number >= 4.0. If some future single-tasking AES supports appl_search(), the "multitasking" initialization should be used. Multitasking AES versions with a version number < 4.0 should never exist; to be on the safe side, applications should not attempt to use XAcc if such a situation is detected (5).

2.2.1.1 Single-tasking GEM versions

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 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:

    
         msgbuf[0]:  ACC_ID
         msgbuf[1]:  sender's apid
         msgbuf[2]:  length of the message - 16, giving 0
         msgbuf[3]:  program version number and message groups
         msgbuf[4] and msgbuf[5]:   pointer to sender's name
         msgbuf[6]:  menu number (menu_id) as returned by menu_register()
         msgbuf[7]:  reserved (see ACC_ACC)
    
    

    The low byte of msgbuf[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 initialisation. As the version number is stored in msgbuf[3], it should not occur again in the name. (6)

    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 msgbuf[1] and msgbuf[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 ist no menu number and thus msgbuf[6] can be used for any other purpose if neccessary. The same applies to msgbuf[7].

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

    
         msgbuf[0]:  ACC_ACC
         msgbuf[3]:  program version number and message groups
         msgbuf[4] and msgbuf[5]:   pointer to accessory's name
         msgbuf[6]:  accessory's menu number (menu_id)
         msgbuf[7]:  accessory's apid
    
    

  4. An accessory receiving the ACC_ACC message from the main application sends an ACC_ID message to the thereby registered 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:

    
         msgbuf[0]:  ACC_OPEN
    
    

    Just before the accessory returns control to another program, it sends the message

    
         msgbuf[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 window-less 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).

2.2.1.2 Multitasking GEM versions

The initialization procedure is much simpler in this case. Any application, i.e. both 'standard' applications and accessories, uses appl_search() to detect all currently running AES processes when it is started. To each application or accessory (i.e. everything but system processes) it sends an ACC_ID message:


  msgbuf[0]:  ACC_ID
  msgbuf[1]:  sender's apid
  msgbuf[2]:  length of the message - 16, giving 0
  msgbuf[3]:  program version number and message groups
  msgbuf[4] and msgbuf[5]:   pointer to sender's name
  msgbuf[6]:  menu number (menu_id) as returned by menu_register()
  msgbuf[7]:  reserved

The low byte of msgbuf[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 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 processor-dependent format. The name itself is a string of characters terminated by two 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. It must also reside in globally accessible memory. As the version number is stored in msgbuf[3], it should not occur again in the name. (6)

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

When receiving an ACC_ID message, an application replies by sending a message of the same format to the original sender, the only difference being that ACC_ACC is used instead of ACC_ID. Applications with several menu entries must again send one message for each entry.

The messages ACC_OPEN and ACC_CLOSE are not used in multitasking systems.

Note: The only difference between ACC_ID and ACC_ACC for multitasking systems is that an application receiving ACC_ID sends ACC_ACC as a reply, whereas no reply is sent on receiving ACC_ACC. This prevents applications from sending ACC_ID to each other indefinitely. Obviously the name ACC_ACC has lost its original meaning and probably should be changed. But since the symbolic names do not influence the actual behaviour of any program, this is not really important at all.

Since in a multitasking environment every participating application can terminate, some means must be provided to tell other applications about this. Therefore the message ACC_EXIT has been added to the list of level 0 messages. Before terminating, any application sends


  msgbuf[0]:  ACC_EXIT
  msgbuf[1]:  sender's apid
  msgbuf[2]:  length of the message - 16, giving 0

to all applications that have ever registered themselves by sending ACC_ID or ACC_ACC.

2.2.2 Extended names

Experience with XAcc has shown that it would often be useful to have more information about an application than specified with ACC_ID messages. For example it is sometimes useful to check for a special feature that is not unique to a single program, but to several similar ones. This was the motivation for the introduction of "extended names".

An "extended name" is a character string of the format


'name'\0XDSC\0'string'\0'string'\0...'string'\0\0

i.e. a "standard" name followed by the string "XDSC" (for "eXtended DeSCription"), followed by a list of strings containing additional information. The end of the list is marked by an additional zero byte.

Each information string indicates by its first byte what kind of information it contains. Currently the following types are defined:

'1'
application type (human-readable)

The text following this byte (an ASCII-1, 0x31) should roughly specify the type of application, e.g. "word processor" or "spreadsheet". The purpose is for applications to present this information to the user to let him/her decide where data should go. This is not the place for advertising hype; a word processor should call itself "word processor" and not "document editing and design system".

It should be clear that the text should be understandable for end users, especially it should be in the language used for the user interface.

'2'
application type (machine-readable)

Currently defined are:

"WP"
word processor

"DP"
DTP

"ED"
text editor

"DB"
database

"SS"
spreadsheet

"RG"
raster graphics application

"VG"
vector graphics application

"GG"
general graphics application

"MU"
music application

"CD"
CAD

"DC"
data communication

"DT"
desktop

"PE"
programming environment

'X'
extended features

This string is used to indicate special communication capabilities of an application. It can be used to give more specific information than the message groups understood. Since this information is meant to be used by other applications rather than end users, short abbreviations are sufficient.

'N'
generic name

Often several related, but not completely identical, applications have different names. Marketing requirements may even dictate changes of the "official" brand names, making them unsuitable for a "technical" identification. In such cases a "generic" name for all these programs can be specified, which is mainly used by other programs wishing to use special messages.

The "normal" name should be the "official" name of the program, just as it is used on the package, in the manual, and in similar places. It should be presentable to the user to let him/her decide where to send data.

Example: The address database "That's Address" identifies itself with the extended name (in C syntax)


"That's Address\0XDSC\01database\02DB\0XMM\0XSU\0"

indicating that it is a database with features "MM" and "SU". The first one indicates a special mail merge mode, the second one the possibility of retrieving data by sending the key via ACC_TEXT. (Further information on this program can be obtained from its manual.)

2.2.3 Message group 1


ACC_ACK  = 0x500
ACC_TEXT = 0x501
ACC_KEY  = 0x502

  1. Transmitting text data:

    
         msgbuf[0]:  ACC_TEXT
         msgbuf[4] and msgbuf[5]:   pointer to text
    
    

    The text may contain all printable ASCII characters (code >= 32) and the following control codes:

    0x09
    TAB (may be interpreted as a space by the receiver)

    0x0A
    LF (usually ignored by receiver)

    0x0D
    CR (used to mark an end-of-line (or end-of paragraph)

    Other control codes may only be used if the receiver is known to understand them. The text is terminated by a zero byte.

    After the text has been interpreted completely, the receiver acknowledges by sending

    
         msgbuf[0]:  ACC_ACK
         msgbuf[3]:  0 if the text was simply ignored, 1 if it was used in
                     some sensible way
    
    

    The sender of a text message may not change the text nor send any other text messages to the same receiver until is has received the acknowledge.

    The sender must make sure that the memory used to store the text is globally accessible.

    The receiver should normally interpret the text as if it were typed from the keyboard. A word processor would for example insert it into the currently edited document (this implies using CR as an end-of- paragraph mark), a command line interpreter would interpret the text as a command (which implies using CR as an end-of-line mark).

  2. Simulation of a key press:

    
         msgbuf[0]:  ACC_KEY
         msgbuf[3]:  scan code of the simulated key and corresponding
                     ASCII code (as returned by evnt_keybd())
         msgbuf[4]:  state of the SHIFT keys (as returned by Kbshift())
    
    

    This message should be regarded identical to a keyboard event (7). It can be used to send control commands to a receiver which might have been issued from the keyboard. Of course this requires a knowledge of the receiver as no standard keyboard command sets exist. It should be noted that the receiver is free to use only the ASCII code or the scan code, or both of them.

    This message is acknowledged after its interpretation with

    
         msgbuf[0]:  ACC_ACK
         msgbuf[3]:  0 if ACC_KEY was ignored or a given command was not
                     understood, 1 if some action was taken.
    
    

To prevent a deadlock if a program does not properly acknowledge a message, the sender should have some way to recover. An accessory could for example stop waiting for an acknowledgement after the next AC_OPEN, a main application might time out after a sufficiently long period.

2.2.4 Message group 2


ACC_META = 0x503
ACC_IMG  = 0x504

These message are used to exchange drawings and pictures. Only the file formats defined in the GEM documentation are used; they are sufficient to meet most requirements, and any GEM application should be able to handle them anyway.

  1. Sending a metafile:

    
         msgbuf[0]:  ACC_META
         msgbuf[3]:  1 for the final part, 0 otherwise
         msgbuf[4] and msgbuf[5]:   pointer to data
         msgbuf[6] and msgbuf[7]:   length of data (32 bit longword)
    
    

    The metafile data is sent in the same format as they would be stored on disk. As metafiles can become quite large and especially accessories often do not have sufficient memory to store them, a file can be sent in several pieces. The receiver has to take care of assembling all parts to restore the original data, if neccessary by writing the parts to a file. The last part of a file is marked by msgbuf[3]=1. The sender may send no other data between the parts of a file. msgbuf[6] and msgbuf[7] contain the length of the part being sent, not the total length.

    The receiver acknowledges each part as described for level 1. As for text messages, the sender must make sure that the data to be transferred is stored in globally accessible memory.

  2. Sending a bit image file:

    
         msgbuf[0]: ACC_IMG
    
    

    otherwise identical to 1)

2.3 Compatibility considerations

There are two major changes with respect to the original (1) XAcc definition:

  1. "Levels" have been replaced by "message groups".

    The motivation for this change was that the classification according to exchangeable data types was not really a hierarchical one; there is no reason why a programm accepting graphics should also be able to understand text. The new scheme makes no such arbitrary assumptions.

    There is only one situation in which a possible incompatibility could occur: an application following the "old" convention encounters a "new" application and one of them indicates 2 in the level/message group byte. This would be interpretes as "graphics only" by one and as "graphics and text" by the other. Since the number of level-2 applications was always extremely small (in fact, the author (8) knows only of a single one), this should be no problem in practice.

  2. Extended names have been introduced.

    This could lead to a problem in the extremely unlikely case of an "old" application using a name string which is accidentally followed by "XDSC".

In any case it is expected that most applications will be converted to the new rules soon, if only to support MultiTOS.


Contents Introduction Extended XAcc