Editar

Compartilhar via


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