Funzione ZwFsControlFile (ntifs.h)
La routine ZwFsControlFile invia un codice di controllo direttamente a un driver di filtro file system o file system specificato, causando l'esecuzione dell'azione specificata dal 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 eseguire l'azione specificata. L'oggetto file deve essere stato aperto per 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 fornito, il chiamante verrà inserito in uno stato di attesa fino al completamento dell'operazione richiesta e l'evento specificato viene impostato sullo stato Signaled. 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 è presente un oggetto di completamento di 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 di completamento di I/O è stato associato all'oggetto file. Al termine dell'operazione, il contesto APC viene passato all'APC, se è stato specificato o il contesto di completamento viene incluso come parte del messaggio di completamento che l'oggetto di completamento di I/O Manager esegue il post dell'oggetto di completamento I/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 in OutputBuffer viene restituito nel membro Information 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 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 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 fornire 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 vengono restituite informazioni 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
ZwFsControlFile restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:
Commenti
ZwFsControlFile offre 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 I/O asincrono (senza FILE_SYNCHRONOUS_XXX create/ open option set), 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 .
I codici FSCTL seguenti sono attualmente documentati per i driver in modalità kernel:
FSCTL_OPBATCH_ACK_CLOSE_PENDING
FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
Per altre informazioni sui codici FSCTL_XXX definiti dal sistema, vedere la sezione "Osservazioni" della voce di riferimento per DeviceIoControl nella documentazione di Microsoft Windows SDK.
Per altre informazioni sui codici IOCTL_XXX definiti dal sistema e sulla definizione di valori di IOCTL_XXX specifici del driver o di FSCTL_XXX, vedere Uso di codici di controllo I/O nella Guida all'architettura in modalità kernele codici di controllo di input del dispositivo e di output nella documentazione di Windows SDK.
I minifilter devono usare FltFsControlFile anziché ZwFsControlFile.
I chiamanti di ZwFsControlFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.
Requisiti
| 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) |
Vedi anche
Uso dei codici di controllo I/O
Uso di nt e zw versioni delle routine di Servizi di sistema nativo