注意
某些資訊與發行前版本產品有關，在發行前版本產品可能經過大幅修改。 Microsoft未就此處提供的資訊提供任何明示或默示擔保。
重要
本主題所述的功能可在 Windows Insider Preview發行前版本取得。 這些功能出現的最早版本是 Windows Insider Preview 版本 10.0.25289。
HWREQCHK API 的這些範例示範如何利用它來取得硬體裝置的相關信息，以及其判斷 Windows 升級資格的特定 Windows 11 或更新版本。
GetHardwareRequirementSystemInfo API 範例
下列範例示範如何呼叫 getHardwareRequirementSystemInfo 來取得裝置系統資訊，這是 Windows 硬體需求評估引擎所使用的相同資訊。 內容是，「我可以升級嗎？」工具可能會使用此工具來報告納入 true 或 false 回應的裝置系統資訊，EvaluateHardwareRequirement 函式。
#include <windows.h>
#include <objbase.h>
#include <wil/resource.h>
#include <hwreqchkapi.h>
#define PRINT_TRUE_FALSE(cond) (cond ? L"TRUE" : L"FALSE")
HRESULT
GetHardwareRequirementSystemInfoExample()
/*++
Routine Description:
Get the Hardware Requirements System Info that is used to evaluate against the requirements
Example:
Demonstrates GetHardwareRequirementSystemInfo API
Arguments:
N/A
Return Value:
HRESULT - S_OK or a FAILED HRESULT if unsuccessful getting the defined list of hardware requirements
--*/
{
HWREQCHK_DEVICE_HARDWARE_SYSINFO sysinfo{};
HRESULT result = GetHardwareRequirementSystemInfo(&sysinfo);
if (SUCCEEDED(result))
{
wprintf(L" SSE2 Processor Support: %ls\n", PRINT_TRUE_FALSE(sysinfo.SSE2ProcessorSupport));
wprintf(L" NX Processor Support: %ls\n", PRINT_TRUE_FALSE(sysinfo.NXProcessorSupport));
wprintf(L" PrefetchW Support: %ls\n", PRINT_TRUE_FALSE(sysinfo.PrefetchWSupport));
wprintf(L" CompareExchange128 Support: %ls\n",
PRINT_TRUE_FALSE(sysinfo.CompareExchange128Support));
wprintf(L" LahfSahf Support: %ls\n", PRINT_TRUE_FALSE(sysinfo.LahfSahfSupport));
wprintf(L" CPU Core Count: %lu\n", sysinfo.CpuCoreCount);
wprintf(L" SecureBoot Capable: %ls\n", PRINT_TRUE_FALSE(sysinfo.SecureBootCapable));
wprintf(L" TPM Version: %lu\n", sysinfo.TpmVersion );
wprintf(L" CPU Mhz: %lu\n", sysinfo.CpuMhz);
wprintf(L" RamMB: %lu\n", sysinfo.RamMB);
wprintf(L" SystemDiskSizeMB: %lu\n", sysinfo.SystemDiskSizeMB);
wprintf(L" Architecture: %lu\n", sysinfo.Architecture);
wprintf(L" CPU Vendor: %lu\n", sysinfo.CpuVendor );
wprintf(L" CPU Family: %lu\n", sysinfo.CpuFamily);
wprintf(L" CPU Model: %lu\n", sysinfo.CpuModel);
wprintf(L" CPU Stepping: %lu\n", sysinfo.CpuStepping);
wprintf(L" ArmV81 Processor Support: %ls\n", PRINT_TRUE_FALSE(sysinfo.ArmV81ProcessorSupport));
wprintf(L" Platform: %lu\n", sysinfo.Platform );
wprintf(L" IsServer: %ls\n", PRINT_TRUE_FALSE(sysinfo.IsServer ));
wprintf(L" Lockdown Mode: %lu\n", sysinfo.LockdownMode);
wprintf(L" Product OS: %lu\n", sysinfo.ProductOS );
wprintf(L" Product Name: %ls\n", sysinfo.ProductName);
wprintf(L" Processor Name: %ls\n", sysinfo.ProcessorName);
}
else
{
wprintf(L"Failed calling GetHardwareRequirementSystemInfo. Error:0x%.8x\n", result);
}
return result;
}
EvaluateHardwareRequirement API 範例
此範例示範如何使用 EvaluateHardwareRequirement。 這是查詢裝置硬體系統屬性以根據定義的硬體需求進行評估的函式。 範例方法 EvaluateHardwareRequirementExample，接受 HWREQCHK_DEVICE_HARDWARE_REQUIREMENT 結構，其中包含要評估哪些硬體需求的相關信息。 其他範例將示範開發人員可以填入結構內容的不同方式，以判斷要評估的需求。
#include <windows.h>
#include <objbase.h>
#include <wil/resource.h>
#include <hwreqchkapi.h>
HRESULT
EvaluateHardwareRequirementExample(
_In_ const HWREQCHK_DEVICE_HARDWARE_REQUIREMENT& deviceHardwareRequirement)
/*++
Routine Description:
Evaluate the specific hardware requirement using the information supplied in the HWREQCHK_DEVICE_HARDWARE_REQUIREMENT structure
Example:
Demonstrates EvaluateHardwareRequirement API
Arguments:
deviceHardwareRequirement - Specifies the specific device hardware requirement structure that is used to invoke the EvaluateHardwareRequirement API
Return Value:
HRESULT - S_OK or a Failed HRESULT if unsuccessful invoking the EvaluateHardwareRequirement API
--*/
{
//
// Automatically free HWREQCHK_DEVICE_HARDWARE_EVALUATION (via CoTaskMemFree)
// objects when it goes out of scope. See WIL (https://github.com/Microsoft/wil/wiki).
//
wil::unique_cotaskmem_array_ptr<HWREQCHK_DEVICE_HARDWARE_EVALUATION>
deviceHardwareRequirementEvaluations;
BOOL evaluationResult = FALSE;
static const std::map<const std::wstring, const std::wstring> constraintRuleMapping =
{
{ L"SSE2ProcessorSupport", L"Processor must support the SSE2 instruction set"} ,
{ L"NXProcessorSupport", L"Processor must support data execution prevention" },
{ L"CompareExchange128", L"Processor must support the CMPXCHG16B instruction also referred to as CompareExchange128" },
{ L"LahfSahfSupport", L"Processor must support the LAHF and SAHF instructions" },
{ L"PrefetchWSupport", L"Processor must support the PrefetchW instructions" },
{ L"CpuCores", L"The minimum number of CPU cores that must exist on the device" },
{ L"CpuFms", L"TPM must be version 2.0 exactly(no higher, no lower)" },
{ L"Tpm", L"TPM must be version 2.0 exactly" },
{ L"UefiSecureBoot", L"Secure boot must be supported on the device"},
{ L"Memory", L"The minimum amount of memory in MB that must exist on the device" },
{ L"IotMemory", L"The minimum amount of memory in MB that must exist on the device" },
{ L"ServerMemory", L"The minimum amount of memory in MB that must exist on the device" },
{ L"SystemDriveSize", L"The minimum amout of total system disk size" },
{ L"IotSystemDriveSize", L"The minimum amout of total system disk size" },
{ L"CpuFms", L"The CPU must be a supported Family, Model and Stepping (FMS) processor signature" },
{ L"BlockedByHomeSkuSModeStateSV", L"SMode must be disabled unless the OS SKU is a 'Home'SKU" }
};
HRESULT result = EvaluateHardwareRequirement(
&deviceHardwareRequirement,
&evaluationResult,
&deviceHardwareRequirementEvaluations,
deviceHardwareRequirementEvaluations.size_address<ULONG>());
if (FAILED(result))
{
wprintf(L"The requirement failed the EvaluateHardwareRequirement API. Error:0x%.8x\n", result);
}
else
{
//
// On Success, the 'evaluationResult' variable will either be TRUE (evaluation succeeded)
// or it will be FALSE (evaluation failed).
//
if (evaluationResult != FALSE)
{
wprintf(L"The hardware requirement evaluation succeeded. The device does meet the hardware requirements\n");
}
else
{
wprintf(L"The hardware requirement evaluation did not pass. The device does not meet the hardware requirements.\n");
}
// Loop through each constraint evaluation performed
for (const auto& deviceHardwareRequirementEvaluation : deviceHardwareRequirementEvaluations)
{
auto findConstraint = constraintRuleMapping.find(deviceHardwareRequirementEvaluation.RuleName);
std::wstring constraintDescription = L"Constraint Not Found";
if (findConstraint != constraintRuleMapping.end())
{
constraintDescription = findConstraint->second;
}
// Display the Rules that were evaluated as part of the requirements.
// NOTE: RuleName is a non-localized value coming from the internally defined JSON contents.
wprintf(L"\tConstraint Name: %-64ls Succeeded: %-8ls\n\t\tDescription: %ls\n",
deviceHardwareRequirementEvaluation.RuleName,
deviceHardwareRequirementEvaluation.Succeeded ? L"TRUE" : L"FALSE",
constraintDescription.c_str());
}
if (evaluationResult == FALSE)
{
// The device failed to meet the hardware requirements, dump the system
// info by calling the other example GetHardwareRequirementSystemInfoExample,
// which calls the API GetHardwareRequirementSystemInfo and dumps the contents.
GetHardwareRequirementSystemInfoExample();
}
}
return result;
}
GetLatestHardwareRequirement API 範例
下列範例示範如何使用 GetLatestHardwareRequirement。 函式會查詢並傳回指定 HWREQCHK_PRODUCT_TYPE 列舉值的最新硬體需求。 如果呼叫成功，則會將 HWREQCHK_DEVICE_HARDWARE_REQUIREMENT 結構的內容傳遞至上述 EvaluateHardwareRequirement 範例。
#include <windows.h>
#include <objbase.h>
#include <wil/resource.h>
#include <hwreqchkapi.h>
HRESULT
GetLatestHardwareRequirementExample(
_In_ HWREQCHK_PRODUCT_TYPE productType)
/*++
Routine Description:
Get the latest hardware requirement defined and then use
the information supplied in the HWREQCHK_DEVICE_HARDWARE_REQUIREMENT
to evaluate hardware requirements against it.
Example:
Demonstrates the use of the GetLatestHardwareRequirement API. If successful, the
EvaluateHardwareRequirementExample method is invoked to ‘evaluate’
the latest hardware requirement.
Arguments:
productType - A valid HWREQCHK_PRODUCT_TYPE enumeration value to get the latest hardware requirement
Return Value:
HRESULT - S_OK or a FAILED HRESULT if unsuccessful getting the defined list of hardware requirements
--*/
{
HWREQCHK_DEVICE_HARDWARE_REQUIREMENT deviceHardwareRequirement {};
// Get the currently defined latest hardware requirement for the product type value
// specified in the productEnum variable.
HRESULT result = GetLatestHardwareRequirement(productType, &deviceHardwareRequirement);
if (FAILED(result))
{
wprintf(L"The call to GetLatestHardwareRequirement failed. Error:0x%.8x\n", result);
}
else
{
//
// Use the default hardware requirement returned from the GetLatestHardwareRequirement API
// to verify the hardware device requirements for the latest defined OS
// by calling the EvaluateHardwareRequirementExample method.
//
result = EvaluateHardwareRequirementExample(deviceHardwareRequirement);
}
return result;
}
GetHardwareRequirements API 範例
此範例示範如何使用 GetHardwareRequirements 來取得已定義且可評估之整個硬體需求清單。 此範例會列舉每個可用的需求，直到找到符合提供給範例方法的自變數為止。
#include <windows.h>
#include <objbase.h>
#include <wil/resource.h>
#include <hwreqchkapi.h>
HRESULT
GetHardwareRequirementsExample(
_In_ HWREQCHK_TARGET_RELEASE targetRelease,
_In_ HWREQCHK_PRODUCT_TYPE productType)
/*++
Routine Description:
Gets all of the defined hardware requirements and evaluates one or more of the requirements
Example:
Demonstrates the use of the GetHardwareRequirements API. If successful and a
match is found for the supplied requirement & product enum arguments, then the
EvaluateHardwareRequirementExample method is invoked to ‘evaluate’
the hardware requirement.
Arguments:
targetRelease - A valid HWREQCHK_TARGET_RELEASE enumeration value
used to filter the list of returned requirement(s)
productType – A valid HWREQCHK_PRODUCT_TYPE enumeration value
used to filter the list of returned requirement(s)
Return Value:
HRESULT - S_OK or a FAILED HRESULT if unsuccessful getting the
defined list of hardware requirements
--*/
{
const HRESULT errNotFound = HRESULT_FROM_WIN32(ERROR_NOT_FOUND);
//
// Automatically free HWREQCHK_DEVICE_HARDWARE_REQUIREMENT (via CoTaskMemFree)
// objects when it goes out of scope. See WIL (https://github.com/Microsoft/wil/wiki).
//
wil::unique_cotaskmem_array_ptr<HWREQCHK_DEVICE_HARDWARE_REQUIREMENT> deviceHardwareRequirements;
// Get the currently defined hardware requirements
HRESULT result = GetHardwareRequirements(
&deviceHardwareRequirements,
deviceHardwareRequirements.size_address<ULONG>());
if (FAILED(result))
{
wprintf(L"The call to GetHardwareRequirements failed. Error:0x%.8x\n", result);
}
else
{
for (const auto& deviceHardwareRequirement : deviceHardwareRequirements)
{
result = errNotFound;
// Look for a requirement matching the TargetRelease and ProductType enumeration values
if (deviceHardwareRequirement.TargetRelease == targetRelease &&
deviceHardwareRequirement.ProductType == productType)
{
// We found a match. Now evaluate the requirement by
// calling the EvaluateHardwareRequirementExample method
result = EvaluateHardwareRequirementExample(deviceHardwareRequirement);
if (FAILED(result))
{
wprintf(L"Error invoking the example method EvaluateHardwareRequirementExample\n");
}
break ;
}
}
}
if (result == errNotFound )
{
wprintf(L"Unable to locate a matching target-release '%d' and product-type '%d'\n",
targetRelease, producttype);
}
return result;
}