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 asincrono se il chiamante specifica un oggetto Event, ApcRoutine e 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 specificato, 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 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 utilizzato come contesto APC se il chiamante fornisce un APC o viene utilizzato come contesto di completamento se un oggetto di completamento di I/O è stato associato all'oggetto file. Al termine dell'operazione, il contesto APC viene passato all'APC, se ne è stato specificato uno o il contesto di completamento viene incluso come parte del messaggio di completamento che il gestore di I/O invia all'oggetto di completamento I/O associato.

Questo parametro è facoltativo e può essere NULL. Deve essere NULL se ApcRoutine è NULL e non è presente 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 in OutputBuffer viene restituito nel membro Informazioni di questa struttura.

[in] FsControlCode

FSCTL_ codiceXXX che indica l'operazione di controllo del file system da eseguire. Il valore di questo parametro determina i formati e le lunghezze necessarie di 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.

[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 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 OutputBuffer. Questo valore viene ignorato se OutputBuffer è NULL.

Valore restituito

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

Commenti

NtFsControlFile offre una visualizzazione coerente dei dati di input e output nel sistema e nei 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 l'I/O asincrono (con nessuno dei due set di opzioni create/open FILE_SYNCHRONOUS_XXX ), 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 oggetto ApcRoutine , viene chiamato con i puntatori ApcContext e IoStatusBlock .

Di seguito sono riportati alcuni dei codici ODBCTL 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_XXX definiti dal sistema, vedere la sezione "Osservazioni" della voce di riferimento per DeviceIoControl.

Per altre informazioni sui codici IOCTL_XXX definiti dal sistema e sulla definizione di valori di IOCTL_XXX o FSCTL_XXX specifici del driver, vedere Uso di codici di controllo di I/Oe codici di controllo di input del dispositivo e di output.

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, è consigliabile usare il nome "NtFsControlFile" anziché "ZwFsControlFile".

Per le chiamate dai driver in modalità kernel, le versioni NtXXX e ZwXXX 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 altre informazioni sulla relazione tra le versioni NtXXX e ZwXXX di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.For more information about the Nt XXX and Zw versions of the Native System Services Routines.

Requisiti

Vedi anche

FltFsControlFile

IRP_MJ_FILE_SYSTEM_CONTROL

IoGetFunctionCodeFromCtlCode

IoIsOperationSynchronous

ZwClose

ZwCreateFile

ZwDeviceIoControlFile

ZwOpenFile