Does one of these:

• Waits for a specified number of units from the semaphore.
• Finds out how many units are available.

DWORD WaitForRtSemaphore(
    RTHANDLE hSemaphore,     // handle for RT semaphore
    WORD wCount,            // number of units to wait for
    DWORD dwMilliseconds    // number of milliseconds to wait for units
);

Parameters

hSemaphore

Handle for an RT semaphore.

wCount

Number of units the calling thread requests. To find out how many units are available, specify 0 (zero).

dwMilliseconds

The number of milliseconds the calling thread waits:

NO_WAIT	The thread does not wait.
WAIT_FOREVER	The thread waits for its request to be fully satisfied.
1-655349	Calling thread goes to sleep for this many milliseconds, after which it awakes. Note: The kernel converts milliseconds to high-level ticks.

Remarks

You can specify the amount of time a thread that uses WaitForRtSemaphore waits for a semaphore unit. Two factors determine whether the thread receives the units and how soon: how many units the thread asks for, and where the thread is in the queue.

• If the number of units requested is within the specified maximum for that semaphore, the request is valid.
  • If the thread is at the front of the queue and the number is less than the current number, the request is granted immediately and the thread stays running.
  • If a request is valid but cannot be granted immediately, it can either wait or not.
  • If the thread specifies that it can wait, the thread goes into the thread queue and goes to sleep by waiting for a pre-set length of time. If the time elapses before the thread gets the units it asked for, the thread awakens and receives an E_TIME condition code.
  • If the thread specifies that it cannot wait, the thread receives an E_TIME condition code.
• If the thread asks for more units than the maximum number allowed for a particular semaphore, the request is invalid and the semaphore returns an E_LIMIT status code.

Return Values

The number of units remaining on the semaphore.

Success.

WAIT_FAILED

Failure. To determine the status, call GetLastRtError.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_TIME 0x0001

No units were available during the waiting period specified in dwMilliseconds.

E_LIMIT 0x0004

wCount contains a value greater than the maximum value specified for the semaphore when it was created.

E_EXIST 0x0006

You used an invalid value for hSemaphore.

E_TYPE 0x8002

hSemaphore requires an RT handle for a semaphore.

E_PARAM 0x8004

dwMilliseconds contains an invalid value.

E_INVALID_ADDRESS 0x00E2

The address provided for the remote object is not a valid address.

Requirements

See Also

Semaphore system calls