Función IoCreateStreamFileObject (ntifs.h)

Artículo
08/07/2023

La rutina IoCreateStreamFileObject crea un nuevo objeto de archivo de secuencia.

Sintaxis

PFILE_OBJECT IoCreateStreamFileObject(
  [in, optional] PFILE_OBJECT   FileObject,
  [in, optional] PDEVICE_OBJECT DeviceObject
);

Parámetros

[in, optional] FileObject

Puntero al objeto de archivo al que está relacionado el nuevo archivo de secuencia. Este parámetro es opcional y puede ser NULL.

[in, optional] DeviceObject

Puntero a un objeto de dispositivo para el dispositivo en el que se va a abrir el archivo de secuencia. Si el autor de la llamada especifica un valor distinto de NULL para FileObject, se omite el valor de DeviceObject . De lo contrario, el autor de la llamada debe especificar un valor distinto de NULL para DeviceObject.

Valor devuelto

IoCreateStreamFileObject devuelve un puntero al objeto de archivo de secuencia recién creado.

Comentarios

Los sistemas de archivos llaman a IoCreateStreamFileObject para crear un nuevo objeto de archivo de secuencia. Un objeto de archivo de secuencia es idéntico a un objeto de archivo normal, salvo que se establece la marca de objeto de archivo FO_STREAM_FILE.

Un objeto de archivo de secuencia se usa normalmente para representar una secuencia interna para un volumen montado por el sistema de archivos. Este archivo de volumen virtual permite al sistema de archivos ver, cambiar y almacenar en caché la estructura del volumen en disco como si fuera un archivo normal. En este caso, el parámetro DeviceObject de la llamada a IoCreateStreamFileObject especifica el objeto de dispositivo de volumen (VDO) para el volumen.

Un objeto de archivo de secuencia también se puede usar para representar un flujo de datos alternativo para acceder a los metadatos de un archivo, como atributos extendidos o descriptores de seguridad. En este caso, el parámetro FileObject de la llamada a IoCreateStreamFileObject especifica un objeto de archivo existente para el archivo. El objeto de archivo de secuencia recién creado permite al sistema de archivos ver, cambiar y almacenar en caché los metadatos del archivo como si fuera un archivo normal.

Cuando el objeto de archivo de secuencia ya no es necesario, el autor de la llamada debe disminuir su recuento de referencias llamando a ObDereferenceObject. Cuando el recuento de referencias del objeto de archivo de secuencia alcanza cero, se envía una solicitud de IRP_MJ_CLOSE a la pila de controladores del sistema de archivos para el volumen.

Los escritores de controladores de filtro del sistema de archivos deben tener en cuenta que IoCreateStreamFileObject hace que se envíe una solicitud de IRP_MJ_CLEANUP a la pila de controladores del sistema de archivos para el volumen. Dado que los sistemas de archivos suelen crear objetos de archivo de secuencia como un efecto secundario de las operaciones distintas de IRP_MJ_CREATE, es difícil que los controladores de filtro detecten de forma confiable la creación de objetos de archivo de secuencia. Por lo tanto, un controlador de filtro debe esperar recibir IRP_MJ_CLEANUP y IRP_MJ_CLOSE solicitudes de objetos de archivo no vistos previamente.

Si se produce un error de asignación de grupo, IoCreateStreamFileObject genera una excepción de STATUS_INSUFFICIENT_RESOURCES.