Fonction SetFileInformationByHandle (fileapi.h)

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

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.

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

Voir aussi

CreateFile

Fonctions de gestion des fichiers

Sécurité du fichier et droits d’accès

Droits d’accès génériques

GetFileInformationByHandle

GetFileInformationByHandleEx