Método IWDFUnifiedPropertyStore::GetPropertyData (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. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]
O método GetPropertyData recupera a configuração atual de uma propriedade de dispositivo.
Sintaxe
HRESULT GetPropertyData(
[in] const DEVPROPKEY *PropertyKey,
[in] LCID Lcid,
[in] ULONG Flags,
[in] ULONG PropertyDataSize,
[out, optional] PVOID PropertyData,
[out] ULONG *PropertyDataRequiredSize,
[out] DEVPROPTYPE *PropertyType
);
Parâmetros
[in] PropertyKey
Um ponteiro para uma estrutura DEVPROPKEY que especifica a chave de propriedade do dispositivo.
[in] Lcid
Especifica um identificador de localidade. Defina esse parâmetro como um valor LCID específico do idioma ou para LOCALE_NEUTRAL. O LOCALE_NEUTRAL LCID especifica que a propriedade é neutra em idioma (ou seja, não específica a nenhum idioma). Não defina esse parâmetro como LOCALE_SYSTEM_DEFAULT ou LOCALE_USER_DEFAULT. Para obter mais informações sobre valores LCID específicos do idioma, consulte Estrutura LCID.
[in] Flags
Reservado para uso do sistema. Os drivers devem definir esse valor como 0.
[in] PropertyDataSize
O tamanho, em bytes, do buffer para o qual PropertyData aponta.
[out, optional] PropertyData
Um ponteiro para os dados da propriedade do dispositivo.
[out] PropertyDataRequiredSize
Um ponteiro para um ULONG para receber o tamanho das informações de propriedade retornadas em PropertyData.
[out] PropertyType
Um ponteiro para um valor DEVPROPTYPE . Se GetPropertyData for concluído com êxito, o método usará PropertyType para fornecer o tipo de dados retornado no buffer PropertyData .
Retornar valor
GetPropertyData retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar os valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Falha na tentativa da estrutura de alocar memória. |
|
O parâmetro PropertyDataRequiredSize contém o tamanho do buffer necessário. |
|
Se o driver especificar WdfPropertyStoreRootClassDeviceInterfaceKey, a interface solicitada deverá ser aquela que o driver UMDF registrou anteriormente. |
|
O driver pode solicitar dados de propriedade da interface do dispositivo apenas começando com Windows 8. |
Esse método pode retornar um dos outros valores que Winerror.h contém.
Comentários
Os drivers baseados em estrutura usam o método GetPropertyData para recuperar as propriedades do dispositivo definidas como parte do modelo de propriedade do dispositivo unificado.
Em particular, você pode usar esse método para recuperar a chave de hardware de um dispositivo ou uma instância de uma classe de interface de dispositivo. Quando você chamar IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, defina o membro RootClass do parâmetro RootSpecifier como WdfPropertyStoreRootClassHardwareKey ou WdfPropertyStoreRootClassDeviceInterfaceKey.
Se você especificar WdfPropertyStoreRootClassHardwareKey, ao chamar GetPropertyData, deverá fornecer um valor DEVPROPKEY personalizado no parâmetro PropertyKey e não uma chave definida por PnP. O valor deve ter sido definido anteriormente chamando SetPropertyData, uma função de propriedade de dispositivo SetupDI ou usando a diretiva INF AddProperty.
Para obter mais informações sobre as propriedades do dispositivo, consulte Propriedades do dispositivo.
Para obter mais informações sobre como acessar o registro, consulte Usando o Registro em drivers baseados em UMDF.
Exemplos
Para propriedades de tamanho variável, o driver deve fazer duas passagens para recuperar os dados da propriedade. Primeiro, o driver deve passar um buffer NULL no parâmetro PropertyData e definir PropertyDataSize como 0. Em seguida, o driver deve alocar um buffer com base no PropertyDataRequiredSize retornado e chamar GetPropertyData novamente, passando o buffer alocado.
O exemplo a seguir demonstra esse padrão.
HRESULT
GetFriendlyName(
_In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
)
{
HRESULT hr = S_OK;
DEVPROPTYPE type;
ULONG requiredSize;
BYTE * friendlyNameBuffer = NULL;
ULONG friendlyNameBufferSize;
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
0, //BufferSize
NULL, //Buffer
&requiredSize,
&type
);
if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
friendlyNameBufferSize = requiredSize;
friendlyNameBuffer = new BYTE[requiredSize];
if (NULL == friendlyNameBuffer)
{
hr = E_OUTOFMEMORY;
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Out of memory while allocating property data buffer returning:”
“ %!HRESULT!",
hr
);
goto exit;
}
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
friendlyNameBufferSize,
friendlyNameBuffer,
&requiredSize,
&type
);
if (FAILED(hr))
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
if (type != DEVPROP_TYPE_STRING)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Expected type %d, actual type: %d",
DEVPROP_TYPE_STRING,
type
);
hr = E_UNEXPECTED;
goto exit;
}
exit:
delete [] friendlyNameBuffer;
friendlyNameBuffer = NULL;
return hr;
}
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.11 |
| Cabeçalho | wudfddi.h |
| DLL | WUDFx.dll |
Confira também
IWDFUnifiedPropertyStoreFactory