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