HWREQCHK API 範例
注意
有些資訊與發行前版本產品有關，在正式發行前可能會大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
重要
本主題所述的功能可在Windows Insider Preview的發行前版本取得。 這些功能出現的最早版本是Windows Insider Preview 10.0.25289 版。
HWREQCHK API 的這些範例示範如何利用它來取得硬體裝置的相關資訊，以及其針對特定版本Windows 11或更新版本的 Windows 升級資格。
GetHardwareRequirementSystemInfo API 範例
下列範例示範如何藉由呼叫 GetHardwareRequirementSystemInfo來取得裝置系統資訊，這是 Windows 硬體需求評估引擎所使用的相同資訊。 內容是「我可以升級嗎？」工具可能會使用它來報告納入 trueEvaluateHardwareRequirement函式之 或 false 回應中的裝置系統資訊。
#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;
}