Función FsRtlRemovePerStreamContext (ntifs.h)

Artículo
12/22/2024

FsRtlRemovePerStreamContext quita una estructura de contexto por secuencia de la lista de contextos por secuencia asociados a una secuencia de archivos.

Sintaxis

PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  [in]           PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  [in, optional] PVOID                      OwnerId,
  [in, optional] PVOID                      InstanceId
);

Parámetros

[in] StreamContext

Puntero a la estructura FSRTL_ADVANCED_FCB_HEADER de la secuencia de archivos. Para obtener este puntero de un objeto de archivo, use la macro FsRtlGetPerStreamContextPointer.

[in, optional] OwnerId

Se usa para identificar la información de contexto como perteneciente a un controlador de filtro determinado.

[in, optional] InstanceId

Se usa para buscar una instancia determinada de un contexto por secuencia. Si no se proporciona, se quita y devuelve cualquiera de los contextos que pertenecen al controlador de filtro.

Si no se proporciona ni el OwnerId de ni el InstanceId, se quitará y devolverá cualquier contexto asociado por secuencia.

Valor devuelto

FsRtlRemovePerStreamContext devuelve un puntero al contexto por secuencia que se quita. Si no se encuentra ninguna coincidencia o si el sistema de archivos no admite contextos de filtro, FsRtlRemovePerStreamContext devuelve NULL.

Observaciones

Un controlador de filtro del sistema de archivos llama a FsRtlRemovePerStreamContext para quitar su propia estructura de contexto por secuencia de la lista de contextos por secuencia asociados a una secuencia de archivos.

FsRtlRemovePerStreamContext quita solo la primera estructura de contexto por secuencia coincidente que se encuentra. Si hay contextos de coincidencia adicionales por secuencia, el controlador de filtro debe llamar a FsRtlRemovePerStreamContext tantas veces como sea necesario para quitarlos todos.

Esta rutina solo se debe usar cuando un controlador de filtro necesita descartar la información de contexto que tiene asociada a una secuencia de archivos mientras la secuencia sigue abierta. Por ejemplo, un controlador de filtro podría llamar a FsRtlRemovePerStreamContext en los casos siguientes:

Cuando recibe una solicitud de una aplicación en modo de usuario para detener el registro de solicitudes de E/S en un volumen determinado.
Cuando detecta que se ha cambiado el nombre de un archivo o directorio.

Cuando se cierra una secuencia de archivos, el sistema de archivos es responsable de asegurarse de que todos los contextos por secuencia asociados a esa secuencia se quitan y liberan. Para ello, el sistema de archivos debe llamar a FsRtlTeardownPerStreamContexts en el bloque de control de archivos (FCB) u otro objeto de contexto de secuencia para la secuencia de archivos. FsRtlTeardownPerStreamContexts recorre la lista FilterContexts, quitando cada entrada y llamando a su rutina FreeCallback.

Por lo tanto, un controlador de filtro del sistema de archivos no debe llamar a FsRtlRemovePerStreamContext desde dentro de una rutina de envío de IRP_MJ_CLOSE o IRP_MJ_PNP. No solo sería innecesaria esta llamada, pero también podría interferir con la llamada del sistema de archivos a FsRtlTeardownPerStreamContexts.

Un controlador de filtro del sistema de archivos no debe llamar a FsRtlRemovePerStreamContext desde dentro de la rutina de FreeCallback de una estructura de contexto por secuencia. Esto se debe a que el sistema de archivos subyacente llama a la rutina FreeCallback después de haber quitado la estructura de contexto de la lista FilterContexts.

Para inicializar una estructura de contexto por secuencia, use la macro FsRtlInitPerStreamContext.

Para asociar una estructura de contexto por secuencia inicializada a una secuencia de archivos, llame a FsRtlInsertPerStreamContext.

Para recuperar una estructura de contexto por secuencia asociada a una secuencia de archivos, llame a FsRtlLookupPerStreamContext.

FsRtlRemovePerStreamContext solo se pueden usar en sistemas de archivos que admiten contextos de filtro.

Para obtener más información, vea Per-Stream Contexto de seguimiento en un controlador de filtro del sistema de archivos heredado.

Requisitos

Requisito	Valor
cliente mínimo admitido	Paquete acumulativo de actualizaciones de Windows 2000 SP4; Windows XP
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	<= APC_LEVEL