1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wlr_data_control_unstable_v1">
3 <copyright>
4 Copyright © 2018 Simon Ser
5 Copyright © 2019 Ivan Molodetskikh
6
7 Permission to use, copy, modify, distribute, and sell this
8 software and its documentation for any purpose is hereby granted
9 without fee, provided that the above copyright notice appear in
10 all copies and that both that copyright notice and this permission
11 notice appear in supporting documentation, and that the name of
12 the copyright holders not be used in advertising or publicity
13 pertaining to distribution of the software without specific,
14 written prior permission. The copyright holders make no
15 representations about the suitability of this software for any
16 purpose. It is provided "as is" without express or implied
17 warranty.
18
19 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
20 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
21 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
22 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
23 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
24 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
25 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
26 THIS SOFTWARE.
27 </copyright>
28
29 <description summary="control data devices">
30 This protocol allows a privileged client to control data devices. In
31 particular, the client will be able to manage the current selection and take
32 the role of a clipboard manager.
33
34 Warning! The protocol described in this file is experimental and
35 backward incompatible changes may be made. Backward compatible changes
36 may be added together with the corresponding interface version bump.
37 Backward incompatible changes are done by bumping the version number in
38 the protocol and interface names and resetting the interface version.
39 Once the protocol is to be declared stable, the 'z' prefix and the
40 version number in the protocol and interface names are removed and the
41 interface version number is reset.
42
43 Note! This protocol is deprecated and not intended for production use.
44 For clipboard management, use the ext-data-control-v1 protocol.
45 </description>
46
47 <interface name="zwlr_data_control_manager_v1" version="2">
48 <description summary="manager to control data devices">
49 This interface is a manager that allows creating per-seat data device
50 controls.
51 </description>
52
53 <request name="create_data_source">
54 <description summary="create a new data source">
55 Create a new data source.
56 </description>
57 <arg name="id" type="new_id" interface="zwlr_data_control_source_v1"
58 summary="data source to create"/>
59 </request>
60
61 <request name="get_data_device">
62 <description summary="get a data device for a seat">
63 Create a data device that can be used to manage a seat's selection.
64 </description>
65 <arg name="id" type="new_id" interface="zwlr_data_control_device_v1"/>
66 <arg name="seat" type="object" interface="wl_seat"/>
67 </request>
68
69 <request name="destroy" type="destructor">
70 <description summary="destroy the manager">
71 All objects created by the manager will still remain valid, until their
72 appropriate destroy request has been called.
73 </description>
74 </request>
75 </interface>
76
77 <interface name="zwlr_data_control_device_v1" version="2">
78 <description summary="manage a data device for a seat">
79 This interface allows a client to manage a seat's selection.
80
81 When the seat is destroyed, this object becomes inert.
82 </description>
83
84 <request name="set_selection">
85 <description summary="copy data to the selection">
86 This request asks the compositor to set the selection to the data from
87 the source on behalf of the client.
88
89 The given source may not be used in any further set_selection or
90 set_primary_selection requests. Attempting to use a previously used
91 source is a protocol error.
92
93 To unset the selection, set the source to NULL.
94 </description>
95 <arg name="source" type="object" interface="zwlr_data_control_source_v1"
96 allow-null="true"/>
97 </request>
98
99 <request name="destroy" type="destructor">
100 <description summary="destroy this data device">
101 Destroys the data device object.
102 </description>
103 </request>
104
105 <event name="data_offer">
106 <description summary="introduce a new wlr_data_control_offer">
107 The data_offer event introduces a new wlr_data_control_offer object,
108 which will subsequently be used in either the
109 wlr_data_control_device.selection event (for the regular clipboard
110 selections) or the wlr_data_control_device.primary_selection event (for
111 the primary clipboard selections). Immediately following the
112 wlr_data_control_device.data_offer event, the new data_offer object
113 will send out wlr_data_control_offer.offer events to describe the MIME
114 types it offers.
115 </description>
116 <arg name="id" type="new_id" interface="zwlr_data_control_offer_v1"/>
117 </event>
118
119 <event name="selection">
120 <description summary="advertise new selection">
121 The selection event is sent out to notify the client of a new
122 wlr_data_control_offer for the selection for this device. The
123 wlr_data_control_device.data_offer and the wlr_data_control_offer.offer
124 events are sent out immediately before this event to introduce the data
125 offer object. The selection event is sent to a client when a new
126 selection is set. The wlr_data_control_offer is valid until a new
127 wlr_data_control_offer or NULL is received. The client must destroy the
128 previous selection wlr_data_control_offer, if any, upon receiving this
129 event.
130
131 The first selection event is sent upon binding the
132 wlr_data_control_device object.
133 </description>
134 <arg name="id" type="object" interface="zwlr_data_control_offer_v1"
135 allow-null="true"/>
136 </event>
137
138 <event name="finished">
139 <description summary="this data control is no longer valid">
140 This data control object is no longer valid and should be destroyed by
141 the client.
142 </description>
143 </event>
144
145 <!-- Version 2 additions -->
146
147 <event name="primary_selection" since="2">
148 <description summary="advertise new primary selection">
149 The primary_selection event is sent out to notify the client of a new
150 wlr_data_control_offer for the primary selection for this device. The
151 wlr_data_control_device.data_offer and the wlr_data_control_offer.offer
152 events are sent out immediately before this event to introduce the data
153 offer object. The primary_selection event is sent to a client when a
154 new primary selection is set. The wlr_data_control_offer is valid until
155 a new wlr_data_control_offer or NULL is received. The client must
156 destroy the previous primary selection wlr_data_control_offer, if any,
157 upon receiving this event.
158
159 If the compositor supports primary selection, the first
160 primary_selection event is sent upon binding the
161 wlr_data_control_device object.
162 </description>
163 <arg name="id" type="object" interface="zwlr_data_control_offer_v1"
164 allow-null="true"/>
165 </event>
166
167 <request name="set_primary_selection" since="2">
168 <description summary="copy data to the primary selection">
169 This request asks the compositor to set the primary selection to the
170 data from the source on behalf of the client.
171
172 The given source may not be used in any further set_selection or
173 set_primary_selection requests. Attempting to use a previously used
174 source is a protocol error.
175
176 To unset the primary selection, set the source to NULL.
177
178 The compositor will ignore this request if it does not support primary
179 selection.
180 </description>
181 <arg name="source" type="object" interface="zwlr_data_control_source_v1"
182 allow-null="true"/>
183 </request>
184
185 <enum name="error" since="2">
186 <entry name="used_source" value="1"
187 summary="source given to set_selection or set_primary_selection was already used before"/>
188 </enum>
189 </interface>
190
191 <interface name="zwlr_data_control_source_v1" version="1">
192 <description summary="offer to transfer data">
193 The wlr_data_control_source object is the source side of a
194 wlr_data_control_offer. It is created by the source client in a data
195 transfer and provides a way to describe the offered data and a way to
196 respond to requests to transfer the data.
197 </description>
198
199 <enum name="error">
200 <entry name="invalid_offer" value="1"
201 summary="offer sent after wlr_data_control_device.set_selection"/>
202 </enum>
203
204 <request name="offer">
205 <description summary="add an offered MIME type">
206 This request adds a MIME type to the set of MIME types advertised to
207 targets. Can be called several times to offer multiple types.
208
209 Calling this after wlr_data_control_device.set_selection is a protocol
210 error.
211 </description>
212 <arg name="mime_type" type="string"
213 summary="MIME type offered by the data source"/>
214 </request>
215
216 <request name="destroy" type="destructor">
217 <description summary="destroy this source">
218 Destroys the data source object.
219 </description>
220 </request>
221
222 <event name="send">
223 <description summary="send the data">
224 Request for data from the client. Send the data as the specified MIME
225 type over the passed file descriptor, then close it.
226 </description>
227 <arg name="mime_type" type="string" summary="MIME type for the data"/>
228 <arg name="fd" type="fd" summary="file descriptor for the data"/>
229 </event>
230
231 <event name="cancelled">
232 <description summary="selection was cancelled">
233 This data source is no longer valid. The data source has been replaced
234 by another data source.
235
236 The client should clean up and destroy this data source.
237 </description>
238 </event>
239 </interface>
240
241 <interface name="zwlr_data_control_offer_v1" version="1">
242 <description summary="offer to transfer data">
243 A wlr_data_control_offer represents a piece of data offered for transfer
244 by another client (the source client). The offer describes the different
245 MIME types that the data can be converted to and provides the mechanism
246 for transferring the data directly from the source client.
247 </description>
248
249 <request name="receive">
250 <description summary="request that the data is transferred">
251 To transfer the offered data, the client issues this request and
252 indicates the MIME type it wants to receive. The transfer happens
253 through the passed file descriptor (typically created with the pipe
254 system call). The source client writes the data in the MIME type
255 representation requested and then closes the file descriptor.
256
257 The receiving client reads from the read end of the pipe until EOF and
258 then closes its end, at which point the transfer is complete.
259
260 This request may happen multiple times for different MIME types.
261 </description>
262 <arg name="mime_type" type="string"
263 summary="MIME type desired by receiver"/>
264 <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
265 </request>
266
267 <request name="destroy" type="destructor">
268 <description summary="destroy this offer">
269 Destroys the data offer object.
270 </description>
271 </request>
272
273 <event name="offer">
274 <description summary="advertise offered MIME type">
275 Sent immediately after creating the wlr_data_control_offer object.
276 One event per offered MIME type.
277 </description>
278 <arg name="mime_type" type="string" summary="offered MIME type"/>
279 </event>
280 </interface>
281</protocol>