Função IoGetDeviceProperty (wdm.h)

Artigo
02/07/2025

A rotina de IoGetDeviceProperty recupera informações sobre um dispositivo, como informações de configuração e o nome de seu PDO.

Sintaxe

NTSTATUS IoGetDeviceProperty(
  [in]            PDEVICE_OBJECT           DeviceObject,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

Parâmetros

[in] DeviceObject

Ponteiro para o PDO (objeto de dispositivo físico) para o dispositivo que está sendo consultado.

[in] DeviceProperty

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

[in] BufferLength

Especifica o tamanho, em bytes, do PropertyBufferfornecido pelo chamador.

[out, optional] PropertyBuffer

Ponteiro para um buffer fornecido pelo chamador para receber as informações da propriedade. O buffer pode ser alocado de memória paginável. O tipo do buffer é determinado pelo DeviceProperty (consulte acima).

[out] ResultLength

Ponteiro para um ULONG para receber o tamanho das informações de propriedade retornadas em PropertyBuffer . Se IoGetDeviceProperty retornar STATUS_BUFFER_TOO_SMALL, ele definirá esse parâmetro como o comprimento do buffer necessário.

Valor de retorno

IoGetDeviceProperty retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Os valores de retorno de erro possíveis incluem o seguinte.

Código de retorno	Descrição
STATUS_BUFFER_TOO_SMALL	O buffer no PropertyBuffer era muito pequeno. ResultLength aponta para o comprimento do buffer necessário.
STATUS_INVALID_PARAMETER_2	O DeviceProperty determinado não é uma das propriedades tratadas por essa rotina.
STATUS_INVALID_DEVICE_REQUEST	Possivelmente indica que o DeviceObject fornecido não era um ponteiro PDO válido.

Observações

IoGetDeviceProperty recupera informações de instalação do dispositivo do registro. Use essa rotina, em vez de acessar o registro diretamente, para isolar um driver de diferenças entre plataformas e de possíveis alterações na estrutura do Registro.

Para muitas solicitações de DeviceProperty, é possível fazer duas ou mais chamadas para IoGetDeviceProperty para determinar os bufferLength necessários. A primeira chamada deve usar um valor de melhor adivinhação. Se o status de retorno for STATUS_BUFFER_TOO_SMALL, o driver deverá liberar seu buffer atual, alocar um buffer do tamanho retornado em ResultLength e chamar IoGetDeviceProperty novamente. Como algumas das propriedades de instalação são dinâmicas, o tamanho dos dados pode mudar entre o tempo em que o tamanho necessário é retornado e o driver chama essa rotina novamente. Portanto, os drivers devem chamar IoGetDeviceProperty dentro de um loop executado até que o status de retorno não seja STATUS_BUFFER_TOO_SMALL.

Os drivers de função que dão suporte a dispositivos em um barramento herdado e em um barramento PnP podem usar as propriedades DevicePropertyBusNumber, DevicePropertyBusTypeGuide DevicePropertyLegacyBusType para distinguir entre os ônibus.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 2000.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)