Product SiteDocumentation Site

4.13. Data sharing between clients

The Wayland protocol provides clients a mechanism for sharing data that allows the implementation of copy-paste and drag-and-drop. The client providing the data creates a wl_data_source object and the clients obtaining the data will see it as wl_data_offer object. This interface allows the clients to agree on a mutually supported mime type and transfer the data via a file descriptor that is passed through the protocol.
The next section explains the negotiation between data source and data offer objects. Section 4.13.2, “Data devices” explains how these objects are created and passed to different clients using the wl_data_device interface that implements copy-paste and drag-and-drop support.
See Section A.8, “wl_data_offer - offer to transfer data”, Section A.9, “wl_data_source - offer to transfer data”, Section A.10, “wl_data_device - data transfer device” and Section A.11, “wl_data_device_manager - data transfer interface” for protocol descriptions.
MIME is defined in RFC's 2045-2049. A registry of MIME types is maintained by the Internet Assigned Numbers Authority (IANA).

4.13.1. Data negotiation

A client providing data to other clients will create a wl_data_source object and advertise the mime types for the formats it supports for that data through the wl_data_source.offer request. On the receiving end, the data offer object will generate one wl_data_offer.offer event for each supported mime type.
The actual data transfer happens when the receiving client sends a wl_data_offer.receive request. This request takes a mime type and a file descriptor as arguments. This request will generate a wl_data_source.send event on the sending client with the same arguments, and the latter client is expected to write its data to the given file descriptor using the chosen mime type.

4.13.2. Data devices

Data devices glue data sources and offers together. A data device is associated with a wl_seat and is obtained by the clients using the wl_data_device_manager factory object, which is also responsible for creating data sources.
Clients are informed of new data offers through the wl_data_device.data_offer event. After this event is generated the data offer will advertise the available mime types. New data offers are introduced prior to their use for copy-paste or drag-and-drop.

4.13.2.1. Selection

Each data device has a selection data source. Clients create a data source object using the device manager and may set it as the current selection for a given data device. Whenever the current selection changes, the client with keyboard focus receives a wl_data_device.selection event. This event is also generated on a client immediately before it receives keyboard focus.
The data offer is introduced with wl_data_device.data_offer event before the selection event.

4.13.2.2. Drag and Drop

A drag-and-drop operation is started using the wl_data_device.start_drag request. This requests causes a pointer grab that will generate enter, motion and leave events on the data device. A data source is supplied as argument to start_drag, and data offers associated with it are supplied to clients surfaces under the pointer in the wl_data_device.enter event. The data offer is introduced to the client prior to the enter event with the wl_data_device.data_offer event.
Clients are expected to provide feedback to the data sending client by calling the wl_data_offer.accept request with a mime type it accepts. If none of the advertised mime types is supported by the receiving client, it should supply NULL to the accept request. The accept request causes the sending client to receive a wl_data_source.target event with the chosen mime type.
When the drag ends, the receiving client receives a wl_data_device.drop event at which it is expected to transfer the data using the wl_data_offer.receive request.