View source for DosQNmPipeSemState

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

==Syntax==
 DosQNmPipeSemState (SemHandle, InfoBuf, InfoBufLen)

==Parameters==
;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.

==Return Code==
 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. 

==Example Code==
=== C Binding===
<PRE>
typedef struct   npss  {        /* QNmPipeSemState information record */
   UCHAR  npss_status;          /* type of record, 0=EOI, 1=read ok,  */
                                /*   2 = write ok, 3 = pipe closed    */
   UCHAR  npss_flag;            /* additional info, 01=waiting thread */
   USHORT npss_key;             /* user's key value                   */
   USHORT npss_avail;           /* available data/space if status=1/2 */
}; /* npss */

#define INCL_DOSNMPIPES

USHORT  rc = DosQNmPipeSemState(SemHandle, InfoBuf, InfoBufLen);

HSEM             SemHandle;     /* Semaphore handle */
PBYTE            InfoBuf;       /* Address of returned info */
USHORT           InfoBufLen;    /* Length of InfoBuf */

USHORT           rc;            /* return code */
</PRE>

===MASM Binding===
<PRE>
EXTRN  DosQNmPipeSemState:FAR
INCL_DOSNMPIPES     EQU 1

PUSH   DWORD   SemHandle     ;Semaphore handle
PUSH@  OTHER   InfoBuf       ;Information (returned)
PUSH   WORD    InfoBufLen    ;Length of InfoBuf
CALL   DosQNmPipeSemState

Returns WORD
</PRE>

==Related Functions==
* 

[[Category:Dos]]