Fonction CreateFile2 (fileapi.h)
Crée ou ouvre un fichier ou un périphérique d’E/S. Les périphériques d’E/S les plus couramment utilisés sont les suivants : fichier, flux de fichiers, répertoire, disque physique, volume, mémoire tampon de la console, lecteur de bande, ressource de communication, fente de courrier et tuyau. La fonction retourne un handle qui peut être utilisé pour accéder au fichier ou à l’appareil pour différents types d’E/S en fonction du fichier ou de l’appareil et des indicateurs et attributs spécifiés.
Lorsqu’il est appelé à partir d’une application du Windows Store, CreateFile2 est simplifié. Vous pouvez ouvrir uniquement des fichiers ou des répertoires dans les répertoires ApplicationData.LocalFolder ou Package.InstalledLocation . Vous ne pouvez pas ouvrir de canaux nommés ou de mailslots ou créer des fichiers chiffrés (FILE_ATTRIBUTE_ENCRYPTED).
Syntaxe
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
Paramètres
[in] lpFileName
Nom du fichier ou de l’appareil à créer ou à ouvrir.
Pour plus d’informations sur les noms d’appareils spéciaux, consultez Définition d’un nom d’appareil MS-DOS.
Pour créer un flux de fichier, 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 demandé au fichier ou à l’appareil, qui peut être résumé en lecture, en écriture, à la fois ou à 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, Sécurité des fichiers et droits d’accès, Constantes des droits d’accès aux fichiers et ACCESS_MASK.
Si ce paramètre est égal à zéro, l’application peut interroger certaines métadonnées telles que des attributs de fichier, de répertoire ou d’appareil sans accéder à ce fichier ou appareil, même si GENERIC_READ accès aurait été refusé.
Vous ne pouvez pas demander un mode d’accès en conflit avec le mode de partage spécifié par le paramètre dwShareMode dans une demande ouverte qui a déjà un handle ouvert.
Pour plus d’informations, consultez la section Remarques de cette rubrique et Création et ouverture de fichiers.
[in] dwShareMode
Mode de partage demandé du fichier ou de l’appareil, qui peut être lu, écrit, à la fois, supprimé, tous ces éléments ou aucun (reportez-vous au tableau suivant). Les demandes d’accès aux attributs ou aux attributs étendus ne sont pas affectées par cet indicateur.
Si ce paramètre est égal à zéro et que CreateFile2 réussit, le fichier ou l’appareil ne peut pas être partagé et ne peut pas être ouvert à nouveau tant que le handle du fichier ou de l’appareil n’est pas fermé. Pour plus d'informations, consultez la section Notes.
Vous ne pouvez pas demander un mode de partage qui est en conflit avec le mode d’accès spécifié dans une demande existante qui a un handle ouvert. CreateFile2 échoue et la fonction GetLastError retourne ERROR_SHARING_VIOLATION.
Pour permettre à un processus de partager un fichier ou un appareil pendant qu’un autre processus a le fichier ou l’appareil ouvert, utilisez une combinaison compatible d’une ou plusieurs des valeurs suivantes. Pour plus d’informations sur les combinaisons valides de ce paramètre avec le paramètre dwDesiredAccess , consultez Création et ouverture de fichiers.
[in] dwCreationDisposition
Action à entreprendre sur un fichier ou un appareil qui existe ou n’existe pas.
Pour les appareils autres que les fichiers, ce paramètre est généralement défini sur OPEN_EXISTING.
Pour plus d'informations, consultez la section Notes.
Ce paramètre doit être l’une des valeurs suivantes, qui ne peut pas être combinée :
[in, optional] pCreateExParams
Pointeur vers une structure CREATEFILE2_EXTENDED_PARAMETERS facultative.
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
Pour compiler une application qui utilise la fonction CreateFile2 , définissez la macro _WIN32_WINNT comme 0x0602 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.
CreateFile2 prend en charge l’interaction de fichier et la plupart des autres types d’appareils et mécanismes d’E/S disponibles pour les développeurs Windows. Cette section tente de couvrir les divers problèmes que les développeurs peuvent rencontrer lors de l’utilisation de CreateFile2 dans différents contextes et avec différents types d’E/S. Le texte tente d’utiliser le fichier word uniquement lorsqu’il fait référence spécifiquement aux données stockées dans un fichier réel sur un système de fichiers. Toutefois, certaines utilisations du fichier peuvent faire référence plus généralement à un objet d’E/S qui prend en charge des mécanismes de type fichier. Cette utilisation libérale du terme fichier est particulièrement répandue dans les noms de constantes et de paramètres en raison des raisons historiques mentionnées précédemment.
Lorsqu’une application a terminé d’utiliser le handle d’objet retourné par CreateFile2, utilisez la fonction CloseHandle pour fermer le handle. Cela libère non seulement les ressources système, mais peut avoir une influence plus large sur des éléments tels que le partage du fichier ou de l’appareil et la validation des données sur le disque. Les détails sont indiqués dans cette rubrique, selon le cas.
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 qui ont un système de fichiers monté avec cette prise en charge, un nouveau fichier hérite des attributs de compression et de chiffrement de son répertoire.
Vous ne pouvez pas utiliser CreateFile2 pour contrôler la compression, la décompression ou le déchiffrement sur un fichier ou un répertoire. Pour plus d’informations, consultez Création et ouverture de fichiers, Compression et décompression de fichiers et Chiffrement de fichiers.
Si le membre lpSecurityAttributes de la structure CREATEFILE2_EXTENDED_PARAMETERS passée dans le paramètre pCreateExParams a la valeur NULL, le handle retourné par CreateFile2 ne peut pas être hérité par les processus enfants que votre application peut créer. Les informations suivantes concernant ce membre s’appliquent également :
- Si la variable membre bInheritHandle n’est pas FALSE, ce 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 membre lpSecurityDescriptor ait un effet sur ceux-ci, ce qui peut être déterminé à l’aide de GetVolumeInformation.
| Technologie | Prise en charge |
|---|---|
| Protocole Server Message Block (SMB) 3.0 | Oui |
| 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) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Comportement des liens symboliques
Si l’appel à cette fonction crée un fichier, il n’y a aucun changement de comportement. Tenez également compte des informations suivantes concernant FILE_FLAG_OPEN_REPARSE_POINT indicateur pour le membre dwFileFlags de la structure CREATEFILE2_EXTENDED_PARAMETERS passée dans le paramètre pCreateExParams :-
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.
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 CreateFile2 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 pour dwDesiredAccess 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.
Pour plus d’informations, consultez Création et ouverture de fichiers.
Flux de fichiers
Sur les systèmes de fichiers NTFS, vous pouvez utiliser CreateFile2 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 CreateFile2. 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 CreateDirectory ou CreateDirectoryEx.Pour ouvrir un répertoire à l’aide de CreateFile2, spécifiez l’indicateur FILE_FLAG_BACKUP_SEMANTICS dans le cadre du membre dwFileFlags de la structure CREATEFILE2_EXTENDED_PARAMETERS passée dans le paramètre pCreateExParams . 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 CreateFile2 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.
Disques physiques et volumes
L’accès direct au disque ou à un volume est limité.Vous pouvez utiliser la fonction CreateFile2 pour ouvrir un lecteur de disque physique ou un volume, qui retourne un handle de périphérique de stockage à accès direct (DASD) qui peut être utilisé avec la fonction DeviceIoControl . Cela vous permet d’accéder directement au disque ou au volume, par exemple les métadonnées de disque comme la table de partition. Toutefois, ce type d’accès expose également le lecteur de disque ou le volume à une perte de données potentielle, car une écriture incorrecte sur un disque à l’aide de ce mécanisme peut rendre son contenu inaccessible au système d’exploitation. Pour garantir l’intégrité des données, veillez à vous familiariser avec DeviceIoControl et comment les autres API se comportent différemment avec un handle d’accès direct par rapport à un handle de système de fichiers.
Les conditions suivantes doivent être remplies pour qu’un tel appel réussisse :
- L’appelant doit disposer de privilèges administratifs. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.
- Le paramètre dwCreationDisposition doit avoir l’indicateur OPEN_EXISTING .
- Lors de l’ouverture d’un volume ou d’une disquette, le paramètre dwShareMode doit avoir l’indicateur FILE_SHARE_WRITE .
| String | Signification |
|---|---|
| « \\.\PhysicalDrive0 » | Ouvre le premier lecteur physique. |
| « \\.\PhysicalDrive2 » | Ouvre le troisième lecteur physique. |
Pour obtenir l’identificateur de lecteur physique d’un volume, ouvrez un handle sur le volume et appelez la fonction DeviceIoControl avec IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Ce code de contrôle retourne le numéro de disque et le décalage pour chacune des extensions du volume ; un volume peut s’étendre sur plusieurs disques physiques.
Pour obtenir un exemple d’ouverture d’un lecteur physique, consultez Appel de DeviceIoControl.
Lors de l’ouverture d’un volume ou d’un lecteur multimédia amovible (par exemple, un lecteur de disquette ou un lecteur de mémoire flash), la chaîne lpFileName doit avoir la forme suivante : « \.\X : ». N’utilisez pas de barre oblique inverse de fin (\), qui indique le répertoire racine d’un lecteur. Le tableau suivant présente quelques exemples de chaînes de lecteur.
| String | Signification |
|---|---|
| « \\.\A : » | Ouvre le lecteur de disquette A. |
| « \\.\C : » | Ouvre le volume C :. |
| « \\.\C :\ » | Ouvre le système de fichiers du volume C :. |
Vous pouvez également ouvrir un volume en faisant référence à son nom de volume. Pour plus d’informations, consultez Affectation de noms à un volume.
Un volume contient un ou plusieurs systèmes de fichiers montés. Les handles de volume peuvent être ouverts comme non mis en cache à la discrétion du système de fichiers particulier, même lorsque l’option non mise en cache n’est pas spécifiée dans CreateFile2. Vous devez supposer que tous les systèmes de fichiers Microsoft ouvrent des handles de volume comme non mis en cache. Les restrictions sur les E/S non mises en cache pour les fichiers s’appliquent également aux volumes.
Un système de fichiers peut nécessiter ou non l’alignement de la mémoire tampon même si les données ne sont pas mises en cache. Toutefois, si l’option non mise en cache est spécifiée lors de l’ouverture d’un volume, l’alignement de la mémoire tampon est appliqué quel que soit le système de fichiers sur le volume. Il est recommandé sur tous les systèmes de fichiers d’ouvrir les handles de volume comme non mis en cache et de suivre les restrictions d’E/S non mises en cache.
Changer l’appareil
Les codes de contrôle IOCTL_CHANGER_* pour DeviceIoControl acceptent un handle pour un appareil de changeur. Pour ouvrir un appareil de changeur, utilisez un nom de fichier au format suivant : « \\.\Changerx », où x est un nombre qui indique l’appareil à ouvrir, en commençant par zéro. Pour ouvrir le périphérique de changeur zéro dans une application écrite en C ou C++, utilisez le nom de fichier suivant : « \\\\.\Changer0 ».Lecteurs de bande
Vous pouvez ouvrir des lecteurs de bande à l’aide d’un nom de fichier au format suivant : « \\.\TAPEx », où x est un nombre qui indique le lecteur à ouvrir, en commençant par zéro. Pour ouvrir le lecteur de bande zéro dans une application écrite en C ou C++, utilisez le nom de fichier suivant : « \\\\.\\TAPE0 ».Pour plus d’informations, consultez Sauvegarde.
Ressources de communication
La fonction CreateFile2 peut créer un handle pour une ressource de communication, telle que le port série COM1. Pour les ressources de communication, le paramètre dwCreationDisposition doit être OPEN_EXISTING, le paramètre dwShareMode doit être égal à zéro (accès exclusif) et le paramètre hTemplateFile doit être NULL. L’accès en lecture, en écriture ou en lecture/écriture peut être spécifié, et le handle peut être ouvert pour les E/S qui se chevauchent.Pour spécifier un numéro de port COM supérieur à 9, utilisez la syntaxe suivante : « \.\COM10 ». Cette syntaxe fonctionne pour tous les numéros de port et le matériel qui permet de spécifier des numéros de port COM.
Pour plus d’informations sur les communications, consultez Communications.
Consoles
La fonction CreateFile2 peut créer un handle pour l’entrée de console (CONIN$). Si le processus a un handle ouvert en raison d’un héritage ou d’une duplication, il peut également créer un handle pour la mémoire tampon d’écran active (CONOUT$). Le processus appelant doit être attaché à une console héritée ou à une console allouée par la fonction AllocConsole . Pour les descripteurs de console, définissez les paramètres CreateFile2 comme suit.| Paramètres | Valeur |
|---|---|
| lpFileName |
Utilisez la valeur CONIN$ pour spécifier l’entrée de la console.
Utilisez la valeur CONOUT$ pour spécifier la sortie de la console. CONIN$ obtient un handle vers la mémoire tampon d’entrée de la console, même si la fonction SetStdHandle redirige le handle d’entrée standard. Pour obtenir le handle d’entrée standard, utilisez la fonction GetStdHandle . CONOUT$ obtient un handle vers la mémoire tampon d’écran active, même si SetStdHandle redirige le handle de sortie standard. Pour obtenir le handle de sortie standard, utilisez GetStdHandle. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE est préférable, mais l’un ou l’autre peut limiter l’accès.
|
| dwShareMode |
Lors de l’ouverture de CONIN$, spécifiez FILE_SHARE_READ. Lors de l’ouverture de CONOUT$, spécifiez FILE_SHARE_WRITE.
Si le processus appelant hérite de la console, ou si un processus enfant doit pouvoir accéder à la console, ce paramètre doit être |
| dwCreationDisposition | Vous devez spécifier OPEN_EXISTING lors de l’utilisation de CreateFile2 pour ouvrir la console. |
Définissez les membres de la structure CREATEFILE2_EXTENDED_PARAMETERS passées dans le paramètre pCreateExParams comme suit.
| Membres | Valeur |
|---|---|
| lpSecurityAttributes | Si vous souhaitez que la console soit héritée, le membre bInheritHandle de la structure SECURITY_ATTRIBUTES doit avoir la valeur TRUE. |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
Ignoré. |
Le tableau suivant présente différents paramètres de dwDesiredAccess et lpFileName.
| lpFileName | dwDesiredAccess | Résultats |
|---|---|---|
| « CON » | GENERIC_READ | Ouvre la console pour l’entrée. |
| « CON » | GENERIC_WRITE | Ouvre la console pour la sortie. |
| « CON » | GENERIC_READ | GENERIC_WRITE |
Provoque l’échec de CreateFile2 ; GetLastError retourne ERROR_FILE_NOT_FOUND. |
Mailslots
Si CreateFile2 ouvre la fin du client d’un maillot, la fonction retourne INVALID_HANDLE_VALUE si le client maillot tente d’ouvrir un maillot local avant que le serveur maillot ne l’ait créé avec la fonction CreateMailSlot .Pour plus d’informations, consultez Mailslots.
Tuyaux
Si CreateFile2 ouvre l’extrémité cliente d’un canal nommé, la fonction utilise n’importe quel instance du canal nommé qui est à l’état d’écoute. Le processus d’ouverture peut dupliquer le handle autant de fois que nécessaire, mais une fois ouvert, le canal nommé instance ne peut pas être ouvert par un autre client. L’accès spécifié lors de l’ouverture d’un canal doit être compatible avec l’accès spécifié dans le paramètre dwOpenMode de la fonction CreateNamedPipe .Si la fonction CreateNamedPipe n’a pas été correctement appelée sur le serveur avant cette opération, aucun canal n’existe et CreateFile2 échoue avec ERROR_FILE_NOT_FOUND.
S’il existe au moins un canal actif instance mais qu’aucun canal d’écoute n’est disponible sur le serveur, ce qui signifie que toutes les instances de canal sont actuellement connectées, CreateFile2 échoue avec ERROR_PIPE_BUSY.
Pour plus d’informations, consultez Canaux.
Configuration requise
| 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] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
À propos de la gestion des répertoires
À propos de la gestion des volumes
Création, suppression et maintenance des fichiers
Contrôle d’entrée et de sortie de l’appareil (IOCTL)
Compression et décompression de fichiers
Fonctions de gestion des fichiers
Sécurité du fichier et droits d’accès
Fonctions
Obtention et définition des informations sur un fichier
Rubriques de présentation
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour