SetFileAttributesTransactedA, fonction (winbase.h)

Article
03/03/2024

[Microsoft recommande vivement aux développeurs d’utiliser d’autres moyens pour répondre aux besoins de votre application. De nombreux scénarios utilisant TxF peuvent être réalisés à l’aide de techniques plus simples et plus facilement disponibles. En outre, TxF peut ne pas être disponible dans les versions à venir de Microsoft Windows. Pour plus d’informations et les alternatives à TxF, consultez Alternatives à l’utilisation de Transactionnel NTFS.]

Définit les attributs d’un fichier ou d’un répertoire en tant qu’opération transactionnelle.

Syntaxe

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

Paramètres

[in] lpFileName

Nom du fichier dont les attributs doivent être définis.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

Le fichier doit résider sur l’ordinateur local ; sinon, la fonction échoue et le dernier code d’erreur est défini sur ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] dwFileAttributes

Attributs de fichier à définir pour le fichier.

Pour obtenir la liste des valeurs d’attribut de fichier et leurs descriptions, consultez Constantes d’attributs de fichier. Ce paramètre peut être une ou plusieurs valeurs, combinées à l’aide de l’opérateur or au niveau du bit. Toutefois, toutes les autres valeurs remplacent FILE_ATTRIBUTE_NORMAL.

Tous les attributs ne sont pas pris en charge par cette fonction. Pour plus d'informations, consultez la section Notes.

Voici une liste des valeurs d’attribut prises en charge.

FILE_ATTRIBUTE_ARCHIVE (32 (0x20))

FILE_ATTRIBUTE_HIDDEN (2 (0x2))

FILE_ATTRIBUTE_NORMAL (128 (0x80))

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (8192 (0x2000))

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000))

FILE_ATTRIBUTE_READONLY (1 (0x1))

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

[in] hTransaction

Handle de la transaction. Ce handle est retourné par la fonction CreateTransaction .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Le tableau suivant décrit comment définir les attributs qui ne peuvent pas être définis à l’aide de SetFileAttributesTransacted. Notez qu’il ne s’agit pas d’opérations traitées.

Attribut	Guide pratique pour définir
FILE_ATTRIBUTE_COMPRESSED 0x800	Pour définir l’état de compression d’un fichier, utilisez la fonction DeviceIoControl avec l’opération FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE 0x40	Réservé ; ne pas utiliser.
FILE_ATTRIBUTE_DIRECTORY 0x10	Les fichiers ne peuvent pas être convertis en répertoires. Pour créer un répertoire, utilisez la fonction CreateDirectory ou CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Pour créer un fichier chiffré, utilisez la fonction CreateFile avec l’attribut FILE_ATTRIBUTE_ENCRYPTED . Pour convertir un fichier existant en fichier chiffré, utilisez la fonction EncryptFile .
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Pour associer un point d’analyse à un fichier ou un répertoire, utilisez la fonction DeviceIoControl avec l’opération FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Pour définir l’attribut éparse d’un fichier, utilisez la fonction DeviceIoControl avec l’opération FSCTL_SET_SPARSE .

Si un fichier est ouvert pour modification dans une transaction, aucun autre thread ne peut ouvrir le fichier pour modification tant que la transaction n’est pas validée. Si un thread traité ouvre d’abord le fichier, tous les threads suivants qui tentent d’ouvrir le fichier pour modification avant la validation de la transaction reçoivent une violation de partage. Si un thread non traité ouvre le fichier pour modification avant que le thread traité ne le fasse, et qu’il est toujours ouvert lorsque le thread traité tente de l’ouvrir, la transaction reçoit l’erreur ERROR_TRANSACTIONAL_CONFLICT .

Pour plus d’informations sur les transactions, consultez NTFS transactionnel.

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	No
Basculement transparent SMB 3.0 (TFO)	No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	No
Système de fichiers du volume partagé de cluster (CsvFS)	No
Système de fichiers résilient (ReFS)	No

SMB 3.0 ne prend pas en charge TxF.

Opérations traitées

Si un fichier est ouvert pour modification dans une transaction, aucun autre thread ne peut ouvrir le fichier pour modification tant que la transaction n’est pas validée. Par conséquent, si un thread traité ouvre le fichier en premier, tous les threads suivants qui tentent de modifier le fichier avant la validation de la transaction reçoivent une violation de partage. Si un thread non traité modifie le fichier avant le thread traité et que le fichier est toujours ouvert lorsque la transaction tente de l’ouvrir, la transaction reçoit l’erreur ERROR_TRANSACTIONAL_CONFLICT.

Notes

L’en-tête winbase.h définit SetFileAttributesTransacted en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll