IoCreateSynchronizationEvent

The IoCreateSynchronizationEvent routine creates or opens a named synchronization event for use in serialization of access to hardware between two otherwise unrelated drivers.

PKEVENT 
  IoCreateSynchronizationEvent(
    IN PUNICODE_STRING  EventName,
    OUT PHANDLE  EventHandle
    );

Parameters

EventName

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

EventHandle

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

Return Value

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

Headers

Declared in ntddk.h. Include ntddk.h.

Comments

The event object is created if it does not already exist. IoCreateSynchronizationEvent sets the state of a new synchronization event to Signaled. If the event object already exists, it is simply opened. The pair of drivers that use a synchronization event call KeWaitForSingleObject with the PKEVENT pointer returned by this routine.

When a synchronization event is set to the Signaled state, a single thread of execution that was waiting on the event is released, and the event is automatically reset to the Not-Signaled state.

To release the event, a driver calls ZwClose with the event handle.

Sharing event objects between user mode and kernel mode requires care. The system creates user-mode event objects relative to the \\BaseNamedObjects object directory, and only those event objects are visible to user-mode programs. The Xxx user-mode event corresponds to the \\BaseNamedObjects\Xxx kernel-mode event. The preferred method to share event objects between user mode and kernel mode is for the user-mode program to create the event object and pass it to the driver through an IOCTL. The \\BaseNamedObjects object directory is not created until the Win32® system initializes. Therefore, drivers that are loaded at boot time cannot create event objects in their DriverEntry routines that are visible to user-mode programs.

For more information on events, see Event Objects.

Callers of IoCreateSynchronizationEvent must be running at IRQL = PASSIVE_LEVEL.

See Also

IoCreateNotificationEvent, KeWaitForSingleObject, RtlInitUnicodeString, ZwClose