XIQueryDevice.txt revision 37eb1ca1 
1XIQUERYDEVICE(libmansuffix)
2============================
3
4NAME
5----
6
7   XIQueryDevice, XIFreeDeviceInfo - get information about devices.
8
9SYNOPSIS
10--------
11
12   #include <X11/extensions/XInput2.h>
13
14   XIDeviceInfo* XIQueryDevice( Display *display,
15                                int deviceid,
16                                int *ndevices_return);
17
18   XIFreeDeviceInfo( XIDeviceInfo *info);
19
20   deviceid
21          Specifies the device to query or XIAllDevices or
22          XIAllMasterDevices.
23
24   display
25          Specifies the connection to the X server.
26
27   ndevices_return
28          Returns the number of devices returned.
29
30   info
31          A list of device XIDeviceInfo structs to be freed.
32
33
34DESCRIPTION
35-----------
36
37   The XIQueryDevice returns information about one or more input
38   devices. If the deviceid specifies a device, ndevices_return is
39   1 and the returned information describes only the requested
40   device. If deviceid is XIAllDevices or XIAllMasterDevices,
41   ndevices_return is the number of devices or master devices,
42   respectively, and the returned information represents all
43   devices or all master devices, respectively.
44
45   To free the XIDeviceInfo array returned by XIQueryDevice, use
46   XIFreeDeviceInfo.
47
48   For each input device requested, the XIQueryDevice returns an
49   XIDeviceInfo structure. Each structure contains information
50   about the capabilities of one input device available to the
51   server.
52
53                typedef struct
54                {
55                    int                 deviceid;
56                    char                *name;
57                    int                 use;
58                    int                 attachment;
59                    Bool                enabled;
60                    int                 num_classes;
61                    XIAnyClassInfo      **classes;
62                } XIDeviceInfo;
63
64   The deviceid is the numeric unique id of the device. A deviceid
65   is unique for the life-time of a device but a server may re-use
66   the id once a device has been removed.
67
68   The name points to a null-terminated string specifying the
69   identifier of the device.
70
71   The use and attachment fields specify the type of the device
72   and the current attachment or pairing.
73   - If use is XIMasterPointer, the device is a master pointer and
74     attachment specifies the deviceid of the paired master
75     keyboard.
76   - If use is XIMasterKeyboard, the device is a master keyboard,
77     and the attachment field specifies the paired master pointer.
78   - If use is XISlavePointer, the device is a slave device and
79     currently attached to the master pointer specified in
80     attachement.
81   - If use is XISlaveKeyboard, the device is a slave device an
82     currently attached to the master keyboard specified in
83     attachment.
84   - If use is XIFloatingSlave, the device is a slave device
85     currently not attached to any master device. The value of the
86     attachment field for floating slave devices is undefined.
87
88   The enabled field specifies if the device is currently enabled
89   and can send events. Disabled devices will not send events.
90
91   The num_classes field specifies the number of input classes
92   pointed to by classes. The first two fields of all input
93   classes are identical.
94
95                typedef struct
96                {
97                    int         type;
98                    int         sourceid;
99                } XIAnyClassInfo;
100
101   The type field specifies the type of the input class.
102   Currently, the following types are defined:
103       XIKeyClass, XIButtonClass, XIValuatorClass
104
105   In the future, additional types may be added. Clients are
106   required to ignore unknown input classes.
107
108   The sourceid is the deviceid this class originated from. For
109   master devices, the sourceid is typically the id of the slave
110   device currently sending events. For slave devices, the
111   sourceid is typically the device's id.
112
113   A device may have zero or one XIButtonClass, denoting the
114   device's capability to send button events.
115
116               typedef struct {
117                   int           mask_len;
118                   unsigned char *mask;
119               } XIButtonState;
120
121               typedef struct
122               {
123                   int         type;
124                   int         sourceid;
125                   int         num_buttons;
126                   Atom        *labels;
127                   XIButtonState state;
128               } XIButtonClassInfo;
129
130   The num_buttons field specifies the number of buttons available
131   on this device. A device that has an XIButtonClass must have at
132   least one button.
133
134   labels is a list of num_buttons Atoms specifying the button
135   labels for this device. If the label is not None, then the
136   label specifies the type of button in physical device order
137   (i.e. as the buttons are numbered on the physical input
138   device).
139
140   The state is the current button state as seen by clients (i.e.
141   after button mapping is applied). The mask_len field specifies
142   the length of mask in bytes. For each button on the device, the
143   respective bit in mask is set if the button is currently
144   logically down.
145
146   A device may have zero or one XIKeyClass, denoting the device's
147   capability to send key events.
148
149               typedef struct
150               {
151                   int         type;
152                   int         sourceid;
153                   int         num_keycodes;
154                   int         *keycodes;
155               } XIKeyClassInfo;
156
157   The num_keycodes field specifies the number of keycodes
158   available on this device. A device that has an XIKeyClass must
159   have at least one keycode.
160
161   keycodes is a list of num_keycodes keycodes the device may
162   send.
163
164   A device may have zero or more XIValuatorClass, denoting the
165   device's capability to send coordinates.
166
167               typedef struct
168               {
169                   int         type;
170                   int         sourceid;
171                   int         number;
172                   Atom        label;
173                   double      min;
174                   double      max;
175                   double      value;
176                   int         resolution;
177                   int         mode;
178               } XIValuatorInfo;
179
180   The number field specifies the number of the axis on the
181   physical device.
182
183   If the label field is not None, the value of label is an Atom
184   describing the axis.
185
186   min and max are the minimum and maximum values allowed on this
187   axis. If both are zero, no minumum or maximum values are set on
188   this device. value is the current value of this axis.
189
190   The resolution field specifies the resolution of the device in
191   units/m.
192
193   The mode specifies the mode of this axis. If the mode is
194   XIModeAbsolute this axis sends absolute coordinates. If the
195   mode is XIModeRelative, this device sends relative coordinates.
196
197   XIQueryDevice can generate a BadDevice error.
198
199   XIFreeDeviceInfo frees the information returned by
200   XIQueryDevice.
201
202DIAGNOSTICS
203-----------
204
205   BadDevice
206          An invalid device was specified. The device does not
207          exist or is not a pointer device.
208
209