HWREQCHK API 示例

项目
03/13/2025

注意

某些信息与预发行产品有关，该产品在商业发布之前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。

重要

本主题中所述的功能在 Windows Insider Preview的预发行版本中提供。显示这些功能的最早版本是 Windows Insider Preview 版本 10.0.25289。

HWREQCHK API 的这些示例演示如何利用它获取有关硬件设备及其确定的 Windows 升级资格的特定版本的 Windows 11 或更高版本的信息。

GetHardwareRequirementSystemInfo API 示例

下面的示例演示如何通过调用 GetHardwareRequirementSystemInfo（Windows 硬件要求评估引擎使用的相同信息）来获取设备系统信息。上下文是，它可能由“是否可以升级？”工具使用，以报告从 EvaluateHardwareRequirement 函数中考虑 true 或 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;
}

HWREQCHK API 概述

HWREQCHK API 函数

Windows 实现库（WIL） wiki

通过

HWREQCHK API 示例

GetHardwareRequirementSystemInfo API 示例

EvaluateHardwareRequirement API 示例

GetLatestHardwareRequirement API 示例

GetHardwareRequirements API 示例

反馈

其他资源

通过

HWREQCHK API 示例

GetHardwareRequirementSystemInfo API 示例

EvaluateHardwareRequirement API 示例

GetLatestHardwareRequirement API 示例

GetHardwareRequirements API 示例

相关主题

反馈

其他资源