The ZwCreateEvent routine creates an event object, sets the initial state of the event to the specified value, and opens a handle to the object with the specified desired access.
NTSYSAPI NTSTATUS ZwCreateEvent( PHANDLE EventHandle, ACCESS_MASK DesiredAccess, POBJECT_ATTRIBUTES ObjectAttributes, EVENT_TYPE EventType, BOOLEAN InitialState );
A pointer to a variable that will receive the event object handle. The handle includes bookkeeping information, such as a reference count and security context.
The ACCESS_MASK value that represents the desired types of access for the event object. The following table contains the event-specific ACCESS_MASK values.
|EVENT_QUERY_STATE||Query the state of the event object.|
|EVENT_MODIFY_STATE||Modify the state of the event object.|
|EVENT_ALL_ACCESS||All possible access rights to the event object.|
A pointer to the object attributes structure supplied by the caller to be used for the specified object. These attributes would include the ObjectName and the SECURITY_DESCRIPTOR, for example. This parameter is initialized by calling the InitializeObjectAttributes macro.
The type of the event, which can be SynchronizationEvent or a NotificationEvent. These values belong to the EVENT_TYPE enumeration, which is defined in the Ntdef.h header file. The event type can be modified with the REALTIME_OBJECT_FLAG modifier to provide priority-ordered queuing of wait requests.
The initial state of the event object. Set to TRUE to initialize the event object to the Signaled state. Set to FALSE to initialize the event object to the not-Signaled state.
ZwCreateEvent returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:
||Resources required by this function could not be allocated.|
||The supplied ObjectAttributes structure contained an invalid parameter value.|
||The specified EventType parameter was invalid. The allowable EventType values are NotificationEvent or SynchronizationEvent. The REALTIME_OBJECT_FLAG can also be specified for these EventType parameters.|
||The ObjectAttributes parameter contained an ObjectName in the OBJECT_ATTRIBUTES structure that was invalid.|
||The ObjectAttributes parameter did not contain a RootDirectory member, but the ObjectName member in the OBJECT_ATTRIBUTES structure was an empty string or did not contain an OBJECT_NAME_PATH_SEPARATOR character. This indicates incorrect syntax for the object path.|
||The caller did not have the required privilege to create a handle with the access specified in the DesiredAccess parameter.|
ZwCreateEvent creates an event object, sets it initial state to the specified value, and opens a handle to the object with the specified desired access.
ZwCreateEvent can create either notification or synchronization events.
Events are used to coordinate execution. Events can be used by file system drivers to allow a caller to wait for completion of the requested operation until the given event is set to the Signaled state.
Notification events can be used to notify one or more threads of execution that an event has occurred. Synchonization events can be used in the serialization of access to hardware between two otherwise unrelated drivers.
A synchonization event is auto-resetting. When a synchronization event is set to the Signaled state, a single thread of execution that was waiting for the event to be signaled is released, and the event is automatically reset to the Not-Signaled state.
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.
To synchronize on a notification event:
- Create the notification event with ZwCreateEvent with the EventType parameter set to NotificationEvent.
- Wait for the event to be signaled by calling ZwWaitForSingleObject with the EventHandle returned by ZwCreateEvent. More than one thread of execution can wait for a given notification event to be signaled. To poll instead of stall, specify a Timeout of zero to ZwWaitForSingleObject.
- Close the handle to the notification event with ZwClose when access to the event is no longer needed.
There are two alternate ways to specify the name of the object passed to ZwCreateEvent:
- As a fully qualified pathname, supplied in the ObjectName member of the input ObjectAttributes.
- As pathname relative to the directory represented by the handle in the RootDirectory member of the input ObjectAttributes.
For more information about events, see Event Objects.
|Minimum supported client||Available starting with Windows XP.|
|Header||ntifs.h (include Ntifs.h)|
|DDI compliance rules||PowerIrpDDis, HwStorPortProhibitedDDIs|