EventWaitHandle.OpenExisting 方法
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
開啟一個指定的命名同步事件（如果已經存在）。
多載
| 名稱 | Description |
|---|---|
| OpenExisting(String) |
開啟指定的命名同步事件（如果已存在）。 |
| OpenExisting(String, EventWaitHandleRights) |
若已存在，會開啟指定的命名同步事件，並以所需的安全存取權限。 |
| OpenExisting(String, NamedWaitHandleOptions) |
開啟指定的命名同步事件（如果已存在）。 若選項僅設定為目前使用者，物件的存取控制會被驗證為呼叫使用者。 |
OpenExisting(String)
開啟指定的命名同步事件（如果已存在）。
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。
如果命名空間中存在該請求類型的同步物件，則會開啟該現有的同步物件。 若命名空間中不存在同步物件，或命名空間中存在不同類型的同步物件，則拋出 a 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 and 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。
如果命名空間中存在該請求類型的同步物件，則會開啟該現有的同步物件。 若命名空間中不存在同步物件，或命名空間中存在不同類型的同步物件，則拋出 a WaitHandleCannotBeOpenedException 。
rights參數必須包含EventWaitHandleRights.Synchronize允許執行緒等待事件的旗標，以及EventWaitHandleRights.Modify允許執行緒呼叫 Set and Reset 方法的旗標。
此 OpenExisting 方法嘗試開啟一個已命名的系統事件。 若要在系統事件尚未存在時建立該事件，請使用 EventWaitHandle 具有 name 參數的建構子之一。
多個使用相同值 name 的呼叫不一定回傳相同的 EventWaitHandle 物件，即使回傳的物件代表相同的命名系統事件。
另請參閱
適用於
OpenExisting(String, NamedWaitHandleOptions)
開啟指定的命名同步事件（如果已存在）。 若選項僅設定為目前使用者，物件的存取控制會被驗證為呼叫使用者。
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 指定存取權限僅限於目前使用者，且同步物件與其不相容，則會拋出 a WaitHandleCannotBeOpenedException 。 如果命名空間中不存在同步物件，或命名空間中存在不同類型的同步物件，則也會拋出 a WaitHandleCannotBeOpenedException 。
該 OpenExisting 方法嘗試開啟指定的命名系統事件。 若要在系統事件尚未存在時建立該事件，請使用 EventWaitHandle 具有 name 參數的建構子之一。
多個使用相同值 name 的呼叫不一定回傳相同的 EventWaitHandle 物件，即使回傳的物件代表相同的命名系統事件。
