Clipboard device

This specification describes the clipboard device of the Bedrock computer system.

The clipboard device provides access to two system clipboards and the ability to drag data between programs.

Ports

Read entry

Each read entry port is associated with a clipboard.

Writing a value to a read entry port will remove all bytes from the read queue of the associated clipboard, and then will read the current entry on the clipboard into that queue. If a zero value was written, a binary entry will be read. If a non-zero value was written, a text entry will be read. If the clipboard does not contain an entry of the correct type, no entry will be read.

Write entry

Each write entry port is associated with a clipboard.

Writing a value to a write entry port will remove the current entry from the associated clipboard, then will write the contents of the associated write queue to the clipboard, and then will remove all bytes from that queue. If a zero value was written, the contents of the queue will be written as a binary entry. If a non-zero value was written, the contents of the queue will be written as a text entry.

Read length

Each read length port is associated with a clipboard.

Reading from a read length port will return the number of bytes waiting in the read queue of the associated clipboard. If the queue contains more than 255 bytes, the value 0xFF will be returned.

Write length

Each write length port is associated with a clipboard.

Reading from a write length port will return the number of bytes of free space in the write queue of the associated clipboard. If the queue has space for more than 255 additional bytes, the value 0xFF will be returned.

Writing to a write length port will remove all bytes from the write queue of the associated clipboard.

Head

Each head port is associated with a clipboard.

Reading from a head port will remove and return a byte from the front of the read queue of the associated clipboard. If the queue is empty, the value zero will be returned.

Writing a byte to a head port will push that byte to the back of the write queue of the associated clipboard. No byte will be pushed if the queue is full.

Drag entry

Reading from this port will return 0xFF if the entry on the secondary clipboard is currently being dragged over this system, otherwise it will return zero.

Writing a non-zero byte to this port will set the drag flag, indicating that the entry on the secondary clipboard is current being dragged by this system.

Writing a zero byte to this port will indicate that the entry on the secondary clipboard is no longer being dragged by this system.

Drop entry

Reading from this port will return 0xFF if the drop flag is set, otherwise it will return zero, and then the flag will be cleared.

Writing a byte to this port will indicate that the entry on the secondary clipboard has been dropped by this system, and then the drag flag will be cleared.

Data structures

Clipboard

A clipboard is a shared data structure that can contain at most one binary entry and at most one text entry.

Each clipboard contains two buffer queues, a read queue and a write queue. The read queue is used to read an entry from the clipboard, and the write queue is used to write an entry to the clipboard.

This device contains two clipboards: the primary clipboard, controlled by the first eight ports, and the secondary clipboard, controlled by the last eight.

Buffer queue

A buffer queue is a first-in first-out byte queue used to buffer clipboard data for reading or writing. The length of each queue is implementation defined.

If a queue is full, all new bytes will be dropped.

Primary clipboard

The primary clipboard is used for data that the user has explicitly requested to be copied.

Secondary clipboard

The secondary clipboard is used for data that the user has implicitly requested to be copied, such as by selecting text or by dropping a file.

Binary entry

A binary entry is a sequence of zero or more bytes. The maximum size of a binary entry is implementation defined.

Text entry

A text entry is a sequence of zero or more bytes representing a UTF-8 encoded string. The maximum size of a text entry is implementation defined.

The behaviour when a text entry does not contain a valid UTF-8 encoded string is undefined.

Drag flag

The drag flag is a flag that indicates that the entry on the secondary clipboard is currently being dragged by this system. The initial state of this flag is cleared.

Drop flag

The drop flag is a flag that indicates that the entry on the secondary clipboard has just been dropped on this system. The initial state of this flag is cleared.

When an entry is dropped on this system, the drop flag will be set. When an entry is dragged over this system, the drop flag will be cleared.

Implementation

Dropping files

Dropping a file will drop a text entry containing the Bedrock path of that file (as per the File device specification), and not the contents of the file itself. If the file cannot be represented as a Bedrock path, such as when a file is not a descendant of the root directory of the Bedrock file system, no entry will be dropped.

Dropping multiple files will drop a text entry containing a concatenated list of the Bedrock paths of those files, with every path but the last followed by the newline character 0x0A. Unrepresentable files will be omitted.

If the file device is sandboxed, dropped paths will need to be translated to be valid from the sandboxed root.

Selecting data

When the user selects data in a program, that data should be written as an entry to the secondary clipboard to make it immediately available to other systems.

Safety

Access to the primary or secondary clipboard could allow a malicious program to read and modify sensitive data, or replace the contents of the clipboard with malicious content.

To mitigate this, a separate clipboard could be provided for untrusted programs.

Wake

This device will send a wake request to the system device when an entry is initially dragged over this system, or when an entry is dropped on this system, or when an entry is no longer being dragged over this system.