include/ui/clipboard.h

   1 #ifndef QEMU_CLIPBOARD_H
   2 #define QEMU_CLIPBOARD_H
   3
   4 #include "qemu/notify.h"
   5
   6 /**
   7  * DOC: Introduction
   8  *
   9  * The header ``ui/clipboard.h`` declares the qemu clipboard interface.
  10  *
  11  * All qemu elements which want use the clipboard can register as
  12  * clipboard peer.  Subsequently they can set the clipboard content
  13  * and get notifications for clipboard updates.
  14  *
  15  * Typical users are user interfaces (gtk), remote access protocols
  16  * (vnc) and devices talking to the guest (vdagent).
  17  *
  18  * Even though the design allows different data types only plain text
  19  * is supported for now.
  20  */
  21
  22 typedef enum QemuClipboardType QemuClipboardType;
  23 typedef enum QemuClipboardSelection QemuClipboardSelection;
  24 typedef struct QemuClipboardPeer QemuClipboardPeer;
  25 typedef struct QemuClipboardInfo QemuClipboardInfo;
  26
  27 /**
  28  * enum QemuClipboardType
  29  *
  30  * @QEMU_CLIPBOARD_TYPE_TEXT: text/plain; charset=utf-8
  31  * @QEMU_CLIPBOARD_TYPE__COUNT: type count.
  32  */
  33 enum QemuClipboardType {
  34     QEMU_CLIPBOARD_TYPE_TEXT,
  35     QEMU_CLIPBOARD_TYPE__COUNT,
  36 };
  37
  38 /* same as VD_AGENT_CLIPBOARD_SELECTION_* */
  39 /**
  40  * enum QemuClipboardSelection
  41  *
  42  * @QEMU_CLIPBOARD_SELECTION_CLIPBOARD: clipboard (explitcit cut+paste).
  43  * @QEMU_CLIPBOARD_SELECTION_PRIMARY: primary selection (select + middle mouse button).
  44  * @QEMU_CLIPBOARD_SELECTION_SECONDARY: secondary selection (dunno).
  45  * @QEMU_CLIPBOARD_SELECTION__COUNT: selection count.
  46  */
  47 enum QemuClipboardSelection {
  48     QEMU_CLIPBOARD_SELECTION_CLIPBOARD,
  49     QEMU_CLIPBOARD_SELECTION_PRIMARY,
  50     QEMU_CLIPBOARD_SELECTION_SECONDARY,
  51     QEMU_CLIPBOARD_SELECTION__COUNT,
  52 };
  53
  54 /**
  55  * struct QemuClipboardPeer
  56  *
  57  * @name: peer name.
  58  * @update: notifier for clipboard updates.
  59  * @request: callback for clipboard data requests.
  60  *
  61  * Clipboard peer description.
  62  */
  63 struct QemuClipboardPeer {
  64     const char *name;
  65     Notifier update;
  66     void (*request)(QemuClipboardInfo *info,
  67                     QemuClipboardType type);
  68 };
  69
  70 /**
  71  * struct QemuClipboardInfo
  72  *
  73  * @refcount: reference counter.
  74  * @owner: clipboard owner.
  75  * @selection: clipboard selection.
  76  * @types: clipboard data array (one entry per type).
  77  *
  78  * Clipboard content data and metadata.
  79  */
  80 struct QemuClipboardInfo {
  81     uint32_t refcount;
  82     QemuClipboardPeer *owner;
  83     QemuClipboardSelection selection;
  84     struct {
  85         bool available;
  86         bool requested;
  87         size_t size;
  88         void *data;
  89     } types[QEMU_CLIPBOARD_TYPE__COUNT];
  90 };
  91
  92 /**
  93  * qemu_clipboard_peer_register
  94  *
  95  * @peer: peer information.
  96  *
  97  * Register clipboard peer.  Registering is needed for both active
  98  * (set+grab clipboard) and passive (watch clipboard for updates)
  99  * interaction with the qemu clipboard.
 100  */
 101 void qemu_clipboard_peer_register(QemuClipboardPeer *peer);
 102
 103 /**
 104  * qemu_clipboard_peer_unregister
 105  *
 106  * @peer: peer information.
 107  *
 108  * Unregister clipboard peer.
 109  */
 110 void qemu_clipboard_peer_unregister(QemuClipboardPeer *peer);
 111
 112 /**
 113  * qemu_clipboard_peer_owns
 114  *
 115  * @peer: peer information.
 116  * @selection: clipboard selection.
 117  *
 118  * Return TRUE if the peer owns the clipboard.
 119  */
 120 bool qemu_clipboard_peer_owns(QemuClipboardPeer *peer,
 121                               QemuClipboardSelection selection);
 122
 123 /**
 124  * qemu_clipboard_info
 125  *
 126  * @selection: clipboard selection.
 127  *
 128  * Return the current clipboard data & owner informations.
 129  */
 130 QemuClipboardInfo *qemu_clipboard_info(QemuClipboardSelection selection);
 131
 132 /**
 133  * qemu_clipboard_info_new
 134  *
 135  * @owner: clipboard owner.
 136  * @selection: clipboard selection.
 137  *
 138  * Allocate a new QemuClipboardInfo and initialize it with the given
 139  * @owner and @selection.
 140  *
 141  * QemuClipboardInfo is a reference-counted struct.  The new struct is
 142  * returned with a reference already taken (i.e. reference count is
 143  * one).
 144  */
 145 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
 146                                            QemuClipboardSelection selection);
 147 /**
 148  * qemu_clipboard_info_ref
 149  *
 150  * @info: clipboard info.
 151  *
 152  * Increase @info reference count.
 153  */
 154 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
 155
 156 /**
 157  * qemu_clipboard_info_unref
 158  *
 159  * @info: clipboard info.
 160  *
 161  * Decrease @info reference count.  When the count goes down to zero
 162  * free the @info struct itself and all clipboard data.
 163  */
 164 void qemu_clipboard_info_unref(QemuClipboardInfo *info);
 165
 166 /**
 167  * qemu_clipboard_update
 168  *
 169  * @info: clipboard info.
 170  *
 171  * Update the qemu clipboard.  Notify all registered peers (including
 172  * the clipboard owner) that the qemu clipboard has been updated.
 173  *
 174  * This is used for both new completely clipboard content and for
 175  * clipboard data updates in response to qemu_clipboard_request()
 176  * calls.
 177  */
 178 void qemu_clipboard_update(QemuClipboardInfo *info);
 179
 180 /**
 181  * qemu_clipboard_request
 182  *
 183  * @info: clipboard info.
 184  * @type: clipboard data type.
 185  *
 186  * Request clipboard content.  Typically the clipboard owner only
 187  * advertises the available data types and provides the actual data
 188  * only on request.
 189  */
 190 void qemu_clipboard_request(QemuClipboardInfo *info,
 191                             QemuClipboardType type);
 192
 193 /**
 194  * qemu_clipboard_set_data
 195  *
 196  * @peer: clipboard peer.
 197  * @info: clipboard info.
 198  * @type: clipboard data type.
 199  * @size: data size.
 200  * @data: data blob.
 201  * @update: notify peers about the update.
 202  *
 203  * Set clipboard content for the given @type.  This function will make
 204  * a copy of the content data and store that.
 205  */
 206 void qemu_clipboard_set_data(QemuClipboardPeer *peer,
 207                              QemuClipboardInfo *info,
 208                              QemuClipboardType type,
 209                              uint32_t size,
 210                              const void *data,
 211                              bool update);
 212
 213 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QemuClipboardInfo, qemu_clipboard_info_unref)
 214
 215 #endif /* QEMU_CLIPBOARD_H */