Syntax

  #include <\nlm\nit\nwsync.h>  
   
  int WaitOnSemaphore (  
     long   semaphoreHandle,  
     WORD   timeoutLimit); 
  

Parameters

semaphoreHandle

(IN) Specifies the semaphore handle of an open semaphore.

timeoutLimit

(IN) Specifies the timeout value.

Return Values

Remarks

For cross-platform functionality, call NWWaitOnSemaphore.

An application must call this function before accessing the network resource associated with the semaphore.

If the semaphore value is still greater than or equal to zero after the function decrements it, the application can access the associated resource. If the value is less than zero, the function queues the application for the time interval specified in the timeoutLimit parameter. If the semaphore is incremented n + 1 times (where n is the negation of the semaphore value before the process called WaitOnSempahore), the process is restarted and WaitOnSempahore returns a value of 0. Otherwise, the process is restarted when the timeout expires and a value of 254 is returned.

An application can obtain a semaphore handle by calling OpenSemaphore.

The timeoutLimit indicates how long the server should wait if the semaphore value is negative. The timeoutLimit is specified in units of 1/18 of a second (0 means no wait).

WaitOnSemaphore temporarily disables the current connection number on which it is issued. This can pose a problem if the NLM thread group has set its current connection to that of a client before making the call. If this happens, the client is blocked out from getting file service requests until the unblock (that is, WaitOnSemaphore returns) occurs. If the delay is substantial, the client encounters the "Error sending/receiving on network" critical error.

To avoid this problem, an NLM should allocate connection numbers of its own when doing any network semaphore activity. A separate connection should be used for each thread group that uses network semaphores. Be cautious of using connection 0 for network semaphores. If a semaphore blocks, all other NLM applications in the system are prevented from doing any type of function that requires an enabled connection number.

See Also

CloseSemaphore, ExamineSemaphore, OpenSemaphore, SignalSemaphore