Função WdfDeviceQueryProperty (wdfdevice.h)

  • Artigo

[Aplica-se a KMDF e UMDF]

O método WdfDeviceQueryProperty recupera uma propriedade de dispositivo especificada.

Sintaxe

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] DeviceProperty

Um enumerador do tipo DEVICE_REGISTRY_PROPERTY que identifica a propriedade do dispositivo a ser recuperada.

[in] BufferLength

O tamanho, em bytes, do buffer apontado por PropertyBuffer.

[out] PropertyBuffer

Um ponteiro fornecido pelo chamador para um buffer alocado pelo chamador que recebe as informações solicitadas. O ponteiro poderá ser NULL se o parâmetro BufferLength for zero.

[out] ResultLength

Um local fornecido pelo chamador que, no retorno, contém o tamanho, em bytes, das informações que o método armazenou em PropertyBuffer. Se o valor retornado da função for STATUS_BUFFER_TOO_SMALL, esse local receberá o tamanho do buffer necessário.

Retornar valor

Se a operação for bem-sucedida, WdfDeviceQueryProperty retornará STATUS_SUCCESS. Os valores retornados adicionais incluem:

Código de retorno Descrição
STATUS_BUFFER_TOO_SMALL
 O buffer fornecido é muito pequeno para receber as informações.
STATUS_INVALID_PARAMETER_2
 O valor deviceproperty especificado é inválido
STATUS_INVALID_DEVICE_REQUEST
 Os drivers do dispositivo ainda não relataram as propriedades do dispositivo.
 

O método pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Antes de receber dados de propriedade do dispositivo, os drivers normalmente chamam o método WdfDeviceQueryProperty apenas para obter o tamanho do buffer necessário. Para algumas propriedades, o tamanho dos dados pode mudar entre quando o tamanho necessário é retornado e quando o driver chama WdfDeviceQueryProperty novamente. Portanto, os drivers devem chamar WdfDeviceQueryProperty dentro de um loop que é executado até que a status de retorno não seja STATUS_BUFFER_TOO_SMALL.

É melhor usar WdfDeviceQueryProperty somente se o tamanho do buffer necessário for conhecido e inalterado, pois nesse caso o driver precisa chamar WdfDeviceQueryProperty apenas uma vez. Se o tamanho do buffer necessário for desconhecido ou variar, o driver deverá chamar WdfDeviceAllocAndQueryProperty.

Como alternativa, você pode usar WdfDeviceQueryPropertyEx para acessar as propriedades do dispositivo expostas por meio do Modelo de Propriedade Unificada.

Exemplos

O exemplo de código a seguir obtém a propriedade DevicePropertyBusTypeGuid de um dispositivo. O exemplo chama WdfDeviceQueryProperty em vez de WdfDeviceAllocAndQueryProperty porque o comprimento de um GUID é conhecido.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Requisitos

Requisito Valor
Plataforma de Destino Universal
Versão mínima do KMDF 1.0
Versão mínima do UMDF 2,0
Cabeçalho wdfdevice.h (inclua Wdf.h)
Biblioteca Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
Regras de conformidade de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Confira também

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty