IWDFUnifiedPropertyStore：：GetPropertyData 方法（wudfddi.h）

發行項
02/07/2025

[警告： UMDF 2 是最新版本的 UMDF，並取代 UMDF 1。所有新的UMDF驅動程式都應該使用UMDF 2撰寫。未將新功能新增至 UMDF 1，而且較新版本的 Windows 10 上對 UMDF 1 的支援有限。通用 Windows 驅動程式必須使用 UMDF 2。如需詳細資訊，請參閱開始使用 UMDF。]

GetPropertyData 方法會擷取裝置屬性目前的設定。

語法

HRESULT GetPropertyData(
  [in]            const DEVPROPKEY *PropertyKey,
  [in]            LCID             Lcid,
  [in]            ULONG            Flags,
  [in]            ULONG            PropertyDataSize,
  [out, optional] PVOID            PropertyData,
  [out]           ULONG            *PropertyDataRequiredSize,
  [out]           DEVPROPTYPE      *PropertyType
);

參數

[in] PropertyKey

指定裝置屬性索引鍵之 DEVPROPKEY 結構的指標。

[in] Lcid

指定地區設定標識碼。將此參數設定為語言特定的 LCID 值或LOCALE_NEUTRAL。 LOCALE_NEUTRAL LCID 指定屬性是語言中性（也就是不是任何語言特有的）。請勿將此參數設定為LOCALE_SYSTEM_DEFAULT或LOCALE_USER_DEFAULT。如需語言特定 LCID 值的詳細資訊，請參閱 LCID 結構。

[in] Flags

保留供系統使用。驅動程式應將此值設定為 0。

[in] PropertyDataSize

PropertyData 所指向之緩衝區的大小，以位元組為單位。

[out, optional] PropertyData

裝置屬性數據的指標。

[out] PropertyDataRequiredSize

ULONG 的指標，用來接收在 PropertyData 中傳回之屬性資訊的大小。

[out] PropertyType

DEVPROPTYPE 值的指標。如果 GetPropertyData 成功完成，此方法會使用 PropertyType 來提供在 PropertyData 緩衝區中傳回的數據類型。

傳回值

如果作業成功，GetPropertyData 會傳回S_OK。否則，方法可能會傳回下列值。

傳回碼	描述
E_OUTOFMEMORY	架構嘗試配置記憶體失敗。
HRESULT_FROM_NT（STATUS_BUFFER_TOO_SMALL）	PropertyDataRequiredSize 參數包含所需緩衝區的大小。
HRESULT_FROM_WIN32（ERROR_INVALID_PARAMETER）	如果驅動程式指定 WdfPropertyStoreRootClassDeviceInterfaceKey，則要求的介面必須是 UMDF 驅動程式先前註冊的介面。
HRESULT_FROM_WIN32 （STATUS_NOT_SUPPORTED）	驅動程式只能從 Windows 8 開始要求裝置介面屬性數據。

這個方法可能會傳回 Winerror.h 包含的其他其中一個值。

言論

架構型驅動程式會使用 GetPropertyData 方法來擷取定義為統一裝置屬性模型的一部分的裝置屬性。

特別是，您可以使用這個方法來擷取裝置硬體密鑰或裝置介面類別的實例。當您呼叫 IWDFUnifiedPropertyStoreFactory：：RetrieveUnifiedDevicePropertyStore時，請將 RootSpecifier 參數的 RootClass 成員設定為 WdfPropertyStoreRootClassHardwareKey 或 WdfPropertyStoreRootClassDeviceInterfaceKey。

如果您指定 WdfPropertyStoreRootClassHardwareKey，則當您 呼叫 getPropertyData時，您必須在 PropertyKey 參數中提供自定義 DEVPROPKEY 值，而不是 PnP 定義的索引鍵。先前必須藉由呼叫 setPropertyData 、SetupDI 裝置屬性函式，或使用 INF AddProperty 指示詞來設定值。

如需裝置屬性的詳細資訊，請參閱裝置屬性。

如需存取登錄的詳細資訊，請參閱在以 UMDF 為基礎的驅動程式中使用登入。

例子

針對可變大小屬性，驅動程式應該進行兩次傳遞來擷取屬性數據。首先，驅動程式應該在 PropertyData 參數中傳遞 NULL 緩衝區，並將 PropertyDataSize 設為 0。然後，驅動程式應該根據傳回的 PropertyDataRequiredSize 配置緩衝區，然後再次呼叫 GetPropertyData，並傳遞配置的緩衝區。

下列範例示範此模式。

HRESULT
GetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    DEVPROPTYPE type;
    ULONG requiredSize;
    BYTE * friendlyNameBuffer = NULL;
    ULONG friendlyNameBufferSize;

    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            0, //BufferSize
            NULL, //Buffer
            &requiredSize,
            &type
            );

    if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }

    friendlyNameBufferSize = requiredSize;
    friendlyNameBuffer = new BYTE[requiredSize];
    if (NULL == friendlyNameBuffer)
    {
        hr = E_OUTOFMEMORY;
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Out of memory while allocating property data buffer returning:”
            “ %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            friendlyNameBufferSize,
            friendlyNameBuffer,
            &requiredSize,
            &type
            );

    if (FAILED(hr))
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    if (type != DEVPROP_TYPE_STRING)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Expected type %d, actual type: %d",
            DEVPROP_TYPE_STRING,
            type
            );
        hr = E_UNEXPECTED;
        goto exit;
    }

exit:
    delete [] friendlyNameBuffer;
    friendlyNameBuffer = NULL;

    return hr;
}