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

Include Info

#define INCL_DOSNMPIPES
#include <os2.h>

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 CPI: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 recieve 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 CPI:DosRead will receive a value of zero for bytes read. A thread blocked by CPI: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 CPI:DosClose in order to free the resources used.

Relevant Structures

Gotchas

Sample Code

#define INCL_DOSNMPIPES
#include 

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. */
}