Função WdfIoTargetAllocAndQueryTargetProperty (wdfiotarget.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfIoTargetAllocAndQueryTargetProperty aloca um buffer e recupera uma propriedade de dispositivo especificada para um destino de E/S especificado.

Sintaxe

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

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] PoolType

Um valor de tipo POOL_TYPE que especifica o tipo de memória a ser alocado.

[in, optional] PropertyMemoryAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que descreve atributos de objeto para o objeto de memória que a função alocará. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] PropertyMemory

Um ponteiro para um local do tipo WDFMEMORY que recebe um identificador para um objeto de memória de estrutura.

Retornar valor

WdfIoTargetAllocAndQueryTargetProperty 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
STATUS_INVALID_PARAMETER ou STATUS_INVALID_PARAMETER_2	O valor especificado pelo parâmetro DeviceProperty era inválido.
STATUS_INVALID_DEVICE_REQUEST	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

O método WdfIoTargetAllocAndQueryTargetProperty determina a quantidade de memória necessária para manter a propriedade do dispositivo solicitada. Esse método aloca memória suficiente para manter os dados e retorna um identificador para um objeto de memória de estrutura que descreve a memória alocada. Para acessar os dados, o driver pode chamar WdfMemoryGetBuffer.

Para obter mais informações sobre WdfIoTargetAllocAndQueryTargetProperty, 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 chama WdfIoTargetAllocAndQueryTargetProperty para obter a propriedade DevicePropertyFriendlyName . Depois que WdfIoTargetAllocAndQueryTargetProperty retornar, o driver poderá chamar WdfMemoryGetBuffer para obter um ponteiro para o buffer que contém a cadeia de caracteres de nome.

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

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)