Функция CreateFileMapping

Функция CreateFileMapping создает или открывает именованный или безымянный объект отображенного в памяти (проецируемого) файла для заданного файла.

Синтаксис

HANDLE CreateFileMapping(
  HANDLE hFile,                       // дескриптор файла
  LPSECURITY_ATTRIBUTES lpAttributes, // защита 
  DWORD flProtect,                    // атрибуты защиты
  DWORD dwMaximumSizeHigh,            // старшее слово размера
  DWORD dwMaximumSizeLow,             // младшее слово размера
  LPCTSTR lpName                      // имя объекта
);

Параметры

hFile
[in] Дескриптор файла, из которого создается "проецируемый" объект. Файл должен открываться с правами доступа, совместимыми с флажками защиты, заданными параметром flProtect. Рекомендуется, хотя и не обязательно, чтобы файлы, которые Вы намереваетесь отображать, открывались для монопольного доступа. Для получения дополнительной информации, см. статью Защита файла и права доступа.
Если hFile - INVALID_HANDLE_VALUE, вызывающий процесс должен также установить размер "проецируемого " объекта в параметрах dwMaximumSizeHigh и dwMaximumSizeLow. В этом случае, CreateFileMapping создает объект "проецируемый файл" заданного размера, поддерживаемый  файлом подкачки операционной системы, а не именованным файлом в файловой системе. Объект "проецируемый файл" может совместно использоваться посредством дублирования, посредством наследования или по имени. Начальное содержание страниц в объекте "проецируемый файл" равняется нулю (0).
lpAttributes
[in] Указатель на структуру SECURITY_ATTRIBUTES, которая обуславливает, может ли возвращенный дескриптор быть унаследован дочерними процессами. Если lpAttributes - ПУСТО (NULL), дескриптор не может быть унаследован.

Windows NT/2000/XP: Член структуры lpSecurityDescriptor  определяет дескриптор безопасности для нового объекта "проецируемый файл". Если lpAttributes - ПУСТО (NULL), объект "проецируемый файл" получает заданный по умолчанию (типичный) дескриптор безопасности. Списки управления доступом (ACL) в заданном по умолчанию дескрипторе безопасности для объекта "проецируемый файл" происходят от первичного или  заимствованного маркера прав создателя.

Обратите внимание! на то, что такое выполнение может вызвать угрозу безопасности. Чтобы избежать этого риска, используйте допустимую структуру SECURITY_ATTRIBUTES
flProtect
[in] Вид защиты необходимый для файла, когда он отображается. Этим параметром может быть одно из ниже перечисленных значений.
Значение Описание
PAGE_READONLY Дает доступ к страницам  переданной области только для чтения. Попытка записать в переданную область, приводит к нарушению прав доступа. Файл, определяемый параметром hFile  должен быть создан с правом доступа GENERIC_READ.
PAGE_READWRITE Дает доступ к операциям чтения-записи страниц переданной области. Файл, определяемый hFile должен быть создан с правами доступа GENERIC_READ и GENERIC_WRITE.
PAGE_WRITECOPY Дает доступ к копированию при записи страниц переданной области. Файлы, определяемые параметром hFile  должны создаваться с правами доступа GENERIC_READ и GENERIC_WRITE.
PAGE_EXECUTE_READ Дает доступ для чтения и исполнения к страницам переданной области. Файл, определенный параметром hFile, должен быть создан с правами доступа GENERIC_READ и GENERIC_EXECUTE.

Windows XP и Windows Server 2003:  Это функциональное свойство не доступно для версий ниже Windows XP SP2 и Windows Server  2003 SP1.

PAGE_EXECUTE_READWRITE Дает доступ для чтения, записи и исполнения к страницам переданной области. Файл, определенный параметром hFile должен быть создан с правами доступа GENERIC_READ, GENERIC_WRITE и GENERIC_EXECUTE.
Windows XP и Windows Server 2003:  Это функциональное свойство не доступно для версий ниже Windows XP SP2 и Windows Server  2003 SP1.
 

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

 

Значение Описание
SEC_COMMIT Размещает физическое  устройство хранения данных в памяти или в файле подкачки на диске для всех страниц раздела. Это - заданная по умолчанию (типичная) установка.
SEC_IMAGE Windows NT/2000/XP: Файл, определяемый для отображенного в памяти файла раздела, - загрузочный модуль исполняемого файла (PE-файла). Поскольку информация отображения и защиты файла взяты из PE-файла, то никакие другие атрибуты с  SEC_IMAGE не допустимы.

Windows Me/98/95:  Этот флажок не поддерживается.

SEC_NOCACHE Все страницы раздела определяются как некэшируемые. 

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

Обратите внимание! на то, что флажок SEC_NOCACHE требует, чтобы также были установлены, или SEC_RESERVE, или SEC_COMMIT.

Windows Me/98/95:  Этот флажок не поддерживается.

SEC_RESERVE Резервирует все страницы раздела, не помещая их в физическую память. Зарезервированный блок страниц не может использоваться никакими другими операциями распределения, до тех пор, пока он не освободится. Зарезервированные страницы могут быть переданы при последующих вызовах функции VirtualAlloc. Этот атрибут допустим только в том случае, если параметр hFile  имеет значение INVALID_HANDLE_VALUE; то есть это объект "проецируемый файл", поддерживаемый  файлом подкачки операционной системы.
 

dwMaximumSizeHigh

[in] Старшее двойное слово (DWORD) максимального размера объекта "проецируемый файл".

dwMaximumSizeLow

[in] Младшее двойное слово (DWORD) максимального размера объекта "проецируемый файл". Если этот параметр и dwMaximumSizeHigh равняются нулю, максимальный размер объекта "проецируемый файл" равен текущему размеру файла, идентифицированного hFile.

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

lpName

[in] Указатель на символьную строку с нулем в конце, определяющую имя "проецируемого " объекта.

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

Если этот параметр - ПУСТО (NULL), "проецируемый " объект создается без имени.

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

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

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

Windows 2000: Если Терминал сервисов не запущен,  префиксы "Global\" и "Local\" игнорируются. Остаток от имени может содержать любой символ кроме символа обратного слэша (\).

Windows NT : Имя может содержать любой символ кроме символа обратного слэша (\).

Windows 95/98/Me: Имя может содержать любой символ кроме символа обратного слэша (\). Пустая  строка (" ") - допустимое  имя объекта.

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

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

Если функция завершается ошибкой, возвращаемое значение - ПУСТО (NULL). Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.

Замечания

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

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

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

Windows 95/98/Me: Дескрипторы файла, которые использовались, чтобы создать объекты "проецируемый файл", не должны использоваться при последующих вызовах функций файлового ввода - вывода, типа ReadFile и WriteFile. Вообще, если дескриптор файла использовался при успешном вызове функции CreateFileMapping, не используйте этот дескриптор, если сначала не закроете соответствующий объект "проецируемый файл".

Создание объекта "проецируемый файл" создает возможность отображенного представления файла, а не само проецируемое представление. Функции MapViewOfFile и MapViewOfFileEx проецируют представление файла в адресном пространстве процесса.

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

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

Отображаемый файл и файл,  получивший доступ посредством функций ввода/вывода данных  (I/O) (ReadFile и WriteFile) не обязательно связаны.

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

Сессии Терминала сервисов могут использовать совместно используемые блоки памяти, чтобы перемещать данные между процессами, порожденными этими сессиями. Если Вы делаете это, то имеете в виду, что совместно используемая память, не может использоваться в ситуациях, где существуют оба из нижеследующих  условий:

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

Чтобы иметь отображение с разрешениями исполнения , ваше приложение должно вызвать функцию CreateFileMapping или с флажками PAGE_EXECUTE_READWRITE или с PAGE_EXECUTE_READ, а затем вызвать MapViewOfFile с флажками FILE_MAP_EXECUTE | FILE_MAP_WRITE или FILE_MAP_EXECUTE | FILE_MAP_READ.

Пример

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

hMap = CreateFileMapping(...); 

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS) 
{ 
    CloseHandle(hMap); 
    hMap = NULL; 
} 
return hMap; 

Код примера

Пример смотри в статье  Создание именованной совместно используемой памяти.

Смотри также

Обзор Управление файламиФункции, используемые для отображения файла в память, CloseHandle, DuplicateHandle, MapViewOfFile, MapViewOfFileEx, OpenFileMapping, ReadFile, SECURITY_ATTRIBUTES, UnmapViewOfFile, VirtualAlloc, WriteFile

Размещение и совместимость CreateFileMapping

К

Windows XP

Да 

л

Windows 2000 Professional

Да

и

Windows NT Workstation

Да

е

Windows Me

Да

н

Windows 98

Да

т

Windows 95

Да

 
С

Windows Server 2003

Да

е Windows 2000 Server Да
р Windows NT Server Да
в    
е    
р    

Используемая библиотека

Kernel32.lib

Используемая DLL -
 Заголовочный файл  

- объявлено в

Winbase.h

 - включено в

Windows.h

 Unicode

Реализуется как версии Unicode и  ANSI. Обратите внимание на то, что поддержка в Windows Me/98/95 требует программы Microsoft Layer for Unicode.

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz