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