Función IoGetDeviceObjectPointer (wdm.h)

Artículo
08/08/2023

La rutina IoGetDeviceObjectPointer devuelve un puntero al objeto superior de la pila del objeto de dispositivo con nombre y un puntero al objeto de archivo correspondiente, si se puede conceder el acceso solicitado a los objetos.

Sintaxis

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Parámetros

[in] ObjectName

Puntero a un búfer que contiene una cadena Unicode que es el nombre del objeto de dispositivo.

[in] DesiredAccess

Especifica el valor de ACCESS_MASK que representa el acceso deseado. Normalmente DesiredAccess es FILE_READ_DATA. Con poca frecuencia, se especifican los derechos de acceso FILE_WRITE_DATA o FILE_ALL_ACCESS.

[out] FileObject

Puntero al objeto de archivo que representa el objeto de dispositivo correspondiente al código en modo de usuario si la llamada se realiza correctamente.

[out] DeviceObject

Puntero al objeto de dispositivo que representa el dispositivo lógico, virtual o físico con nombre si la llamada se realiza correctamente.

Valor devuelto

IoGetDeviceObjectPointer devuelve STATUS_SUCCESS si se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado:

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

Comentarios

IoGetDeviceObjectPointer establece una "conexión" entre el autor de la llamada y el controlador de nivel inferior siguiente. Un llamador correcto puede usar el puntero de objeto de dispositivo devuelto para inicializar sus propios objetos de dispositivo. También se puede usar como argumento para IoAttachDeviceToDeviceStack, IoCallDriver y cualquier rutina que cree IRP para controladores inferiores. El puntero devuelto es un argumento obligatorio para IoCallDriver.

Esta rutina también devuelve un puntero al objeto de archivo correspondiente. Cuando se descarga, un controlador puede desreferenciar el objeto de archivo como medio de desreferenciar indirectamente el objeto de dispositivo. Para ello, el controlador llama a ObDereferenceObject desde su rutina Unload, pasando el puntero de objeto de archivo devuelto por IoGetDeviceObjectPointer. Si no se desreferencia el objeto de dispositivo en la rutina Unload de un controlador, se impide que se descargue el controlador siguiente inferior. Sin embargo, los controladores que cierran el objeto de archivo antes del proceso de descarga deben sacar una referencia adicional en el objeto de dispositivo antes de desreferenciar el objeto de archivo. De lo contrario, la desreferenciación del objeto de archivo puede provocar una eliminación prematura del objeto de dispositivo.

Para obtener un puntero al controlador de nivel superior de la pila de controladores del sistema de archivos, un controlador debe asegurarse de que el sistema de archivos está montado; Si no es así, esta rutina atraviesa la pila de dispositivos de almacenamiento. Para asegurarse de que el sistema de archivos está montado en el dispositivo de almacenamiento, el controlador debe especificar una máscara de acceso adecuada, como FILE_READ_DATA o FILE_WRITE_ATTRIBUTES, en el parámetro DesiredAccess . Especificar FILE_READ_ATTRIBUTES no hace que se monte el sistema de archivos.

Después de que cualquier controlador de nivel superior se encadene por encima de otro controlador llamando correctamente a esta rutina, el controlador de nivel superior debe establecer el campo StackSize en su objeto de dispositivo en el del objeto de dispositivo del controlador de nivel inferior más uno.

Los autores de llamadas de IoGetDeviceObjectPointer deben ejecutarse en IRQL = PASSIVE_LEVEL.

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	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)