Функция CreateFileMappingFromApp (memoryapi.h)

Статья
08/24/2023

Создает или открывает именованный или неименованный объект сопоставления файлов для указанного файла из приложения Магазина Windows.

Синтаксис

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

Параметры

[in] hFile

Дескриптор файла, из которого создается объект сопоставления файлов.

Файл должен быть открыт с правами доступа, совместимыми с флагами защиты, указанными параметром flProtect . Это не обязательно, но рекомендуется открывать файлы, которые планируется сопоставить, для монопольного доступа. Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

Если hFileINVALID_HANDLE_VALUE, вызывающий процесс должен также указать размер объекта сопоставления файлов в параметрах dwMaximumSizeHigh и dwMaximumSizeLow . В этом сценарии CreateFileMappingFromApp создает объект сопоставления файлов указанного размера, который поддерживается системным файлом подкачки, а не файлом в файловой системе.

[in, optional] SecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Член lpSecurityDescriptor структуры SECURITY_ATTRIBUTES задает дескриптор безопасности для нового объекта сопоставления файлов.

Если securityAttributes имеет значение NULL, дескриптор не может быть унаследован, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов поступают из основного маркера или маркера олицетворения создателя. Дополнительные сведения см. в разделе Безопасность сопоставления файлов и права доступа.

[in] PageProtection

Задает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.

Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
PAGE_READONLY 0x02	Позволяет сопоставлять представления для доступа только для чтения или копирования при записи. Попытка записи в определенный регион приводит к нарушению доступа. Дескриптор файла, который указывает параметр hFile , должен быть создан с правом доступа GENERIC_READ .
PAGE_READWRITE 0x04	Позволяет сопоставлять представления для доступа только для чтения, копирования при записи или для чтения и записи. Дескриптор файла, который указывает параметр hFile , должен быть создан с правами доступа GENERIC_READ и GENERIC_WRITE .
PAGE_WRITECOPY 0x08	Позволяет сопоставлять представления для доступа только для чтения или копирования при записи. Это значение эквивалентно PAGE_READONLY. Дескриптор файла, который указывает параметр hFile , должен быть создан с правом доступа GENERIC_READ .

Приложение может указать один или несколько следующих атрибутов для объекта сопоставления файлов, объединяя их с одним из предыдущих значений защиты страниц.

Значение	Значение
SEC_COMMIT 0x8000000	Если объект сопоставления файлов поддерживается файлом подкачки операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла с адресным пространством процесса весь диапазон страниц фиксируется, а не резервируется. Система должна иметь достаточно зафиксируемых страниц для хранения всего сопоставления. В противном случае createFileMappingFromApp завершается сбоем. Этот атрибут не влияет на объекты сопоставления файлов, которые поддерживаются исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_COMMIT нельзя сочетать с SEC_RESERVE. Если атрибут не указан, предполагается SEC_COMMIT .
SEC_IMAGE_NO_EXECUTE 0x11000000	Указывает, что файл, который указывает параметр hFile , является исполняемым файлом образа, который не будет выполняться, а загруженный файл образа не будет выполняться принудительной проверки целостности. Кроме того, сопоставление представления объекта сопоставления файлов, созданного с помощью атрибута SEC_IMAGE_NO_EXECUTE , не будет вызывать обратные вызовы драйвера, зарегистрированные с помощью API ядра PsSetLoadImageNotifyRoutine . Атрибут SEC_IMAGE_NO_EXECUTE должен быть объединён со значением защиты страницы PAGE_READONLY . Никакие другие атрибуты не являются допустимыми для SEC_IMAGE_NO_EXECUTE.
SEC_LARGE_PAGES 0x80000000	Позволяет использовать большие страницы для объектов сопоставления файлов, которые поддерживаются файлом подкачки операционной системы (параметр hfileINVALID_HANDLE_VALUE). Этот атрибут не поддерживается для объектов сопоставления файлов, которые поддерживаются исполняемыми файлами изображений или файлами данных (параметр hFile — это дескриптор исполняемого изображения или файла данных). Максимальный размер объекта сопоставления файлов должен быть кратным минимальному размеру большой страницы, возвращаемой функцией GetLargePageMinimum . Если это не так, createFileMappingFromApp завершается ошибкой . При сопоставлении представления объекта сопоставления файлов, созданного с помощью SEC_LARGE_PAGES, базовый адрес и размер представления также должны быть кратными минимальному большому размеру страницы. SEC_LARGE_PAGES требует, чтобы в токене вызывающего объекта была включена привилегия SeLockMemoryPrivilege . Если указан SEC_LARGE_PAGES , необходимо также указать SEC_COMMIT .
SEC_NOCACHE 0x10000000	Задает все страницы, которые не кэшируются. Приложения не должны использовать этот атрибут, за исключением случаев, когда это явно необходимо для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_NOCACHE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_NOCACHE требуется задать атрибут SEC_RESERVE или SEC_COMMIT .
SEC_RESERVE 0x4000000	Если объект сопоставления файлов поддерживается файлом подкачки операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла с адресным пространством процесса весь диапазон страниц резервируется для последующего использования процессом, а не фиксируется. Зарезервированные страницы можно зафиксировать при последующих вызовах функции VirtualAlloc . После фиксации страницы они не могут быть освобождены или выведены из эксплуатации с помощью функции VirtualFree . Этот атрибут не влияет на объекты сопоставления файлов, которые поддерживаются исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_RESERVE нельзя сочетать с SEC_COMMIT.
SEC_WRITECOMBINE 0x40000000	Задает все страницы для объединения записей. Приложения не должны использовать этот атрибут, за исключением случаев, когда это явно необходимо для устройства. Использование взаимосвязанных функций с памятью, сопоставленной с SEC_WRITECOMBINE , может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_WRITECOMBINE требуется задать атрибут SEC_RESERVE или SEC_COMMIT .

[in] MaximumSize

Максимальный размер объекта сопоставления файлов.

Попытка сопоставить файл длиной 0 (ноль) завершается с ошибкой с кодом ERROR_FILE_INVALID. Приложения должны тестировать файлы длиной 0 (ноль) и отклонять эти файлы.

[in, optional] Name

Имя объекта сопоставления файлов.

Если этот параметр соответствует имени существующего объекта сопоставления, функция запрашивает доступ к объекту с защитой, указанной flProtect .

Если этот параметр имеет значение NULL, объект сопоставления файлов создается без имени.

Если lpName соответствует имени существующего события, семафора, мьютекса, таймера ожидания или объекта задания, функция завершается ошибкой, а функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит потому, что эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нулевого сеанса, требуется привилегия SeCreateGlobalPrivilege . Дополнительные сведения см. в разделе Пространства имен объектов ядра.

Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, изложенным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для созданного объекта сопоставления файлов.

Если объект существует до вызова функции, функция возвращает дескриптор существующему объекту (с его текущим размером, а не указанным размером), а GetLastError возвращает ERROR_ALREADY_EXISTS.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

После создания объекта сопоставления файлов размер файла не должен превышать размер объекта сопоставления файлов; Если это так, не все содержимое файла доступно для совместного использования.

Если приложение указывает размер объекта сопоставления файлов, который больше размера фактического именованного файла на диске и если защита страницы разрешает доступ на запись (то есть параметр flProtect указывает PAGE_READWRITE), файл на диске увеличивается в соответствии с указанным размером объекта сопоставления файлов. Если файл расширен, содержимое файла между старым и новым концами файла не гарантируется равным нулю; поведение определяется файловой системой. Если невозможно увеличить файл на диске, createFileMappingFromApp завершается сбоем и GetLastError возвращает ERROR_DISK_FULL.

Начальное содержимое страниц в объекте сопоставления файлов, поддерживаемом файлом подкачки операционной системы, равно 0 (ноль).

Дескриптор, возвращаемый CreateFileMappingFromApp , имеет полный доступ к новому объекту сопоставления файлов и может использоваться с любой функцией, требующей дескриптора для объекта сопоставления файлов.

Несколько процессов могут совместно использовать представление одного файла, используя один общий объект сопоставления файлов или создавая отдельные объекты сопоставления файлов, поддерживаемые одним и тем же файлом. Один объект сопоставления файлов может быть совместно использоваться несколькими процессами путем наследования дескриптора при создании процесса, дублирования дескриптора или открытия объекта сопоставления файлов по имени. Дополнительные сведения см. в разделе Функции CreateProcess, DuplicateHandle и OpenFileMapping .

Создание объекта сопоставления файлов фактически не сопоставляет представление с адресным пространством процесса. Функция MapViewOfFileEx сопоставляет представление файла с адресным пространством процесса.

За одним важным исключением, представления файлов, производные от любого объекта сопоставления файлов, который поддерживается одним и тем же файлом, являются согласованными или идентичными в определенный момент времени. Когерентность гарантируется для представлений в рамках процесса и представлений, сопоставленных различными процессами.

Исключение связано с удаленными файлами. Несмотря на то, что CreateFileMappingFromApp работает с удаленными файлами, они не согласованы. Например, если два компьютера сопоставляют файл как доступный для записи и изменяют одну и ту же страницу, каждый компьютер видит только собственные записи на страницу. При обновлении данных на диске они не объединяются.

Сопоставленный файл и файл, к которому осуществляется доступ с помощью функций ввода-вывода (ReadFile и WriteFile), не обязательно являются согласованными.

Сопоставленные представления объекта сопоставления файлов поддерживают внутренние ссылки на объект, и объект сопоставления файлов не закрывается до тех пор, пока не будут освобождены все ссылки на него. Поэтому, чтобы полностью закрыть объект сопоставления файлов, приложение должно отменить сопоставление всех сопоставленных представлений объекта сопоставления файлов путем вызова UnmapViewOfFile и закрыть дескриптор объекта сопоставления файлов путем вызова CloseHandle. Эти функции можно вызывать в любом порядке.

При изменении файла с помощью сопоставленного представления метка времени последнего изменения может не обновляться автоматически. При необходимости вызывающий объект должен использовать SetFileTime для установки метки времени.

Используйте структурированную обработку исключений для защиты любого кода, который записывает или считывает из представления файлов. Дополнительные сведения см. в статье Чтение и запись из представления файлов.

Вы можете успешно запросить защиту исполняемого файла, только если ваше приложение имеет возможность codeGeneration .

Требования


Минимальная версия клиента	Windows 8 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	memoryapi.h (включая Windows.h)
Библиотека	onecore.lib
DLL	Kernel32.dll