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.
Implementation of RFC 6143 §7.7 Encodings. https://tools.ietf.org/html/rfc6143#section-7.7
Implementation of RFC 6143 §7.6 Server-to-Client Messages. https://tools.ietf.org/html/rfc6143#section-7.6
Index ¶
- Constants
- func Errorf(format string, a ...interface{}) error
- func NewVNCError(desc string) error
- func SetSettle(s time.Duration)
- func Settle() time.Duration
- type Bell
- type Buffer
- type ClientAuth
- type ClientAuthNone
- type ClientAuthVNC
- type ClientConfig
- type ClientConn
- func (c *ClientConn) ClientCutText(text string) error
- func (c *ClientConn) Close() error
- func (c *ClientConn) DebugMetrics()
- func (c *ClientConn) DesktopName() string
- func (c *ClientConn) Encodable(enc encodings.Encoding) (Encoding, bool)
- func (c *ClientConn) Encodings() Encodings
- func (c *ClientConn) FramebufferHeight() uint16
- func (c *ClientConn) FramebufferUpdateRequest(inc rfbflags.RFBFlag, x, y, w, h uint16) error
- func (c *ClientConn) FramebufferWidth() uint16
- func (c *ClientConn) KeyEvent(key keys.Key, down bool) error
- func (c *ClientConn) ListenAndHandle() error
- func (c *ClientConn) PointerEvent(button buttons.Button, x, y uint16) error
- func (c *ClientConn) SetEncodings(encs Encodings) error
- func (c ClientConn) SetFrameBuffer(width uint16, height uint16) (err error)
- func (c *ClientConn) SetPixelFormat(pf PixelFormat) error
- func (c *ClientConn) ZlibStream() zrle.ZlibStream
- type ClientCutTextMessage
- type Color
- type ColorMap
- type CopyRectEncoding
- type CursorPseudoEncoding
- type DesktopSizePseudoEncoding
- type EncodableFunc
- type Encoding
- type Encodings
- type FramebufferUpdate
- type FramebufferUpdateRequestMessage
- type KeyEventMessage
- type Marshaler
- type MarshalerUnmarshaler
- type PixelFormat
- type PointerEventMessage
- type RRERect
- type RREncoding
- type RawEncoding
- type Rectangle
- type ServerCutText
- type ServerInit
- type ServerMessage
- type SetColorMapEntries
- type SetEncodingsMessage
- type SetPixelFormatMessage
- type Unmarshaler
- type VNCError
- type ZRLEncoding
Examples ¶
Constants ¶
const ( PressKey = true ReleaseKey = false )
const ( // Client ProtocolVersions. PROTO_VERS_UNSUP = "UNSUPPORTED" PROTO_VERS_3_3 = "RFB 003.003\n" PROTO_VERS_3_8 = "RFB 003.008\n" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Bell ¶
type Bell struct{}
Bell represents the wire format message, sans message-type.
func (*Bell) Read ¶
func (*Bell) Read(c *ClientConn) (ServerMessage, error)
Read implements the ServerMessage interface.
func (*Bell) Type ¶
func (*Bell) Type() messages.ServerMessage
Type implements the ServerMessage interface.
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.
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 encodings.Encoding) (Encoding, bool)
Encodable returns the Encoding that can be used to encode a Rectangle, or false if the encoding isn't recognized.
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 rfbflags.RFBFlag, 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.
func (*ClientConn) FramebufferWidth ¶
func (c *ClientConn) FramebufferWidth() uint16
FramebufferWidth returns the server provided framebuffer width.
func (*ClientConn) KeyEvent ¶
func (c *ClientConn) KeyEvent(key keys.Key, 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. Constants are provided in `keys/keys.go`. To simulate a key press, you must send a key with both a true and false down event.
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(keys.Return, true) vc.KeyEvent(keys.Return, 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(button buttons.Button, x, y uint16) error
PointerEvent indicates that pointer movement or a pointer button press or release.
The `button` is a bitwise mask of various Button values. When a button is set, it is pressed, when it is unset, it is released.
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(buttons.None, x, y) // Click and release the left mouse button. vc.PointerEvent(buttons.Left, x, y) vc.PointerEvent(buttons.None, x, y) // Close connection. vc.Close()
Output:
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.
TODO(kward:20170306) Fix bad practice of mixing of protocol and internal state here.
func (ClientConn) SetFrameBuffer ¶
func (c ClientConn) SetFrameBuffer(width uint16, height uint16) (err error)
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.
func (*ClientConn) ZlibStream ¶
func (c *ClientConn) ZlibStream() zrle.ZlibStream
type ClientCutTextMessage ¶
type ClientCutTextMessage struct { Msg messages.ClientMessage // 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
NewColor returns a new Color object.
type CopyRectEncoding ¶
func (*CopyRectEncoding) Marshal ¶
func (*CopyRectEncoding) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*CopyRectEncoding) Read ¶
func (*CopyRectEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*CopyRectEncoding) String ¶
func (*CopyRectEncoding) String() string
String implements the fmt.Stringer interface.
func (*CopyRectEncoding) Type ¶
func (*CopyRectEncoding) Type() encodings.Encoding
Type implements the Encoding interface.
type CursorPseudoEncoding ¶
type CursorPseudoEncoding struct {
// contains filtered or unexported fields
}
CursorPseudoEncoding represents a Cursor message from the server.
func (*CursorPseudoEncoding) Marshal ¶
func (e *CursorPseudoEncoding) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*CursorPseudoEncoding) Read ¶
func (*CursorPseudoEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*CursorPseudoEncoding) String ¶
func (e *CursorPseudoEncoding) String() string
String implements the fmt.Stringer interface.
func (*CursorPseudoEncoding) Type ¶
func (*CursorPseudoEncoding) Type() encodings.Encoding
Type implements the Encoding interface.
type DesktopSizePseudoEncoding ¶
type DesktopSizePseudoEncoding struct{}
DesktopSizePseudoEncoding represents a desktop size message from the server.
func (*DesktopSizePseudoEncoding) Marshal ¶
func (e *DesktopSizePseudoEncoding) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*DesktopSizePseudoEncoding) Read ¶
func (*DesktopSizePseudoEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*DesktopSizePseudoEncoding) String ¶
func (e *DesktopSizePseudoEncoding) String() string
String implements the fmt.Stringer interface.
func (*DesktopSizePseudoEncoding) Type ¶
func (*DesktopSizePseudoEncoding) Type() encodings.Encoding
Type implements the Encoding interface.
type EncodableFunc ¶
EncodableFunc describes the function for encoding a Rectangle.
type Encoding ¶
type Encoding interface { fmt.Stringer Marshaler // 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, error) // The number that uniquely identifies this encoding type. Type() encodings.Encoding }
An Encoding implements a method for encoding pixel data that is sent by the server to the client.
type FramebufferUpdate ¶
type FramebufferUpdate struct { NumRect uint16 // number-of-rectangles Rects []Rectangle // rectangles }
FramebufferUpdate holds a FramebufferUpdate wire format message.
func (*FramebufferUpdate) Marshal ¶
func (m *FramebufferUpdate) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*FramebufferUpdate) Read ¶
func (m *FramebufferUpdate) Read(c *ClientConn) (ServerMessage, error)
Read implements the ServerMessage interface.
func (*FramebufferUpdate) Type ¶
func (m *FramebufferUpdate) Type() messages.ServerMessage
Type implements the ServerMessage interface.
func (*FramebufferUpdate) Unmarshal ¶
func (m *FramebufferUpdate) Unmarshal(_ []byte) error
Unmarshal implements the Unmarshaler interface.
type FramebufferUpdateRequestMessage ¶
type FramebufferUpdateRequestMessage struct { Msg messages.ClientMessage // message-type Inc rfbflags.RFBFlag // incremental X, Y uint16 // x-, y-position Width, Height uint16 // width, height }
FramebufferUpdateRequestMessage holds the wire format message.
type KeyEventMessage ¶
type KeyEventMessage struct { Msg messages.ClientMessage // message-type DownFlag rfbflags.RFBFlag // down-flag Key keys.Key // key // contains filtered or unexported fields }
KeyEventMessage holds the wire format message.
type Marshaler ¶
type Marshaler interface { // Marshal returns the wire encoding of a message. Marshal() ([]byte, error) }
Marshaler is the interface satisfied for marshaling messages.
type MarshalerUnmarshaler ¶
type MarshalerUnmarshaler interface { Marshaler Unmarshaler }
MarshalerUnmarshaler satisfies both the Marshaler and Unmarshaler interfaces.
type PixelFormat ¶
type PixelFormat struct { BPP uint8 // bits-per-pixel Depth uint8 // depth BigEndian rfbflags.RFBFlag // big-endian-flag TrueColor rfbflags.RFBFlag // 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) 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) String ¶
func (pf PixelFormat) String() string
String implements the fmt.Stringer interface.
func (*PixelFormat) Unmarshal ¶
func (pf *PixelFormat) Unmarshal(data []byte) error
Unmarshal implements the Unmarshaler interface.
type PointerEventMessage ¶
type PointerEventMessage struct { Msg messages.ClientMessage // message-type Mask uint8 // button-mask X, Y uint16 // x-, y-position }
PointerEventMessage holds the wire format message.
type RREncoding ¶
RREncoding represents an RRE encoded framebufferupdate
func (*RREncoding) Marshal ¶
func (e *RREncoding) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*RREncoding) Read ¶
func (*RREncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*RREncoding) String ¶
func (e *RREncoding) String() string
String implements the fmt.Stringer interface.
func (*RREncoding) Type ¶
func (*RREncoding) Type() encodings.Encoding
Type implements the Encoding interface.
type RawEncoding ¶
type RawEncoding struct {
Colors []Color
}
RawEncoding holds raw encoded rectangle data.
func (*RawEncoding) Marshal ¶
func (e *RawEncoding) Marshal() ([]byte, error)
Marshal implements the Encoding interface.
func (*RawEncoding) Read ¶
func (*RawEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*RawEncoding) String ¶
func (*RawEncoding) String() string
String implements the fmt.Stringer interface.
func (*RawEncoding) Type ¶
func (*RawEncoding) Type() encodings.Encoding
Type implements the Encoding interface.
type Rectangle ¶
type Rectangle struct {
X, Y uint16
Width, Height uint16
Enc Encoding
// contains filtered or unexported fields
}
Rectangle represents a rectangle of pixel data.
func NewRectangle ¶
func NewRectangle(fn EncodableFunc) *Rectangle
NewRectangle returns a new Rectangle object.
func (*Rectangle) Read ¶
func (r *Rectangle) Read(c *ClientConn) error
Read a rectangle message from ClientConn c.
type ServerCutText ¶
type ServerCutText struct {
Text string
}
ServerCutText represents the wire format message, sans message-type and padding.
func (*ServerCutText) Read ¶
func (*ServerCutText) Read(c *ClientConn) (ServerMessage, error)
Read implements the ServerMessage interface.
func (*ServerCutText) Type ¶
func (*ServerCutText) Type() messages.ServerMessage
Type implements the ServerMessage interface.
type ServerInit ¶
type ServerInit struct {
FBWidth, FBHeight uint16
PixelFormat PixelFormat
NameLength uint32
}
ServerInit message sent after server receives a ClientInit message. https://tools.ietf.org/html/rfc6143#section-7.3.2
func (*ServerInit) Unmarshal ¶
func (m *ServerInit) Unmarshal(data []byte) error
type ServerMessage ¶
type ServerMessage interface { // The type of the message that is sent down on the wire. Type() messages.ServerMessage // 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) }
ServerMessage is the interface satisfied by server messages.
type SetColorMapEntries ¶
SetColorMapEntries holds a SetColorMapEntries wire format message, sans message-type and padding.
func (*SetColorMapEntries) Read ¶
func (*SetColorMapEntries) Read(c *ClientConn) (ServerMessage, error)
Read implements the ServerMessage interface.
func (*SetColorMapEntries) Type ¶
func (*SetColorMapEntries) Type() messages.ServerMessage
Type implements the ServerMessage interface.
type SetEncodingsMessage ¶
type SetEncodingsMessage struct { Msg messages.ClientMessage // 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 messages.ClientMessage // message-type PF PixelFormat // pixel-format // contains filtered or unexported fields }
SetPixelFormatMessage holds the wire format message.
type Unmarshaler ¶
type Unmarshaler interface { // Unmarshal parses a wire format message into a message. Unmarshal(data []byte) error }
Unarshaler is the interface satisfied for unmarshaling messages.
type VNCError ¶
type VNCError struct {
// contains filtered or unexported fields
}
VNCError implements error interface.
type ZRLEncoding ¶
ZRLEncoding represents an ZRLE encoded update
func (*ZRLEncoding) Decode ¶
func (z *ZRLEncoding) Decode(c *ClientConn, rect *Rectangle) ([][]zrle.CPixel, error)
Decode Decodes the data attached to the ZLRE message
func (*ZRLEncoding) Marshal ¶
func (z *ZRLEncoding) Marshal() ([]byte, error)
Marshal implements the Marshaler interface.
func (*ZRLEncoding) Read ¶
func (z *ZRLEncoding) Read(c *ClientConn, rect *Rectangle) (Encoding, error)
Read implements the Encoding interface.
func (*ZRLEncoding) String ¶
func (z *ZRLEncoding) String() string
String implements the fmt.Stringer interface.
func (*ZRLEncoding) Type ¶
func (z *ZRLEncoding) Type() encodings.Encoding
Type implements the Encoding interface.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package buttons describes the supported button masks.
|
Package buttons describes the supported button masks. |
Package encodings provides constants for the known VNC encoding types.
|
Package encodings provides constants for the known VNC encoding types. |
go
|
|
metrics
The metrics package provides support for tracking various metrics.
|
The metrics package provides support for tracking various metrics. |
Package keys provides constants for all the keyboard inputs.
|
Package keys provides constants for all the keyboard inputs. |
Package logging provides common logging functionality.
|
Package logging provides common logging functionality. |
Package messages provides constants for the client and server messages.
|
Package messages provides constants for the client and server messages. |
Package rfbflags provides constants for the RFB flag values.
|
Package rfbflags provides constants for the RFB flag values. |