Device Properties Protocol Spec - Draft 1

[Peter Hutterer]

As you are possibly aware, I'm trying to push device properties into a new
X Input version 1.5. We have a working implementation in the server right now,
it basically needs to be released. However, after XDS and more review, I'd
like to cull it a bit to make it simpler.

Requests:
- ListDeviceProperties
- GetDeviceProperty
- ChangeDeviceProperty
- DeleteDeviceProperty

Events:
- DevicePropertyNotify

Full description below.

The difference to the current implementation is that there is no
meta-information about the property. This information included immutable,
client-created, range and pending. I deem all four as too much information.

If such information is required in the future, such requests can be added
easily in future versions of XInput.

Comments MUCH appreciated.

If this spec is accepted, I will adjust inputproto, libXi and the server
accordingly and release them.

Cheers,
  Peter

-----------------------------------------------------------------------------

Listing Device Properties

            ListDeviceProperties
                     deviceid: CARD8
            =>
                     nAtoms: CARD16
                     Atoms: LISTofATOM
            

Errors: Device

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


            GetDeviceProperty:
                     property: ATOM
                     type: ATOM
                     longOffset: CARD32
                     longLength: CARD32
                     deviceid: CARD8
                     delete: BOOL
            =>
                     propertyType: ATOM
                     bytesAfter: CARD32
                     nItems: CARD32
                     format: CARD8
                     data: [LISTofCARD8]
            

Errors: Atom, Device, Value

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. A length of 0 is valid.

If delete is True, the property is deleted after querying its data.

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 secifies 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

            ChangeDeviceProperty:
                     property: ATOM
                     type: ATOM
                     deviceid: CARD8
                     format: CARD8
                     mode: CARD8
                     nUnits: CARD32
            

Errors: Atom, Device, Value, Match

Changes the 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 secifies 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

            DeleteDeviceProperty:
                     property: ATOM
                     deviceid: CARD8
            

Errors: Atom, Device, Value, Match

Deletes the specified property.

-----------------------------------------------------------------------------

PropertyEvents

            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.