# *-*- Mode: Python -*-*
##
+#
+# Echo back a unique integer value, and prepend to response a
+# leading sentinel byte (0xFF) the client can check scan for.
+#
+# This is used by clients talking to the guest agent over the
+# wire to ensure the stream is in sync and doesn't contain stale
+# data from previous client. It must be issued upon initial
+# connection, and after any client-side timeouts (including
+# timeouts on receiving a response to this command).
+#
+# After issuing this request, all guest agent responses should be
+# ignored until the response containing the unique integer value
+# the client passed in is returned. Receival of the 0xFF sentinel
+# byte must be handled as an indication that the client's
+# lexer/tokenizer/parser state should be flushed/reset in
+# preparation for reliably receiving the subsequent response. As
+# an optimization, clients may opt to ignore all data until a
+# sentinel value is receiving to avoid unecessary processing of
+# stale data.
+#
+# Similarly, clients should also precede this *request*
+# with a 0xFF byte to make sure the guest agent flushes any
+# partially read JSON data from a previous client connection.
+#
+# @id: randomly generated 64-bit integer
+#
+# Returns: The unique integer id passed in by the client
+#
+# Since: 1.1
+# ##
+{ 'command': 'guest-sync-delimited'
+ 'data': { 'id': 'int' },
+ 'returns': 'int' }
+
+##
# @guest-sync:
#
# Echo back a unique integer value
# partially-delivered JSON text in such a way that this response
# can be obtained.
#
+# In cases where a partial stale response was previously
+# received by the client, this cannot always be done reliably.
+# One particular scenario being if qemu-ga responses are fed
+# character-by-character into a JSON parser. In these situations,
+# using guest-sync-delimited may be optimal.
+#
+# For clients that fetch responses line by line and convert them
+# to JSON objects, guest-sync should be sufficient, but note that
+# in cases where the channel is dirty some attempts at parsing the
+# response may result in a parser error.
+#
# Such clients should also precede this command
-# with a 0xFF byte to make such the guest agent flushes any
+# with a 0xFF byte to make sure the guest agent flushes any
# partially read JSON data from a previous session.
#
# @id: randomly generated 64-bit integer
#define QGA_VIRTIO_PATH_DEFAULT "\\\\.\\Global\\org.qemu.guest_agent.0"
#endif
#define QGA_PIDFILE_DEFAULT "/var/run/qemu-ga.pid"
+#define QGA_SENTINEL_BYTE 0xFF
struct GAState {
JSONMessageParser parser;
#ifdef _WIN32
GAService service;
#endif
+ bool delimit_response;
};
-static struct GAState *ga_state;
+struct GAState *ga_state;
#ifdef _WIN32
DWORD WINAPI service_ctrl_handler(DWORD ctrl, DWORD type, LPVOID data,
}
}
+void ga_set_response_delimited(GAState *s)
+{
+ s->delimit_response = true;
+}
+
#ifndef _WIN32
static void become_daemon(const char *pidfile)
{
static int send_response(GAState *s, QObject *payload)
{
const char *buf;
- QString *payload_qstr;
+ QString *payload_qstr, *response_qstr;
GIOStatus status;
g_assert(payload && s->channel);
return -EINVAL;
}
- qstring_append_chr(payload_qstr, '\n');
- buf = qstring_get_str(payload_qstr);
+ if (s->delimit_response) {
+ s->delimit_response = false;
+ response_qstr = qstring_new();
+ qstring_append_chr(response_qstr, QGA_SENTINEL_BYTE);
+ qstring_append(response_qstr, qstring_get_str(payload_qstr));
+ QDECREF(payload_qstr);
+ } else {
+ response_qstr = payload_qstr;
+ }
+
+ qstring_append_chr(response_qstr, '\n');
+ buf = qstring_get_str(response_qstr);
status = ga_channel_write_all(s->channel, buf, strlen(buf));
- QDECREF(payload_qstr);
+ QDECREF(response_qstr);
if (status != G_IO_STATUS_NORMAL) {
return -EIO;
}
#include "qemu-queue.h"
#include "host-utils.h"
-static GAState *ga_state;
-
static void reopen_fd_to_null(int fd)
{
int nullfd;
/* register init/cleanup routines for stateful command groups */
void ga_command_state_init(GAState *s, GACommandState *cs)
{
- ga_state = s;
#if defined(CONFIG_FSFREEZE)
ga_command_state_add(cs, guest_fsfreeze_init, guest_fsfreeze_cleanup);
#endif
va_end(ap);
}
+int64_t qmp_guest_sync_delimited(int64_t id, Error **errp)
+{
+ ga_set_response_delimited(ga_state);
+ return id;
+}
+
int64_t qmp_guest_sync(int64_t id, Error **errp)
{
return id;
typedef struct GAState GAState;
typedef struct GACommandState GACommandState;
+extern GAState *ga_state;
void ga_command_state_init(GAState *s, GACommandState *cs);
void ga_command_state_add(GACommandState *cs,
void ga_disable_logging(GAState *s);
void ga_enable_logging(GAState *s);
void slog(const gchar *fmt, ...);
+void ga_set_response_delimited(GAState *s);