Función IoGetDeviceProperty (wdm.h)
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) |