DosQNmPipeSemState

Bindings:  C, MASM 

This call returns information about local named pipes attached to a 
specific system semaphore. 

 DosQNmPipeSemState      (SemHandle, InfoBuf, InfoBufLen) 
 

 SemHandle (HSEM) - input 
    System semaphore handle that was previously attached to a named pipe 
    by DosSetNmPipeSem. 

 InfoBuf (PBYTE) - output 
    Address of the buffer that contains records, or multiple records, for 
    each named pipe: 

    pipestatus (UCHAR) 
       Coded value indicating the state of the named pipe: 

       Value     Definition 
       0         End of information buffer (EOF).  No more information 
                 records follow and subsequent fields in this information 
                 record have no defined value. 
       1         Read data available. 
       2         Write space available. 
       3         Pipe is closed. 

    pipestate (UCHAR) 
       Bit mask indicating additional information about the state of the 
       named pipe: 

       Bit        Description 
       7-1        Reserved 
       0          A thread is waiting on the other end of the pipe. 

    keyhandle (USHORT) 
       Key value associated with SemHandle at the time of the call to 
       DosSetNmPipeSem. 

    pipedata (USHORT) 
       Pipe "data or space" availability state: 

       Value     Definition 
       1         Amount of read space available in the pipe. 
       2         Amount of write data available in the pipe. 

 InfoBufLen (USHORT) - input 
    Size in bytes of InfoBuf. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 

    87        ERROR_INVALID_PARAMETER 

    111       ERROR_BUFFER_OVERFLOW 
 
 Remarks 

 A record is placed in InfoBuf for each local named pipe that has a 
 semaphore attached whose handle matches the handle specified and whose 
 state is closed or allows blocking mode I/O to be done. 

 There is no guarantee that records in the buffer refer to named pipes 
 opened by the process making this call.  If the same system semaphore is 
 attached to different named pipes by multiple processes, information 
 about named pipes that are not accessible to the caller can be returned. 
  Thus, cooperating processes should agree on a convention for key values 
 to help identify the named pipes of interest.  A key value is associated 
 with the pipe at the time the semaphore is set with DosSetNmPipeSem. 

 If a process wants data in the buffer to refer only to its own named 
 pipes, it must use an exclusive system semaphore. 

 A process associates a single semaphore with multiple pipes by way of 
 DosSetNmPipeSem. After waking up from a wait on the semaphore, a thread 
 issues DosQNmPipeSemState, which returns the I/O state information for 
 all pipes associated with the semaphore. The thread can scan this 
 information to determine which pipes can be read or written.  This is 
 more efficient than polling the pipes with a non-blocking I/O on each 
 pipe.