CreateFile2FromAppW, fonction (fileapifromapp.h)

Crée ou ouvre un fichier ou un périphérique d’E/S. Le comportement de cette fonction est identique à CreateFile2, sauf que cette fonction adhère au modèle de sécurité d’application plateforme Windows universelle.

Syntaxe

WINSTORAGEAPI HANDLE CreateFile2FromAppW(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
) noexcept;

Paramètres

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.

Pour plus d’informations sur la désactivation de la limitation de MAX_PATH sans passer à la limite « \ ??\ », consultez la section « Limitation de longueur maximale du chemin d’accès » de l’article Nommage des fichiers, des chemins et des espaces de noms .

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.

Si ce paramètre est égal à zéro et que la fonction 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. Cette fonction échouerait et la fonction GetLastError retournerait 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.

Note Les options de partage pour chaque handle ouvert restent en vigueur jusqu’à ce que ce handle soit fermé, quel que soit le contexte du processus.

 

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. L’accès exclusif à un fichier ou à un répertoire n’est accordé que si l’application dispose d’un accès en écriture au fichier.
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. Si un fichier ou un répertoire est ouvert et que cet indicateur n’est pas spécifié et que l’appelant n’a pas accès en écriture au fichier ou au répertoire, 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.

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.

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.
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).
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 .

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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10 version 1803
En-tête	fileapifromapp.h