Функция CreateFileMapping2 (memoryapi.h)
Создает или открывает именованный или неименованный объект сопоставления файлов для указанного файла. Вы можете указать предпочтительный узел NUMA для физической памяти в качестве расширенного параметра; см. параметр ExtendedParameters.
Синтаксис
HANDLE CreateFileMapping2(
HANDLE File,
SECURITY_ATTRIBUTES *SecurityAttributes,
ULONG DesiredAccess,
ULONG PageProtection,
ULONG AllocationAttributes,
ULONG64 MaximumSize,
PCWSTR Name,
MEM_EXTENDED_PARAMETER *ExtendedParameters,
ULONG ParameterCount
);
Параметры
File
Тип: _In_ HANDLE
Дескриптор файла, из которого создается объект сопоставления файлов.
Файл должен быть открыт с правами доступа, совместимыми с флагами защиты , указанными параметром flProtect. Это не обязательно, но рекомендуется, чтобы файлы, которые планируется сопоставить для эксклюзивного доступа. Дополнительные сведения см. в прав доступа и безопасности файлов.
Если hFile INVALID_HANDLE_VALUE, вызов должен также указать размер объекта сопоставления файлов в dwMaximumSizeHigh и параметры dwMaximumSizeLow dwMaximumSizeLow. В этом сценарии CreateFileMapping создает объект сопоставления файлов указанного размера, который поддерживается системным файлом на страницы вместо файла в файловой системе.
SecurityAttributes
Тип: _In_opt_ SECURITY_ATTRIBUTES*
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Элемент
Если lpAttributesNULL, дескриптор не может наследоваться, а объект сопоставления файлов получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для объекта сопоставления файлов получены из первичного или олицетворения маркера создателя. Дополнительные сведения см. в "Безопасность и доступ к файлам".
DesiredAccess
Тип: _In_ ULONG
Маска требуемого доступа для возвращаемого дескриптора сопоставления файлов. Список прав доступа см. в разделе безопасность сопоставления файлов и права доступа.
PageProtection
Тип: _In_ ULONG
Указывает защиту страницы объекта сопоставления файлов. Все сопоставленные представления объекта должны быть совместимы с этой защитой.
Этот параметр может быть одним из следующих значений.
AllocationAttributes
Тип: _In_ ULONG
Для объекта сопоставления файлов можно указать один или несколько следующих атрибутов. Также см. параметр PageProtection.
| Ценность | Значение |
|---|---|
|
Если объект сопоставления файлов поддерживается файлом разбиения по страницам операционной системы (параметр hfileINVALID_HANDLE_VALUE), указывает, что при сопоставлении представления файла в адресное пространство процесса весь диапазон страниц фиксируется, а не зарезервирован. Система должна иметь достаточно зафиксируемых страниц для хранения всего сопоставления. В противном случае CreateFileMapping завершается ошибкой.
Этот атрибут не влияет на объекты сопоставления файлов, поддерживаемые исполняемыми файлами изображений или файлами данных (параметр hfile является дескриптором файла). SEC_COMMIT нельзя объединить с SEC_RESERVE. Если атрибут не указан, SEC_COMMIT предполагается. |
|
Указывает, что файл, указывающий параметр hFile, является исполняемым файлом образа.
Атрибут SEC_IMAGE должен сочетаться со значением защиты страницы, например PAGE_READONLY. Однако это значение защиты страницы не влияет на представления исполняемого файла образа. Защита страниц для представлений исполняемого файла образа определяется самим исполняемым файлом. Никакие другие атрибуты не являются допустимыми с SEC_IMAGE. |
|
Указывает, что файл, который указывает параметр hFile является исполняемым файлом образа, который не будет выполняться, а загруженный файл образа не будет иметь принудительной проверки целостности.
Кроме того, сопоставление представления объекта сопоставления файлов, созданного с помощью атрибута SEC_IMAGE_NO_EXECUTE, не будет вызывать обратные вызовы драйвера, зарегистрированные с помощью API ядра psSetLoadImageNotifyRoutine.
Атрибут SEC_IMAGE_NO_EXECUTE должен сочетаться со значением защиты страницы PAGE_READONLY. Никакие другие атрибуты не являются допустимыми с SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2012 и Windows 8. |
|
Позволяет использовать большие страницы для объектов сопоставления файлов, поддерживаемых файлом подкачки операционной системы (параметр hfile имеет значение INVALID_HANDLE_VALUE). Этот атрибут не поддерживается для объектов сопоставления файлов, поддерживаемых исполняемыми файлами изображений или файлами данных (параметр hFile является дескриптором исполняемого образа или файла данных).
Максимальный размер объекта сопоставления файлов должен иметь несколько минимальных размеров большой страницы, возвращаемой функцией GetLargePageMinimum. Если это не так, CreateFileMapping завершается ошибкой. При сопоставлении представления объекта сопоставления файлов, созданного с SEC_LARGE_PAGES, базовый адрес и размер представления также должны быть несколькими из минимального размера большой страницы. SEC_LARGE_PAGES требует, чтобы SeLockMemoryPrivilege привилегии были включены в маркере вызывающего объекта. Если указан SEC_LARGE_PAGES, необходимо также указать SEC_COMMIT. Windows Server 2003: это значение не поддерживается до Windows Server 2003 с пакетом обновления 1 (SP1). Windows XP: это значение не поддерживается. |
|
Задает все страницы, которые не кэшируются.
Приложения не должны использовать этот атрибут, за исключением случаев, когда явно требуется для устройства. Использование заблокированных функций с памятью, сопоставленной с 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. Windows Server 2003 и Windows XP: этот флаг не поддерживается до Windows Vista. |
MaximumSize
Тип: _In_ ULONG64
Максимальный размер объекта сопоставления файлов.
Если этот параметр равен 0 (ноль), максимальный размер объекта сопоставления файлов равен текущему размеру файла, который идентифицирует hFile.
Попытка сопоставить файл с длиной 0 (ноль) завершается ошибкой с кодом ошибки ERROR_FILE_INVALID. Необходимо протестировать файлы с длиной 0 (ноль) и отклонить эти файлы.
Name
Тип: _In_opt_ PCWSTR
Имя объекта сопоставления файлов.
Если этот параметр соответствует имени существующего объекта сопоставления, функция запрашивает доступ к объекту с защитой, которая flProtect указывает.
Если этот параметр значение NULL, то объект сопоставления файлов создается без имени.
Если lpName соответствует имени существующего события, семафора, мьютекса, ожидающего таймера или объекта задания, функция завершается ошибкой, а функция getLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Для создания объекта сопоставления файлов в глобальном пространстве имен из сеанса, отличного от нуля сеанса, требуется
Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь для входа использует сеанс 0 (ноль), следующий пользователь для входа использует сеанс 1 (один) и т. д. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
ExtendedParameters
Тип: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*
Необязательный указатель на один или несколько расширенных параметров типа MEM_EXTENDED_PARAMETER. Каждое из этих расширенных значений параметров может иметь поле типа
ParameterCount
в параметре ULONG
Число расширенных параметров, на которые указывает ExtendedParameters.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором созданного объекта сопоставления файлов.
Если объект существует перед вызовом функции, функция возвращает дескриптор существующему объекту (с текущим размером, а не указанным размером), а GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
См. примечания
Примеры
Пример см. в статье Создание именованной общей памятиили создание сопоставления файлов с помощью больших страниц.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Сборка Windows 10 20348 |
| минимальный поддерживаемый сервер | Сборка Windows 10 20348 |
| целевая платформа | Виндоус |
| заголовка | memoryapi.h (включая Windows.h, Memoryapi.h) |
| библиотеки |
onecore.lib |
| DLL | Kernel32.dll |