RtkCreateEvent

RtkCreateEvent creates an RTSS event. A handle is returned to the newly created event.

Syntax

NTSTATUS RtkCreateEvent(
    RTSSINST RtssInst,
    PHANDLE EventHandle,
    LPSECURITY_ATTRIBUTES Security,
    BOOLEAN ManualReset,
    BOOLEAN InitialState,
    PUNICODE_STRING Name
);

Parameters

RtssInst

An RTSSINST value returned from a call to RtkRtssAttach or RtkRtssAttachEx. Must pass in a valid RTSSINST value or the call will fail with STATUS_INVALID_PARAMETER.

EventHandle

A pointer to a handle that will receive a handle to the newly created event object. Must pass in a valid pointer to a handle or the call will fail with STATUS_INVALID_PARAMETER.

Security

Ignored.

ManualReset

Specifies whether a manual-reset or auto-reset event is created. If TRUE, then use the RtkResetEvent function to manually reset the state to non-signaled. If FALSE, the system automatically resets the state to non-signaled after a single waiting thread has been released.

InitialState

The initial state of the event object. If TRUE, the initial state is signaled; otherwise it is non-signaled.

Name

A pointer to a UNICODE_STRING specifying the name of the event object. The name is limited to 260 characters and can contain any character except the backslash path-separator character (\). Name comparison is case-sensitive.

If Name matches the name of an existing named event object, this function requests EVENT_ALL_ACCESS access to the existing object. In this case, the InitialOwner parameter is ignored because it has already been set by the creating driver.

If Name matches the name of another kind of object in the same namespace (such as an existing semaphore or mutex), the function fails and the function returns STATUS_INVALID_HANDLE. This occurs because these objects share the same namespace.

If Name is NULL, the event object is created without a name.

Return Value

RtkCreateEvent returns STATUS_SUCCESS on successfully creating the event or one of the following NTSTATUS error code in failure.

• STATUS_INVALID_PARAMETER
• STATUS_UNSUCCESSFUL
• STATUS_INVALID_HANDLE
• STATUS_NO_MEMORY

Remarks

The handle returned by RtkCreateEvent has EVENT_ALL_ACCESS access to the new event object and can be used in any function that requires a handle to an event object.

Any thread of the calling driver can specify the event-object handle in a call to RtkWaitforSingleObject or RtkWaitForMultipleObjects. This wait function returns when the state of the specified object is signaled.

The initial state of the event object is specified by the InitialState parameter. Use the RtkSetEvent function to set the state of an event object to signaled. Use the RtkResetEvent function to reset the state of an event object to nonsignaled.

When the state of a manual-reset event object is signaled, it remains signaled until it is explicitly reset to nonsignaled by the RtkResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object, can be released while the object's state is signaled.

When the state of an auto-reset event object is signaled, it remains signaled until a single waiting thread is released; the system then automatically resets the state to nonsignaled. If no threads are waiting, the event object's state remains signaled.

Multiple processes or drivers can have handles of the same event object, enabling use of the object for driver and process synchronization. The available object-sharing mechanism is: A process can specify the name of an event object in a call to RtkOpenEvent or RtkCreateEvent.

RtkCloseHandle closes an event-object handle. The system closes the handle automatically when the driver calls RtkRtssDetach. The event object is destroyed when its last handle has been closed.

See Also:

RtkCloseHandle

RtkOpenEvent