Topic       : Documentation for Thing
Author      : Arno Welzel/Thomas Binder/TransAction
Version     : thing.hyp 1.27E (23/8/1998)
Subject     : Documentation/Shells
Nodes       : 269
Index Size  : 6336
HCP-Version : 4
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : %I
@help       : %Hilfe
@options    : +g -i -s +y +zz -t4 -d10
@width      : 75
@hostname   : THING   
View Ref-FileAV Protocol                                                           Thing

The AV Protocol was developed for use with Stefan Eissing's Gemini 
replacement desktop. Gemini comprised a GUI (Graphical User Interface) 
desktop named Venus, and a command line interpreter called Mupfel. 
To allow Venus to communicate with desk accessories the AV Protocol was 
developed and is widely supported today. The name derives from:

(AV ~ Accessory <-> Venus)

In the meantime there have been some additions to the original definition 
and to be able to differentiate between the original and extended versions 
the date of the new definition has been added to the descriptions in this 
text. The Thing package contains a revised version of the file VAPROTO.H 
listing all the new messages, which can be used by programmers.

The additions have been agreed with Stefan Eissing and it is safe to assume 
that no conflicts will arise with future Gemini versions.

Thing supports most of the messages defined up to 26th June 1995 and as a 
consequence is an excellent 'AV-server' that improves the functionality 
of your desk accessories and operation under a multitasking OS. 
Filename quoting is still not supported!

In the following description Thing acts as the 'Server' and accessories 
and applications that use Thing's server functions are 'Clients'.

In order to use Thing as an AV-server under a multitasking environment 
you must set an environmental variable for Thing called AVSERVER. This 
can be done very elegantly with an additional entry in the appropriate 
configuration file of the relevant operating system (MagiC or MultiTOS): 

  MagiC

    Enter '#_ENV AVSERVER=THING' in the file MAGX.INF (must be added
    before '#_CTR'!)

  MultiTOS

    Enter 'setenv AVSERVER=THING' in the file MINT.CNF.


The following functions are supported by Thing:

          Client -> Server                       Server -> Client

  AV_PROTOKOLL     AV_GETSTATUS          VA_PROTOSTATUS    VA_SETSTATUS
  AV_STATUS        AV_SENDKEY            VA_START          VA_FILEFONT
  AV_ASKFILEFONT   AV_ASKCONFONT         VA_CONFONT        VA_WINDOPEN
  AV_OPENWIND      AV_STARTPROG          VA_PROGSTART      VA_DRAGACCWIND
  AV_ACCWINDOPEN   AV_ACCWINDCLOSED      VA_COPY_COMPLETE  VA_THAT_IZIT
  AV_COPY_DRAGGED  AV_PATH_UPDATE        VA_DRAG_COMPLETE  VA_FONTCHANGED
  AV_WHAT_IZIT     AV_DRAG_ON_WINDOW     VA_XOPEN          VA_VIEWED
  AV_EXIT          AV_STARTED            VA_FILECHANGED
  AV_XWIND         AV_VIEW               VA_FILECOPIED
  AV_FILEINFO      AV_COPYFILE           VA_FILEDELETED
  AV_DELFILE                             VA_PATH_UPDATE
 

      Some hints for implementing the protocol in your own programs:

      ∙ Under Single-TOS only the (main-) application 0 can act as
        AV-server.
        In a multitasking environment like MagiC or MultiTOS, you have 
        to establish the presence of an AV-server by checking the 
        environmental variable AVSERVER. Under no circumstances make the 
        unsafe assumption that the server also has an application-ID 0 
        here, just because under MagiC the desktop by chance is always 
        started with ID 0! Because under MultiTOS the desktop does not
        have an ID 0!

      ∙ Once a program uses AV_PROTOKOLL it must use AV_EXIT before 
        terminating! The AV_PROTOKOLL message may only be sent once 
        unless one has sent an AV_EXIT beforehand)!

      ∙ A program should always wait for the return of VA_PROTOSTATUS
        before sending any other AV_... messages to the server! It may 
        well be that the current server does not support all the 
        documented functions and hence the relevant AES messages do not 
        trigger the desired actions!

      ∙ All memory blocks, which are used to pass file and folder names, 
        parameters etc. must be allocated 'global' when running under 
        under MultiTOS!!! (hint: Mxalloc(<size>,0x42)). Otherwise memory
        violations will occur!

      ∙ All filenames and folder names must contain complete path names 
        including the drive e.g. 'i:\test.txt').

      ∙ If the server supports filename 'quoting' they can be enclosed 
        in single quote marks. If a quote mark is part of the file name,
        it has to be repeated once:

          d:\letter to moni    becomes   'd:\letter to moni'
          d:\peter's picture   becomes   'd:\peter''s picture'

      ∙ If there is more than one file/folder name, the names should 
        be separated using a single space (ASCII character 32).

      ∙ Folder names must be terminated with a backslash ('\' - ASCII 92)
        e.g. 'i:\letters\' (even if Gemini 1.a doesn't seem to do this)!

      ∙ To provide 'global' window cycling, AV clients should send
         Control  +  W  to the server via the AV_SENDKEY message.