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:
| Barramento | Descrição |
|---|---|
| 1394 | Não fornece um endereço porque os endereços são voláteis. O padrão é 0xFFFFFFFF. |
| EISA | Número do slot (0-F). |
| IDE | Para um dispositivo IDE, o endereço contém a ID de destino e o LUN. Para um canal IDE, o endereço é zero ou um (0 = canal primário e 1 = canal secundário). |
| ISApnp | Não fornece um endereço. O padrão é 0xFFFFFFFF. |
| Pc Card (PCMCIA) | O número do soquete (normalmente 0x00 ou 0x40). |
| PCI | O número do dispositivo na palavra alta e o número da função na palavra baixa. |
| SCSI | A ID de destino. |
| USB | O número da porta. |
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.
| Código de retorno | Descrição |
|---|---|
| STATUS_BUFFER_TOO_SMALL | O buffer em PropertyBuffer era muito pequeno. ResultLength aponta para o comprimento do buffer necessário. |
| STATUS_INVALID_PARAMETER_2 | A DeviceProperty fornecida 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. |
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
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 2000. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |