Función IoCreateStreamFileObjectEx2 (ntifs.h)

Artículo
05/23/2024

La rutina IoCreateStreamFileObjectEx2 crea un nuevo objeto de archivo de secuencia con opciones de creación para un objeto de dispositivo de destino.

Sintaxis

NTSTATUS IoCreateStreamFileObjectEx2(
  [in]            PIO_CREATE_STREAM_FILE_OPTIONS CreateOptions,
  [in, optional]  PFILE_OBJECT                   FileObject,
  [in, optional]  PDEVICE_OBJECT                 DeviceObject,
  [out]           PFILE_OBJECT                   *StreamFileObject,
  [out, optional] PHANDLE                        FileHandle
);

Parámetros

[in] CreateOptions

Puntero a una estructura de IO_CREATE_STREAM_FILE_OPTIONS que contiene las opciones de creación para el nuevo objeto de archivo de secuencia.

[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.

[out] StreamFileObject

Puntero a un puntero de objeto de dispositivo para recibir el objeto de archivo de secuencia.

[out, optional] FileHandle

Puntero a un identificador de archivo para la secuencia en la salida. Este parámetro es opcional y puede ser NULL.

Valor devuelto

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

Comentarios

Los sistemas de archivos llaman a IoCreateStreamFileObjectEx2 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 .

Normalmente, un objeto de archivo de secuencia se usa 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 IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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 IoCreateStreamFileObjectEx2 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 detectar de forma confiable la creación de objetos de archivo de secuencia. Por lo tanto, un controlador de filtro debe esperarrecibir IRP_MJ_CLEANUP yIRP_MJ_CLOSE solicitudes de objetos de archivo no vistos anteriormente.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE