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_info_new
 114  *
 115  * @owner: clipboard owner.
 116  * @selection: clipboard selection.
 117  *
 118  * Allocate a new QemuClipboardInfo and initialize it with the given
 119  * @owner and @selection.
 120  *
 121  * QemuClipboardInfo is a reference-counted struct.  The new struct is
 122  * returned with a reference already taken (i.e. reference count is
 123  * one).
 124  */
 125 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
 126                                            QemuClipboardSelection selection);
 127 /**
 128  * qemu_clipboard_info_ref
 129  *
 130  * @info: clipboard info.
 131  *
 132  * Increase @info reference count.
 133  */
 134 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
 135
 136 /**
 137  * qemu_clipboard_info_unref
 138  *
 139  * @info: clipboard info.
 140  *
 141  * Decrease @info reference count.  When the count goes down to zero
 142  * free the @info struct itself and all clipboard data.
 143  */
 144 void qemu_clipboard_info_unref(QemuClipboardInfo *info);
 145
 146 /**
 147  * qemu_clipboard_update
 148  *
 149  * @info: clipboard info.
 150  *
 151  * Update the qemu clipboard.  Notify all registered peers (including
 152  * the clipboard owner) that the qemu clipboard has been updated.
 153  *
 154  * This is used for both new completely clipboard content and for
 155  * clipboard data updates in response to qemu_clipboard_request()
 156  * calls.
 157  */
 158 void qemu_clipboard_update(QemuClipboardInfo *info);
 159
 160 /**
 161  * qemu_clipboard_request
 162  *
 163  * @info: clipboard info.
 164  * @type: clipboard data type.
 165  *
 166  * Request clipboard content.  Typically the clipboard owner only
 167  * advertises the available data types and provides the actual data
 168  * only on request.
 169  */
 170 void qemu_clipboard_request(QemuClipboardInfo *info,
 171                             QemuClipboardType type);
 172
 173 /**
 174  * qemu_clipboard_set_data
 175  *
 176  * @peer: clipboard peer.
 177  * @info: clipboard info.
 178  * @type: clipboard data type.
 179  * @size: data size.
 180  * @data: data blob.
 181  * @update: notify peers about the update.
 182  *
 183  * Set clipboard content for the given @type.  This function will make
 184  * a copy of the content data and store that.
 185  */
 186 void qemu_clipboard_set_data(QemuClipboardPeer *peer,
 187                              QemuClipboardInfo *info,
 188                              QemuClipboardType type,
 189                              uint32_t size,
 190                              void *data,
 191                              bool update);
 192
 193 #endif /* QEMU_CLIPBOARD_H */