Langage de programmation - C pour Windows - API de Windows

CreateFileA	kernel32.dll	Création d'un fichier

Syntaxe

HANDLE CreateFileA( LPCTSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile );

Paramètres

Nom	Description
lpFileName	Ce paramètre permet d'indiquer le nom du fichier ou du périphérique à créer ou à ouvrir. Vous pouvez utiliser des barres obliques (/) ou des barres obliques inverses () dans ce nom.
dwDesiredAccess	Ce paramètre permet d'indiquer l'accès demandé au fichier ou au périphérique, pouvant être résumé en lecture, en écriture, les deux ou aucun (avec la valeur 0).
dwShareMode	Ce paramètre permet d'indiquer le mode de partage demandé du fichier ou du périphérique, pouvant être lu, écrit, supprimé, tous, ou aucun. Les demandes d'accès aux attributs ou aux attributs étendus ne sont pas affectées par ce drapeau. Voici les modes reconnus :
	Constante	Valeur	Description
	0	0x00000000	Cette constante permet d'empêcher les autres processus d'ouvrir un fichier ou un périphérique s'ils demandent un accès en suppression, en lecture ou en écriture.
	FILE_SHARE_DELETE	0x00000004	Cette constante permet aux opérations ouvertes ultérieures sur un fichier ou un périphérique de demander un accès par suppression. Sinon, les autres processus ne peuvent pas ouvrir le fichier ou le périphérique s'ils demandent un accès en suppression. Si ce drapeau n'est pas spécifié, mais que le fichier ou le périphérique a été ouvert pour un accès en suppression, la fonction échoue. L'accès à la suppression permet les opérations de suppression et de renommage.
	FILE_SHARE_READ	0x00000001	Cette constante permet aux opérations ouvertes ultérieures sur un fichier ou un périphérique de demander un accès en lecture. Sinon, les autres processus ne peuvent pas ouvrir le fichier ou le périphérique s'ils demandent un accès en lecture. Si ce drapeau n'est pas spécifié, mais que le fichier ou le périphérique a été ouvert pour un accès en lecture, la fonction échoue.
	FILE_SHARE_WRITE	0x00000002	Cette constante permet aux opérations ouvertes ultérieures sur un fichier ou un périphérique de demander un accès en écriture. Sinon, les autres processus ne peuvent pas ouvrir le fichier ou le périphérique s'ils demandent un accès en écriture. Si ce drapeau n'est pas spécifié, mais que le fichier ou le périphérique a été ouvert pour un accès en écriture ou dispose d'une cartographie de fichier avec un accès en écriture, la fonction échoue.
lpSecurityAttributes	Ce paramètre permet d'indiquer un pointeur sur une structure SECURITY_ATTRIBUTES contenant deux membres de données distincts mais liés : un descripteur de sécurité facultatif et une valeur booléenne déterminant si le descripteur renvoyé peut être hérité par des processus enfants. Ce paramètre peut être NULL.
dwCreationDisposition	Ce paramètre permet d'indiquer l'action à entreprendre sur un fichier ou un périphérique existant ou inexistant. Pour les périphériques autres que les fichiers, ce paramètre est généralement défini sur OPEN_EXISTING. Ce paramètre doit être l'une des valeurs suivantes, ne pouvant pas être combinées :
	Constante	Valeur	Description
	CREATE_ALWAYS	2	Cette constante permet de toujours créer un nouveau fichier. Si le fichier spécifié existe et qu'il est accessible en écriture, la fonction remplace 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 0.
	CREATE_NEW	1	Cette constante permet de créer un nouveau fichier, seulement s'il n'existe pas déjà. Si le fichier spécifié existe, la fonction échoue et le dernier code d'erreur est défini sur ERROR_FILE_EXISTS (80). Si le fichier spécifié n'existe pas et constitue un chemin valide vers un emplacement accessible en écriture, un nouveau fichier est créé.
	OPEN_ALWAYS	4	Cette constante permet de toujours ouvrir un fichier. Si le fichier spécifié existe, la fonction réussit et le dernier code d'erreur est défini sur ERROR_ALREADY_EXISTS (183). Si le fichier spécifié n'existe pas et constitue un chemin valide vers un emplacement accessible en écriture, la fonction crée un fichier et le code de la dernière erreur est défini sur 0.
	OPEN_EXISTING	3	Cette constante permet d'ouvrir un fichier ou un périphérique, uniquement s'il existe. Si le fichier ou le périphérique spécifié n'existe pas, la fonction échoue et le dernier code d'erreur est défini sur ERROR_FILE_NOT_FOUND (2).
	TRUNCATE_EXISTING	5	Cette constante permet d'ouvrir un fichier et le tronque de manière à ce que sa taille soit égale à 0 octet, uniquement s'il existe. Si le fichier spécifié n'existe pas, la fonction échoue et le dernier code d'erreur est défini sur ERROR_FILE_NOT_FOUND (2). Le processus appelant doit ouvrir le fichier avec le bit GENERIC_WRITE défini dans le paramètre dwDesiredAccess.
dwFlagsAndAttributes	Ce paramètre permet d'indiquer les attributs et les drapeaux de fichier ou de périphérique, FILE_ATTRIBUTE_NORMAL étant la valeur par défaut la plus courante pour les fichiers. Voici les modes reconnus :
	Constante	Valeur	Description
	FILE_ATTRIBUTE_ARCHIVE	0x20	Cette constante permet d'indiquer que le fichier doit être archivé. Les applications utilisent cet attribut pour marquer les fichiers à sauvegarder ou à supprimer.
	FILE_ATTRIBUTE_ENCRYPTED	0x4000	Cette constante permet d'indiquer que le fichier ou le répertoire est crypté. Pour un fichier, cette situation signifie que toutes les données du fichier sont cryptées. Pour un répertoire, cette situation signifie que le cryptage est la valeur par défaut pour les fichiers et sous-répertoires nouvellement créés. Ce drapeau n'a aucun effet si FILE_ATTRIBUTE_SYSTEM est également spécifié. Ce drapeau n'est pas pris en charge sur les éditions Home, Home Premium, Starter ou ARM de Windows.
	FILE_ATTRIBUTE_HIDDEN	0x2	Cette constante permet d'indiquer que le fichier est caché. Ne l'incluez pas dans une liste de répertoire ordinaire.
	FILE_ATTRIBUTE_NORMAL	0x80	Cette constante permet d'indiquer que le fichier n'a pas d'autres attributs définis. Cet attribut n'est valide que s'il est utilisé seul.
	FILE_ATTRIBUTE_OFFLINE	0x1000	Cette constante permet d'indiquer que les données d'un fichier ne sont pas immédiatement disponibles. Cet attribut indique que les données du fichier sont physiquement déplacées vers un entreposage hors connexion. Cet attribut est utilisé par entreposage à distance (Remote Storage), le logiciel de gestion d'entreposage hiérarchique. Les applications ne doivent pas modifier arbitrairement cet attribut.
	FILE_ATTRIBUTE_READONLY	0x1	Cette constante permet d'indiquer que le fichier est en lecture seulement. Les applications peuvent lire le fichier, mais ne peuvent ni l'écrire ni le supprimer.
	FILE_ATTRIBUTE_SYSTEM	0x4	Cette constante permet d'indiquer que le fichier fait partie du système d'exploitation ou est utilisé exclusivement par un système d'exploitation.
	FILE_ATTRIBUTE_TEMPORARY	0x100	Cette constante permet d'indiquer que le fichier est utilisé pour l'entreposage temporaire.
	FILE_FLAG_BACKUP_SEMANTICS	0x02000000	Cette constante permet d'indiquer que le fichier est en cours d'ouverture ou de création pour une opération de sauvegarde ou de restauration. Le système s'assure que le processus appelant annule les contrôles de sécurité des fichiers lorsqu'il dispose des privilèges SE_BACKUP_NAME et SE_RESTORE_NAME. Vous devez définir ce drapeau pour obtenir un descripteur dans un répertoire. Un descripteur de répertoire peut être transmis à certaines fonctions au lieu d'un descripteur de fichier.
	FILE_FLAG_DELETE_ON_CLOSE	0x04000000	Cette constante permet d'indiquer que le fichier doit être supprimé immédiatement après la fermeture de tous ses descripteurs, cette situation inclut le descripteur spécifié et tous les autres descripteurs 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 ultérieures du fichier échouent, sauf si le mode de partage FILE_SHARE_DELETE est spécifié.
	FILE_FLAG_NO_BUFFERING	0x20000000	Cette constante permet d'indiquer que le fichier ou le périphérique est en cours d'ouverture sans mise en cache système pour la lecture et l'écriture de données. Ce drapeau n'affecte pas la mise en cache du disque dur ni les fichiers cartographiés en mémoire. Il existe des conditions strictes pour travailler avec des fichiers ouverts avec CreateFileA à l'aide du drapeau FILE_FLAG_NO_BUFFERING.
	FILE_FLAG_OPEN_NO_RECALL	0x00100000	Cette constante permet d'indiquer que les données du fichier sont demandées, mais elles devraient continuer à se trouver dans l'entreposage à distance. Il ne doit pas être ramené dans un lieu d'entreposage local. Ce drapeau est destiné aux systèmes d'entreposage à distance.
	FILE_FLAG_OPEN_REPARSE_POINT	0x00200000	Cette constante permet d'indiquer que le traitement normal des points d'analyse ne se produira pas; la fonction CreateFileA va tenter d'ouvrir le point d'analyse. Lorsqu'un fichier est ouvert, un descripteur de fichier est renvoyé, que le filtre contrôlant le point d'analyse soit opérationnel ou non. Ce drapeau ne peut pas être utilisé avec le drapeau CREATE_ALWAYS. Si le fichier n'est pas un point d'analyse, ce drapeau est ignoré.
	FILE_FLAG_OVERLAPPED	0x40000000	Cette constante permet d'indiquer que le fichier ou le périphérique est en cours d'ouverture ou de création pour les entrée/sorties désynchronisés. Lorsque les opérations d'entrée/sortie suivantes sont terminées sur ce descripteur, l'événement spécifié dans la structure OVERLAPPED sera défini sur l'état signalé. Si ce drapeau est spécifié, le fichier peut être utilisé pour des opérations de lecture et d'écriture simultanées. Si ce drapeau n'est pas spécifié, alors les opérations d'entrée/sortie sont sérialisées, même si les appels aux fonctions de lecture et d'écriture spécifient une structure OVERLAPPED.
	FILE_FLAG_POSIX_SEMANTICS	0x0100000	Cette constante permet d'indiquer que l'accès se fera conformément aux règles POSIX. Cette situation inclut l'autorisation de plusieurs fichiers avec des noms, ne différant que par le cas, pour les systèmes de fichiers prenant en charge cette dénomination. Faites attention lorsque vous utilisez ce drapeau, car les fichiers créés avec ce drapeau peuvent ne pas être accessibles par les applications écrites pour le système d'exploitation MS-DOS ou les environnements Windows 16 bits.
	FILE_FLAG_RANDOM_ACCESS	0x10000000	Cette constante permet d'indiquer que l'accès est destiné à être aléatoire. Le système peut utiliser cette information pour optimiser la mise en cache des fichiers. Ce drapeau n'a aucun effet si le système de fichiers ne prend pas en charge les entrées/sorties en cache et FILE_FLAG_NO_BUFFERING.
	FILE_FLAG_SESSION_AWARE	0x00800000	Cette constante permet d'indiquer que le fichier ou le périphérique est en cours d'ouverture avec la reconnaissance de session. Si ce drapeau n'est pas spécifié, les processus par session (tels que ceux utilisant la redirection USB RemoteFX) ne peuvent pas être ouverts par les processus en cours d'exécution dans la session 0. Cet indicateur n'a aucun effet pour les appelants n'étant pas en session 0. Ce drapeau n'est pris en charge que par les éditions serveur de Windows. De plus, ce drapeau n'est pas pris en charge avant Windows Server 2012.
	FILE_FLAG_SEQUENTIAL_SCAN	0x08000000	Cette constante permet d'indiquer que l'accès est conçu pour être séquentiel du début à la fin. Le système peut utiliser cette information pour optimiser la mise en cache des fichiers. Ce drapeau ne doit pas être utilisé si une lecture en aval (c'est-à-dire des analyses inversées) sera utilisée. Ce drapeau n'a aucun effet si le système de fichiers ne prend pas en charge les entrées/sorties en cache et FILE_FLAG_NO_BUFFERING.
	FILE_FLAG_WRITE_THROUGH	0x80000000	Cette constante permet d'indiquer que les opérations d'écriture ne passeront pas par un cache intermédiaire, elles iront directement sur le disque.
	Le paramètre dwFlagsAndAttributes peut également spécifier des informations SQOS. Lorsque l'application appelante spécifie l'indicateur SECURITY_SQOS_PRESENT dans le cadre de dwFlagsAndAttributes, elle peut également contenir une ou plusieurs des valeurs suivantes :
	SECURITY_ANONYMOUS		Cette constante permet d'indiquer qu'il faut emprunter l'identité d'un client au niveau de l'emprunte d'identité anonyme.
	SECURITY_CONTEXT_TRACKING		Cette constante permet d'indiquer que le mode de suivi de sécurité est dynamique. Si ce drapeau n'est pas spécifié, le mode de suivi de la sécurité est statique.
	SECURITY_DELEGATION		Cette constante permet d'indiquer que l'emprunte d'identité d'un client est au niveau de l'emprunte d'identité de délégation.
	SECURITY_EFFECTIVE_ONLY		Cette constante permet d'indiquer que seuls les aspects activés du contexte de sécurité du client sont disponibles pour le serveur. Si vous ne spécifiez pas ce drapeau, tous les aspects du contexte de sécurité du client sont disponibles. Cette situation permet au client de limiter les groupes et privilèges qu'un serveur peut utiliser lors de l'emprunt d'identité du client.
	SECURITY_IDENTIFICATION		Cette constante permet d'indiquer que l'emprunte d'identité d'un client est au niveau de l'emprunt d'identité pour l'identification.
	SECURITY_IMPERSONATION		Cette constante permet d'indiquer que l'emprunte d'identité d'un client est au niveau de l'emprunt d'identité. C'est le comportement par défaut si aucun autre drapeau n'est spécifié avec le drapeau SECURITY_SQOS_PRESENT.
hTemplateFile	Ce paramètre permet d'indiquer un descripteur valide dans un fichier de modèle avec le droit d'accès GENERIC_READ. Le fichier de modèle fournit les attributs de fichier et les attributs étendus pour le fichier en cours de création. Ce paramètre peut être NULL. Lors de l'ouverture d'un fichier existant, la fonction CreateFileA ignore ce paramètre. Lors de l'ouverture d'un nouveau fichier crypté, le fichier hérite de la liste de contrôle d'accès discrétionnaire de son répertoire parent.

Retour

Valeur	Description
INVALID_HANDLE_VALUE	Cette valeur permet d'indiquer que la fonction a échoué. Pour obtenir des informations d'erreur étendues, appelez la fonction GetLastError.
INVALID_HANDLE_VALUE !=	Ces valeurs permettent d'indiquer que l'opération a réussi, et la valeur de retour est un descripteur ouvert du fichier, du périphérique, du canal nommé ou de l'emplacement de courrier spécifié.

Description

Cette fonction permet d'effectuer la création ou l'ouverture d'un fichier ou d'un périphérique d'entrée/sortie. Les périphériques d'entrée/sorties 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 magnétique, ressource de communication, emplacement de courrier et canal. La fonction renvoie un descripteur pouvant être utilisé pour accéder au fichier ou au périphérique pour différents types d'entrée/sortie, en fonction du fichier ou du périphérique et des drapeaux et attributs spécifiés.

Remarques

La fonction CreateFileA a été développé à l'origine spécifiquement pour l'interaction de fichiers, mais a depuis été développé et amélioré pour inclure la plupart des autres types de périphériques et mécanismes d'entrée/sortie disponibles pour les développeurs Windows.
Lorsqu'une application a fini d'utiliser le descripteur d'objet renvoyé par la fonction CreateFileA, utilisez la fonction CloseHandle pour fermer le descripteur. Cette situation libère non seulement des ressources système, mais peut également avoir une influence plus large sur le partage du fichier ou du périphérique et la validation des données sur le disque.
Windows Server 2003 et Windows XP : Une violation de partage se produit si vous tentez d'ouvrir un fichier ou un répertoire pour le supprimer sur un ordinateur à distance lorsque la valeur du paramètre dwDesiredAccess est le drapeau d'accès DELETE (0x00010000) ou avec tout autre drapeau d'accès et que le fichier ou le répertoire à distance n'a pas été ouvert avec FILE_SHARE_DELETE. Pour éviter la violation de partage dans ce scénario, ouvrez le fichier ou le répertoire à distance avec uniquement le droit d'accès DELETE, ou appelez DeleteFileA sans ouvrir le fichier ou le répertoire à la suppression.
Certains systèmes de fichiers, tels que le système de fichiers NTFS, prennent en charge la compression ou le cryptage pour des fichiers et des répertoires individuels. Sur les volumes dotés d'un système de fichiers monté avec cette prise en charge, un nouveau fichier hérite des attributs de compression et de cryptage de son répertoire.
Vous ne pouvez pas utiliser la fonction CreateFileA pour contrôler la compression, la décompression ou le déchiffrement d'un fichier ou d'un répertoire.
Windows Server 2003 et Windows XP : par souci de compatibilité ascendante, la fonction CreateFileA n'applique pas de règles d'héritage lorsque vous spécifiez un descripteur de sécurité dans lpSecurityAttributes. Pour prendre en charge l'héritage, les fonctions interrogeant ultérieurement le descripteur de sécurité de ce fichier peuvent déterminer et signaler de manière heuristique que l'héritage est en vigueur.
Comme indiqué précédemment, si le paramètre lpSecurityAttributes est NULL, le descripteur renvoyé par la fonction CreateFileA ne peut pas être hérité par aucun processus enfant créé par votre application. Les informations suivantes concernant ce paramètre s'appliquent également : Si la variable membre bInheritHandle n'est pas FALSE, c'est-à-dire une valeur différente de zéro, le descripteur peut être hérité. Par conséquent, il est essentiel que ce membre de structure soit correctement initialisé à FALSE si vous ne souhaitez pas que le descripteur 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é des fichiers et des répertoires pour que le membre lpSecurityDescriptor puisse les affecter, cette situation peut être déterminé à l'aide de la fonction GetVolumeInformationA.
La fonction CreateFileA avec disposition de remplacement échouera s'il est exécuté sur un fichier contenant déjà un autre flux de données ouvert.
A partir de Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes :

Technologie	Supporté
Protocole SMB (Server Message Block) version 3.0	Oui
TFO (SMB 3.0 Transparent Failover)	Selon certaines conditions
SMB 3.0 avec SO (Scale-out File Share)	Selon certaines conditions
CsvFS (Cluster Shared Volume File System)	Oui
ReFS (Resilient File System)	Oui

Pour effectuer cette opération en tant qu'opération transactionnelle, ce qui permet de créer un descripteur utilisable pour les entrées/sorties transactées, utilisez la fonction CreateFileTransacted.

Voir également

Articles - Les géants de l'informatique - Microsoft

Dernière mise à jour : Dimanche, le 6 décembre 2015

Section courante

A propos

Section administrative du site

CreateFileA