com.tplan.robot.remoteclient.rfb
Interface RfbClient

All Superinterfaces:

BellTransferCapable, Capability, Configurable, DesktopUpdateCapable, KeyTransferCapable, Plugin, PointerTransferCapable, RemoteDesktopClient, RfbConstants

All Known Implementing Classes:

RfbClientImpl

public interface RfbClient
extends RfbConstants, Configurable, RemoteDesktopClient, BellTransferCapable, PointerTransferCapable, KeyTransferCapable, DesktopUpdateCapable

This interface defines methods of an RFB client.

RFB communication is described by the RFB protocol. See e.g. The RFB Protocol v. 3.8 at the RealVNC site. A typical session starts with a few initial handshaking messages which negotiate protocol version, authentication, connection parameters, format of the image data and the initial remote desktop image. After the communication is successfully started, the client keeps sending the mouse, keyboard and clipboard events to the server and the server sends back updated parts of the remote desktop image and server clipboard and bell events.

The client interface defines four types of methods:

• Get- and set-methods of the client parameters like server host name and port, password, protocol version used for the communication with the server, remote desktop name, geometry (size) and image.
• Status methods showing whether the client is connecting (i.e. an initial handshake is in progress) or connected to an RFB server.
• Methods implementing the mouse, keyboard and clipboard client to server messages.
• RFB listener methods which allow registered objects to receive server messages.

The client is not expected to expose methods of the initial handshaking messages. These should be implemented internally in the connect() method. The client should be typically used as follows:

• Set the host name, port and password (if required).
• Invoke the connect() method. If the connection fails, the method throws an exception.
• If the connection succeeds, the application uses the exposed client methods to send mouse, keyboard and clipboard events to the server. The RFB listener interface allows to implement custom actions reacting on the updates of the remote desktop, clipboard changes and bell events.

T-Plan Robot Enterprise, (C) 2009-2012 T-Plan Limited. All rights reserved.

Field Summary

static String

LOGIN_PARAM_SHARED_DESKTOP

Fields inherited from interface com.tplan.robot.remoteclient.rfb.RfbConstants

BYTEMASK, CINIT_EXCLUSIVE_DESKTOP, CINIT_SHARE_DESKTOP, ENCODING_COMPRESSION_LEVEL_PSEUDO, ENCODING_COPY_RECT, ENCODING_CORRE, ENCODING_CURSOR_PSEUDO, ENCODING_DESKTOP_SIZE, ENCODING_GII_PSEUDO, ENCODING_HEXTILE, ENCODING_HEXTILE_ANY_SUBRECTS, ENCODING_HEXTILE_BG_SPECIFIED, ENCODING_HEXTILE_FG_SPECIFIED, ENCODING_HEXTILE_RAW, ENCODING_HEXTILE_SUBRECTS_COLORED, ENCODING_JPEG_FINE_GRAINED_PSEUDO, ENCODING_JPEG_SUBSAMPLING_PSEUDO, ENCODING_JPEGQLVL, ENCODING_LASTRECT_PSEUDO, ENCODING_POINTER_POSITION, ENCODING_RAW, ENCODING_RRE, ENCODING_TIGHT, ENCODING_X_CURSOR_PSEUDO, ENCODING_ZLIB, ENCODING_ZLIBHEX, MSG_C2S_CLIENT_CUT_TEXT, MSG_C2S_FIX_COLOR_MAP_ENTRIES, MSG_C2S_FRAMEBUFFER_UPDATE_REQUEST, MSG_C2S_KEY_EVENT, MSG_C2S_POINTER_EVENT, MSG_C2S_SET_ENCODINGS, MSG_C2S_SET_PIXEL_FORMAT, MSG_S2C_BELL, MSG_S2C_COMMUNICATION_ERROR, MSG_S2C_CONNECTED, MSG_S2C_CONNECTING, MSG_S2C_DISCONNECTED, MSG_S2C_DISCONNECTING, MSG_S2C_FRAMEBUFFER_UPDATE, MSG_S2C_SERVER_CUT_TEXT, MSG_S2C_SERVER_INIT, MSG_S2C_SET_COLOR_MAP_ENTRIES, PROTOCOL_VERSION_3_3, PROTOCOL_VERSION_3_7, PROTOCOL_VERSION_3_8, RFB_LISTEN_PORT_OFFSET, RFB_PORT_OFFSET, SECURITY_CDEAN, SECURITY_INVALID, SECURITY_MD5, SECURITY_NONE, SECURITY_RA2, SECURITY_RA2NE, SECURITY_RESPONSE_FAILED, SECURITY_RESPONSE_OK, SECURITY_RESPONSE_TOO_MANY_ATTEMPTS, SECURITY_SASL, SECURITY_TIGHT, SECURITY_TLS, SECURITY_TYPE_NAMES, SECURITY_TYPES, SECURITY_ULTRA, SECURITY_VENCRYPT, SECURITY_VNC_AUTH, SPECIAL_KEY_CODES, VAR_LISTEN, VK_CONTEXT_MENU, VK_WINDOWS

Fields inherited from interface com.tplan.robot.remoteclient.RemoteDesktopClient

LOGIN_PARAM_PASSWORD, LOGIN_PARAM_URI, LOGIN_PARAM_USER

Method Summary

int[]	getEncodings() Get the array of preferred encoding codes.
Map<Integer,Encoding>	getSupportedEncodingMap() Get a map of encodings supported by the client where key is their numeric code as is stated in the SetEncodings message of the RFB protocol and value is an encoding handler (Encoding instance).
boolean	isPseudoCursorEnabled() Find out whether the pseudo cursor is enabled or not.
boolean	isSharedMode() Find out whether the client is set to connect in the shared mode or not.
void	resetModifiersIfNeeded() Reset all modifiers (Shift, Ctrl, Alt, Meta) which has been previously pressed but haven't been released yet.
void	sendFramebufferUpdateRequest(Rectangle rect, boolean incremental) Implementation of the FramebufferUpdateRequest client-to-server RFB v3.3 message.
void	setEncodings(int[] encodings) Implementation of the SetEncodings client-to-server RFB v3.3 message.
void	setPixelFormat(byte bitsPerPixel, byte colorDepth, boolean bigEndian, boolean trueColor, int redMax, int greenMax, int blueMax, byte redShift, byte greenShift, byte blueShift) Set the pixel format used by this client.
void	setPseudoCursorEnabled(boolean enable) Convenience method allowing to set on/off the cursor pseudo encoding.
void	setSharedMode(boolean sharedMode) Set whether to connect in a shared or exclusive mode.

Methods inherited from interface com.tplan.robot.preferences.Configurable

getPreferences, setConfiguration

Methods inherited from interface com.tplan.robot.remoteclient.RemoteDesktopClient

addClientListener, addServerListener, close, connect, destroy, getConnectString, getDefaultPort, getDesktopHeight, getDesktopName, getDesktopWidth, getHost, getImage, getLastMouseEvent, getLoginParamsSpecification, getPassword, getPort, getProtocol, getUser, hasSufficientConnectInfo, isConnected, isConnectedTo, isConnecting, isConsoleMode, isLocalDisplay, removeClientListener, removeServerListener, sendClientCutText, setConsoleMode, setLoginParams

Methods inherited from interface com.tplan.robot.plugin.Plugin

checkDependencies, getCode, getDate, getDescription, getDisplayName, getImplementedInterface, getLowestSupportedVersion, getMessageAfterInstall, getMessageBeforeInstall, getSupportContact, getUniqueId, getVendorHomePage, getVendorName, getVersion, requiresRestart

Methods inherited from interface com.tplan.robot.remoteclient.capabilities.BellTransferCapable

isBellTransferSupported, receiveBell

Methods inherited from interface com.tplan.robot.remoteclient.capabilities.PointerTransferCapable

isPointerTransferSupported, sendPointerEvent

Methods inherited from interface com.tplan.robot.remoteclient.capabilities.KeyTransferCapable

isKeyTransferSupported, sendKeyEvent

Methods inherited from interface com.tplan.robot.remoteclient.capabilities.DesktopUpdateCapable

isKeyTransferSupported

Field Detail

LOGIN_PARAM_SHARED_DESKTOP

static final String LOGIN_PARAM_SHARED_DESKTOP

See Also:

Constant Field Values

Method Detail

getSupportedEncodingMap

Map<Integer,Encoding> getSupportedEncodingMap()

Get a map of encodings supported by the client where key is their numeric code as is stated in the SetEncodings message of the RFB protocol and value is an encoding handler (Encoding instance).

Returns:

Integer array with numeric codes of image encodings supported by the client.

setEncodings

void setEncodings(int[] encodings)
                  throws IOException

Implementation of the SetEncodings client-to-server RFB v3.3 message. The method is supposed to send the encodings specfied by the array of integer numbers where the array members are encoding type numbers defined by the RFB protocol, such as 0 (Raw encoding), 1 (CopyRect) etc.

Parameters:

encodings - array of encodings supported by this server in the order of preference.

Throws:

IOException - if an I/O error is received when the new list of encodings is sent to the client.

getEncodings

int[] getEncodings()

Get the array of preferred encoding codes. See the setEncodings(int[]) method for details.

Returns:

array of preferred encoding codes.

isSharedMode

boolean isSharedMode()

Find out whether the client is set to connect in the shared mode or not. Be aware that the method returns value of a member variable flag and it doesn't have to reflect status of the current connection. If you have connected to a desktop and then changed the flag through setSharedMode(boolean), the method will return the flag value rather than the connection property.

Returns:

true if the client is configured to connect in shared mode, false otherwise.

setSharedMode

void setSharedMode(boolean sharedMode)

Set whether to connect in a shared or exclusive mode. As this flag applies only in the connection init phase, any change requires to reconnect an eventual existing connection.

Parameters:

sharedMode - true will set the shared mode, false sets the exclusive one.

setPixelFormat

void setPixelFormat(byte bitsPerPixel,
                    byte colorDepth,
                    boolean bigEndian,
                    boolean trueColor,
                    int redMax,
                    int greenMax,
                    int blueMax,
                    byte redShift,
                    byte greenShift,
                    byte blueShift)

Set the pixel format used by this client.

Parameters:

bitsPerPixel - number of bits per pixel. See the RFB 3.3 SetPixelFormat specification for details.

colorDepth - color depth in bits. See the RFB 3.3 SetPixelFormat specification for details.

bigEndian - true sets the big endian order, false the little endian one. See the RFB 3.3 SetPixelFormat specification for details.

trueColor - true means that pixels contain real RGB values while false indicates that the pixel values are pointers to a color map. See the RFB 3.3 SetPixelFormat specification for details.

redMax - maximum value of the red color. See the RFB 3.3 SetPixelFormat specification for details.

greenMax - maximum value of the green color. See the RFB 3.3 SetPixelFormat specification for details.

blueMax - maximum value of the blue color. See the RFB 3.3 SetPixelFormat specification for details.

redShift - the position (bit) where the red color starts in the pixel data. See the RFB 3.3 SetPixelFormat specification for details.

greenShift - the position (bit) where the green color starts in the pixel data. See the RFB 3.3 SetPixelFormat specification for details.

blueShift - the position (bit) where the blue color starts in the pixel data. See the RFB 3.3 SetPixelFormat specification for details.

sendFramebufferUpdateRequest

void sendFramebufferUpdateRequest(Rectangle rect,
                                  boolean incremental)
                                  throws IOException

Implementation of the FramebufferUpdateRequest client-to-server RFB v3.3 message. The method is supposed to send a request for the update of the remote desktop image (or it's part).

Parameters:

rect - rectangle of the remote desktop image the client is interested in. This argument should never be null - use the full remote desktop rectangle if you are requesting full image.

incremental - this flag is defined by the RFB protocol and enables/disables incremental sending of the updated image.

Throws:

IOException - if an I/O error is received when the message is sent to the client.

setPseudoCursorEnabled

void setPseudoCursorEnabled(boolean enable)
                            throws IOException,
                                   IllegalStateException

Convenience method allowing to set on/off the cursor pseudo encoding. This functionality is supported from the Enterprise version 2.3 and it is only applicable when the Pseudo Cursor Plugin is available. When the encoding is on, the mouse pointer is not part of the desktop image and it is rendered locally by the client. This makes image comparison more reliable because there are no image differences caused by conflicting mouse pointer.

When the encoding is off and it is being switched on, the method adds the cursor pseudo encoding code (-239) to the list of supported encodings, calls the setEncodings(int[]) method to notify the server of the change and also calls sendFramebufferUpdateRequest(java.awt.Rectangle, boolean) to get a new copy of the screen image without the cursor. When the encoding is being switched off, the steps are the same but the encoding code is removed from the list.

Unless this method is called, the client follows the list of encodings which is stored in the local configuration. As the client listens to configuration changes, any change to the list is picked up immediately and applied to the existing VNC connection. A call of this method makes the client switch to a "manual encoding mode" which breaks these rules and makes it bypass the configuration. The impact is that any outside change of the configuration file will not be picked up by this client until this method gets called again.

Parameters:

enable - true enables cursor pseudo encoding, false disables.

Throws:

IOException - the method throws any exceptions produced by the the client-server method calls (setEncodings(), sendFramebufferUpdateRequest()).

IllegalStateException - when the required cursor pseudo encoding plugin is not available.

isPseudoCursorEnabled

boolean isPseudoCursorEnabled()

Find out whether the pseudo cursor is enabled or not.

Returns:

true if the pseudo cursor support is on, false otherwise.

resetModifiersIfNeeded

void resetModifiersIfNeeded()

Reset all modifiers (Shift, Ctrl, Alt, Meta) which has been previously pressed but haven't been released yet.