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 |