IWDFPropertyStoreFactory::RetrieveDevicePropertyStore-Methode (wudfddi.h)

Artikel
08/08/2023

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die RetrieveDevicePropertyStore-Methode ruft eine Eigenschaftenspeicherschnittstelle ab, die Treiber für den Zugriff auf die Registrierung verwenden können.

Syntax

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
);

Parameter

[in] RootSpecifier

Die Adresse einer vom Treiber zugewiesenen WDF_PROPERTY_STORE_ROOT-Struktur . Der Treiber füllt diese Struktur aus, um den Eigenschaftenspeicher zu identifizieren, den RetrieveDevicePropertyStore abruft.

[in] Flags

Ein WDF_PROPERTY_STORE_RETRIEVE_FLAGS typisiertes Flag, das angibt, ob UMDF einen angegebenen Registrierungseintrag erstellen soll, wenn dieser nicht vorhanden ist, und ob der neue Eintrag beim Neustart von Windows gelöscht werden soll.

[in] DesiredAccess

Eine REGSAM-typisierte Bitmaske, die die Zugriffstypen auf die Registrierung angibt, über die Ihr Treiber verfügen soll. Der REGSAM-Typ ist in Winreg.h definiert und wird in der Windows SDK unter REGSAM beschrieben. Die Bitmaske darf keinen zugriff auf GENERIC_WRITE, KEY_CREATE_SUB_KEY oder WRITE_DAC angeben. (Obwohl der Treiber KEY_CREATE_SUB_KEY nicht angeben kann, kann sein Aufruf von RetrieveDevicePropertyStore einen Unterschlüssel erstellen.)

[in] SubkeyPath

Ein Zeiger auf eine vom Aufrufer bereitgestellte Zeichenfolge, die den Namen eines Unterschlüssels darstellt, der sich unter dem Registrierungsschlüssel befindet, den der RootSpecifier-Parameter angibt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie unter Hinweise.

[out] PropertyStore

Die Adresse eines Speicherorts, der einen Zeiger auf eine IWDFNamedPropertyStore2-Schnittstelle empfängt . Der Treiber verwendet diese Schnittstelle, um auf Werte in der Registrierung zuzugreifen.

[out] Disposition

Die Adresse eines Speicherorts, der einen WDF_PROPERTY_STORE_DISPOSITION typisierten Wert empfängt.

Rückgabewert

RetrieveDevicePropertyStore gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
E_INVALIDARG	Der Aufrufer hat ein ungültiges Eingabeargument bereitgestellt.
E_OUTOFMEMORY	Fehler beim Belegen von Speicher

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Hinweise

Ihr Treiber kann RetrieveDevicePropertyStore aufrufen, um Zugriff auf den Softwareschlüssel des Treibers, den Hardwareschlüssel des aktuellen Geräts, Schlüssel für die Geräteschnittstellen, die das aktuelle Gerät unterstützt, oder auf den DEVICEMAP-Schlüssel zu erhalten.

Wenn Sie den SubkeyPath-Parameter angeben, müssen Sie einen eindeutigen Namen verwenden, z. B. den Dienstnamen des Treibers. Ein Treiber kann einen Unterschlüssel verwenden, um gerätespezifische Informationen zu speichern.

Weitere Informationen zur Verwendung von RetrieveDevicePropertyStore für den Zugriff auf die Registrierung finden Sie unter Verwenden der Registrierung in UMDF-basierten Treibern.

Beispiele

Im folgenden Codebeispiel wird der Wert abgerufen, der dem PortName-Eintrag unter dem Hardwareschlüssel eines Geräts zugewiesen ist.

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);
...

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.9
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Weitere Informationen

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory

Freigeben über