DosSetNmPipeSem
This call attaches a system semaphore to a local named pipe.
Syntax
DosSetNmPipeSem (Handle, SemHandle, KeyHandle)
Parameters
- Handle (HPIPE) - input
- Handle of the named pipe returned by DosMakeNmPipe or DosOpen.
- SemHandle (HSEM) - input
- A system semaphore handle that is cleared when the pipe (identified by Handle) has read data or write space available.
- KeyHandle (USHORT) - input
- An arbitrary value that is used to associate named pipe actions with result codes in DosQNmPipeSemState.
Return Code
- rc (USHORT) - return
- Return code descriptions are:
- 0 NO_ERROR
- 6 ERROR_INVALID_HANDLE
- 87 ERROR_INVALID_PARAMETER
- 120 ERROR_INVALID_FUNCTION
- 187 ERROR_SEM_NOT_FOUND
- 230 ERROR_BAD_PIPE
- 233 ERROR_PIPE_NOT_CONNECTED
Remarks
This call is intended for use only with local named pipes. If an attempt is made to attach a semaphore to a remote named pipe, ERROR_INVALID_FUNCTION is returned.
DosSetNmPipeSem supports serving applications that need to handle a large number of incoming pipes. By using semaphores, the application avoids such resource-consuming methods as dedicating a thread for each incoming pipe, or polling each pipe with non-blocking I/O. Instead, the application issues a DosSemWait or a DosMuxSemWait and waits for notification that I/O can be performed.
The system semaphore indicated by SemHandle is attached to the named pipe indicated by Handle. Up to two semaphores may be attached to a pipe, one for the serving side and one for the client side. If a semaphore is already attached to a side of the pipe, the semaphore is overridden.
The arbitrary value assigned to KeyHandle as input for DosSetNmPipeSem is used by DosQNmPipeSemState as output. This enables the application to distinguish events specific to a particular pipe when several pipes are attached to the same semaphore. DosQNmPipeSemState can be used to provide additional information about the I/O that can be performed on the set of pipes.
Bindings
C
#define INCL_DOSNMPIPES USHORT rc = DosSetNmPipeSem(Handle, SemHandle, KeyHandle); HPIPE Handle; /* Pipe handle */ HSEM SemHandle; /* Semaphore handle */ USHORT KeyHandle; /* Key value */ USHORT rc; /* return code */
MASM
EXTRN DosSetNmPipeSem:FAR INCL_DOSNMPIPES EQU 1 PUSH WORD Handle ;Pipe handle PUSH DWORD SemHandle ;Semaphore handle PUSH WORD KeyHandle ;Key value CALL DosSetNmPipeSem Returns WORD