Función ZwFsControlFile (ntifs.h)

Artículo
07/11/2023

La rutina ZwFsControlFile envía un código de control directamente a un sistema de archivos especificado o al controlador de filtro del sistema de archivos, lo que hace que el controlador correspondiente realice la acción especificada.

Sintaxis

NTSYSAPI NTSTATUS ZwFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Parámetros

[in] FileHandle

Identificador devuelto por ZwCreateFile o ZwOpenFile para el objeto de archivo que representa el archivo o directorio en el que se va a realizar la acción especificada. El objeto de archivo debe haberse abierto para E/S asincrónica si el autor de la llamada especifica un evento, ApcRoutine y un contexto de APC (en ApcContext) o un contexto de finalización (en ApcContext).

[in, optional] Event

Identificador de un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se colocará en un estado de espera hasta que se complete la operación solicitada y el evento especificado se establezca en el estado Signaled. Este parámetro es opcional y puede ser NULL. Debe ser NULL si el autor de la llamada esperará a que FileHandle se establezca en el estado Signaled.

[in, optional] ApcRoutine

Dirección de una rutina de APC proporcionada por el autor de la llamada que se llamará cuando se complete la operación solicitada. Este parámetro es opcional y puede ser NULL. Debe ser NULL si hay un objeto de finalización de E/S asociado al objeto de archivo.

[in, optional] ApcContext

Puntero a un área de contexto determinada por el autor de la llamada. Este valor de parámetro se usa como contexto de APC si el autor de la llamada proporciona un APC o se usa como contexto de finalización si se ha asociado un objeto de finalización de E/S al objeto de archivo. Cuando se completa la operación, el contexto de APC se pasa al APC, si se especificó uno o el contexto de finalización se incluye como parte del mensaje de finalización que el Administrador de E/S publica en el objeto de finalización de E/S asociado.

Este parámetro es opcional y puede ser NULL. Debe ser NULL si ApcRoutine es NULL y no hay ningún objeto de finalización de E/S asociado al objeto de archivo.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación. Para llamadas correctas que devuelven datos, el número de bytes escritos en OutputBuffer se devuelve en el miembro Information de esta estructura.

[in] FsControlCode

FSCTL_XXX código que indica qué operación de control del sistema de archivos se va a llevar a cabo. El valor de este parámetro determina los formatos y las longitudes necesarias de InputBuffer y OutputBuffer, así como los pares de parámetros siguientes. Para obtener información detallada sobre los códigos FSCTL_XXX definidos por el sistema, vea la sección "Comentarios" de la entrada de referencia para DeviceIoControl en la documentación de Microsoft Windows SDK.

[in, optional] InputBuffer

Puntero a un búfer de entrada asignado por el autor de la llamada que contiene información específica del dispositivo que se va a proporcionar al controlador de destino. Si FsControlCode especifica una operación que no requiere datos de entrada, este puntero es opcional y puede ser NULL.

[in] InputBufferLength

Tamaño, en bytes, del búfer en InputBuffer. Este valor se omite si InputBuffer es NULL.

[out, optional] OutputBuffer

Puntero a un búfer de salida asignado por el autor de la llamada en el que se devuelve información del controlador de destino. Si FsControlCode especifica una operación que no genera datos de salida, este puntero es opcional y puede ser NULL.

[in] OutputBufferLength

Tamaño, en bytes, del búfer en OutputBuffer. Este valor se omite si OutputBuffer es NULL.

Valor devuelto

ZwFsControlFile devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Comentarios

ZwFsControlFile proporciona una vista coherente de los datos de entrada y salida al sistema y a los controladores en modo kernel, a la vez que proporciona aplicaciones y controladores subyacentes con un método dependiente del controlador para especificar una interfaz de comunicaciones.

Si el autor de la llamada abrió el archivo para E/S asincrónica (sin FILE_SYNCHRONOUS_XXX create/open option set), el evento especificado, si existe, se establecerá en el estado señalado cuando se complete la operación de control del dispositivo. De lo contrario, el objeto de archivo especificado por FileHandle se establecerá en el estado señalado. Si se especificó un ApcRoutine , se llama a con los punteros ApcContext e IoStatusBlock .

Actualmente se documentan los siguientes códigos FSCTL para los controladores en modo kernel:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

Para obtener más información sobre los códigos FSCTL_XXX definidos por el sistema, vea la sección "Comentarios" de la entrada de referencia para DeviceIoControl en la documentación de Microsoft Windows SDK.

Para obtener más información sobre los códigos IOCTL_XXX definidos por el sistema y sobre cómo definir valores de IOCTL_XXX o FSCTL_XXX específicos del controlador, consulte Uso de códigos de control de E/S en la Guía de arquitectura del modo kernel y códigos de control de entrada y salida del dispositivo en la documentación de Windows SDK.

Los minifiltros deben usar FltFsControlFile en lugar de ZwFsControlFile.

Los autores de llamadas de ZwFsControlFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.

Nota Si la llamada a la función ZwFsControlFile se produce en modo de usuario, debe usar el nombre "NtFsControlFile" en lugar de "ZwFsControlFile".

En el caso de las llamadas desde controladores en modo kernel, las versiones **Nt*Xxx*** y **Zw*Xxx*** de una rutina de Servicios del sistema nativo de Windows pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones **Nt*Xxx*** y **Zw*Xxx*** de una rutina, vea [Usar las versiones Nt y Zw de las rutinas de servicios del sistema nativo](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000.
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)