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

  • Статья

Подпрограмма 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 с дескриптором события.

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

  • Приложение пользовательского режима создает объект события и передает дескриптор к объекту драйверу, отправляя драйверу IOCTL. Драйвер должен обрабатывать IOCTL в контексте процесса, создавшего объект события, и должен проверить дескриптор, вызвав ObReferenceObjectByHandle. Этот метод рекомендуется использовать для совместного использования объектов событий в пользовательском режиме и режиме ядра.

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

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

Требования

Требование Значение
Минимальная версия клиента Доступно начиная с Windows 2000.
Целевая платформа Универсальное
Верхняя часть wdm.h (включая Ntddk.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Правила соответствия DDI HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

См. также раздел

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose