Partager via


CREATEFILE2_EXTENDED_PARAMETERS structure (fileapi.h)

Contient des paramètres étendus facultatifs pour CreateFile2.

Syntaxe

typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
  DWORD                 dwSize;
  DWORD                 dwFileAttributes;
  DWORD                 dwFileFlags;
  DWORD                 dwSecurityQosFlags;
  LPSECURITY_ATTRIBUTES lpSecurityAttributes;
  HANDLE                hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;

Membres

dwSize

Contient la taille de cette structure, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).

dwFileAttributes

Les attributs et indicateurs de fichier ou d’appareil, FILE_ATTRIBUTE_NORMAL étant la valeur par défaut la plus courante pour les fichiers.

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.

Notes

Lorsque CreateFile2 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.

Certains des attributs et indicateurs de fichier suivants peuvent s’appliquer uniquement aux fichiers et pas nécessairement à tous les autres types d’appareils que CreateFile2 peut ouvrir. Pour plus d’informations, consultez la section Remarques de la CreateFile2 page de référence et Création et ouverture de fichiers.

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

Cet indicateur n’est pas pris en charge sur les éditions Famille, Famille Premium, Starter ou ARM de Windows.

Cet indicateur n’est pas pris en charge lorsqu’il est appelé à partir d’une application du Windows Store.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
Le fichier est masqué. Ne l’incluez pas dans une liste d’annuaires ordinaire.
FILE_ATTRIBUTE_INTEGRITY_STREAM
32768 (0x8000)
Fichier ou répertoire configuré avec intégrité. Pour un fichier, tous les flux de données du fichier sont intègres. Pour un répertoire, l’intégrité est la valeur par défaut pour les fichiers et sous-répertoires nouvellement créés, sauf indication contraire de l’appelant.

Cet indicateur est uniquement pris en charge sur le système de fichiers ReFS.

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.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

dwFileFlags

Ce paramètre peut contenir des combinaisons d’indicateurs (FILE_FLAG_*) pour contrôler le comportement de mise en cache des fichiers ou des appareils, les modes d’accès et d’autres indicateurs à usage spécial.

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 la section Notes.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
Le fichier doit être supprimé immédiatement après la fermeture de tous ses handles, ce qui comprend le handle spécifié et tous les autres handles ouverts ou dupliqués.

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_IGNORE_IMPERSONATED_DEVICEMAP
0x00020000
Un mappage d’appareils est un mappage entre les noms d’appareils DOS et les appareils dans le système, et est utilisé lors de la résolution des noms DOS. Des mappages d’appareils distincts existent pour chaque utilisateur dans le système, et les utilisateurs peuvent gérer leurs propres mappages d’appareils. En règle générale, pendant l’emprunt d’identité, la carte d’appareil de l’utilisateur emprunté est utilisée. Toutefois, lorsque cet indicateur est défini, le mappage des appareils de l’utilisateur du processus est utilisé à la place.
FILE_FLAG_NO_BUFFERING
0x20000000
Le fichier ou l’appareil est ouvert sans mise en cache système pour les lectures et les écritures de données. Cet indicateur n’affecte pas la mise en cache du disque dur ou les fichiers mappés en mémoire.

Il existe des exigences strictes pour utiliser correctement les fichiers ouverts avec CreateFile2 à l’aide de l’indicateur FILE_FLAG_NO_BUFFERING . Pour plus d’informations, consultez Mise en mémoire tampon des fichiers.

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 ; CreateFile2 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é.

Pour plus d'informations, consultez la section Notes.

FILE_FLAG_OPEN_REQUIRING_OPLOCK
0x00040000
Le fichier est en cours d’ouverture et un verrou opportuniste (oplock) sur le fichier est demandé en tant qu’opération atomique unique. Le système de fichiers recherche les oplocks avant d’effectuer l’opération de création, et échoue la création avec un dernier code d’erreur de ERROR_CANNOT_BREAK_OPLOCK si le résultat est d’interrompre un oplock existant.

Si vous utilisez cet indicateur et que votre appel à la fonction CreateFile2 est retourné avec succès, la première opération que vous devez effectuer sur le handle de fichier consiste à demander un oplock en appelant la fonction DeviceIOControl , puis à passer FSCTL_REQUEST_OPLOCK ou l’une des autres opérations de verrouillage opportunistes. Si vous effectuez d’autres opérations de système de fichiers avec le handle de fichier avant de demander un oplock, un blocage peut se produire.

Note Vous pouvez appeler en toute sécurité la fonction CloseHandle sur le handle de fichier sans demander au préalable un oplock.

 
FILE_FLAG_OVERLAPPED
0x40000000
Le fichier ou l’appareil est en cours d’ouverture ou de création pour les E/S asynchrones.

Lorsque les opérations d’E/S suivantes sont terminées sur ce handle, l’événement spécifié dans la structure CHEVAUCHEMENT EST défini sur l’état signalé.

Si cet indicateur est spécifié, le fichier peut être utilisé pour des opérations de lecture et d’écriture simultanées.

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 .

Pour plus d’informations sur les considérations à prendre en compte lors de l’utilisation d’un handle de fichier créé avec cet indicateur, consultez la section Handles d’E/S synchrones et asynchrones de cette rubrique.

FILE_FLAG_POSIX_SEMANTICS
0x01000000
L’accès se produit selon les règles POSIX. Cela inclut l’autorisation de plusieurs fichiers avec des noms différents uniquement en cas, pour les systèmes de fichiers qui prennent en charge ce nom. Soyez prudent 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
L’accès est destiné à être aléatoire. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier.

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.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

FILE_FLAG_SESSION_AWARE
0x00800000
Le fichier ou l’appareil est en cours d’ouverture 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 s’exécutant 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
L’accès est destiné à être séquentiel du début à la fin. Le système peut utiliser cette indication pour optimiser la mise en cache du fichier.

Cet indicateur ne doit pas être utilisé si la lecture-behind (c’est-à-dire les analyses descendantes) est utilisée.

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.

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

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

Pour plus d’informations, consultez la section Comportement de mise en cache de cette rubrique.

dwSecurityQosFlags

Le paramètre dwSecurityQosFlags spécifie les informations SQOS. Pour plus d’informations, consultez Niveaux d’emprunt d’identité.

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’emprunt d’identité d’identification.
SECURITY_IMPERSONATION
Emprunt d’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é.

lpSecurityAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui contient deux membres de données distincts mais associés : un descripteur de sécurité facultatif et une valeur booléenne qui détermine si le handle retourné peut être hérité par des processus enfants.

Ce paramètre peut être NULL.

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

Le membre lpSecurityDescriptor de la structure spécifie un SECURITY_DESCRIPTOR pour un fichier ou un appareil. Si ce membre a la valeur NULL, un descripteur de sécurité par défaut est attribué au fichier ou à l’appareil associé au handle retourné.

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

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

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

hTemplateFile

Handle valide pour un fichier modèle avec le droit d’accès GENERIC_READ . Le fichier 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, CreateFile2 ignore ce paramètre.

Lors de l’ouverture d’un nouveau fichier chiffré, le fichier hérite de la liste de contrôle d’accès discrétionnaire de son répertoire parent. Pour plus d’informations, consultez Chiffrement de fichiers.

Notes

Pour compiler une application qui utilise la structure CREATEFILE2_EXTENDED_PARAMETERS , définissez la macro _WIN32_WINNT en tant que 0x0602 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Comportement de mise en cache

Plusieurs des valeurs possibles pour le membre dwFileFlags sont utilisées pour contrôler ou affecter la façon dont les données associées au handle sont mises en cache par le système. Il s'agit des éléments suivants :

  • FILE_FLAG_NO_BUFFERING
  • FILE_FLAG_RANDOM_ACCESS
  • FILE_FLAG_SEQUENTIAL_SCAN
  • FILE_FLAG_WRITE_THROUGH
  • FILE_ATTRIBUTE_TEMPORARY

Si aucun de ces indicateurs n’est spécifié, le système utilise un schéma de mise en cache à usage général par défaut. Sinon, la mise en cache système se comporte comme spécifié pour chaque indicateur.

Certains de ces indicateurs ne doivent pas être combinés. Par instance, la combinaison de FILE_FLAG_RANDOM_ACCESS avec FILE_FLAG_SEQUENTIAL_SCAN est une auto-défaite.

La spécification de l’indicateur FILE_FLAG_SEQUENTIAL_SCAN peut augmenter les performances des 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 de manière séquentielle, mais qui ignorent parfois l’avance sur de petites plages d’octets. Si une application déplace le pointeur de fichier pour un accès aléatoire, des performances de mise en cache optimales ne se produisent probablement pas. Toutefois, le bon fonctionnement est toujours garanti.

Les indicateurs FILE_FLAG_WRITE_THROUGH et FILE_FLAG_NO_BUFFERING sont indépendants et peuvent être combinés.

Si FILE_FLAG_WRITE_THROUGH est utilisé mais qu’FILE_FLAG_NO_BUFFERING n’est pas également spécifié, de sorte que la mise en cache système est en vigueur, les données sont écrites dans le cache système, mais sont vidées sur le disque sans délai.

Si FILE_FLAG_WRITE_THROUGH et FILE_FLAG_NO_BUFFERING sont tous deux spécifiés, de sorte que la mise en cache système n’est pas en vigueur, les données sont immédiatement vidées sur le disque sans passer par le cache système Windows. Le système d’exploitation demande également une écriture directe du cache matériel local du disque dur sur un support persistant.

Notes

Tout le matériel de disque dur ne prend pas en charge cette fonctionnalité d’écriture directe.

L’utilisation correcte de l’indicateur FILE_FLAG_NO_BUFFERING nécessite des considérations d’application particulières. Pour plus d’informations, consultez Mise en mémoire tampon de fichiers.

Une demande d’écriture directe via FILE_FLAG_WRITE_THROUGH entraîne également le vidage ntfs de toutes les modifications de métadonnées, telles qu’une mise à jour d’horodatage ou une opération de renommage, qui résultent du traitement de la demande. Pour cette raison, l’indicateur FILE_FLAG_WRITE_THROUGH est souvent utilisé avec l’indicateur FILE_FLAG_NO_BUFFERING en remplacement de l’appel de la fonction FlushFileBuffers après chaque écriture, ce qui peut entraîner des pénalités de performances inutiles. L’utilisation de ces indicateurs permet d’éviter ces pénalités. Pour obtenir des informations générales sur la mise en cache des fichiers et des métadonnées, consultez Mise en cache de fichiers.

Lorsque FILE_FLAG_NO_BUFFERING est combiné à FILE_FLAG_OVERLAPPED, les indicateurs offrent 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 (par exemple, lors de la création d’un fichier vide). Pour vous assurer que les métadonnées sont vidées sur le disque, utilisez la fonction FlushFileBuffers .

Si vous spécifiez l’attribut FILE_ATTRIBUTE_TEMPORARY , les systèmes de fichiers évitent d’écrire des données dans le stockage de masse si la mémoire cache est suffisante, car une application supprime un fichier temporaire après la fermeture d’un handle. Dans ce cas, le système peut entièrement éviter d’écrire les données. Bien qu’il ne contrôle pas directement la mise en cache des données de la même manière que les indicateurs mentionnés précédemment, l’attribut FILE_ATTRIBUTE_TEMPORARY indique au système de conserver autant que possible dans le cache système sans écriture et peut donc être préoccupant pour certaines applications.

Handles d’E/S synchrones et asynchrones

CreateFile2 permet de créer un fichier ou un handle d’appareil synchrone ou asynchrone. Un handle synchrone se comporte de telle sorte que les appels de fonction E/S à l’aide de ce handle soient bloqués jusqu’à ce qu’ils se terminent, tandis qu’un handle de fichier asynchrone permet au système de retourner immédiatement à partir des appels de fonction E/S, qu’ils ont terminé l’opération d’E/S ou non. Comme indiqué précédemment, ce comportement synchrone et asynchrone est déterminé en spécifiant FILE_FLAG_OVERLAPPED dans le membre dwFileFlags de la structure CREATEFILE2_EXTENDED_PARAMETERS passée dans le paramètre pCreateExParams . Il existe plusieurs complexités et pièges potentiels lors de l’utilisation d’E/S asynchrones ; Pour plus d’informations, consultez E/S synchrones et asynchrones.

Spécifications

   
Client minimal pris en charge Windows 8 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau | Applications UWP]
En-tête fileapi.h (inclure Windows.h)

Voir aussi

CreateFile2

Structures de gestion des fichiers