RtkCreateSemaphore

RtkCreateSemaphore creates an RTSS semaphore object.

Syntax

NTSTATUS RtkCreateSemaphore(
    RTSSINST RtssInst,
    PHANDLE SemaphoreHandle,
    LPSECURITY_ATTRIBUTES Security,
    LONG InitialCount,
    LONG MaximumCount,
    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.

Semaphore Handle

A pointer to a handle that will receive a handle to the newly created semaphore 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.

InitialCount

An initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to MaximumCount. The state of a semaphore is signaled when its count is greater than zero and non-signaled when it is zero. The count is decreased by one whenever a wait function releases a thread that was waiting for the semaphore. The count is increased by a specified amount by calling RtkReleaseSemaphore.

MaximumCount

The maximum count for the semaphore object. This value must be greater than zero.

Name

A pointer to a PUNICODE_STRING specifying the name of the semaphore 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 semaphore object, this function requests SEMAPHORE_ALL_ACCESS access to the existing object. In this case, InitialCount and MaximumCount are ignored because they have 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 mutex 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 semaphore object is created without a name.

Return Value

RtkCreateSemaphore returns STATUS_SUCCESS on success or if the call fails the following NTSTATUS error codes are possible:

• STATUS_INVALID_PARAMETER
• STATUS_UNSUCCESSFUL
• STATUS_INVALID_HANDLE
• STATUS_NO_MEMORY

Remarks

The handle returned by RtkCreateSemaphore has SEMAPHORE_ALL_ACCESS accesses to the new semaphore object and can be used in any function that requires a handle to a semaphore object.

The state of a semaphore object is signaled when its count is greater than zero, and nonsignaled when its count is equal to zero. The InitialCount parameter specifies the initial count. The count can never be less than zero or greater than the value specified in the MaximumCount parameter.

Any thread of the calling driver can specify the semaphore 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 semaphore object, enabling use of the object for driver and process synchronization. The available object-sharing mechanism is: A process can specify the name of a semaphore object in a call to RtkOpenSemaphore or RtkCreateSemaphore.

Use RtkCloseHandle to close the handle. The system closes the handle automatically when the process terminates. The semaphore object is destroyed when its last handle has been closed.

See Also:

RtkCloseHandle

RtkOpenSemaphore

RtkReleaseSemaphore