Funzione ZwFsControlFile (ntifs.h)

Articolo
12/21/2024

La routine ZwFsControlFile invia direttamente un codice di controllo a un file system o a un driver di filtro del file system specificato, causando l'esecuzione dell'azione specificata da parte del driver corrispondente.

Sintassi

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
);

Parametri

[in] FileHandle

Handle restituito da ZwCreateFile o ZwOpenFile per l'oggetto file che rappresenta il file o la directory in cui deve essere eseguita l'azione specificata. L'oggetto file deve essere stato aperto per l'I/O asincrona se il chiamante specifica un Event, ApcRoutinee un contesto APC (in ApcContext) o un contesto di completamento (in ApcContext).

[in, optional] Event

Handle per un evento creato dal chiamante. Se questo parametro viene fornito, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione richiesta e l'evento specificato viene impostato sullo stato Segnalato. Questo parametro è facoltativo e può essere NULL. Deve essere NULL se il chiamante attenderà che il FileHandle venga impostato sullo stato Segnalato.

[in, optional] ApcRoutine

Indirizzo di una routine APC fornita dal chiamante da chiamare al termine dell'operazione richiesta. Questo parametro è facoltativo e può essere NULL. Deve essere NULL se è presente un oggetto di completamento I/O associato all'oggetto file.

[in, optional] ApcContext

Puntatore a un'area di contesto determinata dal chiamante. Questo valore di parametro viene usato come contesto APC se il chiamante fornisce un APC o viene usato come contesto di completamento se un oggetto completamento I/O è stato associato all'oggetto file. Al termine dell'operazione, il contesto APC viene passato al APC, se è stato specificato o il contesto di completamento viene incluso come parte del messaggio di completamento che gestione I/O invia all'oggetto di completamento A/O associato.

Questo parametro è facoltativo e può essere NULL. Deve essere NULL se ApcRoutine è NULL e all'oggetto file non è associato alcun oggetto di completamento I/O.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione. Per le chiamate riuscite che restituiscono dati, il numero di byte scritti nel OutputBuffer viene restituito nel membro informazioni di questa struttura.

[in] FsControlCode

FSCTL_xxx codice che indica quale operazione di controllo del file system deve essere eseguita. Il valore di questo parametro determina i formati e le lunghezze necessarie del InputBuffer e OutputBuffer, nonché quali delle coppie di parametri seguenti sono necessarie. Per informazioni dettagliate sui codici FSCTL_XXX definiti dal sistema, vedere la sezione "Osservazioni" della voce di riferimento per DeviceIoControl nella documentazione di Microsoft Windows SDK.

[in, optional] InputBuffer

Puntatore a un buffer di input allocato dal chiamante che contiene informazioni specifiche del dispositivo da assegnare al driver di destinazione. Se FsControlCode specifica un'operazione che non richiede dati di input, questo puntatore è facoltativo e può essere NULL.

[in] InputBufferLength

Dimensioni, in byte, del buffer in corrispondenza di InputBuffer. Questo valore viene ignorato se InputBuffer è NULL.

[out, optional] OutputBuffer

Puntatore a un buffer di output allocato dal chiamante in cui le informazioni vengono restituite dal driver di destinazione. Se FsControlCode specifica un'operazione che non produce dati di output, questo puntatore è facoltativo e può essere NULL.

[in] OutputBufferLength

Dimensioni, in byte, del buffer in corrispondenza di OutputBuffer. Questo valore viene ignorato se OutputBuffer è NULL.

Valore restituito

ZwFsControlFile restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Osservazioni

ZwFsControlFile fornisce una visualizzazione coerente dei dati di input e output al sistema e ai driver in modalità kernel, fornendo applicazioni e driver sottostanti con un metodo dipendente dal driver per specificare un'interfaccia di comunicazione.

Se il chiamante ha aperto il file per operazioni di I/O asincrone (con nessuno dei due FILE_SYNCHRONOUS_XXX set di opzioni create/open), l'evento specificato, se presente, verrà impostato sullo stato segnalato al termine dell'operazione di controllo del dispositivo. In caso contrario, l'oggetto file specificato da FileHandle verrà impostato sullo stato segnalato. Se è stato specificato un ApcRoutine , viene chiamato con i puntatori ApcContext e IoStatusBlock.

I codici FSCTL seguenti sono attualmente documentati per i driver in modalità 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

Per altre informazioni sui codici FSCTL_definiti dal sistema, vedere la sezione "Osservazioni" della voce di riferimento per DeviceIoControl nella documentazione di Microsoft Windows SDK.

Per altre informazioni sui codici di IOCTL_definiti dal sistema e sulla definizione di XXX IOCTL_ o FSCTL_XXX valori, vedere Using I/O Control Codes (Uso di codici di controllo I/O) nella Guida all'architettura della modalità kernel e codici di controllo di input e output del dispositivo nella documentazione di Windows SDK.

I minifiltri devono usare FltFsControlFile anziché ZwFsControlFile.

I chiamanti di ZwFsControlFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.

Nota Se la chiamata alla funzione ZwFsControlFile si verifica in modalità utente, è consigliabile usare il nome "NtFsControlFile" anziché "ZwFsControlFile".

Per le chiamate dai driver in modalità kernel, le versioni **Nt*Xxx** e **Zw*Xxx** di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per ulteriori informazioni sulla relazione tra le versioni **Nt*Xxx** e **Zw*Xxx** di una routine, vedere [Using Nt and Zw Versions of the Native System Services Routines](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000.
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)