IVMVirtualPC::RegisterVirtualMachine method

Article
12/11/2020

[Windows Virtual PC is no longer available for use as of Windows 8. Instead, use the Hyper-V WMI provider (V2).]

Registers an existing virtual machine configuration and retrieves the virtual machine object.

Syntax

HRESULT RegisterVirtualMachine(
  [in]          BSTR              configurationName,
  [in]          BSTR              configurationPath,
  [out, retval] IVMVirtualMachine **virtualMachine
);

Parameters

configurationName [in]: The name of the virtual machine to be registered. The length of the name cannot exceed 80 characters and the combined length of the name and path cannot exceed MAX_PATH (260) characters. The specified name may contain the .vmc extension. If this parameter is NULL or an empty string, the configurationPath parameter must specify the full path to the configuration file.
configurationPath [in]: The path to the folder that contains the existing configuration file. If the configurationName parameter is NULL or an empty string, this must specify the full path to the existing configuration file.
virtualMachine [out, retval]: A pointer to a new IVMVirtualMachine object that represents this virtual machine.

Return value

This method can return one of these values.

Return code/value	Description
S_OK 0	The operation was successful.
E_POINTER 0x80004003	The configurationName or configurationPath parameter is invalid, or virtualMachine is NULL.
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) 0x80070003	The system cannot find the path specified by the configurationName and configurationPath parameters.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	The system cannot find the file specified by the configurationName and configurationPath parameters.
HRESULT_FROM_WIN32(ERROR_INVALID_NAME) 0x8007007b	The configurationPath parameter contains an invalid character (one of "*?:<>/\|"").
HRESULT_FROM_WIN32(ERROR_BAD_PATHNAME) 0x800700a1	The parameter configurationPath parameter specifies an empty or relative path. An absolute path is required.
HRESULT_FROM_WIN32(ERROR_BUFFER_OVERFLOW) 0x8007006f	The path specified by the configurationName and configurationPath parameters results in a path that is too long. The combined length of the path must be less than MAX_PATH (260) characters.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) 0x800700b7	A configuration file with this name already exists at this location.
VM_E_CONFIG_NAME_TOO_LONG 0xA0040401	The configurationName parameter exceeds 80 characters in length.
VM_E_CONFIG_NAME_INVALID_CHAR 0xA0040402	The configurationName parameter contains an invalid character (one of "*?:<>/\|\"").
VM_E_CONFIG_DUPLICATE_NAME 0xA0040403	There is already a virtual machine with this name.
VM_E_HARDWARE_VIRTUALIZATION_DISABLED 0xA0040951	The processor does not support Hardware Accelerated Virtualization (HAV) extensions.
DISP_E_EXCEPTION 0x80020009	An unexpected error has occurred.

Remarks

Virtual machine names are case-insensitive, for example, "MyVM" and "myvm" refer to the same virtual machine.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	None supported
End of client support	Windows 7
Product	Windows Virtual PC
Header	VPCCOMInterfaces.h
IID	IID_IVMVirtualPC is defined as 236ba0d9-a24a-4292-a132-27c1421dfd01