Функция CreateFileMappingFromApp (memoryapi.h)
Создает или открывает объект сопоставления именованных или неименованных файлов для указанного файла из приложения Магазина Windows.
Синтаксис
HANDLE CreateFileMappingFromApp(
[in] HANDLE hFile,
[in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
[in] ULONG PageProtection,
[in] ULONG64 MaximumSize,
[in, optional] PCWSTR Name
);
Параметры
[in] hFile
Дескриптор файла, из которого создается объект сопоставления файлов.
Файл должен быть открыт с правами доступа, совместимыми с флагами защиты , указанными параметром flProtect. Это не обязательно, но рекомендуется, чтобы файлы, которые планируется сопоставить для эксклюзивного доступа. Дополнительные сведения см. в права доступа и безопасности файлов.
Если hFile INVALID_HANDLE_VALUE, вызов должен также указать размер объекта сопоставления файлов в dwMaximumSizeHigh и параметры dwMaximumSizeLow dwMaximumSizeLow. В этом сценарии CreateFileMappingFromApp создает объект сопоставления файлов указанного размера, который поддерживается системным файлом на страницы вместо файла в файловой системе.
[in, optional] SecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент
Если SecurityAttributesNULL, дескриптор не может наследоваться, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов получены из первичного или олицетворения маркера создателя. Дополнительные сведения см. в "Безопасность и доступ к файлам".
[in] PageProtection
Указывает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.
Этот параметр может быть одним из следующих значений.
Приложение может указать один или несколько следующих атрибутов для объекта сопоставления файлов, объединив их с одним из предыдущих значений защиты страниц.
| Ценность | Значение |
|---|---|
|
Если объект сопоставления файлов поддерживается файлом разбиения по страницам операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла в адресное пространство процесса весь диапазон страниц фиксируется, а не зарезервирован. Система должна иметь достаточно зафиксируемых страниц для хранения всего сопоставления. В противном случае CreateFileMappingFromApp завершается ошибкой.
Этот атрибут не влияет на объекты сопоставления файлов, поддерживаемые исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_COMMIT нельзя объединить с SEC_RESERVE. Если атрибут не указан, SEC_COMMIT предполагается. |
|
Указывает, что файл, который указывает параметр hFile является исполняемым файлом образа, который не будет выполняться, а загруженный файл образа не будет иметь принудительной проверки целостности.
Кроме того, сопоставление представления объекта сопоставления файлов, созданного с помощью атрибута SEC_IMAGE_NO_EXECUTE, не будет вызывать обратные вызовы драйвера, зарегистрированные с помощью API ядра psSetLoadImageNotifyRoutine.
Атрибут SEC_IMAGE_NO_EXECUTE должен сочетаться со значением защиты страницы PAGE_READONLY. Никакие другие атрибуты не являются допустимыми с SEC_IMAGE_NO_EXECUTE. |
|
Позволяет использовать большие страницы для объектов сопоставления файлов, поддерживаемых файлом подкачки операционной системы (параметр hfile имеет значение INVALID_HANDLE_VALUE). Этот атрибут не поддерживается для объектов сопоставления файлов, поддерживаемых исполняемыми файлами изображений или файлами данных (параметр hFile является дескриптором исполняемого образа или файла данных).
Максимальный размер объекта сопоставления файлов должен иметь несколько минимальных размеров большой страницы, возвращаемой функцией GetLargePageMinimum. Если это не так, CreateFileMappingFromApp завершается ошибкой. При сопоставлении представления объекта сопоставления файлов, созданного с SEC_LARGE_PAGES, базовый адрес и размер представления также должны быть несколькими из минимального размера большой страницы. SEC_LARGE_PAGES требует, чтобы SeLockMemoryPrivilege привилегии были включены в маркере вызывающего объекта. Если указан SEC_LARGE_PAGES, необходимо также указать SEC_COMMIT. |
|
Задает все страницы, которые не кэшируются.
Приложения не должны использовать этот атрибут, за исключением случаев, когда явно требуется для устройства. Использование заблокированных функций с памятью, сопоставленной с SEC_NOCACHE, может привести к EXCEPTION_ILLEGAL_INSTRUCTION исключению. SEC_NOCACHE требует установки атрибута SEC_RESERVE или SEC_COMMIT. |
|
Если объект сопоставления файлов поддерживается файлом подкачки операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла в адресное пространство процесса весь диапазон страниц зарезервирован для последующего использования процессом, а не фиксации.
Зарезервированные страницы можно зафиксировать в последующих вызовах функции VirtualAlloc. После фиксации страниц они не могут быть освобождены или удалены с помощью функции VirtualFree. Этот атрибут не влияет на объекты сопоставления файлов, поддерживаемые исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_RESERVE нельзя сочетать с SEC_COMMIT. |
|
Задает все страницы для объединения записей.
Приложения не должны использовать этот атрибут, за исключением случаев, когда явно требуется для устройства. Использование заблокированных функций с памятью, сопоставленной с 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. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нуля сеанса, требуется
Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором созданного объекта сопоставления файлов.
Если объект существует перед вызовом функции, функция возвращает дескриптор существующему объекту (с текущим размером, а не указанным размером), а GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
После создания объекта сопоставления файлов размер файла не должен превышать размер объекта сопоставления файлов; Если это так, для общего доступа доступны не все содержимое файла.
Если приложение задает размер объекта сопоставления файлов, превышающего размер фактического именованного файла на диске, и если защита страницы разрешает доступ на запись (то есть параметр flProtect указывает PAGE_READWRITE), то файл на диске увеличивается, чтобы соответствовать указанному размеру объекта сопоставления файлов. Если файл расширен, содержимое файла между старым концем файла и новым концем файла не гарантируется нулевой. Поведение определяется файловой системой. Если файл на диске нельзя увеличить, CreateFileMappingFromApp завершается ошибкой, и GetLastError возвращает ERROR_DISK_FULL.
Начальное содержимое страниц в объекте сопоставления файлов, поддерживаемом файлом подкачки операционной системы, равно 0 (ноль).
Дескриптор, который CreateFileMappingFromApp возвращает полный доступ к новому объекту сопоставления файлов и может использоваться с любой функцией, требующей дескриптора объекта сопоставления файлов.
Несколько процессов могут совместно использовать представление одного файла с помощью одного объекта сопоставления файлов или создания отдельных объектов сопоставления файлов, поддерживаемых одним и тем же файлом. Один объект сопоставления файлов можно совместно использовать несколькими процессами, наследуя дескриптор при создании процесса, дедупликации дескриптора или открытия объекта сопоставления файлов по имени. Дополнительные сведения см. вCreateProcess
Создание объекта сопоставления файлов фактически не сопоставляет представление с адресным пространством процесса. Функция MapViewOfFileEx сопоставляет представление файла в адресное пространство процесса.
При одном важном исключении представления файлов, производные от любого объекта сопоставления файлов, поддерживаемого одним и тем же файлом, являются последовательными или идентичными в определенное время. Совместная обработка гарантируется для представлений в процессе и для представлений, сопоставленных различными процессами.
Исключение связано с удаленными файлами. Хотя CreateFileMappingFromApp работает с удаленными файлами, он не поддерживает их согласованность. Например, если два компьютера сопоставляют файл как доступный для записи, и оба изменяют одну и ту же страницу, каждый компьютер видит только собственные записи на страницу. Когда данные обновляются на диске, они не объединяются.
Сопоставленный файл и файл, к которому осуществляется доступ с помощью функций ввода-вывода (ReadFile и WriteFile) не обязательно согласованы.
Сопоставленные представления объекта сопоставления файлов поддерживают внутренние ссылки на объект, и объект сопоставления файлов не закрывается до тех пор, пока не будут выпущены все ссылки на него. Таким образом, чтобы полностью закрыть объект сопоставления файлов, приложение должно отменить сопоставление всех сопоставленных представлений объекта сопоставления файлов путем вызова UnmapViewOfFile и закрытия дескриптора объекта сопоставления файлов путем вызова CloseHandle. Эти функции можно вызывать в любом порядке.
При изменении файла с помощью сопоставленного представления метка времени последнего изменения может не обновляться автоматически. При необходимости вызывающий объект должен использовать SetFileTime, чтобы задать метку времени.
Используйте структурированную обработку исключений для защиты любого кода, записываемого в представление файла или считывающего их. Дополнительные сведения см. в чтения и записи изпредставления файлов.
Вы можете успешно запросить защиту исполняемых файлов только в том случае, если у приложения есть возможность codeGeneration.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 8 [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2012 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | memoryapi.h (включая Windows.h) |
| библиотеки |
onecore.lib |
| DLL | Kernel32.dll |
См. также
создание объекта сопоставления файлов
Функции сопоставления файлов