DosTransactNPipe

From EDM2
Jump to: navigation, search

Writes to a duplex message pipe, then reads from it.

Syntax

DosTransactNPipe (hpipe, pOutbuf, cbOut, pInbuf, cbIn, pcbRead)

Parameters

hpipe (HPIPE) - input 
A named-pipe handle.
This handle is returned by DosCreateNPipe for a server process, or by DosOpen for a client process.
pOutbuf (PVOID) - input 
A pointer to the buffer that is to be written to the pipe.
cbOut (ULONG) - input 
The number of bytes to be written.
pInbuf (PVOID) - output 
A pointer to the buffer for returned data.
cbIn (ULONG) - input 
The maximum size, in bytes, of returned data.
pcbRead (PULONG) - output 
A pointer to the number of bytes read.

Return Code

ulrc (APIRET) - returns
DosTransactNPipe returns one of the following values:
  • 0 NO_ERROR
  • 5 ERROR_ACCESS_DENIED
  • 11 ERROR_BAD_FORMAT
  • 109 ERROR_BROKEN_PIPE
  • 157 ERROR_DISCARDED
  • 230 ERROR_BAD_PIPE
  • 231 ERROR_PIPE_BUSY
  • 233 ERROR_PIPE_NOT_CONNECTED
  • 234 ERROR_MORE_DATA

Remarks

DosTransactNPipe is intended for use only on a duplex message pipe that is in message-read mode. If this function is issued for a pipe that is not a duplex message pipe, ERROR_BAD_FORMAT is returned.

The current setting of the pipe's blocking mode has no effect on this function; that is, even if the pipe is in nonblocking mode, DosTransactNPipe writes the entire pOutbuf to the pipe, and does not return until it reads a response from the pipe into pInbuf. If pInbuf is too small to contain the response message, ERROR_MORE_DATA is returned.

The function does not succeed if there is any unread data in the pipe, or if the pipe is not in message-read mode.

Clients of named pipes created with the NP_ACCESS_OUTBOUND or NP_ACCESS_INBOUND access mode cannot use the DosTransactNPipe function. If the named pipe's client uses the DosTransactNPipe function, the function returns error code ERROR_ACCESS_DENIED.

An attempt to write to a pipe whose other end has been closed returns ERROR_BROKEN_PIPE or, if the other end was closed without reading all pending data, ERROR_DISCARDED.

Example Code

This example handles the client side of a pipe. It opens an existing named pipe, sends a message to the host, and reads the host reply using the DosTransactNP function.

Before running this example, compile and run the example code shown in the DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, or DosSetNPipeSem functions, which handles the host side of the pipe. 

#define INCL_DOSFILEMGR       /* DOS File Manager values */
#define INCL_DOSNMPIPES       /* DOS Named Pipes values */
#define INCL_DOSSEMAPHORES    /* DOS Semaphore values */
#define INCL_DOSERRORS        /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(VOID) {
   APIRET   rc                     = NO_ERROR;   /* Return code */
   CHAR     outmsg[256]            = "";         /* Output message buffer */
   CHAR     inmsg[256]             = "";         /* Input message buffer */
   HFILE    PipeHandle             = NULLHANDLE; /* Pipe handle */
   PIPEINFO PipeBuffer[4]          = {{0}};
   struct   _AVAILDATA  BytesAvail = {0};
   UCHAR    Buffer[200]            = {0};
   ULONG    bytes                  = 0;
   ULONG    Action                 = 0;
   PIPESEMSTATE infobuf[3]         = {{0}};

   rc = DosOpen("\\PIPE\\EXAMPLE", &PipeHandle, &Action, 0, 0, FILE_OPEN,
                OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE |
                OPEN_FLAGS_FAIL_ON_ERROR, NULL);
   if (rc != NO_ERROR) {
      printf("DosOpen error: error code = %u\n", rc);
      return 1;
   }  else printf("Connected to Pipe.\n");

   printf("Enter message to send to PIPEHOST: ");

   fflush(NULL);   /* Force above printf to output device */
   gets(outmsg);

   rc = DosTransactNPipe(PipeHandle,          /* Handle of duplex pipe */
                         outmsg,              /* Output message buffer */
                         strlen(outmsg),      /* Size of output message */
                         inmsg,               /* Input message buffer */
                         sizeof(inmsg),       /* SIze of input buffer */
                         &bytes);             /* Number of bytes read */
   if (rc != NO_ERROR) {
      printf("DosTransactNPipe error: error code = %u\n", rc);
      return 1;
   }

   printf("\nMessage received from PIPEHOST: %s\n\n", inmsg);

   printf("...Disconnected\n");
   return NO_ERROR;
}

Related Functions

Retrieved from "http://www.edm2.com/index.php?title=DosTransactNPipe&oldid=72907"