I am sponsoring this case for myself and closing it as approved automatic
as it simply tracks the community addition of new protocol requests & events
to the existing Input extension to the X protocol, and the corresponding
API additions to the libXi library.
This case requests a Micro/Patch binding, though no patch backport is
currently planned.
-Alan Coopersmith- alan.coopersmith at sun.com
Sun Microsystems, Inc. - X Window System Engineering
Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
X Input Extension 1.5
1.2. Name of Document Author/Supplier:
Author: Alan Coopersmith
1.3 Date of This Document:
14 May, 2009
4. Technical Description
This case updates the definition of the X Input Extension (XI)
protocol used in Solaris & OpenSolaris from version 1.4 to version 1.5
of the spec from the X.Org Foundation. The additional API adds
support for properties on input devices to be queried and set by
clients, following the design pattern used by the existing support for
output device properties added in RandR 1.2 and the long standing
window properties of the core X11 protocol.
Properties may be read-only to clients, allowing drivers to provide
additional information about their state, or may be writable by clients,
allowing clients to change device configuration at runtime without
requiring editing xorg.conf and restarting the X server. Clients may
also create their own properties to provide information about devices
to other clients. Properties created by clients will be flagged as such
to prevent spoofing device-created properties and to allow clients to know
that changes to such properties are likely ignored by the server/device.
It additionally updates the libXi client API from version 1.1 to
version 1.2 to provide the matching support for device properties.
Support for Input version 1.5 in the Xorg server will be handled by
the Xorg server 1.6 case (PSARC 2009/292).
The new protocol requests & event are defined by these excerpts from
the Xinput protocol specification:
Listing Device Properties
Introduced with XI 1.5
ListDeviceProperties
deviceid: CARD8
=>
nAtoms: CARD16
Atoms: LISTofATOM
Errors: Device
Each device can store an arbitrary number of properties. These
properties can be allocated by either the client or the
driver. The client can change device properties and the server
guarantees that the device driver is notified about a change
of the device's properties.
ListDeviceProperties returns all properties of a device. The
client is expected to retrieve details about the properties it
is interested in separately.
Getting a Device Property
Introduced with XI 1.5
GetDeviceProperty:
property: ATOM
type: ATOM
longOffset: CARD32
longLength: CARD32
deviceid: CARD8
delete: BOOL
=>
propertyType: ATOM
bytesAfter: CARD32
nItems: CARD32
format: CARD8
deviceid: CARD8
data: [LISTofCARD8]
Errors: Atom, Device, Value, Access
Retrieve the value for a property. If the property does not
exist, propertyType is None and all other fields are
undefined.
If type is not AnyPropertyType and does not match the
property's actual type, the propertyType, bytesAfter, and
format are returned but not the actual data.
longOffset and longLength specify the offset and length
respectively in 32-bit multiples of the data to retrieve.
If delete is True, the property is deleted after querying its
data. If the property cannot be deleted, a BadAccess error is
returned.
propertyType returns the atom identifier that defines the
actual type of the property.
If bytesAfter is non-zero, it specifies the number of data
4-byte units after the retrieved chunk of data.
format specifies whether the data should be viewed as a list
of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8,
16, and 32. This information allows the X server to correctly
perform byte-swap operations as necessary.
nItem specifies the number of 8-bit, 16-bit, or 32-bit items
returned after the request.
Changing a Device Property
Introduced with XI 1.5
ChangeDeviceProperty:
property: ATOM
type: ATOM
deviceid: CARD8
format: CARD8
mode: CARD8
nUnits: CARD32
Errors: Atom, Device, Value, Match, Access
Changes the value of a specified property.
The type specifies the atom identifier that defines the type
of the property. If mode is not PropModeReplace, the type
must match the current type of the property or a BadMatch
error is returned.
format specifies whether the data should be viewed as a list
of 8-bit, 16-bit, or 32-bit quantities. Possible values are 8,
16, and 32. This information allows the X server to correctly
perform byte-swap operations as necessary.
If mode is PropModeReplace, a preexising value for this
property is replaced with the new value. If mode is
PropModePrepend or PropModeAppend, the value is prepended or
appended, respectively, to the current value of the property.
nUnits specifies the number of 8-bit, 16-bit, or 32-bit items
supplied after the reply.
Changing a device property results in a
DevicePropertyNotifyEvent being sent to all clients.
Deleting a Device Property
Introduced with XI 1.5
DeleteDeviceProperty:
property: ATOM
deviceid: CARD8
Errors: Atom, Device, Match, Access.
Deletes the specified property. If the property cannot be
deleted by the client, a BadAccess error is returned.
DevicePropertyNotifyEvent
Introduced with XI 1.5
DevicePropertyNotifyEvent
deviceid: CARD8
state: CARD8
time: TIMESTAMP
atom: ATOM
A DevicePropertyNotifyEvent is sent to all clients when a
property on the device is created, deleted, or changes value.
The deviceid specifies the device which's property has been modified.
The atom specifies the named identifier of the property that
has been altered.
If state is PropertyNewValue, the given property has a new
value or has been newly created. If state is PropertyDeleted,
the given property has been deleted.
The new API functions mirror these requests - they are:
#include <X11/extensions/XInput.h>
Atom* XListDeviceProperties(Display *display,
XDevice *device,
int *nprops_return);
int XGetDeviceProperty(Display *display, XDevice *device,
Atom property, long offset,
long length, Bool delete,
Bool pending, Atom req_type,
Atom *actual_type_return,
int *actual_format_return,
unsigned long *nitems_return,
unsigned long *bytes_after_return,
unsigned char **prop_return);
void XChangeDeviceProperty(Display *display,
XDevice *device, Atom property,
Atom type, int format, int mode,
const char *data, int nelements);
void XDeleteDeviceProperty(Display *display,
XDevice *device, Atom property);
The man pages defining these are provided in the case materials.
Like window properties and output device properties, these add another
avenue for clients to communicate information between processes. The
Trusted Extensions team has been informed of this addition to evaluate
whether additional policy will be needed for property access in
labeled zones, similar to the existing window property policies.
Imported Interfaces:
--------------------
libXi.so.5 Standard PSARC 1992/172
<X11/extensions/XInput.h> Standard PSARC 1992/172
Xinput extension protocol Standard PSARC 1992/172
Exported Interfaces:
--------------------
libXi.so.5 version SUNW_1.3 Committed [1]
including all 4 API's listed above
Xinput extension protocol version 1.5 Committed see above
References in case materials directory:
[1] XListDeviceProperties.man, XGetDeviceProperty.man
(XChangeDeviceProperty & XDeleteDeviceProperty are covered in
XGetDeviceProperty.man)
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
X Consolidation (Desktop C-Team)
6.5. ARC review type: Automatic
6.6. ARC Exposure: open
