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