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_info_new 114 * 115 * @owner: clipboard owner. 116 * @selection: clipboard selection. 117 * 118 * Allocate a new QemuClipboardInfo and initialize it with the given 119 * @owner and @selection. 120 * 121 * QemuClipboardInfo is a reference-counted struct. The new struct is 122 * returned with a reference already taken (i.e. reference count is 123 * one). 124 */ 125 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner, 126 QemuClipboardSelection selection); 127 /** 128 * qemu_clipboard_info_ref 129 * 130 * @info: clipboard info. 131 * 132 * Increase @info reference count. 133 */ 134 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info); 135 136 /** 137 * qemu_clipboard_info_unref 138 * 139 * @info: clipboard info. 140 * 141 * Decrease @info reference count. When the count goes down to zero 142 * free the @info struct itself and all clipboard data. 143 */ 144 void qemu_clipboard_info_unref(QemuClipboardInfo *info); 145 146 /** 147 * qemu_clipboard_update 148 * 149 * @info: clipboard info. 150 * 151 * Update the qemu clipboard. Notify all registered peers (including 152 * the clipboard owner) that the qemu clipboard has been updated. 153 * 154 * This is used for both new completely clipboard content and for 155 * clipboard data updates in response to qemu_clipboard_request() 156 * calls. 157 */ 158 void qemu_clipboard_update(QemuClipboardInfo *info); 159 160 /** 161 * qemu_clipboard_request 162 * 163 * @info: clipboard info. 164 * @type: clipboard data type. 165 * 166 * Request clipboard content. Typically the clipboard owner only 167 * advertises the available data types and provides the actual data 168 * only on request. 169 */ 170 void qemu_clipboard_request(QemuClipboardInfo *info, 171 QemuClipboardType type); 172 173 /** 174 * qemu_clipboard_set_data 175 * 176 * @peer: clipboard peer. 177 * @info: clipboard info. 178 * @type: clipboard data type. 179 * @size: data size. 180 * @data: data blob. 181 * @update: notify peers about the update. 182 * 183 * Set clipboard content for the given @type. This function will make 184 * a copy of the content data and store that. 185 */ 186 void qemu_clipboard_set_data(QemuClipboardPeer *peer, 187 QemuClipboardInfo *info, 188 QemuClipboardType type, 189 uint32_t size, 190 const void *data, 191 bool update); 192 193 #endif /* QEMU_CLIPBOARD_H */ 194