IWDFUnifiedPropertyStore::GetPropertyData 方法 (wudfddi.h)

[警告: 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 成員設定為WdfPropertyStoreRootClassHardwareKeyWdfPropertyStoreRootClassDeviceInterfaceKey

如果您指定WdfPropertyStoreRootClassHardwareKey,則在呼叫GetPropertyData時,您必須在PropertyKey參數中提供自訂DEVPROPKEY值,而不是 PnP 定義的金鑰。 先前必須藉由呼叫 SetPropertyDataSetupDI 裝置屬性函式或使用 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;
}

規格需求

   
結束支援 在 UMDF 2.0 和更新版本中無法使用。
目標平臺 桌面
最低 UMDF 版本 1.11
標頭 wudfddi.h
DLL WUDFx.dll

另請參閱

IWDFUnifiedPropertyStore

IWDFUnifiedPropertyStoreFactory

RetrieveUnifiedDevicePropertyStore

SetPropertyData

WDF_PROPERTY_STORE_ROOT

WDF_PROPERTY_STORE_ROOT_CLASS