DosConnectNPipe

From EDM2
Jump to: navigation, search

Prepares a named pipe for a client process.

Syntax

DosConnectNPipe(hpipe)

Parameters

hpipe (HPIPE) - input
The named-pipe handle to connect (returned to the server process by DosCreateNPipe).

Return Code

ulrc (APIRET) - returns
DosConnectNPipe returns one of the following values:
  • 0 NO_ERROR
  • 95 ERROR_INTERRUPT
  • 109 ERROR_BROKEN_PIPE
  • 230 ERROR_BAD_PIPE
  • 233 ERROR_PIPE_NOT_CONNECTED

Remarks

DosConnectNPipe is issued by a server process to put a named pipe into the listening state. This enables a client process to gain access to the pipe by calling DosOpen.

If the client end of the pipe is already open when DosConnectNPipe is issued, DosConnectNPipe returns immediately and has no effect. If the client end is closed, the result depends on whether the pipe is in blocking mode or nonblocking mode. (Blocking/nonblocking mode is specified when the pipe is created; it can also be changed by DosSetNPHState).

  • If the pipe is in blocking mode, DosConnectNPipe waits for a client to open the pipe before returning.
  • If the pipe is in nonblocking mode, DosConnectNPipe returns immediately with ERROR_PIPE_NOT_CONNECTED. Nevertheless, the pipe is placed into the listening state, permitting a client to subsequently issue DosOpen successfully.

Multiple DosConnectNPipe calls can be issued for a pipe that is in nonblocking mode. If the pipe is not already either open or closing, the first call to DosConnectNPipe puts the pipe into the listening state; subsequent calls merely test the pipe state.

If the pipe was previously opened and then closed by a client, but has not yet been disconnected by the server, DosConnectNPipe returns ERROR_BROKEN_PIPE.

If the function is interrupted while it is waiting for a client to open the pipe, ERROR_INTERRUPT is returned.

If DosConnectNPipe is called by a client process, ERROR_BAD_PIPE is returned.

Also, ERROR_BAD_PIPE is returned if you specify an invalid name or file handle.

Example Code

This example handles host end of a named pipe for several other named pipe examples. Some return code checking has been omitted. Compile and run this program before running client programs to the named pipe.

#define INCL_BASE
#define INCL_DOSSEMAPHORES
#define INCL_DOSNMPIPES
#include <os2.h>
#include <stdio.h>
#include <string.h>

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