Função WdfDeviceQueryPropertyEx (wdfdevice.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

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

Sintaxe

NTSTATUS WdfDeviceQueryPropertyEx(
  [in]  WDFDEVICE                 Device,
  [in]  PWDF_DEVICE_PROPERTY_DATA DeviceProperty,
  [in]  ULONG                     BufferLength,
  [out] PVOID                     PropertyBuffer,
  [out] PULONG                    RequiredSize,
  [out] PDEVPROPTYPE              Type
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] DeviceProperty

Um ponteiro para uma estrutura WDF_DEVICE_PROPERTY_DATA 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] RequiredSize

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.

[out] Type

Um ponteiro para uma variável de DEVPROPTYPE. Se o método for bem-sucedido, ao retornar, esse parâmetro conterá o valor do tipo de propriedade dos dados de propriedade armazenados no PropertyBuffer.

Valor de retorno

Se a operação for bem-sucedida, WdfDeviceQueryPropertyEx retornará STATUS_SUCCESS. Os valores de retorno 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	O valor DeviceProperty especificado é inválido.

O método pode retornar outros valores NTSTATUS .

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Você pode usar WdfDeviceQueryPropertyEx para recuperar qualquer propriedade exposta por meio do modelo de propriedade unificada, enquanto o método WdfDeviceQueryProperty só permite consultar um subconjunto do modelo de propriedade unificada.

Antes de receber dados de propriedade do dispositivo, os drivers normalmente chamam o método WdfDeviceQueryPropertyEx 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 WdfDeviceQueryPropertyEx novamente. Portanto, os drivers devem chamar WdfDeviceQueryPropertyEx dentro de um loop executado até que o status de retorno não seja STATUS_BUFFER_TOO_SMALL.

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

Para obter informações sobre métodos relacionados, consulte Acessando o modelo de propriedade do dispositivo unificado.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.13
versão mínima do UMDF	2.0
cabeçalho	wdfdevice.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	APC_LEVEL

Consulte também

WdfDeviceQueryInterfaceProperty

WdfDeviceQueryProperty

Compartilhar via