Função IoGetDeviceProperty (wdm.h)

A rotina 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

Especifica a propriedade do dispositivo que está sendo solicitada. Deve ser um dos seguintes valores de enumeração DEVICE_REGISTRY_PROPERTY :

DevicePropertyAddress

Solicita o endereço do dispositivo no barramento. PropertyBuffer aponta para um ULONG.

A interpretação desse endereço é específica do barramento. O chamador dessa rotina deve chamar a rotina novamente para solicitar o DevicePropertyBusTypeGuid ou, possivelmente, o DevicePropertyLegacyBusType, para que ele possa interpretar o endereço. Um valor de endereço de 0xFFFFFFFF indica que o motorista do ônibus subjacente não forneceu um endereço de ônibus para o dispositivo.

A lista a seguir descreve as informações que determinados motoristas de ônibus armazenam no PropertyBuffer para seus dispositivos filho:

DevicePropertyBootConfiguration

Solicita os recursos de hardware atribuídos ao dispositivo pelo firmware, em forma bruta. PropertyBuffer aponta para uma estrutura de CM_RESOURCE_LIST .

DevicePropertyBootConfigurationTranslated

Os recursos de hardware atribuídos ao dispositivo pelo firmware, em formato traduzido. PropertyBuffer aponta para uma estrutura de CM_RESOURCE_LIST .

DevicePropertyBusNumber

Solicita o número do barramento herdado ao qual o dispositivo está conectado. PropertyBuffer aponta para um ULONG.

DevicePropertyBusTypeGuid

Solicita o GUID para o barramento ao qual o dispositivo está conectado. Os GUIDs do tipo de barramento definido pelo sistema são listados no arquivo de cabeçalho Wdmguid.h. PropertyBuffer aponta para um GUID, que é uma estrutura de 16 bytes que contém o GUID em formato binário.

DevicePropertyClassGuid

Solicita o GUID para a classe de instalação do dispositivo. PropertyBuffer aponta para uma matriz terminada em NULL do WCHAR. Essa rotina retorna o GUID em um formato de cadeia de caracteres da seguinte maneira, em que cada "c" representa um caractere hexadecimal: {cccccc-cccc-cccc-cccccccccc}

DevicePropertyClassName

Solicita o nome da classe de instalação do dispositivo, em formato de texto. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyCompatibleIDs

Solicita as IDs compatíveis relatadas pelo dispositivo. PropertyBuffer aponta para um valor REG_MULTI_SZ.

DevicePropertyDeviceDescription

Solicita uma cadeia de caracteres que descreve o dispositivo, como "Microsoft PS/2 Port Mouse", normalmente definida pelo fabricante. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyDriverKeyName

Solicita o nome da chave do Registro específica do driver. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyEnumeratorName

Solicita o nome do enumerador para o dispositivo, como "PCI" ou "raiz". PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyFriendlyName

Solicita uma cadeia de caracteres que pode ser usada para distinguir entre dois dispositivos semelhantes, normalmente definidos pelo instalador de classe. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyHardwareID

Solicita as IDs de hardware fornecidas pelo dispositivo que identificam o dispositivo. PropertyBuffer aponta para um valor REG_MULTI_SZ.

DevicePropertyInstallState

Solicita o estado de instalação do dispositivo. O estado de instalação é retornado como um valor de enumeração DEVICE_INSTALL_STATE .

DevicePropertyLegacyBusType

Solicita o tipo de barramento, como PCIBus ou PCMCIABus. PropertyBuffer aponta para um valor de enumeração INTERFACE_TYPE.

DevicePropertyLocationInformation

Solicita informações sobre a localização do dispositivo no barramento; a interpretação dessas informações é específica do barramento. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyManufacturer

Solicita uma cadeia de caracteres que identifica o fabricante do dispositivo. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyPhysicalDeviceObjectName

Solicita o nome do PDO para este dispositivo. PropertyBuffer aponta para uma cadeia de caracteres WCHAR terminada em NULL.

DevicePropertyRemovalPolicy

Solicita a política de remoção atual do dispositivo. O sistema operacional usa esse valor como uma dica para determinar como o dispositivo é normalmente removido. O parâmetro PropertyBuffer aponta para um valor de enumeração DEVICE_REMOVAL_POLICY .

DevicePropertyUINumber

Solicita um número associado ao dispositivo que pode ser exibido na interface do usuário. PropertyBuffer aponta para um valor ULONG.

Esse número normalmente é um número de slot percebido pelo usuário, como um número impresso ao lado do slot no quadro ou algum outro número que facilita a localização do dispositivo físico para o usuário. Se o dispositivo estiver em um barramento sem convenção de número de interface do usuário ou se o driver de barramento do dispositivo não puder determinar o número da interface do usuário, esse valor será 0xFFFFFFFF.

[in] BufferLength

Especifica o tamanho, em bytes, do PropertyBuffer fornecido pelo chamador.

[out, optional] PropertyBuffer

Ponteiro para um buffer fornecido pelo chamador para receber as informações da propriedade. O buffer pode ser alocado da memória paginável. O tipo do buffer é determinado pela DeviceProperty (veja 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.

Retornar valor

IoGetDeviceProperty retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Possíveis valores retornados por erro incluem o seguinte.

Comentários

IoGetDeviceProperty recupera informações de configuraçã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 , pode levar duas ou mais chamadas para IoGetDeviceProperty para determinar o BufferLength necessário. A primeira chamada deve usar um valor de melhor suposição. Se a 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 que é executado até que a 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, DevicePropertyBusTypeGuid e DevicePropertyLegacyBusType para distinguir entre os barramentos.

Requisitos

Confira também

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST