structure CREATEFILE2_EXTENDED_PARAMETERS (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.
Note
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 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 uniquement s’appliquer aux fichiers et pas nécessairement tous les autres types d’appareils qui CreateFile2 peuvent s’ouvrir. Pour plus d’informations, consultez la section Remarques de la page de référence CreateFile2 et Création et ouverture de fichiers.
Pour obtenir 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 d’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.
| Drapeau | Signification |
|---|---|
|
Le fichier est ouvert ou créé 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 a des privilèges SE_BACKUP_NAME et SE_RESTORE_NAME. Pour plus d’informations, consultez Modification des privilèges dans unde jeton.
Vous devez définir cet indicateur pour obtenir un handle sur un répertoire. Un handle de répertoire peut être transmis à certaines fonctions au lieu d’un handle de fichier. Pour plus d’informations, consultez la section Remarques. |
|
Le fichier doit être supprimé immédiatement après la fermeture de tous ses handles, qui inclut le handle spécifié et tous les autres handles ouverts ou dupliqués.
S’il existe des handles ouverts existants 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 pour le fichier échouent, sauf si le mode de partage FILE_SHARE_DELETE est spécifié. |
|
Une carte d’appareil est un mappage entre les noms d’appareils DOS et les appareils du système, et est utilisé lors de la résolution des noms DOS. Il existe des mappages d’appareils distincts pour chaque utilisateur du système, et les utilisateurs peuvent gérer leurs propres cartes d’appareils. En règle générale, lors de l’emprunt d’identité, la carte d’appareil de l’utilisateur emprunt d’identité serait utilisée. Toutefois, lorsque cet indicateur est défini, la carte de l’appareil de l’utilisateur de processus est utilisée à la place. |
|
Le fichier ou l’appareil est ouvert sans mise en cache système pour les lectures et écritures de données. Cet indicateur n’affecte pas la mise en cache de disque dur ou les fichiers mappés en mémoire.
Il existe des exigences strictes pour l’utilisation des fichiers ouverts avec createFile2 à l’aide de l’indicateur de FILE_FLAG_NO_BUFFERING, pour plus d’informations, consultez de mise en mémoire tampon de fichiers. |
|
Les données de fichier sont demandées, mais elles doivent continuer à se trouver dans le stockage distant. Il ne doit pas être transporté vers le stockage local. Cet indicateur est utilisé par les systèmes de stockage distants. |
|
Le traitement normal point d’analyse ne se produit pas ; CreateFile2 tentera 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 Remarques. |
|
Le fichier est ouvert et un verrou opportuniste (oplock) sur le fichier est demandé en tant qu’opération atomique unique. Le système de fichiers vérifie les oplocks avant d’effectuer l’opération de création et échouera la création avec un dernier code d’erreur de ERROR_CANNOT_BREAK_OPLOCK si le résultat serait d’interrompre un oplock existant.
Si vous utilisez cet indicateur et votre appel à la fonction
Remarque Vous pouvez appeler en toute sécurité la fonction CloseHandle sur le handle de fichier sans demander d’abord un oplock.
|
|
Le fichier ou l’appareil est ouvert ou créé pour les E/S asynchrones.
Lorsque les opérations d’E/S suivantes sont effectuées sur ce handle, l’événement spécifié dans la structure OVERLAPPED sera défini sur l’état signalé. Si cet indicateur est spécifié, le fichier peut être utilisé pour les 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 SE CHEVAUCHER. Pour plus d’informations sur les considérations relatives à l’utilisation d’un handle de fichier créé avec cet indicateur, consultez la section handles d’E/S synchrones et asynchrones de cette rubrique. |
|
L’accès se produit en fonction des règles POSIX. Cela inclut l’autorisation de plusieurs fichiers avec des noms, qui diffèrent uniquement dans le cas, pour les systèmes de fichiers qui prennent en charge ce nom. Veillez à utiliser 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. |
|
L’accès est destiné à être aléatoire. Le système peut l’utiliser comme indicateur pour optimiser la mise en cache des fichiers.
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. |
|
Le fichier ou l’appareil est ouvert avec une prise en charge 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. |
|
L’accès est destiné à être séquentiel de début à fin. Le système peut l’utiliser comme indicateur pour optimiser la mise en cache des fichiers.
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. |
|
Les opérations d’écriture ne passent par aucun cache intermédiaire, elles vont 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é.
lpSecurityAttributes
Pointeur vers une structure SECURITY_ATTRIBUTES qui contient deux membres de données distincts mais connexes : un descripteur de sécurité facultatif et une valeur booléenne qui détermine si le handle retourné peut être hérité par les processus enfants.
Ce paramètre peut être NULL.
Si ce paramètre est 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 lpSecurityDescriptor membre de la structure spécifie un SECURITY_DESCRIPTOR pour un fichier ou un appareil. Si ce membre est NULL, le fichier ou l’appareil associé au handle retourné est affecté à un descripteur de sécurité par défaut.
Le bInheritHandle membre 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 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, 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 .
Remarques
Pour compiler une application qui utilise la structure CREATEFILE2_EXTENDED_PARAMETERS, définissez la macro _WIN32_WINNT comme 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 les dwFileFlags membre 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. Elles sont les suivantes :
- 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 du système se comporte comme spécifié pour chaque indicateur.
Certains de ces indicateurs ne doivent pas être combinés. Par exemple, la combinaison de FILE_FLAG_RANDOM_ACCESS avec FILE_FLAG_SEQUENTIAL_SCAN est 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 visibles pour les applications qui lisent les fichiers volumineux principalement de manière séquentielle, mais ignorent occasionnellement les petites plages d’octets. Si une application déplace le pointeur de fichier pour l’accès aléatoire, les performances de mise en cache optimales ne se produisent probablement pas. Toutefois, une opération correcte est toujours garantie.
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 que FILE_FLAG_NO_BUFFERING n’est pas également spécifié, de sorte que la mise en cache du système soit en vigueur, les données sont écrites dans le cache du système, mais sont vidées sur le disque sans délai.
Si FILE_FLAG_WRITE_THROUGH et FILE_FLAG_NO_BUFFERING sont tous les deux spécifiés, de sorte que la mise en cache du système n’est pas en vigueur, les données sont immédiatement vidées sur le disque sans passer par le cache du système Windows. Le système d’exploitation demande également une écriture du cache matériel local du disque dur sur un média persistant.
Note
Le matériel de disque dur ne prend pas en charge cette fonctionnalité d’écriture.
L’utilisation appropriée de l’indicateur de FILE_FLAG_NO_BUFFERING nécessite des considérations particulières relatives à l’application. Pour plus d’informations, consultez de mise en mémoire tampon de fichiers .
Une requête en écriture via FILE_FLAG_WRITE_THROUGH entraîne également le vidage de toutes les modifications de métadonnées, telles qu’une mise à jour d’horodatage ou une opération de renommage, résultant du traitement de la demande. Pour cette raison, l’indicateur de FILE_FLAG_WRITE_THROUGH est souvent utilisé avec l’indicateur FILE_FLAG_NO_BUFFERING comme 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 des fichiers.
Lorsque FILE_FLAG_NO_BUFFERING est combinée à 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.
En spécifiant l’attribut FILE_ATTRIBUTE_TEMPORARY, les systèmes de fichiers évitent d’écrire des données dans le stockage en masse si une mémoire cache suffisante est disponible, car une application supprime un fichier temporaire une fois qu’un handle est fermé. Dans ce cas, le système peut tout à fait é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 façon que les indicateurs mentionnés précédemment, l’attribut FILE_ATTRIBUTE_TEMPORARY indique au système de contenir autant que possible dans le cache système sans écrire et peut donc être préoccupé par certaines applications.
Handles d’E/S synchrones et asynchrones
CreateFile2 fournit la création d’un handle de fichier ou d’appareil synchrone ou asynchrone. Un handle synchrone se comporte de sorte que les appels de fonction d’E/S à l’aide de ce handle sont 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 d’E/S, qu’ils terminent 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 dwFileFlags membre 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 d’E/S synchrones et asynchrones.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8 [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2012 [applications de bureau | Applications UWP] |
| d’en-tête | fileapi.h (include Windows.h) |