WDF_PROPERTY_STORE_ROOT 結構 (wudfddi_types.h)

  • 發行項

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

WDF_PROPERTY_STORE_ROOT 結構包含可識別UMDF屬性存放區的資訊。

語法

typedef struct _WDF_PROPERTY_STORE_ROOT {
  ULONG                         LengthCb;
  WDF_PROPERTY_STORE_ROOT_CLASS RootClass;
  union {
    struct {
      PCWSTR ServiceName;
    } HardwareKey;
    struct {
      LPCGUID InterfaceGUID;
      PCWSTR  ReferenceString;
    } DeviceInterfaceKey;
    struct {
      PCWSTR LegacyMapName;
    } LegacyHardwareKey;
  } Qualifier;
} WDF_PROPERTY_STORE_ROOT, *PWDF_PROPERTY_STORE_ROOT;

成員

LengthCb

這個結構的長度，以位元組為單位。

RootClass

識別屬性存放區的 WDF_PROPERTY_STORE_ROOT_CLASS型別值。

Qualifier

Qualifier.HardwareKey

Qualifier.HardwareKey.ServiceName

NULL 終止字元字串的指標，可識別登錄中裝置硬體機碼底下的驅動程式特定子機碼。 如需此成員的詳細資訊，請參閱下列一節。

Qualifier.DeviceInterfaceKey

Qualifier.DeviceInterfaceKey.InterfaceGUID

識別裝置介面之 GUID 的指標。 驅動程式先前必須呼叫 IWDFDevice：：CreateDeviceInterface ，才能註冊裝置介面。

Qualifier.DeviceInterfaceKey.ReferenceString

識別裝置介面參考字串之 NULL終止字元字串的指標。 如果驅動程式在呼叫 IWDFDevice：：CreateDeviceInterface 時指定參考字串，則必須指定這個成員。 否則，這個成員必須是 NULL。

Qualifier.LegacyHardwareKey

Qualifier.LegacyHardwareKey.LegacyMapName

NULL 終止字元字串的指標，可識別登錄中 HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP 機碼底下的子機碼。 只有少數較舊的驅動程式會使用此金鑰。

備註

WDF_PROPERTY_STORE_ROOT 結構可用來做為 IWDFPropertyStoreFactory：：RetrieveDevicePropertyStore 和 IWDFUnifiedPropertyStoreFactory：：RetrieveUnifiedDevicePropertyStore 的輸入。

UMDF 屬性存放區代表驅動程式可以存取的登錄機碼。 在驅動程式呼叫上述其中一種方法之前，它必須先初始化 WDF_PROPERTY_STORE_ROOT 結構。 驅動程式必須零 結構，然後將 LengthCb 成員設定為結構的長度。

若要開啟 軟體金鑰，您的驅動程式必須：

  1. 將結構的 LengthCb 成員設定為結構大小。
  2. 將結構的 RootClass 成員設定為 WdfPropertyStoreRootClassSoftwareKey。
若要開啟裝置 的硬體金鑰，您的驅動程式必須：
  1. 將結構的 LengthCb 成員設定為結構大小。
  2. 將結構的 RootClass 成員設定為 WdfPropertyStoreRootClassHardwareKey。
  3. 設定 Qualifier.HardwareKey.ServiceName 成員的值。 此值必須是下列其中一項：
    • WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT，在裝置的硬體密鑰下開啟 \Device Parameters 子機碼。 驅動程式只能取得此子機碼的讀取許可權。
    • WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT，在 \Device Parameters 子機碼下開啟符合驅動程式服務名稱的子機碼。 驅動程式可以取得此子機碼的讀取或寫入許可權。 如果子機碼不存在，驅動程式可以選擇性地建立子機碼。
    • 驅動程式提供的字元字串，以在 \Device Parameters 子機碼下，以符合字元字串的名稱開啟子機碼。 驅動程式可以取得此子機碼的讀取或寫入許可權。 如果子機碼不存在，驅動程式可以選擇性地建立子機碼。

    如果您的驅動程式在裝置的硬體密鑰下建立子機碼，最好指定 WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT ，因為 UMDF 會建立符合驅動程式服務名稱的子機碼。 使用此名稱可確保每個驅動程式都會建立唯一命名的子機碼。 驅動程式不得將 WDF 或 WUDF 指定為子機碼名稱。

若要開啟 裝置介面金鑰，您的驅動程式必須：
  1. 將結構的 LengthCb 成員設定為結構大小。
  2. 將結構的 RootClass 成員設定為 WdfPropertyStoreRootClassDeviceInterfaceKey。
  3. 將 Qualifier.DeviceInterfaceKey.InterfaceGUID 成員設定為驅動程式指定給先前呼叫 IWDFDevice：：CreateDeviceInterface 的 GUID。
  4. 將 Qualifier.DeviceInterfaceKey.ReferenceString 成員設定為驅動程式先前呼叫 IWDFDevice：：CreateDeviceInterface 的參考字元串，如果驅動程式未指定參考字符串，則為 NULL 。
驅動程式可以取得裝置介面密鑰的讀取或寫入許可權。

若要開啟 DEVICEMAP 金鑰，您的驅動程式必須：

  1. 將結構的 LengthCb 成員設定為結構大小。
  2. 將結構的 RootClass 成員設定為 WdfPropertyStoreRootClassLegacyHardwareKey。
  3. 將 Qualifier.LegacyHardwareKey.LegacyMapName 成員設定為字元字串，指定登錄中 HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP 機碼底下的子機碼。
驅動程式可以在 DEVICEMAP 機碼下取得指定子機碼的讀取或寫入許可權。 如果子機碼不存在，驅動程式可以選擇性地建立子機碼。 不過，建立此子機碼的驅動程式必須指定 WdfPropertyStoreCreateVolatile 旗標，讓系統每次重新啟動時都會刪除子機碼。

如需這些登錄機碼的詳細資訊，請參閱 在 UMDF 型驅動程式中使用登錄。

規格需求

需求 值
最低UMDF版本 1.9
標頭 wudfddi_types.h (包括 Wudfddi.h)

另請參閱

IWDFPropertyStoreFactory：：RetrieveDevicePropertyStore