CreateFileTransactedA, fonction (winbase.h)

[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.]

Crée ou ouvre un fichier, un flux de fichiers ou un répertoire en tant qu’opération transactionnelle. La fonction retourne un handle qui peut être utilisé pour accéder à l’objet.

Pour effectuer cette opération en tant qu’opération non exécutée ou pour accéder à des objets autres que des fichiers (par exemple, des canaux nommés, des appareils physiques, des mailslots), utilisez la fonction CreateFile .

Pour plus d’informations sur les transactions, consultez la section Remarques de cette rubrique.

Syntaxe

HANDLE CreateFileTransactedA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile,
  [in]           HANDLE                hTransaction,
  [in, optional] PUSHORT               pusMiniVersion,
                 PVOID                 lpExtendedParameter
);

Paramètres

[in] lpFileName

Nom d’un objet à créer ou à ouvrir.

L’objet 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.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, 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 MAX_PATH sans précédencer « \\ ?\ ». Pour plus d’informations, consultez la section « Limitation maximale de la longueur du chemin d’accès » de Naming Files, Paths et Namespaces .

Pour créer un flux de fichiers, spécifiez le nom du fichier, un signe deux-points, puis le nom du flux. Pour plus d’informations, consultez Flux de fichiers.

[in] dwDesiredAccess

Accès à l’objet, qui peut être résumé en lecture, écriture, les deux ou aucun (zéro). Les valeurs les plus couramment utilisées sont GENERIC_READ, GENERIC_WRITE ou les deux (GENERIC_READ | GENERIC_WRITE). Pour plus d’informations, consultez Droits d’accès génériques et Sécurité des fichiers et droits d’accès.

Si ce paramètre est égal à zéro, l’application peut interroger des attributs de fichier, de répertoire ou d’appareil sans accéder à ce fichier ou à cet appareil. Pour plus d’informations, consultez la section Remarques de cette rubrique.

Vous ne pouvez pas demander un mode d’accès qui entre en conflit avec le mode de partage spécifié dans une demande ouverte qui a un handle ouvert. Pour plus d’informations, consultez Création et ouverture de fichiers.

[in] dwShareMode

Mode de partage d’un objet, qui peut être lu, écrit, à la fois, supprimé, tous ces éléments ou aucun (reportez-vous au tableau suivant).

Si ce paramètre a la valeur zéro et que CreateFileTransacted réussit, l’objet ne peut pas être partagé et ne peut pas être rouvert tant que le handle n’est pas fermé. Pour plus d’informations, consultez la section Remarques de cette rubrique.

Vous ne pouvez pas demander un mode de partage qui entre en conflit avec le mode d’accès spécifié dans une demande ouverte qui a un handle ouvert, car cela entraînerait la violation de partage suivante : ERROR_SHARING_VIOLATION. Pour plus d’informations, consultez Création et ouverture de fichiers.

Pour permettre à un processus de partager un objet alors qu’un autre processus a l’objet ouvert, utilisez une combinaison d’une ou plusieurs des valeurs suivantes pour spécifier le mode d’accès qu’ils peuvent demander pour ouvrir l’objet.

Note Les options de partage pour chaque handle ouvert restent en vigueur jusqu’à ce que ce handle soit fermé, quel que soit le contexte du processus.
 
Valeur Signification
0
0x00000000
Désactive les opérations d’ouverture suivantes sur un objet pour demander n’importe quel type d’accès à cet objet.
FILE_SHARE_DELETE
0x00000004
Active les opérations d’ouverture suivantes sur un objet pour demander l’accès à la suppression.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès de suppression.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès de suppression, la fonction échoue.

FILE_SHARE_READ
0x00000001
Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en lecture.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en lecture.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en lecture, la fonction échoue.

FILE_SHARE_WRITE
0x00000002
Active les opérations d’ouverture suivantes sur un objet pour demander l’accès en écriture.

Sinon, d’autres processus ne peuvent pas ouvrir l’objet s’ils demandent un accès en écriture.

Si cet indicateur n’est pas spécifié, mais que l’objet a été ouvert pour l’accès en écriture ou a un mappage de fichiers avec accès en écriture, la fonction échoue.

[in, optional] lpSecurityAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui contient un descripteur de sécurité facultatif et détermine également si le handle retourné peut ou non être hérité par des processus enfants. Le paramètre peut être NULL.

Si le paramètre lpSecurityAttributes a la valeur NULL, le handle retourné par CreateFileTransacted ne peut pas être hérité par les processus enfants que votre application peut créer et l’objet associé au handle retourné obtient un descripteur de sécurité par défaut.

Le membre bInheritHandle de la structure spécifie si le handle retourné peut être hérité.

Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour un objet, mais peut également être NULL.

Si le membre lpSecurityDescriptor a la valeur NULL, un descripteur de sécurité par défaut est attribué à l’objet associé au handle retourné.

CreateFileTransacted ignore le membre lpSecurityDescriptor lors de l’ouverture d’un fichier existant, mais continue d’utiliser le membre bInheritHandle .

Pour plus d’informations, consultez la section Remarques de cette rubrique.

[in] dwCreationDisposition

Action à entreprendre sur les fichiers qui existent et qui n’existent pas.

Pour plus d’informations, consultez la section Remarques de cette rubrique.

Ce paramètre doit être l’une des valeurs suivantes, qui ne peuvent pas être combinées.

Valeur Signification
CREATE_ALWAYS
2
Crée un fichier, toujours.

Si le fichier spécifié existe et est accessible en écriture, la fonction tronque le fichier, la fonction réussit et le code de la dernière erreur est défini sur ERROR_ALREADY_EXISTS (183).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide, un nouveau fichier est créé, la fonction réussit et le code de la dernière erreur est défini sur zéro.

Pour plus d’informations, consultez la section Remarques de cette rubrique.

CREATE_NEW
1
Crée un fichier, uniquement s’il n’existe pas déjà.

Si le fichier spécifié existe, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_EXISTS (80).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide à un emplacement accessible en écriture, un nouveau fichier est créé.

OPEN_ALWAYS
4
Ouvre toujours un fichier.

Si le fichier spécifié existe, la fonction réussit et le code de dernière erreur est défini sur ERROR_ALREADY_EXISTS (183).

Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide à un emplacement accessible en écriture, la fonction crée un fichier et le code de dernière erreur est défini sur zéro.

OPEN_EXISTING
3
Ouvre un fichier ou un appareil, uniquement s’il existe.

Si le fichier spécifié n’existe pas, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_NOT_FOUND (2).

Pour plus d’informations, consultez la section Remarques de cette rubrique.

TRUNCATE_EXISTING
5
Ouvre un fichier et le tronque de sorte que sa taille soit égale à zéro octet, uniquement s’il existe.

Si le fichier spécifié n’existe pas, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_NOT_FOUND (2).

Le processus appelant doit ouvrir le fichier avec le GENERIC_WRITE bit défini dans le cadre du paramètre dwDesiredAccess .

[in] dwFlagsAndAttributes

Attributs et indicateurs de fichier, FILE_ATTRIBUTE_NORMAL étant la valeur par défaut la plus courante.

Ce paramètre peut inclure n’importe quelle combinaison des attributs de fichier disponibles (FILE_ATTRIBUTE_*). Tous les autres attributs de fichier remplacent FILE_ATTRIBUTE_NORMAL.

Ce paramètre peut également contenir des combinaisons d’indicateurs (FILE_FLAG_) pour contrôler le comportement de mise en mémoire tampon, les modes d’accès et d’autres indicateurs à usage spécial. Ils se combinent avec n’importe quelle valeur FILE_ATTRIBUTE_ .

Ce paramètre peut également contenir des informations SQOS (Security Quality of Service) en spécifiant l’indicateur SECURITY_SQOS_PRESENT . Des informations supplémentaires sur les indicateurs liés à SQOS sont présentées dans le tableau suivant les tables d’attributs et d’indicateurs.

Remarque  

Lorsque CreateFileTransacted ouvre un fichier existant, il combine généralement les indicateurs de fichier avec les attributs de fichier du fichier existant et ignore tous les attributs de fichier fournis dans le cadre de dwFlagsAndAttributes. Les cas spéciaux sont détaillés dans Création et ouverture de fichiers.

 
Les attributs et indicateurs de fichier suivants sont utilisés uniquement pour les objets fichier, et non pour les autres types d’objets que CreateFileTransacted ouvre (vous trouverez des informations supplémentaires dans la section Remarques de cette rubrique). Pour un accès plus avancé aux attributs de fichier, consultez SetFileAttributes. Pour obtenir la liste complète de tous les attributs de fichier avec leurs valeurs et descriptions, consultez Constantes des attributs de fichier.
Attribut Signification
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
Le fichier doit être archivé. Les applications utilisent cet attribut pour marquer des fichiers à des fins de sauvegarde ou de suppression.
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
Le fichier ou le répertoire est chiffré. Cela signifie pour un fichier, que toutes ses données sont chiffrées. Pour un répertoire, cela signifie que le chiffrement est la valeur par défaut pour les fichiers et sous-répertoires nouvellement créés. Pour plus d’informations, consultez Chiffrement de fichier.

Cet indicateur n’a aucun effet si FILE_ATTRIBUTE_SYSTEM est également spécifié.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
Le fichier est masqué. Ne l’incluez pas dans une liste d’annuaires ordinaire.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
Le fichier n’a pas d’autres attributs définis. Cet attribut n’est valide que s’il est utilisé seul.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
Les données d’un fichier ne sont pas immédiatement disponibles. Cet attribut indique que les données de fichier sont physiquement déplacées vers le stockage hors connexion. Cet attribut est utilisé par le stockage à distance, le logiciel de gestion du stockage hiérarchique. Les applications ne doivent pas modifier arbitrairement cet attribut.
FILE_ATTRIBUTE_READONLY
1 (0x1)
Le fichier est en lecture seule. Les applications peuvent lire le fichier, mais ne peuvent pas l’écrire ou le supprimer.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
Le fichier fait partie ou est utilisé exclusivement par un système d’exploitation.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
Le fichier est utilisé pour le stockage temporaire. Les systèmes de fichiers évitent d’écrire des données dans le stockage de masse si suffisamment de mémoire cache est disponible, car une application supprime un fichier temporaire après la fermeture d’un handle. Dans ce cas, le système peut complètement éviter d’écrire les données. Sinon, les données sont écrites après la fermeture du descripteur.
 
Indicateur Signification
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Le fichier est en cours d’ouverture ou de création pour une opération de sauvegarde ou de restauration. Le système garantit que le processus appelant remplace les vérifications de sécurité des fichiers lorsque le processus dispose de privilèges SE_BACKUP_NAME et SE_RESTORE_NAME . Pour plus d’informations, consultez Modification des privilèges dans un jeton.

Vous devez définir cet indicateur pour obtenir un handle dans un répertoire. Un handle de répertoire peut être passé à certaines fonctions au lieu d’un handle de fichier. Pour plus d’informations, consultez Descripteurs d’annuaire.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
Le fichier doit être supprimé immédiatement après la fermeture du dernier handle d’enregistreur traité dans le fichier, à condition que la transaction soit toujours active. Si un fichier a été marqué pour suppression et qu’un handle d’enregistreur traité est toujours ouvert une fois la transaction terminée, le fichier n’est pas supprimé.

S’il existe des descripteurs ouverts dans un fichier, l’appel échoue, sauf s’ils ont tous été ouverts avec le mode de partage FILE_SHARE_DELETE .

Les demandes d’ouverture suivantes du fichier échouent, sauf si le mode de partage FILE_SHARE_DELETE est spécifié.

FILE_FLAG_NO_BUFFERING
0x20000000
Le fichier est ouvert sans mise en cache système. Cet indicateur n’affecte pas la mise en cache du disque dur ou les fichiers mappés en mémoire. Lorsqu’il est combiné avec FILE_FLAG_OVERLAPPED, l’indicateur offre des performances asynchrones maximales, car les E/S ne reposent pas sur les opérations synchrones du gestionnaire de mémoire. Toutefois, certaines opérations d’E/S prennent plus de temps, car les données ne sont pas conservées dans le cache. En outre, les métadonnées du fichier peuvent toujours être mises en cache. Pour vider les métadonnées sur le disque, utilisez la fonction FlushFileBuffers.

Une application doit répondre à certaines exigences lors de l’utilisation de fichiers ouverts avec FILE_FLAG_NO_BUFFERING :

  • L’accès aux fichiers doit commencer à des décalages d’octets dans un fichier qui sont des multiples entiers de la taille du secteur du volume.
  • L’accès au fichier doit être pour les nombres d’octets qui sont des multiples entiers de la taille du secteur du volume. Par exemple, si la taille du secteur est de 512 octets, une application peut demander des lectures et écritures de 512, 1024, 1536 ou 2 048 octets, mais pas de 335, 981 ou 7171 octets.
  • Les adresses de mémoire tampon pour les opérations de lecture et d’écriture doivent être alignées sur un secteur, ce qui signifie qu’elles sont alignées sur les adresses en mémoire qui sont des multiples entiers de la taille du secteur du volume. Selon le disque, cette exigence peut ne pas être appliquée.
Une façon d’aligner des mémoires tampons sur des multiples entiers de la taille du secteur de volume consiste à utiliser VirtualAlloc pour allouer les mémoires tampons. Il alloue de la mémoire alignée sur les adresses qui sont des multiples entiers de la taille de la page mémoire du système d’exploitation. Étant donné que les tailles de page mémoire et de secteur de volume ont une puissance de 2, cette mémoire est également alignée sur les adresses qui sont des multiples entiers d’une taille de secteur de volume. Les pages mémoire ont une taille de 4 ou 8 Ko ; Les secteurs sont de 512 octets (disques durs), de 2 048 octets (CD) ou de 4 096 octets (disques durs) et, par conséquent, les secteurs de volume ne peuvent jamais être plus grands que les pages mémoire.

Une application peut déterminer une taille de secteur de volume en appelant la fonction GetDiskFreeSpace .

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Les données de fichier sont demandées, mais elles doivent continuer à se trouver dans le stockage distant. Il ne doit pas être retransporté vers le stockage local. Cet indicateur est destiné aux systèmes de stockage distants.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
Le traitement normal du point d’analyse ne se produira pas ; CreateFileTransacted tente d’ouvrir le point d’analyse. Lorsqu’un fichier est ouvert, un handle de fichier est retourné, que le filtre qui contrôle le point d’analyse soit opérationnel ou non. Cet indicateur ne peut pas être utilisé avec l’indicateur CREATE_ALWAYS . Si le fichier n’est pas un point d’analyse, cet indicateur est ignoré.
FILE_FLAG_OVERLAPPED
0x40000000
Le fichier est ouvert ou créé pour les E/S asynchrones. Une fois l’opération terminée, l’événement spécifié dans la structure OVERLAPPED est défini sur l’état signalé. Opérations qui prennent beaucoup de temps pour traiter les ERROR_IO_PENDING de retour.

Si cet indicateur est spécifié, le fichier peut être utilisé pour des opérations simultanées de lecture et d’écriture. Le système ne gère pas le pointeur de fichier. Par conséquent, vous devez passer la position du fichier aux fonctions de lecture et d’écriture dans la structure CHEVAUCHEMENT OU mettre à jour le pointeur de fichier.

Si cet indicateur n’est pas spécifié, les opérations d’E/S sont sérialisées, même si les appels aux fonctions de lecture et d’écriture spécifient une structure CHEVAUCHÉE .

FILE_FLAG_POSIX_SEMANTICS
0x01000000
Le fichier est accessible conformément aux règles POSIX. Cela inclut l’autorisation de plusieurs fichiers avec des noms, ne différant que dans la casse, pour les systèmes de fichiers qui prennent en charge ce nommage. Faites attention lorsque vous utilisez cette option, car les fichiers créés avec cet indicateur peuvent ne pas être accessibles par les applications écrites pour MS-DOS ou Windows 16 bits.
FILE_FLAG_RANDOM_ACCESS
0x10000000
Le fichier doit être accessible de manière aléatoire. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier.
FILE_FLAG_SESSION_AWARE
0x00800000
Le fichier ou l’appareil est ouvert avec la reconnaissance de session. Si cet indicateur n’est pas spécifié, les appareils par session (par exemple, un appareil utilisant la redirection USB RemoteFX) ne peuvent pas être ouverts par les processus exécutés dans la session 0. Cet indicateur n’a aucun effet pour les appelants qui ne sont pas dans la session 0. Cet indicateur est pris en charge uniquement sur les éditions serveur de Windows.

Windows Server 2008 R2 et Windows Server 2008 : Cet indicateur n’est pas pris en charge avant Windows Server 2012.

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
Le fichier est accessible de manière séquentielle du début à la fin. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier. Si une application déplace le pointeur de fichier pour un accès aléatoire, la mise en cache optimale peut ne pas se produire. Toutefois, le bon fonctionnement est toujours garanti.

La spécification de cet indicateur peut augmenter les performances pour les applications qui lisent des fichiers volumineux à l’aide d’un accès séquentiel. Les gains de performances peuvent être encore plus notables pour les applications qui lisent des fichiers volumineux principalement séquentiellement, mais qui ignorent parfois de petites plages d’octets.

Cet indicateur n’a aucun effet si le système de fichiers ne prend pas en charge les E/S mises en cache et les FILE_FLAG_NO_BUFFERING.

FILE_FLAG_WRITE_THROUGH
0x80000000
Les opérations d’écriture ne passent par aucun cache intermédiaire, elles vont directement sur le disque.

Si FILE_FLAG_NO_BUFFERING n’est pas également spécifié, afin que la mise en cache du système soit en vigueur, les données sont écrites dans le cache système, mais elles sont vidées sur le disque sans délai.

Si FILE_FLAG_NO_BUFFERING est également spécifié, de sorte que la mise en cache du système n’est pas appliquée, les données sont immédiatement vidées sur le disque sans passer par le cache système. Le système d’exploitation demande également une écriture via le cache du disque dur sur un média persistant. Toutefois, tous les matériels ne prennent pas en charge cette fonctionnalité d’écriture directe.

 

Le paramètre dwFlagsAndAttributes peut également spécifier des informations de qualité de service de sécurité. Pour plus d’informations, consultez Niveaux d’emprunt d’identité. Lorsque l’application appelante spécifie l’indicateur SECURITY_SQOS_PRESENT dans le cadre de dwFlagsAndAttributes, il peut également contenir une ou plusieurs des valeurs suivantes.

Indicateur de sécurité Signification
SECURITY_ANONYMOUS
Emprunte l’identité d’un client au niveau de l’emprunt d’identité anonyme.
SECURITY_CONTEXT_TRACKING
Le mode de suivi de la sécurité est dynamique. Si cet indicateur n’est pas spécifié, le mode de suivi de la sécurité est statique.
SECURITY_DELEGATION
Emprunte l’identité d’un client au niveau de l’emprunt d’identité de délégation.
SECURITY_EFFECTIVE_ONLY
Seuls les aspects activés du contexte de sécurité du client sont disponibles pour le serveur. Si vous ne spécifiez pas cet indicateur, tous les aspects du contexte de sécurité du client sont disponibles.

Cela permet au client de limiter les groupes et les privilèges qu’un serveur peut utiliser lors de l’emprunt d’identité du client.

SECURITY_IDENTIFICATION
Emprunte l’identité d’un client au niveau de l’identité.
SECURITY_IMPERSONATION
Emprunter l’identité d’un client au niveau de l’emprunt d’identité. Il s’agit du comportement par défaut si aucun autre indicateur n’est spécifié avec l’indicateur SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

Handle valide pour un fichier de modèle avec le droit d’accès GENERIC_READ . Le fichier de modèle fournit des attributs de fichier et des attributs étendus pour le fichier en cours de création. Ce paramètre peut être NULL.

Lors de l’ouverture d’un fichier existant, CreateFileTransacted ignore le fichier de modèle.

Lors de l’ouverture d’un nouveau fichier chiffré EFS, le fichier hérite de la liste DACL de son répertoire parent.

[in] hTransaction

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

[in, optional] pusMiniVersion

Miniversion à ouvrir. Si la transaction spécifiée dans hTransaction n’est pas la transaction qui modifie le fichier, ce paramètre doit être NULL. Sinon, ce paramètre peut être un identificateur de miniversion retourné par le code de contrôle FSCTL_TXFS_CREATE_MINIVERSION ou l’une des valeurs suivantes.

Valeur Signification
TXFS_MINIVERSION_COMMITTED_VIEW
0x0000
Affichage du fichier à la date de sa dernière validation.
TXFS_MINIVERSION_DIRTY_VIEW
0xFFFF
Vue du fichier tel qu’il est modifié par la transaction.
TXFS_MINIVERSION_DEFAULT_VIEW
0xFFFE
La vue commit ou sale du fichier, selon le contexte. Une transaction qui modifie le fichier obtient la vue sale, tandis qu’une transaction qui ne modifie pas le fichier obtient la vue validée.

lpExtendedParameter

Ce paramètre est réservé et doit être NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle ouvert pour le fichier, l’appareil, le canal nommé ou l’emplacement de messagerie spécifié.

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

Remarques

Lorsque vous utilisez le handle retourné par CreateFileTransacted, utilisez la version transactionnée des fonctions d’E/S de fichier au lieu des fonctions d’E/S de fichier standard, le cas échéant. Pour plus d’informations, consultez Considérations relatives à la programmation pour ntfs transactionnel.

Lors de l’ouverture d’un handle traité dans un répertoire, ce handle doit avoir des autorisations FILE_WRITE_DATA (FILE_ADD_FILE) et FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Celles-ci sont incluses dans les autorisations FILE_GENERIC_WRITE . Vous devez ouvrir des répertoires avec moins d’autorisations si vous utilisez simplement le handle pour créer des fichiers ou des sous-répertoires ; sinon, des violations de partage peuvent se produire.

Vous ne pouvez pas ouvrir un fichier avec FILE_EXECUTE niveau d’accès lorsque ce fichier fait partie d’une autre transaction (autrement dit, une autre application l’a ouvert en appelant CreateFileTransacted). Cela signifie que CreateFileTransacted échoue si le niveau d’accès FILE_EXECUTE ou FILE_ALL_ACCESS est spécifié

Lorsqu’une application non transactionnée appelle CreateFileTransacted avec MAXIMUM_ALLOWED spécifié pour lpSecurityAttributes, un handle est ouvert avec le même niveau d’accès à chaque fois. Lorsqu’une application transactionnée appelle CreateFileTransacted avec MAXIMUM_ALLOWED spécifié pour lpSecurityAttributes, un handle est ouvert avec une quantité d’accès différente selon que le fichier est verrouillé ou non par une transaction. Par exemple, si l’application appelante a FILE_EXECUTE niveau d’accès pour un fichier, l’application obtient cet accès uniquement si le fichier ouvert n’est pas verrouillé par une transaction ou est verrouillé par une transaction et que l’application est déjà un lecteur traité pour ce fichier.

Pour obtenir une description complète des opérations traitées, consultez NTFS transactionnel .

Utilisez la fonction CloseHandle pour fermer un handle d’objet retourné par CreateFileTransacted lorsque le handle n’est plus nécessaire et avant de valider ou de restaurer la transaction.

Certains systèmes de fichiers, tels que le système de fichiers NTFS, prennent en charge la compression ou le chiffrement pour les fichiers et répertoires individuels. Sur les volumes mis en forme pour ce type de système de fichiers, un nouveau fichier hérite des attributs de compression et de chiffrement de son répertoire.

Vous ne pouvez pas utiliser CreateFileTransacted pour contrôler la compression sur un fichier ou un répertoire. Pour plus d’informations, consultez Compression et décompression de fichiers et Chiffrement de fichier.

Comportement de lien symbolique : si l’appel à cette fonction crée un fichier, il n’y a aucun changement de comportement.

Si FILE_FLAG_OPEN_REPARSE_POINT est spécifié :

  • Si un fichier existant est ouvert et qu’il s’agit d’un lien symbolique, le descripteur retourné est un descripteur vers ce lien symbolique.
  • Si TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE sont spécifiés, le fichier affecté est un lien symbolique.
Si FILE_FLAG_OPEN_REPARSE_POINT n’est pas spécifié :
  • Si un fichier existant est ouvert et qu’il s’agit d’un lien symbolique, le descripteur retourné est un descripteur de la cible.
  • Si CREATE_ALWAYS, TRUNCATE_EXISTING ou FILE_FLAG_DELETE_ON_CLOSE sont spécifiés, le fichier affecté est la cible.
Il n’est pas garanti qu’une écriture multi-secteur soit atomique, sauf si vous utilisez une transaction (autrement dit, le handle créé est un handle traité). Une écriture à secteur unique est atomique. Les écritures multi-secteurs mises en cache peuvent ne pas toujours être écrites sur le disque ; Par conséquent, spécifiez FILE_FLAG_WRITE_THROUGH pour vous assurer qu’une écriture multi-secteur entière est écrite sur le disque sans mise en cache.

Comme indiqué précédemment, si le paramètre lpSecurityAttributes a la valeur NULL, le handle retourné par CreateFileTransacted ne peut pas être hérité par les processus enfants que votre application peut créer. Les informations suivantes concernant ce paramètre s’appliquent également :

  • Si bInheritHandle n’a pas la valeur FALSE, qui est une valeur différente de zéro, le handle peut être hérité. Par conséquent, il est essentiel que ce membre de structure soit correctement initialisé sur FALSE si vous ne souhaitez pas que le handle puisse être hérité.
  • Les listes de contrôle d’accès (ACL) du descripteur de sécurité par défaut d’un fichier ou d’un répertoire sont héritées de son répertoire parent.
  • Le système de fichiers cible doit prendre en charge la sécurité sur les fichiers et les répertoires pour que le lpSecurityDescriptor ait un effet sur ceux-ci, qui peut être déterminé à l’aide de GetVolumeInformation
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
 

Notez que SMB 3.0 ne prend pas en charge TxF.

Fichiers

Si vous essayez de créer un fichier sur un lecteur de disquette qui ne dispose pas d’une disquette ou d’un lecteur de CD-ROM qui n’a pas de CD, le système affiche un message pour que l’utilisateur insère un disque ou un CD. Pour empêcher le système d’afficher ce message, appelez la fonction SetErrorMode avec SEM_FAILCRITICALERRORS.

Pour plus d’informations, consultez Création et ouverture de fichiers.

Si vous renommez ou supprimez un fichier, puis que vous le restaurez peu après, le système recherche dans le cache des informations de fichier à restaurer. Les informations mises en cache incluent leur paire de noms court/long et l’heure de création.

Si vous appelez CreateFileTransacted sur un fichier en attente de suppression suite à un appel précédent à DeleteFile, la fonction échoue. Le système d’exploitation retarde la suppression du fichier jusqu’à ce que tous les handles du fichier soient fermés. GetLastError retourne ERROR_ACCESS_DENIED.

Le paramètre dwDesiredAccess peut être égal à zéro, ce qui permet à l’application d’interroger les attributs de fichier sans accéder au fichier si l’application s’exécute avec des paramètres de sécurité adéquats. Cela est utile pour tester l’existence d’un fichier sans l’ouvrir pour un accès en lecture et/ou en écriture, ou pour obtenir d’autres statistiques sur le fichier ou le répertoire. Consultez Obtention et définition d’informations sur le fichier et GetFileInformationByHandle.

Lorsqu’une application crée un fichier sur un réseau, il est préférable d’utiliser GENERIC_READ | GENERIC_WRITE plutôt que d’utiliser GENERIC_WRITE seule. Le code obtenu est plus rapide, car le redirecteur peut utiliser le gestionnaire de cache et envoyer moins de PME avec plus de données. Cette combinaison évite également un problème où l’écriture dans un fichier sur un réseau peut occasionnellement retourner ERROR_ACCESS_DENIED.

Flux de fichiers

Sur les systèmes de fichiers NTFS, vous pouvez utiliser CreateFileTransacted pour créer des flux distincts dans un fichier.

Pour plus d’informations, consultez Flux de fichiers.

Téléphonique

Une application ne peut pas créer de répertoire à l’aide de CreateFileTransacted. Par conséquent, seule la valeur OPEN_EXISTING est valide pour dwCreationDisposition pour ce cas d’usage. Pour créer un répertoire, l’application doit appeler CreateDirectoryTransacted, CreateDirectory ou CreateDirectoryEx.

Pour ouvrir un répertoire à l’aide de CreateFileTransacted, spécifiez l’indicateur FILE_FLAG_BACKUP_SEMANTICS dans le cadre de dwFlagsAndAttributes. Les vérifications de sécurité appropriées s’appliquent toujours lorsque cet indicateur est utilisé sans privilèges SE_BACKUP_NAME et SE_RESTORE_NAME .

Lorsque vous utilisez CreateFileTransacted pour ouvrir un répertoire pendant la défragmentation d’un volume de système de fichiers FAT ou FAT32, ne spécifiez pas le droit d’accès MAXIMUM_ALLOWED . L’accès au répertoire est refusé si cette opération est effectuée. Spécifiez plutôt le droit d’accès GENERIC_READ .

Pour plus d’informations, consultez À propos de la gestion d’annuaires.

Notes

L’en-tête winbase.h définit CreateFileTransacted 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

Voir aussi

CloseHandle

CopyFileTransacted

CreateDirectoryTransacted

DeleteFileTransacted

Compression et décompression de fichiers

Chiffrement de fichiers

Fonctions de gestion des fichiers

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

Flux de fichiers

FindFirstFileTransacted

Fonctions

GetFileAttributesTransacted

MoveFileTransacted

Rubriques de présentation

Éléments à prendre en compte pour la programmation pour Transactional NTFS

ReadFile

Transactional NTFS (TxF)

WriteFile