DosWaitMuxWaitSem

DosWaitMuxWaitSem blocks until the specified muxwait semaphore clears.

Syntax
DosWaitMuxWaitSem( hmuxSemaphore, ulTimeOut, pulUserField )

Parameters
returning.
 * HEV hevSemaphore (input):The handle of the semaphore to block on.
 * ULONG ulTimeout (input):The number of milliseconds the function will wait before
 * Set to SEM_IMMEDIATE_RETURN (0), the function will return immediately regardless of whether or not the semaphore is posted.
 * Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore is posted.

DCMW_WAIT_ALL flag, this will contain the user field of the last semaphore that was posted or released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY flag, this will contain the user field of the semaphore that was posted or released. If the thread did not block, this will contain the user field of the last semaphore in the MuxWait list.
 * PULONG pulUserField (output):A pointer to a ULONG that will contain the value of the user field from the SEMRECORD structure. If the MuxWait semaphore was created with the

Returns

 * APIRET rc:The following values can be returned:

Usage Explanation
MuxWait semaphores are edge triggered. This means that if a muxwait semaphore consists of a number of event semaphores and all have posted except for one, if one of the semaphores resets before the last hold-out posts then it will need to wait for the reset semaphore to post again.

If the MuxWait semaphore consists of mutex semaphores and was created with the DCMW_WAIT_ALL attribute, the process obtains ownership of all mutex semaphores only when all semaphores have been released. If the MuxWait semaphore was created with the DCMW_WAIT_ANY attribute, the process obtains ownership of the first mutex semaphore to release.

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

If the thread to be blocked, waiting on an event semaphore, is a PM thread, WinWaitMuxWaitSem should be used instead of DosWaitMuxWaitSem. This will allow the message queue thread to continue processing.

Sample Code

 * 1) define INCL_DOSSEMAPHORES
 * 2) include 

HMUX hmuxMySemaphore;     /* MySemaphore handle */ ULONG TimeOut= -1;        /* the number of milliseconds the */ /* the caller will block for the sem */ /* this example will block forever */ ULONG ulUserField;        /* to be filled with useful info */

/* access is gained to the semaphore in question */ /* either by DosCreateEventSem ... */	/* ... or by DosOpenEventSem */ /* its handle is placed in hevMySemaphore */

rc = DosWaitMuxWaitSem(hevMySemaphore, TimeOut,&ulUserField);

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