Функция 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

Функция MapViewOfFile

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

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

Синтаксис

LPVOID MapViewOfFile(

HANDLE hFileMappingObject, // дескр. объекта проецируемый файл

DWORD dwDesiredAccess, // режим доступа

DWORD dwFileOffsetHigh, // старшее DWORD смещения

DWORD dwFileOffsetLow, // младшее DWORD смещения

SIZE_T dwNumberOfBytesToMap // число отображаемых байтов

);

Параметры

hFileMappingObject

[in] Дескриптор открытого дескриптора объекта "проецируемый файл". Функции CreateFileMapping и OpenFileMapping возвращают этот дескриптор.

dwDesiredAccess

[in] Тип доступа к объекту "проецируемый файл" и, следовательно, это защита страниц, отображаемого файла. Этим параметром могут быть одно из ниже перечисленных значений.

Значение	Предназначение
FILE_MAP_WRITE	Доступ к операциям чтения-записи. Отображаемый объект должен быть создан с защитой PAGE_READWRITE . Чтение/запись представления файла отображается.
FILE_MAP_READ	Доступ только для чтения. Отображаемый объект должен быть создан с защитой PAGE_READWRITE или PAGE_READONLY. Представление файла только для чтения отображается.
FILE_MAP_ALL_ACCESS	То же самое, что и FILE_MAP_WRITE.
FILE_MAP_COPY	Копирование при доступе для записи. Отображаемый объект должен создаваться с флажком защиты PAGE_WRITECOPY.   Система помещает физическое сохранение данных из файла подкачки, когда вызывается MapViewOfFile. Фактическое физическое запоминающее устройство не используется до тех пор, пока поток в вашем процессе не запишет по адресу в представлении. В этой точке система копирует исходную страницу в новую страницу, поддерживаемую файлом подкачки, отображает страницу в адресное пространство процесса и изменяет защиту страницы на PAGE_READWRITE. Потоки в вашем процессе могут получить доступ только к этой локальной копии данных, а не первоначальным данным. Если эта страница когда-либо вырезается от рабочего набора страниц физической памяти вашего процесса, тогда она может записаться в запоминающем устройстве файла подкачки, которое было передано, когда вызывалась MapViewOfFile. Этот процесс только назначает физическую память, когда действительно записывается по виртуальному адресу. Изменения никогда не записываются обратно в исходный файл и освобождаются, когда поток в вашем процессе отменяет отображение представления. Пространство файла подкачки всего представления передается тогда, когда определяется доступ копирования при записи, потому что это дает возможность потоку в вашем процессе писать в каждую отдельно взятую страницу. Поэтому, когда вызываетсяMapViewOfFile, должно быть получено достаточно физического пространства устройства хранения данных.
FILE_MAP_EXECUTE	Доступ к исполнению кода (программы). Код, может быть запущен из отображаемой памяти. "Проецируемый " объект должен быть создан с доступом PAGE_EXECUTE_READWRITE или PAGE_EXECUTE_READ. Windows XP и Windows Server 2003: Эта функция не доступна до тех пор, пока не модернизируются до Windows XP SP2 иWindows Server 2003 SP1.

dwFileOffsetHigh

[in] Старшее двойное слово (DWORD) смещения файла, где начинается отображение.

dwFileOffsetLow

[in] Младшее двойное слово (DWORD) смещения файла, где начинается отображение. Комбинация старшего и младшего смещения должна установить смещение внутри файла, которое соответствует степени дробления системой распределенной памяти, или функция завершается ошибкой. То есть, смещение должно быть кратно степени дробления памяти. Используйте функцию GetSystemInfo, которая заполняет члены структуры SYSTEM_INFO, чтобы получить степень дробления системой распределенной памяти.

dwNumberOfBytesToMap

[in] Число отображаемых байтов файла. Если этот параметр равняется нулю, отображается весь файл.

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

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

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

Замечания

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

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

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

Отображаемое представление файла не гарантирует, что будет последовательным с файлом, к которому обращается функция ReadFile или WriteFile.

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

Windows NT/2000/XP: Если объект "проецируемый файл" поддерживается файлом подкачки (hFile - INVALID_HANDLE_VALUE), то этот файл должен быть достаточно большим, чтобы вместить все отображение. Если это не так, функция MapViewOfFile завершается ошибкой.

Windows 95/98/Me: Функция MapViewOfFile может потребовать, чтобы файл подкачки рос. Если файл подкачки не может расти, функция завершается ошибкой.

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

Функция 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

Функция UnmapViewOfFile

Функция UnmapViewOfFile отменяет отображение  представления файла из адресного пространства вызывающего процесса.

Синтаксис

BOOL UnmapViewOfFile( LPCVOID lpBaseAddress // начальный адрес );

Параметры

lpBaseAddress

[in] Указатель на базовый адрес отображаемого представления файла, отображение которого должно быть прекращено. Это значение должно быть идентично значению, возвращенному предыдущим вызовом функцииMapViewOfFile или MapViewOfFileEx.

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

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

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

Замечания

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

• Windows 95/98/Me: Файлы,  отображение последних представлений которых еще не было прекращено, считаются открытым с теми же самыми ограничениями совместного использования,  что и первоначальный дескриптор файла.

• Windows NT/2000/XP: Файлы,  отображение последних представлений которых еще не было прекращено, считаются открытым без совместного использования ограничений. 

WaitForSingleObject Syntax

C++

DWORD WINAPI WaitForSingleObject(

_In_  HANDLE hHandle,

_In_  DWORD dwMilliseconds

);

Parameters

hHandle [in]

A handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section.

If this handle is closed while the wait is still pending, the function's behavior is undefined.

The handle must have the SYNCHRONIZE access right. For more information, see Standard Access Rights.

dwMilliseconds [in]

The time-out interval, in milliseconds. If a nonzero value is specified, the function waits until the object is signaled or the interval elapses. If dwMilliseconds is zero, the function does not enter a wait state if the object is not signaled; it always returns immediately. If dwMilliseconds is INFINITE, the function will return only when the object is signaled.

Return value

If the function succeeds, the return value indicates the event that caused the function to return. It can be one of the following values.

Return code/value	Description
WAIT_ABANDONED 0x00000080L	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread and the mutex state is set to nonsignaled. If the mutex was protecting persistent state information, you should check it for consistency.
WAIT_OBJECT_0 0x00000000L	The state of the specified object is signaled.
WAIT_TIMEOUT 0x00000102L	The time-out interval elapsed, and the object's state is nonsignaled.
WAIT_FAILED (DWORD)0xFFFFFFFF	The function has failed. To get extended error information, call GetLastError.

 

Remarks

The WaitForSingleObject function checks the current state of the specified object. If the object's state is nonsignaled, the calling thread enters the wait state until the object is signaled or the time-out interval elapses.

The function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

The WaitForSingleObject function can wait for the following objects:

• Change notification

• Console input

• Event

• Memory resource notification

• Mutex

• Process

• Semaphore

• Thread

• Waitable timer

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and the CoInitialize function. Therefore, if you have a thread that creates windows, useMsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.

Функция CloseHandle закрывает дескриптор открытого объекта.

Синтаксис

BOOL CloseHandle( HANDLE hObject // дескриптор объекта );

Параметры

hObject

[in/out] Дескриптор открытого объекта.

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

Если функция завершается успешно, величина возвращаемого значения - не нуль.

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

Поскольку значения псевдо-дескриптора допускаются как правильные от функции GetCurrentHandle, они (или - (минус)1) могут задаваться как значение hObject.

Эта функция породит исключительную ситуацию, если или значение дескриптора, которое не допустимо (или 0) или значение псевдо-дескриптора, задается как значение hObject, а приложение запущено в среде отладчика. Это включает в себя закрытие дескриптора дважды и использование функции CloseHandle для дескриптора, возвращенного функцией FindFirstFile. 

Обратите внимание! на то, что эта функция не будет порождать исключительную ситуацию тогда, когда значение дескриптора, которое не допустимо или значение псевдо-дескриптора, задается, а приложение не запущено в среде отладчика.

Замечания

Функция CloseHandle закрывает дескрипторы ниже перечисленных объектов:

Признак доступа Коммуникационное устройство Консольный ввод данных Экранный буфер консоли Событие Файл Файл, отображаемый в память Задание Почтовый ящик в ядре системы Мьютекс Именованный канал Канал Процесс Семафор Сокет Поток  Таймер ожидания

Функция CloseHandle аннулирует заданный дескриптор объекта, уменьшает итоговое число дескрипторов объекта и выполняет проверку наличия объекта. После того, как последний дескриптор объект закрывается, объект удаляется из системы.

Закрытие дескриптора потока не завершает работу связанного потока. Чтобы удалить объект потока, Вы должны завершить работу потока, затем закрыть все дескрипторы потока.

Используйте функцию CloseHandle, чтобы закрыть дескрипторы, возвращенные при помощи вызова функции CreateFile. Используйте функцию FindClose, чтобы закрыть дескрипторы, возвращенные при помощи вызова функции FindFirstFile.

CreateWaitableTimer

• HANDLE CreateWaitableTimer(LPSECURITY_ATTRIBUTES lpTimerAttributes, BOOL bManualReset, LPCTSTR lpTimerName ) - функция создает ожидающий таймер в занятом состоянии, из которого он выводится принудительно, т.е. после создания объект не активен. Таймер может быть двух типов с автосбросом или ручным сбросом, определяется параметром bManualReset. Если таймер с ручным сбросом, то при переходе в свободное состояние запускаются все потоки, которые его ожидали. Таймер с автосбросом запускает только один поток. Первый параметр обычно всегда NULL, последний - имя таймера. Имя используется для совместного разделения объекта между процессами.

• BOOL SetWaitableTimer(HANDLE hTimer, const LARGE_INTEGER *pDueTime,LONG lPeriod,PTIMERAPCROUTINE pfnCompletionRoutine, PVOID pvArgToCompletionRoutine, BOOL bResume) - функция запускает таймер и определяет все его параметры. Функция может быть вызвана в любой момент для перенастройки таймера, если таймер в этот момент был в занятом состоянии, то вызов функции не освобождает его, после вызова функции таймер продолжит работу с новыми параметрами. После вызова функции таймер переходит в занятое состояние и отрабатывает время, указанное во втором параметре. - Первый параметр - дескриптор таймера.  - Второй параметр pDueTime определяет время перехода таймера в свободное состояние (signaled) или время срабатывания таймера. В течении этого времени поток, ожидающий срабатывания таймера, находится в спящем состоянии. Если указана функция асинхронного вызова (APC), то она ставится в момент срабатывания таймера в очередь на выполнение. Параметр pDueTime может быть определен как абсолютное или относительное время, абсолютное время определяет момент первого запуска и является величиной положительной. Определение абсолютного времени требует подготовительных операций по преобразованию полной даты в величину типа LARGE_INTEGER. Относительное время определяет момент первого срабатывания таймера после вызова функции. Относительное время является величиной отрицательной, выраженной в 100нс интервалах. - Третий параметр lPeriod определяет режим работы и одновременно период повторения срабатываний ожидающего таймера. Если период равен нулю -таймер сработает однократно, если не нуль, срабатывания будут повторятся с указанным периодом. Величина указывается в миллисекундах. Следует заметить, что установка lPeriod с точностью до 1 мсек не означает, что потоку точно в это время будут предоставлены ресурсы процессора. В действительности период пульсирующего таймера приблизительно кратен периоду времени, предоставлямого потоку системой. Например, на моем компьютере время отводимое потоку системой составляет 15,625 мсек. Если установить период срабатывания таймера равным 20 мсек, то в действительности он будет срабатывать с периодом приблизительно 32 мсек.  - Четвертый параметр pfnCompletionRoutine определяет указатель на необязательную функцию асинхронного вызова (APC), которая помещается в очередь функций APC в момент срабатывания таймера и затем вызывается. Ее вызов производится из того потока, который вызвал функцию SetWaitableTimer, но при условии, что он находится в состоянии ожидания, т.е. поток должен вызвать ожидающую функцию и находиться в ней. Если поток не находится в ожидающей функции, то функция асинхронного вызова не будет поставлена в очередь. Так осуществляется защита от переполнения очереди APC вызовами таймера. Функция асинхронного вызова должна завершаться до следующего срабатывания таймера. Если при наличии функции APC вызывается SetWaitableTimer с новыми параметрами, то функция APC немедленно выполняется, а затем уже выполняется для новых параметров. - Пятый параметр передает в функцию асинхронного вызова (APC) произвольный аргумент, например указатель на объект или структуру. - Последний параметр bResume, если он не нуль, выводит машину из спящего состояния по срабатыванию таймера.

• HANDLE OpenWaitableTimer(DWORD dwDesiredAccess, BOOL bInheritHandle, LPCTSTR lpTimerName) - функция открывает существующий именованный таймер. Используется для доступа к одному таймеру из разных процессов.

• BOOL CancelWaitableTimer(HANDLE hTimer) - функция останавливает таймер и отменяет выполнение функции APC, не изменяя состояния таймера. Если таймер был в занятом состоянии, то потоки остаются в спящем состоянии до возобновления работы таймера. Если же таймер оказался на этот момент в свободном состоянии, то он в нем и остается, потоки будут работать. При перенастройке таймера эту функцию вызывать не нужно.

CreateToolhelp32Snapshot