IWDFPropertyStoreFactory::RetrieveDevicePropertyStore-Methode (wudfddi.h)

Artikel
02/07/2025

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. 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, der abgerufen RetrieveDevicePropertyStore abruft.

[in] Flags

Ein WDF_PROPERTY_STORE_RETRIEVE_FLAGS-typed-Flag, das angibt, ob UMDF einen angegebenen Registrierungseintrag erstellen soll, wenn er nicht vorhanden ist, und ob der neue Eintrag gelöscht werden soll, wenn Windows neu gestartet wird.

[in] DesiredAccess

Eine REGSAM-typierte Bitmaske, die die Typen des Zugriffs auf die Registrierung angibt, über die Der Treiber verfügen soll. Der REGSAM-Typ ist in Winreg.h definiert und wird im Windows SDK unter REGSAM-beschrieben. Die Bitmaske darf nicht GENERIC_WRITE, KEY_CREATE_SUB_KEY oder WRITE_DAC Zugriff angeben. (Obwohl der Treiber KEY_CREATE_SUB_KEY nicht angeben kann, kann der 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-werden. Weitere Informationen finden Sie in den Anmerkungen.

[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-typed-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 Versuch, Arbeitsspeicher zuzuweisen.

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

Bemerkungen

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 den DEVICEMAP--Schlüssel zu erhalten.

Wenn Sie den parameter SubkeyPath angeben, müssen Sie einen eindeutigen Namen verwenden, z. B. den Dienstnamen des Treibers. Ein Treiber verwendet möglicherweise einen Unterschlüssel, 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
Mindest-UMDF-Version	1.9
Header-	wudfddi.h (include Wudfddi.h)
DLL-	WUDFx.dll

Siehe auch

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory-

Freigeben über