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 22typedef enum QemuClipboardType QemuClipboardType; 23typedef enum QemuClipboardNotifyType QemuClipboardNotifyType; 24typedef enum QemuClipboardSelection QemuClipboardSelection; 25typedef struct QemuClipboardPeer QemuClipboardPeer; 26typedef struct QemuClipboardNotify QemuClipboardNotify; 27typedef 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 */ 35enum 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 */ 49enum 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 */ 65struct 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 */ 80enum 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 */ 93struct 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 */ 112struct 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 */ 135void qemu_clipboard_peer_register(QemuClipboardPeer *peer); 136 137/** 138 * qemu_clipboard_peer_unregister 139 * 140 * @peer: peer information. 141 * 142 * Unregister clipboard peer. 143 */ 144void 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 */ 154bool 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 */ 165void 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 */ 175QemuClipboardInfo *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 */ 185bool 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 */ 200QemuClipboardInfo *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 */ 209QemuClipboardInfo *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 */ 219void 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 */ 233void qemu_clipboard_update(QemuClipboardInfo *info); 234 235/** 236 * qemu_clipboard_reset_serial 237 * 238 * Reset the clipboard serial. 239 */ 240void 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 */ 252void 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 */ 268void qemu_clipboard_set_data(QemuClipboardPeer *peer, 269 QemuClipboardInfo *info, 270 QemuClipboardType type, 271 uint32_t size, 272 const void *data, 273 bool update); 274 275G_DEFINE_AUTOPTR_CLEANUP_FUNC(QemuClipboardInfo, qemu_clipboard_info_unref) 276 277#endif /* QEMU_CLIPBOARD_H */ 278