HcsModifyComputeSystem

Article
04/26/2022

Description

Modifies settings of a compute system, see sample code for simple example.

Syntax

HRESULT WINAPI
HcsModifyComputeSystem(
    _In_ HCS_SYSTEM computeSystem,
    _In_ HCS_OPERATION operation,
    _In_ PCWSTR configuration,
    _In_opt_ HANDLE identity
    );

Parameters

computeSystem

Handle the compute system to modify.

operation

Handle to the operation that tracks the modify operation.

configuration

JSON document of ModifySettingRequest specifying the settings to modify.

identity

Optional handle to an access token that is used when applying the settings.

Return Values

The function returns HRESULT.

If the return value is S_OK, it means the operation started successfully. Callers are expected to get the operation's result using HcsWaitForOperationResult or HcsGetOperationResult.

Operation Results

The return value of HcsWaitForOperationResult or HcsGetOperationResult based on current operation listed as below.

Operation Result Value	Description
`S_OK`	The compute system was modified successfully

Remarks

The ModifySettingRequest JSON document has a property called "Settings" of type Any. In JSON, Any means an arbitrary object with no restrictions. Refer to the following table to know what JSON type HCS expects for each "ResourcePath".

`"ResourcePath"`	`"Settings"` Type	Valid `"RequestType"` in ModifyRequestType
L"VirtualMachine/ComputeTopology/Processor/CpuGroup"	CpuGroup	No Limit
L"VirtualMachine/ComputeTopology/Processor/IdledProcessors"	IdleProcessorsRequest	Only "Update"
L"VirtualMachine/ComputeTopology/Processor/CpuFrequencyPowerCap"	ULONG	No Limit
L"VirtualMachine/Devices/FlexibleIov/`<Identifier>`" `Identifier` is expected as uniq name to represent the flexible IOV device	FlexibleIoDevice	Only "Add"
L"VirtualMachine/ComputeTopology/Gpu"	GpuConfiguration	Only "Update"
L"VirtualMachine/Devices/MappedPipes/`<Identifier>`" `Identifier` is expected as uniq name to represent the host named pipe to be mapped	`Settings` should be empty	"Add" or "Remove"
L"VirtualMachine/ComputeTopology/Memory/SizeInMB"	UINT64, meaning new memory size in MB	No Limit
L"VirtualMachine/Devices/NetworkAdapters/`<Identifier`>" `Identifier` is expected as uniq name to represent the network adapter	NetworkAdapter	No Limit
L"VirtualMachine/Devices/Plan9/Shares"	Plan9Share	No Limit
L"VirtualMachine/Devices/Scsi/`<Identifier>`/Attachments/`<UnsignedInt>`" `Identifier` is expected as uniq name to represent the scsi device; `UnsignedInt` is expected as the unsigned int value to represent the lun of the disk	Attachment	No Limit `Settings` is ignored when type is "Remove"
L"VirtualMachine/Devices/ComPorts/`<UnsignedInt>`" `UnsignedInt` is expected to represent the serial ID which is not larger than 1	comPort	No Limit(check c_SerialResourceRegex???)
L"VirtualMachine/Devices/SharedMemory/Regions"	SharedMemoryRegion	No Limit
L"VirtualMachine/Devices/VirtualPMem/Devices/`<UnsignedInt>`" `UnsignedInt` is expected to represent the number identifier of the VPMEM device	VirtualPMemDevice	"Add" or "Remove" `Settings` is ignored when type is "Remove"
L"VirtualMachine/Devices/VirtualPMem/Devices/`<UnsignedInt>`/Mappings/`<UnsignedInt>`" First `UnsignedInt` is expected to represent the number identifier of the VPMEM device; Second `UnsignedInt` is expected to represent the offset indicating which Mapping to modify	VirtualPMemMapping	"Add" or "Remove" `Settings` is ignored when type is "Remove"
L"VirtualMachine/Devices/VirtualSmb/Shares"	VirtualSmbShare	No Limit
L"VirtualMachine/Devices/VirtualPci/" + c_Identifier	VirtualPciDevice	"Add" or "Remove" `Settings` is ignored when type is "Remove"

Requirements

Parameter	Description
Minimum supported client	Windows 10, version 1809
Minimum supported server	Windows Server 2019
Target Platform	Windows
Header	ComputeCore.h
Library	ComputeCore.lib
Dll	ComputeCore.dll

Partager via