source: trunk/vnc/vnc_javasrc/README @ 91

Last change on this file since 91 was 66, checked in by quentin, 17 years ago

Initial checkin of modified Java VNC viewer for use as remote console

File size: 21.3 KB
Line 
1
2  TightVNC Java Viewer version 1.3.9
3
4======================================================================
5
6This distribution is based on the standard VNC source and includes new
7TightVNC-specific features and fixes, such as additional low-bandwidth
8optimizations, major GUI improvements, and more.
9
10        Copyright (C) 1999 AT&T Laboratories Cambridge.
11        Copyright (C) 2000 Tridia Corp.
12        Copyright (C) 2002-2003 RealVNC Ltd.
13        Copyright (C) 2001-2004 HorizonLive.com, Inc.
14        Copyright (C) 2000-2007 Constantin Kaplinsky
15        Copyright (C) 2000-2007 TightVNC Group
16        All rights reserved.
17
18This software is distributed under the GNU General Public Licence as
19published by the Free Software Foundation. See the file LICENCE.TXT for the
20conditions under which this software is made available. TightVNC also
21contains code from other sources. See the Acknowledgements section below, and
22the individual files for details of the conditions under which they are made
23available.
24
25
26Compiling from the sources
27==========================
28
29To compile all the .java files to .class files, simply do:
30
31        % make all
32
33This will also generate a JAR (Java archive) file containing all the classes.
34Most JVM (Java Virtual Machine) implementations are able to use either a set
35of .class files, or the JAR archive.
36
37
38Installation
39============
40
41There are three basic ways to use TightVNC Java viewer:
42
43  1. Running applet as part of TightVNC server installation.
44
45     Both the Unix and Windows versions of TightVNC servers include small
46     built-in HTTP server which can serve Java viewer to Web clients. This
47     enables easy Web access to the shared desktop without need to install
48     any software on the client computer. Unix and Windows versions of
49     TightVNC servers are different in the way they store the .class and .jar
50     files: the Unix server (Xvnc) is able to serve any set of files present
51     in a particular directory, while the Windows server (WinVNC) has all the
52     .class and .jar files inside the WinVNC executable file. Therefore, for
53     Xvnc, it's enough to copy the files into a correct directory, but for
54     WinVNC, the server binaries should be rebuild if the built-in Java
55     viewer should be updated.
56
57     To install the Java viewer under Xvnc, copy all the .class files, the
58     .jar file and the .vnc files to an installation directory (e.g.
59     /usr/local/vnc/classes):
60
61         cp *.class *.jar *.vnc /usr/local/vnc/classes
62
63     Also, make sure that the vncserver script is configured to point to the
64     installation directory (see the Xvnc manual page for the description of
65     the -httpd command-line option).
66
67  2. Running applet hosted on a standalone Web server.
68
69     Another possibility to use the Java viewer is to install it under a
70     fully-functional HTTP server such as Apache or IIS. Obviously, this
71     method requires running an HTTP server, and due to the Java security
72     restrictions, it's also required that the server should be installed on
73     the same machine which is running the TightVNC server. In this case,
74     installation is simply copying the .class and .jar files into a
75     directory that is under control of the HTTP server. Also, an HTML page
76     should be created which will act as a the base document for the viewer
77     applet (see an example named index.html in this distribution).
78
79     NOTE: Provided index.html page is an example only. Before using that
80     file, edit it with a text editor. See more information inside
81     index.html.
82
83  3. Running the viewer as a standalone application.
84
85     Finally, the Java viewer can be executed locally on the client machine,
86     but this method requires installation of either JRE (Java Runtime
87     Environment) or JDK (Java Development Kit). If all the .class files are
88     in the current directory, the Java viewer can be executed like this,
89     from the command line:
90
91         java VncViewer HOST vnchost PORT 5900
92
93     The parameters HOST and PORT are required, but there is a number of
94     optional parameters as well (see the Parameters section below).
95
96Parameters
97==========
98
99TightVNC Java viewer supports a number of parameters allowing you to
100customize its behavior. Most parameters directly correspond to the settings
101found in the Options window. However, there are parameters that do not
102correspond to those settings. For such parameters, you can see a note "no GUI
103equivalent", in the documentation below.
104
105Parameters can be specified in one of the two ways, depending on how the Java
106viewer is used:
107
108  1. When the Java viewer is run as an applet (embedded within an HTML
109     document), parameters should be specified in the <PARAM> HTML tags,
110     within the appropriate <APPLET> section. Here is an example:
111
112    <APPLET CODE=VncViewer.class ARCHIVE=VncViewer.jar WIDTH=400 HEIGHT=300>
113      <PARAM NAME="PORT" VALUE=5901>
114      <PARAM NAME="Scaling factor" VALUE=50>
115    </APPLET>
116
117  2. When run as a standalone application, the Java viewer reads parameters
118     from the command line. Command-line arguments should be specified in
119     pairs -- first goes parameter name, then parameter value. Here is a
120     command line example:
121
122     java VncViewer HOST vnchost PORT 5901 "Scaling factor" 50
123
124Both parameter names and their values are case-insensitive. The only
125exception is the "PASSWORD" parameter, as VNC passwords are case-sensitive.
126
127Here is the complete list of parameters supported in TightVNC Java viewer:
128
129--> "HOST" (no GUI equivalent)
130
131    Value: host name or IP address of the VNC server.
132    Default: in applet mode, the host from which the applet was loaded.
133
134    This parameter tells the viewer which server to connect to. It's not
135    needed in the applet mode, because default Java security policy allow
136    connections from applets to the only one host anyway, and that is the
137    host from which the applet was loaded. However, this parameter is
138    required if the viewer is used as a standalone application.
139
140--> "PORT" (no GUI equivalent)
141
142    Value: TCP port number on the VNC server.
143    Default: none.
144
145    This parameter is required in all cases. Note that this port is not the
146    one used for HTTP connection from the browser, it is the port used for
147    RFB connection. Usually, VNC servers use ports 58xx for HTTP connections,
148    and ports 59xx for RFB connections. Thus, most likely, this parameter
149    should be set to something like 5900, 5901 etc.
150
151--> "PASSWORD"
152
153    Value: session password in plain text.
154    Default: none, ask user.
155
156    DO NOT EVER USE THIS PARAMETER, unless you really know what you are
157    doing. It's extremely dangerous from the security point of view. When
158    this parameter is set, the viewer won't ever ask for a password.
159
160--> "ENCPASSWORD"
161
162    Value: encrypted session password in hex-ascii.
163    Default: none, ask user.
164
165    The same as the "PASSWORD" parameter but DES-encrypted using a fixed key.
166    Its value should be represented in hex-ascii e.g. "494015f9a35e8b22".
167    This parameter has higher priority over the "PASSWORD" parameter. DO NOT
168    EVER USE THIS PARAMETER, unless you really know what you are doing. It's
169    extremely dangerous from the security point of view, and encryption does
170    not actually help here since the decryption key is always known.
171
172--> "Encoding"
173
174    Values: "Auto", "Raw", "RRE", "CoRRE", "Hextile", "ZRLE", "Zlib", "Tight".
175    Default: "Auto".
176
177    The preferred encoding. If the value is "Auto", then the viewer will
178    continuously estimate average network throughput and request encodings
179    that are appropriate for current connection speed. "Hextile" is an
180    encoding that was designed for fast networks, while "Tight" is better
181    suited for low-bandwidth connections. From the other side, "Tight"
182    decoder in the TightVNC Java viewer seems to be more efficient than
183    "Hextile" decoder so it may be ok for fast networks too. "ZRLE" encoding
184    is similar to "Tight", but it does not support JPEG compression and
185    compression levels. Unlike "Tight" encoding, "ZRLE" is supported in
186    recent versions of RealVNC products. Other encodings are not efficient
187    and provided for compatibility reasons.
188
189--> "Compression level"
190
191    Values: "Default", "1", "2", "3", "4", "5", "6", "7", "8", "9".
192    Default: "Default". ;-)
193
194    Use specified compression level for "Tight" and "Zlib" encodings. Level 1
195    uses minimum of CPU time on the server but achieves weak compression
196    ratios. Level 9 offers best compression but may be slow in terms of CPU
197    time consumption on the server side. Use high levels with very slow
198    network connections, and low levels when working over higher-speed
199    networks. The "Default" value means that the server's default compression
200    level should be used.
201
202--> "JPEG image quality"
203
204    Values: "JPEG off", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9".
205    Default: "6".
206
207    Use the specified image quality level in "Tight" encoding. Quality level
208    0 denotes bad image quality but very impressive compression ratios, while
209    level 9 offers very good image quality at lower compression ratios. If
210    the value is "JPEG off", the server will not use lossy JPEG compression
211    in "Tight" encoding.
212
213--> "Cursor shape updates"
214
215    Values: "Enable", "Ignore", "Disable".
216    Default: "Enable".
217
218    Cursor shape updates is a protocol extension used to handle remote cursor
219    movements locally on the client side, saving bandwidth and eliminating
220    delays in mouse pointer movement. Note that current implementation of
221    cursor shape updates does not allow a client to track mouse cursor
222    position at the server side. This means that clients would not see mouse
223    cursor movements if mouse was moved either locally on the server, or by
224    another remote VNC client. Set this parameter to "Disable" if you always
225    want to see real cursor position on the remote side. Setting this option
226    to "Ignore" is similar to "Enable" but the remote cursor will not be
227    visible at all. This can be a reasonable setting if you don't care about
228    cursor shape and don't want to see two mouse cursors, one above another.
229
230--> "Use CopyRect"
231
232    Values: "Yes", "No".
233    Default: "Yes".
234
235    The "CopyRect" encoding saves bandwidth and drawing time when parts of
236    the remote screen are moving around. Most likely, you don't want to
237    change this setting.
238
239--> "Restricted colors"
240
241    Values: "Yes", "No".
242    Default: "No".
243
244    If set to "No", then 24-bit color format is used to represent pixel data.
245    If set to "Yes", then only 8 bits are used to represent each pixel. 8-bit
246    color format can save bandwidth, but colors may look very inaccurate.
247
248--> "Mouse buttons 2 and 3"
249
250    Values: "Normal", "Reversed".
251    Default: "Normal".
252
253    If set to "Reversed", then right mouse button (button 2) will act as it
254    was middle mouse button (button 3), and vice versa.
255
256--> "View only"
257
258    Values: "Yes", "No".
259    Default: "No".
260
261    If set to "Yes", then all keyboard and mouse events in the desktop window
262    will be silently ignored and will not be passed to the remote side.
263
264--> "Scale remote cursor"
265
266    Values: "No", "50%", "75%", "125%", "150%".
267    Default: "No".
268
269    If a percentage value is specified, the remote cursor is reduced
270    or enlarged accordingly. Scaling takes place only when "View only"
271    is set to "No", and "Cursor shape updates" is set to "Enable".
272
273--> "Share desktop"
274
275    Values: "Yes", "No".
276    Default: "Yes".
277
278    Share the connection with other clients on the same VNC server. The exact
279    behaviour in each case depends on the server configuration.
280
281--> "Open new window" (no GUI equivalent, applicable only in the applet mode)
282
283    Values: "Yes", "No".
284    Default: "No".
285
286    Operate in a separate window. This makes possible resizing the desktop,
287    and adds scroll bars when necessary. If the server supports variable
288    desktop size, the window will resize automatically when remote desktop
289    size changes.
290
291--> "Scaling factor" (no GUI equivalent)
292
293    Value: an integer in the range of [1..1000], or the string "auto".
294    Default: "100".
295
296    Scale local representation of the remote desktop. The value is
297    interpreted as scaling factor in percents. The default value of 100%
298    corresponds to the original framebuffer size. Values below 100 reduce
299    image size, values above 100 enlarge the image proportionally. If the
300    parameter is set to "auto", automatic scaling is performed. Auto-scaling
301    tries to choose scaling factor such way that the whole remote framebuffer
302    will fit on the local screen. Currently, auto-scaling is supported only
303    when the remote desktop is shown in a separate frame (always true in the
304    application mode, and also in the applet mode with "Open new window"
305    parameter set to "yes").
306
307--> "Show controls" (no GUI equivalent)
308
309    Values: "Yes", "No".
310    Default: "Yes".
311
312    Set to "No" if you want to get rid of that button panel at the top.
313
314--> "Offer relogin" (no GUI equivalent, not applicable in the applet mode)
315
316    Values: "Yes", "No".
317    Default: "Yes".
318
319    If set to "No", the buttons "Login again" and "Close window" won't be
320    shown on disconnects or after an error has occured.
321
322--> "Show offline desktop" (no GUI equivalent)
323
324    Values: "Yes", "No".
325    Default: "No".
326
327    If set to "Yes", the viewer would continue to display desktop even
328    if the remote side has closed the connection. In this case, if the
329    button panel is enabled, then the "Disconnect" button would be
330    changed to "Hide desktop" after the connection is lost.
331
332--> "Defer screen updates" (no GUI equivalent)
333
334    Value: time in milliseconds.
335    Default: "20".
336
337    When updating the desktop contents after receiving an update from server,
338    schedule repaint within the specified number of milliseconds. Small delay
339    helps to coalesce several small updates into one drawing operation,
340    improving CPU usage. Set this parameter to 0 to disable deferred updates.
341
342--> "Defer cursor updates" (no GUI equivalent)
343
344    Value: time in milliseconds.
345    Default: "10".
346
347    When updating the desktop after moving the mouse, schedule repaint within
348    the specified number of milliseconds. This setting makes sense only when
349    "Cursor shape updates" parameter is set to "Enable". Small delay helps to
350    coalesce several small updates into one drawing operation, improving CPU
351    usage. Set this parameter to 0 to disable deferred cursor updates.
352
353--> "Defer update requests" (no GUI equivalent)
354
355    Value: time in milliseconds.
356    Default: "50".
357
358    After processing an update received from server, wait for the specified
359    number of milliseconds before requesting next screen update. Such delay
360    will end immediately on every mouse or keyboard event if not in the "view
361    only" mode. Small delay helps the server to coalesce several small
362    updates into one framebuffer update, improving both bandwidth and CPU
363    usage. Increasing the parameter value does not affect responsiveness on
364    mouse and keyboard events, but causes delays in updating the screen when
365    there is no mouse and keyboard activity on the client side.
366
367--> "SocketFactory" (no GUI equivalent)
368
369    Value: name of the class.
370    Default: none.
371
372    This option provides the way to define an alternate I/O implementation.
373    The dynamically referenced class must implement a SocketFactory
374    interface, and create a Socket, as configured by this parameter. See the
375    source in SocketFactory.java.
376
377
378RECORDING VNC SESSIONS
379======================
380
381Current version of the TightVNC Java viewer is able to record VNC (RFB)
382sessions in files for later playback. The data format in saved session files
383is compatible with the rfbproxy program written by Tim Waugh. Most important
384thing about session recording is that it's supported only if Java security
385manager allows access to local filesystem. Typically, it would not work for
386unsigned applets. To use this feature, either use TightVNC Java viewer as a
387standalone application (Java Runtime Environment or Java Development Kit
388should be installed), or as a signed applet. The code checks if it's possible
389to support session recording, and if everything's fine, the new "Record"
390button should appear in the button panel. Pressing this button opens new
391window which controls session recording. The GUI is pretty self-explained.
392
393Other important facts about session recording:
394
395--> All sessions are recorded in the 24-bit color format. If you use
396    restricted colors (8-bit format), it will be temporarly switched to
397    24-bit mode during session recording.
398
399--> All sessions are recorded with cursor shape updates turned off. This is
400    necessary to represent remote cursor movements in recorded sessions.
401
402--> Closing and re-opening the recording control window does not affect the
403    recording. It's not necessary to keep that window open during recording a
404    session.
405
406--> Avoid using Zlib and ZRLE encodings when recording sessions. If you have
407    started recording BEFORE opening a VNC session, then you are ok. But
408    otherwise, all Zlib-encoded updates will be saved Raw-encoded (that is,
409    without compression at all). The case with ZRLE is even worse -- ZRLE
410    updates will not be saved at all, so the resulting session file may be
411    corrupted. Zlib decoding depends on the pixel data received earlier, thus
412    saving the data received from the server at an arbitrary moment is not
413    sufficient to decompress it correctly. And there is no way to tell Zlib
414    or ZRLE decoder to reset decompressor's state -- that's a limitation of
415    these encoders. The viewer could re-compress raw pixel data again before
416    saving Zlib-encoded sessions, but unfortunately Java API does not allow
417    to flush zlib data streams making it impossible to save Zlib-encoded RFB
418    pixel data without using native code.
419
420--> Usually, Tight encoding is the most suitable one for session recording,
421    but some of the issues described above for the Zlib encoding affect the
422    Tight encoding as well. Unlike Zlib sessions, Tight-encoded sessions are
423    always saved Tight-encoded, but the viewer has to re-compress parts of
424    data to synchronize encoder's and decoder's zlib streams. And, due to
425    Java zlib API limitations, zlib streams' states have to be reset on each
426    compressed rectangle, causing compression ratios to be lower than in the
427    original VNC session. If you want to achieve the best possible
428    performance, turn recording on BEFORE connecting to the VNC server,
429    otherwise CPU usage and compression ratios may be notably less efficient.
430
431
432HINTS
433=====
434
435--> To refresh remote desktop in the view-only mode, press "r" or "R"
436    on the keyboard.
437
438
439ACKNOWLEDGEMENTS
440================
441
442This distribution contains Java DES software by Dave Zimmerman
443<dzimm@widget.com> and Jef Poskanzer <jef@acme.com>.  This is:
444
445    Copyright (c) 1996 Widget Workshop, Inc. All Rights Reserved.
446
447    Permission to use, copy, modify, and distribute this software and its
448    documentation for NON-COMMERCIAL or COMMERCIAL purposes and without fee
449    is hereby granted, provided that this copyright notice is kept intact.
450   
451    WIDGET WORKSHOP MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
452    SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT
453    NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
454    PARTICULAR PURPOSE, OR NON-INFRINGEMENT. WIDGET WORKSHOP SHALL NOT BE
455    LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
456    MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
457   
458    THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE
459    CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE
460    PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
461    NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
462    SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE
463    SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE
464    PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES").  WIDGET
465    WORKSHOP SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF
466    FITNESS FOR HIGH RISK ACTIVITIES.
467
468    Copyright (C) 1996 by Jef Poskanzer <jef@acme.com>.  All rights
469    reserved.
470
471    Redistribution and use in source and binary forms, with or without
472    modification, are permitted provided that the following conditions
473    are met:
474    1. Redistributions of source code must retain the above copyright
475       notice, this list of conditions and the following disclaimer.
476    2. Redistributions in binary form must reproduce the above copyright
477       notice, this list of conditions and the following disclaimer in the
478       documentation and/or other materials provided with the distribution.
479
480    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
481    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
482    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
483    PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS
484    BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
485    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
486    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
487    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
488    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
489    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
490    ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
491
492    Visit the ACME Labs Java page for up-to-date versions of this and other
493    fine Java utilities: http://www.acme.com/java/
Note: See TracBrowser for help on using the repository browser.