struttura WDF_PROPERTY_STORE_ROOT (wudfddi_types.h)

Articolo
08/08/2023

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedere Introduzione con UMDF.]

La struttura WDF_PROPERTY_STORE_ROOT contiene informazioni che identificano un archivio proprietà UMDF.

Sintassi

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;

Members

LengthCb

Lunghezza, in byte, di questa struttura.

RootClass

Valore WDF_PROPERTY_STORE_ROOT_CLASS tipizzato che identifica un archivio delle proprietà.

Qualifier

Qualifier.HardwareKey

Qualifier.HardwareKey.ServiceName

Puntatore a una stringa di caratteri con terminazione NULL che identifica una sottochiave specifica del driver sotto la chiave hardware di un dispositivo nel Registro di sistema. Per altre informazioni su questo membro, vedere la sezione Osservazioni seguenti.

Qualifier.DeviceInterfaceKey

Qualifier.DeviceInterfaceKey.InterfaceGUID

Puntatore a un GUID che identifica un'interfaccia del dispositivo. Il driver deve essere stato chiamato in precedenza IWDFDevice::CreateDeviceInterface per registrare l'interfaccia del dispositivo.

Qualifier.DeviceInterfaceKey.ReferenceString

Puntatore a una stringa di caratteri con terminazione NULL che identifica una stringa di riferimento per un'interfaccia del dispositivo. Il driver deve specificare questo membro se ha specificato una stringa di riferimento quando ha chiamato IWDFDevice::CreateDeviceInterface. In caso contrario, questo membro deve essere NULL.

Qualifier.LegacyHardwareKey

Qualifier.LegacyHardwareKey.LegacyMapName

Puntatore a una stringa di caratteri con terminazione NULL che identifica una sottochiave nella chiave HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP nel Registro di sistema. Questa chiave viene usata solo da alcuni driver meno recenti.

Commenti

La struttura WDF_PROPERTY_STORE_ROOT viene usata come input per IWDFPropertyStoreFactory::RetrieveDevicePropertyStore e IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore.

Gli archivi delle proprietà UMDF rappresentano le chiavi del Registro di sistema a cui possono accedere i driver. Prima che il driver chiami uno dei metodi precedenti, deve inizializzare la struttura WDF_PROPERTY_STORE_ROOT . Il driver deve zero la struttura e quindi impostare il membro LengthCb sulla lunghezza della struttura.

Per aprire una chiave software, il driver deve:

Impostare il membro LengthCb della struttura sulla dimensione della struttura.
Impostare il membro RootClass della struttura su WdfPropertyStoreRootClassSoftwareKey.

Per aprire la chiave hardware di un dispositivo, il driver deve:

Impostare il membro LengthCb della struttura sulla dimensione della struttura.
Impostare il membro RootClass della struttura su WdfPropertyStoreRootClassHardwareKey.
Impostare un valore per il membro Qualifier.HardwareKey.ServiceName . Questo valore deve essere uno dei seguenti:
- WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT, per aprire la sottochiave \Parametri dispositivo nella chiave hardware del dispositivo. Il driver può ottenere solo l'accesso in lettura a questa sottochiave.
- WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT, per aprire una sottochiave corrispondente al nome del servizio del driver, nella sottochiave \Parametri dispositivo . Il driver può ottenere l'accesso in lettura o scrittura a questa sottochiave. Il driver può facoltativamente creare la sottochiave se non esiste.
- Stringa di caratteri fornita dal driver per aprire una sottochiave con un nome corrispondente alla stringa di caratteri, nella sottochiave \Parametri dispositivo . Il driver può ottenere l'accesso in lettura o scrittura a questa sottochiave. Il driver può facoltativamente creare la sottochiave se non esiste.
Se il driver crea una sottochiave sotto la chiave hardware di un dispositivo, è consigliabile specificare WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT perché UMDF crea una sottochiave corrispondente al nome del servizio del driver. L'uso di questo nome garantisce che ogni driver crei una sottochiave denominata in modo univoco. Il driver non deve specificare WDF o WUDF come nome della sottochiave.

Per aprire una chiave dell'interfaccia del dispositivo, il driver deve:

Impostare il membro LengthCb della struttura sulla dimensione della struttura.
Impostare il membro RootClass della struttura su WdfPropertyStoreRootClassDeviceInterfaceKey.
Impostare il membro Qualifier.DeviceInterfaceKey.InterfaceGUID sul GUID specificato su una chiamata precedente a IWDFDevice::CreateDeviceInterface.
Impostare il membro Qualifier.DeviceInterfaceKey.ReferenceString sulla stringa di riferimento specificata dal driver a una chiamata precedente a IWDFDevice::CreateDeviceInterface o NULL se il driver non specifica una stringa di riferimento.

Il driver può ottenere l'accesso in lettura o scrittura alla chiave dell'interfaccia del dispositivo.

Per aprire la chiave DEVICEMAP, il driver deve:

Impostare il membro LengthCb della struttura sulla dimensione della struttura.
Impostare il membro RootClass della struttura su WdfPropertyStoreRootClassLegacyHardwareKey.
Impostare il membro Qualifier.LegacyHardwareKey.LegacyMapName su una stringa di caratteri che specifica una sottochiave nella chiave HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP nel Registro di sistema.

Il driver può ottenere l'accesso in lettura o scrittura alla sottochiave specificata nella chiave DEVICEMAP . Il driver può facoltativamente creare la sottochiave se non esiste. Tuttavia, un driver che crea questa sottochiave deve specificare il flag WdfPropertyStoreCreateVolatile in modo che il sistema elimini la sottochiave ogni volta che viene riavviato.

Per altre informazioni su queste chiavi del Registro di sistema, vedere Uso del Registro di sistema nei driver basati su UMDF.

Requisiti

Requisito	Valore
Versione UMDF minima	1,9
Intestazione	wudfddi_types.h (includere Wudfddi.h)

Vedi anche

IWDFPropertyStoreFactory::RetrieveDevicePropertyStore

Condividi tramite