Code Documentation

api Module

Helpers to allow vncdotool to be intergrated into other applications.

Warning

EXPERIMENTAL. This feature is under development, your help testing and debugging is appreciated.

vncdotool.api.connect(server: str) → ThreadedVNCClientProxy

vncdotool.api.connect(server: str, password: str | None) → ThreadedVNCClientProxy

vncdotool.api.connect(server: str, password: str | None, factory_class: type[VNCDoToolFactory]) → ThreadedVNCClientProxy

vncdotool.api.connect(server: str, password: str | None, factory_class: type[VNCDoToolFactory], proxy: type[TProxy]) → TProxy

vncdotool.api.connect(server: str, password: str | None, factory_class: type[VNCDoToolFactory], proxy: type[TProxy], timeout: float | None) → TProxy

vncdotool.api.connect(server: str, password: str | None, factory_class: type[VNCDoToolFactory], proxy: type[TProxy], timeout: float | None, username: str | None) → TProxy

Connect to a VNCServer and return a Client instance that is usable in the main thread of non-Twisted Python Applications,

>>> from vncdotool import api
>>> with api.connect('host') as client
>>>     client.keyPress('c')

You may then call any regular VNCDoToolClient method on client from your application code.

If you are using a GUI toolkit or other major async library please read Choosing a Reactor and GUI Toolkit Integration for a better method of intergrating vncdotool.

vncdotool.api.shutdown() → None

Shutdown background thread running Twisted reactor.

client Module

Twisted based VNC client protocol and factory.

exception vncdotool.client.AuthenticationError

Bases: VNCDoException

VNC Server requires Authentication

exception vncdotool.client.ProtocolError

Bases: VNCDoException

VNC Server sent something we cannot handle

class vncdotool.client.VMWareClient

Bases: VNCDoToolClient

SINGLE_PIXLE_UPDATE = b'\x00\x00\x00\x01\x00\x00\x00\x00\x00\x01\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00'

dataReceived(data: bytes) → None

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

@param data: a string of indeterminate length. Please keep in mind

that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.

class vncdotool.client.VMWareFactory

Bases: VNCDoToolFactory

protocol

alias of VMWareClient

exception vncdotool.client.VNCDoException

Bases: Exception

class vncdotool.client.VNCDoToolClient

Bases: RFBClient

MAX_DESKTOP_SIZE = 65536

SPECIAL_KEYS_US = '~!@#$%^&*()_+{}|:"<>?'

bell()

buttons = 0

captureRegion(fp: str | Path | IO[bytes], x: int, y: int, w: int, h: int, incremental: bool = False) → Deferred

Save a region of the current display to filename

captureScreen(fp: str | Path | IO[bytes], incremental: bool = False, format: str | None = None) → Deferred

Capture and save the current VNC screen display to a file.

Parameters:

fp (TFile): The destination where the screenshot will be saved.

It can be a string path, a pathlib.Path object, or a file-like object opened in binary mode.

incremental (bool, optional):

• False (default): Captures the entire screen.

• True: Captures only the regions of the screen that have changed since the last capture.

format (str | None, optional):

• See Pillow’s list of image formats: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html

• If set to None, Pillow will determine the format based on the provided file name.

cmask: Image | None = None

commitUpdate(rectangles: list[Tuple[int, int, int, int]] | None = None) → None

called after a series of updateRectangle(), copyRectangle() or fillRectangle() are finished.

Typicaly, here is the place to request the next screen update with framebufferUpdateRequest() with incremental=True.

Parameters:

rectangles – a list of tuples (x,y,w,h) with the updated rectangles.

connectionLost(reason: Failure) → None

Called when the connection is shut down.

Clear any circular references here, and any external references to this Protocol. The connection has been closed.

@type reason: L{twisted.python.failure.Failure}

connectionMade() → None

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

copy_text(text: str) → None

The server has new ISO 8859-1 (Latin-1) text in its cut buffer. (aka clipboard)

cursor: Image | None = None

deferred: Deferred | None = None

drawCursor() → None

encoding = 0

expectRegion(filename: str, x: int, y: int, maxrms: float = 0) → Deferred

Wait until a portion of the screen matches the target image

The region compared is defined by the box (x, y), (x + image.width, y + image.height)

expectScreen(filename: str, maxrms: float = 0) → Deferred

Wait until the display matches a target image

Parameters:

• filename – an image file to read and compare against.

• maxrms – the maximum root mean square between histograms of the screen and target image.

property image_mode: str

keyDown(key: str) → TClient

keyPress(key: str) → TClient

Send a key press to the server

Parameters:

key – either [a-z] or a from KEYMAP.

keyUp(key: str) → TClient

mouseDown(button: int) → TClient

Send a mouse button down at the last set position

Parameters:

button – [1-n]

mouseDrag(x: int, y: int, step: int = 1) → Iterator[Deferred]

Move the mouse point to position (x, y) in increments of step

mouseMove(x: int, y: int) → TClient

Move the mouse pointer to position (x, y)

mousePress(button: int) → TClient

Send a mouse click at the last set position

Parameters:

button – [1-n]

mouseUp(button: int) → TClient

Send mouse button released at the last set position

Parameters:

button – [1-n]

paste(message: str) → TClient

pause(duration: float) → Deferred

refreshScreen(incremental: bool = False) → Deferred

screen: Image | None = None

setImageMode() → None

Check support for PixelFormats announced by server or select client supported alternative.

updateCursor(x: int, y: int, width: int, height: int, image: bytes, mask: bytes) → None

New cursor, focuses at (x, y)

updateDesktopSize(width: int, height: int) → None

New desktop size of width*height.

updateRectangle(x: int, y: int, width: int, height: int, data: bytes) → None

new bitmap data.

Parameters:

data – bytes in the pixel format set up earlier.

vncAuthFailed(reason: bytes | str) → None

called when the authentication failed. the connection is closed.

vncConnectionMade() → None

connection is initialized and ready. typicaly, the pixel format is set here.

vncProtocolError(reason: str) → None

called when the server sends something we cannot handle. the connection is closed.

vncRequestPassword() → None

a password is needed to log on, use sendPassword() to send one.

x = 0

y = 0

class vncdotool.client.VNCDoToolFactory

Bases: RFBFactory

clientConnectionFailed(connector: <InterfaceClass twisted.internet.interfaces.IConnector>, reason: Failure) → None

Called when a connection has failed to connect.

It may be useful to call connector.connect() - this will reconnect.

clientConnectionLost(connector: <InterfaceClass twisted.internet.interfaces.IConnector>, reason: Failure) → None

Called when an established connection is lost.

It may be useful to call connector.connect() - this will reconnect.

clientConnectionMade(protocol: VNCDoToolClient) → None

force_caps = False

last_rect = True

nocursor = False

password: str | None = None

protocol

alias of VNCDoToolClient

pseudocursor = False

pseudodesktop = True

qemu_extended_key = True

shared = True

username: str | None = None

vncdotool.client.factory_connect(factory: VNCDoToolFactory, host: str, port: int, family: AddressFamily) → None

rfb Module

RFB protocol implementattion, client side.

Override RFBClient and RFBFactory in your application. See vncviewer.py for an example.

Reference: https://www.rfc-editor.org/rfc/rfc6143 https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst

class vncdotool.rfb.PixelFormat(bpp: int = 32, depth: int = 24, bigendian: bool = False, truecolor: bool = True, redmax: int = 255, greenmax: int = 255, bluemax: int = 255, redshift: int = 0, greenshift: int = 8, blueshift: int = 16)

Bases: object

RFC 6143 §7.4. Pixel Format Data Structure.

STRUCT: ClassVar = <_struct.Struct object>

VALIDATE: ClassVar = False

bigendian: bool = False

bluemax: int = 255

blueshift: int = 16

bpp: int = 32

property bypp: int

depth: int = 24

classmethod from_bytes(block: bytes) → PixelFormat

greenmax: int = 255

greenshift: int = 8

redmax: int = 255

redshift: int = 0

to_bytes() → bytes

truecolor: bool = True

class vncdotool.rfb.RFBClient

Bases: Protocol

MAX_CLIENT_VERSION = (3, 8)

SUPPORTED_AUTHS = {AuthTypes.NONE, AuthTypes.VNC_AUTHENTICATION, AuthTypes.DIFFIE_HELLMAN}

SUPPORTED_ENCODINGS = {Encoding.PSEUDO_QEMU_EXTENDED_KEY_EVENT, Encoding.PSEUDO_CURSOR, Encoding.PSEUDO_LAST_RECT, Encoding.PSEUDO_DESKTOP_SIZE, Encoding.RAW, Encoding.COPY_RECTANGLE, Encoding.RRE, Encoding.CORRE, Encoding.HEXTILE, Encoding.ZRLE}

SUPPORTED_SERVER_VERSIONS = {(3, 3), (3, 7), (3, 8), (3, 889), (4, 0), (4, 1), (5, 0)}

ardRequestCredentials() → None

beginUpdate() → None

called before a series of updateRectangle(), copyRectangle() or fillRectangle().

bell()

property bypp: int

clientCutText(message: str) → None

The client has new ISO 8859-1 (Latin-1) text in its cut buffer. (aka clipboard)

commitUpdate(rectangles: list[Tuple[int, int, int, int]] | None = None) → None

called after a series of updateRectangle(), copyRectangle() or fillRectangle() are finished.

Typicaly, here is the place to request the next screen update with framebufferUpdateRequest() with incremental=True.

Parameters:

rectangles – a list of tuples (x,y,w,h) with the updated rectangles.

copyRectangle(srcx: int, srcy: int, x: int, y: int, width: int, height: int) → None

used for copyrect encoding. copy the given rectangle (src, srxy, width, height) to the target coords (x,y)

copy_text(text: str) → None

The server has new ISO 8859-1 (Latin-1) text in its cut buffer. (aka clipboard)

dataReceived(data: bytes) → None

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

@param data: a string of indeterminate length. Please keep in mind

that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.

expect(handler: Callable[[...], None], size: int, *args: Any, **kwargs: Any) → None

fillRectangle(x: int, y: int, width: int, height: int, color: bytes) → None

fill the area with the color.

Parameters:

color – bytes in the pixel format set up earlier.

framebufferUpdateRequest(x: int = 0, y: int = 0, width: int | None = None, height: int | None = None, incremental: bool = False) → None

keyEvent(key: Key | int, down: bool = True) → None

For most ordinary keys, the “keysym” is the same as the corresponding ASCII value. Other common keys are shown in the Key constants.

pointerEvent(x: int, y: int, buttonmask: int = 0) → None

Indicates either pointer movement or a pointer button press or release. The pointer is now at (x-position, y-position), and the current state of buttons 1 to 8 are represented by bits 0 to 7 of button-mask respectively, 0 meaning up, 1 meaning down (pressed).

sendPassword(password: str) → None

send password

setEncodings(list_of_encodings: Collection[Encoding]) → None

setPixelFormat(pixel_format: PixelFormat) → None

set_color_map(first: int, colors: list[tuple[int, int, int]]) → None

The server is using a new color map.

updateCursor(x: int, y: int, width: int, height: int, image: bytes, mask: bytes) → None

New cursor, focuses at (x, y)

updateDesktopSize(width: int, height: int) → None

New desktop size of width*height.

updateRectangle(x: int, y: int, width: int, height: int, data: bytes) → None

new bitmap data.

Parameters:

data – bytes in the pixel format set up earlier.

vncAuthFailed(reason: Failure) → None

called when the authentication failed. the connection is closed.

vncConnectionMade() → None

connection is initialized and ready. typicaly, the pixel format is set here.

vncProtocolError(reason: str) → None

called when the server sends something we cannot handle. the connection is closed.

vncRequestPassword() → None

a password is needed to log on, use sendPassword() to send one.

class vncdotool.rfb.RFBFactory(password: str | None = None, shared: bool = False)

Bases: ClientFactory

A factory for remote frame buffer connections.

protocol

alias of RFBClient

vncdotool.rfb.des_encrypt(key: bytes, data: bytes) → bytes

Encrypt with single DES, as the VNC family’s password handling uses.

Single DES in ECB is weak, and is what RFB specifies: both the authentication challenge response (RFC 6143 section 7.2.2) and the password file format are defined in terms of it, so a stronger algorithm here would simply fail to talk to any VNC server.

vncdotool.rfb.reverse_bits(data: bytes) → bytes

The bit-reversal the VNC family applies to a DES key before using it, both for the authentication challenge response here and for the password obfuscation in ~/.vnc/passwd files.

command Module

Command line interface to interact with a VNC Server.

exception vncdotool.command.CommandParseError

Bases: RuntimeError

class vncdotool.command.ExitStatus(value)

Bases: IntEnum

Exit codes returned by vncdo, grouped by cause.

AUTHENTICATION_FAILED = 3

COMMAND_FAILED = 30

CONNECTION_FAILED = 10

CONNECTION_LOST = 11

ERROR = 1

PROTOCOL_ERROR = 20

SUCCESS = 0

TIMEOUT = 40

USAGE = 2

class vncdotool.command.ExitingProcess

Bases: ProcessProtocol

errReceived(data: bytes) → None

Some data was received from stderr.

processExited(reason: Failure) → None

This will be called when the subprocess exits.

@type reason: L{twisted.python.failure.Failure}

exception vncdotool.command.TimeoutError

Bases: RuntimeError

class vncdotool.command.VNCDoCLIClient

Bases: VNCDoToolClient

vncRequestPassword() → None

a password is needed to log on, use sendPassword() to send one.

class vncdotool.command.VNCDoCLIFactory

Bases: VNCDoToolFactory

clientConnectionFailed(connector: <InterfaceClass twisted.internet.interfaces.IConnector>, reason: Failure) → None

Called when a connection has failed to connect.

It may be useful to call connector.connect() - this will reconnect.

clientConnectionLost(connector: <InterfaceClass twisted.internet.interfaces.IConnector>, reason: Failure) → None

Called when an established connection is lost.

It may be useful to call connector.connect() - this will reconnect.

done(exit_code: ExitStatus) → None

error(reason: Failure, default: ExitStatus = ExitStatus.COMMAND_FAILED) → None

protocol

alias of VNCDoCLIClient

static status_for(reason: Failure, default: ExitStatus) → ExitStatus

class vncdotool.command.VNCDoToolOptionParser(usage=None, option_list=None, option_class=<class 'optparse.Option'>, version=None, conflict_handler='error', description=None, formatter=None, add_help_option=True, prog=None, epilog=None)

Bases: OptionParser

format_help(formatter: HelpFormatter | None = None) → str

vncdotool.command.add_standard_options(parser: OptionParser) → OptionParser

vncdotool.command.build_command_list(factory: VNCDoCLIFactory, args: list[str], delay: float | None = None, warp: float = 1.0, incremental_refreshes: bool = False) → None

vncdotool.command.build_proxy(options: Values) → VNCLoggingServerFactory

vncdotool.command.build_tool(options: Values, args: list[str]) → VNCDoCLIFactory

vncdotool.command.log_connected(pcol: TClient) → TClient

vncdotool.command.log_exceptions(type_: type[BaseException], value: BaseException, tb: TracebackType | None) → None

vncdotool.command.parse_server(server: str) → tuple[AddressFamily, str, int]

vncdotool.command.setup_logging(options: Values) → None

vncdotool.command.vncdo(argv: list[str] | None = None) → None

vncdotool.command.vncdo_replay() → None

Replay a vnclog –capture-raw archive: serve it, or drive it.

Two processes: –server serves the recorded bytes, and any client (this command without –server, a GUI viewer, or a hand-written vncdo line) can drive the session against it. See docs/capture.rst.

vncdotool.command.vnclog() → None

loggingproxy Module

class vncdotool.loggingproxy.NullTransport

Bases: object

addressFamily = 0

loseConnection() → None

setTcpNoDelay(enabled: bool) → None

write(data: bytes) → None

writeSequence(data: bytes) → None

exception vncdotool.loggingproxy.ProtocolError

Bases: Exception

VNC Protocol error

class vncdotool.loggingproxy.RFBServer

Bases: Protocol

connectionMade() → None

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

dataReceived(data: bytes) → None

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

@param data: a string of indeterminate length. Please keep in mind

that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.

handle_clientCutText(block: bytes) → None

handle_framebufferUpdate(x: int, y: int, w: int, h: int, incremental: bool) → None

handle_keyEvent(key: int, down: bool) → None

handle_keyEventExtended(keysym: int, down: bool, keycode: int) → None

handle_pointerEvent(x: int, y: int, buttonmask: int) → None

handle_setEncodings(encodings: Sequence[int]) → None

handle_setPixelFormat(pixel_format: PixelFormat) → None

class vncdotool.loggingproxy.VNCLoggingClient

Bases: VNCDoToolClient

Specialization of a VNCDoToolClient that will save screen captures.

capture: CaptureWriter | None = None

capture_file: str | None = None

commitUpdate(rectangles: list[Tuple[int, int, int, int]] | None = None) → None

called after a series of updateRectangle(), copyRectangle() or fillRectangle() are finished.

Typicaly, here is the place to request the next screen update with framebufferUpdateRequest() with incremental=True.

Parameters:

rectangles – a list of tuples (x,y,w,h) with the updated rectangles.

class vncdotool.loggingproxy.VNCLoggingClientFactory

Bases: ProxyClientFactory

protocol

alias of VNCLoggingClientProxy

class vncdotool.loggingproxy.VNCLoggingClientProxy

Bases: ProxyClient

Accept data from a server and forward to logger and downstream client.

VNC server -> VNCLoggingClientProxy -> VNC client
                                    -> VNCLoggingClient

dataReceived(data: bytes) → None

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

@param data: a string of indeterminate length. Please keep in mind

that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.

ncaptures = 0

startLogging(peer: VNCLoggingServerProxy) → None

vnclog: VNCLoggingClient | None = None

class vncdotool.loggingproxy.VNCLoggingServerFactory(host: str, port: int)

Bases: ProxyFactory

capture_failed: bool = False

capture_path: str | None = None

capture_preserve_auth: bool = False

clientConnectionLost(client: VNCLoggingServerProxy) → None

clientConnectionMade(client: VNCLoggingServerProxy) → None

force_caps = False

getRecordedSession() → bytes

getRecorder() → Callable[[str], int]

last_rect = True

nocursor = False

one_shot: bool = False

output: IO[str] | str = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>

password: str | None = None

password_required = False

protocol

alias of VNCLoggingServerProxy

pseudocursor = False

pseudodesktop = True

qemu_extended_key = True

server_address: str = ''

sessionFinished() → None

End the process after a –one-shot session, once it has closed.

session_taken: bool = False

shared = True

class vncdotool.loggingproxy.VNCLoggingServerProxy

Bases: ProxyServer, RFBServer

Proxy in the middle, decodes and logs RFB messages before sending them upstream.

VNC client -> VNCLoggingServerProxy -> VNC server
                                    -> RFBServer

buttons = 0

capture: CaptureWriter | None = None

clientProtocolFactory

alias of VNCLoggingClientFactory

connectionLost(reason: Failure) → None

Called when the connection is shut down.

Clear any circular references here, and any external references to this Protocol. The connection has been closed.

@type reason: L{twisted.python.failure.Failure}

connectionMade() → None

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

dataReceived(data: bytes) → None

Called whenever data is received.

Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.

@param data: a string of indeterminate length. Please keep in mind

that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.

handle_keyEvent(key: int, down: bool) → None

handle_pointerEvent(x: int, y: int, buttonmask: int) → None

recorder: Callable[[str], int] | None = None

refused: bool = False

saw_bytes: bool = False

server: str | None = None

took_session: bool = False

property vnclog_client: VNCLoggingClient | None