DosSetNmPipeSem

Description

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.

Example Code

C Binding

#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 Binding

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