Função WdfIoTargetQueryTargetProperty (wdfiotarget.h)
[Aplica-se somente ao KMDF]
O método WdfIoTargetQueryTargetProperty recupera uma propriedade de dispositivo especificada para um destino de E/S especificado.
Sintaxe
NTSTATUS WdfIoTargetQueryTargetProperty(
[in] WDFIOTARGET IoTarget,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Parâmetros
[in] IoTarget
Um identificador para um objeto de destino de E/S local ou remoto que foi obtido de uma chamada anterior para WdfDeviceGetIoTarget ou WdfIoTargetCreate ou de um método fornecido por um destino de E/S especializado.
[in] DeviceProperty
Um valor do tipo DEVICE_REGISTRY_PROPERTY que identifica a propriedade do dispositivo a ser recuperada.
[in] BufferLength
O tamanho, em bytes, do buffer para o qual PropertyBuffer aponta.
[out, optional] PropertyBuffer
Um ponteiro para um buffer alocado pelo chamador que recebe as informações de propriedade do dispositivo solicitadas. Esse ponteiro poderá ser NULL se BufferLength for zero.
[out] ResultLength
Um ponteiro para um local que, no retorno, contém o tamanho, em bytes, das informações que WdfIoTargetQueryTargetProperty armazenou no buffer para o qual PropertyBuffer aponta. Se WdfIoTargetQueryTargetProperty retornar STATUS_BUFFER_TOO_SMALL, esse local receberá o tamanho do buffer necessário.
Retornar valor
WdfIoTargetQueryTargetProperty retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
O buffer que o parâmetro PropertyBuffer apontou era muito pequeno para receber as informações solicitadas. |
|
O valor especificado pelo parâmetro DeviceProperty era inválido. |
|
Os drivers do dispositivo ainda não relataram as propriedades do dispositivo. |
Esse método também pode retornar outros valores NTSTATUS.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
Antes que os drivers recebam dados de propriedade do dispositivo, eles normalmente chamam o método WdfIoTargetQueryTargetProperty para obter o tamanho do buffer necessário. Para algumas propriedades, o tamanho dos dados pode ser alterado entre quando o tamanho necessário é retornado e quando o driver chama WdfIoTargetQueryTargetProperty novamente. Portanto, os drivers devem chamar WdfIoTargetQueryTargetProperty dentro de um loop que é executado até que a status de retorno não seja STATUS_BUFFER_TOO_SMALL.
Em vez de chamar WdfIoTargetQueryTargetProperty, o driver pode chamar WdfIoTargetAllocAndQueryTargetProperty, que aloca um buffer e coloca as informações da propriedade no buffer.
Para obter mais informações sobre WdfIoTargetQueryTargetProperty, consulte Obtendo informações sobre um destino de E/S geral.
Para obter mais informações sobre destinos de E/S, consulte Usando destinos de E/S.
Exemplos
O exemplo de código a seguir obtém a propriedade DevicePropertyUINumber de um dispositivo. O exemplo chama WdfIoTargetQueryTargetProperty em vez de WdfIoTargetAllocAndQueryTargetProperty porque o comprimento de um número de interface do usuário é conhecido.
ULONG targetUINumber, resultLength;
NTSTATUS status;
status = WdfIoTargetQueryTargetProperty(
target,
DevicePropertyUINumber,
sizeof(targetNumber),
&targetUINumber,
&resultLength
);
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Cabeçalho | wdfiotarget.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.) |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |