From alanc@sac.sfbay.sun.com Thu May 14 17:18:32 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4F0IVOW016022 for ; Thu, 14 May 2009 17:18:32 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4F0IRlW018852; Fri, 15 May 2009 01:18:29 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJN00507SUSYB00@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 18:18:28 -0600 (MDT) Received: from dm-sfbay-01.sfbay.sun.com ([129.145.155.118]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJN00KIKSURJU40@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 18:18:27 -0600 (MDT) Received: from sac.sfbay.sun.com (sac.SFBay.Sun.COM [129.146.226.132]) by dm-sfbay-01.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4F0IR2b026293; Thu, 14 May 2009 17:18:27 -0700 (PDT) Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4F0IQ6o015990; Thu, 14 May 2009 17:18:26 -0700 (PDT) Received: (from alanc@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id n4F0IQea015986; Thu, 14 May 2009 17:18:26 -0700 (PDT) Date: Thu, 14 May 2009 17:18:26 -0700 (PDT) From: Alan Coopersmith Subject: X Input Extension 1.5 [PSARC/2009/303 Self Review] To: PSARC-ext@sun.com Cc: xwin-discuss@opensolaris.org Message-id: <200905150018.n4F0IQea015986@sac.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 9088 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@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 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 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