Méthode IWDFPropertyStoreFactory ::RetrieveDevicePropertyStore (wudfddi.h)

[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 méthode RetrieveDevicePropertyStore récupère une interface de magasin de propriétés que les pilotes peuvent utiliser pour accéder au Registre.

Syntaxe

HRESULT RetrieveDevicePropertyStore(
  [in]  PWDF_PROPERTY_STORE_ROOT          RootSpecifier,
  [in]  WDF_PROPERTY_STORE_RETRIEVE_FLAGS Flags,
  [in]  REGSAM                            DesiredAccess,
  [in]  PCWSTR                            SubkeyPath,
  [out] IWDFNamedPropertyStore2           **PropertyStore,
  [out] WDF_PROPERTY_STORE_DISPOSITION    *Disposition
);

Paramètres

[in] RootSpecifier

Adresse d’une structure de WDF_PROPERTY_STORE_ROOT allouée par un pilote. Le pilote remplit cette structure pour identifier le magasin de propriétés récupéré par RetrieveDevicePropertyStore .

[in] Flags

Indicateur de type WDF_PROPERTY_STORE_RETRIEVE_FLAGS qui spécifie si UMDF doit créer une entrée de Registre spécifiée si elle n’existe pas, et si la nouvelle entrée doit être supprimée lors du redémarrage de Windows.

[in] DesiredAccess

Masque de bits de type REGSAM qui spécifie les types d’accès au Registre que vous souhaitez que votre pilote ait. Le type REGSAM est défini dans Winreg.h et est décrit dans la SDK Windows regsam. Le masque de bits ne doit pas spécifier l’accès GENERIC_WRITE, KEY_CREATE_SUB_KEY ou WRITE_DAC. (Bien que le pilote ne puisse pas spécifier KEY_CREATE_SUB_KEY, son appel à RetrieveDevicePropertyStore peut créer une sous-clé.)

[in] SubkeyPath

Pointeur vers une chaîne de caractères fournie par l’appelant qui représente le nom d’une sous-clé située sous la clé de Registre spécifiée par le paramètre RootSpecifier . Ce paramètre est facultatif et peut être NULL. Pour plus d’informations, consultez Remarques.

[out] PropertyStore

Adresse d’un emplacement qui reçoit un pointeur vers une interface IWDFNamedPropertyStore2 . Le pilote utilise cette interface pour accéder aux valeurs dans le Registre.

[out] Disposition

Adresse d’un emplacement qui reçoit une valeur de type WDF_PROPERTY_STORE_DISPOSITION.

Valeur retournée

RetrieveDevicePropertyStore retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
E_INVALIDARG	L’appelant a fourni un argument d’entrée non valide.
E_OUTOFMEMORY	Une tentative d’allocation de mémoire a échoué.

 

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient

Remarques

Votre pilote peut appeler RetrieveDevicePropertyStore pour obtenir l’accès à la clé logicielle du pilote, à la clé matérielle de l’appareil actuel, aux clés des interfaces d’appareil prises en charge par l’appareil actuel ou à la clé DEVICEMAP .

Si vous fournissez le paramètre SubkeyPath , vous devez utiliser un nom unique, tel que le nom du service du pilote. Un pilote peut utiliser une sous-clé pour stocker des informations spécifiques à l’appareil.

Pour plus d’informations sur l’utilisation de RetrieveDevicePropertyStore pour accéder au Registre, consultez Utilisation du Registre dans les pilotes basés sur UMDF.

Exemples

L’exemple de code suivant récupère la valeur affectée à l’entrée PortName sous la clé matérielle d’un appareil.

IWDFPropertyStoreFactory *pPropertyStoreFactory = NULL;
WDF_PROPERTY_STORE_ROOT RootSpecifier;
IWDFNamedPropertyStore2 * pHardwarePropertyStore2 = NULL;
PROPVARIANT comPortPV;
WCHAR portName[] = L"PortName";
HRESULT hr;
...
//
// Get the property store factory interface.
//
hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pPropertyStoreFactory));
if (FAILED(hr))
{
    goto Exit;
}
//
//Initialize the WDF_PROPERTY_STORE_ROOT structure. We want to open the 
// \Device Parameters subkey under the device's hardware key.
//
RtlZeroMemory(&RootSpecifier,
              sizeof(WDF_PROPERTY_STORE_ROOT));
RootSpecifier.LengthCb = sizeof(WDF_PROPERTY_STORE_ROOT);
RootSpecifier.RootClass = WdfPropertyStoreRootClassHardwareKey;
RootSpecifier.Qualifier.HardwareKey.ServiceName = WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT;

//
// Get the property store interface for the hardware key of the
// device that m_FxDevice represents.
//
hr = pPropertyStoreFactory->RetrieveDevicePropertyStore(
                                           &RootSpecifier,
                                           WdfPropertyStoreNormal,
                                           KEY_QUERY_VALUE,
                                           NULL,
                                           &pHardwarePropertyStore2,
                                           NULL
                                           );
if (FAILED(hr))
{
    goto Exit;
}

//
// Get the value of the "PortName" entry, which is stored under 
// the device's \Device Parameters subkey.
//
PropVariantInit(&comPortPV);
hr = pHardwarePropertyStore2->GetNamedValue(portName,
                                            &comPortPV);
if (FAILED(hr))
{
   goto Exit;
}
...
Exit:
    SAFE_RELEASE(pHardwarePropertyStore2);
    SAFE_RELEASE(pPropertyStoreFactory);
...

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFDevice ::RetrieveDevicePropertyStore

IWDFDeviceInitialize ::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory