WinRequestMutexSem

Syntax
rc = WinRequestMutexSem( hmtxSemaphore,                         ulTimeOut );

Parameters

 * HMTX hmtxSemaphore (input):The handle of the semaphore to be released.
 * ULONG ulTimeout (input):The number of milliseconds the function will wait before returning.
 * Set to SEM_IMMEDIATE_RETURN (0), the function will return immediately regardless of whether or not the semaphore is free.
 * Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained.

Returns
APIRET rc The following values can be returned

Include Info

 * 1) define INCL_WINMESSAGEMGR
 * 2) include 

Usage Explanation
WinRequestMutexSem blocks until ownership of a mutex semaphore may be obtained. Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner.

WinRequestMutexSem is intended to be used in Presentation Manager applications rather than the DosRequestMutexSem counterpart to avoid hanging the PM Message Queue.

Gotchas
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.

Sample Code

 * 1) define INCL_WINMESSAGEMGR
 * 2) include

HMTX hmtxMySemaphore;     /* MySemaphore handle */ ULONG TimeOut= -1;        /* the number of milliseconds the */ /* the caller will block for the sem */ /* this example will block forever */ APIRET rc;                /* return code */

/* access is gained to the semaphore in question */ /* either by DosCreateMutexSem ... */	/* ... or by DosOpenMutexSem */ /* its handle is placed in hmtxMySemaphore */

rc = WinRequestMutexSem(hmtxMySemaphore, TimeOut);

if (rc != 0) {	 /* We got an error to take care of. */	}