RtkCreateMutex

RtkCreateMutex creates an RTSS mutex. A handle is returned to the newly created mutex object.

Syntax

NTSTATUS RtkCreateMutex(
    RTSSINST RtssInst,
    PHANDLE MutexHandle,
    LPSECURITY_ATTRIBUTES Security,
    BOOLEAN InitialOwner,
    PUNICODE_STRING Name
);

Parameters

RtssInst

An RTSSINST value returned from a call to RtkRtssAttach or RtkRtssAttachEx. Must pass in a valid RTSSINST value or the call will fail with STATUS_INVALID_PARAMETER.

MutexHandle

A pointer to a handle that will receive a handle to the newly created Mutex object. Must pass in a valid pointer to a handle or the call will fail with STATUS_INVALID_PARAMETER.

Security (ignored)

A pointer to a SECURITY_ATTRIBUTES structure.

InitialOwner

The initial ownership state of the mutex object. If TRUE, the calling thread requests immediate ownership of the mutex object. Otherwise, the mutex is not owned.

Name

A pointer to a PUNICODE_STRING specifying the name of the event object. The name is limited to RTX64_MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case-sensitive.

If Name matches the name of an existing named mutex object, this function requests MUTEX_ALL_ACCESS access to the existing object. In this case, the InitialOwner parameter is ignored because it has already been set by the creating driver.

If Name matches the name of another kind of object in the same namespace (such as an existing semaphore or event), the function fails and the function returns STATUS_INVALID_HANDLE. This occurs because these objects share the same namespace.

If Name is NULL, the mutex object is created without a name.

Return Value

RtkCreateMutex returns STATUS_SUCCESS on success, or if the call fails the following NTSTATUS error codes can occur:

• STATUS_INVALID_PARAMETER
• STATUS_UNSUCCESSFUL
• STATUS_INVALID_HANDLE
• STATUS_NO_MEMORY

Remarks

The handle returned by RtkCreateMutex has MUTEX_ALL_ACCESS access to the new mutex object and can be used in any function that requires a handle to a mutex object.

Any thread of the calling driver can specify the mutex object handle in a call to RtkWaitforSingleObject or RtkWaitForMultipleObjects. This wait function returns when the state of the specified object is signaled.

Multiple processes or drivers can have handles of the same mutex object, enabling use of the object for driver and process synchronization. The available object-sharing mechanism is: A process or driver can specify the name of a mutex object in a call to RtkOpenMutex or RtkCreateMutex.

RtkCloseHandle closes a mutex object handle. The system closes the handle automatically when the driver calls RtkRtssDetach. The mutex object is destroyed when its last handle has been closed.

See Also:

RtkCloseHandle

RtkOpenMutex

RtkReleaseMutex