Debian Codegraph @

src/shared/qmp-client.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include "shared-forward.h"
5
6 typedef int (*qmp_event_callback_t)(
7 QmpClient *client,
8 const char *event,
9 sd_json_variant *data,
10 void *userdata);
11
12 typedef void (*qmp_disconnect_callback_t)(
13 QmpClient *client,
14 void *userdata);
15
16 /* Success: (result, NULL, 0). QMP error: (NULL, desc, -EIO). Transport: (NULL, NULL, -errno). */
17 typedef int (*qmp_command_callback_t)(
18 QmpClient *client,
19 sd_json_variant *result,
20 const char *error_desc,
21 int error,
22 void *userdata);
23
24 /* Bundles arguments + fds for one command. Construct fresh per invoke via the macros below. */
25 typedef struct QmpClientArgs {
26 sd_json_variant *arguments;
27 int *fds_consume;
28 size_t n_fds;
29 } QmpClientArgs;
30
31 #define QMP_CLIENT_ARGS(args_) \
32 (&(QmpClientArgs){ .arguments = (args_) })
33 #define QMP_CLIENT_ARGS_FD(args_, fd_) \
34 (&(QmpClientArgs){ .arguments = (args_), .fds_consume = (int[]){ (fd_) }, .n_fds = 1 })
35
36 /* Takes ownership of fd; handshake runs lazily on first invoke or from the event loop. */
37 int qmp_client_connect_fd(QmpClient **ret, int fd);
38
39 int qmp_client_attach_event(QmpClient *c, sd_event *event, int64_t priority);
40
41 /* Single non-blocking pump step: write → dispatch → parse → read → disconnect. Returns >0 if
42 * progress was made, 0 if idle, <0 on error (-ENOTCONN on disconnect). Same contract as
43 * sd_varlink_process(). */
44 int qmp_client_process(QmpClient *c);
45
46 /* Block on the transport fd until readable, or until timeout (USEC_INFINITY for no timeout).
47 * Same contract as sd_varlink_wait(). */
48 int qmp_client_wait(QmpClient *c, uint64_t timeout_usec);
49
50 /* True iff there are no outstanding command replies (slots set is empty). Useful as the pump-loop
51 * exit condition for callers driving the client synchronously via process() + wait(). */
52 bool qmp_client_is_idle(QmpClient *c);
53
54 /* True iff the connection is dead. Stable terminal state — once set, it stays set. */
55 bool qmp_client_is_disconnected(QmpClient *c);
56
57 void* qmp_client_set_userdata(QmpClient *c, void *userdata);
58 void* qmp_client_get_userdata(QmpClient *c);
59
60 /* Async send. Returns 0 on send (callback will fire later), negative errno on failure. If
61 * ret_slot is non-NULL, returns a reference to a QmpSlot which can be used to cancel the call
62 * (by unreffing it before the reply arrives). */
63 int qmp_client_invoke(
64 QmpClient *client,
65 QmpSlot **ret_slot,
66 const char *command,
67 QmpClientArgs *args,
68 qmp_command_callback_t callback,
69 void *userdata);
70
71 int qmp_client_call(
72 QmpClient *client,
73 const char *command,
74 QmpClientArgs *args,
75 sd_json_variant **ret_result,
76 char **reterr_error_desc);
77
78 int qmp_client_call_future(
79 QmpClient *client,
80 const char *command,
81 QmpClientArgs *args,
82 sd_future **ret);
83
84 int future_get_qmp_reply(
85 sd_future *f,
86 sd_json_variant **ret_result,
87 char **reterr_error_desc);
88
89 void qmp_client_bind_event(QmpClient *c, qmp_event_callback_t callback, void *userdata);
90 void qmp_client_bind_disconnect(QmpClient *c, qmp_disconnect_callback_t callback, void *userdata);
91 int qmp_client_set_description(QmpClient *c, const char *description);
92 sd_event* qmp_client_get_event(QmpClient *c);
93 uint64_t qmp_client_next_fdset_id(QmpClient *client);
94
95 DECLARE_TRIVIAL_REF_UNREF_FUNC(QmpClient, qmp_client);
96 DEFINE_TRIVIAL_CLEANUP_FUNC(QmpClient *, qmp_client_unref);
97
98 DECLARE_TRIVIAL_REF_UNREF_FUNC(QmpSlot, qmp_slot);
99 DEFINE_TRIVIAL_CLEANUP_FUNC(QmpSlot *, qmp_slot_unref);
100
101 QmpClient* qmp_slot_get_client(QmpSlot *slot);
102
103 /* Returns true iff any object entry in schema (result of query-qmp-schema) has a member with this
104 * name. QEMU's introspection replaces type names with opaque numeric ids, so lookup-by-type-name is
105 * impossible — but member names are real. Use only when the member name is unique in the schema. */
106 bool qmp_schema_has_member(sd_json_variant *schema, const char *member_name);