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.

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.

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.

dwSecurityQosFlags

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

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.

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

Voir aussi

CreateFile2

Structures de gestion des fichiers