xgb

README

go-xgb

XGB is the X protocol Go language Binding.

It is the Go equivalent of XCB, the X protocol C-language Binding (http://xcb.freedesktop.org/).

gruf's Fork

This is a fork of jezek's go-xgb repository. It is not yet complete...

• ewmh, xcursor, icccm packages are unsupported
• tests are not yet updated

It is a complete rewrite of the dialer, underlying X connection and generated code itself. Though the existing xgbgen code generator was still used as the basis for parsing xcb definition files.

The primary differences intended were:

• more idiomatic Go code
• more idiomatic logging
• support debug output via debug build tag
• rely on memory pooling where possible

jezek's Fork

I've forked the XGB repository from BurntSushi's github to apply some patches which caused panics and memory leaks upon close and tests were added, to test multiple server close scenarios.

BurntSushi's Fork

I've forked the XGB repository from Google Code due to inactivty upstream.

Godoc documentation can be found here: https://godoc.org/github.com/BurntSushi/xgb

Much of the code has been rewritten in an effort to support thread safety and multiple extensions. Namely, go_client.py has been thrown away in favor of an xgbgen package.

The biggest parts that haven't been rewritten by me are the connection and authentication handshakes. They're inherently messy, and there's really no reason to re-work them. The rest of XGB has been completely rewritten.

I like to release my code under the WTFPL, but since I'm starting with someone else's work, I'm leaving the original license/contributor/author information in tact.

I suppose I can legitimately release xgbgen under the WTFPL. To be fair, it is at least as complex as XGB itself. sigh

Unless otherwise noted, the XGB source files are distributed under the BSD-style license found in the LICENSE file.

Contributions should follow the same procedure as for the Go project: http://golang.org/doc/contribute.html

Documentation

Index

• Variables
• func ReadAuthority(hostname, display string) (string, []byte, error)
• type ErrorUnmarshaler
• type EventUnmarshaler
• type IgnoreXReply
  • func (IgnoreXReply) Unmarshal([]byte) error
• type RawXReply
  • func (rpl *RawXReply) Unmarshal(data []byte) error
• type XConn
  • func Dial(display string) (*XConn, []byte, error)
  • func (conn *XConn) Close() error
  • func (conn *XConn) Ext(name string) (op uint8, ok bool)
  • func (conn *XConn) NewXID() uint32
  • func (conn *XConn) Recv() (XEvent, error)
  • func (conn *XConn) Register(ext XExtension) error
  • func (conn *XConn) Send(data []byte) error
  • func (conn *XConn) SendRecv(data []byte, dst XReply) error
  • func (conn *XConn) Sync() error
• type XDialer
  • func (d *XDialer) Dial(display string) (*XConn, []byte, error)
  • func (d *XDialer) DialConn(authName string, authData []byte, conn net.Conn) (*XConn, []byte, error)
  • func (d *XDialer) DialContext(ctx context.Context, display string) (*XConn, []byte, error)
• type XError
• type XEvent
• type XExtension
• type XReply

Variables

var DefaultDialer = XDialer{
	InboundBuffer: 1000,
}

DefaultDialer is the default XDialer instance.

Functions

func ReadAuthority

func ReadAuthority(hostname, display string) (string, []byte, error)

ReadAuthority reads the X authority file for the DISPLAY. Uses os.Hostname() if hostname empty. Returns authority name and data.

Types

type ErrorUnmarshaler

type ErrorUnmarshaler func([]byte) (XError, error)

type EventUnmarshaler

type EventUnmarshaler func([]byte) (XEvent, error)

type IgnoreXReply

type IgnoreXReply struct{}

ignoreXReply is a noop XReply implementation.

func (IgnoreXReply) Unmarshal

func (IgnoreXReply) Unmarshal([]byte) error

type RawXReply

type RawXReply []byte

RawXReply is a byte slice type alias that fulfills the XReply interface type, allowing you to store an X reply for later decoding.

func (*RawXReply) Unmarshal

func (rpl *RawXReply) Unmarshal(data []byte) error

type XConn

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

XConn represents a connection to an X server, handling asychronous background receipt and unmarshaling of incoming data for use as the more accessible XError and XEvent types.

func Dial

func Dial(display string) (*XConn, []byte, error)

Dial calls XDialer{}.Dial() on the DefaultDialer instance.

func (*XConn) Close

func (conn *XConn) Close() error

Close will close the X connection.

func (*XConn) Ext

func (conn *XConn) Ext(name string) (op uint8, ok bool)

Ext returns the major opcode for extension with given name.

func (*XConn) NewXID

func (conn *XConn) NewXID() uint32

NextID returns the next available X ID.

func (*XConn) Recv

func (conn *XConn) Recv() (XEvent, error)

Recv blocks until receipt of next XEvent / error.

func (*XConn) Register

func (conn *XConn) Register(ext XExtension) error

Register querying the X server for support of this extension, and register relevant event / error unmarshalers internally within XConn.

func (*XConn) Send

func (conn *XConn) Send(data []byte) error

Send will send given data to the X server.

func (*XConn) SendRecv

func (conn *XConn) SendRecv(data []byte, dst XReply) error

SendRecv sends the given data, and blocks until receipt of XReply into given container.

func (*XConn) Sync

func (conn *XConn) Sync() error

Sync will force a roundtrip to X server, by sending a GetInputFocus request and blocking on X response.

type XDialer

type XDialer struct {

	// InboundBuffer allows specifying how
	// many inbound X messages to buffer
	// before the connection will block.
	InboundBuffer int

	// NetDialer allows specifying the
	// underlying net.Dialer to use.
	NetDialer *net.Dialer
}

XDialer provides a dialer for connection to an X server.

func (*XDialer) Dial

func (d *XDialer) Dial(display string) (*XConn, []byte, error)

Dial calls XDialer{}.DialContext() using background context (non-blocking).

func (*XDialer) DialConn

func (d *XDialer) DialConn(authName string, authData []byte, conn net.Conn) (*XConn, []byte, error)

DialConn attempts to prepare new X connection (including auth handshake) for an already open network connection.

func (*XDialer) DialContext

func (d *XDialer) DialContext(ctx context.Context, display string) (*XConn, []byte, error)

DialContext attempts to open X connection for given display (X format network address) string.

type XError

type XError interface {
	// SeqID returns the X sequence ID
	// this error is associated with.
	SeqID() uint16

	error
}

type XEvent

type XEvent interface {
	// SeqID returns the X sequence ID
	// this event is associated with.
	SeqID() uint16
}

type XExtension

type XExtension struct {
	XName       string
	MajorOpcode uint8
	EventFuncs  map[uint8]EventUnmarshaler
	ErrorFuncs  map[uint8]ErrorUnmarshaler
}

type XReply

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