textfiles/computers/DOCUMENTATION/spy.txt

Description
-----------
SPY is a "remote control" program for NetBios compatible networks.  The
current version of SPY is intended as a demonstration of a network
client-server application implemented in Pascal.  We have found it somewhat
useful for lending remote assistance to our network users.

SPY and its accompanying documentation and source files are:

Copyright (c) 1989 by Edwin T. Floyd
All rights reserved

SPY and its accompanying documentation is not "shareware" and I do not request
payment for it.  You may distribute and use it without restriction as long as
you don't sell it and don't hold me liable for any errors or consequential
damages.  If you wish to include this software as part of a commercial
package offered for sale, you must obtain written permission from me, the
author:

Edwin T. Floyd [76067,747]
#9 Adams Park Court
Columbus, GA 31909
404-322-0076 (home)
404-576-3305 (work)

Release History
---------------
11-17-89 1.3 - Corrected missed EGA/VGA mode changes, documentation
11-15-89 1.2 - Internal version, corrected EGA/VGA/MCGA program hang bugs
10-04-89 1.1 - Common functions separated to SPYSUP, recovery improved.
               First public release.
09-30-89 1.0 - Internal version, never released

Operation
---------
SPY is in two parts: SPY.EXE and SPYTSR.EXE.

SPYTSR is a "Terminate and Stay Resident" program that must be running on the
machine to be controlled.  Run like this:

  SPYTSR name [adapter]

..where "name" is the network name by which this invocation of SPYTSR is to
be known, and (optional) "adapter" is a numeric network adapter number.  If
adapter is omitted, SPYTSR uses adapter zero.  The network name may be up
to fifteen characters long.  All alphabetic characters in the name are shifted
to upper case.  The name may not contain spaces.  The actual network name that
SPYTSR adds to the adapter is the name specified padded to the right with
spaces to fifteen characters and terminated with 0EFh as the sixteenth
character.

SPYTSR occupies about 36k (large for a TSR, but not too bad for one written in
a high-level language), and does very little except listen until it receives a
request from SPY.  SPYTSR handles these types of requests:

  SendScreen     - Reads the contents of the video buffer and cursor position
                   into an internal buffer and transmits it to the client.

  StuffKeyboard  - Copies Key and Scan Codes from the client's message to an
                   internal table where they are inserted into the keyboard
                   stream by the Int 16h intercept.  To the user, keystrokes
                   simply appear out of nowhere.  It's really spooky.

  Boot           - Reboots the system running SPYTSR as if the user had
                   performed a "three finger salute" (Ctrl-Alt-Del).

  DieQuietly     - SPYTSR cancels all its sessions and commands, deletes its
                   network name and removes itself from memory.

  SendScreenInfo - SPYTSR returns information about it's video screen,
                   including the adapter type, video mode, number of rows
                   and columns, and the maximum size of the buffer that
                   SendScreen may transmit.

SPY is a quick-and-dirty remote control program that builds requests for
SPYTSR and displays the screen data returned by the SendScreen request.
Run like this:

  SPY name [adapter]

..where "name" is the network name by which an invocation of SPYTSR is known
(see above), and (optional) "adapter" is a numeric network adapter number.
If adapter is omitted, SPY uses adapter zero.  SPY constructs a network name
just like SPYTSR does, and then calls that name in an attempt to establish a
"session" with SPYTSR.  If SPY is unable to establish a session within about
half a minute, it gives up and terminates with an error message.  If SPY is
successful, it requests screen information via SendScreenInfo, allocates
memory for a screen buffer, and then begins its monitor cycle.

The monitor cycle has two independent components which are implemented as
subtasks in the SPY program. They are:

  Screen-Update cycle - About once every two seconds, SPY sends a SendScreen
  request to SPYTSR, receives the screen data reply and displays the screen
  data on the local screen.  For few seconds after the Keyboard cycle (see
  below) sends a StuffKeyboard request, the Screen-Update cycle requests
  screen data about twice each second.  Screen updates are suspended during
  "Break" processing.  The Screen-Update cycle also attempts to reestablish
  a broken session by calling SPYTSR.

  Keyboard cycle - SPY constantly checks for keystrokes by issuing
  Int 16h.  The keyboard cycle moves keystrokes to a StuffKeyboard request
  message transmits to SPYTSR.  The keyboard cycle also examines keystrokes
  for the "Break" key (Alt-0 in this implementation), displays the break
  menu on the screen, and processes the menu selection keystroke.

When the SPY user presses Alt-0, the Keyboard cycle displays the following menu
on the screen:

    You are connected to remote system <name>
    Break menu:

      (E)xit SPY on local system
      (B)oot remote system
      (S)top SPYTSR on remote system
      (Alt-0) Send Alt-0 to remote system

    Press a key to choose an action or <Esc> to return...

The next keystroke determines the action taken by SPY, as indicated on
the menu.  Allowable keystrokes are indicated in parentheses.  All other
keystrokes are ignored, except Escape which returns the user to the screen
update display.  If the user chooses any option except Alt-0 or Escape, SPY
terminates after restoring the original screen saved when it started.

Two other utilities are supplied: SPYSTOP.EXE and SPYBOOT.EXE.  These are
non-interactive commands that simply issue the DieQuietly (SPYSTOP) and
Boot (SPYBOOT) requests to a SPYTSR invocation.  Both utilities accept the
same command line parameters as SPY.EXE.

The executable code for SPY is distributed in the SPYEXE.ZIP archive.  This
archive includes the following files:

  SPYTSR.EXE   - Resident portion of SPY
  SPY.EXE      - SPY monitor
  SPYSTOP.EXE  - Remote stop utility
  SPYBOOT.EXE  - Remote boot utility
  SPY.DOC      - This file

Source Code
-----------
The source code for SPY is distributed in the SPYSRC.ZIP archive.  This
archive includes the following source files:

  SPY.PAS      - Source code for SPY
  SPYTSR.PAS   - Source code for SPYTSR
  SPYSTOP.PAS  - Source code for SPYSTOP
  SPYBOOT.PAS  - Source code for SPYBOOT
  SPYSUP.PAS   - Source code for support unit with common declarations for
                 other SPY sources.

In addition SPYSRC contains the following support files:

  NETBIOS.TPU  - Precompiled unit for NetBios support
  NETBIOS.DOC  - A copy of the Interface section for NETBIOS.TPU
  TSR.TPU      - Precompiled unit for Terminate and Stay Resident support
  TSR.DOC      - A copy of the Interface section for TSR.TPU
  MULTI.TPU    - Precompiled unit for Non-preemptive multitasking
  MULTI.DOC    - A copy of the Interface section for MULTI.TPU
  MULTITSR.PAS - Source code for unit which links MULTI and TSR units
  SCREEN.PAS   - Source code for screen I/O unit
  SCREEN.OBJ   - Preassembled external routines for SCREEN
  SPY.DOC      - This file

Because the precompiled units were compiled with Turbo Pascal, v5.5., that
version of the compiler must be used to compile the source code supplied.
Source code for units: NETBIOS, TSR, MULTI, and SCREEN.ASM will be available
from the author at some future date.

Limitations
-----------
SPY works with NetBIOS, only.  Users of Novell networks which are not running
on top of NetBIOS must install the NetBIOS emulation facility to use SPY.
SPY was developed on an ArtiSoft LANtastic network.

This version of SPY properly displays text-mode screens only.  It does not
translate attribute bytes when monitoring a screen which displays many colors
on a monitor which displays fewer colors, so your text may look strange when
you "SPY" a CGA, EGA or VGA screen on a monochrome monitor.  Graphics will
simply look like garbage.  Also, no provision is made to monitor off-screen
portions of an EGA or VGA 43 or 50 line mode screen on an adapter which is
currently displaying 80 x 25.  In that case, only the upper-left corner of the
screen will display.  SPY uses the current mode of the screen from which it
is run, so it may be advisable to issue a MODE command before running SPY.

The keyboard cycle on both SPY and SPYTSR works entirely with the data
available via Int 16h.  So it will be impossible to trigger programs which
monitor the BIOS shift state flags or the keyboard interrupt (Int 09h). This
includes many TSR's, like SideKick (I haven't actually tried it with SideKick,
but suspect it won't work), LanPup, and some communications programs (ProComm
works nicely; in fact, I use it to run ProComm on a network server from my
office).  Because of the communications delay and the relatively long interval
between screen updates, remote keyboarding appears sort of "jumpy"; the
character keyed may not appear immediately on the monitor.  This can be
disconcerting to some typists (it is to me).

In addition to the areas indicated above, a commercial implementation of a
network remote control program should perform data compression on screen data.
This would allow screen updates to occur more often without swamping the
network and might improve the "jumpy" effect.  Perhaps a copy of the screen
last transmitted could be maintained in SPYTSR and only the differences sent
(this gets a little tricky where multiple clients are requesting screens
asynchronously, so to keep the demo simple I didn't attempt it here.).

True to it's name, SPY has absolutely no security features.  The user of the
remote system running SPYTSR is completely at the mercy of anyone who knows
its network name and has a copy of SPY.  A commercial implementation should
provide some form of password protection and SPYTSR should beep or show a
courtesy warning message on the monitored screen whenever SPY connects.  The
target system user should have the option of being or not being monitored.

SPY should be rewritten to manage multiple remote screens in separate windows,
and, finally, SPYTSR should be rewritten in assembler to reduce it's overhead.

Or, you could buy The Network Eye (tm) by Artisoft in Tucson Arizona.  I
hear good things about this product, though I haven't tried it yet.  I
believe it implements most of the "improvements" listed above, including
especially multiple windows.

Other uses
----------
The SPY and SPYTSR source programs provide a "shell" which may be used to
implement other "client-server" applications in Pascal.  Those portions of
SPYTSR which handle SPY requests may be replaced with code which does just
about anything.  The support units; MULTI and TSR remove most of the
restrictions ordinarily associated with TSR's in high level languages.  In
particular, the server may open files and do disk I/O with standard Pascal
procedures.  SPYTSR is an example of a "context free" server in that it does
not need to distinguish between its clients or remember anything about
previous transactions.

What's in store
---------------
I plan to supplement the NETBIOS and MULTI units early next year (90) with
units to handle most of the dirty work of client-server applications through
NetBios; in particular: synchronization and error recovery after interruption
of the network connection, and facilities for creating "context dependent"
servers.  In the near future I will make available the source code for the
precompiled units.  Please drop me a note (write, please, don't call) if you
want to be notified when these are ready.

                          - End -