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.EventWaitHandle

static member OpenExisting : string -> System.Threading.EventWaitHandle

Public Shared Function OpenExisting (name As String) As EventWaitHandle

Parameters

Returns

An object that represents the named system event.

Attributes

SecurityCriticalAttributeSupportedOSPlatformAttribute

Exceptions

Remarks

Thename can be prefixed withGlobal\ orLocal\ to specify a namespace. When theGlobal namespace is specified, the synchronization object can be shared with any processes on the system. When theLocal namespace is specified, which is also the default when no namespace is specified, the synchronization object can be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects might be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, seeObject Names.

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, aWaitHandleCannotBeOpenedException is thrown.

TheOpenExisting method tries to open the specified named system event. To create the system event when it does not already exist, use one of theEventWaitHandle constructors that has aname parameter.

Multiple calls to this method that use the same value forname do not necessarily return the sameEventWaitHandle object, even though the objects that are returned represent the same named system event.

In .NET Framework, this method overload is equivalent to calling theSystem.Threading.EventWaitHandle.OpenExisting(System.String,System.Security.AccessControl.EventWaitHandleRights) method overload and specifyingEventWaitHandleRights.Synchronize andEventWaitHandleRights.Modify rights, combined by using the bitwiseOR operation.

Specifying theEventWaitHandleRights.Synchronize flag allows a thread to wait on the named system event, and specifying theEventWaitHandleRights.Modify flag allows a thread to call theSet andReset methods.

See also

• Overview of synchronization primitives

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.EventWaitHandle

Public Shared Function OpenExisting (name As String, rights As EventWaitHandleRights) As EventWaitHandle

Parameters

Returns

An object that represents the named system event.

Attributes

SecurityCriticalAttribute

Exceptions

Examples

The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses theOpenExisting(String) method overload to test for the existence of a named event.

If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event.

If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call toOpenExisting(String). The exception is caught, and the example uses theOpenExisting(String, EventWaitHandleRights) method overload to wait on the event with the rights needed to read and change the permissions.

After the permissions are changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions.

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.ThreadingImports System.Security.AccessControlFriend 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

Remarks

Thename can be prefixed withGlobal\ orLocal\ to specify a namespace. When theGlobal namespace is specified, the synchronization object can be shared with any processes on the system. When theLocal namespace is specified, which is also the default when no namespace is specified, the synchronization object can be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects might be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, seeObject Names.

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, aWaitHandleCannotBeOpenedException is thrown.

Therights parameter must include theEventWaitHandleRights.Synchronize flag to allow threads to wait on the event, and theEventWaitHandleRights.Modify flag to allow threads to call theSet andReset methods.

TheOpenExisting method tries to open an existing named system event. To create the system event when it does not already exist, use one of theEventWaitHandle constructors that has aname parameter.

Multiple calls to this method that use the same value forname do not necessarily return the sameEventWaitHandle object, even though the objects that are returned represent the same named system event.

See also

• Overview of synchronization primitives

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.EventWaitHandle

Public Shared Function OpenExisting (name As String, options As NamedWaitHandleOptions) As EventWaitHandle

Parameters

Returns

An object that represents the named system event.

Attributes

SupportedOSPlatformAttribute

Exceptions

Remarks

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. However, ifoptions specifies access limited to the current user and the synchronization object is not compatible with it, aWaitHandleCannotBeOpenedException is thrown. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, aWaitHandleCannotBeOpenedException is thrown as well.

TheOpenExisting method tries to open the specified named system event. To create the system event when it does not already exist, use one of theEventWaitHandle constructors that has aname parameter.

Multiple calls to this method that use the same value forname do not necessarily return the sameEventWaitHandle object, even though the objects that are returned represent the same named system event.

See also

• Overview of synchronization primitives