Fonction SetFileInformationByHandle (fileapi.h)

Article
08/23/2023

Définit les informations relatives au fichier spécifié.

Pour récupérer des informations de fichier à l’aide d’un handle de fichier, consultez GetFileInformationByHandle Ou GetFileInformationByHandleEx.

Syntaxe

BOOL SetFileInformationByHandle(
  [in] HANDLE                    hFile,
  [in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
  [in] LPVOID                    lpFileInformation,
  [in] DWORD                     dwBufferSize
);

Paramètres

[in] hFile

Handle du fichier pour lequel modifier les informations.

Ce handle doit être ouvert avec les autorisations appropriées pour la modification demandée. Pour plus d’informations, consultez les sections Remarques et Exemple de code.

Ce handle ne doit pas être un handle de canal.

[in] FileInformationClass

Valeur d’énumération FILE_INFO_BY_HANDLE_CLASS qui spécifie le type d’informations à modifier.

Pour obtenir une table de valeurs valides, consultez la section Remarques.

[in] lpFileInformation

Pointeur vers la mémoire tampon qui contient les informations à modifier pour la classe d’informations de fichier spécifiée. La structure vers laquelle pointe ce paramètre correspond à la classe spécifiée par FileInformationClass.

Pour obtenir une table des types de structure valides, consultez la section Remarques.

[in] dwBufferSize

Taille de lpFileInformation, en octets.

Valeur retournée

Retourne une valeur différente de zéro en cas de réussite ou de zéro dans le cas contraire.

Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Certaines classes d’informations sur les fichiers se comportent légèrement différemment selon les versions de système d’exploitation. Ces classes sont prises en charge par les pilotes sous-jacents, et toutes les informations qu’elles retournent peuvent être modifiées entre les versions du système d’exploitation.

Le tableau suivant montre les classes d’informations de fichier valides et leurs types de structure de données correspondants à utiliser avec cette fonction.

Valeur FileInformationClass	type lpFileInformation
FileBasicInfo 0	FILE_BASIC_INFO
FileRenameInfo 3	FILE_RENAME_INFO
FileDispositionInfo 4	FILE_DISPOSITION_INFO
FileAllocationInfo 5	FILE_ALLOCATION_INFO
FileEndOfFileInfo 6	FILE_END_OF_FILE_INFO
FileIoPriorityHintInfo 12	FILE_IO_PRIORITY_HINT_INFO

Vous devez spécifier les indicateurs d’accès appropriés lors de la création du handle de fichier à utiliser avec SetFileInformationByHandle. Par exemple, si l’application utilise FILE_DISPOSITION_INFO avec le membre DeleteFile défini sur TRUE, le fichier a besoin de l’accès DELETE demandé dans l’appel à la fonction CreateFile . Pour en voir un exemple, consultez la section Exemple de code. Pour plus d’informations sur les autorisations de fichier, consultez Sécurité des fichiers et droits d’accès.

S’il existe une transaction liée au descripteur, les modifications apportées sont traitées pour les classes d’informations FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo et FileDispositionInfo. Si FileDispositionInfo est spécifié, seule l’opération de suppression est traitée si une opération DeleteFile a été demandée. Dans ce cas, si la transaction n’est pas validée avant la fermeture du handle, la suppression ne se produit pas. Pour plus d’informations sur TxF, consultez Transactional NTFS (TxF).

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Voir le commentaire
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Voir le commentaire
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

SMB 3.0 ne prend pas en charge le renommage d’autres flux de données sur les partages de fichiers avec une fonctionnalité de disponibilité continue.

Exemples

L’exemple C++ suivant montre comment créer un fichier et le marquer pour suppression lorsque le handle est fermé.

//...
  HANDLE hFile = CreateFile( TEXT("tempfile"), 
                             GENERIC_READ | GENERIC_WRITE | DELETE,
                             0 /* exclusive access */,
                             NULL, 
                             CREATE_ALWAYS,
                             0, 
                             NULL);

  if (hFile != INVALID_HANDLE_VALUE)
   {
    FILE_DISPOSITION_INFO fdi;
    fdi.DeleteFile = TRUE; // marking for deletion

    BOOL fResult = SetFileInformationByHandle( hFile, 
                                               FileDispositionInfo, 
                                               &fdi, 
                                               sizeof(FILE_DISPOSITION_INFO) );

    if (fResult)
     {
      // File will be deleted upon CloseHandle.
      _tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );

      // ... 
      // Now use the file for whatever temp data storage you need,
      // it will automatically be deleted upon CloseHandle or 
      // application termination.
      // ...
     }
    else
     {
      _tprintf( TEXT("error %lu:  SetFileInformationByHandle could not mark tempfile for deletion\n"), 
                GetLastError() );
     }

    CloseHandle(hFile); 

    // At this point, the file is closed and deleted by the system.
   }
  else 
   {
    _tprintf( TEXT("error %lu:  could not create tempfile\n"), 
              GetLastError() );
 }
//...

Spécifications


Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	fileapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib; FileExtd.lib sur Windows Server 2003 et Windows XP
DLL	Kernel32.dll
Composant redistribuable	Kit de développement logiciel (SDK) Windows sur Windows Server 2003 et Windows XP.