Export (0) Print
Expand All
Expand Minimize

IoCreateSynchronizationEvent routine

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

Syntax


PKEVENT IoCreateSynchronizationEvent(
  _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

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

Remarks

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 for 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. 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 Ntddk.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlIoPassive4, PowerIrpDDis, HwStorPortProhibitedDDIs

See also

IoCreateNotificationEvent
KeWaitForSingleObject
RtlInitUnicodeString
ZwClose

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft