xgbsel/request.go

package xgbsel

import "io"
import "bytes"
import "errors"
import "github.com/jezek/xgb"
import "github.com/jezek/xgbutil"
import "github.com/jezek/xgb/xproto"
import "github.com/jezek/xgbutil/xprop"
import "github.com/jezek/xgbutil/xevent"
import "github.com/jezek/xgbutil/xwindow"

type selReqState int; const (
	selReqStateClosed selReqState = iota
	selReqStateAwaitTargets
	selReqStateAwaitValue
	selReqStateAwaitChunk
)

// Requestor provices details about the request such as the window that is
// requesting the selection data, and what targets it accepts.
type Requestor interface {
	// Window returns the window that is requesting the selection data.
	Window () *xwindow.Window

	// Choose picks target from a slice of available targets and returns
	// (target, true). If no target was picket, it returns ("", false).
	Choose (available []Target) (target Target, ok bool)

	// Success is called once the owner responds with data. The data must be
	// closed once it has been read.
	Success (Target, io.ReadCloser)

	// Failure is called if the transfer fails at any point, or if there
	// isn't any data to begin with. In the first case, an error is given.
	// In the second case, the error will be nil.
	Failure (error)
}

// Request represents an ongoing request for the selection contents.
type Request struct {
	state       selReqState
	requestor   Requestor
	source      xproto.Atom
	destination xproto.Atom
	incrBuffer  []byte
	incrTarget  Target
}

// NewRequest sends a new selection request.
func NewRequest (requestor Requestor, source, destination xproto.Atom) *Request {
	request := &Request {
		source:      source,
		destination: destination,
		requestor:   requestor,
	}

	targets, err := xprop.Atm(requestor.Window().X, "TARGETS")
	if err != nil { request.die(err); return nil }
	request.convertSelection(targets, selReqStateAwaitTargets)
	return request
}

func (request *Request) convertSelection (target xproto.Atom, switchTo selReqState) {
	// The requestor should set the property argument to the name of a
	// property that the owner can use to report the value of the selection.
	// Requestors should ensure that the named property does not exist on
	// the window before issuing the ConvertSelection. The exception to this
	// rule is when the requestor intends to pass parameters with the
	// request. Some targets may be defined such that requestors can pass
	// parameters along with the request. If the requestor wishes to provide
	// parameters to a request, they should be placed in the specified
	// property on the requestor window before the requestor issues the
	// ConvertSelection request, and this property should be named in the
	// request.
	err := xproto.DeletePropertyChecked (
		request.requestor.Window().X.Conn(),
		request.requestor.Window().Id,
		request.destination).Check()
	if err != nil { request.die(err); return }

	// The selection argument specifies the particular selection involved,
	// and the target argument specifies the required form of the
	// information. For information about the choice of suitable atoms to
	// use, see section 2.6. The requestor should set the requestor argument
	// to a window that it created; the owner will place the reply property
	// there. The requestor should set the time argument to the timestamp on
	// the event that triggered the request for the selection value. Note
	// that clients should not specify CurrentTime*.
	err = xproto.ConvertSelectionChecked (
		request.requestor.Window().X.Conn(),
		request.requestor.Window().Id,
		request.source,
		target,
		request.destination,
		// TODO: *possibly replace this zero with an actual timestamp
		// received from the server. this is non-trivial as we cannot
		// rely on the timestamp of the last received event.
		0).Check()
	if err != nil { request.die(err); return }
	
	request.state = switchTo
}

func (request *Request) die (err error) {
	request.requestor.Failure(err)
	request.state = selReqStateClosed
}

func (request *Request) finalize (target Target, reader io.ReadCloser) {
	request.requestor.Success(target, reader)
	request.state = selReqStateClosed
}

func (request *Request) open () bool {
	return request.state != selReqStateClosed
}

// While the selection request is active, HandleSelectionNotify should be called
// when the requesting window recieves a SelectionNotify event. This must be
// registered as an event handler manually.
func (request *Request) HandleSelectionNotify (
	connection *xgbutil.XUtil,
	event xevent.SelectionNotifyEvent,
) {
	// the only valid states that we can process a SelectionNotify event in
	invalidState :=
		request.state != selReqStateAwaitValue &&
		request.state != selReqStateAwaitTargets
	if invalidState { return }
	
	// Follow:
	// https://tronche.com/gui/x/icccm/sec-2.html#s-2.4
	
	// If the property argument is None, the conversion has been refused.
	// This can mean either that there is no owner for the selection, that
	// the owner does not support the conversion implied by the target, or
	// that the server did not have sufficient space to accommodate the
	// data.
	if event.Property == 0 { request.die(nil); return }

	// When using GetProperty to retrieve the value of a selection, the
	// property argument should be set to the corresponding value in the
	// SelectionNotify event. Because the requestor has no way of knowing
	// beforehand what type the selection owner will use, the type argument
	// should be set to AnyPropertyType. Several GetProperty requests may be
	// needed to retrieve all the data in the selection; each should set the
	// long-offset argument to the amount of data received so far, and the
	// size argument to some reasonable buffer size (see section 2.5). If
	// the returned value of bytes-after is zero, the whole property has
	// been transferred.
	reply, err := xproto.GetProperty (
		connection.Conn(), false, request.requestor.Window().Id,
		event.Property, xproto.GetPropertyTypeAny,
		0, (1 << 32) - 1).Reply()
	if err != nil { request.die(err); return }
	if reply.Format == 0 {
		request.die(errors.New("x: missing selection property"))
		return
	}

	// https://tronche.com/gui/x/icccm/sec-2.html#s-2.7.2
	// Requestors may receive a property of type INCR9 in response to any
	// target that results in selection data. This indicates that the owner
	// will send the actual data incrementally. The contents of the INCR
	// property will be an integer, which represents a lower bound on the
	// number of bytes of data in the selection. The requestor and the
	// selection owner transfer the data in the selection in the following
	// manner. The selection requestor starts the transfer process by
	// deleting the (type==INCR) property forming the reply to the
	// selection.
	incr, err := xprop.Atm(request.requestor.Window().X, "INCR")
	if err != nil { request.die(err); return }
	if reply.Type == incr {
		// reply to the INCR selection
		err = xproto.DeletePropertyChecked (
			request.requestor.Window().X.Conn(),
			request.requestor.Window().Id,
			request.destination).Check()
		if err != nil { request.die(err); return }

		// await the first chunk
		request.state = selReqStateAwaitChunk
		return
	}

	// Once all the data in the selection has been retrieved (which may
	// require getting the values of several properties &emdash; see section
	// 2.7), the requestor should delete the property in the SelectionNotify
	// request by using a GetProperty request with the delete argument set
	// to True. As previously discussed, the owner has no way of knowing
	// when the data has been transferred to the requestor unless the
	// property is removed.
	err = xproto.DeletePropertyChecked (
		request.requestor.Window().X.Conn(),
		request.requestor.Window().Id,
		request.destination).Check()
	if err != nil { request.die(err); return }

	// depending on which state the selection request is in, do something
	// different with the property's value
	switch request.state {
	case selReqStateAwaitValue:
		// get the type from the property and convert that to the mime
		// value to pass to the application.
		targetName, err := xprop.AtomName (
			request.requestor.Window().X, reply.Type)
		if err != nil { request.die(err); return }
		
		// we now have the full selection data in the property, so we
		// finalize the request and are done.
		reader := io.NopCloser(bytes.NewReader(reply.Value))
		request.finalize(Target(targetName), reader)
		
	case selReqStateAwaitTargets:
		// make a list of the targets we got
		buffer := reply.Value
		atoms  := make([]xproto.Atom, len(buffer) / 4)
		for index := range atoms {
			atoms[index] = xproto.Atom(xgb.Get32(buffer[index * 4:]))
		}
		targets := make([]Target, len(atoms))
		for index, atom := range atoms {
			targetName, err := xprop.AtomName (
				request.requestor.Window().X, atom)
			if err != nil { request.die(err); return }
			targets[index] = Target(targetName)
		}

		// choose the best target
		var chosenAtom xproto.Atom
		chosenTarget, ok := request.requestor.Choose(targets)
		if ok {
			for index, target := range targets {
				if target == chosenTarget {
					chosenAtom = atoms[index]
				}
			}
		}

		if chosenAtom == 0 {
			request.die(nil)
			return
		}

		// await the selection value
		request.convertSelection(chosenAtom, selReqStateAwaitValue)
	}
}

// While the selection request is active, HandlePropertyNotify should be called
// when the requesting window recieves a PropertyNotify event. This must be
// registered as an event handler manually.
func (request *Request) HandlePropertyNotify (
	connection *xgbutil.XUtil,
	event xevent.PropertyNotifyEvent,
) {
	// the only valid state that we can process a PropertyNotify event in
	if request.state != selReqStateAwaitChunk { return }
	if event.State != xproto.PropertyNewValue { return }

	request.handleINCRProperty(event.Atom)
}

func (request *Request) handleINCRProperty (property xproto.Atom) {
	// Retrieving data using GetProperty with the delete argument True.
	reply, err := xproto.GetProperty (
		request.requestor.Window().X.Conn(), true,
		request.requestor.Window().Id, property, xproto.GetPropertyTypeAny,
		0, (1 << 32) - 1).Reply()
	if err != nil { request.die(err); return }

	if len(reply.Value) == 0 {
		// a zero length property means the transfer has finished. we
		// finalize the request with the data we have, and don't wait
		// for more.
		reader := io.NopCloser(bytes.NewReader(request.incrBuffer))
		request.finalize(request.incrTarget, reader)

		// we want to be extra sure we aren't holding onto this memory
		request.incrBuffer = nil
	} else {
		// a property with content means the transfer is still ongoing.
		// we append the data we got and wait for more.
		request.state = selReqStateAwaitChunk
		request.incrBuffer = append(request.incrBuffer, reply.Value...)
		
		targetName, err := xprop.AtomName (
			request.requestor.Window().X, reply.Type)
		if err != nil { request.die(err); return }
		request.incrTarget = Target(targetName)
	}
}