DosSetNPipeSem

Description
Attaches a shared event semaphore to a local named pipe.

Syntax

 * 1) define INCL_DOSNMPIPES
 * 2) include 

HPIPE    hpipe;  /* The named-pipe handle to which a semaphore is to be attached. */ HSEM     hsem;   /* The handle of an event semaphore or a multiple-wait (muxwait) semaphore that is posted when the pipe (hpipe) has either data to be read or write space available. */ ULONG    key;    /* A key value that distinguishes events arriving on different named pipes that are attached to the same semaphore. */ APIRET   ulrc;   /* Return Code. */

ulrc = DosSetNPipeSem(hpipe, hsem, key); 

Parameters

 * hpipe (HPIPE) - input : The named-pipe handle to which a semaphore is to be attached.
 * The server handle is returned by DosCreateNPipe; the client handle is returned by DosOpen.


 * hsem (HSEM) - input : The handle of an event semaphore or a multiple-wait (muxwait) semaphore that is posted when the pipe (hpipe) has either data to be read or write space available.
 * key (ULONG) - input : A key value that distinguishes events arriving on different named pipes that are attached to the same semaphore.

Return Code
ulrc (APIRET) - returns DosSetNPipeSem returns one of the following values:
 * 0 NO_ERROR
 * 1 ERROR_INVALID_FUNCTION
 * 6 ERROR_INVALID_HANDLE
 * 87 ERROR_INVALID_PARAMETER
 * 187 ERROR_SEM_NOT_FOUND
 * 230 ERROR_BAD_PIPE
 * 233 ERROR_PIPE_NOT_CONNECTED

Remarks
DosSetNPipeSem can be used with local pipes or on the client end of a remote pipe. (A remote pipe is the client end of a pipe created on a remote named pipe server.) If an attempt is made to attach a semaphore to the server end of a remote pipe, DosSetNPipeSem returns 1 (ERROR_INVALID_FUNCTION).

If a semaphore is already attached to the specified handle, DosSetNPipeSem replaces the existing semaphore with the new one.

Example Code
This example handles the host end of a named pipe for several other named pipe examples. Some return code checking has been omitted for brevity. 
 * 1) define INCL_BASE
 * 2) define INCL_DOSSEMAPHORES
 * 3) define INCL_DOSNMPIPES
 * 4) include 
 * 5) include 
 * 6) include 

int main(VOID) { CHAR    PipeName[256] = "\\PIPE\\EXAMPLE" ;     /* Pipe name */ HPIPE   PipeHandle    = NULLHANDLE;             /* Pipe handle */ HEV     hev           = NULLHANDLE;             /* Semaphore handle */ ULONG   ulBytes       = 0;                      /* Bytes read or written */ CHAR    message[256]  = "";                     /* Input/Output buffer */ APIRET  rc            = NO_ERROR;               /* Return code */

rc = DosCreateNPipe(PipeName,               /* Name of pipe to create */                       &PipeHandle,             /* Handle returned for pipe */                       NP_ACCESS_DUPLEX,        /* Duplex pipe */                       NP_WAIT |                       NP_TYPE_MESSAGE |                       NP_READMODE_MESSAGE |                       NP_WMESG |               /* Write messages */                       NP_RMESG |               /* Read messages */                       0x01,                    /* Unique instance of pipe */                       sizeof(message),         /* Output buffer size */                       sizeof(message),         /* Input buffer size */                       0L);                     /* Use default time-out */ if (rc != NO_ERROR) { printf("DosCreateNPipe error: return code = %u\n",rc); return 1; }

rc = DosCreateEventSem("\\SEM32\\PIPE\\EXAMPLE", &hev, 0L, 0L); /* Should check if (rc != NO_ERROR) here... This semaphore is not always used. */

rc = DosSetNPipeSem(PipeHandle,      /* Handle for pipe */                       (HSEM) hev,       /* Handle of semaphore */                       1L);              /* Used to distinguish among events */ if (rc != NO_ERROR) { printf("DosSetNPipeSem error: return code = %u\n",rc); return 1; }

printf("Waiting for connection to pipe %s...\n",PipeName);

rc = DosConnectNPipe(PipeHandle); if (rc != NO_ERROR) { printf("DosConnectNPipe error: return code = %u\n",rc); return 1; }

printf("\nCONNECTED\nWaiting for a message...\n"); rc = DosRead(PipeHandle,           /* Handle of pipe */                message,               /* Buffer for message read */                sizeof(message),       /* Buffer size */                &ulBytes);             /* Number of bytes actually read */ if (rc != NO_ERROR) { printf("DosRead error: return code = %u\n",rc); return 1; }

printf("\n\nMessage received was: %s\n\n", message);

strcpy(message, "Thank you for your message!"); rc = DosWrite(PipeHandle,          /* Handle of pipe */                 message,              /* Buffer containing message to write */                 strlen(message),      /* Length of message */                 &ulBytes);            /* Number of bytes actually written */ if (rc != NO_ERROR) { printf("DosWrite error: return code = %u\n",rc); return 1; }

rc = DosCloseEventSem(hev); /* Should check if (rc != NO_ERROR) here... */

rc = DosDisConnectNPipe(PipeHandle); /* Should check if (rc != NO_ERROR) here... */

return NO_ERROR; } 

Related Functions

 * DosCallNPipe
 * DosClose
 * DosCloseMuxWaitSem
 * DosConnectNPipe
 * DosCreateEventSem
 * DosCreateNPipe
 * DosDisConnectNPipe
 * DosDupHandle
 * DosOpen
 * DosPeekNPipe
 * DosQueryNPHState
 * DosQueryNPipeInfo
 * DosQueryNPipeSemState
 * DosRead
 * DosResetBuffer
 * DosSetNPHState
 * DosTransactNPipe
 * DosWaitNPipe
 * DosWaitEventSem
 * DosWaitMuxWaitSem
 * DosWrite