ui: add clipboard documentation

Document clipboard infrastructure in qemu.

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-id: 20210519053940.1888907-1-kraxel@redhat.com
Message-Id: <20210519053940.1888907-4-kraxel@redhat.com>
This commit is contained in:
Gerd Hoffmann 2021-05-19 07:39:34 +02:00
parent 660e8d0f0b
commit 3f20c6d654
3 changed files with 141 additions and 1 deletions

View File

@ -36,6 +36,7 @@ Contents:
multi-thread-tcg
tcg-plugins
bitops
ui
reset
s390-dasd-ipl
clocks

8
docs/devel/ui.rst Normal file
View File

@ -0,0 +1,8 @@
=================
Qemu UI subsystem
=================
Qemu Clipboard
--------------
.. kernel-doc:: include/ui/clipboard.h

View File

@ -3,17 +3,47 @@
#include "qemu/notify.h"
/**
* DOC: Introduction
*
* The header ``ui/clipboard.h`` declares the qemu clipboard interface.
*
* All qemu elements which want use the clipboard can register as
* clipboard peer. Subsequently they can set the clipboard content
* and get notifications for clipboard updates.
*
* Typical users are user interfaces (gtk), remote access protocols
* (vnc) and devices talking to the guest (vdagent).
*
* Even though the design allows different data types only plain text
* is supported for now.
*/
typedef enum QemuClipboardType QemuClipboardType;
typedef enum QemuClipboardSelection QemuClipboardSelection;
typedef struct QemuClipboardPeer QemuClipboardPeer;
typedef struct QemuClipboardInfo QemuClipboardInfo;
/**
* enum QemuClipboardType
*
* @QEMU_CLIPBOARD_TYPE_TEXT: text/plain; charset=utf-8
* @QEMU_CLIPBOARD_TYPE__COUNT: type count.
*/
enum QemuClipboardType {
QEMU_CLIPBOARD_TYPE_TEXT, /* text/plain; charset=utf-8 */
QEMU_CLIPBOARD_TYPE_TEXT,
QEMU_CLIPBOARD_TYPE__COUNT,
};
/* same as VD_AGENT_CLIPBOARD_SELECTION_* */
/**
* enum QemuClipboardSelection
*
* @QEMU_CLIPBOARD_SELECTION_CLIPBOARD: clipboard (explitcit cut+paste).
* @QEMU_CLIPBOARD_SELECTION_PRIMARY: primary selection (select + middle mouse button).
* @QEMU_CLIPBOARD_SELECTION_SECONDARY: secondary selection (dunno).
* @QEMU_CLIPBOARD_SELECTION__COUNT: selection count.
*/
enum QemuClipboardSelection {
QEMU_CLIPBOARD_SELECTION_CLIPBOARD,
QEMU_CLIPBOARD_SELECTION_PRIMARY,
@ -21,6 +51,15 @@ enum QemuClipboardSelection {
QEMU_CLIPBOARD_SELECTION__COUNT,
};
/**
* struct QemuClipboardPeer
*
* @name: peer name.
* @update: notifier for clipboard updates.
* @request: callback for clipboard data requests.
*
* Clipboard peer description.
*/
struct QemuClipboardPeer {
const char *name;
Notifier update;
@ -28,6 +67,16 @@ struct QemuClipboardPeer {
QemuClipboardType type);
};
/**
* struct QemuClipboardInfo
*
* @refcount: reference counter.
* @owner: clipboard owner.
* @selection: clipboard selection.
* @types: clipboard data array (one entry per type).
*
* Clipboard content data and metadata.
*/
struct QemuClipboardInfo {
uint32_t refcount;
QemuClipboardPeer *owner;
@ -40,18 +89,100 @@ struct QemuClipboardInfo {
} types[QEMU_CLIPBOARD_TYPE__COUNT];
};
/**
* qemu_clipboard_peer_register
*
* @peer: peer information.
*
* Register clipboard peer. Registering is needed for both active
* (set+grab clipboard) and passive (watch clipboard for updates)
* interaction with the qemu clipboard.
*/
void qemu_clipboard_peer_register(QemuClipboardPeer *peer);
/**
* qemu_clipboard_peer_unregister
*
* @peer: peer information.
*
* Unregister clipboard peer.
*/
void qemu_clipboard_peer_unregister(QemuClipboardPeer *peer);
/**
* qemu_clipboard_info_new
*
* @owner: clipboard owner.
* @selection: clipboard selection.
*
* Allocate a new QemuClipboardInfo and initialize it with the given
* @owner and @selection.
*
* QemuClipboardInfo is a reference-counted struct. The new struct is
* returned with a reference already taken (i.e. reference count is
* one).
*/
QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
QemuClipboardSelection selection);
/**
* qemu_clipboard_info_ref
*
* @info: clipboard info.
*
* Increase @info reference count.
*/
QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
/**
* qemu_clipboard_info_unref
*
* @info: clipboard info.
*
* Decrease @info reference count. When the count goes down to zero
* free the @info struct itself and all clipboard data.
*/
void qemu_clipboard_info_unref(QemuClipboardInfo *info);
/**
* qemu_clipboard_update
*
* @info: clipboard info.
*
* Update the qemu clipboard. Notify all registered peers (including
* the clipboard owner) that the qemu clipboard has been updated.
*
* This is used for both new completely clipboard content and for
* clipboard data updates in response to qemu_clipboard_request()
* calls.
*/
void qemu_clipboard_update(QemuClipboardInfo *info);
/**
* qemu_clipboard_request
*
* @info: clipboard info.
* @type: clipboard data type.
*
* Request clipboard content. Typically the clipboard owner only
* advertises the available data types and provides the actual data
* only on request.
*/
void qemu_clipboard_request(QemuClipboardInfo *info,
QemuClipboardType type);
/**
* qemu_clipboard_set_data
*
* @peer: clipboard peer.
* @info: clipboard info.
* @type: clipboard data type.
* @size: data size.
* @data: data blob.
* @update: notify peers about the update.
*
* Set clipboard content for the given @type. This function will make
* a copy of the content data and store that.
*/
void qemu_clipboard_set_data(QemuClipboardPeer *peer,
QemuClipboardInfo *info,
QemuClipboardType type,