[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosDisConnectNPipe

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

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
0NO_ERROR
109ERROR_BROKEN_PIPE
230ERROR_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 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 DosRead will recieve a value of zero for bytes read. A thread blocked by DosWrite will recieve 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.

Relevant Structures

Gotchas

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

See Also

 DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, DosPeekNPipe, DosQueryNPHState, DosQueryNPipeInfo, DosQueryNPipeSemState, DosSetNPHState, DosSetNPipeSem, DosTransactNPipe, DosWaitNPipe, DosClose, DosDupHandle, DosOpen, DosRead, DosResetBuffer, DosWrite

Author

Stefan Mars - mars@lysator.liu.se

Additions

Last modified March 17/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosDisConnectNPipe