| 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 */ |