Função WdfFdoInitQueryProperty (wdffdo.h)

[Aplica-se a KMDF e UMDF]

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

Sintaxe

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parâmetros

[in] DeviceInit

Um ponteiro para uma estrutura WDFDEVICE_INIT que o driver obteve de sua função de retorno de chamada EvtDriverDeviceAdd .

[in] DeviceProperty

Um valor de 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 a propriedade do dispositivo solicitada. Esse 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 WdfFdoInitQueryProperty armazenou no PropertyBuffer. Se o valor retornado desse método for STATUS_BUFFER_TOO_SMALL, ResultLength receberá o tamanho do buffer necessário.

Retornar valor

Se a operação for bem-sucedida, o método 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	A estrutura WDFDEVICE_INIT não foi obtida da função de retorno de chamada EvtDriverDeviceAdd do driver.

 

O método também pode retornar outros valores NTSTATUS.

Comentários

Antes de receber dados de propriedade do dispositivo, os drivers normalmente devem fazer uma chamada inicial para WdfFdoInitQueryProperty para obter o tamanho do buffer necessário. Para algumas propriedades, o tamanho dos dados pode mudar entre o tempo em que o tamanho necessário é retornado e o tempo que o driver chama essa rotina novamente. Portanto, os drivers devem chamar WdfFdoInitQueryProperty dentro de um loop que é executado até que a status de retorno não seja STATUS_BUFFER_TOO_SMALL.

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

O driver pode chamar WdfFdoInitQueryProperty somente antes de chamar WdfDeviceCreate. Para obter mais informações sobre como chamar WdfDeviceCreate, consulte Criando um objeto de dispositivo framework.

Depois de chamar WdfDeviceCreate, um driver pode obter informações de propriedade do dispositivo chamando WdfDeviceQueryProperty.

Para obter mais informações sobre o método WdfFdoInitQueryProperty , consulte Criando objetos de dispositivo em um driver de função.

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

Exemplos

O exemplo de código a seguir obtém uma cadeia de caracteres Unicode que representa o nome do enumerador de um dispositivo e retorna TRUE se a cadeia de caracteres for "PCI".

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

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	wdffdo.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Confira também

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty