IWDFUnifiedPropertyStore：：GetPropertyData 方法 (wudfddi.h)

發行項
02/27/2024

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。所有新的 UMDF 驅動程式都應該使用 UMDF 2 來撰寫。未將新功能新增至 UMDF 1，而且較新版本的 #D531349E821EC4A779F2BF5D2805E44EC 上，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。否則，方法可能會傳回下列值。

傳回碼	Description
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;
}