Funzione NtWriteFile (ntifs.h)
La routine ZwWriteFile scrive i dati in un file aperto.
Sintassi
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parametri
[in] FileHandle
Handle per l'oggetto file. Questo handle viene creato da una chiamata riuscita a NtCreateFile o NtOpenFile.
[in, optional] Event
Facoltativamente, un handle per un oggetto evento da impostare sullo stato segnalato al termine dell'operazione di scrittura. I driver intermedi e del dispositivo devono impostare questo parametro su NULL.
[in, optional] ApcRoutine
Questo parametro è riservato. I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
[in, optional] ApcContext
Questo parametro è riservato. I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
[out] IoStatusBlock
Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione di scrittura richiesta. Il membro information riceve il numero di byte effettivamente scritti nel file.
[in] Buffer
Puntatore a un buffer allocato dal chiamante che contiene i dati da scrivere nel file.
[in] Length
Dimensione, in byte, del buffer a cui punta Buffer.
[in, optional] ByteOffset
Puntatore a una variabile che specifica l'offset di byte iniziale nel file per l'inizio dell'operazione di scrittura. Se lunghezza e ByteOffset specificare un'operazione di scrittura oltre la fine del file corrente, NtWriteFile estende automaticamente il file e aggiorna il contrassegno di fine file; tutti i byte non scritti in modo esplicito tra tali contrassegni di fine file precedenti e nuovi vengono definiti come zero.
Se la chiamata a NtCreateFile impostare solo il flag desiredAccess FILE_APPEND_DATA, ByteOffset viene ignorato. I dati nel buffer specificato, per lunghezza byte, viene scritto a partire dalla fine corrente del file.
Se la chiamata a NtCreateFile impostata uno dei flag CreateOptions, FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, gestione I/O mantiene la posizione corrente del file. In tal caso, il chiamante di NtWriteFile può specificare che venga utilizzato l'offset di posizione del file corrente anziché un ByteOffset esplicito valore. Questa specifica può essere effettuata utilizzando uno dei metodi seguenti:
- *Specificare un puntatore a un valore di LARGE_INTEGER con il membro HighPart impostato su -1 e il membro LowPart impostato sul valore definito dal sistema FILE_USE_FILE_POINTER_POSITION.
- Passare un puntatore NULL per ByteOffset.
NtWriteFile aggiorna la posizione corrente del file aggiungendo il numero di byte scritti al termine dell'operazione di scrittura, se usa la posizione corrente del file gestita da I/O Manager.
Anche quando gestione I/O mantiene la posizione corrente del file, il chiamante può reimpostare questa posizione passando un valore ByteOff set esplicito a NtWriteFile. In questo modo la posizione corrente del file viene modificata automaticamente in tale valore ByteOffset, esegue l'operazione di scrittura e quindi aggiorna la posizione in base al numero di byte effettivamente scritti. Questa tecnica fornisce al chiamante il servizio atomic seek-and-write.
È anche possibile che un'operazione di scrittura venga avviata alla fine corrente del file specificando per ByteOffset un puntatore a un valore LARGE_INTEGER con HighPart impostato su -1 e LowPart impostato su FILE_WRITE_TO_END_OF_FILE. Questa operazione funziona indipendentemente dal fatto che gestione I/O mantenga la posizione corrente del file.
[in, optional] Key
I driver intermedi e del dispositivo devono impostare questo puntatore su NULL.
Valore restituito
ntWriteFile restituisce STATUS_SUCCESS in caso di esito positivo o il codice di errore NTSTATUS appropriato in caso di errore.
Osservazioni
I chiamanti di NtWriteFile devono aver già chiamato NtCreateFile con il flag FILE_WRITE_DATA, FILE_APPEND_DATA o GENERIC_WRITE impostato nel parametro DesiredAccess. Si noti che l'accesso solo FILE_APPEND_DATA a un file non consente al chiamante di scrivere in qualsiasi punto del file tranne che alla fine corrente del file, pur avendo FILE_WRITE_DATA accesso a un file non impedisce al chiamante di scrivere o oltre la fine di un file.
Se la chiamata precedente a NtCreateFile impostare il flag FILE_NO_INTERMEDIATE_BUFFERING CreateOptions, i parametri Length e ByteOffset su NtWriteFile devono essere integrali delle dimensioni del settore. Per altre informazioni, vedere NtCreateFile.
NtWriteFile avvia l'operazione di scrittura nel file ByteOffset, nella posizione del file corrente o alla fine del file. Termina l'operazione di scrittura quando è stata scritta lunghezza byte da Buffer. Se necessario, estende la lunghezza del file e reimposta il contrassegno di fine del file.
Se il chiamante ha aperto il file con il flag DesiredAccess SYNCHRONIZE impostato, il chiamante può attendere che questa routine imposti il FileHandle specificato sullo stato segnalato.
I driver devono chiamare NtWriteFile nel contesto del processo di sistema in tre casi:
- Il driver crea l'handle di file passato a NtWriteFile.
- NtWriteFile notifica al driver di completamento di I/O tramite un evento creato dal driver.
- NtWriteFile notifica al driver di completamento di I/O tramite una routine di callback APC che il driver passa a NtWriteFile.
Gli handle di file ed eventi sono validi solo nel contesto del processo in cui vengono creati gli handle. Pertanto, per evitare problemi di sicurezza, il driver deve creare qualsiasi handle di file o evento passato a NtWriteFile nel contesto del processo di sistema invece del contesto di processo in cui si trova il driver.
Analogamente, NtWriteFile deve essere chiamato nel contesto del processo di sistema se notifica al driver di completamento di I/O tramite un APC, perché le API vengono sempre attivate nel contesto del thread che emette la richiesta di I/O. Se il driver chiama NtWriteFile nel contesto di un processo diverso dal processo di sistema, l'APC potrebbe essere ritardato a tempo indeterminato oppure potrebbe non essere attivato perché il thread di origine potrebbe non entrare mai in uno stato di attesa avvisabile.
Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.
I chiamanti di NtWriteFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.
Se la chiamata a questa funzione si verifica in modalità utente, è necessario usare il nome "NtWriteFile" anziché "ZwWriteFile".
Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di Windows Native System Services 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.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 2000 |
| piattaforma di destinazione | Universale |
| intestazione | ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (vedere la sezione Osservazioni) |
| regole di conformità DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |