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 dei byte iniziale nel file per l'inizio dell'operazione di scrittura. Se Length e ByteOffset specificano un'operazione di scrittura oltre il contrassegno di fine file corrente, NtWriteFile estende automaticamente il file e aggiorna il contrassegno di fine file; tutti i byte che non vengono scritti in modo esplicito tra tali contrassegni precedenti e nuovi contrassegni di fine file sono definiti come zero.

Se la chiamata a NtCreateFile imposta solo il flag DesiredAccess FILE_APPEND_DATA, ByteOffset viene ignorato. I dati nel buffer specificato, per byte di lunghezza , sono scritti a partire dalla fine corrente del file.

Se la chiamata a NtCreateFile imposta uno dei flag CreateOptions , FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, gestione I/O mantiene la posizione del file corrente. In tal caso, il chiamante di NtWriteFile può specificare che l'offset della posizione del file corrente deve essere usato anziché un valore ByteOffset esplicito. Questa specifica può essere effettuata utilizzando uno dei metodi seguenti:

• *Specificare un puntatore a un valore 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 del file corrente 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 del file corrente, il chiamante può reimpostare questa posizione passando un valore ByteOffset 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 inizi 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. Ciò 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.

Commenti

I chiamanti di NtWriteFile devono avere già chiamato NtCreateFile con il flag FILE_WRITE_DATA, FILE_APPEND_DATA o GENERIC_WRITE impostato nel parametro DesiredAccess . Si noti che la presenza di solo FILE_APPEND_DATA accesso a un file non consente al chiamante di scrivere in qualsiasi punto del file, ad eccezione del contrassegno di fine file corrente, 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 imposta il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING, i parametri Length e ByteOffset su NtWriteFile devono essere parte integrante delle dimensioni del settore. Per altre informazioni, vedere NtCreateFile.

NtWriteFile avvia l'operazione di scrittura nel file in ByteOffset, nella posizione corrente del file o alla fine del file. Termina l'operazione di scrittura quando contiene byte di lunghezza scritti da Buffer. Se necessario, estende la lunghezza del file e reimposta il contrassegno di fine file.

Se il chiamante ha aperto il file con il flag DesiredAccess SYNCHRONIZE impostato, il chiamante può attendere che questa routine imposti lo stato 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 che passa a NtWriteFile.
• NtWriteFile notifica al driver il completamento di I/O tramite un evento creato dal driver.
• NtWriteFile notifica al driver il 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 eventi che passa a NtWriteFile nel contesto del processo di sistema invece del contesto del processo in cui si trova il driver.

Allo stesso modo, NtWriteFile deve essere chiamato nel contesto del processo di sistema se notifica al driver di completamento di I/O tramite un APC, perché le APC 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 per un tempo illimitato oppure potrebbe non essere attivato affatto perché il thread di origine potrebbe non entrare mai in uno stato di attesa di avviso.

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

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile