CreateEvent

CreateEvent函数创建一个命名或未命名的事件对象。

手柄CreateEvent（

参数

【lpEventAttributes】

指向SECURITY_ATTRIBUTES结构的指针，用于确定返回的句柄是否可由子进程继承。如果【lpEventAttributes】为NULL，则无法继承该句柄。

Windows NT：结构的lpSecurityDescriptor成员指定新事件的安全描述符。如果【lpEventAttributes】为NULL，则事件将获取默认安全描述符。

Windows 95：结构的lpSecurityDescriptor成员将被忽略。

【bManualReset】

指定是否创建手动复位或自动复位事件对象。如果为TRUE，则必须使用ResetEvent功能手动将状态重置为非信号状态。如果为FALSE，则在单个等待线程被释放后，Windows会自动将状态重置为非指定状态。

【bInitialState】

指定事件对象的初始状态。如果为TRUE，则表示初始状态;否则，它是非信号的。

【lpName】

指向一个以null结尾的字符串，指定事件对象的名称。该名称仅限于MAX_PATH个字符，并且可以包含除反斜杠路径分隔符（\\）之外的任何字符。名称比较区分大小写。

如果【lpName】与现有的命名事件对象的名称相匹配，则此函数请求对现有对象的EVENT_ALL_ACCESS访问。在这种情况下，【bManualReset】和【bInitialState】参数被忽略，因为它们已经被创建过程设置了。如果【lpEventAttributes】参数不为NULL，则确定句柄是否可以继承，但其安全描述符成员将被忽略。

如果【lpName】为NULL，则会创建事件对象而不使用名称。

如果【lpName】匹配现有信号量，互斥体或文件映射对象的名称，则该函数将失败，并且GetLastError函数返回ERROR_INVALID_HANDLE。这是因为事件，互斥体，信号量和文件映射对象共享相同的名称空间。

返回值

如果函数成功，则返回值是事件对象的句柄。如果命名事件对象存在于函数调用之前，则GetLastError函数返回ERROR_ALREADY_EXISTS。否则，GetLastError返回零。

如果函数失败，返回值为NULL。要获取扩展错误信息，请调用GetLastError.

备注

由CreateEvent返回的句柄对新的事件对象进行EVENT_ALL_ACCESS访问，并可用于需要事件对象句柄的任何函数中。

调用进程的任何线程都可以在调用其中一个等待功能时指定事件对象句柄。当指定对象的状态发出信号时，单个对象等待函数返回。可以指示多对象等待功能在任何一个或所有指定对象发出信号时返回。当wait函数返回时，等待的线程被释放以继续执行。

事件对象的初始状态由【bInitialState】参数指定。使用SetEvent功能将事件对象的状态设置为发信号。使用ResetEvent函数将事件对象的状态重置为非信号。

当手动复位事件对象的状态发出信号时，它将保持信号，直到它被ResetEvent功能显式地复位为非指定状态。在指示对象的状态时，可以释放任意数量的等待线程或随后开始对指定事件对象进行等待操作的线程。

当自动复位事件对象的状态发出信号时，它保持信号，直到释放单个等待线程;系统自动将状态重置为非指定状态。如果没有线程正在等待，则事件对象的状态保持信号。

多个进程可以具有相同事件对象的句柄，从而使对象能够进行进程间同步。以下对象共享机制可用：

* CreateProcess函数创建的子进程可以继承CreateEvent CreateEvent启用继承的【lpEventAttributes】参数之后的事件对象的句柄。

*进程可以在调用DuplicateHandle函数时指定事件对象句柄，以创建可由另一进程使用的重复句柄。

*进程可以在调用OpenEvent或CreateEvent函数时指定事件对象的名称。

使用CloseHandle功能关闭句柄。当过程终止时，系统自动关闭句柄。当事件对象的最后一个句柄被关闭时被销毁。

也可以看看

CloseHandle, CreateProcess, DuplicateHandle, OpenEvent, ResetEvent, SECURITY_ATTRIBUTES, SetEvent