[v4,3/9] ui: add clipboard documentation

Document clipboard infrastructure in qemu.

Signed-off-by: Gerd Hoffmann <kraxel@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

On Fri, Apr 23, 2021 at 12:34 PM Gerd Hoffmann <kraxel@redhat.com> wrote:

> Document clipboard infrastructure in qemu.
>
> Signed-off-by: Gerd Hoffmann <kraxel@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.lureau@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
>
>