Funzione NtFsControlFile (ntifs.h)

La routine NtFsControlFile invia un codice di controllo direttamente 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

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [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 NtCreateFile o NtOpenFile 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 sia 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 all'oggetto file è associato un oggetto di completamento I/O.

[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 non esiste alcun oggetto di completamento I/O associato all'oggetto file.

[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 di FSCTL_XXX definiti dal sistema, vedere la sezione "Osservazioni" della voce di riferimento per DeviceIoControl.

[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

NtFsControlFile restituisce STATUS_SUCCESS se l'operazione di controllo è stata accodata correttamente al sistema di I/O. Al termine dell'operazione, lo stato effettivo può essere determinato esaminando il campo Stato di IoStatusBlock.

La routine può anche restituire vari valori di stato degli errori, tra cui, a titolo esemplificativo:

• STATUS_ACCESS_DENIED se il chiamante non dispone dei diritti di accesso necessari per FsControlCode o se le chiamate al servizio di sistema NtFsControlFile sono bloccate dai criteri di mitigazione dei processi
• STATUS_INVALID_PARAMETER se viene specificata una combinazione di parametri non valida(ad esempio, specificando un oggetto ApcRoutine quando è associata una porta di completamento I/O all'oggetto file)
• STATUS_INSUFFICIENT_RESOURCES se memoria insufficiente è disponibile per allocare buffer o MDL
• STATUS_PENDING se il parametro Asincrono è TRUE e l'operazione non è ancora stata completata

Per le operazioni asincrone, se Asincrona è TRUE e l'evento non si è ancora verificato, la routine restituisce STATUS_PENDING.

Osservazioni

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

Di seguito sono riportati alcuni dei codici FSCTL 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" di DeviceIoControl, che viene in genere usata dalle applicazioni in modalità utente.

Per altre informazioni sui codici di IOCTL_definiti dal sistema e sulla definizione di valori IOCTL_ xxx specifici del driver o FSCTL_XXX, vedere Using I/O Control Codes and Device Input and Output Control Codes.

I minifiltri devono usare FltFsControlFile anziché NtFsControlFile.

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

Se la chiamata alla funzione NtFsControlFile viene eseguita in modalità utente, è necessario usare il nome "NtFsControlFile" anziché "ZwFsControlFile".

Per le chiamate da driver in modalità kernel, il NtXXX e ZwXXX versioni di una routine di Servizi di sistema nativi di Windows può comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra NtXXX e ZwXXX versioni di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

Vedere anche

FltFsControlFile

IRP_MJ_FILE_SYSTEM_CONTROL

IoGetFunctionCodeFromCtlCode

IoIsOperationSynchronous

ZwClose

ZwCreateFile

ZwDeviceIoControlFile

ZwOpenFile