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