CreateFileFromAppW, fonction (fileapifromapp.h)
Crée ou ouvre un fichier ou un périphérique d’E/S. Le comportement de cette fonction est identique à CreateFile, sauf que cette fonction adhère au modèle de sécurité d’application plateforme Windows universelle.
Syntaxe
WINSTORAGEAPI HANDLE CreateFileFromAppW(
LPCWSTR lpFileName,
DWORD dwDesiredAccess,
DWORD dwShareMode,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDisposition,
DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile
) noexcept;
Paramètres
lpFileName
Nom du fichier ou de l’appareil à créer ou à ouvrir. Vous pouvez utiliser des barres obliques (/) ou des barres obliques inverses (\) dans ce nom.
Dans la version ANSI de cette fonction, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, appelez la version Unicode de la fonction et ajoutez « \ ?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.
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.
Pour la version unicode de cette fonction (CreateFileFromAppW), vous pouvez choisir de supprimer la limitation de MAX_PATH sans avoir à précédencer « \\ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .
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.
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.
| Valeur | Signification |
|---|---|
| 0 0x00000000 | Empêche d’autres processus d’ouvrir un fichier ou un appareil s’ils demandent la suppression, la lecture ou l’accès en écriture. |
| 0x00000004 FILE_SHARE_DELETE | Permet aux opérations d’ouverture suivantes sur un fichier ou un appareil de demander l’accès à la suppression. Sinon, d’autres processus ne peuvent pas ouvrir le fichier ou l’appareil s’ils demandent l’accès à la suppression. Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès de suppression, la fonction échoue. Note Supprimer l’accès autorise les opérations de suppression et de renommage. |
| 0x00000001 FILE_SHARE_READ | Permet aux opérations d’ouverture suivantes sur un fichier ou un appareil de demander l’accès en lecture. Sinon, d’autres processus ne peuvent pas ouvrir le fichier ou l’appareil s’ils demandent l’accès en lecture. Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès en lecture, la fonction échoue. |
| FILE_SHARE_WRITE 0x00000002 | Permet aux opérations d’ouverture suivantes sur un fichier ou un appareil de demander l’accès en écriture. Sinon, d’autres processus ne peuvent pas ouvrir le fichier ou l’appareil s’ils demandent l’accès en écriture. Si cet indicateur n’est pas spécifié, mais que le fichier ou l’appareil a été ouvert pour l’accès en écriture ou a un mappage de fichiers avec accès en écriture, la fonction échoue. |
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 les processus enfants.
Ce paramètre peut être NULL.
Si ce paramètre a la valeur NULL, le handle retourné 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 affecté au fichier ou à l’appareil associé au descripteur de sécurité retourné.
Cette fonction 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é.
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 :
| Valeur | Signification |
|---|---|
| CREATE_ALWAYS 2 | Crée un fichier, toujours. Si le fichier spécifié existe et est accessible en écriture, la fonction le tronque, la fonction réussit et le code de 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 zéro. Pour plus d’informations, consultez la section Remarques de cette rubrique. |
| CREATE_NEW 1 | Crée un fichier, uniquement s’il n’existe pas déjà. Si le fichier spécifié existe, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_EXISTS (80). Si le fichier spécifié n’existe pas et qu’il s’agit d’un chemin d’accès valide à un emplacement accessible en écriture, un nouveau fichier est créé. |
| OPEN_ALWAYS 4 | Ouvre un fichier, toujours. Si le fichier spécifié existe, la fonction réussit et le code de 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 emplacement accessible en écriture, la fonction crée un fichier et le code de la dernière erreur est défini sur zéro. |
| OPEN_EXISTING 3 | Ouvre un fichier ou un appareil, uniquement s’il existe. Si le fichier ou l’appareil spécifié n’existe pas, la fonction échoue et le code de dernière erreur est défini sur ERROR_FILE_NOT_FOUND (2). Pour plus d’informations sur les appareils, consultez la section Remarques. |
| TRUNCATE_EXISTING 5 | Ouvre un fichier et le tronque pour que sa taille soit égale à zéro octet, uniquement s’il existe. Si le fichier spécifié n’existe pas, la fonction échoue et le code de la dernière 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 cadre du paramètre dwDesiredAccess . |
dwFlagsAndAttributes
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.
Ce paramètre peut également 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. Ils se combinent avec n’importe quelle valeur FILE_ATTRIBUTE_* .
Ce paramètre peut également contenir des informations SQOS (Security Quality of Service) en spécifiant l’indicateur SECURITY_SQOS_PRESENT . Des informations supplémentaires sur les indicateurs liés à SQOS sont présentées dans le tableau suivant les tables d’attributs et d’indicateurs.
| 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. |
| FILE_ATTRIBUTE_HIDDEN 2 (0x2) | Le fichier est masqué. Ne l’incluez pas dans une liste d’annuaires ordinaire. |
| 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. |
| 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. |
| 0x04000000 FILE_FLAG_DELETE_ON_CLOSE | 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 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 du fichier échouent, sauf si le mode de partage FILE_SHARE_DELETE est spécifié. |
| 0x20000000 FILE_FLAG_NO_BUFFERING | 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 à la mémoire. Il existe des exigences strictes pour utiliser correctement les fichiers ouverts avec cette fonction à l’aide de l’indicateur FILE_FLAG_NO_BUFFERING . Pour plus d’informations, consultez Mise en mémoire tampon de 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 renvoyé vers le stockage local. Cet indicateur est destiné aux systèmes de stockage distants. |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | Le traitement normal des points d’analyse ne se produira pas ; cette fonction 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_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 0x0100000 | 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. |
| 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 inversées) 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. |
| 0x80000000 FILE_FLAG_WRITE_THROUGH | 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. |
Le paramètre dwFlagsAndAttributespeut également spécifier des informations SQOS. Pour plus d’informations, consultez Niveaux d’emprunt d’identité. 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.
| 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é avec l’indicateur SECURITY_SQOS_PRESENT . |
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, ce paramètre est ignoré.
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.
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.
Configuration requise
| Client minimal pris en charge | Windows 10 version 1803 |
| En-tête | fileapifromapp.h |
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