                                  Avalanche
                                  =========



Introduction
============
Avalanche is a VNC (Virtual Network Computing) client for RISC OS; it allows
you to use a remote machine running a VNC server over a local network or the
internet. VNC servers are available for most popular platforms, Avalanche is
known to work with Xvnc, TightVNC, OSXVNC, WinVNC, UltraVNC and RealVNC.


Installation
=============
Just drag the !Avalanche application from the archive to whichever location
you want and run it from there.

If the choices and manage hotlist options are shaded on the iconbar menu,
then you need to install ConfiX, see below.


Requirements
============
  * RISC OS 4, Select and 5.
      Will probably run on anything from RISC OS 3.1. onwards.

  * SharedCLibrary 5.53
      Available from <http://www.iyonix.com/32bit/system.shtml>
      Note - at present, I am unaware of any freely available 32 bit
      SharedCLibrary 5.53 for the A9. If this runs (without hacks) on
      the A9, please let me know so I can update the documentation.

  * Nested WIMP
      Only required for RISC OS versions before 4.
      Available from <http://www.riscos.com>

  * Reasonably up to date Toolbox modules
      Available from <http://www.riscos.com>

  * BypassAlt
      Optional, allows Avalanche to pass Alt key presses to the server
      without the RISC OS key handler interpreting them. Makes keyboard
      shortcuts possible.
      Available from the same site as Avalanche (see link below).

  * ConfiX
      Optional, allows hotlist and choices to be edited.
      Available from <http://www.xat.nl/en/riscos/sw/confix>.

  * SysLog
      Optional, allows logging to be captured.
      Provided as standard in RISC OS Select/Adjust, otherwise a version is
      available from <http://www.compton.nu/syslog.html>

  * SocketWatch
      Optional, if present, increases efficiency of network reads. This
      should reduce the load on the local machine and improve latency.


Quick Start
===========
Double click on !Avalanche; the !Avalanche icon should appear on the right
side of the icon bar. Click SELECT on the icon, fill in the host field with
the name or IP address of the machine to connect to and click SELECT on
Connect. A window should open and in a second or so, the title bar showing
the machine name and an image of the desktop will appear.

Any clicks or key presses directed at that window are sent to the server and
the results displayed in that window. A connection is terminated by closing
the window, the Avalanche menu is available by clicking MENU over the status
bar at the bottom of the window.

Avalanche fully supports interactive help.


Full Screen Mode - Important
============================
To get a menu in full screen mode, press the right Alt key and click MENU. If
there is a border, because the view is smaller than the current screen mode,
you can click MENU over that as well. If, in the choices, F12 is configured
to be passed to the RISC OS desktop, Shift-F12 will bring the iconbar to the
front as usual and F12 will switch out of full screen mode, returning to the
desktop.


Choices and Hotlist
===================
The main choices are available from the iconbar menu if you have ConfiX
installed. These choices are used by default when starting a connection via
the Connect window or URI. Each hotlist item has its own set of choices and
optionally allows a password to be stored insecurely. If the password field
is left empty, you will be prompted for the password if the server asks for
one. ADJUST clicking on the iconbar icon brings up the hotlist.


Scale to Fit the Window
=======================
When the scale view to window option is enabled, the view of the remote
screen is scaled to fit the visible window size. In this mode, the window's
toggle size icon can be used to quickly open the window to a 1:1 scale,
or as large as the local screen mode allows. Clicking on toggle size again
will restore the window's original size and position. This can be useful
if you want to keep an eye on the remote machine and occasionally interact
with it while working on something else.


Performance Issues
==================
Depending on the encodings used by the server, 32 thousand colour screens
can take twice as much data to update as 64 or 256 colour ones and 16
million colour screens can require 3 or 4 times as much data. If you find
performance lacking, try dropping the number of colours; this can help
over limited bandwidth connections.

The 64 and 256 colour screens will have no difference in performance. The
64 colour screen forces the server to use equal precisions for each of the
red, green and blue components. This will stop tinting of the display
caused by some servers making a bad choice of colours in a 256 colour
mode.

If the connection is still too slow, the other main way to improve
performance is to simplify the screen data so can be better compressed by
the VNC algorithm. In particular: single colour backdrops, non-anti-aliased
fonts and plain window furniture will usually be quicker; avoiding large,
especially photograph like, images and animations will be quicker.

Over a fast local network, most of the above is not needed. In practice, a
32k screen is very usable (assuming a competent VNC server).


Clipboard
=========
The RISC OS clipboard and clipboards of all active VNC sessions are linked
allowing text to be copied and pasted between sessions and local RISC OS
applications. Only plain text will be transferred and there is a limit on
the maximum transmitted text size; the status bar will indicate when
clipboard data is transferred between machines and when it isn't due to
being too long. Dragging a text file onto the VNC window will also paste
it onto the server's clipboard.

Note that some applications do not notify other running tasks if you
paste to the clipboard twice without pasting using another application
in between. Although it is perfectly valid for them to do this, it means
!Avalanche can't tell that new data is on the clipboard to send to the
server.


Keyboard and Mouse Handling
===========================
The basic keyboard and mouse changes (key/button press/release) are simulated
from higher level events generated by the RISC OS Window Manager. In
practice, this works well for almost all applications and means the keyboard
behaves in the same way as it does on RISC OS.

  * When connecting to a Mac, you should be able to generate the apple
    command key by using either of Alt or Meta (windows keys).

  * Normal keys are not sent as being held down - each RISC OS key event is
    sent as a key press immediately followed by a key release, so a press and
    hold will auto-repeat at the rate configured on RISC OS regardless of
    the server.
    The modifier keys Shift, Ctrl, Alt and Meta (windows keys) are handled
    specially to allow key combinations to work.

  * The RISC OS keyboard settings are respected. On RISC OS 5, non latin-1
    alphabets are supported, including UTF-8. This means that foreign
    keyboards and custom keyboard drivers should 'just work' (assuming
    they do on RISC OS and the server/OS combination you're connecting to
    can cope with them - TightVNC on Linux can for instance).

  * Alt is usually interpreted by RISC OS, so with an english keyboard Alt-[
    E will produce e-acute and Alt-C will produce a copyright symbol. This
    is not (usually) useful for VNC, so Avalanche uses a module 'BypassAlt'
    to disable this behaviour, allowing Alt-C to be passed to the VNC server
    as Alt-C and not (C). The usual RISC OS behaviour can be restored from
    the choices/hotlist Other section. BypassAlt is available from the
    Avalanche website.

  * Certain key presses have to be disentangled. Under the RISC OS Window
    Manager, SHIFT-Up is delivered as PageUp. Avalanche checks for things
    like this and breaks them up.


Using port numbers
==================
The new connection window lets you set the VNC display number. VNC display
n corresponds to TCP/IP port number 5900+n. If you wish to use
non-standard ports, this can be done by explicitly appending the port
number to the hostname with a colon, for example:
'myvncserver.somewhere.net:12345'.


Launching from URIs/other programs
==================================
Avalanche acts on 'vnc:' URIs allowing VNC sessions to be initiated by
clicking on a link in a browser window, double clicking on a URI file,
using the command line '*URIDispatch' or by another application. The
syntax is basic at the moment, not allowing options to be specified.

  vnc://<hostname>[:<port>]

If the port is omitted, the default display 0 port of 5900 is used.


Security
========
Avalanche supports the simple VNC DES challenge/response authentication
method. This should not be regarded as secure and in any case, once the
connection is made nothing is encrypted, so all key presses and screen data
would be easy to decode if they were intercepted.

If the local and remote clipboard linking is enabled, any text copied to the
clipboard on the local machine will be transmitted to the server, not
encrypted. This could be a risk if you copy and paste private details
between two other local applications.

If you wish to have a secure connection, I suggest you use a SSH tunnel,
otherwise only use it on trusted networks.


Supported VNC features
======================
  * Protocol versions 3.3, 3.7 and 3.8.
  * Raw, CopyRect, RRE, CoRRE, Hextile and ZLib encodings.
  * Unauthenticated sessions and VNC authentication.
  * 6, 15 and 24bpp true colour and 8bpp colour mapped screens.
  * Screen resizing (DesktopSize pseudo-encoding).
  * Local pointer display (Cursor and XCursor pseudo-encodings).
  * Beep.
  * Getting server identity string (ServerIdentity pseudo-encoding).


Planned Improvements and Wish List
==================================
  * Tight and ZRLE encodings.
  * Connection statistics/information window.
  * Listening mode.
  * DeepKeys support?
  * TLS support.


Contact Details and Reporting Bugs
==================================
If you have any bug reports, suggestions or comments, feel free to send
them to jip22gm@googlemail.com. The latest version will be available
from http://effarig.co.uk/riscos/

If there is a crash, please include the end of the Avalanche Log (accessible
from the iconbar menu, if SysLog is running). It would be helpful if you
could have my SysLogDevice module running at the time (see Avalanche web
site), you can just double click on the module to load with without
installing it if you want and then start Avalanche. This will catch any
output from Avalanche as it crashes and write it to the log.

If you have issues with a server, the 'Encodings' options can disable
specific VNC features. All of them can be disabled and it should work,
although slowly.


Changes
=======
0.28 (14-Jun-2021) Beta:
  * Assembler now follows SCL rules, fixing ZeroPain errors generated within
    the environment handlers.

0.27 (30-Apr-2021) Beta:
  * Toggle size icon for views view is scaled to fit the window:
      - Toggle size resizes for a 1:1 scale, clipping to the screen edge.
      - Toggle size again restores the window's original size and location.
  * Support Julie Stamp's SysLog module:
      - Check System$LogDir as well as SysLog$LogDir for the log file.
      - "Show log..." option flushes the Avalanche SysLog before opening it.
  * Auto-scroll never started for maximised or scaled-to-fit windows.
  * More robust handling and reporting of unexpected errors such as aborts.
  * Limit clean up on unexpected termination to releasing global resources.

0.26 (01-Apr-2021) Beta:
  * Workaround for tasks which fail to handle concurrent clipboard fetches.

0.25 (25-Mar-2021) Beta:
  * Fix instability which could occur sending large messages to server.

0.24 (20-Mar-2021) Beta:
  * Fix likely fatal error when handling key presses.
  * Fix corruption of displayed authentication failure error message.
  * Assorted minor fixes and cleaning up.

0.23 (26-Apr-2013):
  * Add option to open connections from the hotlist on start up.

0.22 (28-Dec-2009):
  * ZLib also built for ARMv7 compatibility this time.

0.21 (10-Dec-2009):
  * Built for ARMv7 compatibility.

0.20 (02-Oct-2009):
  * New option to pass Alt-Arrow keys to RISC OS (useful with MoreDesk).
  * Full screen fixes which showed up when switching virtual desktops.
  * Update contact details.

0.19 (29-Nov-2007):
  * Workaround for toolbox bug, caused crash on some clipboard operations.
  * Dropping a text file on the VNC window sends it to the remote clipboard.
  * Full screen mode reimplemented in a more sensible way.
  * Can start new session full screen or with scale to window enabled.
  * A couple of typos and assorted buglets fixed.

0.18 (02-Apr-2007):
  * F12 returns to desktop in full screen mode when not sent to the server.
  * Added option to lose input focus, can be useful in full screen mode.
  * Better interaction with !MoreDesk, especially in full screen mode.

0.17 (28-Jan-2007):
  * Full screen support.
  * Auto-scroll now works when window is full size, but not full extent.
  * Option to pass F12 combinations through to the desktop, not the server.
  * Added F12 to send keypress menu.
  * Changed default scale buttons to 50%, 100%, 200%, 400%.
  * Window resize icon behaves normally unless fit to window enabled.
  * Status bar and horizontal scroll bar now share space when resizing.
  * Fixed leaking of status window when closing a view.
  * Update window size of screen mode changes.

0.16 (14-Jan-2007):
  * Fixed pointer jumping bug when auto-scrolling at edge of VNC screen.
  * Change RISC OS pointer while auto-scrolling.
  * Disable auto-scrolling when window full size.
  * Release all VNC mouse buttons when the RISC OS pointer exits window.
  * Fixed bug causing initial window size of second view to be incorrect.
  * Loads of fixes to data transfer code, can now copy and paste to NetSurf.
  * Added support for ServerIdentity encoding.
  * Revamped version selection logic.
  * Fixed boot file resetting variables when they are already set.

0.15 (15-Oct-2006) Stable:
  * Added link to website from program info window.
  * Fixed URI handling bug introduced in 0.14.
  * Iconised windows attempt to put something sensible under the icon now.
  * Slightly better icon.

0.14 (04-Aug-2006) Beta:
  * Limit pollword events to avoid hogging the machine with rapid updates.
  * Hopefully fixed screen corruption problems with rectangle copying.
  * Changes to match changes to ctbutils library.

0.13 (09-Jul-2006) Beta:
  * Added option to use window auto-scrolling when dragging.
  * Use SocketWatch module, if available, to improve network read efficiency.
  * Tidied up ConfiX window.
  * Fixed 1 pixel vertical offset between local and remote pointers.
  * Added interactive help messages.
  * Added approximate frame buffer update frequency display to status bar.

0.12 (27-Feb-2006) Stable:
  * Bugfix to clipboard handling fixing problem with local paste from 0.10.

0.11 (09-Feb-2006) Beta:
  * Protocol version number fallback fixed (can connect to UltraVNC now).

0.10 (08-Jan-2006) Beta:
  * Server changing screen size actually works now.
  * Global choices configuration added (needs !Confix).
  * Hotlist (needs !Confix).
  * Local display of pointer added.
  * Can hide/alter the RISC OS pointer or just show the VNC one.
  * Non-interactive passive views which only show the screen.
  * Hopefully fixed Alt key issues.
  * Added menu options for sending Ctrl-Alt-Delete and Alt-Enter.
  * Option to auto-pick screen depth depending on what the server suggests.
  * Status bar gives more feedback on progress during connection.
  * Added approximate bandwidth monitor to status bar.
  * Updated required module versions to recommended ones.
  * Logging sent directly to 'Avalanche' SysLog now.
  * Added view log to iconbar menu.

0.09 (02-Oct-2005) Stable:
  * Fixed handling when writing to closed connection to stop assert failure.
  * Fix to fix in 0.08 (sometimes sending two SecuritySpecify messages).

0.08 (29-Sep-2005):
  * Responds to SecurityList message, so non-V3.3 connections don't stall.

0.07 (21-Sep-2005):
  * Initial latency when moving mouse reduced.
  * Claiming input focus and keyboard navigation of writable icons improved.
  * More friendly message when not entering a hostname.
  * Beep enabled.
  * 8 bit alphabets other than latin-1 work now.

0.06 (21-Aug-2005):
  * Fixed slow window redraw in 24 million colour screen modes.
  * Implemented scaling.
  * Improved mouse and screen update polling, is now more responsive.
  * Uses much less processor time (limited to at most 100 polls per second).
  * Some network errors made a little more friendly.
  * Added help option to iconbar menu.

0.05 (05-Aug-2005):
  * 16m and 32k screens disabled on RISC OS versions not supporting them.
  * Fix to network error handling.
  * Fix to clipboard fetching.

0.04 (29-Jul-2005):
  * Support for handling vnc://<host>[:port] URIs.
  * Status bar implemented, click MENU over bar to get Avalanche menu.
  * Middle button clicks no longer open RISC OS menu - just passed to server.
  * Doesn't demand newest toolbox modules anymore, but requires nested wimp.
  * Inaccessible options now shaded out on VNC screen menu.
  * VNC screen window opened immediately instead of waiting for connection.
  * Updated ZLib to version 1.2.3.

0.03 (23-Jul-2005):
  * The basic VNC authentication (DES challenge/response) implemented.
  * TCP/IP connections can override the display port number using host:port.
  * Fix crash when quitting with an open session.

0.02 (02-Jul-2005):
  * Better keyboard support, should understand UTF-8 alphabet on RISC OS 5.
  * Supports screen resizing, though untested at present.
  * Fix to rectangle fill (affected hextile, RRE and CoRRE encodings).
  * Attempts to set display palette not ignored anymore.
  * Option for 64 colour display.

0.01 (12-Oct-2004):
  * Initial version.


Acknowledgements
================
Avalanche uses the following third party software:

  * ZLib compression library:
    (C) 1995-2003 Jean-loup Gailly and Mark Adler.

  * DES authentication code is derived from D3DES:
    Copyright (c) 1988,1989,1990,1991,1992 by Richard Outerbridge.
    (GEnie : OUTER; CIS : [71755,204]) Graven Imagery, 1992.

  * ConfiX (Paul Reuvers/XAT) is a separate application which, if installed,
    is used to provide the dialogue box for editing the user choices.

  * SocketWatch (C) Dickon Hood is a separate module which, if installed, is
    used by Avalanche to get rapid notification of incomming network data
    instead of polling for it.


License
=======
Copyright (C) 2005-2021, James Peacock.
All rights reserved.

Redistribution and use in binary form, without modification, is permitted
provided that the following conditions are met:

  1. Redistributions in binary form must reproduce the distribution
     unmodified and in its entirety.

  2. Redistributions in binary form must be provided free of charge.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
