Host Compute System API Reference

The following section contains the definitions of the Host Compute System APIs. The DLL exports a set of C-style Windows API functions, using JSON schema as configuration.

Data types

Type	Description
HCS ERROR CODE	Common HCS Error Code
HCS_EVENT_TYPE	Events indicated to callbacks registered by HcsSetComputeSystemCallback or HcsSetProcessCallback
HCS_EVENT	Information about an event that ocurred on a compute system or process.
HCS_EVENT_OPTIONS	Options for an event callback registration
HCS_OPERATION_TYPE	Operation type assigned to a valid hcs operation
HCS_PROCESS_INFORMATION	Information about a process created by HcsCreateProcess

Handle types

Type	Description
HCS_SYSTEM	Handle to a compute system
HCS_PROCESS	Handle to a process running in a compute system
HCS_OPERATION	Handle to an operation on a compute system
HCS_CALLBACK	Handle to a callback registered on a compute system or process

Callback function types

Type	Description
HCS_OPERATION_COMPLETION	The completion callback of an hcs operation
HCS_EVENT_CALLBACK	The compute system events callback

Operations

Function	Description
HcsCreateOperation	Create a new operation
HcsCloseOperation	Close an operation
HcsGetOperationContext	Get the context pointer of an operation
HcsSetOperationContext	Set the context pointer on an operation
HcsGetComputeSystemFromOperation	Get the compute system handle associated with operation
HcsGetProcessFromOperation	Return the handle to the process associated with an operation
HcsGetOperationType	Get the type of the operation
HcsGetOperationId	Get the id of the operation
HcsGetOperationResult	Get the result of the operation
HcsGetOperationResultAndProcessInfo	Return the result of an operation
HcsWaitForOperationResult	Wait for the completion of the create operation
HcsWaitForOperationResultAndProcessInfo	Wait for the completion of the create operation and returns both the result and process info
HcsSetOperationCallback	Set the callback that is invoked on completion of an operation
HcsCancelOperation	Cancel the operation

Compute System Operations

Function	Description
HcsCreateComputeSystem	Create a new compute system
HcsOpenComputeSystem	Open a handle to an existing compute system
HcsCloseComputeSystem	Close a handle to a compute system
HcsStartComputeSystem	Start a compute system
HcsShutDownComputeSystem	Cleanly Shut down a compute system
HcsTerminateComputeSystem	Forcefully terminate a compute system
HcsCrashComputeSystem	Forcefully terminate a compute system
HcsPauseComputeSystem	Pause the execution of a compute system
HcsResumeComputeSystem	Resume the execution of a compute system
HcsSaveComputeSystem	Save the state of a compute system
HcsGetComputeSystemProperties	Query properties of a compute system
HcsModifyComputeSystem	Modify setting of a compute system
HcsSetComputeSystemCallback	Register a callback function to receive notifications for the compute system
HcsEnumerateComputeSystems	Enumerate existing compute systems
HcsWaitForComputeSystemExit	Wait compute system to exit

Process Execution

The following functions enable applications to execute a process in a compute system. For containers, these functions are the main way for an application to start and interact with the workload running in the container.

Function	Description
HcsCreateProcess	Start a process in a compute system
HcsOpenProcess	Open an existing process in a compute system
HcsCloseProcess	Close the handle to a process in a compute system
HcsTerminateProcess	Terminate a process in a compute system
HcsSignalProcess	Send a signal to a process in a compute system
HcsGetProcessInfo	Return the initial startup info of a process in a compute system
HcsGetProcessProperties	Return properties a process in a compute system
HcsModifyProcess	Modify the parameters in a process of a compute system
HcsSetProcessCallback	Register a callback function to receive notifications for a process in a compute system
HcsWaitForProcessExit	Wait a process in a compute system to exit

Host Service Operations

The following functions provide functionality for host compute service.

Function	Description
HcsGetServiceProperties	Return the properties of the Host Compute Service
HcsModifyServiceSettings	Modify the settings of the Host Compute Service
HcsSubmitWerReport	Submit a WER report

Utility Functions for Virtual Machines

The following set of functions allow applications to set up the environment to run virtual machines.

Function	Description
HcsCreateEmptyGuestStateFile	Create an empty guest-state file (.vmgs) for VMs
HcsCreateEmptyRuntimeStateFile	Create an empty runtime-state file (.vmrs) for a VM
HcsGrantVmAccess	Add an entry to a file's ACL that grants access for a VM
HcsRevokeVmAccess	Remove an entry to a file's ACL that granted access for a VM
HcsGrantVmGroupAccess	Grant VM group access (R/O) to the specified file.
HcsRevokeVmGroupAccess	Remove VM group access for the specified file.
HcsGetProcessorCompatibilityFromSavedState	Get the processor compatibility from runtime-state file (.vmrs)

Storage Utility Functions for Containers

The following functions allow applications to create and manage the file system and storage environment that is required to run containers.

Function	Description
HcsImportLayer	Import a container layer and configures it for use on the host
HcsExportLayer	Export a container layer that can be copied to another host or uploaded to a container registry
HcsExportLegacyWritableLayer	Export a legacy container writable layer
HcsDestroyLayer	Delete a container layer from the host
HcsSetupBaseOSLayer	Set up a layer that contains a base OS for a container
HcsSetupBaseOSVolume	Set up the base OS layer based on the mounted volume
HcsInitializeWritableLayer	Initialize the writable layer for a container (i.e. the layer that captures the filesystem)
HcsInitializeLegacyWritableLayer	Initialize the writable layer for a container using the legacy hive folder format
HcsAttachLayerStorageFilter	Set up the layer storage filter on a writable container layers
HcsDetachLayerStorageFilter	Detach the layer storage filter from a writable container layer
HcsFormatWritableLayerVhd	Format a virtual disk for the use as a writable container layer
HcsGetLayerVhdMountPath	Return the volume path for a virtual disk of a writable container layer