On Fri, Apr 23, 2021 at 12:34 PM Gerd Hoffmann <kra...@redhat.com> wrote:
> Document clipboard infrastructure in qemu.
>
> Signed-off-by: Gerd Hoffmann <kra...@redhat.com>
> ---
> include/ui/clipboard.h | 133 ++++++++++++++++++++++++++++++++++++++++-
> docs/devel/index.rst | 1 +
> docs/devel/ui.rst | 8 +++
> 3 files changed, 141 insertions(+), 1 deletion(-)
> create mode 100644 docs/devel/ui.rst
>
>
Reviewed-by: Marc-André Lureau <marcandre.lur...@redhat.com>
diff --git a/include/ui/clipboard.h b/include/ui/clipboard.h
> index b2354a4162db..57d4ad445628 100644
> --- a/include/ui/clipboard.h
> +++ b/include/ui/clipboard.h
> @@ -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_get
> + *
> + * @info: clipboard info.
> + *
> + * Increase @info reference count.
> + */
> QemuClipboardInfo *qemu_clipboard_info_get(QemuClipboardInfo *info);
> +
> +/**
> + * qemu_clipboard_info_put
> + *
> + * @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_put(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,
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index 6cf7e2d2330c..cbdbb9049182 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -36,6 +36,7 @@ Contents:
> multi-thread-tcg
> tcg-plugins
> bitops
> + ui
> reset
> s390-dasd-ipl
> clocks
> diff --git a/docs/devel/ui.rst b/docs/devel/ui.rst
> new file mode 100644
> index 000000000000..06c7d622ce74
> --- /dev/null
> +++ b/docs/devel/ui.rst
> @@ -0,0 +1,8 @@
> +=================
> +Qemu UI subsystem
> +=================
> +
> +Qemu Clipboard
> +--------------
> +
> +.. kernel-doc:: include/ui/clipboard.h
> --
> 2.30.2
>
>
