ui: add clipboard documentation
[qemu/kevin.git] / include / ui / clipboard.h
blobe5bcb365ed62839f53732d16ace25ec94b9cd5bd
1 #ifndef QEMU_CLIPBOARD_H
2 #define QEMU_CLIPBOARD_H
4 #include "qemu/notify.h"
6 /**
7 * DOC: Introduction
9 * The header ``ui/clipboard.h`` declares the qemu clipboard interface.
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.
15 * Typical users are user interfaces (gtk), remote access protocols
16 * (vnc) and devices talking to the guest (vdagent).
18 * Even though the design allows different data types only plain text
19 * is supported for now.
22 typedef enum QemuClipboardType QemuClipboardType;
23 typedef enum QemuClipboardSelection QemuClipboardSelection;
24 typedef struct QemuClipboardPeer QemuClipboardPeer;
25 typedef struct QemuClipboardInfo QemuClipboardInfo;
27 /**
28 * enum QemuClipboardType
30 * @QEMU_CLIPBOARD_TYPE_TEXT: text/plain; charset=utf-8
31 * @QEMU_CLIPBOARD_TYPE__COUNT: type count.
33 enum QemuClipboardType {
34 QEMU_CLIPBOARD_TYPE_TEXT,
35 QEMU_CLIPBOARD_TYPE__COUNT,
38 /* same as VD_AGENT_CLIPBOARD_SELECTION_* */
39 /**
40 * enum QemuClipboardSelection
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.
47 enum QemuClipboardSelection {
48 QEMU_CLIPBOARD_SELECTION_CLIPBOARD,
49 QEMU_CLIPBOARD_SELECTION_PRIMARY,
50 QEMU_CLIPBOARD_SELECTION_SECONDARY,
51 QEMU_CLIPBOARD_SELECTION__COUNT,
54 /**
55 * struct QemuClipboardPeer
57 * @name: peer name.
58 * @update: notifier for clipboard updates.
59 * @request: callback for clipboard data requests.
61 * Clipboard peer description.
63 struct QemuClipboardPeer {
64 const char *name;
65 Notifier update;
66 void (*request)(QemuClipboardInfo *info,
67 QemuClipboardType type);
70 /**
71 * struct QemuClipboardInfo
73 * @refcount: reference counter.
74 * @owner: clipboard owner.
75 * @selection: clipboard selection.
76 * @types: clipboard data array (one entry per type).
78 * Clipboard content data and metadata.
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];
92 /**
93 * qemu_clipboard_peer_register
95 * @peer: peer information.
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.
101 void qemu_clipboard_peer_register(QemuClipboardPeer *peer);
104 * qemu_clipboard_peer_unregister
106 * @peer: peer information.
108 * Unregister clipboard peer.
110 void qemu_clipboard_peer_unregister(QemuClipboardPeer *peer);
113 * qemu_clipboard_info_new
115 * @owner: clipboard owner.
116 * @selection: clipboard selection.
118 * Allocate a new QemuClipboardInfo and initialize it with the given
119 * @owner and @selection.
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).
125 QemuClipboardInfo *qemu_clipboard_info_new(QemuClipboardPeer *owner,
126 QemuClipboardSelection selection);
128 * qemu_clipboard_info_ref
130 * @info: clipboard info.
132 * Increase @info reference count.
134 QemuClipboardInfo *qemu_clipboard_info_ref(QemuClipboardInfo *info);
137 * qemu_clipboard_info_unref
139 * @info: clipboard info.
141 * Decrease @info reference count. When the count goes down to zero
142 * free the @info struct itself and all clipboard data.
144 void qemu_clipboard_info_unref(QemuClipboardInfo *info);
147 * qemu_clipboard_update
149 * @info: clipboard info.
151 * Update the qemu clipboard. Notify all registered peers (including
152 * the clipboard owner) that the qemu clipboard has been updated.
154 * This is used for both new completely clipboard content and for
155 * clipboard data updates in response to qemu_clipboard_request()
156 * calls.
158 void qemu_clipboard_update(QemuClipboardInfo *info);
161 * qemu_clipboard_request
163 * @info: clipboard info.
164 * @type: clipboard data type.
166 * Request clipboard content. Typically the clipboard owner only
167 * advertises the available data types and provides the actual data
168 * only on request.
170 void qemu_clipboard_request(QemuClipboardInfo *info,
171 QemuClipboardType type);
174 * qemu_clipboard_set_data
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.
183 * Set clipboard content for the given @type. This function will make
184 * a copy of the content data and store that.
186 void qemu_clipboard_set_data(QemuClipboardPeer *peer,
187 QemuClipboardInfo *info,
188 QemuClipboardType type,
189 uint32_t size,
190 void *data,
191 bool update);
193 #endif /* QEMU_CLIPBOARD_H */