RtCreateEvent

RtCreateEvent creates a named or unnamed event object.

Syntax

Copy

HANDLE RtCreateEvent(
    [ignored]  LPSECURITY_ATTRIBUTES lpEventAttributes,
    [in]       BOOL bManualReset,
    [in]       BOOL bInitialState,
    [in]       LPCTSTR lpName
);

Parameters

[ignored] lpEventAttributes

Ignored.

[in] bManualReset

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

[in] bInitialState

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

[in] 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. Name comparison is case-sensitive. If the name exceeds 260 characters, this function returns ERROR_FILENAME_EXCED_RANGE.

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

If the function succeeds, it returns a handle to the event object. If the function fails, it returns NULL. Call GetLastError to obtain an error code.

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 full 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 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 the use of the object for interprocess synchronization. The available object-sharing mechanism is: A process can specify the name of an 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.

Requirements

Minimum supported version	Header	Library
wRTOS 1.0 SDK	RtApi.h	RtApi.lib (Windows), Startup.lib (RTSS)