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 QemuClipboardNotifyType QemuClipboardNotifyType;
  24 typedef enum QemuClipboardSelection QemuClipboardSelection;
  25 typedef struct QemuClipboardPeer QemuClipboardPeer;
  26 typedef struct QemuClipboardNotify QemuClipboardNotify;
  27 typedef struct QemuClipboardInfo QemuClipboardInfo;
  28
  29 /**
  30  * enum QemuClipboardType
  31  *
  32  * @QEMU_CLIPBOARD_TYPE_TEXT: text/plain; charset=utf-8
  33  * @QEMU_CLIPBOARD_TYPE__COUNT: type count.
  34  */
  35 enum QemuClipboardType {
  36     QEMU_CLIPBOARD_TYPE_TEXT,
  37     QEMU_CLIPBOARD_TYPE__COUNT,
  38 };
  39
  40 /* same as VD_AGENT_CLIPBOARD_SELECTION_* */
  41 /**
  42  * enum QemuClipboardSelection
  43  *
  44  * @QEMU_CLIPBOARD_SELECTION_CLIPBOARD: clipboard (explitcit cut+paste).
  45  * @QEMU_CLIPBOARD_SELECTION_PRIMARY: primary selection (select + middle mouse button).
  46  * @QEMU_CLIPBOARD_SELECTION_SECONDARY: secondary selection (dunno).
  47  * @QEMU_CLIPBOARD_SELECTION__COUNT: selection count.
  48  */
  49 enum QemuClipboardSelection {
  50     QEMU_CLIPBOARD_SELECTION_CLIPBOARD,
  51     QEMU_CLIPBOARD_SELECTION_PRIMARY,
  52     QEMU_CLIPBOARD_SELECTION_SECONDARY,
  53     QEMU_CLIPBOARD_SELECTION__COUNT,
  54 };
  55
  56 /**
  57  * struct QemuClipboardPeer
  58  *
  59  * @name: peer name.
  60  * @notifier: notifier for clipboard updates.
  61  * @request: callback for clipboard data requests.
  62  *
  63  * Clipboard peer description.
  64  */
  65 struct QemuClipboardPeer {
  66     const char *name;
  67     Notifier notifier;
  68     void (*request)(QemuClipboardInfo *info,
  69                     QemuClipboardType type);
  70 };
  71
  72 /**
  73  * enum QemuClipboardNotifyType
  74  *
  75  * @QEMU_CLIPBOARD_UPDATE_INFO: clipboard info update
  76  * @QEMU_CLIPBOARD_RESET_SERIAL: reset clipboard serial
  77  *
  78  * Clipboard notify type.
  79  */
  80 enum QemuClipboardNotifyType {
  81     QEMU_CLIPBOARD_UPDATE_INFO,
  82     QEMU_CLIPBOARD_RESET_SERIAL,
  83 };
  84
  85 /**
  86  * struct QemuClipboardNotify
  87  *
  88  * @type: the type of event.
  89  * @info: a QemuClipboardInfo event.
  90  *
  91  * Clipboard notify data.
  92  */
  93 struct QemuClipboardNotify {
  94     QemuClipboardNotifyType type;
  95     union {
  96         QemuClipboardInfo *info;
  97     };
  98 };
  99
 100 /**
 101  * struct QemuClipboardInfo
 102  *
 103  * @refcount: reference counter.
 104  * @owner: clipboard owner.
 105  * @selection: clipboard selection.
 106  * @types: clipboard data array (one entry per type).
 107  * @has_serial: whether @serial is available.
 108  * @serial: the grab serial counter.
 109  *
 110  * Clipboard content data and metadata.
 111  */
 112 struct QemuClipboardInfo {
 113     uint32_t refcount;
 114     QemuClipboardPeer *owner;
 115     QemuClipboardSelection selection;
 116     bool has_serial;
 117     uint32_t serial;
 118     struct {
 119         bool available;
 120         bool requested;
 121         size_t size;
 122         void *data;
 123     } types[QEMU_CLIPBOARD_TYPE__COUNT];
 124 };
 125
 126 /**
 127  * qemu_clipboard_peer_register
 128  *
 129  * @peer: peer information.
 130  *
 131  * Register clipboard peer.  Registering is needed for both active
 132  * (set+grab clipboard) and passive (watch clipboard for updates)
 133  * interaction with the qemu clipboard.
 134  */
 135 void qemu_clipboard_peer_register(QemuClipboardPeer *peer);
 136
 137 /**
 138  * qemu_clipboard_peer_unregister
 139  *
 140  * @peer: peer information.
 141  *
 142  * Unregister clipboard peer.
 143  */
 144 void qemu_clipboard_peer_unregister(QemuClipboardPeer *peer);
 145
 146 /**
 147  * qemu_clipboard_peer_owns
 148  *
 149  * @peer: peer information.
 150  * @selection: clipboard selection.
 151  *
 152  * Return TRUE if the peer owns the clipboard.
 153  */
 154 bool qemu_clipboard_peer_owns(QemuClipboardPeer *peer,
 155                               QemuClipboardSelection selection);
 156
 157 /**
 158  * qemu_clipboard_peer_release
 159  *
 160  * @peer: peer information.
 161  * @selection: clipboard selection.
 162  *
 163  * If the peer owns the clipboard, release it.
 164  */
 165 void qemu_clipboard_peer_release(QemuClipboardPeer *peer,
 166                                  QemuClipboardSelection selection);
 167
 168 /**
 169  * qemu_clipboard_info
 170  *
 171  * @selection: clipboard selection.
 172  *
 173  * Return the current clipboard data & owner informations.
 174  */
 175 QemuClipboardInfo *qemu_clipboard_info(QemuClipboardSelection selection);
 176
 177 /**
 178  * qemu_clipboard_check_serial
 179  *
 180  * @info: clipboard info.
 181  * @client: whether to check from the client context and priority.
 182  *
 183  * Return TRUE if the @info has a higher serial than the current clipboard.
 184  */
 185 bool qemu_clipboard_check_serial(QemuClipboardInfo *info, bool client);
 186
 187 /**
 188  * qemu_clipboard_info_new
 189  *
 190  * @owner: clipboard owner.
 191  * @selection: clipboard selection.
 192  *
 193  * Allocate a new QemuClipboardInfo and initialize it with the given
 194  * @owner and @selection.
 195  *
 196  * QemuClipboardInfo is a reference-counted struct.  The new struct is
 197  * returned with a reference already taken (i.e. reference count is
 198  * one).
 199  */
 200 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
 201                                            QemuClipboardSelection selection);
 202 /**
 203  * qemu_clipboard_info_ref
 204  *
 205  * @info: clipboard info.
 206  *
 207  * Increase @info reference count.
 208  */
 209 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
 210
 211 /**
 212  * qemu_clipboard_info_unref
 213  *
 214  * @info: clipboard info.
 215  *
 216  * Decrease @info reference count.  When the count goes down to zero
 217  * free the @info struct itself and all clipboard data.
 218  */
 219 void qemu_clipboard_info_unref(QemuClipboardInfo *info);
 220
 221 /**
 222  * qemu_clipboard_update
 223  *
 224  * @info: clipboard info.
 225  *
 226  * Update the qemu clipboard.  Notify all registered peers (including
 227  * the clipboard owner) that the qemu clipboard has been updated.
 228  *
 229  * This is used for both new completely clipboard content and for
 230  * clipboard data updates in response to qemu_clipboard_request()
 231  * calls.
 232  */
 233 void qemu_clipboard_update(QemuClipboardInfo *info);
 234
 235 /**
 236  * qemu_clipboard_reset_serial
 237  *
 238  * Reset the clipboard serial.
 239  */
 240 void qemu_clipboard_reset_serial(void);
 241
 242 /**
 243  * qemu_clipboard_request
 244  *
 245  * @info: clipboard info.
 246  * @type: clipboard data type.
 247  *
 248  * Request clipboard content.  Typically the clipboard owner only
 249  * advertises the available data types and provides the actual data
 250  * only on request.
 251  */
 252 void qemu_clipboard_request(QemuClipboardInfo *info,
 253                             QemuClipboardType type);
 254
 255 /**
 256  * qemu_clipboard_set_data
 257  *
 258  * @peer: clipboard peer.
 259  * @info: clipboard info.
 260  * @type: clipboard data type.
 261  * @size: data size.
 262  * @data: data blob.
 263  * @update: notify peers about the update.
 264  *
 265  * Set clipboard content for the given @type.  This function will make
 266  * a copy of the content data and store that.
 267  */
 268 void qemu_clipboard_set_data(QemuClipboardPeer *peer,
 269                              QemuClipboardInfo *info,
 270                              QemuClipboardType type,
 271                              uint32_t size,
 272                              const void *data,
 273                              bool update);
 274
 275 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QemuClipboardInfo, qemu_clipboard_info_unref)
 276
 277 #endif /* QEMU_CLIPBOARD_H */