Clipboard architecture
The clipboard write gate, the self-write ledger, the copy listener's path into the history, and the store's memory-only rule.
Scope. How a copy gets into the history and how the keyboard writes the system clipboard. Not covered: retention and what leaves the phone, which are on the data page.
The write gate
Section titled “The write gate”ClipboardWriteGate is the one place the keyboard calls setPrimaryClip or
clearPrimaryClip. Tools and panels (music, Send files, share, gallery,
kaomoji, the camera’s Copy, the box’s Insert), the listener’s write-back of a
tidied copy, Undo, the KDE Connect clipboard and the clears after a delete all
go through it. ArchitectureTest fails a new direct call in feature/ime; the
paste-next path in holdClipForPaste is the one place still writing directly,
allowed by count until it moves.
| Call | What it does |
|---|---|
writeText(context, text, label, sensitive, selfWrite) | A plain-text clip |
writeUri(context, uri, label, mimeType, sensitive) | A URI clip; a blank type is asked of the resolver |
writeClip(context, clip, sensitive, selfWrite) | A prepared clip, its own extras kept |
clear(context) | clearPrimaryClip, or an empty clip before Android 9 |
Every write gets up to three marks in ClipDescription.extras, merged with
whatever extras the clip already carries:
android.content.extra.IS_SENSITIVEwhen the caller says the text is a secret. The key string is written as a literal so it works on every release, as password managers do. The password generator always sets it; the KDE Connect clipboard sets it on textClipSensitivityreads as a secret; the listener’s write-back sets it on a tidied copy that reads as one while the user’s handling isn’t “keep”; Undo puts a clip back with the extras it came with.- The keyboard’s own mark, on every write. The listener uses it to tell a
secret the keyboard copied for the user from one a password manager copied.
Only the second is the manager’s to wipe, so only the second leaves the
history when the clipboard is emptied (
forgetClearedSecret). - A self-write token when
selfWriteis set: a random UUID recorded inSelfWriteLedger.
A write never throws. The clipboard service can refuse one, and a copy button is not worth a crash; the gate returns false instead.
KeyboardClipboard.copy is the entry point for panels that only have a
Context. While the clipboard is private it keeps the copy in memory and tells
the service through onPrivateCopy(text, sensitive); otherwise it calls the
gate.
The self-write ledger
Section titled “The self-write ledger”Two writes must not be filed again by the listener: a tidied copy written back
to the system clipboard (copy rules, link cleaning) and Undo putting a deleted
clip back. Both carry a token. The listener reads the primary clip first and
calls consumeSelfWrite; a token recorded within the last five seconds is
accepted once and removed.
This replaced comparing the clipboard’s text with what the keyboard had just
written (restoringSystemClipText). The text comparison let a real copy of the
same text go by when the keyboard’s own write never produced a callback, and
had nothing to compare for a picture. holdClipForPaste still uses the old
field until it moves to the gate; both checks run, the token first.
The ledger holds at most 64 tokens, prunes expired ones on every call, and never holds content.
The copy listener
Section titled “The copy listener”The listener’s order is unchanged apart from the token check at its head:
- A private in-memory copy yields to the newer system clip.
- A self-write token is consumed and the callback ends.
- KDE Connect, Send files and the reply panel hear about the copy.
- An emptied clipboard runs
forgetClearedSecretand ends. - The gates: clipboard readable (unlocked, keyguard not showing), history on, capture not paused by incognito or a password field (unless the password-field copy is kept).
- Sensitivity: the copying app’s flag, ignored under “keep”; a password-field
copy under “hide”; the
ClipSensitivityheuristic when “Let the keyboard find them” is on and the handling isn’t “keep”. Under “never save” a secret ends the callback. - Pictures are copied out of the provider, counted as they stream and dropped
past
HARD_MAX_IMAGE_BYTES; files, folders and videos are recorded by URI; text is tidied, written back if asked, and added.
ClipboardDiagnostics counts each exit (attempts, gate drops, sensitive drops,
self-write skips, clips stored by kind, pictures not kept) and the service
writes the summary to the debug log when it is destroyed. Counts only: no
text, no length, no hash.
The store
Section titled “The store”ClipboardStore is one in-memory list, synchronized, persisted whole through
SnapshotFile (atomic write through a .part file, ordered tickets so an
older snapshot never lands last).
The memory-only rule is a filter at save time, not a second store.
memoryOnlySensitive is on while the handling is “Hide it and delete it
quickly”. save() then writes every clip except the unpinned sensitive ones,
which stay in the list, in the panel and pasteable, until their short timer
sweeps them. A pinned secret is saved: pinning is the user’s explicit “keep
this”. When the flag turns on and the file still holds a secret an earlier
version wrote, holdsSecretsOnDisk() tells the service to save at once. Pin,
edit, Undo, the paste-time sweep and the clipboard-emptied rule all keep
working on the one list.
