DosSetNmPipeSem

This call attaches a system semaphore to a local named pipe.

DosSetNmPipeSem

(Handle, SemHandle, KeyHandle)

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.
rc (USHORT) - return
Return code descriptions are:
• 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.

  ---

  [Back: DosSetNmPHandState]
  [Next: DosSetPathInfo]