package require tclRFB ?0.5?
rfb::CreateClientSocket host port optlist
rfb::SendFramebufferUpdateRequest sockN inc
rfb::SendKeyEvent sockN downflag keysym
rfb::SendPointerEvent sockN button pressed
rfb::SendClientCutText sockN cutbuffer
rfb::CreateServerSocket port optlist
rfb::SendBell sockN
rfb::SendServerCutText sockN text
rfb::SendFramebufferUpdate sockN encodeList
rfb::ConnectionShutdown sockN
rfb::EncryptPasswdToFile password filename
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.
TclRFB requires Tcl 8.4 or later to run. It does not rely on any given visualization library. Any visualization library 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
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 the server port number, and optlist is a list of option-value pairs. Note that TclRFB 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 primarily describe the client's pixel characteristics and the routines 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.
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 routines passed to rfb::CreateClientSocket in the option list. The client routines take the pixel data provided through the RFB encodings and uses the client visualization library to display the pixels.
The option list is a proper Tcl list containing TclRFB property option-value pairs as sublists. The following option/value pairs MUST be defined in the option list passed:
procname
The procedure has no input parameters.
procname sock
Where sock is the client's socket handle.
procname sock
Where sock is the client's socket handle.
procname text
Where text is the cut text sent from the server.
procname sock x y w h
Where sock is the client's socket handle, x and y are the horizontal and vertical coordinates of the upper-lefthand corner of the pixel region, and w and h are the width and height of the pixel region.
procname srcX srcY dstX dstY w h
Where srcX and srcY are the horizontal and vertical coordinates of the upper-lefthand corner of the source pixel region, dstX and dstY are the horizontal and vertical coordinates of the upper-lefthand corner of the destination pixel region, and w and h are the width and height of the pixel region.
procname pixel x y w h
Where pixel is the pixel value received from the server, x and y are the horizontal and vertical coordinates of the upper-lefthand corner of the pixel region, and w and h are the width and height of the pixel region.
procname
The procedure has no input parameters.
Application-specific array variables can be created via additional option-value pairs. The following option names are reserved for internal use by the client and should not be used:
buttonmask clientBytes clientPixel
bgPixel fgPixel serverBE
serverTC serverBPP serverDepth
serverBmax serverGmax serverRmax
serverBshift serverGshift serverRshift
serverBytes serverPixel state
serverVersionMajor serverVersionMinor
Several library produres provide client-to-server protocol messages:
rfb::CreateServerSocket port optlist
Where port the server port number and optlist is a list of option-value pairs. Note that TclRFB can use any port including those traditionally used by VNC servers.
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.
Routines provided by TclRFB take the pixel data supplied by the server and converts 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.
The option list is a proper Tcl list containg TclRFB property option-value pairs as sublists. The following option/value pairs MUST be defined in the option list passed:
procname sock inc x y w h
Where sock is the socket handle for the server connection instance, inc specifies whether the update should be an incremetal update (1) or a full (0) update, x and y are the horizontal and vertical coordinates of the upper-lefthand corner of the pixel region, and w and h are the width and height of the pixel region.
procname sock downflag keysym
Where sock is the socket handle for the server connection instance, downflag specifies whether a key press (1) or a key release (0) has occurred, and keysym specifies the keysym value sent.
procname sock buttonmask x y
Where sock is the socket handle for the server connection instance, buttonmask specifies the buttons (1-8) that are depressed (1) or released (0), and x and y are the coordinates of the mouse pointer.
procname sock text
Where sock is the socket handle for the server connection instance, and text specifies the text sent from the client cutbuffer to the RFB server.
Application-specific array variables can be created via additional option-value pairs. The following option names are reserved for internal use by the server and should not be used:
clientBE clientTC clientBPP
clientBytes clientPixel clientDepth
clientBmax clientGmax clientRmax
clientBshift clientGshift clientRshift
clientShared serverBytes serverPixel
clientVersionMajor clientVersionMinor
port state
Several library produres provide server-to-client protocol messages:
{rectangle1 rectangle2 ... rectangleN}
where each rectangle is a list in the form
{type x y w h data1 data2}
where type is the number of the RFB encoding type, x and y are the horizontal and vertical coordinates of the upper-lefthand corner of the rectangle, w and h are the width and height of the rectangle, and data1 and data2 are data elements specific to the RFB encoding type.
The specific formats for the different RFB encodings are as follows
Raw encoding (type 0)
{0 x y w h datastring {}}
where datastring is a binary string of pixels, w times h times pixel bytes in length, formated to the client color format. The pixel ordering is left-to-right, top-to-bottom like scanlines.
CopyRect encoding (type 1)
{1 x y w h srcX srcY}
where srcX and srcY are the coordinates of the upper-lefthand corner of the source rectangle.
RRE encoding (type 2)
{2 x y w h bgPixel rectList}
where bgPixel is the background pixel color formated to the client color format and rectList is a proper Tcl list of subrectangles
{subrectangle1 subrectangle2 ... subrectangleN}
where each subrectangle is a proper Tcl list
{xs ys ws hs fgPixel}
where xs and ys are the horizontal and vertical coordinates of the upper-lefthand corner of the subrectangle with respect to the RRE rectangle's coordinates, ws and hs are the width and height of the subrectangle, and fgPixel is the foreground pixel color formated to the client color format.
CoRRE encoding (type 4)
{2 x y w h bgPixel rectList}
where bgPixel is the background pixel color formated to the client color format and rectList is a proper Tcl list of subrectangles
{subrectangle1 subrectangle2 ... subrectangleN}
where each subrectangle is a proper Tcl list
{xs ys ws hs fgPixel}
where xs and ys are the horizontal and vertical coordinates of the upper-lefthand corner of the subrectangle with respect to the RRE rectangle's coordinates, ws and hs are the width and height of the subrectangle, and fgPixel is the foreground pixel color formated to the client color format. Note that ws and hs can be no larger than 255.
Hextile encoding (type 5)
{hextile1 hextile2 ... hextile256}
where each hextile is a proper Tcl list consisting of an eight-bit binary mask value and additional data depending upon the binary mask value.
Hextile of a solid rectangle of last background color
{0}
Hextile of raw pixels
{1 datastring}
where datastring is a binary string of pixels, formated to the client color format. The pixel ordering is left-to-right, top-to-bottom like scanlines.
Set a new background color for subsequent hextiles
{2 bgPixel}
where bgPixel is the new background color specified in the client color format.
Set a new foreground color for subsequent hextiles
{4 fgPixel}
where fgPixel is the new foreground color specified in the client color format.
Hextile of solid rectangle of new background color and a new foreground color is set
{6 bgPixel fgPixel}
where bgPixel is the new background color specified in the client color format and fgPixel is the new foreground color specified in the client color format.
Hextile of solid rectangle of last background color and subrectangles of last foreground color
{8 srects subrectangle1 subrectangle2 ... subrectangleN}
where srects is the number of subrectangles. Following are "N" Tcl lists that represent the number of subrectangles specified by srects. The format of each subrectangle is
{xs ys ws hs}
where xs and ys are the horizontal and vertical coordinates of the upper-lefthand corner of the subrectangle with respect to the particular hextile, and ws and hs are the width and height of the subrectangle, which cannot be greater than 16 pixels. The color of each subrectangle is that of the foreground color in the last hextile.
Hextile of a solid rectangle of new background color and subrectangles of last foreground color
{10 bgPixel srects subrectangle1 subrectangle2 ... subrectangleN}
where bgPixel is the new background color formated to the client color format, srects is the number of subrectangles, and "N" Tcl lists as specified above for hextile mask 8.
Hextile of a solid rectangle of last background color and subrectangles of new foreground color
{12 fgPixel srects subrectangle1 subrectangle2 ... subrectangleN}
where fgPixel is the new foreground color formated to the client color format, srects is the number of subrectangles, and "N" Tcl lists as specified above for hextile mask 8.
Hextile of a solid rectangle of new background color and subrectangles of new foreground color
{14 bgPixel fgPixel srects subrectangle1 subrectangle2 ... subrectangleN}
where bgPixel is the new background color formated to the client color format, fgPixel is the new foreground color specified in the client color format, srects is the number of subrectangles, and "N" Tcl lists as specified above for hextile mask 8.
Hextile of a solid rectangle of last background color and subrectangles with individual foreground colors
{24 srects subrectangle1 subrectangle2 ... subrectangleN}
where srects is the number of subrectangles. Following are "N" Tcl lists that represent the number of subrectangles specified by srects. The format of each subrectangle is
{xs ys ws hs fgPixel}
where xs and ys are the horizontal and vertical coordinates of the upper-lefthand corner of the subrectangle with respect to the particular hextile, ws and hs are the width and height of the subrectangle, which cannot be greater than 16 pixels, and fpPixel is the foreground color of the subrectangle specified in the client color format.
Hextile of solid rectangle of new background color and subrectangles with individual foreground colors
{26 bgPixel srects subrectangle1 subrectangle2 ... subrectangleN}
where bgPixel is the new background color specified in the client color format, srects is the number of subrectangles, and "N" Tcl lists as specified above for hextile mask 24.
Several library produres provide for general support: