Функция IoCreateSynchronizationEvent (wdm.h)

Статья
02/07/2025

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

Синтаксис

PKEVENT IoCreateSynchronizationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Параметры

[in] EventName

Указатель на буфер, содержащий строку Юникода, завершающую значение NULL, которая называет событие.

[out] EventHandle

Указатель на расположение, в котором возвращается дескриптор объекта события. В Windows Server 2003 и более поздних версиях Windows возвращенный дескриптор — это дескриптор ядра .

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

IoCreateSynchronizationEvent возвращает указатель на созданный или открытый объект события или null, если объект события не удалось создать или открыть.

Замечания

Объект события создается, если он еще не существует. IoCreateSynchronizationEvent задает состояние нового события синхронизации signaled. Если объект события уже существует, он просто открывается. Пара драйверов, использующих вызов события синхронизации KeWaitForSingleObject с указателем PKEVENT, возвращенным этой подпрограммой.

Если для события синхронизации задано состояние Signaled, один поток выполнения, ожидающий освобождения события, и событие автоматически сбрасывается в состояние Not-Signaled.

Чтобы освободить событие, драйвер вызывает ZwClose с дескриптором событий.

Для совместного использования объектов событий между пользовательским режимом и режимом ядра требуется забота. Существует два основных метода совместного использования объектов событий:

Приложение пользовательского режима создает объект события и передает дескриптор объекту драйверу, отправляя IOCTL драйверу. Драйвер должен обрабатывать IOCTL в контексте процесса, создавшего объект события, и должен проверить дескриптор, вызвав ObReferenceObjectByHandle. Этот метод рекомендуется использовать для совместного использования объектов событий между режимами пользователя и ядра.
Драйвер создает именованный объект события в глобальном каталоге объектов \BaseNamedObjects. Чтобы получить доступ к событию режима ядра из пользовательского режима, используйте имя Global\\Xxx. Обратите внимание, что параметры безопасности могут запретить приложению открывать событие. Каталог объектов \BaseNamedObjects не создается до инициализации подсистемы Microsoft Win32, поэтому драйверы, загруженные во время загрузки, не могут создавать объекты событий в каталоге \BaseNamedObjects в подпрограммы DriverEntry

Дополнительные сведения о событиях см. в объектов событий.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 2000.
целевая платформа	Всеобщий
заголовка	wdm.h (include Ntddk.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

См. также

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose

Поделиться через