Função WdfDeviceAllocAndQueryProperty (wdfdevice.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfDeviceAllocAndQueryProperty aloca um buffer e recupera uma propriedade de dispositivo especificada.

Sintaxe

NTSTATUS WdfDeviceAllocAndQueryProperty(
  [in]           WDFDEVICE                Device,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] DeviceProperty

Um enumerador DEVICE_REGISTRY_PROPERTYdigitado que identifica a propriedade do dispositivo a ser recuperada.

[in] PoolType

Um enumerador POOL_TYPEdigitado que especifica o tipo de memória a ser alocada.

[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 da estrutura.

Valor de retorno

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

Código de retorno	Descrição
STATUS_INVALID_PARAMETER ou 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 .

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

Observações

O método WdfDeviceAllocAndQueryProperty determina a quantidade de memória necessária para manter a propriedade do dispositivo solicitada. Ele aloca memória suficiente para armazenar 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.

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

Exemplos

O exemplo de código a seguir inicializa uma estrutura de WDF_OBJECT_ATTRIBUTES com atributos para o objeto de memória da estrutura que a estrutura criará para a propriedade solicitada. Em seguida, o exemplo chama WdfDeviceAllocAndQueryProperty para obter a propriedade DevicePropertyPhysicalDeviceObjectName. Depois que wdfDeviceAllocAndQueryProperty retorna, o driver pode chamar WdfMemoryGetBuffer para obter um ponteiro para o buffer que contém a cadeia de caracteres de nome.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFDEVICE  device;
WDFMEMORY  memory;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = device;

status = WdfDeviceAllocAndQueryProperty(device,
                                        DevicePropertyPhysicalDeviceObjectName,
                                        NonPagedPool,
                                        &attributes,
                                        &memory
                                        );
if (!NT_SUCCESS(status)) {
    return STATUS_UNSUCCESSFUL;
}

Requisitos

Requisito	Valor
da 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)

Consulte também

WdfDeviceQueryProperty

Compartilhar via