Função WdfDeviceAllocAndQueryProperty (wdfdevice.h)

  • Artigo

[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 do tipo DEVICE_REGISTRY_PROPERTY que identifica a propriedade do dispositivo a ser recuperada.

[in] PoolType

Um enumerador do 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

Se a operação for bem-sucedida, WdfDeviceAllocAndQueryProperty retornará STATUS_SUCCESS. Os valores retornados 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.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

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, seu 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 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 retornar, o driver poderá 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
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)

Confira também

WdfDeviceQueryProperty