View source for WinWaitEventSem

WinWaitEventSem blocks until the specified event semaphore is posted. Event semaphores are edge-triggered. This means that if the semaphore is posted and reset before a waiting thread has a chance to run, the waiting thread will still act as though the semaphore is posted.

=== Syntax ===
 WinWaitEventSem( ''hevSemaphore'', ''ulTimeOut'' )

=== Parameters ===
;HEV ''hevSemaphore'' (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 posted.
:* Set to '''SEM_INDEFINITE_WAIT''' (-1), the function will block indefinitely (forever) until the semaphore is posted.
 
=== Returns ===
 APIRET rc
The following values can be returned:     
{|class="wikitable"
|0
|NO_ERROR
|Successfully obtained semaphore ownership
|-
|6
|ERROR_INVALID_HANDLE
|Error, The value in ''phevSemaphore'' does not point to a valid semaphore, The calling process must first have access to the semaphore in question
|-
|8
|ERROR_NOT_ENOUGH_MEMORY
|Error, The system memory limit has been exhausted
|-
|95
|ERROR_INTERRUPT
|Error, The thread has become unblocked by an external event such as an exception, ownership 
has not been obtained
|-
|640
|ERROR_TIMEOUT
|Error, The caller was blocked for ''ulTimeout'' milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired.
|}

=== Gotchas ===
The process calling WinWaitEventSem 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 not a PM thread, [[DosWaitEventSem]] should be used instead of WinWaitEventSem.

=== Sample Code ===
<pre> 
 #define INCL_WINMESSAGEMGR 
 #include <os2.h>

HEV  hevMySemaphore;       /* 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 DosCreateEventSem ... */
	/* ... or by DosOpenEventSem */
	/* its handle is placed in hevMySemaphore */

	rc = WinWaitEventSem(hevMySemaphore, TimeOut);

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

=== See Also ===
[[DosCloseEventSem]],
[[DosCreateEventSem]],
[[DosOpenEventSem]],
[[DosPostEventSem]] 
[[DosQueryEventSem]],
[[DosResetEventSem]],
[[DosWaitEventSem]] 

[[Category:Win]]