EventWaitHandle.OpenExisting 方法
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
打开指定的命名同步事件（如果已存在）。
重载
| 名称 | 说明 |
|---|---|
| OpenExisting(String) |
打开指定的命名同步事件（如果已存在）。 |
| OpenExisting(String, EventWaitHandleRights) |
使用所需的安全访问打开指定的命名同步事件（如果已存在）。 |
| OpenExisting(String, NamedWaitHandleOptions) |
打开指定的命名同步事件（如果已存在）。 如果选项仅设置为当前用户，则为调用用户验证对象的访问控制。 |
OpenExisting(String)
- Source:
- EventWaitHandle.cs
- Source:
- EventWaitHandle.cs
- Source:
- EventWaitHandle.cs
- Source:
- EventWaitHandle.cs
- Source:
- EventWaitHandle.cs
打开指定的命名同步事件（如果已存在）。
public:
static System::Threading::EventWaitHandle ^ OpenExisting(System::String ^ name);[System.Security.SecurityCritical]
public static System.Threading.EventWaitHandle OpenExisting(string name);[System.Runtime.Versioning.SupportedOSPlatform("windows")]
public static System.Threading.EventWaitHandle OpenExisting(string name);public static System.Threading.EventWaitHandle OpenExisting(string name);[<System.Security.SecurityCritical>]
static member OpenExisting : string -> System.Threading.EventWaitHandle[<System.Runtime.Versioning.SupportedOSPlatform("windows")>]
static member OpenExisting : string -> System.Threading.EventWaitHandlestatic member OpenExisting : string -> System.Threading.EventWaitHandlePublic Shared Function OpenExisting (name As String) As EventWaitHandle参数
- name
- String
要与其他进程打开和共享的同步对象的名称。 名称区分大小写。 反斜杠字符 （\） 是保留的，只能用于指定命名空间。 有关命名空间的详细信息，请参阅“备注”部分。 根据操作系统，名称可能会有进一步的限制。 例如，在基于 Unix 的操作系统上，排除命名空间后的名称必须是有效的文件名。
返回
一个表示命名系统事件的对象。
- 属性
例外
无法打开具有提供的 name 同步对象。 它可能不存在，或者不同类型的同步对象可能具有相同的名称。 在某些情况下，可能会为无效名称引发此异常。
name 是 null。
name 无效。 这可能是出于各种原因，包括操作系统可能放置的一些限制，例如未知前缀或无效字符。 请注意，名称和通用前缀“Global\”和“Local\”区分大小写。
-或-
还有其他一些错误。 该 HResult 属性可能提供更多信息。
仅Windows：name指定了未知命名空间。 有关详细信息，请参阅 对象名称 。
name 太长。 长度限制可能取决于操作系统或配置。
命名事件存在，但用户没有使用它所需的安全访问权限。
注解
name可以是前缀Global\Local\，也可以指定命名空间。
Global指定命名空间后，可以与系统上的任何进程共享同步对象。
Local指定命名空间时，这也是未指定命名空间时的默认命名空间，同步对象可以与同一会话中的进程共享。 在Windows，会话是登录会话，服务通常在不同的非交互式会话中运行。 在类似 Unix 的操作系统上，每个 shell 都有自己的会话。 会话本地同步对象可能适合在进程与父/子关系之间同步，其中它们都在同一会话中运行。 有关Windows上的同步对象名称的详细信息，请参阅 Object Names。
如果命名空间中存在所请求类型的同步对象，则会打开现有同步对象。 如果命名空间中不存在同步对象，或者命名空间中存在不同类型的同步对象，则会引发一个 WaitHandleCannotBeOpenedException 。
该方法 OpenExisting 尝试打开指定的命名系统事件。 若要在系统事件不存在时创建系统事件，请使用具有参数的构造函数之 EventWaitHandle 一 name 。
对此方法使用相同值的 name 多次调用不一定返回相同的 EventWaitHandle 对象，即使返回的对象表示相同的命名系统事件。
在 .NET Framework 中，此方法重载等效于调用 System.Threading.EventWaitHandle.OpenExisting（System.String，System.Security.AccessControl.EventWaitHandleRights）方法重载并指定 EventWaitHandleRights.Synchronize 和 EventWaitHandleRights.Modify 权限， 通过使用按位 OR 运算进行组合。
指定 EventWaitHandleRights.Synchronize 标志允许线程等待命名系统事件，并指定 EventWaitHandleRights.Modify 标志允许线程调用 Set 和 Reset 方法。
另请参阅
适用于
OpenExisting(String, EventWaitHandleRights)
使用所需的安全访问打开指定的命名同步事件（如果已存在）。
public:
static System::Threading::EventWaitHandle ^ OpenExisting(System::String ^ name, System::Security::AccessControl::EventWaitHandleRights rights);public static System.Threading.EventWaitHandle OpenExisting(string name, System.Security.AccessControl.EventWaitHandleRights rights);[System.Security.SecurityCritical]
public static System.Threading.EventWaitHandle OpenExisting(string name, System.Security.AccessControl.EventWaitHandleRights rights);static member OpenExisting : string * System.Security.AccessControl.EventWaitHandleRights -> System.Threading.EventWaitHandle[<System.Security.SecurityCritical>]
static member OpenExisting : string * System.Security.AccessControl.EventWaitHandleRights -> System.Threading.EventWaitHandlePublic Shared Function OpenExisting (name As String, rights As EventWaitHandleRights) As EventWaitHandle参数
- name
- String
要与其他进程打开和共享的同步对象的名称。 名称区分大小写。 反斜杠字符 （\） 是保留的，只能用于指定命名空间。 有关命名空间的详细信息，请参阅“备注”部分。 根据操作系统，名称可能会有进一步的限制。 例如，在基于 Unix 的操作系统上，排除命名空间后的名称必须是有效的文件名。
- rights
- EventWaitHandleRights
表示所需安全访问的枚举值的按位组合。
返回
一个表示命名系统事件的对象。
- 属性
例外
name 是 null。
无法打开具有提供的 name 同步对象。 它可能不存在，或者不同类型的同步对象可能具有相同的名称。 在某些情况下，可能会为无效名称引发此异常。
name 无效。 这可能是出于各种原因，包括操作系统可能放置的一些限制，例如未知前缀或无效字符。 请注意，名称和通用前缀“Global\”和“Local\”区分大小写。
-或-
还有其他一些错误。 该 HResult 属性可能提供更多信息。
仅Windows：name指定了未知命名空间。 有关详细信息，请参阅 对象名称 。
name 太长。 长度限制可能取决于操作系统或配置。
命名事件存在，但用户没有所需的安全访问权限。
示例
下面的代码示例演示具有访问控制安全性的命名系统事件的跨进程行为。 该示例使用 OpenExisting(String) 方法重载测试命名事件是否存在。
如果该事件不存在，则会使用初始所有权和访问控制安全性创建该事件，以拒绝当前用户使用该事件的权限，但授予对事件读取和更改权限的权限。
如果从两个命令窗口运行编译的示例，则第二个副本将在调用 OpenExisting(String)时引发访问冲突异常。 捕获异常，该示例使用 OpenExisting(String, EventWaitHandleRights) 方法重载等待事件，并具有读取和更改权限所需的权限。
更改权限后，事件将打开，并具有等待该事件并发出信号所需的权限。 如果从第三个命令窗口运行已编译的示例，该示例将使用新权限运行。
using System;
using System.Threading;
using System.Security.AccessControl;
internal class Example
{
internal static void Main()
{
const string ewhName = "EventWaitHandleExample5";
EventWaitHandle ewh = null;
bool doesNotExist = false;
bool unauthorized = false;
// The value of this variable is set by the event
// constructor. It is true if the named system event was
// created, and false if the named event already existed.
//
bool wasCreated;
// Attempt to open the named event.
try
{
// Open the event with (EventWaitHandleRights.Synchronize
// | EventWaitHandleRights.Modify), to wait on and
// signal the named event.
//
ewh = EventWaitHandle.OpenExisting(ewhName);
}
catch (WaitHandleCannotBeOpenedException)
{
Console.WriteLine("Named event does not exist.");
doesNotExist = true;
}
catch (UnauthorizedAccessException ex)
{
Console.WriteLine("Unauthorized access: {0}", ex.Message);
unauthorized = true;
}
// There are three cases: (1) The event does not exist.
// (2) The event exists, but the current user doesn't
// have access. (3) The event exists and the user has
// access.
//
if (doesNotExist)
{
// The event does not exist, so create it.
// Create an access control list (ACL) that denies the
// current user the right to wait on or signal the
// event, but allows the right to read and change
// security information for the event.
//
string user = Environment.UserDomainName + "\\"
+ Environment.UserName;
EventWaitHandleSecurity ewhSec =
new EventWaitHandleSecurity();
EventWaitHandleAccessRule rule =
new EventWaitHandleAccessRule(user,
EventWaitHandleRights.Synchronize |
EventWaitHandleRights.Modify,
AccessControlType.Deny);
ewhSec.AddAccessRule(rule);
rule = new EventWaitHandleAccessRule(user,
EventWaitHandleRights.ReadPermissions |
EventWaitHandleRights.ChangePermissions,
AccessControlType.Allow);
ewhSec.AddAccessRule(rule);
// Create an EventWaitHandle object that represents
// the system event named by the constant 'ewhName',
// initially signaled, with automatic reset, and with
// the specified security access. The Boolean value that
// indicates creation of the underlying system object
// is placed in wasCreated.
//
ewh = new EventWaitHandle(true,
EventResetMode.AutoReset,
ewhName,
out wasCreated,
ewhSec);
// If the named system event was created, it can be
// used by the current instance of this program, even
// though the current user is denied access. The current
// program owns the event. Otherwise, exit the program.
//
if (wasCreated)
{
Console.WriteLine("Created the named event.");
}
else
{
Console.WriteLine("Unable to create the event.");
return;
}
}
else if (unauthorized)
{
// Open the event to read and change the access control
// security. The access control security defined above
// allows the current user to do this.
//
try
{
ewh = EventWaitHandle.OpenExisting(ewhName,
EventWaitHandleRights.ReadPermissions |
EventWaitHandleRights.ChangePermissions);
// Get the current ACL. This requires
// EventWaitHandleRights.ReadPermissions.
EventWaitHandleSecurity ewhSec = ewh.GetAccessControl();
string user = Environment.UserDomainName + "\\"
+ Environment.UserName;
// First, the rule that denied the current user
// the right to enter and release the event must
// be removed.
EventWaitHandleAccessRule rule =
new EventWaitHandleAccessRule(user,
EventWaitHandleRights.Synchronize |
EventWaitHandleRights.Modify,
AccessControlType.Deny);
ewhSec.RemoveAccessRule(rule);
// Now grant the user the correct rights.
//
rule = new EventWaitHandleAccessRule(user,
EventWaitHandleRights.Synchronize |
EventWaitHandleRights.Modify,
AccessControlType.Allow);
ewhSec.AddAccessRule(rule);
// Update the ACL. This requires
// EventWaitHandleRights.ChangePermissions.
ewh.SetAccessControl(ewhSec);
Console.WriteLine("Updated event security.");
// Open the event with (EventWaitHandleRights.Synchronize
// | EventWaitHandleRights.Modify), the rights required
// to wait on and signal the event.
//
ewh = EventWaitHandle.OpenExisting(ewhName);
}
catch (UnauthorizedAccessException ex)
{
Console.WriteLine("Unable to change permissions: {0}",
ex.Message);
return;
}
}
// Wait on the event, and hold it until the program
// exits.
//
try
{
Console.WriteLine("Wait on the event.");
ewh.WaitOne();
Console.WriteLine("Event was signaled.");
Console.WriteLine("Press the Enter key to signal the event and exit.");
Console.ReadLine();
}
catch (UnauthorizedAccessException ex)
{
Console.WriteLine("Unauthorized access: {0}", ex.Message);
}
finally
{
ewh.Set();
}
}
}
Imports System.Threading
Imports System.Security.AccessControl
Friend Class Example
<MTAThread> _
Friend Shared Sub Main()
Const ewhName As String = "EventWaitHandleExample5"
Dim ewh As EventWaitHandle = Nothing
Dim doesNotExist as Boolean = False
Dim unauthorized As Boolean = False
' The value of this variable is set by the event
' constructor. It is True if the named system event was
' created, and False if the named event already existed.
'
Dim wasCreated As Boolean
' Attempt to open the named event.
Try
' Open the event with (EventWaitHandleRights.Synchronize
' Or EventWaitHandleRights.Modify), to wait on and
' signal the named event.
'
ewh = EventWaitHandle.OpenExisting(ewhName)
Catch ex As WaitHandleCannotBeOpenedException
Console.WriteLine("Named event does not exist.")
doesNotExist = True
Catch ex As UnauthorizedAccessException
Console.WriteLine("Unauthorized access: {0}", ex.Message)
unauthorized = True
End Try
' There are three cases: (1) The event does not exist.
' (2) The event exists, but the current user doesn't
' have access. (3) The event exists and the user has
' access.
'
If doesNotExist Then
' The event does not exist, so create it.
' Create an access control list (ACL) that denies the
' current user the right to wait on or signal the
' event, but allows the right to read and change
' security information for the event.
'
Dim user As String = Environment.UserDomainName _
& "\" & Environment.UserName
Dim ewhSec As New EventWaitHandleSecurity()
Dim rule As New EventWaitHandleAccessRule(user, _
EventWaitHandleRights.Synchronize Or _
EventWaitHandleRights.Modify, _
AccessControlType.Deny)
ewhSec.AddAccessRule(rule)
rule = New EventWaitHandleAccessRule(user, _
EventWaitHandleRights.ReadPermissions Or _
EventWaitHandleRights.ChangePermissions, _
AccessControlType.Allow)
ewhSec.AddAccessRule(rule)
' Create an EventWaitHandle object that represents
' the system event named by the constant 'ewhName',
' initially signaled, with automatic reset, and with
' the specified security access. The Boolean value that
' indicates creation of the underlying system object
' is placed in wasCreated.
'
ewh = New EventWaitHandle(True, _
EventResetMode.AutoReset, ewhName, _
wasCreated, ewhSec)
' If the named system event was created, it can be
' used by the current instance of this program, even
' though the current user is denied access. The current
' program owns the event. Otherwise, exit the program.
'
If wasCreated Then
Console.WriteLine("Created the named event.")
Else
Console.WriteLine("Unable to create the event.")
Return
End If
ElseIf unauthorized Then
' Open the event to read and change the access control
' security. The access control security defined above
' allows the current user to do this.
'
Try
ewh = EventWaitHandle.OpenExisting(ewhName, _
EventWaitHandleRights.ReadPermissions Or _
EventWaitHandleRights.ChangePermissions)
' Get the current ACL. This requires
' EventWaitHandleRights.ReadPermissions.
Dim ewhSec As EventWaitHandleSecurity = _
ewh.GetAccessControl()
Dim user As String = Environment.UserDomainName _
& "\" & Environment.UserName
' First, the rule that denied the current user
' the right to enter and release the event must
' be removed.
Dim rule As New EventWaitHandleAccessRule(user, _
EventWaitHandleRights.Synchronize Or _
EventWaitHandleRights.Modify, _
AccessControlType.Deny)
ewhSec.RemoveAccessRule(rule)
' Now grant the user the correct rights.
'
rule = New EventWaitHandleAccessRule(user, _
EventWaitHandleRights.Synchronize Or _
EventWaitHandleRights.Modify, _
AccessControlType.Allow)
ewhSec.AddAccessRule(rule)
' Update the ACL. This requires
' EventWaitHandleRights.ChangePermissions.
ewh.SetAccessControl(ewhSec)
Console.WriteLine("Updated event security.")
' Open the event with (EventWaitHandleRights.Synchronize
' Or EventWaitHandleRights.Modify), the rights required
' to wait on and signal the event.
'
ewh = EventWaitHandle.OpenExisting(ewhName)
Catch ex As UnauthorizedAccessException
Console.WriteLine("Unable to change permissions: {0}", _
ex.Message)
Return
End Try
End If
' Wait on the event, and hold it until the program
' exits.
'
Try
Console.WriteLine("Wait on the event.")
ewh.WaitOne()
Console.WriteLine("Event was signaled.")
Console.WriteLine("Press the Enter key to signal the event and exit.")
Console.ReadLine()
Catch ex As UnauthorizedAccessException
Console.WriteLine("Unauthorized access: {0}", _
ex.Message)
Finally
ewh.Set()
End Try
End Sub
End Class
注解
name可以是前缀Global\Local\，也可以指定命名空间。
Global指定命名空间后，可以与系统上的任何进程共享同步对象。
Local指定命名空间时，这也是未指定命名空间时的默认命名空间，同步对象可以与同一会话中的进程共享。 在Windows，会话是登录会话，服务通常在不同的非交互式会话中运行。 在类似 Unix 的操作系统上，每个 shell 都有自己的会话。 会话本地同步对象可能适合在进程与父/子关系之间同步，其中它们都在同一会话中运行。 有关Windows上的同步对象名称的详细信息，请参阅 Object Names。
如果命名空间中存在所请求类型的同步对象，则会打开现有同步对象。 如果命名空间中不存在同步对象，或者命名空间中存在不同类型的同步对象，则会引发一个 WaitHandleCannotBeOpenedException 。
参数 rights 必须包含 EventWaitHandleRights.Synchronize 标志，以允许线程等待事件，以及 EventWaitHandleRights.Modify 允许线程调用 Set 和 Reset 方法的标志。
该方法 OpenExisting 尝试打开现有的命名系统事件。 若要在系统事件不存在时创建系统事件，请使用具有参数的构造函数之 EventWaitHandle 一 name 。
对此方法使用相同值的 name 多次调用不一定返回相同的 EventWaitHandle 对象，即使返回的对象表示相同的命名系统事件。
另请参阅
适用于
OpenExisting(String, NamedWaitHandleOptions)
- Source:
- EventWaitHandle.cs
- Source:
- EventWaitHandle.cs
打开指定的命名同步事件（如果已存在）。 如果选项仅设置为当前用户，则为调用用户验证对象的访问控制。
public:
static System::Threading::EventWaitHandle ^ OpenExisting(System::String ^ name, System::Threading::NamedWaitHandleOptions options);[System.Runtime.Versioning.SupportedOSPlatform("windows")]
public static System.Threading.EventWaitHandle OpenExisting(string name, System.Threading.NamedWaitHandleOptions options);[<System.Runtime.Versioning.SupportedOSPlatform("windows")>]
static member OpenExisting : string * System.Threading.NamedWaitHandleOptions -> System.Threading.EventWaitHandlePublic Shared Function OpenExisting (name As String, options As NamedWaitHandleOptions) As EventWaitHandle参数
- name
- String
要与其他进程打开和共享的同步对象的名称。 名称区分大小写。
- options
- NamedWaitHandleOptions
命名句柄的范围选项。 默认只能访问当前用户和当前会话。 指定的选项可能会影响名称和对基础句柄对象的访问的命名空间。
返回
一个表示命名系统事件的对象。
- 属性
例外
无法打开具有提供的 name 同步对象。 它可能不存在，或者不同类型的同步对象可能具有相同的名称。 在某些情况下，可能会为无效名称引发此异常。
-或-
具有指定 name 对象的存在，但指定的 options 对象与现有对象的选项不兼容。
name 是空字符串。
name 是 null。
name 无效。 这可能是出于各种原因，包括操作系统可能放置的一些限制，例如未知前缀或无效字符。 请注意，名称和通用前缀“Global\”和“Local\”区分大小写。
-或-
还有其他一些错误。 该 HResult 属性可能提供更多信息。
仅Windows：name指定了未知命名空间。 有关详细信息，请参阅 对象名称 。
name 太长。 长度限制可能取决于操作系统或配置。
命名事件存在，但用户没有使用它所需的安全访问权限。
注解
如果命名空间中存在所请求类型的同步对象，则会打开现有同步对象。 但是，如果 options 指定对当前用户的访问权限，并且同步对象与它不兼容，则会引发一个 WaitHandleCannotBeOpenedException 。 如果命名空间中不存在同步对象，或者命名空间中也存在不同类型的同步对象，也会引发一个 WaitHandleCannotBeOpenedException 同步对象。
该方法 OpenExisting 尝试打开指定的命名系统事件。 若要在系统事件不存在时创建系统事件，请使用具有参数的构造函数之 EventWaitHandle 一 name 。
对此方法使用相同值的 name 多次调用不一定返回相同的 EventWaitHandle 对象，即使返回的对象表示相同的命名系统事件。
