DosSetNPHState
Resets the blocking mode and the read mode of a named pipe.
Syntax
#define INCL_DOSNMPIPES #include <os2.h> HPIPE hpipe; /* The named-pipe handle to reset. */ ULONG state; /* The named-pipe handle state. */ APIRET ulrc; /* Return Code. */ ulrc = DosSetNPHState(hpipe, state);
Parameters
- hpipe (HPIPE) - input
- The named-pipe handle to reset.
- The server handle is returned by DosCreateNPipe; the client handle is returned by DosOpen.
- state (ULONG) - input
- The named-pipe handle state.
- This parameter consists of the following bit fields:
Bit Description
31-16 Reserved.
15 Blocking mode. The blocking mode is defined as either "blocking"
or "nonblocking," as follows:
0 NP_WAIT (0x0000)
Blocking mode: DosRead and DosWrite wait if no data is available.
1 NP_NOWAIT (0x8000)
Nonblocking mode: DosRead and DosWrite return immediately if no data is available.
DosRead normally blocks (waits) until at least partial data can be returned. DosWrite blocks by default until all of the requested bytes have been written. Nonblocking mode changes this behavior as follows:
- DosRead returns immediately with a value of zero for pcbActual if no data is available.
- DosWrite returns a value of zero for pcbActual if there is not enough buffer space available in the pipe; otherwise, the entire data area is transferred.
14-10 Reserved.
9-8 Read Mode. The read mode is defined as follows:
00 NP_READMODE_BYTE (0x0000)
Byte-read mode: Read the pipe as a byte stream.
01 NP_READMODE_MESSAGE (0x0100)
Message-stream mode: Read the pipe as a message stream.
7-0 Reserved, must be set to 0.
Return Code
ulrc (APIRET) - returns
DosSetNPHState returns one of the following values:
- 0 NO_ERROR
- 87 ERROR_INVALID_PARAMETER
- 230 ERROR_BAD_PIPE
- 231 ERROR_PIPE_BUSY
- 233 ERROR_PIPE_NOT_CONNECTED
Remarks
DosSetNPHState resets the blocking mode and the read mode of a named pipe. Both the blocking mode and the read mode must be specified. However, the read mode cannot be changed if the pipe is a byte pipe. (Byte pipes can be read only as byte streams.) In addition, the blocking mode cannot be changed to nonblocking if another thread is currently blocked on an I/O request to the same end of the pipe.
Example Code
This example handles the client side of a pipe. It opens an existing named pipe, sets and queries the pipe handle state, sends a message to the host, reads the host reply, and finally closes the pipe.
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 message[256] = ""; /* Message buffer */
HFILE PipeHandle = NULLHANDLE; /* Pipe handle */
struct _AVAILDATA BytesAvail = {0};
UCHAR Buffer[200] = {0};
ULONG bytes = 0;
ULONG Action = 0;
ULONG PipeState = 0;
ULONG HandType = 0;
ULONG FlagWord = 0;
ULONG BytesRead = 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 HOST\n");
rc = DosSetNPHState(PipeHandle, NP_WAIT);
if (rc != NO_ERROR) {
printf("DosSetNPHState error: error code = %u\n", rc);
return 1;
}
rc = DosQueryNPHState(PipeHandle, &PipeState);
if (rc != NO_ERROR) {
printf("DosQueryNPHState error: error code = %u\n", rc);
return 1;
} else {
printf("Pipe handle state is: %x\n", PipeState);
} /* endif */
printf("Enter message to send to PIPEHOST: ");
fflush(NULL); /* Force above printf prompt to display */
gets(message);
rc = DosWrite(PipeHandle, message, strlen(message), &bytes);
if (rc != NO_ERROR) {
printf("DosWrite error: error code = %u\n", rc);
return 1;
}
rc = DosRead(PipeHandle, message, sizeof(message), &bytes);
if (rc != NO_ERROR) {
printf("DosRead error: error code = %u\n", rc);
return 1;
}
printf("\nMessage received from PIPEHOST was: %s\n\n", message);
rc = DosClose(PipeHandle);
/* Should check if (RC == NO_ERROR) here... */
printf("...Disconnected\n");
return NO_ERROR;
}
