CreateEvent

The CreateEvent function creates a named or unnamed event object.

Parameters

lpsa

Points to a SECURITY_ATTRIBUTES data structure that specifies the security attributes for the event.

The SECURITY_ATTRIBUTES structure has the following format:

typedef struct _SECURITY_ATTRIBUTES { /* sa */

DWORD nLength;

LPVOID lpSecurityDescriptor;

BOOL bInheritHandle;

} SECURITY_ATTRIBUTES;

If lpsa is NULL, the event is created without a security descriptor, and the resulting handle is not inherited during process creation.

fManualReset

Specifies whether the event must be manually reset. If fManualReset is TRUE, the event must be reset with the ResetEvent function. If fManualReset is FALSE, Windows automatically resets the event after releasing a single waiting thread.

fInitialState

Specifies the initial state of the event object. If fInitialState is TRUE, the event is set to the Signaled state (TRUE). If fInitialState is FALSE, the event is set to the Not-Signaled state (FALSE).

lpszEventName

Points to a null-terminated string specifying the name of the event. The name may contain any character except the pathname separator character '\'.

If lpszEventName matches the name of an existing named object, this function requests ALL access to the existing event (this is similar to calling the OpenEvent function).

If lpszEventName is NULL, the event is created without a name.

Return Value

If the function is successful, the return value is a handle to the event. If the event existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. If the event did not exist, GetLastError returns zero.

If the function fails, the return value is NULL. Use the GetLastError function to obtain extended error information.

Comments

The CreateEvent function creates an event with the specified initial state. If an event is in the signaled state (TRUE), a wait operation on the event does not block. If the event is in the not-signaled state (FALSE), a wait operation on the event blocks until the specified event attains the signaled state or the timeout value is exceeded.

To implement an event creation function that fails if the event already exists, an application can use the following code:

hEvent = CreateEvent(...);

if (hEvent != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

CloseHandle(hEvent);

hEvent = NULL;

}

return hEvent;

The CreateEvent function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

The handle that CreateEvent returns has full access to the new event. It may be used with any function that requires a handle to an event.

In addition to the standard object sharing mechanisms available in 32-bit Windows — inheritance and calls to DuplicateHandle — named events may be opened by any thread with appropriate access using the OpenEvent function. This allows the event object to be shared by any application that knows the name of the event.

See Also

CloseHandle, CreateEvent, OpenEvent, ResetEvent WaitForSingleObject, WaitForMultipleObjects