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

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método RetrieveDevicePropertyStore recupera uma interface de repositório de propriedades que os drivers podem usar para acessar o registro.

Sintaxe

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

Parâmetros

[in] RootSpecifier

O endereço de uma estrutura de WDF_PROPERTY_STORE_ROOT alocada pelo driver. O driver preenche essa estrutura para identificar o repositório de propriedades recuperado por RetrieveDevicePropertyStore .

[in] Flags

Um sinalizador do tipo WDF_PROPERTY_STORE_RETRIEVE_FLAGS que especifica se o UMDF deve criar uma entrada de registro especificada se ela não existir e se a nova entrada deve ser excluída quando o Windows for reiniciado.

[in] DesiredAccess

Uma máscara de bits do tipo REGSAM que especifica os tipos de acesso ao registro que você deseja que o driver tenha. O tipo REGSAM é definido em Winreg.h e é descrito no SDK do Windows em REGSAM. A máscara de bits não deve especificar GENERIC_WRITE, KEY_CREATE_SUB_KEY ou acesso WRITE_DAC. (Embora o driver não possa especificar KEY_CREATE_SUB_KEY, sua chamada para RetrieveDevicePropertyStore pode criar uma subchave.)

[in] SubkeyPath

Um ponteiro para uma cadeia de caracteres fornecida pelo chamador que representa o nome de uma subchave localizada sob a chave do Registro especificada pelo parâmetro RootSpecifier . Esse parâmetro é opcional e pode ser NULL. Confira mais informações em Comentários.

[out] PropertyStore

O endereço de um local que recebe um ponteiro para uma interface IWDFNamedPropertyStore2 . O driver usa essa interface para acessar valores no Registro.

[out] Disposition

O endereço de um local que recebe um valor de tipo WDF_PROPERTY_STORE_DISPOSITION.

Retornar valor

RetrieveDevicePropertyStore retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
E_INVALIDARG	O chamador forneceu um argumento de entrada inválido.
E_OUTOFMEMORY	Falha ao tentar alocar memória.

 

Esse método pode retornar um dos outros valores que Winerror.h contém

Comentários

Seu driver pode chamar RetrieveDevicePropertyStore para obter acesso à chave de software do driver, a chave de hardware do dispositivo atual, chaves para as interfaces de dispositivo compatíveis com o dispositivo atual ou a chave DEVICEMAP .

Se você fornecer o parâmetro SubkeyPath , deverá usar um nome exclusivo, como o nome de serviço do driver. Um driver pode usar uma subchave para armazenar informações específicas do dispositivo.

Para obter mais informações sobre como usar RetrieveDevicePropertyStore para acessar o registro, consulte Usando o Registro em Drivers baseados em UMDF.

Exemplos

O exemplo de código a seguir recupera o valor atribuído à entrada PortName sob a chave de hardware de um 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);
...

Requisitos

Requisito	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1,9
Cabeçalho	wudfddi.h (inclua Wudfddi.h)
DLL	WUDFx.dll

Confira também

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory