block/export: Add query-block-exports
[qemu.git] / include / chardev / char-fe.h
1 #ifndef QEMU_CHAR_FE_H
2 #define QEMU_CHAR_FE_H
3
4 #include "chardev/char.h"
5 #include "qemu/main-loop.h"
6
7 typedef void IOEventHandler(void *opaque, QEMUChrEvent event);
8 typedef int BackendChangeHandler(void *opaque);
9
10 /* This is the backend as seen by frontend, the actual backend is
11 * Chardev */
12 struct CharBackend {
13 Chardev *chr;
14 IOEventHandler *chr_event;
15 IOCanReadHandler *chr_can_read;
16 IOReadHandler *chr_read;
17 BackendChangeHandler *chr_be_change;
18 void *opaque;
19 int tag;
20 int fe_open;
21 };
22
23 /**
24 * qemu_chr_fe_init:
25 *
26 * Initializes a front end for the given CharBackend and
27 * Chardev. Call qemu_chr_fe_deinit() to remove the association and
28 * release the driver.
29 *
30 * Returns: false on error.
31 */
32 bool qemu_chr_fe_init(CharBackend *b, Chardev *s, Error **errp);
33
34 /**
35 * qemu_chr_fe_deinit:
36 * @b: a CharBackend
37 * @del: if true, delete the chardev backend
38 *
39 * Dissociate the CharBackend from the Chardev.
40 *
41 * Safe to call without associated Chardev.
42 */
43 void qemu_chr_fe_deinit(CharBackend *b, bool del);
44
45 /**
46 * qemu_chr_fe_get_driver:
47 *
48 * Returns: the driver associated with a CharBackend or NULL if no
49 * associated Chardev.
50 * Note: avoid this function as the driver should never be accessed directly,
51 * especially by the frontends that support chardevice hotswap.
52 * Consider qemu_chr_fe_backend_connected() to check for driver existence
53 */
54 Chardev *qemu_chr_fe_get_driver(CharBackend *be);
55
56 /**
57 * qemu_chr_fe_backend_connected:
58 *
59 * Returns: true if there is a chardevice associated with @be.
60 */
61 bool qemu_chr_fe_backend_connected(CharBackend *be);
62
63 /**
64 * qemu_chr_fe_backend_open:
65 *
66 * Returns: true if chardevice associated with @be is open.
67 */
68 bool qemu_chr_fe_backend_open(CharBackend *be);
69
70 /**
71 * qemu_chr_fe_set_handlers_full:
72 * @b: a CharBackend
73 * @fd_can_read: callback to get the amount of data the frontend may
74 * receive
75 * @fd_read: callback to receive data from char
76 * @fd_event: event callback
77 * @be_change: backend change callback; passing NULL means hot backend change
78 * is not supported and will not be attempted
79 * @opaque: an opaque pointer for the callbacks
80 * @context: a main loop context or NULL for the default
81 * @set_open: whether to call qemu_chr_fe_set_open() implicitely when
82 * any of the handler is non-NULL
83 * @sync_state: whether to issue event callback with updated state
84 *
85 * Set the front end char handlers. The front end takes the focus if
86 * any of the handler is non-NULL.
87 *
88 * Without associated Chardev, nothing is changed.
89 */
90 void qemu_chr_fe_set_handlers_full(CharBackend *b,
91 IOCanReadHandler *fd_can_read,
92 IOReadHandler *fd_read,
93 IOEventHandler *fd_event,
94 BackendChangeHandler *be_change,
95 void *opaque,
96 GMainContext *context,
97 bool set_open,
98 bool sync_state);
99
100 /**
101 * qemu_chr_fe_set_handlers:
102 *
103 * Version of qemu_chr_fe_set_handlers_full() with sync_state = true.
104 */
105 void qemu_chr_fe_set_handlers(CharBackend *b,
106 IOCanReadHandler *fd_can_read,
107 IOReadHandler *fd_read,
108 IOEventHandler *fd_event,
109 BackendChangeHandler *be_change,
110 void *opaque,
111 GMainContext *context,
112 bool set_open);
113
114 /**
115 * qemu_chr_fe_take_focus:
116 *
117 * Take the focus (if the front end is muxed).
118 *
119 * Without associated Chardev, nothing is changed.
120 */
121 void qemu_chr_fe_take_focus(CharBackend *b);
122
123 /**
124 * qemu_chr_fe_accept_input:
125 *
126 * Notify that the frontend is ready to receive data
127 */
128 void qemu_chr_fe_accept_input(CharBackend *be);
129
130 /**
131 * qemu_chr_fe_disconnect:
132 *
133 * Close a fd accepted by character backend.
134 * Without associated Chardev, do nothing.
135 */
136 void qemu_chr_fe_disconnect(CharBackend *be);
137
138 /**
139 * qemu_chr_fe_wait_connected:
140 *
141 * Wait for characted backend to be connected, return < 0 on error or
142 * if no associated Chardev.
143 */
144 int qemu_chr_fe_wait_connected(CharBackend *be, Error **errp);
145
146 /**
147 * qemu_chr_fe_set_echo:
148 * @echo: true to enable echo, false to disable echo
149 *
150 * Ask the backend to override its normal echo setting. This only really
151 * applies to the stdio backend and is used by the QMP server such that you
152 * can see what you type if you try to type QMP commands.
153 * Without associated Chardev, do nothing.
154 */
155 void qemu_chr_fe_set_echo(CharBackend *be, bool echo);
156
157 /**
158 * qemu_chr_fe_set_open:
159 *
160 * Set character frontend open status. This is an indication that the
161 * front end is ready (or not) to begin doing I/O.
162 * Without associated Chardev, do nothing.
163 */
164 void qemu_chr_fe_set_open(CharBackend *be, int fe_open);
165
166 /**
167 * qemu_chr_fe_printf:
168 * @fmt: see #printf
169 *
170 * Write to a character backend using a printf style interface. This
171 * function is thread-safe. It does nothing without associated
172 * Chardev.
173 */
174 void qemu_chr_fe_printf(CharBackend *be, const char *fmt, ...)
175 GCC_FMT_ATTR(2, 3);
176
177 /**
178 * qemu_chr_fe_add_watch:
179 * @cond: the condition to poll for
180 * @func: the function to call when the condition happens
181 * @user_data: the opaque pointer to pass to @func
182 *
183 * If the backend is connected, create and add a #GSource that fires
184 * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP)
185 * is active; return the #GSource's tag. If it is disconnected,
186 * or without associated Chardev, return 0.
187 *
188 * Note that you are responsible to update the front-end sources if
189 * you are switching the main context with qemu_chr_fe_set_handlers().
190 *
191 * Returns: the source tag
192 */
193 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond,
194 GIOFunc func, void *user_data);
195
196 /**
197 * qemu_chr_fe_write:
198 * @buf: the data
199 * @len: the number of bytes to send
200 *
201 * Write data to a character backend from the front end. This function
202 * will send data from the front end to the back end. This function
203 * is thread-safe.
204 *
205 * Returns: the number of bytes consumed (0 if no associated Chardev)
206 */
207 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len);
208
209 /**
210 * qemu_chr_fe_write_all:
211 * @buf: the data
212 * @len: the number of bytes to send
213 *
214 * Write data to a character backend from the front end. This function will
215 * send data from the front end to the back end. Unlike @qemu_chr_fe_write,
216 * this function will block if the back end cannot consume all of the data
217 * attempted to be written. This function is thread-safe.
218 *
219 * Returns: the number of bytes consumed (0 if no associated Chardev)
220 */
221 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len);
222
223 /**
224 * qemu_chr_fe_read_all:
225 * @buf: the data buffer
226 * @len: the number of bytes to read
227 *
228 * Read data to a buffer from the back end.
229 *
230 * Returns: the number of bytes read (0 if no associated Chardev)
231 */
232 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len);
233
234 /**
235 * qemu_chr_fe_ioctl:
236 * @cmd: see CHR_IOCTL_*
237 * @arg: the data associated with @cmd
238 *
239 * Issue a device specific ioctl to a backend. This function is thread-safe.
240 *
241 * Returns: if @cmd is not supported by the backend or there is no
242 * associated Chardev, -ENOTSUP, otherwise the return
243 * value depends on the semantics of @cmd
244 */
245 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg);
246
247 /**
248 * qemu_chr_fe_get_msgfd:
249 *
250 * For backends capable of fd passing, return the latest file descriptor passed
251 * by a client.
252 *
253 * Returns: -1 if fd passing isn't supported or there is no pending file
254 * descriptor. If a file descriptor is returned, subsequent calls to
255 * this function will return -1 until a client sends a new file
256 * descriptor.
257 */
258 int qemu_chr_fe_get_msgfd(CharBackend *be);
259
260 /**
261 * qemu_chr_fe_get_msgfds:
262 *
263 * For backends capable of fd passing, return the number of file received
264 * descriptors and fills the fds array up to num elements
265 *
266 * Returns: -1 if fd passing isn't supported or there are no pending file
267 * descriptors. If file descriptors are returned, subsequent calls to
268 * this function will return -1 until a client sends a new set of file
269 * descriptors.
270 */
271 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num);
272
273 /**
274 * qemu_chr_fe_set_msgfds:
275 *
276 * For backends capable of fd passing, set an array of fds to be passed with
277 * the next send operation.
278 * A subsequent call to this function before calling a write function will
279 * result in overwriting the fd array with the new value without being send.
280 * Upon writing the message the fd array is freed.
281 *
282 * Returns: -1 if fd passing isn't supported or no associated Chardev.
283 */
284 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num);
285
286 #endif /* QEMU_CHAR_FE_H */