WDF_PROPERTY_STORE_ROOT structure (wudfddi_types.h)

  • Article

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La structure WDF_PROPERTY_STORE_ROOT contient des informations qui identifient un magasin de propriétés UMDF.

Syntaxe

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;

Membres

LengthCb

Longueur, en octets, de cette structure.

RootClass

Valeur de type WDF_PROPERTY_STORE_ROOT_CLASS qui identifie un magasin de propriétés.

Qualifier

Qualifier.HardwareKey

Qualifier.HardwareKey.ServiceName

Pointeur vers une chaîne de caractères terminée par NULL qui identifie une sous-clé spécifique au pilote sous la clé matérielle d’un appareil dans le Registre. Pour plus d’informations sur ce membre, consultez la section Remarques suivante.

Qualifier.DeviceInterfaceKey

Qualifier.DeviceInterfaceKey.InterfaceGUID

Pointeur vers un GUID qui identifie une interface d’appareil. Le pilote doit avoir précédemment appelé IWDFDevice ::CreateDeviceInterface pour inscrire l’interface du périphérique.

Qualifier.DeviceInterfaceKey.ReferenceString

Pointeur vers une chaîne de caractères terminée par NULL qui identifie une chaîne de référence pour une interface d’appareil. Le pilote doit spécifier ce membre s’il a spécifié une chaîne de référence lorsqu’il a appelé IWDFDevice ::CreateDeviceInterface. Sinon, ce membre doit être NULL.

Qualifier.LegacyHardwareKey

Qualifier.LegacyHardwareKey.LegacyMapName

Pointeur vers une chaîne de caractères terminée par null qui identifie une sous-clé sous la clé HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP dans le Registre. Cette clé n’est utilisée que par quelques pilotes plus anciens.

Remarques

La structure WDF_PROPERTY_STORE_ROOT est utilisée comme entrée dans IWDFPropertyStoreFactory ::RetrieveDevicePropertyStore et IWDFUnifiedPropertyStoreFactory ::RetrieveUnifiedDevicePropertyStore.

Les magasins de propriétés UMDF représentent les clés de Registre auxquelles les pilotes peuvent accéder. Avant que votre pilote appelle l’une des méthodes ci-dessus, il doit initialiser la structure WDF_PROPERTY_STORE_ROOT . Le pilote doit zéro la structure, puis définir le membre LengthCb sur la longueur de la structure.

Pour ouvrir une clé logicielle, votre pilote doit :

  1. Définissez le membre LengthCb de la structure sur la taille de la structure.
  2. Définissez le membre RootClass de la structure sur WdfPropertyStoreRootClassSoftwareKey.
Pour ouvrir la clé matérielle d’un appareil, votre pilote doit :
  1. Définissez le membre LengthCb de la structure sur la taille de la structure.
  2. Définissez le membre RootClass de la structure sur WdfPropertyStoreRootClassHardwareKey.
  3. Définissez une valeur pour le membre Qualifier.HardwareKey.ServiceName . Cette valeur doit être l’une des suivantes :
    • WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT, pour ouvrir la sous-clé \Paramètres de l’appareil sous la clé matérielle de l’appareil. Le pilote peut uniquement obtenir un accès en lecture à cette sous-clé.
    • WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT, pour ouvrir une sous-clé qui correspond au nom du service du pilote, sous la sous-clé \Paramètres de périphérique . Le pilote peut obtenir un accès en lecture ou en écriture à cette sous-clé. Le pilote peut éventuellement créer la sous-clé si elle n’existe pas.
    • Chaîne de caractères fournie par le pilote pour ouvrir une sous-clé avec un nom correspondant à la chaîne de caractères, sous la sous-clé \Paramètres de périphérique . Le pilote peut obtenir un accès en lecture ou en écriture à cette sous-clé. Le pilote peut éventuellement créer la sous-clé si elle n’existe pas.

    Si votre pilote crée une sous-clé sous la clé matérielle d’un appareil, il est préférable de spécifier WDF_PROPERTY_STORE_HARDWARE_KEY_DEFAULT , car UMDF crée une sous-clé qui correspond au nom du service du pilote. L’utilisation de ce nom garantit que chaque pilote crée une sous-clé nommée de manière unique. Le pilote ne doit pas spécifier WDF ou WUDF comme nom de sous-clé.

Pour ouvrir une clé d’interface de périphérique, votre pilote doit :
  1. Définissez le membre LengthCb de la structure sur la taille de la structure.
  2. Définissez le membre RootClass de la structure sur WdfPropertyStoreRootClassDeviceInterfaceKey.
  3. Définissez le membre Qualifier.DeviceInterfaceKey.InterfaceGUID sur le GUID spécifié par le pilote lors d’un appel précédent à IWDFDevice ::CreateDeviceInterface.
  4. Définissez le membre Qualifier.DeviceInterfaceKey.ReferenceString sur la chaîne de référence spécifiée par le pilote lors d’un appel précédent à IWDFDevice ::CreateDeviceInterface, ou null si le pilote n’a pas spécifié de chaîne de référence.
Le pilote peut obtenir un accès en lecture ou en écriture à la clé d’interface du périphérique.

Pour ouvrir la clé DEVICEMAP, votre pilote doit :

  1. Définissez le membre LengthCb de la structure sur la taille de la structure.
  2. Définissez le membre RootClass de la structure sur WdfPropertyStoreRootClassLegacyHardwareKey.
  3. Définissez le membre Qualifier.LegacyHardwareKey.LegacyMapName sur une chaîne de caractères qui spécifie une sous-clé sous la clé HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP dans le Registre.
Le pilote peut obtenir un accès en lecture ou en écriture à la sous-clé spécifiée sous la clé DEVICEMAP . Le pilote peut éventuellement créer la sous-clé si elle n’existe pas. Toutefois, un pilote qui crée cette sous-clé doit spécifier l’indicateur WdfPropertyStoreCreateVolatile afin que le système supprime la sous-clé chaque fois qu’il redémarre.

Pour plus d’informations sur ces clés de Registre, consultez Utilisation du Registre dans les pilotes UMDF.

Configuration requise

Condition requise Valeur
Version UMDF minimale 1,9
En-tête wudfddi_types.h (incluez Wudfddi.h)

Voir aussi

IWDFPropertyStoreFactory ::RetrieveDevicePropertyStore