Home Gallery Download FAQ ZAAP Beta Contact Links

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.  Using two special new functions in ZTreeWin (Y & Ctrl-Y), a specifed application can also be passed commands to 'manipulate' the current file or files.

The first Assistant Application available for public testing 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:

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'.
Script Host by Martijn Coppoolse has been assigned the identifier ' S'.

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 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 ZBAR.DAT v2.1 specification:

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

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
Run this program from the ZTreeWin directory to watch how the contents of the file is maintained.

 

Advertisement:

 

Last updated: April 13, 2009

copyright © 2022 ZEDTEK, Inc.