monitor: Use QEMU_CLOCK_VIRTUAL for the event queue in qtest mode
[qemu/rayw.git] / qga / commands-win32.c
blobd76327f5a3aefad2142fecb08d98198bea2e47c1
1 /*
2 * QEMU Guest Agent win32-specific command implementations
4 * Copyright IBM Corp. 2012
6 * Authors:
7 * Michael Roth <mdroth@linux.vnet.ibm.com>
8 * Gal Hammer <ghammer@redhat.com>
10 * This work is licensed under the terms of the GNU GPL, version 2 or later.
11 * See the COPYING file in the top-level directory.
14 #include "qemu/osdep.h"
15 #include <glib.h>
16 #include <wtypes.h>
17 #include <powrprof.h>
18 #include <winsock2.h>
19 #include <ws2tcpip.h>
20 #include <iptypes.h>
21 #include <iphlpapi.h>
22 #ifdef CONFIG_QGA_NTDDSCSI
23 #include <winioctl.h>
24 #include <ntddscsi.h>
25 #include <setupapi.h>
26 #include <initguid.h>
27 #endif
28 #include <lm.h>
30 #include "qga/guest-agent-core.h"
31 #include "qga/vss-win32.h"
32 #include "qga-qmp-commands.h"
33 #include "qapi/qmp/qerror.h"
34 #include "qemu/queue.h"
35 #include "qemu/host-utils.h"
36 #include "qemu/base64.h"
38 #ifndef SHTDN_REASON_FLAG_PLANNED
39 #define SHTDN_REASON_FLAG_PLANNED 0x80000000
40 #endif
42 /* multiple of 100 nanoseconds elapsed between windows baseline
43 * (1/1/1601) and Unix Epoch (1/1/1970), accounting for leap years */
44 #define W32_FT_OFFSET (10000000ULL * 60 * 60 * 24 * \
45 (365 * (1970 - 1601) + \
46 (1970 - 1601) / 4 - 3))
48 #define INVALID_SET_FILE_POINTER ((DWORD)-1)
50 typedef struct GuestFileHandle {
51 int64_t id;
52 HANDLE fh;
53 QTAILQ_ENTRY(GuestFileHandle) next;
54 } GuestFileHandle;
56 static struct {
57 QTAILQ_HEAD(, GuestFileHandle) filehandles;
58 } guest_file_state = {
59 .filehandles = QTAILQ_HEAD_INITIALIZER(guest_file_state.filehandles),
62 #define FILE_GENERIC_APPEND (FILE_GENERIC_WRITE & ~FILE_WRITE_DATA)
64 typedef struct OpenFlags {
65 const char *forms;
66 DWORD desired_access;
67 DWORD creation_disposition;
68 } OpenFlags;
69 static OpenFlags guest_file_open_modes[] = {
70 {"r", GENERIC_READ, OPEN_EXISTING},
71 {"rb", GENERIC_READ, OPEN_EXISTING},
72 {"w", GENERIC_WRITE, CREATE_ALWAYS},
73 {"wb", GENERIC_WRITE, CREATE_ALWAYS},
74 {"a", FILE_GENERIC_APPEND, OPEN_ALWAYS },
75 {"r+", GENERIC_WRITE|GENERIC_READ, OPEN_EXISTING},
76 {"rb+", GENERIC_WRITE|GENERIC_READ, OPEN_EXISTING},
77 {"r+b", GENERIC_WRITE|GENERIC_READ, OPEN_EXISTING},
78 {"w+", GENERIC_WRITE|GENERIC_READ, CREATE_ALWAYS},
79 {"wb+", GENERIC_WRITE|GENERIC_READ, CREATE_ALWAYS},
80 {"w+b", GENERIC_WRITE|GENERIC_READ, CREATE_ALWAYS},
81 {"a+", FILE_GENERIC_APPEND|GENERIC_READ, OPEN_ALWAYS },
82 {"ab+", FILE_GENERIC_APPEND|GENERIC_READ, OPEN_ALWAYS },
83 {"a+b", FILE_GENERIC_APPEND|GENERIC_READ, OPEN_ALWAYS }
86 static OpenFlags *find_open_flag(const char *mode_str)
88 int mode;
89 Error **errp = NULL;
91 for (mode = 0; mode < ARRAY_SIZE(guest_file_open_modes); ++mode) {
92 OpenFlags *flags = guest_file_open_modes + mode;
94 if (strcmp(flags->forms, mode_str) == 0) {
95 return flags;
99 error_setg(errp, "invalid file open mode '%s'", mode_str);
100 return NULL;
103 static int64_t guest_file_handle_add(HANDLE fh, Error **errp)
105 GuestFileHandle *gfh;
106 int64_t handle;
108 handle = ga_get_fd_handle(ga_state, errp);
109 if (handle < 0) {
110 return -1;
112 gfh = g_new0(GuestFileHandle, 1);
113 gfh->id = handle;
114 gfh->fh = fh;
115 QTAILQ_INSERT_TAIL(&guest_file_state.filehandles, gfh, next);
117 return handle;
120 static GuestFileHandle *guest_file_handle_find(int64_t id, Error **errp)
122 GuestFileHandle *gfh;
123 QTAILQ_FOREACH(gfh, &guest_file_state.filehandles, next) {
124 if (gfh->id == id) {
125 return gfh;
128 error_setg(errp, "handle '%" PRId64 "' has not been found", id);
129 return NULL;
132 static void handle_set_nonblocking(HANDLE fh)
134 DWORD file_type, pipe_state;
135 file_type = GetFileType(fh);
136 if (file_type != FILE_TYPE_PIPE) {
137 return;
139 /* If file_type == FILE_TYPE_PIPE, according to MSDN
140 * the specified file is socket or named pipe */
141 if (!GetNamedPipeHandleState(fh, &pipe_state, NULL,
142 NULL, NULL, NULL, 0)) {
143 return;
145 /* The fd is named pipe fd */
146 if (pipe_state & PIPE_NOWAIT) {
147 return;
150 pipe_state |= PIPE_NOWAIT;
151 SetNamedPipeHandleState(fh, &pipe_state, NULL, NULL);
154 int64_t qmp_guest_file_open(const char *path, bool has_mode,
155 const char *mode, Error **errp)
157 int64_t fd;
158 HANDLE fh;
159 HANDLE templ_file = NULL;
160 DWORD share_mode = FILE_SHARE_READ;
161 DWORD flags_and_attr = FILE_ATTRIBUTE_NORMAL;
162 LPSECURITY_ATTRIBUTES sa_attr = NULL;
163 OpenFlags *guest_flags;
165 if (!has_mode) {
166 mode = "r";
168 slog("guest-file-open called, filepath: %s, mode: %s", path, mode);
169 guest_flags = find_open_flag(mode);
170 if (guest_flags == NULL) {
171 error_setg(errp, "invalid file open mode");
172 return -1;
175 fh = CreateFile(path, guest_flags->desired_access, share_mode, sa_attr,
176 guest_flags->creation_disposition, flags_and_attr,
177 templ_file);
178 if (fh == INVALID_HANDLE_VALUE) {
179 error_setg_win32(errp, GetLastError(), "failed to open file '%s'",
180 path);
181 return -1;
184 /* set fd non-blocking to avoid common use cases (like reading from a
185 * named pipe) from hanging the agent
187 handle_set_nonblocking(fh);
189 fd = guest_file_handle_add(fh, errp);
190 if (fd < 0) {
191 CloseHandle(fh);
192 error_setg(errp, "failed to add handle to qmp handle table");
193 return -1;
196 slog("guest-file-open, handle: % " PRId64, fd);
197 return fd;
200 void qmp_guest_file_close(int64_t handle, Error **errp)
202 bool ret;
203 GuestFileHandle *gfh = guest_file_handle_find(handle, errp);
204 slog("guest-file-close called, handle: %" PRId64, handle);
205 if (gfh == NULL) {
206 return;
208 ret = CloseHandle(gfh->fh);
209 if (!ret) {
210 error_setg_win32(errp, GetLastError(), "failed close handle");
211 return;
214 QTAILQ_REMOVE(&guest_file_state.filehandles, gfh, next);
215 g_free(gfh);
218 static void acquire_privilege(const char *name, Error **errp)
220 HANDLE token = NULL;
221 TOKEN_PRIVILEGES priv;
222 Error *local_err = NULL;
224 if (OpenProcessToken(GetCurrentProcess(),
225 TOKEN_ADJUST_PRIVILEGES|TOKEN_QUERY, &token))
227 if (!LookupPrivilegeValue(NULL, name, &priv.Privileges[0].Luid)) {
228 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
229 "no luid for requested privilege");
230 goto out;
233 priv.PrivilegeCount = 1;
234 priv.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;
236 if (!AdjustTokenPrivileges(token, FALSE, &priv, 0, NULL, 0)) {
237 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
238 "unable to acquire requested privilege");
239 goto out;
242 } else {
243 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
244 "failed to open privilege token");
247 out:
248 if (token) {
249 CloseHandle(token);
251 if (local_err) {
252 error_propagate(errp, local_err);
256 static void execute_async(DWORD WINAPI (*func)(LPVOID), LPVOID opaque,
257 Error **errp)
259 Error *local_err = NULL;
261 HANDLE thread = CreateThread(NULL, 0, func, opaque, 0, NULL);
262 if (!thread) {
263 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
264 "failed to dispatch asynchronous command");
265 error_propagate(errp, local_err);
269 void qmp_guest_shutdown(bool has_mode, const char *mode, Error **errp)
271 Error *local_err = NULL;
272 UINT shutdown_flag = EWX_FORCE;
274 slog("guest-shutdown called, mode: %s", mode);
276 if (!has_mode || strcmp(mode, "powerdown") == 0) {
277 shutdown_flag |= EWX_POWEROFF;
278 } else if (strcmp(mode, "halt") == 0) {
279 shutdown_flag |= EWX_SHUTDOWN;
280 } else if (strcmp(mode, "reboot") == 0) {
281 shutdown_flag |= EWX_REBOOT;
282 } else {
283 error_setg(errp, QERR_INVALID_PARAMETER_VALUE, "mode",
284 "halt|powerdown|reboot");
285 return;
288 /* Request a shutdown privilege, but try to shut down the system
289 anyway. */
290 acquire_privilege(SE_SHUTDOWN_NAME, &local_err);
291 if (local_err) {
292 error_propagate(errp, local_err);
293 return;
296 if (!ExitWindowsEx(shutdown_flag, SHTDN_REASON_FLAG_PLANNED)) {
297 slog("guest-shutdown failed: %lu", GetLastError());
298 error_setg(errp, QERR_UNDEFINED_ERROR);
302 GuestFileRead *qmp_guest_file_read(int64_t handle, bool has_count,
303 int64_t count, Error **errp)
305 GuestFileRead *read_data = NULL;
306 guchar *buf;
307 HANDLE fh;
308 bool is_ok;
309 DWORD read_count;
310 GuestFileHandle *gfh = guest_file_handle_find(handle, errp);
312 if (!gfh) {
313 return NULL;
315 if (!has_count) {
316 count = QGA_READ_COUNT_DEFAULT;
317 } else if (count < 0) {
318 error_setg(errp, "value '%" PRId64
319 "' is invalid for argument count", count);
320 return NULL;
323 fh = gfh->fh;
324 buf = g_malloc0(count+1);
325 is_ok = ReadFile(fh, buf, count, &read_count, NULL);
326 if (!is_ok) {
327 error_setg_win32(errp, GetLastError(), "failed to read file");
328 slog("guest-file-read failed, handle %" PRId64, handle);
329 } else {
330 buf[read_count] = 0;
331 read_data = g_new0(GuestFileRead, 1);
332 read_data->count = (size_t)read_count;
333 read_data->eof = read_count == 0;
335 if (read_count != 0) {
336 read_data->buf_b64 = g_base64_encode(buf, read_count);
339 g_free(buf);
341 return read_data;
344 GuestFileWrite *qmp_guest_file_write(int64_t handle, const char *buf_b64,
345 bool has_count, int64_t count,
346 Error **errp)
348 GuestFileWrite *write_data = NULL;
349 guchar *buf;
350 gsize buf_len;
351 bool is_ok;
352 DWORD write_count;
353 GuestFileHandle *gfh = guest_file_handle_find(handle, errp);
354 HANDLE fh;
356 if (!gfh) {
357 return NULL;
359 fh = gfh->fh;
360 buf = qbase64_decode(buf_b64, -1, &buf_len, errp);
361 if (!buf) {
362 return NULL;
365 if (!has_count) {
366 count = buf_len;
367 } else if (count < 0 || count > buf_len) {
368 error_setg(errp, "value '%" PRId64
369 "' is invalid for argument count", count);
370 goto done;
373 is_ok = WriteFile(fh, buf, count, &write_count, NULL);
374 if (!is_ok) {
375 error_setg_win32(errp, GetLastError(), "failed to write to file");
376 slog("guest-file-write-failed, handle: %" PRId64, handle);
377 } else {
378 write_data = g_new0(GuestFileWrite, 1);
379 write_data->count = (size_t) write_count;
382 done:
383 g_free(buf);
384 return write_data;
387 GuestFileSeek *qmp_guest_file_seek(int64_t handle, int64_t offset,
388 GuestFileWhence *whence_code,
389 Error **errp)
391 GuestFileHandle *gfh;
392 GuestFileSeek *seek_data;
393 HANDLE fh;
394 LARGE_INTEGER new_pos, off_pos;
395 off_pos.QuadPart = offset;
396 BOOL res;
397 int whence;
398 Error *err = NULL;
400 gfh = guest_file_handle_find(handle, errp);
401 if (!gfh) {
402 return NULL;
405 /* We stupidly exposed 'whence':'int' in our qapi */
406 whence = ga_parse_whence(whence_code, &err);
407 if (err) {
408 error_propagate(errp, err);
409 return NULL;
412 fh = gfh->fh;
413 res = SetFilePointerEx(fh, off_pos, &new_pos, whence);
414 if (!res) {
415 error_setg_win32(errp, GetLastError(), "failed to seek file");
416 return NULL;
418 seek_data = g_new0(GuestFileSeek, 1);
419 seek_data->position = new_pos.QuadPart;
420 return seek_data;
423 void qmp_guest_file_flush(int64_t handle, Error **errp)
425 HANDLE fh;
426 GuestFileHandle *gfh = guest_file_handle_find(handle, errp);
427 if (!gfh) {
428 return;
431 fh = gfh->fh;
432 if (!FlushFileBuffers(fh)) {
433 error_setg_win32(errp, GetLastError(), "failed to flush file");
437 #ifdef CONFIG_QGA_NTDDSCSI
439 static STORAGE_BUS_TYPE win2qemu[] = {
440 [BusTypeUnknown] = GUEST_DISK_BUS_TYPE_UNKNOWN,
441 [BusTypeScsi] = GUEST_DISK_BUS_TYPE_SCSI,
442 [BusTypeAtapi] = GUEST_DISK_BUS_TYPE_IDE,
443 [BusTypeAta] = GUEST_DISK_BUS_TYPE_IDE,
444 [BusType1394] = GUEST_DISK_BUS_TYPE_IEEE1394,
445 [BusTypeSsa] = GUEST_DISK_BUS_TYPE_SSA,
446 [BusTypeFibre] = GUEST_DISK_BUS_TYPE_SSA,
447 [BusTypeUsb] = GUEST_DISK_BUS_TYPE_USB,
448 [BusTypeRAID] = GUEST_DISK_BUS_TYPE_RAID,
449 #if (_WIN32_WINNT >= 0x0600)
450 [BusTypeiScsi] = GUEST_DISK_BUS_TYPE_ISCSI,
451 [BusTypeSas] = GUEST_DISK_BUS_TYPE_SAS,
452 [BusTypeSata] = GUEST_DISK_BUS_TYPE_SATA,
453 [BusTypeSd] = GUEST_DISK_BUS_TYPE_SD,
454 [BusTypeMmc] = GUEST_DISK_BUS_TYPE_MMC,
455 #endif
456 #if (_WIN32_WINNT >= 0x0601)
457 [BusTypeVirtual] = GUEST_DISK_BUS_TYPE_VIRTUAL,
458 [BusTypeFileBackedVirtual] = GUEST_DISK_BUS_TYPE_FILE_BACKED_VIRTUAL,
459 #endif
462 static GuestDiskBusType find_bus_type(STORAGE_BUS_TYPE bus)
464 if (bus > ARRAY_SIZE(win2qemu) || (int)bus < 0) {
465 return GUEST_DISK_BUS_TYPE_UNKNOWN;
467 return win2qemu[(int)bus];
470 DEFINE_GUID(GUID_DEVINTERFACE_VOLUME,
471 0x53f5630dL, 0xb6bf, 0x11d0, 0x94, 0xf2,
472 0x00, 0xa0, 0xc9, 0x1e, 0xfb, 0x8b);
474 static GuestPCIAddress *get_pci_info(char *guid, Error **errp)
476 HDEVINFO dev_info;
477 SP_DEVINFO_DATA dev_info_data;
478 DWORD size = 0;
479 int i;
480 char dev_name[MAX_PATH];
481 char *buffer = NULL;
482 GuestPCIAddress *pci = NULL;
483 char *name = g_strdup(&guid[4]);
485 if (!QueryDosDevice(name, dev_name, ARRAY_SIZE(dev_name))) {
486 error_setg_win32(errp, GetLastError(), "failed to get dos device name");
487 goto out;
490 dev_info = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, 0, 0,
491 DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
492 if (dev_info == INVALID_HANDLE_VALUE) {
493 error_setg_win32(errp, GetLastError(), "failed to get devices tree");
494 goto out;
497 dev_info_data.cbSize = sizeof(SP_DEVINFO_DATA);
498 for (i = 0; SetupDiEnumDeviceInfo(dev_info, i, &dev_info_data); i++) {
499 DWORD addr, bus, slot, func, dev, data, size2;
500 while (!SetupDiGetDeviceRegistryProperty(dev_info, &dev_info_data,
501 SPDRP_PHYSICAL_DEVICE_OBJECT_NAME,
502 &data, (PBYTE)buffer, size,
503 &size2)) {
504 size = MAX(size, size2);
505 if (GetLastError() == ERROR_INSUFFICIENT_BUFFER) {
506 g_free(buffer);
507 /* Double the size to avoid problems on
508 * W2k MBCS systems per KB 888609.
509 * https://support.microsoft.com/en-us/kb/259695 */
510 buffer = g_malloc(size * 2);
511 } else {
512 error_setg_win32(errp, GetLastError(),
513 "failed to get device name");
514 goto out;
518 if (g_strcmp0(buffer, dev_name)) {
519 continue;
522 /* There is no need to allocate buffer in the next functions. The size
523 * is known and ULONG according to
524 * https://support.microsoft.com/en-us/kb/253232
525 * https://msdn.microsoft.com/en-us/library/windows/hardware/ff543095(v=vs.85).aspx
527 if (!SetupDiGetDeviceRegistryProperty(dev_info, &dev_info_data,
528 SPDRP_BUSNUMBER, &data, (PBYTE)&bus, size, NULL)) {
529 break;
532 /* The function retrieves the device's address. This value will be
533 * transformed into device function and number */
534 if (!SetupDiGetDeviceRegistryProperty(dev_info, &dev_info_data,
535 SPDRP_ADDRESS, &data, (PBYTE)&addr, size, NULL)) {
536 break;
539 /* This call returns UINumber of DEVICE_CAPABILITIES structure.
540 * This number is typically a user-perceived slot number. */
541 if (!SetupDiGetDeviceRegistryProperty(dev_info, &dev_info_data,
542 SPDRP_UI_NUMBER, &data, (PBYTE)&slot, size, NULL)) {
543 break;
546 /* SetupApi gives us the same information as driver with
547 * IoGetDeviceProperty. According to Microsoft
548 * https://support.microsoft.com/en-us/kb/253232
549 * FunctionNumber = (USHORT)((propertyAddress) & 0x0000FFFF);
550 * DeviceNumber = (USHORT)(((propertyAddress) >> 16) & 0x0000FFFF);
551 * SPDRP_ADDRESS is propertyAddress, so we do the same.*/
553 func = addr & 0x0000FFFF;
554 dev = (addr >> 16) & 0x0000FFFF;
555 pci = g_malloc0(sizeof(*pci));
556 pci->domain = dev;
557 pci->slot = slot;
558 pci->function = func;
559 pci->bus = bus;
560 break;
562 out:
563 g_free(buffer);
564 g_free(name);
565 return pci;
568 static int get_disk_bus_type(HANDLE vol_h, Error **errp)
570 STORAGE_PROPERTY_QUERY query;
571 STORAGE_DEVICE_DESCRIPTOR *dev_desc, buf;
572 DWORD received;
574 dev_desc = &buf;
575 dev_desc->Size = sizeof(buf);
576 query.PropertyId = StorageDeviceProperty;
577 query.QueryType = PropertyStandardQuery;
579 if (!DeviceIoControl(vol_h, IOCTL_STORAGE_QUERY_PROPERTY, &query,
580 sizeof(STORAGE_PROPERTY_QUERY), dev_desc,
581 dev_desc->Size, &received, NULL)) {
582 error_setg_win32(errp, GetLastError(), "failed to get bus type");
583 return -1;
586 return dev_desc->BusType;
589 /* VSS provider works with volumes, thus there is no difference if
590 * the volume consist of spanned disks. Info about the first disk in the
591 * volume is returned for the spanned disk group (LVM) */
592 static GuestDiskAddressList *build_guest_disk_info(char *guid, Error **errp)
594 GuestDiskAddressList *list = NULL;
595 GuestDiskAddress *disk;
596 SCSI_ADDRESS addr, *scsi_ad;
597 DWORD len;
598 int bus;
599 HANDLE vol_h;
601 scsi_ad = &addr;
602 char *name = g_strndup(guid, strlen(guid)-1);
604 vol_h = CreateFile(name, 0, FILE_SHARE_READ, NULL, OPEN_EXISTING,
605 0, NULL);
606 if (vol_h == INVALID_HANDLE_VALUE) {
607 error_setg_win32(errp, GetLastError(), "failed to open volume");
608 goto out_free;
611 bus = get_disk_bus_type(vol_h, errp);
612 if (bus < 0) {
613 goto out_close;
616 disk = g_malloc0(sizeof(*disk));
617 disk->bus_type = find_bus_type(bus);
618 if (bus == BusTypeScsi || bus == BusTypeAta || bus == BusTypeRAID
619 #if (_WIN32_WINNT >= 0x0600)
620 /* This bus type is not supported before Windows Server 2003 SP1 */
621 || bus == BusTypeSas
622 #endif
624 /* We are able to use the same ioctls for different bus types
625 * according to Microsoft docs
626 * https://technet.microsoft.com/en-us/library/ee851589(v=ws.10).aspx */
627 if (DeviceIoControl(vol_h, IOCTL_SCSI_GET_ADDRESS, NULL, 0, scsi_ad,
628 sizeof(SCSI_ADDRESS), &len, NULL)) {
629 disk->unit = addr.Lun;
630 disk->target = addr.TargetId;
631 disk->bus = addr.PathId;
632 disk->pci_controller = get_pci_info(name, errp);
634 /* We do not set error in this case, because we still have enough
635 * information about volume. */
636 } else {
637 disk->pci_controller = NULL;
640 list = g_malloc0(sizeof(*list));
641 list->value = disk;
642 list->next = NULL;
643 out_close:
644 CloseHandle(vol_h);
645 out_free:
646 g_free(name);
647 return list;
650 #else
652 static GuestDiskAddressList *build_guest_disk_info(char *guid, Error **errp)
654 return NULL;
657 #endif /* CONFIG_QGA_NTDDSCSI */
659 static GuestFilesystemInfo *build_guest_fsinfo(char *guid, Error **errp)
661 DWORD info_size;
662 char mnt, *mnt_point;
663 char fs_name[32];
664 char vol_info[MAX_PATH+1];
665 size_t len;
666 GuestFilesystemInfo *fs = NULL;
668 GetVolumePathNamesForVolumeName(guid, (LPCH)&mnt, 0, &info_size);
669 if (GetLastError() != ERROR_MORE_DATA) {
670 error_setg_win32(errp, GetLastError(), "failed to get volume name");
671 return NULL;
674 mnt_point = g_malloc(info_size + 1);
675 if (!GetVolumePathNamesForVolumeName(guid, mnt_point, info_size,
676 &info_size)) {
677 error_setg_win32(errp, GetLastError(), "failed to get volume name");
678 goto free;
681 len = strlen(mnt_point);
682 mnt_point[len] = '\\';
683 mnt_point[len+1] = 0;
684 if (!GetVolumeInformation(mnt_point, vol_info, sizeof(vol_info), NULL, NULL,
685 NULL, (LPSTR)&fs_name, sizeof(fs_name))) {
686 if (GetLastError() != ERROR_NOT_READY) {
687 error_setg_win32(errp, GetLastError(), "failed to get volume info");
689 goto free;
692 fs_name[sizeof(fs_name) - 1] = 0;
693 fs = g_malloc(sizeof(*fs));
694 fs->name = g_strdup(guid);
695 if (len == 0) {
696 fs->mountpoint = g_strdup("System Reserved");
697 } else {
698 fs->mountpoint = g_strndup(mnt_point, len);
700 fs->type = g_strdup(fs_name);
701 fs->disk = build_guest_disk_info(guid, errp);
702 free:
703 g_free(mnt_point);
704 return fs;
707 GuestFilesystemInfoList *qmp_guest_get_fsinfo(Error **errp)
709 HANDLE vol_h;
710 GuestFilesystemInfoList *new, *ret = NULL;
711 char guid[256];
713 vol_h = FindFirstVolume(guid, sizeof(guid));
714 if (vol_h == INVALID_HANDLE_VALUE) {
715 error_setg_win32(errp, GetLastError(), "failed to find any volume");
716 return NULL;
719 do {
720 GuestFilesystemInfo *info = build_guest_fsinfo(guid, errp);
721 if (info == NULL) {
722 continue;
724 new = g_malloc(sizeof(*ret));
725 new->value = info;
726 new->next = ret;
727 ret = new;
728 } while (FindNextVolume(vol_h, guid, sizeof(guid)));
730 if (GetLastError() != ERROR_NO_MORE_FILES) {
731 error_setg_win32(errp, GetLastError(), "failed to find next volume");
734 FindVolumeClose(vol_h);
735 return ret;
739 * Return status of freeze/thaw
741 GuestFsfreezeStatus qmp_guest_fsfreeze_status(Error **errp)
743 if (!vss_initialized()) {
744 error_setg(errp, QERR_UNSUPPORTED);
745 return 0;
748 if (ga_is_frozen(ga_state)) {
749 return GUEST_FSFREEZE_STATUS_FROZEN;
752 return GUEST_FSFREEZE_STATUS_THAWED;
756 * Freeze local file systems using Volume Shadow-copy Service.
757 * The frozen state is limited for up to 10 seconds by VSS.
759 int64_t qmp_guest_fsfreeze_freeze(Error **errp)
761 int i;
762 Error *local_err = NULL;
764 if (!vss_initialized()) {
765 error_setg(errp, QERR_UNSUPPORTED);
766 return 0;
769 slog("guest-fsfreeze called");
771 /* cannot risk guest agent blocking itself on a write in this state */
772 ga_set_frozen(ga_state);
774 qga_vss_fsfreeze(&i, &local_err, true);
775 if (local_err) {
776 error_propagate(errp, local_err);
777 goto error;
780 return i;
782 error:
783 local_err = NULL;
784 qmp_guest_fsfreeze_thaw(&local_err);
785 if (local_err) {
786 g_debug("cleanup thaw: %s", error_get_pretty(local_err));
787 error_free(local_err);
789 return 0;
792 int64_t qmp_guest_fsfreeze_freeze_list(bool has_mountpoints,
793 strList *mountpoints,
794 Error **errp)
796 error_setg(errp, QERR_UNSUPPORTED);
798 return 0;
802 * Thaw local file systems using Volume Shadow-copy Service.
804 int64_t qmp_guest_fsfreeze_thaw(Error **errp)
806 int i;
808 if (!vss_initialized()) {
809 error_setg(errp, QERR_UNSUPPORTED);
810 return 0;
813 qga_vss_fsfreeze(&i, errp, false);
815 ga_unset_frozen(ga_state);
816 return i;
819 static void guest_fsfreeze_cleanup(void)
821 Error *err = NULL;
823 if (!vss_initialized()) {
824 return;
827 if (ga_is_frozen(ga_state) == GUEST_FSFREEZE_STATUS_FROZEN) {
828 qmp_guest_fsfreeze_thaw(&err);
829 if (err) {
830 slog("failed to clean up frozen filesystems: %s",
831 error_get_pretty(err));
832 error_free(err);
836 vss_deinit(true);
840 * Walk list of mounted file systems in the guest, and discard unused
841 * areas.
843 GuestFilesystemTrimResponse *
844 qmp_guest_fstrim(bool has_minimum, int64_t minimum, Error **errp)
846 error_setg(errp, QERR_UNSUPPORTED);
847 return NULL;
850 typedef enum {
851 GUEST_SUSPEND_MODE_DISK,
852 GUEST_SUSPEND_MODE_RAM
853 } GuestSuspendMode;
855 static void check_suspend_mode(GuestSuspendMode mode, Error **errp)
857 SYSTEM_POWER_CAPABILITIES sys_pwr_caps;
858 Error *local_err = NULL;
860 ZeroMemory(&sys_pwr_caps, sizeof(sys_pwr_caps));
861 if (!GetPwrCapabilities(&sys_pwr_caps)) {
862 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
863 "failed to determine guest suspend capabilities");
864 goto out;
867 switch (mode) {
868 case GUEST_SUSPEND_MODE_DISK:
869 if (!sys_pwr_caps.SystemS4) {
870 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
871 "suspend-to-disk not supported by OS");
873 break;
874 case GUEST_SUSPEND_MODE_RAM:
875 if (!sys_pwr_caps.SystemS3) {
876 error_setg(&local_err, QERR_QGA_COMMAND_FAILED,
877 "suspend-to-ram not supported by OS");
879 break;
880 default:
881 error_setg(&local_err, QERR_INVALID_PARAMETER_VALUE, "mode",
882 "GuestSuspendMode");
885 out:
886 if (local_err) {
887 error_propagate(errp, local_err);
891 static DWORD WINAPI do_suspend(LPVOID opaque)
893 GuestSuspendMode *mode = opaque;
894 DWORD ret = 0;
896 if (!SetSuspendState(*mode == GUEST_SUSPEND_MODE_DISK, TRUE, TRUE)) {
897 slog("failed to suspend guest, %lu", GetLastError());
898 ret = -1;
900 g_free(mode);
901 return ret;
904 void qmp_guest_suspend_disk(Error **errp)
906 Error *local_err = NULL;
907 GuestSuspendMode *mode = g_new(GuestSuspendMode, 1);
909 *mode = GUEST_SUSPEND_MODE_DISK;
910 check_suspend_mode(*mode, &local_err);
911 acquire_privilege(SE_SHUTDOWN_NAME, &local_err);
912 execute_async(do_suspend, mode, &local_err);
914 if (local_err) {
915 error_propagate(errp, local_err);
916 g_free(mode);
920 void qmp_guest_suspend_ram(Error **errp)
922 Error *local_err = NULL;
923 GuestSuspendMode *mode = g_new(GuestSuspendMode, 1);
925 *mode = GUEST_SUSPEND_MODE_RAM;
926 check_suspend_mode(*mode, &local_err);
927 acquire_privilege(SE_SHUTDOWN_NAME, &local_err);
928 execute_async(do_suspend, mode, &local_err);
930 if (local_err) {
931 error_propagate(errp, local_err);
932 g_free(mode);
936 void qmp_guest_suspend_hybrid(Error **errp)
938 error_setg(errp, QERR_UNSUPPORTED);
941 static IP_ADAPTER_ADDRESSES *guest_get_adapters_addresses(Error **errp)
943 IP_ADAPTER_ADDRESSES *adptr_addrs = NULL;
944 ULONG adptr_addrs_len = 0;
945 DWORD ret;
947 /* Call the first time to get the adptr_addrs_len. */
948 GetAdaptersAddresses(AF_UNSPEC, GAA_FLAG_INCLUDE_PREFIX,
949 NULL, adptr_addrs, &adptr_addrs_len);
951 adptr_addrs = g_malloc(adptr_addrs_len);
952 ret = GetAdaptersAddresses(AF_UNSPEC, GAA_FLAG_INCLUDE_PREFIX,
953 NULL, adptr_addrs, &adptr_addrs_len);
954 if (ret != ERROR_SUCCESS) {
955 error_setg_win32(errp, ret, "failed to get adapters addresses");
956 g_free(adptr_addrs);
957 adptr_addrs = NULL;
959 return adptr_addrs;
962 static char *guest_wctomb_dup(WCHAR *wstr)
964 char *str;
965 size_t i;
967 i = wcslen(wstr) + 1;
968 str = g_malloc(i);
969 WideCharToMultiByte(CP_ACP, WC_COMPOSITECHECK,
970 wstr, -1, str, i, NULL, NULL);
971 return str;
974 static char *guest_addr_to_str(IP_ADAPTER_UNICAST_ADDRESS *ip_addr,
975 Error **errp)
977 char addr_str[INET6_ADDRSTRLEN + INET_ADDRSTRLEN];
978 DWORD len;
979 int ret;
981 if (ip_addr->Address.lpSockaddr->sa_family == AF_INET ||
982 ip_addr->Address.lpSockaddr->sa_family == AF_INET6) {
983 len = sizeof(addr_str);
984 ret = WSAAddressToString(ip_addr->Address.lpSockaddr,
985 ip_addr->Address.iSockaddrLength,
986 NULL,
987 addr_str,
988 &len);
989 if (ret != 0) {
990 error_setg_win32(errp, WSAGetLastError(),
991 "failed address presentation form conversion");
992 return NULL;
994 return g_strdup(addr_str);
996 return NULL;
999 #if (_WIN32_WINNT >= 0x0600)
1000 static int64_t guest_ip_prefix(IP_ADAPTER_UNICAST_ADDRESS *ip_addr)
1002 /* For Windows Vista/2008 and newer, use the OnLinkPrefixLength
1003 * field to obtain the prefix.
1005 return ip_addr->OnLinkPrefixLength;
1007 #else
1008 /* When using the Windows XP and 2003 build environment, do the best we can to
1009 * figure out the prefix.
1011 static IP_ADAPTER_INFO *guest_get_adapters_info(void)
1013 IP_ADAPTER_INFO *adptr_info = NULL;
1014 ULONG adptr_info_len = 0;
1015 DWORD ret;
1017 /* Call the first time to get the adptr_info_len. */
1018 GetAdaptersInfo(adptr_info, &adptr_info_len);
1020 adptr_info = g_malloc(adptr_info_len);
1021 ret = GetAdaptersInfo(adptr_info, &adptr_info_len);
1022 if (ret != ERROR_SUCCESS) {
1023 g_free(adptr_info);
1024 adptr_info = NULL;
1026 return adptr_info;
1029 static int64_t guest_ip_prefix(IP_ADAPTER_UNICAST_ADDRESS *ip_addr)
1031 int64_t prefix = -1; /* Use for AF_INET6 and unknown/undetermined values. */
1032 IP_ADAPTER_INFO *adptr_info, *info;
1033 IP_ADDR_STRING *ip;
1034 struct in_addr *p;
1036 if (ip_addr->Address.lpSockaddr->sa_family != AF_INET) {
1037 return prefix;
1039 adptr_info = guest_get_adapters_info();
1040 if (adptr_info == NULL) {
1041 return prefix;
1044 /* Match up the passed in ip_addr with one found in adaptr_info.
1045 * The matching one in adptr_info will have the netmask.
1047 p = &((struct sockaddr_in *)ip_addr->Address.lpSockaddr)->sin_addr;
1048 for (info = adptr_info; info; info = info->Next) {
1049 for (ip = &info->IpAddressList; ip; ip = ip->Next) {
1050 if (p->S_un.S_addr == inet_addr(ip->IpAddress.String)) {
1051 prefix = ctpop32(inet_addr(ip->IpMask.String));
1052 goto out;
1056 out:
1057 g_free(adptr_info);
1058 return prefix;
1060 #endif
1062 GuestNetworkInterfaceList *qmp_guest_network_get_interfaces(Error **errp)
1064 IP_ADAPTER_ADDRESSES *adptr_addrs, *addr;
1065 IP_ADAPTER_UNICAST_ADDRESS *ip_addr = NULL;
1066 GuestNetworkInterfaceList *head = NULL, *cur_item = NULL;
1067 GuestIpAddressList *head_addr, *cur_addr;
1068 GuestNetworkInterfaceList *info;
1069 GuestIpAddressList *address_item = NULL;
1070 unsigned char *mac_addr;
1071 char *addr_str;
1072 WORD wsa_version;
1073 WSADATA wsa_data;
1074 int ret;
1076 adptr_addrs = guest_get_adapters_addresses(errp);
1077 if (adptr_addrs == NULL) {
1078 return NULL;
1081 /* Make WSA APIs available. */
1082 wsa_version = MAKEWORD(2, 2);
1083 ret = WSAStartup(wsa_version, &wsa_data);
1084 if (ret != 0) {
1085 error_setg_win32(errp, ret, "failed socket startup");
1086 goto out;
1089 for (addr = adptr_addrs; addr; addr = addr->Next) {
1090 info = g_malloc0(sizeof(*info));
1092 if (cur_item == NULL) {
1093 head = cur_item = info;
1094 } else {
1095 cur_item->next = info;
1096 cur_item = info;
1099 info->value = g_malloc0(sizeof(*info->value));
1100 info->value->name = guest_wctomb_dup(addr->FriendlyName);
1102 if (addr->PhysicalAddressLength != 0) {
1103 mac_addr = addr->PhysicalAddress;
1105 info->value->hardware_address =
1106 g_strdup_printf("%02x:%02x:%02x:%02x:%02x:%02x",
1107 (int) mac_addr[0], (int) mac_addr[1],
1108 (int) mac_addr[2], (int) mac_addr[3],
1109 (int) mac_addr[4], (int) mac_addr[5]);
1111 info->value->has_hardware_address = true;
1114 head_addr = NULL;
1115 cur_addr = NULL;
1116 for (ip_addr = addr->FirstUnicastAddress;
1117 ip_addr;
1118 ip_addr = ip_addr->Next) {
1119 addr_str = guest_addr_to_str(ip_addr, errp);
1120 if (addr_str == NULL) {
1121 continue;
1124 address_item = g_malloc0(sizeof(*address_item));
1126 if (!cur_addr) {
1127 head_addr = cur_addr = address_item;
1128 } else {
1129 cur_addr->next = address_item;
1130 cur_addr = address_item;
1133 address_item->value = g_malloc0(sizeof(*address_item->value));
1134 address_item->value->ip_address = addr_str;
1135 address_item->value->prefix = guest_ip_prefix(ip_addr);
1136 if (ip_addr->Address.lpSockaddr->sa_family == AF_INET) {
1137 address_item->value->ip_address_type =
1138 GUEST_IP_ADDRESS_TYPE_IPV4;
1139 } else if (ip_addr->Address.lpSockaddr->sa_family == AF_INET6) {
1140 address_item->value->ip_address_type =
1141 GUEST_IP_ADDRESS_TYPE_IPV6;
1144 if (head_addr) {
1145 info->value->has_ip_addresses = true;
1146 info->value->ip_addresses = head_addr;
1149 WSACleanup();
1150 out:
1151 g_free(adptr_addrs);
1152 return head;
1155 int64_t qmp_guest_get_time(Error **errp)
1157 SYSTEMTIME ts = {0};
1158 int64_t time_ns;
1159 FILETIME tf;
1161 GetSystemTime(&ts);
1162 if (ts.wYear < 1601 || ts.wYear > 30827) {
1163 error_setg(errp, "Failed to get time");
1164 return -1;
1167 if (!SystemTimeToFileTime(&ts, &tf)) {
1168 error_setg(errp, "Failed to convert system time: %d", (int)GetLastError());
1169 return -1;
1172 time_ns = ((((int64_t)tf.dwHighDateTime << 32) | tf.dwLowDateTime)
1173 - W32_FT_OFFSET) * 100;
1175 return time_ns;
1178 void qmp_guest_set_time(bool has_time, int64_t time_ns, Error **errp)
1180 Error *local_err = NULL;
1181 SYSTEMTIME ts;
1182 FILETIME tf;
1183 LONGLONG time;
1185 if (!has_time) {
1186 /* Unfortunately, Windows libraries don't provide an easy way to access
1187 * RTC yet:
1189 * https://msdn.microsoft.com/en-us/library/aa908981.aspx
1191 error_setg(errp, "Time argument is required on this platform");
1192 return;
1195 /* Validate time passed by user. */
1196 if (time_ns < 0 || time_ns / 100 > INT64_MAX - W32_FT_OFFSET) {
1197 error_setg(errp, "Time %" PRId64 "is invalid", time_ns);
1198 return;
1201 time = time_ns / 100 + W32_FT_OFFSET;
1203 tf.dwLowDateTime = (DWORD) time;
1204 tf.dwHighDateTime = (DWORD) (time >> 32);
1206 if (!FileTimeToSystemTime(&tf, &ts)) {
1207 error_setg(errp, "Failed to convert system time %d",
1208 (int)GetLastError());
1209 return;
1212 acquire_privilege(SE_SYSTEMTIME_NAME, &local_err);
1213 if (local_err) {
1214 error_propagate(errp, local_err);
1215 return;
1218 if (!SetSystemTime(&ts)) {
1219 error_setg(errp, "Failed to set time to guest: %d", (int)GetLastError());
1220 return;
1224 GuestLogicalProcessorList *qmp_guest_get_vcpus(Error **errp)
1226 PSYSTEM_LOGICAL_PROCESSOR_INFORMATION pslpi, ptr;
1227 DWORD length;
1228 GuestLogicalProcessorList *head, **link;
1229 Error *local_err = NULL;
1230 int64_t current;
1232 ptr = pslpi = NULL;
1233 length = 0;
1234 current = 0;
1235 head = NULL;
1236 link = &head;
1238 if ((GetLogicalProcessorInformation(pslpi, &length) == FALSE) &&
1239 (GetLastError() == ERROR_INSUFFICIENT_BUFFER) &&
1240 (length > sizeof(SYSTEM_LOGICAL_PROCESSOR_INFORMATION))) {
1241 ptr = pslpi = g_malloc0(length);
1242 if (GetLogicalProcessorInformation(pslpi, &length) == FALSE) {
1243 error_setg(&local_err, "Failed to get processor information: %d",
1244 (int)GetLastError());
1246 } else {
1247 error_setg(&local_err,
1248 "Failed to get processor information buffer length: %d",
1249 (int)GetLastError());
1252 while ((local_err == NULL) && (length > 0)) {
1253 if (pslpi->Relationship == RelationProcessorCore) {
1254 ULONG_PTR cpu_bits = pslpi->ProcessorMask;
1256 while (cpu_bits > 0) {
1257 if (!!(cpu_bits & 1)) {
1258 GuestLogicalProcessor *vcpu;
1259 GuestLogicalProcessorList *entry;
1261 vcpu = g_malloc0(sizeof *vcpu);
1262 vcpu->logical_id = current++;
1263 vcpu->online = true;
1264 vcpu->has_can_offline = false;
1266 entry = g_malloc0(sizeof *entry);
1267 entry->value = vcpu;
1269 *link = entry;
1270 link = &entry->next;
1272 cpu_bits >>= 1;
1275 length -= sizeof(SYSTEM_LOGICAL_PROCESSOR_INFORMATION);
1276 pslpi++; /* next entry */
1279 g_free(ptr);
1281 if (local_err == NULL) {
1282 if (head != NULL) {
1283 return head;
1285 /* there's no guest with zero VCPUs */
1286 error_setg(&local_err, "Guest reported zero VCPUs");
1289 qapi_free_GuestLogicalProcessorList(head);
1290 error_propagate(errp, local_err);
1291 return NULL;
1294 int64_t qmp_guest_set_vcpus(GuestLogicalProcessorList *vcpus, Error **errp)
1296 error_setg(errp, QERR_UNSUPPORTED);
1297 return -1;
1300 static gchar *
1301 get_net_error_message(gint error)
1303 HMODULE module = NULL;
1304 gchar *retval = NULL;
1305 wchar_t *msg = NULL;
1306 int flags;
1307 size_t nchars;
1309 flags = FORMAT_MESSAGE_ALLOCATE_BUFFER |
1310 FORMAT_MESSAGE_IGNORE_INSERTS |
1311 FORMAT_MESSAGE_FROM_SYSTEM;
1313 if (error >= NERR_BASE && error <= MAX_NERR) {
1314 module = LoadLibraryExW(L"netmsg.dll", NULL, LOAD_LIBRARY_AS_DATAFILE);
1316 if (module != NULL) {
1317 flags |= FORMAT_MESSAGE_FROM_HMODULE;
1321 FormatMessageW(flags, module, error, 0, (LPWSTR)&msg, 0, NULL);
1323 if (msg != NULL) {
1324 nchars = wcslen(msg);
1326 if (nchars >= 2 &&
1327 msg[nchars - 1] == L'\n' &&
1328 msg[nchars - 2] == L'\r') {
1329 msg[nchars - 2] = L'\0';
1332 retval = g_utf16_to_utf8(msg, -1, NULL, NULL, NULL);
1334 LocalFree(msg);
1337 if (module != NULL) {
1338 FreeLibrary(module);
1341 return retval;
1344 void qmp_guest_set_user_password(const char *username,
1345 const char *password,
1346 bool crypted,
1347 Error **errp)
1349 NET_API_STATUS nas;
1350 char *rawpasswddata = NULL;
1351 size_t rawpasswdlen;
1352 wchar_t *user = NULL, *wpass = NULL;
1353 USER_INFO_1003 pi1003 = { 0, };
1354 GError *gerr = NULL;
1356 if (crypted) {
1357 error_setg(errp, QERR_UNSUPPORTED);
1358 return;
1361 rawpasswddata = (char *)qbase64_decode(password, -1, &rawpasswdlen, errp);
1362 if (!rawpasswddata) {
1363 return;
1365 rawpasswddata = g_renew(char, rawpasswddata, rawpasswdlen + 1);
1366 rawpasswddata[rawpasswdlen] = '\0';
1368 user = g_utf8_to_utf16(username, -1, NULL, NULL, &gerr);
1369 if (!user) {
1370 goto done;
1373 wpass = g_utf8_to_utf16(rawpasswddata, -1, NULL, NULL, &gerr);
1374 if (!wpass) {
1375 goto done;
1378 pi1003.usri1003_password = wpass;
1379 nas = NetUserSetInfo(NULL, user,
1380 1003, (LPBYTE)&pi1003,
1381 NULL);
1383 if (nas != NERR_Success) {
1384 gchar *msg = get_net_error_message(nas);
1385 error_setg(errp, "failed to set password: %s", msg);
1386 g_free(msg);
1389 done:
1390 if (gerr) {
1391 error_setg(errp, QERR_QGA_COMMAND_FAILED, gerr->message);
1392 g_error_free(gerr);
1394 g_free(user);
1395 g_free(wpass);
1396 g_free(rawpasswddata);
1399 GuestMemoryBlockList *qmp_guest_get_memory_blocks(Error **errp)
1401 error_setg(errp, QERR_UNSUPPORTED);
1402 return NULL;
1405 GuestMemoryBlockResponseList *
1406 qmp_guest_set_memory_blocks(GuestMemoryBlockList *mem_blks, Error **errp)
1408 error_setg(errp, QERR_UNSUPPORTED);
1409 return NULL;
1412 GuestMemoryBlockInfo *qmp_guest_get_memory_block_info(Error **errp)
1414 error_setg(errp, QERR_UNSUPPORTED);
1415 return NULL;
1418 /* add unsupported commands to the blacklist */
1419 GList *ga_command_blacklist_init(GList *blacklist)
1421 const char *list_unsupported[] = {
1422 "guest-suspend-hybrid",
1423 "guest-set-vcpus",
1424 "guest-get-memory-blocks", "guest-set-memory-blocks",
1425 "guest-get-memory-block-size",
1426 "guest-fsfreeze-freeze-list",
1427 "guest-fstrim", NULL};
1428 char **p = (char **)list_unsupported;
1430 while (*p) {
1431 blacklist = g_list_append(blacklist, g_strdup(*p++));
1434 if (!vss_init(true)) {
1435 g_debug("vss_init failed, vss commands are going to be disabled");
1436 const char *list[] = {
1437 "guest-get-fsinfo", "guest-fsfreeze-status",
1438 "guest-fsfreeze-freeze", "guest-fsfreeze-thaw", NULL};
1439 p = (char **)list;
1441 while (*p) {
1442 blacklist = g_list_append(blacklist, g_strdup(*p++));
1446 return blacklist;
1449 /* register init/cleanup routines for stateful command groups */
1450 void ga_command_state_init(GAState *s, GACommandState *cs)
1452 if (!vss_initialized()) {
1453 ga_command_state_add(cs, NULL, guest_fsfreeze_cleanup);