
 Ver 2.1 - November 15th, 2008

 ZAAP is a programming interface which provides a mechanism for ZTreeWin to
 interact with third-party 'assistant applications'.

 What is an Assistant Application?
 In its simplest form, it is a new application that will be written (or an
 existing application that will be adapted) to automatically display the file
 currently selected in ZTreeWin.  Additionally, Using two special functions
 in ZTreeWin (Y & Ctrl-Y), a specifed application can also be passed commands
 to 'manipulate' the current file or set of tagged files.

 The first Assistant Application available to the public is 'rpVT'.
 'rpVT' has been in development since November of 2001 by Reasoning &
 procedureS Inc.,  a subsidiary of Genese Inc.
 Please visit the rpVT website to download a copy, and for installation and
 operational instructions: http://www.ztwiki.com/tiki-index.php?page=rpVT

 In order to support a set of commands unique to a particular Assistant
 Application, developers should register with Zedtek their preferred 'Client
 Identifier' (passed in the entryline field below).  rpVT has been assigned
 the identifier 'R'.

 How does ZTreeWin communicate with an Assistant Application?
 When ZTreeWin has the ZAAP feature enabled (by use of the /ZB command line
 switch), it will automatically publish information, known as a 'pamphlet',
 regarding the current file or directory into a small file called ZBAR.DAT,
 which is created in the ZTreeWin program directory.  This file contains
 information regarding the current state of ZTreeWin as well as sequence
 numbers and a checksum to maintain integrity between the applications.

 The best way to understand the ZBAR.DAT interface is to see it in operation.
 The developer of rpVT, Rudy Penteado, has kindly made available a very handy
 utility called ZBarSpy: http://www.zedtek.com/download/ZBarSpy.zip
 Run ZBarSpy.exe from the ZTreeWin directory to watch how the contents of
 zbar.txt is updated as ZTreeWin is used.

 Visit the following link for more ZAAP information:
 http://www.ztwiki.com/tiki-index.php?page=m_Zaap_Utilities

 The 'zbar.dat' file internal structure:       (1) means note 1, etc.
Ŀ
                                                                                
 Binary seq #  (incremented every new pamphlet issued)                         
                                                                               
        ZTree:  @  New filename in pamphlet                                   
         Cmd    w  Screen status change (same filename)                       
         (5)    ^  Shift/Ctrl-key entry                                       
                ~  Shift/Ctrl/Alt-key entry                                   
                Q  ZTree quitting                                             
                h  Hold pre-command                                           
                y  AA pre-command                                             
                Y  AA command                                                 
                                                            Checksum  (11)   
            Stats (9)                                                       
                 Full path      Full path (other panel)   Copy of seq #  
                                              NULL                      
 ÿ                                                      ÿÿ              
 AAxxxx--@-D81C-----C:\ztw\test.txt*D:\abc\test.txt*entryline*CSAA              
   Ĵ                                                           
        Reserved           NULL                    NULL              
       v2 rev                                                           
       Block size (8)                         From ZTree 'Y/Ctrl-Y' (10) 
                                                                           
       Page (D or F)                                                       
 ZTreeٳ                                                                      
 window Cmd Char:  01h-FFh               (6)                                 
 handle             s - simple Y command  (7)                                 
  (1)               t - Ctrl-Y command    (7)                                 
                                                                              
       Z screen status  (4)                                                   
                                                                               
       Version/Return flag from AA:    k    simple OK for handshake  (2)       
        ZTree v2 sets this              t/T  tag the file             (2)       
        character to '0x82'             u/U  untag the file           (2)       
                                        e    file operation error  (2)(3)       
                                        s    command syntax error  (2)(3)       
                                                                                


 The 'Full path' strings are encoded in UTF-8 format, and can represent up to 400
 characters.

 Notes:

 (1) ZTree window handle of the instance that last wrote to the
      pamphlet. Value is X86 standard little endian dword.

 (2) When an Y or Ctrl-Y command is issued, the corresponding
     application must respond with a return flag.
     The application must write back the zbar file in the same
     format ZTree issued it in, including the block size, revision
     number and reserved bytes.
     This flag is the 7th character in the string and can receive
     a few values as response.  See above.
     Any additional codes for the return flag which may be added
     in the future will be characters with the high-bit not set
     (as to reserve the values >= 0x80 for ZTree itself), and will
     not use the hyphen character '-' (which is set by ZTree v1.x
     per the ZAAP v1 spec).
     ZTree will wait indefinitely for an response from the AA
     when issuing a Y or Ctrl-Y command, but can be interrupted
     by hitting the Esc key.  A ZAAP can return an uppercase 'T'
     or 'U' return flag to indicate that the file has changed.
     This causes ZTree to publish a '@' command next, to notify
     all ZAAPs that the file has been changed.

 (3) If the return flag from a Y or Ctrl-Y command is an error
     (either "e" or "s"), the AA should store a message into the
     "entry line" position of the zbar.dat structure.  The length
     of such error messages should be kept under 73 characters
     to avoid truncation.
     The final NULL, the new checksum and a copy of the sequence
     number have to be refreshed by the AA before writing to
     the file.
     If the format violates the zbar.dat structure rules or the
     checksum doesn't match, ZTree will not display the error
     message in its lower lines.

 (4) ZTree screen status informs the AAs what type of screen
     is being used in Z so they can adjust their owns.
         7 - Auto-view is in use.
         j - JFC function invoked
         l - Left pane is active in split-view.
         m - Menu screen is in use.
         n - Normal screen is in use.
         r - Right pane is active in split-view.
         s - Statistics screen is in use.
         v - Internal Viewer is in use (in standard mode)
         x - Execute screen is in use.

 (5) When ZTree starts, the standard "@" is used.
     When a keyboard command is issued, the "^" is used for the
     Sh/Ctrl-X commands and "~" for the Sh/Ctrl/Alt-X ones.
     When ZTree quits, "Q" is used as a command.
     When the user enters Y cmd, ZTree uses a "y" pre-command
     while waiting for the user to finish the entry and "Y"
     command when the entry is finished.
     When the user enters a C or M command, ZTree puts an
     "h" pre-command to instruct the AA to stop any work with
     the current file.
     When the filename under the bar changes, ZTree updates
     the path and uses an "@" as command.
     When the screen changes format and the filename is the same,
     ZTree changes the status and uses "w" as command.

 (6) Codes generated with the Sh/Ctrl or Sh/Ctrl/Alt keys.
      See the SCKeys.kbd for a list of keyboard codes available.

 (7) When a Y or Ctrl-Y command is issued, ZTree informs the AA
      if it was a simple Y or a tagged Ctrl-Y operation by
      means of this flag: "s" for Y, "t" for Ctrl-Y.

 (8) Block size indicates the additional block of data that
     proceeds the first full pathname, including the block size
     byte itself.  Following the block size is a one byte value
     indicating the block revision format, currently 1.

 (9) Stats indicator can be one of the following values:
        B - Split screen with stats visible for both panels.
        C - Current panel stats are visible (split and non-split).
        N - Split screen and no stats visible.

 (10) Y command string, up to 255 characters

 (11) Checksums are generated using R16 (Rotate-16bit) type.
      Description:
       Start
       CS word to null.
       Pointer to beginning of string (sequence #)
       Loop: (until 3rd null after the reserved block is processed)
         Rotate left CS 1 bit
         Add the character from string to CS (w/MSB=0)
         Increment pointer
       End loop

