CreateEvent Function (Windows API)

CreateEvent Function

This topic describes the CreateEvent function, which creates or opens a named or unnamed event object.

Function Signature


                        HANDLE CreateEvent(

                            LPSECURITY_ATTRIBUTES lpEventAttributes,

                            BOOL bManualReset,

                            BOOL bInitialState,

                            LPCWSTR lpName

                        );

Parameters

lpEventAttributes: A pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the event object. If this parameter is NULL, the event object gets a default security descriptor.
bManualReset: If this parameter is TRUE, the function creates an auto-reset event object. If this parameter is FALSE, the function creates a manual-reset event object.
bInitialState: If this parameter is TRUE, the initial state of the event object is signaled. Otherwise, its initial state is nonsignaled.
lpName: The name of the event object. The name is limited to MAX_PATH characters. The name can contain any character except backslash (\). If lpName is NULL, the event object is created without a name.

Return Value

If the function succeeds, the return value is a handle to the newly created event object.

HANDLE

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Event objects are synchronization objects that the system uses to track the state of an event. An event object can be in either a signaled state or a nonsignaled state.

When an event object is created, its initial state is determined by the bInitialState parameter. If bManualReset is TRUE, the event object remains signaled until ResetEvent is called. If bManualReset is FALSE, the event object remains signaled until a thread waits for it by calling the WaitForSingleObject or WaitForMultipleObjects function. When a thread successfully waits for an auto-reset event object, the system automatically resets the event object to the nonsignaled state.

Use the CloseHandle function to close the handle to the event object when it is no longer needed.

To create or open a named event object, specify a name for the event object in the lpName parameter. If the event object already exists, the function checks the bManualReset and bInitialState parameters to ensure they are compatible with the existing object. If they are compatible, the function returns a handle to the existing event object. If they are not compatible, the function returns an error.

Requirements

Minimum supported client: Windows XP
Minimum supported server: Windows Server 2003
Header: winbase.h (include windows.h)
Library: Kernel32.lib
DLL: Kernel32.dll

MSDN Community