Funzione ZwSetInformationFile (wdm.h)

Articolo
11/07/2024

La routine ZwSetInformationFile modifica vari tipi di informazioni su un oggetto file.

Sintassi

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parametri

[in] FileHandle

Handle per l'oggetto file. Questo handle viene creato da una chiamata riuscita a ZwCreateFile o ZwOpenFile.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione richiesta. Il membro Information riceve il numero di byte impostati nel file.

[in] FileInformation

Puntatore a un buffer contenente le informazioni da impostare per il file. La struttura specifica in questo buffer è determinata dal parametro FileInformationClass. Ad esempio, se il parametro FileInformationClass è impostato sulla costante FileDispositionInformationEx, questo parametro deve essere un puntatore a una struttura FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Dimensioni, in byte, del buffer FileInformation.

[in] FileInformationClass

Tipo di informazioni, fornito nel buffer a cui punta FileInformation, da impostare per il file. I driver intermedi e del dispositivo possono specificare uno dei valori di FILE_INFORMATION_CLASS seguenti.

valore FileInformationClass	Significato
FileBasicInformation	Modificare le informazioni fornite in una struttura FILE_BASIC_INFORMATION. Il chiamante deve aver aperto il file con il flag FILE_WRITE_ATTRIBUTES impostato nel parametro DesiredAccess .
FileDispositionInformation	Richiedere di eliminare il file quando viene chiuso o annullare un'eliminazione richiesta in precedenza. La scelta se eliminare o annullare viene fornita in una struttura di FILE_DISPOSITION_INFORMATION. Il chiamante deve aver aperto il file con il flag DELETE impostato nel parametro DesiredAccess.
FileDispositionInformationEx	Richiedere di eliminare il file o annullare un'eliminazione richiesta in precedenza. La scelta se eliminare o annullare, nonché le impostazioni per quando e come deve essere eseguita l'eliminazione, vengono fornite in una struttura FILE_DISPOSITION_INFORMATION_EX. Il chiamante deve aver aperto il file con il flag DELETE** impostato nel parametro DesiredAccess .
FileEndOfFileInformation	Modificare le informazioni di fine file correnti, fornite in una struttura FILE_END_OF_FILE_INFORMATION. L'operazione può troncare o estendere il file. Il chiamante deve aver aperto il file con il flag di FILE_WRITE_DATA impostato nel parametro DesiredAccess .
FileIoPriorityHintInformation	Modificare l'hint di priorità IRP predefinito corrente per l'handle di file. Il nuovo valore viene fornito in una struttura FILE_IO_PRIORITY_HINT_INFORMATION. Questa struttura deve essere allineata a 8 byte.
FileLinkInformation	Creare un collegamento rigido a un file esistente, specificato in una struttura FILE_LINK_INFORMATION. Non tutti i file system supportano collegamenti rigidi; ad esempio NTFS fa mentre FAT non lo fa.
FilePositionInformation	Modificare le informazioni sul file corrente, archiviate in una struttura FILE_POSITION_INFORMATION.
FileRenameInformation	Modificare il nome del file corrente, fornito in una struttura FILE_RENAME_INFORMATION. Il chiamante deve avere accesso DELETE al file.
FileShortNameInformation	Modificare il nome di file breve corrente, fornito in una struttura FILE_NAME_INFORMATION. Il file deve trovarsi in un volume NTFS e il chiamante deve aver aperto il file con il flag DesiredAccess DELETE impostato nel parametro DesiredAccess.
FileIoCompletionNotificationInformation	Modificare i flag di notifica di completamento I/O del file. Supporta gli stessi flag di SetFileCompletionNotificationModes.
FileValidDataLengthInformation	Modificare la lunghezza dei dati valida corrente per il file, fornito in una struttura FILE_VALID_DATA_LENGTH_INFORMATION. Il file deve trovarsi in un volume NTFS e il chiamante deve aver aperto il file con il flag FILE_WRITE_DATA impostato nel parametro DesiredAccess. Gli utenti non amministratori e remoti devono avere il privilegio SeManageVolumePrivilege.
FileReplaceCompletionInformation	Modificare o rimuovere la porta di completamento I/O per l'handle di file specificato. Il chiamante fornisce un puntatore a una struttura FILE_COMPLETION_INFORMATION che specifica un handle di porta e una chiave di completamento. Se l'handle di porta non è NULL, questo handle specifica una nuova porta di completamento I/O da associare all'handle di file. Per rimuovere la porta di completamento I/O associata all'handle di file, impostare l'handle di porta nella struttura su NULL. Per ottenere un handle di porta, un chiamante in modalità utente può chiamare la funzione CreateIoCompletionPort .

Valore restituito

ZwSetInformationFile restituisce STATUS_SUCCESS o uno stato di errore appropriato.

Osservazioni

ZwSetInformationFile modifica le informazioni su un file. Ignora qualsiasi membro di una struttura_INFORMATION FILE_XXX non supportata da un particolare dispositivo o file system.

Se imposti FileInformationClass su FileDispositionInformation, puoi successivamente passare FileHandle a ZwClose ma non ad altre routine ZwXxxFile. Poiché FileDispositionInformation fa sì che il file venga contrassegnato per l'eliminazione, si tratta di un errore di programmazione per tentare qualsiasi operazione successiva sull'handle diverso da chiuderlo.

Se imposti FileInformationClass su FilePositionInformatione la chiamata precedente a ZwCreateFile incluso il flag FILE_NO_INTERMEDIATE_BUFFERING nel parametro CreateOptions , vengono applicate alcune restrizioni sul membro CurrentByteOffset della struttura FILE_POSITION_INFORMATION. Per altre informazioni, vedere ZwCreateFile.

Se imposti FileInformationClass su FileEndOfFileInformatione il membro EndOfFile di FILE_END_OF_FILE_INFORMATION specifica un offset oltre la fine del file corrente, ZwSetInformationFile estende il file e riempie l'estensione con zeri.

Per altre informazioni sull'uso dei file, vedere Uso di file in un driver.

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

Se la chiamata a questa funzione viene eseguita in modalità utente, è necessario usare il nome "NtSetInformationFile" anziché "ZwSetInformationFile".

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
piattaforma di destinazione	Universale
intestazione	wdm.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(storport), PowerIrpDDis(wdm)