CreateFileMappingFromApp, fonction (memoryapi.h)

Article
08/24/2023

Crée ou ouvre un objet de mappage de fichiers nommé ou non nommé pour un fichier spécifié à partir d’une application du Windows Store.

Syntaxe

HANDLE CreateFileMappingFromApp(
  [in]           HANDLE               hFile,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in]           ULONG                PageProtection,
  [in]           ULONG64              MaximumSize,
  [in, optional] PCWSTR               Name
);

Paramètres

[in] hFile

Handle du fichier à partir duquel créer un objet de mappage de fichiers.

Le fichier doit être ouvert avec des droits d’accès compatibles avec les indicateurs de protection spécifiés par le paramètre flProtect . Il n’est pas obligatoire, mais il est recommandé d’ouvrir les fichiers que vous envisagez de mapper pour un accès exclusif. Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

Si hFile est INVALID_HANDLE_VALUE, le processus appelant doit également spécifier une taille pour l’objet de mappage de fichiers dans les paramètres dwMaximumSizeHigh et dwMaximumSizeLow . Dans ce scénario, CreateFileMappingFromApp crée un objet de mappage de fichiers d’une taille spécifiée qui est sauvegardé par le fichier de pagination système au lieu d’un fichier dans le système de fichiers.

[in, optional] SecurityAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui détermine si un handle retourné peut être hérité par des processus enfants. Le membre lpSecurityDescriptor de la structure SECURITY_ATTRIBUTES spécifie un descripteur de sécurité pour un nouvel objet de mappage de fichiers.

Si SecurityAttributes a la valeur NULL, le handle ne peut pas être hérité et l’objet de mappage de fichiers obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès (ACL) dans le descripteur de sécurité par défaut pour un objet de mappage de fichiers proviennent du jeton principal ou d’emprunt d’identité du créateur. Pour plus d’informations, consultez Sécurité et droits d’accès du mappage de fichiers.

[in] PageProtection

Spécifie la protection de page de l’objet de mappage de fichiers. Toutes les vues mappées de l’objet doivent être compatibles avec cette protection.

Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
PAGE_READONLY 0x02	Permet de mapper des vues pour l’accès en lecture seule ou en copie sur écriture. Une tentative d’écriture dans une région spécifique entraîne une violation d’accès. Le handle de fichier spécifié par le paramètre hFile doit être créé avec le droit d’accès GENERIC_READ .
PAGE_READWRITE 0x04	Permet de mapper des vues pour l’accès en lecture seule, à la copie en écriture ou en lecture/écriture. Le handle de fichier spécifié par le paramètre hFile doit être créé avec les droits d’accès GENERIC_READ et GENERIC_WRITE .
PAGE_WRITECOPY 0x08	Permet de mapper des vues pour l’accès en lecture seule ou en copie sur écriture. Cette valeur équivaut à PAGE_READONLY. Le handle de fichier spécifié par le paramètre hFile doit être créé avec le droit d’accès GENERIC_READ .

Une application peut spécifier un ou plusieurs des attributs suivants pour l’objet de mappage de fichiers en les combinant avec l’une des valeurs de protection de page précédentes.

Valeur	Signification
SEC_COMMIT 0x8000000	Si l’objet de mappage de fichiers est sauvegardé par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE), spécifie que lorsqu’une vue du fichier est mappée dans un espace d’adressage de processus, toute la plage de pages est validée plutôt que réservée. Le système doit avoir suffisamment de pages pouvant être engagées pour contenir l’intégralité du mappage. Sinon, CreateFileMappingFromApp échoue. Cet attribut n’a aucun effet pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hfile est un handle vers un fichier). SEC_COMMIT ne peut pas être combiné avec SEC_RESERVE. Si aucun attribut n’est spécifié, SEC_COMMIT est supposé.
SEC_IMAGE_NO_EXECUTE 0x11000000	Spécifie que le fichier spécifié par le paramètre hFile est un fichier image exécutable qui ne sera pas exécuté et que le fichier image chargé n’aura aucune vérification d’intégrité forcée exécutée. En outre, le mappage d’une vue d’un objet de mappage de fichiers créé avec l’attribut SEC_IMAGE_NO_EXECUTE n’appelle pas les rappels de pilotes inscrits à l’aide de l’API du noyau PsSetLoadImageNotifyRoutine . L’attribut SEC_IMAGE_NO_EXECUTE doit être combiné avec la valeur de protection de page PAGE_READONLY. Aucun autre attribut n’est valide avec SEC_IMAGE_NO_EXECUTE.
SEC_LARGE_PAGES 0x80000000	Permet d’utiliser des pages volumineuses pour les objets de mappage de fichiers qui sont sauvegardés par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE). Cet attribut n’est pas pris en charge pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hFile est un handle vers une image exécutable ou un fichier de données). La taille maximale de l’objet de mappage de fichiers doit être un multiple de la taille minimale d’une grande page retournée par la fonction GetLargePageMinimum . Si ce n’est pas le cas, CreateFileMappingFromApp échoue. Lors du mappage d’une vue d’un objet de mappage de fichiers créé avec SEC_LARGE_PAGES, l’adresse de base et la taille d’affichage doivent également être des multiples de la taille minimale de la grande page. SEC_LARGE_PAGES nécessite l’activation du privilège SeLockMemoryPrivilege dans le jeton de l’appelant. Si SEC_LARGE_PAGES est spécifié, SEC_COMMIT doit également être spécifié.
SEC_NOCACHE 0x10000000	Définit toutes les pages pour qu’elles ne soient pas mises en cache. Les applications ne doivent pas utiliser cet attribut, sauf en cas d’obligation explicite pour un appareil. L’utilisation des fonctions verrouillées avec la mémoire mappée avec SEC_NOCACHE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION . SEC_NOCACHE nécessite la définition de l’attribut SEC_RESERVE ou SEC_COMMIT .
SEC_RESERVE 0x4000000	Si l’objet de mappage de fichiers est sauvegardé par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE), spécifie que lorsqu’une vue du fichier est mappée dans un espace d’adressage de processus, toute la plage de pages est réservée pour une utilisation ultérieure par le processus plutôt que validée. Les pages réservées peuvent être validées dans les appels suivants à la fonction VirtualAlloc . Une fois les pages validées, elles ne peuvent pas être libérées ou libérées avec la fonction VirtualFree . Cet attribut n’a aucun effet pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hfile est un handle vers un fichier). SEC_RESERVE ne peut pas être combiné avec SEC_COMMIT.
SEC_WRITECOMBINE 0x40000000	Définit toutes les pages à combiner en écriture. Les applications ne doivent pas utiliser cet attribut, sauf en cas d’obligation explicite pour un appareil. L’utilisation des fonctions verrouillées avec la mémoire mappée avec SEC_WRITECOMBINE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION . SEC_WRITECOMBINE nécessite la définition de l’attribut SEC_RESERVE ou SEC_COMMIT .

[in] MaximumSize

Taille maximale de l’objet de mappage de fichiers.

Une tentative de mappage d’un fichier d’une longueur de 0 (zéro) échoue avec un code d’erreur de ERROR_FILE_INVALID. Les applications doivent tester les fichiers d’une longueur égale à 0 (zéro) et rejeter ces fichiers.

[in, optional] Name

Nom de l’objet de mappage de fichiers.

Si ce paramètre correspond au nom d’un objet de mappage existant, la fonction demande l’accès à l’objet avec la protection spécifiée par flProtect .

Si ce paramètre a la valeur NULL, l’objet de mappage de fichiers est créé sans nom.

Si lpName correspond au nom d’un événement, sémaphore, mutex, minuteur d’attente ou objet de travail existant, la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.

Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception du caractère barre oblique inverse (\). La création d’un objet de mappage de fichiers dans l’espace de noms global à partir d’une session autre que la session zéro nécessite le privilège SeCreateGlobalPrivilege . Pour plus d’informations, consultez Espaces de noms d’objets de noyau.

Le changement rapide d’utilisateur est implémenté à l’aide de sessions Terminal Services. Le premier utilisateur à se connecter utilise la session 0 (zéro), l’utilisateur suivant à ouvrir une session utilise la session 1 (1), et ainsi de suite. Les noms d’objets de noyau doivent suivre les instructions décrites pour Les services Terminal Server afin que les applications puissent prendre en charge plusieurs utilisateurs.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle de l’objet de mappage de fichiers nouvellement créé.

Si l’objet existe avant l’appel de fonction, la fonction retourne un handle à l’objet existant (avec sa taille actuelle, et non la taille spécifiée), et GetLastError retourne ERROR_ALREADY_EXISTS.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Une fois qu’un objet de mappage de fichiers est créé, la taille du fichier ne doit pas dépasser la taille de l’objet de mappage de fichier ; si c’est le cas, tout le contenu du fichier n’est pas disponible pour le partage.

Si une application spécifie une taille pour l’objet de mappage de fichiers supérieure à la taille du fichier nommé réel sur le disque et si la protection de page autorise l’accès en écriture (autrement dit, le paramètre flProtect spécifie PAGE_READWRITE), le fichier sur le disque est augmenté pour correspondre à la taille spécifiée de l’objet de mappage de fichiers. Si le fichier est étendu, il n’est pas garanti que le contenu du fichier entre l’ancienne fin du fichier et la nouvelle fin du fichier soit égal à zéro . le comportement est défini par le système de fichiers. Si le fichier sur le disque ne peut pas être augmenté, CreateFileMappingFromApp échoue et GetLastError retourne ERROR_DISK_FULL.

Le contenu initial des pages d’un objet de mappage de fichiers soutenu par le fichier de pagination du système d’exploitation est 0 (zéro).

Le handle retourné par CreateFileMappingFromApp a un accès complet à un nouvel objet de mappage de fichiers et peut être utilisé avec n’importe quelle fonction qui nécessite un handle vers un objet de mappage de fichiers.

Plusieurs processus peuvent partager une vue du même fichier en utilisant un seul objet de mappage de fichiers partagés ou en créant des objets de mappage de fichiers distincts soutenus par le même fichier. Un seul objet de mappage de fichiers peut être partagé par plusieurs processus en héritant le handle lors de la création du processus, en dupliquant le handle ou en ouvrant l’objet de mappage de fichiers par son nom. Pour plus d’informations, consultez les fonctions CreateProcess, DuplicateHandle et OpenFileMapping .

La création d’un objet de mappage de fichiers ne mappe pas réellement la vue dans un espace d’adressage de processus. La fonction MapViewOfFileEx mappe une vue d’un fichier dans un espace d’adressage de processus.

À une exception importante, les vues de fichiers dérivées de n’importe quel objet de mappage de fichiers qui est adossé au même fichier sont cohérentes ou identiques à un moment spécifique. La cohérence est garantie pour les vues au sein d’un processus et pour les vues qui sont mappées par différents processus.

L’exception est liée aux fichiers distants. Bien que CreateFileMappingFromApp fonctionne avec des fichiers distants, il ne les maintient pas cohérents. Par exemple, si deux ordinateurs mappent un fichier en tant que fichier accessible en écriture et modifient tous les deux la même page, chaque ordinateur ne voit que ses propres écritures dans la page. Lorsque les données sont mises à jour sur le disque, elles ne sont pas fusionnées.

Un fichier mappé et un fichier accessible à l’aide des fonctions d’entrée et de sortie (E/S) (ReadFile et WriteFile) ne sont pas nécessairement cohérents.

Les vues mappées d’un objet de mappage de fichiers conservent les références internes à l’objet, et un objet de mappage de fichiers ne se ferme pas tant que toutes les références à cet objet ne sont pas libérées. Par conséquent, pour fermer complètement un objet de mappage de fichiers, une application doit annuler le mappage de toutes les vues mappées de l’objet de mappage de fichiers en appelant UnmapViewOfFile et fermer le handle d’objet de mappage de fichiers en appelant CloseHandle. Ces fonctions peuvent être appelées dans n’importe quel ordre.

Lors de la modification d’un fichier via une vue mappée, l’horodatage de la dernière modification peut ne pas être mis à jour automatiquement. Si nécessaire, l’appelant doit utiliser SetFileTime pour définir l’horodatage.

Utilisez la gestion structurée des exceptions pour protéger tout code qui écrit ou lit à partir d’une vue de fichier. Pour plus d’informations, consultez Lecture et écriture à partir d’un affichage fichier.

Vous ne pouvez demander une protection exécutable que si votre application dispose de la fonctionnalité codeGeneration .

Spécifications


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	memoryapi.h (inclure Windows.h)
Bibliothèque	onecore.lib
DLL	Kernel32.dll