Metodo IWDFPropertyStoreFactory::RetrieveDevicePropertyStore (wudfddi.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità 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, vedi Introduzione a UMDF.]

Il metodo RetrieveDevicePropertyStore recupera un'interfaccia dell'archivio delle proprietà che i driver possono usare per accedere al Registro di sistema.

Sintassi

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

Parametri

[in] RootSpecifier

Indirizzo di una struttura di WDF_PROPERTY_STORE_ROOT allocata dal driver. Il driver compila questa struttura per identificare l'archivio delle proprietà recuperato RetrieveDevicePropertyStore.

[in] Flags

Flag WDF_PROPERTY_STORE_RETRIEVE_FLAGStipizzato che specifica se UMDF deve creare una voce del Registro di sistema specificata se non esiste e se la nuova voce deve essere eliminata al riavvio di Windows.

[in] DesiredAccess

Maschera di bit tipizzata REGSAM che specifica i tipi di accesso al Registro di sistema che si desidera che il driver abbia. Il tipo REGSAM è definito in Winreg.h ed è descritto in Windows SDK in REGSAM. La maschera di bit non deve specificare GENERIC_WRITE, KEY_CREATE_SUB_KEY o WRITE_DAC l'accesso. Sebbene il driver non possa specificare KEY_CREATE_SUB_KEY, la chiamata a RetrieveDevicePropertyStore può creare una sottochiave.

[in] SubkeyPath

Puntatore a una stringa di caratteri fornita dal chiamante che rappresenta il nome di una sottochiave che si trova nella chiave del Registro di sistema specificata dal RootSpecifier parametro. Questo parametro è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni.

[out] PropertyStore

Indirizzo di una posizione che riceve un puntatore a un'interfaccia IWDFNamedPropertyStore2. Il driver usa questa interfaccia per accedere ai valori nel Registro di sistema.

[out] Disposition

Indirizzo di una posizione che riceve un valore WDF_PROPERTY_STORE_DISPOSITION-typed.

Valore restituito

RetrieveDevicePropertyStore restituisce S_OK se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
E_INVALIDARG	Il chiamante ha fornito un argomento di input non valido.
E_OUTOFMEMORY	Tentativo di allocazione della memoria non riuscito.

Questo metodo potrebbe restituire uno degli altri valori contenuti in Winerror.h

Osservazioni

Il driver può chiamare RetrieveDevicePropertyStore per ottenere l'accesso alla chiave software del driver, alla chiave hardware del dispositivo corrente, alle chiavi per le interfacce del dispositivo supportate dal dispositivo corrente o alla chiave DEVICEMAP.

Se si specifica il parametro SubkeyPath, è necessario usare un nome univoco, ad esempio il nome del servizio del driver. Un driver potrebbe usare una sottochiave per archiviare informazioni specifiche del dispositivo.

Per altre informazioni sull'uso di RetrieveDevicePropertyStore per accedere al Registro di sistema, vedere Uso del Registro di sistema nei driver basati su UMDF.

Esempi

L'esempio di codice seguente recupera il valore assegnato alla voce PortName sotto la chiave hardware di un dispositivo.

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

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.9
intestazione	wudfddi.h (include Wudfddi.h)
dll	WUDFx.dll

Vedere anche

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory

Condividi tramite