Expand Minimize

IoCreateNotificationEvent routine

The IoCreateNotificationEvent routine creates or opens a named notification event used to notify one or more threads of execution that an event has occurred.

Syntax


PKEVENT IoCreateNotificationEvent(
  _In_   PUNICODE_STRING EventName,
  _Out_  PHANDLE EventHandle
);

Parameters

EventName [in]

Pointer to a buffer containing a null-terminated Unicode string that names the event.

EventHandle [out]

Pointer to a location in which to return a handle for the event object. In Windows Server 2003 and later versions of Windows, the returned handle is a kernel handle.

Return value

IoCreateNotificationEvent returns a pointer to the created or opened event object or NULL if the event object could not be created or opened.

Remarks

IoCreateNotificationEvent creates and opens the event object if it does not already exist. IoCreateNotificationEvent sets the state of a new notification event to Signaled. If the event object already exists, IoCreateNotificationEvent just opens the event object.

When a notification event is set to the Signaled state it remains in that state until it is explicitly cleared.

Notification events, like synchronization events, are used to coordinate execution. Unlike a synchronization event, a notification event is not auto-resetting. Once a notification event is in the Signaled state, it remains in that state until it is explicitly reset (with a call to KeClearEvent or KeResetEvent).

To synchronize on a notification event:

  1. Open the notification event with IoCreateNotificationEvent. Identify the event with the EventName string.

  2. Wait for the event to be signaled by calling KeWaitForSingleObject with the PKEVENT returned by IoCreateNotificationEvent. More than one thread of execution can wait for a given notification event. To poll instead of stall, specify a Timeout of zero to KeWaitForSingleObject.

  3. Close the handle to the notification event with ZwClose when access to the event is no longer needed.

Sharing event objects between user mode and kernel mode requires care. There are two main methods for sharing event objects:

  • The user-mode application creates the event object and passes a handle to the object to the driver by sending an IOCTL to the driver. The driver must handle the IOCTL in the context of the process that created the event object and must validate the handle by calling ObReferenceObjectByHandle. This method is the recommended method for sharing event objects between user and kernel modes.

  • The driver creates a named event object in the \\BaseNamedObjects object directory. You can open a kernel-mode event named \\BaseNamedObjects\Xxx in user mode under the name Xxx. Note that security settings can prevent an application from opening the event. For more information, see the OpenEvent Fails in a Non-Administrator Account KB article. The \\BaseNamedObjects object directory is not created until the Microsoft Win32 subsystem initializes, so drivers that are loaded at boot time cannot create event objects in the \\BaseNamedObjects directory in their DriverEntry routines.

For more information about events, see Event Objects.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlIoPassive4, HwStorPortProhibitedDDIs

See also

IoCreateSynchronizationEvent
KeClearEvent
KeResetEvent
KeSetEvent
KeWaitForSingleObject
RtlInitUnicodeString
ZwClose

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft