RtCreateEvent

RtCreateEvent creates a named or unnamed event object.

Syntax

HANDLE RtCreateEvent(
    LPSECURITY_ATTRIBUTES lpEventAttributes,
    BOOL ManualReset,
    BOOL bInitialState,
    LPCTSTR lpName
);

Parameters

lpEventAttributes

Ignored.

bManualReset

Specifies whether a manual-reset or auto-reset event is created. If TRUE, then use the RtResetEvent 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.

bInitialState

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

lpName

A pointer to a null-terminated 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 lpName matches the name of an existing named event object, this function requests access to the existing object. In this case, bManualReset and bInitialState are ignored because they have already been set by the creating process.

If lpName matches the name of an existing mutex, semaphore, or shared memory object, the function fails and RtGetLastError returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and shared memory objects share the same namespace.

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

Return Value

A handle to the event object if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

If the function succeeds, and the named event object existed before the function call, GetLastError returns ERROR_ALREADY_EXISTS.

Remarks

The handle returned by RtCreateEvent has all accesses 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 process can specify the event-object handle in a call to one of the wait functions. The wait functions return when the state of the specified object is signaled. When a wait function returns, the waiting thread is released to continue its execution.

The initial state of the event object is specified by the bInitialState parameter. Use the RtSetEvent function to set the state of an event object to signaled. Use the RtResetEvent function to reset the state of an event object to non-signaled.

When the state of a manual-reset event is signaled, it remains signaled until it is explicitly reset to non-signaled by the RtResetEvent 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 resets the state to non-signaled. If no threads are waiting, the event object remains signaled.

Multiple processes can have handles to the same named event object, enabling use of the object for interprocess synchronization. The available object-sharing mechanism is: A process can specify the name of a event object in a call to RtOpenEvent or RtCreateEvent.

Use RtCloseHandle to close the handle. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.

See Also:

RtCloseHandle

RtOpenEvent

RtPulseEvent

RtResetEvent

RtSetEvent