DosDisConnectNPipe
Syntax
rc = DosDisConnectNPipe( hpipeHandle );
Parameters
- HPIPE hpipeHandle (input)
- The handle to the named-pipe, as returned by DosCreateNPipe.
Returns
- APIRET rc
- The following values can be returned:
- 0 NO_ERROR
- 109 ERROR_BROKEN_PIPE
- 230 ERROR_BAD_PIPE
Usage Explanation
A server process uses DosDisConnectNPipe to acknowledge that a client process has closed a named pipe. Any attempt by a client process to use DosDisConnectNPipe will result in the ERROR_BAD_PIPE error returned to the child process. Until the server has issued DosDisConnectNPipe followed by DosConnectNPipe another child process can't open the pipe.
Between the child closing its end of the pipe, and the server disconnecting the pipe, any attempt by the server to read from the pipe will result in a value of 0 returned to it. An attempt to write to it will result in ERROR_BROKEN_PIPE error returned. ERROR_PIPE_BUSY will be returned to all clients trying to open the pipe.
If the client's end is still open when the server issues DosDisConnectNPipe, it will result in the pipe being disconnected from the server, closed on the client side. There are two things to note about the client here. It does not specifically get a message that the pipe has been closed for it, instead it will receive an error next time it tries to access the pipe. The other thing to note is that since the server forced closing of the client side, data that has not yet been read by the client will be lost.
Blocked threads are awakened by DosDisConnectNPipe. A thread blocked by DosRead will receive a value of zero for bytes read. A thread blocked by DosWrite will receive the ERROR_BROKEN_PIPE error.
The client's handle becomes invalid by the server calling DosDisConnectNPipe, but it does not free the handle. Therefore the client must issue DosClose in order to free the resources used.
Sample Code
#define INCL_DOSNMPIPES
#include <os2.h>
HPIPE Handle; /* The pipe handle. */
APIRET rc; /* Just to take care of the return code */
rc = DosDisConnectNPipe( Handle);
if (rc != 0)
{
/* We have an error we must take care of. */
}
