vnc

package module
v0.0.0-...-b8b4570 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2018 License: MIT Imports: 13 Imported by: 1

README

VNC Library for Go

go-vnc is a VNC client library for Go.

This library implements RFC 6143 -- The Remote Framebuffer Protocol -- the protocol used by VNC.

  • Build Status: Build Status
  • Documentation: GoDoc

Setup

  1. Download software and supporting packages.

    $ go get github.com/donomii/go-vnc
$ go get golang.org/x/net

Usage

Sample code usage is available in the GoDoc.

The source code is laid out such that the files match the document sections:

  • [7.1] handshake.go
  • [7.2] security.go
  • [7.3] initialization.go
  • [7.4] pixel_format.go
  • [7.5] client.go
  • [7.6] server.go
  • [7.7] encodings.go

There are two additional files that provide everything else:

  • vncclient.go -- code for instantiating a VNC client
  • common.go -- common stuff not related to the RFB protocol

Documentation

Overview

Package vnc provides VNC client implementation.

This package implements The Remote Framebuffer Protocol as documented in [RFC 6143](http://tools.ietf.org/html/rfc6143).

A basic VNC client can be created like this: 

// Establish TCP connection to VNC server.
nc, err := net.Dial("tcp", "127.0.0.1:5900")
if err != nil {
  log.Fatalf("Error connecting to VNC host. %v", err)
}

// Negotiate connection with the server.
vcc := NewClientConfig("some_password")
vc, err := Connect(context.Background(), nc, vcc)
if err != nil {
  log.Fatalf("Error negotiating connection to VNC host. %v", err)
}

// Periodically request framebuffer updates.
go func(){
  w, h := vc.FramebufferWidth(), vc.FramebufferHeight()
  for {
    if err := v.conn.FramebufferUpdateRequest(vnc.RFBTrue, 0, 0, w, h); err != nil {
      log.Printf("error requesting framebuffer update: %v", err)
    }
    time.Sleep(1*time.Second)
  }
}()

// Listen and handle server messages.
go vc.ListenAndHandle()

// Process messages coming in on the ServerMessage channel.
for {
  msg := <-vcc.ServerMessageCh
  switch msg.Type() {
  case FramebufferUpdateMsg:
    log.Println("Received FramebufferUpdate message.")
  default:
    log.Printf("Received message type:%v msg:%v\n", msg.Type(), msg)
  }
}

This example will connect to a VNC server running on the localhost. It will periodically request updates from the server, and listen for and handle incoming FramebufferUpdate messages coming from the server.

Index

Examples

Constants

View Source 
const (
	PressKey   = true
	ReleaseKey = false
)
View Source 
const (
	KeySpace = iota + 0x0020
	KeyExclam
	KeyQuoteDbl
	KeyNumberSign
	KeyDollar
	KeyPercent
	KeyAmpersand
	KeyApostrophe
	KeyParenLeft
	KeyParenRight
	KeyAsterisk
	KeyPlus
	KeyComma
	KeyMinus
	KeyPeriod
	KeySlash
	Key0
	Key1
	Key2
	Key3
	Key4
	Key5
	Key6
	Key7
	Key8
	Key9
	KeyColon
	KeySemicolon
	KeyLess
	KeyEqual
	KeyGreater
	KeyQuestion
	KeyAt
	KeyA
	KeyB
	KeyC
	KeyD
	KeyE
	KeyF
	KeyG
	KeyH
	KeyI
	KeyJ
	KeyK
	KeyL
	KeyM
	KeyN
	KeyO
	KeyP
	KeyQ
	KeyR
	KeyS
	KeyT
	KeyU
	KeyV
	KeyW
	KeyX
	KeyY
	KeyZ
	KeyBracketLeft
	KeyBackslash
	KeyBracketRight
	KeyAsciiCircum
	KeyUnderscore
	KeyGrave
	Keya
	Keyb
	Keyc
	Keyd
	Keye
	Keyf
	Keyg
	Keyh
	Keyi
	Keyj
	Keyk
	Keyl
	Keym
	Keyn
	Keyo
	Keyp
	Keyq
	Keyr
	Keys
	Keyt
	Keyu
	Keyv
	Keyw
	Keyx
	Keyy
	Keyz
	KeyBraceLeft
	KeyBar
	KeyBraceRight
	KeyAsciiTilde
)

Latin 1 (byte 3 = 0) ISO/IEC 8859-1 = Unicode U+0020..U+00FF

View Source 
const (
	KeyBackspace = iota + 0xff08
	KeyTab
	KeyLinefeed
	KeyClear

	KeyReturn
)
View Source 
const (
	KeyPause      = 0xff13
	KeyScrollLock = 0xff14
	KeySysReq     = 0xff15
	KeyEscape     = 0xff1b
)
View Source 
const (
	KeyHome = iota + 0xff50
	KeyLeft
	KeyUp
	KeyRight
	KeyDown
	KeyPageUp
	KeyPageDown
	KeyEnd
	KeyInsert = 0xff63
)
View Source 
const (
	KeyF1 = iota + 0xffbe
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
)
View Source 
const (
	KeyShiftLeft = iota + 0xffe1
	KeyShiftRight
	KeyControlLeft
	KeyControlRight
	KeyCapsLock

	KeyAltLeft
	KeyAltRight
	KeyDelete = 0xffff
)
View Source 
const (
	RFBFalse = uint8(iota)
	RFBTrue
)
View Source 
const (
	Raw               = int32(0)
	CopyRect          = int32(1)
	RRE               = int32(2)
	Hextile           = int32(5)
	TRLE              = int32(15)
	ZRLE              = int32(16)
	ColorPseudo       = int32(-239)
	DesktopSizePseudo = int32(-223)
)
View Source 
const (
	// Client ProtocolVersions.
	PROTO_VERS_UNSUP = "UNSUPPORTED"
	PROTO_VERS_3_3   = "RFB 003.003\n"
	PROTO_VERS_3_8   = "RFB 003.008\n"
)
View Source 
const (
	FramebufferUpdateMsg = uint8(iota)
	SetColorMapEntriesMsg
	BellMsg
	ServerCutTextMsg
)

Variables

This section is empty.

Functions

func NewVNCError 

func NewVNCError(s string) error

NewVNCError returns a custom VNCError error.

func SetSettle 

func SetSettle(s time.Duration)

SetSettle changes the UI settle duration.

func Settle 

func Settle() time.Duration

Settle returns the UI settle duration.

Types

type Bell 

type Bell struct{}

Bell signals that an audible bell should be made on the client.

See RFC 6143 Section 7.6.3

func (*Bell) Read 

func (*Bell) Read(c *ClientConn) (ServerMessage, error)

func (*Bell) Type 

func (*Bell) Type() uint8

type Buffer 

type Buffer struct {
	// contains filtered or unexported fields
}

func NewBuffer 

func NewBuffer(b []byte) *Buffer

func (*Buffer) Bytes 

func (b *Buffer) Bytes() []byte

func (*Buffer) Read 

func (b *Buffer) Read(data interface{}) error

func (*Buffer) Write 

func (b *Buffer) Write(data interface{}) error

func (*Buffer) WriteByte 

func (b *Buffer) WriteByte(c byte)

func (*Buffer) WriteBytes 

func (b *Buffer) WriteBytes(p []byte)

type ButtonMask 

type ButtonMask uint8

ButtonMask represents a mask of pointer presses/releases. 

const (
	ButtonLeft ButtonMask = 1 << iota
	ButtonMiddle
	ButtonRight
	Button4
	Button5
	Button6
	Button7
	Button8
	ButtonNone = ButtonMask(0)
)

All available button mask components.

type ClientAuth 

type ClientAuth interface {
	// SecurityType returns the byte identifier sent by the server to
	// identify this authentication scheme.
	SecurityType() uint8

	// Handshake is called when the authentication handshake should be
	// performed, as part of the general RFB handshake. (see 7.2.1)
	Handshake(*ClientConn) error
}

ClientAuth implements a method of authenticating with a remote server.

type ClientAuthNone 

type ClientAuthNone struct{}

ClientAuthNone is the "none" authentication. See 7.2.1.

func (*ClientAuthNone) Handshake 

func (*ClientAuthNone) Handshake(conn *ClientConn) error

func (*ClientAuthNone) SecurityType 

func (*ClientAuthNone) SecurityType() uint8

type ClientAuthVNC 

type ClientAuthVNC struct {
	Password string
}

ClientAuthVNC is the standard password authentication. See 7.2.2.

func (*ClientAuthVNC) Handshake 

func (auth *ClientAuthVNC) Handshake(conn *ClientConn) error

func (*ClientAuthVNC) SecurityType 

func (*ClientAuthVNC) SecurityType() uint8

type ClientConfig 

type ClientConfig struct {

	// A slice of ClientAuth methods. Only the first instance that is
	// suitable by the server will be used to authenticate.
	Auth []ClientAuth

	// Password for servers that require authentication.
	Password string

	// Exclusive determines whether the connection is shared with other
	// clients. If true, then all other clients connected will be
	// disconnected when a connection is established to the VNC server.
	Exclusive bool

	// The channel that all messages received from the server will be
	// sent on. If the channel blocks, then the goroutine reading data
	// from the VNC server may block indefinitely. It is up to the user
	// of the library to ensure that this channel is properly read.
	// If this is not set, then all messages will be discarded.
	ServerMessageCh chan ServerMessage

	// A slice of supported messages that can be read from the server.
	// This only needs to contain NEW server messages, and doesn't
	// need to explicitly contain the RFC-required messages.
	ServerMessages []ServerMessage
	// contains filtered or unexported fields
}

A ClientConfig structure is used to configure a ClientConn. After one has been passed to initialize a connection, it must not be modified.

func NewClientConfig 

func NewClientConfig(p string) *ClientConfig

NewClientConfig returns a populated ClientConfig.

type ClientConn 

type ClientConn struct {
	// contains filtered or unexported fields
}

The ClientConn type holds client connection information.

func Connect 

func Connect(ctx context.Context, c net.Conn, cfg *ClientConfig) (*ClientConn, error)

Connect negotiates a connection to a VNC server.

func NewClientConn 

func NewClientConn(c net.Conn, cfg *ClientConfig) *ClientConn

func (*ClientConn) ClientCutText 

func (c *ClientConn) ClientCutText(text string) error

ClientCutText tells the server that the client has new text in its cut buffer. The text string MUST only contain Latin-1 characters. This encoding is compatible with Go's native string format, but can only use up to unicode.MaxLatin1 values.

See RFC 6143 Section 7.5.6

func (*ClientConn) Close 

func (c *ClientConn) Close() error

Close a connection to a VNC server.

func (*ClientConn) DebugMetrics 

func (c *ClientConn) DebugMetrics()

func (*ClientConn) DesktopName 

func (c *ClientConn) DesktopName() string

DesktopName returns the server provided desktop name.

func (*ClientConn) Encodable 

func (c *ClientConn) Encodable(enc int32) (Encoding, bool)

func (*ClientConn) Encodings 

func (c *ClientConn) Encodings() Encodings

Encodings returns the server provided encodings.

func (*ClientConn) FramebufferHeight 

func (c *ClientConn) FramebufferHeight() uint16

FramebufferHeight returns the server provided framebuffer height.

func (*ClientConn) FramebufferUpdateRequest 

func (c *ClientConn) FramebufferUpdateRequest(inc uint8, x, y, w, h uint16) error

Requests a framebuffer update from the server. There may be an indefinite time between the request and the actual framebuffer update being received.

See RFC 6143 Section 7.5.3

func (*ClientConn) FramebufferWidth 

func (c *ClientConn) FramebufferWidth() uint16

FramebufferWidth returns the server provided framebuffer width.

func (*ClientConn) KeyEvent 

func (c *ClientConn) KeyEvent(keysym uint32, down bool) error

KeyEvent indicates a key press or release and sends it to the server. The key is indicated using the X Window System "keysym" value. Use Google to find a reference of these values. To simulate a key press, you must send a key with both a down event, and a non-down event.

See RFC 6143 Section 7.5.4.

Example 
// Establish TCP connection.
nc, err := net.DialTimeout("tcp", "127.0.0.1:5900", 10*time.Second)
if err != nil {
	panic(fmt.Sprintf("Error connecting to host: %v\n", err))
}

// Negotiate VNC connection.
vc, err := Connect(context.Background(), nc, NewClientConfig("somepass"))
if err != nil {
	panic(fmt.Sprintf("Could not negotiate a VNC connection: %v\n", err))
}

// Press and release the return key.
vc.KeyEvent(KeyReturn, true)
vc.KeyEvent(KeyReturn, false)

// Close VNC connection.
vc.Close()

Output:

func (*ClientConn) ListenAndHandle 

func (c *ClientConn) ListenAndHandle() error

ListenAndHandle listens to a VNC server and handles server messages.

func (*ClientConn) PointerEvent 

func (c *ClientConn) PointerEvent(mask ButtonMask, x, y uint16) error

PointerEvent indicates that pointer movement or a pointer button press or release.

The mask is a bitwise mask of various ButtonMask values. When a button is set, it is pressed, when it is unset, it is released.

See RFC 6143 Section 7.5.5

Example 
// Establish TCP connection.
nc, err := net.DialTimeout("tcp", "127.0.0.1:5900", 10*time.Second)
if err != nil {
	panic(fmt.Sprintf("Error connecting to host: %v\n", err))
}

// Negotiate VNC connection.
vc, err := Connect(context.Background(), nc, NewClientConfig("somepass"))
if err != nil {
	panic(fmt.Sprintf("Could not negotiate a VNC connection: %v\n", err))
}

// Move mouse to x=100, y=200.
x, y := uint16(100), uint16(200)
vc.PointerEvent(ButtonNone, x, y)

// Click and release the left mouse button.
vc.PointerEvent(ButtonLeft, x, y)
vc.PointerEvent(ButtonNone, x, y)

// Close connection.
vc.Close()

Output:

func (*ClientConn) SetDebug 

func (c *ClientConn) SetDebug(debug bool)

SetDebugging [dis-]enables debugging.

func (*ClientConn) SetEncodings 

func (c *ClientConn) SetEncodings(encs Encodings) error

SetEncodings sets the encoding types in which the pixel data can be sent from the server. After calling this method, the encs slice given should not be modified.

See RFC 6143 Section 7.5.2

func (*ClientConn) SetPixelFormat 

func (c *ClientConn) SetPixelFormat(pf PixelFormat) error

SetPixelFormat sets the format in which pixel values should be sent in FramebufferUpdate messages from the server.

See RFC 6143 Section 7.5.1

type ClientCutTextMessage 

type ClientCutTextMessage struct {
	Msg uint8 // message-type

	Length uint32 // length
	// contains filtered or unexported fields
}

ClientCutTextMessage holds the wire format message, sans the text field.

type Color 

type Color struct {
	R, G, B uint16
	// contains filtered or unexported fields
}

Color represents a single color in a color map.

func NewColor 

func NewColor(pf *PixelFormat, cm *ColorMap) *Color

func (*Color) Marshal 

func (c *Color) Marshal() ([]byte, error)

func (*Color) Unmarshal 

func (c *Color) Unmarshal(data []byte) error

type ColorMap 

type ColorMap [256]Color

type DesktopSizePseudoEncoding 

type DesktopSizePseudoEncoding struct{}

DesktopSizePseudoEncoding enables desktop resize support. See RFC 6143 §7.8.2.

func (*DesktopSizePseudoEncoding) Marshal 

func (e *DesktopSizePseudoEncoding) Marshal() ([]byte, error)

func (*DesktopSizePseudoEncoding) Read 

func (*DesktopSizePseudoEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, []byte, error)

func (*DesktopSizePseudoEncoding) Type 

func (*DesktopSizePseudoEncoding) Type() int32

type EncodableFunc 

type EncodableFunc func(enc int32) (Encoding, bool)

type Encoding 

type Encoding interface {
	// The number that uniquely identifies this encoding type.
	Type() int32

	// Read the contents of the encoded pixel data from the reader.
	// This should return a new Encoding implementation that contains
	// the proper data.
	Read(*ClientConn, *Rectangle) (Encoding, []byte, error)

	// Marshal implements the Marshaler interface.
	Marshal() ([]byte, error)
}

An Encoding implements a method for encoding pixel data that is sent by the server to the client.

type Encodings 

type Encodings []Encoding

func (Encodings) Marshal 

func (e Encodings) Marshal() ([]byte, error)

type FramebufferUpdate 

type FramebufferUpdate struct {
	NumRect uint16      // number-of-rectangles
	Rects   []Rectangle // rectangles
}

FramebufferUpdate holds the wire format message.

func NewFramebufferUpdate 

func NewFramebufferUpdate(rects []Rectangle) *FramebufferUpdate

func (*FramebufferUpdate) Marshal 

func (m *FramebufferUpdate) Marshal() ([]byte, error)

func (*FramebufferUpdate) Read 

func (m *FramebufferUpdate) Read(c *ClientConn) (ServerMessage, error)

func (*FramebufferUpdate) Type 

func (m *FramebufferUpdate) Type() uint8

type FramebufferUpdateRequestMessage 

type FramebufferUpdateRequestMessage struct {
	Msg           uint8  // message-type
	Inc           uint8  // incremental
	X, Y          uint16 // x-, y-position
	Width, Height uint16 // width, height
}

FramebufferUpdateRequestMessage holds the wire format message.

type KeyEventMessage 

type KeyEventMessage struct {
	Msg      uint8 // message-type
	DownFlag uint8 // down-flag

	Key uint32 // key
	// contains filtered or unexported fields
}

KeyEventMessage holds the wire format message.

type Marshaler 

type Marshaler interface {
	Marshal() ([]byte, error)
}

Marshaler is the interface for objects that can marshal themselves.

type PixelFormat 

type PixelFormat struct {
	BPP                             uint8  // bits-per-pixel
	Depth                           uint8  // depth
	BigEndian                       uint8  // big-endian-flag
	TrueColor                       uint8  // true-color-flag
	RedMax, GreenMax, BlueMax       uint16 // red-, green-, blue-max (2^BPP-1)
	RedShift, GreenShift, BlueShift uint8  // red-, green-, blue-shift
	// contains filtered or unexported fields
}

PixelFormat describes the way a pixel is formatted for a VNC connection. 

var (
	PixelFormat8bit  PixelFormat = NewPixelFormat(8)
	PixelFormat16bit PixelFormat = NewPixelFormat(16)
	PixelFormat32bit PixelFormat = NewPixelFormat(32)
)

func NewPixelFormat 

func NewPixelFormat(bpp uint8) PixelFormat

NewPixelFormat returns a populated PixelFormat structure.

func (PixelFormat) Len 

func (pf PixelFormat) Len() int

Len returns the length of a PixelFormat struct.

func (PixelFormat) Marshal 

func (pf PixelFormat) Marshal() ([]byte, error)

Marshal implements the Marshaler interface.

func (*PixelFormat) Read 

func (pf *PixelFormat) Read(r io.Reader) error

Read reads from an io.Reader, and populates the PixelFormat.

func (*PixelFormat) Unmarshal 

func (pf *PixelFormat) Unmarshal(data []byte) error

Unmarshal implements the Unmarshaler interface.

type PointerEventMessage 

type PointerEventMessage struct {
	Msg  uint8  // message-type
	Mask uint8  // button-mask
	X, Y uint16 // x-, y-position
}

PointerEventMessage holds the wire format message.

type RawEncoding 

type RawEncoding struct {
	Colors []Color
}

RawEncoding is raw pixel data sent by the server. See RFC 6143 §7.7.1.

func (*RawEncoding) Marshal 

func (e *RawEncoding) Marshal() ([]byte, error)

func (*RawEncoding) Read 

func (*RawEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, []byte, error)

func (*RawEncoding) Type 

func (*RawEncoding) Type() int32

type Rectangle 

type Rectangle struct {
	X, Y          uint16
	Width, Height uint16
	Enc           Encoding
	BytePix       []byte
	// contains filtered or unexported fields
}

Rectangle represents a rectangle of pixel data.

func NewRectangle 

func NewRectangle(c *ClientConn) *Rectangle

func (*Rectangle) Area 

func (r *Rectangle) Area() int

func (*Rectangle) DebugPrint 

func (r *Rectangle) DebugPrint()

func (*Rectangle) Marshal 

func (r *Rectangle) Marshal() ([]byte, error)

func (*Rectangle) Read 

func (r *Rectangle) Read(c *ClientConn) error

Read a rectangle from a connection.

func (*Rectangle) Unmarshal 

func (r *Rectangle) Unmarshal(data []byte) error

type ServerCutText 

type ServerCutText struct {
	Text string
}

ServerCutText indicates the server has new text in the cut buffer.

See RFC 6143 Section 7.6.4

func (*ServerCutText) Read 

func (*ServerCutText) Read(c *ClientConn) (ServerMessage, error)

func (*ServerCutText) Type 

func (*ServerCutText) Type() uint8

type ServerMessage 

type ServerMessage interface {
	// The type of the message that is sent down on the wire.
	Type() uint8

	// Read reads the contents of the message from the reader. At the point
	// this is called, the message type has already been read from the reader.
	// This should return a new ServerMessage that is the appropriate type.
	Read(*ClientConn) (ServerMessage, error)
}

A ServerMessage implements a message sent from the server to the client.

type SetColorMapEntries 

type SetColorMapEntries struct {
	FirstColor uint16
	Colors     []Color
}

func (*SetColorMapEntries) Read 

func (*SetColorMapEntries) Read(c *ClientConn) (ServerMessage, error)

func (*SetColorMapEntries) Type 

func (*SetColorMapEntries) Type() uint8

type SetEncodingsMessage 

type SetEncodingsMessage struct {
	Msg uint8 // message-type

	NumEncs uint16 // number-of-encodings
	// contains filtered or unexported fields
}

SetEncodingsMessage holds the wire format message, sans encoding-type field.

type SetPixelFormatMessage 

type SetPixelFormatMessage struct {
	Msg uint8 // message-type

	PF PixelFormat // pixel-format
	// contains filtered or unexported fields
}

SetPixelFormatMessage holds the wire format message.

type Unmarshaler 

type Unmarshaler interface {
	Unmarshal([]byte) error
}

Unmarshaler is the interface for objects that can marshal themselves.

type VNCError 

type VNCError struct {
	// contains filtered or unexported fields
}

VNCError implements error interface.

func (VNCError) Error 

func (e VNCError) Error() string

Error returns an VNCError as a string.

Source Files

View all Source files

Directories

Path Synopsis
go
metrics
The metrics package provides support for tracking various metrics.
 The metrics package provides support for tracking various metrics.
operators

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.