TclRFB is a pure-Tcl implementation of the Remote Framebuffer (RFB) protocol that is used in the Virtual Network Computing (VNC) remote desktop application. Currently, TclRFB supports version 3.3 of the RFB protocol. Both client and server functions are supported. Multiple client and/or server instances can exist within the same interpreter. Currently supported RFB encodings are Raw, CopyRect, RRE, CoRRE, and Hextile.
TclRFB requires Tcl 8.4 or later to run. It does not rely on any given widget library. Any widget library with bindings to Tcl can be used (e.g. Tk, gnocl (gTk), or the Tcl bindings to FLTK) or none at all. The authentication component of the protocol is fully supported when either the TclDES (Data Encryption Standard and Triple-DES) or TclDESjr (Data Encryption Standard only) extension is used with TclRFB. The TclDES and TclDESjr extensions can be obtained at http://tcldes.sourceforge.net.
The TclRFB extension is implemented as the rfb namespace. Within this namespace, procedures and variables that support the protocol are isolated from the global namespace. Additional details of the RFB protocol can be found in "The RFB Protocol" by Richardson and Wood at http://www.realvnc.com/docs/rfbproto.pdf
The intent of TclRFB is to enable the creation of light-weight, scripted remote interfaces, much like Proxy Tk, used in TeamWave (for information, see http://www.usenix.org/events/tcl2k/full_papers/roseman/roseman_html/). The user interface can then be displayed through a VNC viewer, using either the standalone version (Unix, Windows, Macintosh, Palm, and other platforms), the Java-based version running in a web browser, or one based on TclRFB.
To install the TclRFB library, simply copy the directory tclRFB0.5 and its contents to a directory whose path is listed in the Tcl auto_path variable. Alternately, the path to the TclRFB library can be added to the auto_path variable.
Once the installation is done, the TclRFB library can be loaded into a Tcl interpreter using the package command:
package require tclRFB
This will create the rfb namespace.
An RFB client is started by making a call to rfb::CreateClientSocket. This procedure is invoked as follows:
rfb::CreateClientSocket host port optlist
Where host is the hostname or IP address (dotted quad) of the computer running a server supporting the RFB protocol, port is the server port number, and optlist is a list of option-value pairs. Note that TclRFB clients can use any port including those traditionally used by VNC servers.
The list of option-value pairs describes the properties of the client. These properties are primarily the client's pixel characteristics and the procedures used to handle the RFB pixel encodings that support the client visualization. The client pixel characteristics are used to inform the server as to the pixel format best handled by the client. The server must transform its local pixel representation into that supported by the client. Additional details of the client options and procedures used to implement an RFB client are presented in the man page.
The call to rfb::CreateClientSocket creates an instance of an RFB client state machine. The state machine processes RFB protocol messages coming from the server. Pixel data received from the server is passed to the client visualization procedures whose names were passed in the option list to rfb::CreateClientSocket. The client procedures take the pixel data provided through the RFB encodings and uses the client visualization library to display the pixels.
An example RFB client, client.tcl, is provided to demonstrate how to use the TclRFB library's client procedures. It can be found in the examples subdirectory of the distribution. The client supports bgr233 truecolor pixel format and 24-bit truecolor (rgb888) pixel format. The user can select the hostname/IP and the port number or display number of the RFB server. The display number port assignment corresponds to that used with VNC, i.e. the port number is equal to the display number plus 5900. Sharing of the connection with other RFB clients can be enabled as well. A password or the path to a file containing an encrypted password can be specified. RFB pixel encoding preferences can also be selected.
The client has been tested against the Unix VNC server 3.3.3r2 and the TclRFB server, rfbcounter.tcl, mentioned below. Either TclDES or TclDESjr must be installed to support RFB authentication. The performance of the TclRFB client compares favorably to that of the Unix vncviewer. Noticeable rendering lags do occur when mouse cursor movements cause focus changes between windows and when large amounts of screen area are written. A screen shot of the client connected to a Unix vncserver is shown here. A screen shot of the client connected to the rfbcounter.tcl server is shown here.
rfb::CreateServerSocket port optlist
Where port is the server port number and optlist is a list of option-value pairs. Note that TclRFB servers can use any port including those traditionally used by VNC servers. The socket that is created then waits for connections from RFB clients.
When a client connects to the server, a server connection instance is created via a call to rfb::AcceptServerSocket. The parameters passed to rfb::CreateServerSocket are applied to the server socket instance. An RFB server state machine is created to process the RFB protocol messages that come from the client.
Procedures provided by TclRFB take the pixel data supplied by the server and convert it to RFB protocol messages. It is the responsibility of the server to make sure the pixel data is in the format appropriate for the client prior to submitting it for encoding. Additional details of the server options and procedures used to implement and RFB are presented in the man page.
An example RFB server, rfbcounter.tcl is provided to demonstrate how to use the TclRFB library's server procedues. This server is inspired by the rfbcounter described at http://www.uk.research.att.com/vnc/rfbcounter.html. It can be found in the examples subdirectory of the distribution. The server supports either a six-digit counter or a 24-hour clock (when the -clock option is specified), which displays in HH:MM:SS format. The foreground and background colors can be also be specified. The display number port assignment corresponds to that used with VNC, i.e. the port number is equal to the display number plus 5900.
The only pixel format supported by the server is bgr233. The only RFB encoding protocol supported is RRE. Therefore, any RFB client that intends to connect to the server must support these formats.
The server has been tested against the Unix VNC viewer 3.3.3r2 and the TclRFB client, client.tcl, mentioned above. It has also been tested with multiple clients connecting to it simultaneously. Either TclDES or TclDESjr must be installed to support RFB authentication. A screen shot of a Unix vncviewer connected to the rfbcounter.tcl server is shown here.
TclRFB 0.5 is available as either gzipped tar archive for
GNU/Linux (and other Un*xes) or pkzip archive for Microsoft Windows. Both can
be obtained at the
TclRFB
SourceForge Files page.
Earler versions of TclRFB can also be found at the
TclRFB SourceForge
Files page.
© 2003 Mac A. Cody
Last updated Friday, May 9, 2003
