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  *
  77  * Clipboard notify type.
  78  */
  79 enum QemuClipboardNotifyType {
  80     QEMU_CLIPBOARD_UPDATE_INFO,
  81 };
  82
  83 /**
  84  * struct QemuClipboardNotify
  85  *
  86  * @type: the type of event.
  87  * @info: a QemuClipboardInfo event.
  88  *
  89  * Clipboard notify data.
  90  */
  91 struct QemuClipboardNotify {
  92     QemuClipboardNotifyType type;
  93     union {
  94         QemuClipboardInfo *info;
  95     };
  96 };
  97
  98 /**
  99  * struct QemuClipboardInfo
 100  *
 101  * @refcount: reference counter.
 102  * @owner: clipboard owner.
 103  * @selection: clipboard selection.
 104  * @types: clipboard data array (one entry per type).
 105  * @has_serial: whether @serial is available.
 106  * @serial: the grab serial counter.
 107  *
 108  * Clipboard content data and metadata.
 109  */
 110 struct QemuClipboardInfo {
 111     uint32_t refcount;
 112     QemuClipboardPeer *owner;
 113     QemuClipboardSelection selection;
 114     bool has_serial;
 115     uint32_t serial;
 116     struct {
 117         bool available;
 118         bool requested;
 119         size_t size;
 120         void *data;
 121     } types[QEMU_CLIPBOARD_TYPE__COUNT];
 122 };
 123
 124 /**
 125  * qemu_clipboard_peer_register
 126  *
 127  * @peer: peer information.
 128  *
 129  * Register clipboard peer.  Registering is needed for both active
 130  * (set+grab clipboard) and passive (watch clipboard for updates)
 131  * interaction with the qemu clipboard.
 132  */
 133 void qemu_clipboard_peer_register(QemuClipboardPeer *peer);
 134
 135 /**
 136  * qemu_clipboard_peer_unregister
 137  *
 138  * @peer: peer information.
 139  *
 140  * Unregister clipboard peer.
 141  */
 142 void qemu_clipboard_peer_unregister(QemuClipboardPeer *peer);
 143
 144 /**
 145  * qemu_clipboard_peer_owns
 146  *
 147  * @peer: peer information.
 148  * @selection: clipboard selection.
 149  *
 150  * Return TRUE if the peer owns the clipboard.
 151  */
 152 bool qemu_clipboard_peer_owns(QemuClipboardPeer *peer,
 153                               QemuClipboardSelection selection);
 154
 155 /**
 156  * qemu_clipboard_peer_release
 157  *
 158  * @peer: peer information.
 159  * @selection: clipboard selection.
 160  *
 161  * If the peer owns the clipboard, release it.
 162  */
 163 void qemu_clipboard_peer_release(QemuClipboardPeer *peer,
 164                                  QemuClipboardSelection selection);
 165
 166 /**
 167  * qemu_clipboard_info
 168  *
 169  * @selection: clipboard selection.
 170  *
 171  * Return the current clipboard data & owner informations.
 172  */
 173 QemuClipboardInfo *qemu_clipboard_info(QemuClipboardSelection selection);
 174
 175 /**
 176  * qemu_clipboard_info_new
 177  *
 178  * @owner: clipboard owner.
 179  * @selection: clipboard selection.
 180  *
 181  * Allocate a new QemuClipboardInfo and initialize it with the given
 182  * @owner and @selection.
 183  *
 184  * QemuClipboardInfo is a reference-counted struct.  The new struct is
 185  * returned with a reference already taken (i.e. reference count is
 186  * one).
 187  */
 188 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
 189                                            QemuClipboardSelection selection);
 190 /**
 191  * qemu_clipboard_info_ref
 192  *
 193  * @info: clipboard info.
 194  *
 195  * Increase @info reference count.
 196  */
 197 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
 198
 199 /**
 200  * qemu_clipboard_info_unref
 201  *
 202  * @info: clipboard info.
 203  *
 204  * Decrease @info reference count.  When the count goes down to zero
 205  * free the @info struct itself and all clipboard data.
 206  */
 207 void qemu_clipboard_info_unref(QemuClipboardInfo *info);
 208
 209 /**
 210  * qemu_clipboard_update
 211  *
 212  * @info: clipboard info.
 213  *
 214  * Update the qemu clipboard.  Notify all registered peers (including
 215  * the clipboard owner) that the qemu clipboard has been updated.
 216  *
 217  * This is used for both new completely clipboard content and for
 218  * clipboard data updates in response to qemu_clipboard_request()
 219  * calls.
 220  */
 221 void qemu_clipboard_update(QemuClipboardInfo *info);
 222
 223 /**
 224  * qemu_clipboard_request
 225  *
 226  * @info: clipboard info.
 227  * @type: clipboard data type.
 228  *
 229  * Request clipboard content.  Typically the clipboard owner only
 230  * advertises the available data types and provides the actual data
 231  * only on request.
 232  */
 233 void qemu_clipboard_request(QemuClipboardInfo *info,
 234                             QemuClipboardType type);
 235
 236 /**
 237  * qemu_clipboard_set_data
 238  *
 239  * @peer: clipboard peer.
 240  * @info: clipboard info.
 241  * @type: clipboard data type.
 242  * @size: data size.
 243  * @data: data blob.
 244  * @update: notify peers about the update.
 245  *
 246  * Set clipboard content for the given @type.  This function will make
 247  * a copy of the content data and store that.
 248  */
 249 void qemu_clipboard_set_data(QemuClipboardPeer *peer,
 250                              QemuClipboardInfo *info,
 251                              QemuClipboardType type,
 252                              uint32_t size,
 253                              const void *data,
 254                              bool update);
 255
 256 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QemuClipboardInfo, qemu_clipboard_info_unref)
 257
 258 #endif /* QEMU_CLIPBOARD_H */