Función IoGetDeviceProperty (wdm.h)

Artículo
03/08/2023

La rutina IoGetDeviceProperty recupera información sobre un dispositivo, como la información de configuración y el nombre de su PDO.

Sintaxis

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

Puntero al objeto de dispositivo físico (PDO) para el dispositivo que se consulta.

[in] DeviceProperty

Especifica la propiedad del dispositivo que se solicita. Debe ser uno de los siguientes valores de enumeración DEVICE_REGISTRY_PROPERTY:

DevicePropertyAddress

Solicita la dirección del dispositivo en el bus. PropertyBuffer apunta a un ULONG.

La interpretación de esta dirección es específica del bus. El autor de la llamada de esta rutina debe llamar de nuevo a la rutina para solicitar DevicePropertyBusTypeGuid, o posiblemente devicePropertyLegacyBusType, para que pueda interpretar la dirección. Un valor de dirección de 0xFFFFFFFF indica que el controlador de bus subyacente no ha proporcionado una dirección de bus para el dispositivo.

En la lista siguiente se describe la información que ciertos controladores de autobús almacenan en PropertyBuffer para sus dispositivos secundarios:

En bus	Descripción
1394	No proporciona una dirección porque las direcciones son volátiles. El valor predeterminado es 0xFFFFFFFF.
EISA	Número de ranura (0-F).
IDE	Para un dispositivo IDE, la dirección contiene el identificador de destino y el LUN. Para un canal IDE, la dirección es cero o una (0 = canal principal y 1 = canal secundario).
Isapnp	No proporciona una dirección. El valor predeterminado es 0xFFFFFFFF.
Tarjeta PC (PCMCIA)	Número de socket (normalmente 0x00 o 0x40).
PCI	Número de dispositivo en la palabra alta y el número de función en la palabra baja.
SCSI	Identificador de destino.
USB	Número del puerto.

DevicePropertyBootConfiguration

Solicita los recursos de hardware asignados al dispositivo por el firmware, en formato sin procesar. PropertyBuffer apunta a una estructura CM_RESOURCE_LIST .

DevicePropertyBootConfigurationTranslated

Los recursos de hardware asignados al dispositivo por el firmware, en formato traducido. PropertyBuffer apunta a una estructura CM_RESOURCE_LIST .

DevicePropertyBusNumber

Solicita el número de bus heredado del bus al que está conectado el dispositivo. PropertyBuffer apunta a un ULONG.

DevicePropertyBusTypeGuid

Solicita el GUID del bus al que está conectado el dispositivo. Los GUID de tipo de bus definidos por el sistema se enumeran en el archivo de encabezado Wdmguid.h. PropertyBuffer apunta a un GUID, que es una estructura de 16 bytes que contiene el GUID en formato binario.

DevicePropertyClassGuid

Solicita el GUID para la clase de instalación del dispositivo. PropertyBuffer apunta a una matriz terminada en NULL de WCHAR. Esta rutina devuelve el GUID en un formato de cadena como se indica a continuación, donde cada "c" representa un carácter hexadecimal: {cccccccc-cccc-cccc-cccc-cccccccccc}

DevicePropertyClassName

Solicita el nombre de la clase de instalación del dispositivo, en formato de texto. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyCompatibleIDs

Solicita los identificadores compatibles notificados por el dispositivo. PropertyBuffer apunta a un valor de REG_MULTI_SZ.

DevicePropertyDeviceDescription

Solicita una cadena que describe el dispositivo, como "Microsoft PS/2 Port Mouse", normalmente definido por el fabricante. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyDriverKeyName

Solicita el nombre de la clave del Registro específica del controlador. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyEnumeratorName

Solicita el nombre del enumerador para el dispositivo, como "PCI" o "root". PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyFriendlyName

Solicita una cadena que se puede usar para distinguir entre dos dispositivos similares, normalmente definidos por el instalador de clase. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyHardwareID

Solicita los identificadores de hardware proporcionados por el dispositivo que identifican el dispositivo. PropertyBuffer apunta a un valor de REG_MULTI_SZ.

DevicePropertyInstallState

Solicita el estado de instalación del dispositivo. El estado de instalación se devuelve como un valor de enumeración DEVICE_INSTALL_STATE .

DevicePropertyLegacyBusType

Solicita el tipo de bus, como PCIBus o PCMCIABus. PropertyBuffer apunta a un valor de enumeración INTERFACE_TYPE .

DevicePropertyLocationInformation

Solicita información sobre la ubicación del dispositivo en el bus; la interpretación de esta información es específica del bus. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyManufacturer

Solicita una cadena que identifica al fabricante del dispositivo. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyPhysicalDeviceObjectName

Solicita el nombre del PDO para este dispositivo. PropertyBuffer apunta a una cadena WCHAR terminada en NULL.

DevicePropertyRemovalPolicy

Solicita la directiva de eliminación actual del dispositivo. El sistema operativo usa este valor como sugerencia para determinar cómo se quita normalmente el dispositivo. El parámetro PropertyBuffer apunta a un valor de enumeración DEVICE_REMOVAL_POLICY .

DevicePropertyUINumber

Solicita un número asociado al dispositivo que se puede mostrar en la interfaz de usuario. PropertyBuffer apunta a un valor de ULONG.

Este número suele ser un número de ranura percibido por el usuario, como un número impreso junto a la ranura en la placa, o algún otro número que facilita la localización del dispositivo físico para el usuario. Si el dispositivo está en un bus que no tiene ninguna convención de número de interfaz de usuario o si el controlador de bus del dispositivo no puede determinar el número de interfaz de usuario, este valor es 0xFFFFFFFF.

[in] BufferLength

Especifica el tamaño, en bytes, del propertyBuffer proporcionado por el autor de la llamada.

[out, optional] PropertyBuffer

Puntero a un búfer proporcionado por el autor de la llamada para recibir la información de la propiedad. El búfer se puede asignar desde la memoria paginable. El tipo del búfer viene determinado por DeviceProperty (consulte más arriba).

[out] ResultLength

Puntero a un ULONG para recibir el tamaño de la información de propiedad devuelta en PropertyBuffer. Si IoGetDeviceProperty devuelve STATUS_BUFFER_TOO_SMALL, establece este parámetro en la longitud del búfer necesaria.

Valor devuelto

IoGetDeviceProperty devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes.

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	El búfer de PropertyBuffer era demasiado pequeño. ResultLength apunta a la longitud de búfer necesaria.
STATUS_INVALID_PARAMETER_2	La propiedad DeviceProperty especificada no es una de las propiedades que controla esta rutina.
STATUS_INVALID_DEVICE_REQUEST	Posiblemente indica que deviceObject dado no era un puntero PDO válido.

Comentarios

IoGetDeviceProperty recupera la información de configuración del dispositivo del registro. Use esta rutina, en lugar de acceder al registro directamente, para aislar a un controlador de las diferencias entre plataformas y de los posibles cambios en la estructura del Registro.

Para muchas solicitudes deviceProperty , puede tomar dos o más llamadas a IoGetDeviceProperty para determinar el bufferLength necesario. La primera llamada debe usar un valor de mejor estimación. Si el estado devuelto es STATUS_BUFFER_TOO_SMALL, el controlador debe liberar su búfer actual, asignar un búfer del tamaño devuelto en ResultLength y volver a llamar a IoGetDeviceProperty . Dado que algunas de las propiedades de configuración son dinámicas, el tamaño de los datos puede cambiar entre el momento en que se devuelve el tamaño necesario y el controlador llama a esta rutina de nuevo. Por lo tanto, los controladores deben llamar a IoGetDeviceProperty dentro de un bucle que se ejecute hasta que el estado devuelto no sea STATUS_BUFFER_TOO_SMALL.

Los controladores de funciones que admiten dispositivos en un bus heredado y un bus PnP pueden usar las propiedades DevicePropertyBusNumber, DevicePropertyBusTypeGuid y DevicePropertyLegacyBusType para distinguir entre los buses.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 2000.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)