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_peer_release 125 * 126 * @peer: peer information. 127 * @selection: clipboard selection. 128 * 129 * If the peer owns the clipboard, release it. 130 */ 131 void qemu_clipboard_peer_release(QemuClipboardPeer *peer, 132 QemuClipboardSelection selection); 133 134 /** 135 * qemu_clipboard_info 136 * 137 * @selection: clipboard selection. 138 * 139 * Return the current clipboard data & owner informations. 140 */ 141 QemuClipboardInfo *qemu_clipboard_info(QemuClipboardSelection selection); 142 143 /** 144 * qemu_clipboard_info_new 145 * 146 * @owner: clipboard owner. 147 * @selection: clipboard selection. 148 * 149 * Allocate a new QemuClipboardInfo and initialize it with the given 150 * @owner and @selection. 151 * 152 * QemuClipboardInfo is a reference-counted struct. The new struct is 153 * returned with a reference already taken (i.e. reference count is 154 * one). 155 */ 156 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner, 157 QemuClipboardSelection selection); 158 /** 159 * qemu_clipboard_info_ref 160 * 161 * @info: clipboard info. 162 * 163 * Increase @info reference count. 164 */ 165 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info); 166 167 /** 168 * qemu_clipboard_info_unref 169 * 170 * @info: clipboard info. 171 * 172 * Decrease @info reference count. When the count goes down to zero 173 * free the @info struct itself and all clipboard data. 174 */ 175 void qemu_clipboard_info_unref(QemuClipboardInfo *info); 176 177 /** 178 * qemu_clipboard_update 179 * 180 * @info: clipboard info. 181 * 182 * Update the qemu clipboard. Notify all registered peers (including 183 * the clipboard owner) that the qemu clipboard has been updated. 184 * 185 * This is used for both new completely clipboard content and for 186 * clipboard data updates in response to qemu_clipboard_request() 187 * calls. 188 */ 189 void qemu_clipboard_update(QemuClipboardInfo *info); 190 191 /** 192 * qemu_clipboard_request 193 * 194 * @info: clipboard info. 195 * @type: clipboard data type. 196 * 197 * Request clipboard content. Typically the clipboard owner only 198 * advertises the available data types and provides the actual data 199 * only on request. 200 */ 201 void qemu_clipboard_request(QemuClipboardInfo *info, 202 QemuClipboardType type); 203 204 /** 205 * qemu_clipboard_set_data 206 * 207 * @peer: clipboard peer. 208 * @info: clipboard info. 209 * @type: clipboard data type. 210 * @size: data size. 211 * @data: data blob. 212 * @update: notify peers about the update. 213 * 214 * Set clipboard content for the given @type. This function will make 215 * a copy of the content data and store that. 216 */ 217 void qemu_clipboard_set_data(QemuClipboardPeer *peer, 218 QemuClipboardInfo *info, 219 QemuClipboardType type, 220 uint32_t size, 221 const void *data, 222 bool update); 223 224 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QemuClipboardInfo, qemu_clipboard_info_unref) 225 226 #endif /* QEMU_CLIPBOARD_H */ 227