1XICHANGEPROPERTY(3)                                        XICHANGEPROPERTY(3)
2
3
4

NAME

6       XIChangeProperty, XIGetProperty, XIDeleteProperty - change, retrieve or
7       delete a device's property.
8

SYNOPSIS

10       #include <X11/extensions/XInput2.h>
11
12       void XIChangeProperty( Display* dpy,
13                              int deviceid,
14                              Atom property,
15                              Atom type,
16                              int format,
17                              int mode,
18                              unsigned char *data,
19                              int num_items)
20
21       void XIDeleteProperty( Display *dpy,
22                              int deviceid,
23                              Atom property)
24
25       Status XIGetProperty( Display *dpy,
26                             int deviceid,
27                             Atom property,
28                             long offset,
29                             long length,
30                             Bool delete_property,
31                             Atom type,
32                             Atom *type_return,
33                             int *format_return,
34                             unsigned long *num_items_return,
35                             unsigned long *bytes_after_return,
36                             unsigned char **data)
37
38       bytes_after_return
39              Returns the number of bytes remaining to be read in the prop-
40              erty if a partial read was performed.
41
42       data
43              Specifies the property data.
44
45       display
46              Specifies the connection to the X server.
47
48       delete_property
49              Specifies a Boolean value that determines whether the property
50              is to be deleted.
51
52       deviceid
53              The device to list the properties for.
54
55       format
56              Specifies whether the data should be viewed as a list of
57              8-bit, 16-bit, or 32-bit quantities.  Possible values are 8,
58              16, and 32.  This information allows the X server to correctly
59              perform byte-swap operations as necessary. If the
60              format is 16-bit or 32-bit, you must explicitly cast your
61              data pointer to an (unsigned char *) in the call to
62              XIChangeProperty.
63
64       format_return
65              Returns the actual format of the property.
66
67       length
68              Specifies the length in 32-bit multiples of the data to be
69              retrieved.
70
71       offset
72              Specifies the offset in the specified property (in 32-bit
73              quantities) where the data is to be retrieved.
74
75       mode
76              One of XIPropModeAppend, XIPropModePrepend or XIPropModeReplace.
77
78       num_items
79              Number of items in data in the format specified.
80
81       nitems_return
82              Returns the actual number of 8-bit, 16-bit, or 32-bit items
83              stored in data.
84
85       property
86              Specifies the property name.
87
88       type
89              Specifies the type of the property.  The X server does not
90              interpret the type but simply passes it back to an application
91              that later calls XIGetProperty.
92
93       type_return
94              Returns the atom identifier that defines the actual type of
95              the property.
96

DESCRIPTION

98       The XIGetProperty function returns the actual type of the property; the
99       actual format of the property; the number of 8-bit, 16-bit, or 32-bit
100       items transferred; the number of bytes remaining to be read in the
101       property; and a pointer to the data actually returned. XIGetProperty
102       sets the return arguments as follows:
103
104       ·   If the specified property does not exist for the specified device,
105           XIGetProperty returns None to actual_type_return and the value zero
106           to actual_format_return and bytes_after_return. The nitems_return
107           argument is empty. In this case, the delete argument is ignored.
108
109       ·   If the specified property exists but its type does not match the
110           specified type, XIGetProperty returns the actual property type to
111           actual_type_return, the actual property format (never zero) to
112           actual_format_return, and the property length in bytes (even if the
113           actual_format_return is 16 or 32) to bytes_after_return. It also
114           ignores the delete argument. The nitems_return argument is empty.
115
116       ·   If the specified property exists and either you assign
117           XIAnyPropertyType to the req_type argument or the specified type
118           matches the actual property type, XIGetProperty returns the actual
119           property type to actual_type_return and the actual property format
120           (never zero) to actual_format_return. It also returns a value to
121           bytes_after_return and nitems_return, by defining the following
122           values:
123
124               N = length of the stored property in bytes
125               I = 4 * offset
126               T = N - I
127               L = MINIMUM(T, 4 * length)
128               A = N - (I + L)
129
130       The returned value starts at byte index I in the property (indexing
131       from zero), and its length in bytes is L. If the value for long_offset
132       causes L to be negative, a BadValue error results. The value of
133       bytes_after_return is A, giving the number of trailing unread bytes in
134       the stored property.
135
136       If the returned format is 8, the returned data is represented as a char
137       array. If the returned format is 16, the returned data is represented
138       as a uint16_t array and should be cast to that type to obtain the ele-
139       ments. If the returned format is 32, the returned data is represented
140       as a uint32_t array and should be cast to that type to obtain the
141       elements.
142
143       XIGetProperty always allocates one extra byte in prop_return (even if
144       the property is zero length) and sets it to zero so that simple
145       properties consisting of characters do not have to be copied into yet
146       another string before use.
147
148       If delete is True and bytes_after_return is zero, XIGetProperty deletes
149       the property from the window and generates an XIPropertyNotify event on
150       the window.
151
152       The function returns Success if it executes successfully. To free the
153       resulting data, use XFree.
154
155       XIGetProperty can generate BadAtom, BadValue, and BadWindow errors.
156
157       The XIChangeProperty function alters the property for the specified
158       device and causes the X server to generate a XIPropertyNotify event for
159       that device. XIChangeProperty performs the following:
160
161       ·   If mode is XIPropModeReplace, XIChangeProperty discards the
162           previous property value and stores the new data.
163
164       ·   If mode is XIPropModePrepend or XIPropModeAppend, XIChangeProperty
165           inserts the specified data before the beginning of the existing
166           data or onto the end of the existing data, respectively. The type
167           and format must match the existing property value, or a BadMatch
168           error results. If the property is undefined, it is treated as
169           defined with the correct type and format with zero-length data.
170
171       If the specified format is 8, the property data must be a char array.
172       If the specified format is 16, the property data must be a uint16_t
173       array. If the specified format is 32, the property data must be a
174       uint32_t array.
175
176       The lifetime of a property is not tied to the storing client.
177       Properties remain until explicitly deleted, until the device is
178       removed, or until the server resets. The maximum size of a property is
179       server dependent and can vary dynamically depending on the amount of
180       memory the server has available. (If there is insufficient space, a
181       BadAlloc error results.)
182
183       XIChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue,
184       and BadDevice errors.
185
186       The XIDeleteProperty function deletes the specified property only if
187       the property was defined on the specified device and causes the X
188       server to generate a XIPropertyNotify event for the device unless the
189       property does not exist.
190
191       XIDeleteProperty can generate BadAtom and BadDevice errors.
192

DIAGNOSTICS

194       BadAlloc The server failed to allocate the requested resource or server
195       memory.
196
197       BadAtom A value for an Atom argument does not name a defined Atom.
198
199       BadValue Some numeric value falls outside the range of values accepted
200       by the request. Unless a specific range is specified for an argument,
201       the full range defined by the argument’s type is accepted. Any argument
202       defined as a set of alternatives can generate this error.
203
204       BadDevice An invalid device was specified. The device does not exist.
205
206       BadAtom An invalid property was specified. The property does not exist.
207

BUGS

209           The protocol headers for XI 2.0 did not provide
210           XIAnyPropertyType, XIPropModeReplace, XIPropModePrepend or
211           XIPropModeAppend. Use AnyPropertyType, PropModeReplace,
212           PropModePrepend and PropModeAppend instead, respectively.
213

SEE ALSO

215       XIListProperties(3)
216
217
218
219                                  03/09/2013               XICHANGEPROPERTY(3)
Impressum