EventWaitHandleAcl.Create Method

Definition

Namespace:

System.Threading

Assembly:

System.Threading.AccessControl.dll

Gets or creates an EventWaitHandle instance, allowing a EventWaitHandleSecurity instance to be optionally specified to set it during the event creation.

public:
 static System::Threading::EventWaitHandle ^ Create(bool initialState, System::Threading::EventResetMode mode, System::String ^ name, [Runtime::InteropServices::Out] bool % createdNew, System::Security::AccessControl::EventWaitHandleSecurity ^ eventSecurity);

public static System.Threading.EventWaitHandle Create (bool initialState, System.Threading.EventResetMode mode, string? name, out bool createdNew, System.Security.AccessControl.EventWaitHandleSecurity? eventSecurity);

static member Create : bool * System.Threading.EventResetMode * string * bool * System.Security.AccessControl.EventWaitHandleSecurity -> System.Threading.EventWaitHandle

Public Shared Function Create (initialState As Boolean, mode As EventResetMode, name As String, ByRef createdNew As Boolean, eventSecurity As EventWaitHandleSecurity) As EventWaitHandle

Parameters

initialState

Boolean

true to set the initial state to signaled if the named event is created as a result of this call; false to set it to non-signaled.

mode

EventResetMode

One of the enum values that determines whether the event resets automatically or manually.

name

String

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character (\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

createdNew

Boolean

When this method returns, this argument is always set to true if a local event is created; that is, when name is null or Empty. If name has a valid, non-empty value, this argument is set to true when the system event is created, or it is set to false if an existing system event is found with that name.

eventSecurity

EventWaitHandleSecurity

The optional Windows access control security to apply.

Returns

EventWaitHandle

An object that represents an event wait handle as requested.

Exceptions

ArgumentException

The mode enum value was out of legal range.

-or-

.NET Framework only: name is longer than MAX_PATH (260 characters).

ArgumentOutOfRangeException

The mode enum value was out of legal range. In some cases ArgumentException is thrown instead.

IOException

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local\" are case-sensitive.

-or-

There was some other error. The HResult property may provide more information.

DirectoryNotFoundException

Windows only: name specified an unknown namespace. See Object Names for more information.

PathTooLongException

The name is too long. Length restrictions may depend on the operating system or configuration.

WaitHandleCannotBeOpenedException

A synchronization object with the provided name cannot be created. A synchronization object of a different type might have the same name.

UnauthorizedAccessException

The named event exists, but the user does not have the desired security access.

ArgumentNullException

.NET Framework only: The name length is beyond MAX_PATH (260 characters).

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may 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 may 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, see Object Names.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a WaitHandleCannotBeOpenedException is thrown. Otherwise, a new synchronization object is created.

Caution

By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can pass in an EventWaitHandleSecurity when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code.